# 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.

`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.
