Add portable topics and surveys, decision approval history, execution plans, local Codex and Claude adapters, and general agent routing. Consolidate Plan and EPIC results through deterministic completion receipts, reviewed cancellation scope and recoverable reconciliation. Track the completed WRK-0001 and WRK-0002 records, protocol documentation, source manifests and delivery evidence. Validation: 117 tests including Modulith; GraalVM 25 native compilation, standalone smoke and ZIP/TAR verification on macOS ARM64; identical persisted context across JVM and native executions.
79 lines
4.4 KiB
Markdown
79 lines
4.4 KiB
Markdown
# EPIC contract
|
|
|
|
An EPIC is a Work with `epic: true` and a versioned definition under
|
|
`epic/<Work ID>.md`. Ordinary schema-1 Works default to `epic: false`; reads never
|
|
rewrite them. Definition revisions retain SHA-256-linked snapshots under
|
|
`epic/.history/<Work ID>/`. Links point to project-scoped Work IDs, not source repos.
|
|
|
|
## Topology and policy
|
|
|
|
The initial topology is a forest: one parent per Work, nested EPICs allowed, no
|
|
self-links or cycles. Each child is important by default. Links and importance
|
|
changes require an actor/reason, preserve history and invalidate prior authorization.
|
|
Completed/cancelled parents must be reopened before policy or topology changes.
|
|
|
|
Modes: RESULTS waits for every important child to be COMPLETED with valid completion
|
|
evidence; an important CANCELLED child stays pending. Optional children are reported
|
|
without blocking. DECOMPOSITION leaves child results out of closure readiness and
|
|
requires the ordinary human-reviewed completion command for the parent's own output.
|
|
An empty important set never triggers automatic completion.
|
|
|
|
## Automatic completion and authority
|
|
|
|
RESULTS can close automatically only after `epic authorize --human-approved` records
|
|
explicit human delegation for the current policy, parent scope and child scopes.
|
|
The human authorizes the structured aggregate condition as sufficient for the parent's
|
|
criteria. Scope/policy changes make that authority stale. This is an audit attestation,
|
|
not authentication. Local questions, surveys, decisions, plans and evidence still need
|
|
to pass mechanical readiness. No model evaluates those conditions.
|
|
|
|
Automatic completion produces an owned ART receipt with policy/child completion
|
|
digests and maps parent criteria to that receipt. The completion has origin
|
|
SYSTEM_EPIC, humanApproved=false and a reference to the actual policy authorization;
|
|
ordinary completions remain HUMAN and require direct human approval. The receipt
|
|
does not pretend that the framework performed semantic acceptance or a source test.
|
|
|
|
## Propagation and recovery
|
|
|
|
The public lifecycle commands complete/cancel/reopen/update notify affected ancestors
|
|
inside the project lock and return a report to the requester. Important-child reopening
|
|
reopens RESULTS ancestors and clears archive while retaining old completion records.
|
|
Optional-child changes do not invalidate a delivery; DECOMPOSITION does not follow
|
|
child execution. A manually BLOCKED/CANCELLED parent is never automatically completed.
|
|
Nested completions propagate from descendants to ancestors.
|
|
|
|
An explicit `work reopen` on an EPIC suspends its automatic authority for replanning;
|
|
reopening caused by a changed important child preserves authority when scopes remain
|
|
the same. Adding children to a delivered EPIC therefore means explicitly reopening,
|
|
editing links/scopes and reviewing authorization again.
|
|
|
|
`epic check` is read-only. `epic reconcile` deterministically repairs missed
|
|
propagation from canonical child state, including after interruption between child
|
|
and parent writes. Repeated notifications do not duplicate completion or receipts.
|
|
No server, message broker, database or agent invocation is used. Invalid histories,
|
|
missing links and unsafe paths are diagnosed; arbitrary corrupted files still need
|
|
deliberate repair. Publication remains atomic per file, not a global transaction.
|
|
|
|
## CLI
|
|
|
|
Create ordinary Works, then configure/link them:
|
|
|
|
```sh
|
|
aie epic configure WRK-0001 --mode results --by agent --reason "Coordinate delivery"
|
|
aie epic link WRK-0001 WRK-0002 --by agent --reason "First slice"
|
|
aie epic link WRK-0001 WRK-0003 --by agent --reason "Second slice"
|
|
aie epic authorize WRK-0001 --by owner --reason "These results satisfy the EPIC criteria" --human-approved
|
|
aie epic show WRK-0001 --format json
|
|
aie epic check WRK-0001 --format json
|
|
aie epic importance WRK-0001 WRK-0003 --optional --by owner --reason "Explicit scope review"
|
|
# Review and authorize the revised policy before it can close automatically.
|
|
aie epic history WRK-0001 --format json
|
|
aie epic reconcile WRK-0001 --requester agent --request-id resume-1 --format json
|
|
```
|
|
|
|
`epic unlink` retains prior definitions in history. Context includes parent, policy,
|
|
children, pending reasons, authority and completion provenance. Results are stable
|
|
for unchanged canonical files. Configuring an EPIC does not create or execute children.
|
|
Real model adapters, automatic decomposition proposals and legacy import remain out
|
|
of this slice. Zelda is not modified by its implementation or temporary experiments.
|