81 lines
4.6 KiB
Markdown
81 lines
4.6 KiB
Markdown
# EPIC contract
|
|
|
|
An EPIC is a Work with `epic: true` and a versioned typed SQLite policy.
|
|
The legacy file backend uses `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.
|
|
SQLite is embedded; no server, message broker or agent invocation is used. Invalid histories,
|
|
missing links and unsafe paths are diagnosed; arbitrary corrupted files still need
|
|
deliberate repair. SQLite commits related propagation transactionally; only legacy
|
|
files retain per-file publication. Required gates also constrain parent delivery.
|
|
New aggregate receipts are structured database facts; old receipt files stay readable.
|
|
|
|
## 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.
|