Disciplines · Decisions (ADRs)

ADR-0076: Eve governed goal-to-verified-delivery lifecycle

Oshun already has an event-sourced intent ledger, work-item and decision state machines, attributed TTL leases, append-only reports, observed-main shipping, and machine-only artifact verification.

Proposed · 2026-09-02
8sections9 minread
Markdown source
On this page

Status: Proposed — engineering direction agent-adopted; named production ratification pending

Date: 2026-09-02

Authors: Eve SOTA gap-closure task 2.1

Reviewers: pending — Product owner, Eve workbench/platform owner, Security owner, Evaluation owner, Reliability owner

This ADR is effective for implementation and CI on merge. It does not fabricate human approval, enable autonomous fleet drain, or close Phase 2, G1, or G12. Live activation remains blocked by the named ratification and cross-phase gates below.

Context#

Oshun already has an event-sourced intent ledger, work-item and decision state machines, attributed TTL leases, append-only reports, observed-main shipping, and machine-only artifact verification. The source-bound baseline records 3 entity kinds, 10 work-item statuses, 12 work-item transitions, and 0 MCP operations.

That is a useful execution substrate, not yet a governed delivery lifecycle. The current entity universe is work-item | decision | thread; it has no durable goal, requirement, dependency-graph, or verification-plan entity. The queue-dependency-and-fencing-contract gate is implemented (owner task 2.2). The bounded-resumable-drain gate is implemented (owner task 2.3). The typed-triage gate is implemented (owner task 2.4). The operator-read-model gate is implemented (owner task 2.5). The execution-isolation gate is implemented (owner task 2.6). The provider-free-model-and-parity-proof gate is implemented (owner task 2.7). The gated-live-drain-and-soak gate is not-implemented (owner task 2.8). A queue drain built directly on this partial shape could execute prepared work faster while losing why it exists, what human decisions constrain it, what proves it, and whether its state differs from a hand lease.

Decision#

Adopt the versioned lifecycle eve.governed-delivery.v1:

goal → requirements → dependency DAG → verification plan → work items → leases → review → ship → verify

Every planning change is a successor revision with a new digest; none overwrites the record it replaces. Every transition stays in the existing append-only intent plane or an explicitly versioned extension of it. A queue drain is selection and supervision, never a second lifecycle.

# Stage Durable output Admission gate Implementation owner(s)
1 goal An actor-attributed goal revision with objective, non-goals, source provenance, authority boundary, risk class, ambiguity record, and accepted human-decision references. Material ambiguity, conflicting human direction, or missing authority blocks decomposition until an explicit clarification or accepted decision is recorded. 11.2
2 requirements Stable requirement ids with statements, acceptance criteria, non-goals, source refs, decision refs, risk, and exact goal-revision provenance. Every material goal clause maps to at least one requirement or an accepted human decision explaining its exclusion; an uncovered clause fails closed. 11.2
3 dependency-dag A versioned acyclic graph with stable node ids, typed edges, edge rationale, requirement coverage, and a canonical graph digest. Unknown nodes, cycles, uncovered requirements, and a dependency bypass without a superseding accepted decision make the plan inadmissible. 2.2, 11.2
4 verification-plan A preregistered verification matrix binding each requirement and work item to proof boundaries, commands or human rubric, negative controls, expected outcomes, rollback evidence, and explicit limitations. No work item becomes ready or leasable unless every requirement it owns has direct planned evidence and every high-risk claim has an applicable red control. 11.2, 12.2
5 work-items Atomic work items carrying goalRevisionId, planRevisionId, requirementRefs, dependencyRefs, verificationPlanRefs, scope, non-goals, risk, expected artifacts, and reversal or compensation boundary. An item with an orphan reference, implicit scope, no owned requirement, no proof plan, or an unclassified irreversible effect cannot enter ready. 2.2, 11.2
6 leases An actor-attributed, TTL-bounded lease acquired through the canonical queue API and represented by the ordinary work-item lifecycle events. Dependency readiness, concurrency, spend, fencing, idempotency, capability, and resource preflight all pass before acquisition; refusal emits no partial state. 2.2, 2.3, 2.6
7 review Append-only progress and completion reports, artifact and command evidence, an independently attributed review verdict, and either an in-review state or an evented reopen/triage outcome. Completion does not imply approval. Review checks the pre-registered requirements and evidence; rejection or ambiguity returns through an explicit event rather than erasing history. 2.4, 11.4
8 ship A shipped transition containing the commit actually observed on origin/main plus repository and artifact provenance. Only an approved in-review item may ship; configured repository verification fails closed when the commit is absent, unmerged, or unverifiable. 2.3, 2.6
9 verify A separately attributed verifier result per requirement and plan row: verified, ship-verify-gap, contradicted, or explicitly not-machine-checkable, with evidence and limitations. The implementer cannot grant verified. Only direct evidence at the registered boundary closes a requirement; missing or indirect evidence stays open and triaged. 2.4, 2.7, 11.4

Human decisions are authority, not context decoration#

  • An agent may draft or propose a decision, but it may not accept one for a human: agentMayAcceptForHuman=false.
  • Accepted human decisions are required for material-goal-or-non-goal-change, requirement-removal-or-scope-reduction, dependency-bypass, verification-waiver, irreversible-action-authorization, cloud-spend-or-live-autonomy-activation.
  • Decision events, rejected options, rationale, actor, timestamp, and supersedes chain are append-only. A plan revision references the exact decisions it consumed; summaries never replace the source record.
  • Conflicting current human decisions stop planning and name the conflict; recency, model confidence, or drain priority cannot silently choose one.

The current decision machine's accepted/superseded chain is retained. Implementations must close its present authority gap: the word “human” in a stage meaning is not enforcement. An accepted planning decision must carry the authenticated human actor and the exact plan revision that consumed it.

Requirement traceability is bidirectional and closure is direct#

The required chain is:

goalRevisionId → requirementId → dependencyNodeId → verificationPlanRowId → workItemId → leaseEventSeq → reviewEventSeq → shippedCommitSha → verificationResultId

Every material goal clause maps to a requirement or a recorded accepted exclusion; every requirement maps forward through the plan to a verification result; every result maps back to the exact goal and decision revision. Orphan references fail closed. not-machine-checkable is honest but does not close a requirement, and narrower or indirect evidence cannot close a broader claim.

Reversible boundaries preserve facts#

  • Planning edits append successor revisions; an active scope change releases or triages the lease and creates linked successor work rather than mutating the brief underneath an agent.
  • Lease release and review rejection are explicit events. Reports and rejected options remain in history.
  • A shipped commit and a verification observation cannot be undone in place. Create a linked repair or revert work item and new commit; never rewrite the shipped or verification event.
  • Before lease, name the effect, exact confirmation, blast radius, and compensation or explicit irreversibility. After execution, reversal is a new attributed action with its own evidence.

Reversible means a declared, tested inverse or compensation. It never means writing an earlier status over a later fact.

Drain and hand-lease parity#

The invariant drain-hand-lease-ledger-state-parity is normative. For the same logical item, actor, controlled clock, TTL, report inputs, observed commit, artifact, and verifier result, both acquisition modes invoke this exact operation sequence:

listReady → lease → buildTaskBrief → report:progress → report:completion → markShipped → runArtifactDiffVerifier

The drain may choose an eligible item, bound and checkpoint the run, and supervise resources. It may not append work-item ledger events directly, mutate projections, invent drain-only transitions, or infer shipped/verified from process exit. Run/selection metadata belongs to a separate orchestration record and cannot affect work-item reduction.

Parity is tested at two levels:

  1. Folded state equality on kind, title, body, status, priority, expectation, graphRefs, orphanedRefs, lease.
  2. Ordered semantic-event equality on entityKind, eventType, payload.phase, payload.from, payload.to, payload.transitionId, payload.lease, payload.branch, payload.commits, payload.prUrl, payload.observedCommitSha, payload.outcome, payload.graphVersion after removing only seq, createdAt, conversationRef.

Actor identity is evidence and is never normalized away. Task 2.7 must provide the executable provider-free equivalence proof; task 2.3 may not ship a drain that lacks it.

Current implementation gates#

Gate Current state Owner Exact unblock condition
queue-dependency-and-fencing-contract implemented 2.2 Queue semantics enforce dependency readiness, concurrency and spend admission, priority fairness, TTL renewal, monotonic fencing, idempotency, retry bounds, poison quarantine, orphan recovery, and terminal ownership.
bounded-resumable-drain implemented 2.3 A bounded dry-runnable drain invokes only the canonical queue operations, persists its run/checkpoints, supervises process groups and resources, resumes safely, and has no unbounded loop.
typed-triage implemented 2.4 Every verifier gap, test failure, conflict, ambiguity, budget exhaustion, and refusal becomes a distinct evidence-bearing triage record; none silently requeues or closes.
operator-read-model implemented 2.5 The attributed fleet read model exposes queue/dependency/lease/triage/run/outcome/kill-switch state and trace links without granting mutation authority.
execution-isolation implemented 2.6 Branch/worktree, dirty-tree, remote divergence, credentials, command roots, egress, secrets, artifacts, and implementer/verifier identity are fail-closed.
provider-free-model-and-parity-proof implemented 2.7 A provider-free state model proves the drain/hand parity rule and duplicate, expiry, renewal, stale-fence, crash, cycle, poison, cancellation, and restart properties.
gated-live-drain-and-soak not-implemented 2.8 Only after Security, Evaluation, and Reliability admission, a diverse real backlog drain and supervised soak meet preregistered success, intervention, retry, duplicate-action, time, cost, and verification floors.

Task 2.8 remains blocked until the Phase 4 Security, Phase 12 Evaluation, and Phase 13 Reliability gates admit live autonomy.

Rejected options#

Option Reason
queue-only-lifecycle A queue without durable goals, requirements, dependencies, and proof plans scales implementation throughput while losing whether the right work was selected.
drain-specific-state-machine A second transition or persistence path makes drained work semantically different from an operator lease and creates an unreviewed shortcut around the intent ledger.
mutable-plan-document Overwriting a plan erases prior human decisions, scope changes, and the requirement chain needed to explain an outcome or recover safely.
completion-or-merge-means-verified An agent report or merged commit proves activity, not that requirements or registered evidence passed; verification stays separately attributed and fail-closed.
manual-path-exception Letting hand-leased work bypass the drain contract would make the parity invariant vacuous and preserve an ungoverned path for high-impact actions.

Ratification#

Reviewer Status
Product owner pending
Eve workbench/platform owner pending
Security owner pending
Evaluation owner pending
Reliability owner pending

Implementation posture is effective-on-merge. Live autonomy posture is blocked-pending-named-ratification-and-cross-phase-gates.

Consequences#

  • Tasks 2.2–2.7 now have a single versioned contract to implement and adversarially model; task 2.8 cannot treat three successful queue items as lifecycle proof.
  • Phase 11 may deepen plan and review quality, but it must use these stable ids, revision, authority, traceability, and parity rules rather than defining a parallel engineering lifecycle.
  • Existing event-sourced work-item behavior remains useful and source-bound; this ADR does not falsely claim the missing planning entities or drain exist.
  • The machine record is ../audits/eve-sota-governed-delivery-lifecycle/2026-09-02.json, digest b0029d9df8179287204e006b55cd4e9410898127b9ac89eb0ce6cbf5cd632418.

Limitations#

  • This decision closes task 2.1 only. It defines an implementation contract; it does not add durable goal, requirement, dependency, verification-plan, or drain records.
  • The observed workbench baseline is source inspection of the current repository, not a live Postgres, MCP, coding-agent, or provider execution.
  • The current event ledger and queue already provide useful work-item, decision, lease, ship, and artifact-verification behavior, but they do not yet enforce the complete governed-delivery chain or drain/hand parity proof.
  • Tasks 2.2 through 2.7 own the missing runtime contracts and executable parity/fault proof; task 2.8 owns gated live backlog and soak evidence.
  • Named human ratification is pending, live autonomous activation is forbidden, Phase 2 remains open, and gaps G1 and G12 remain open for final task 18.1 reclassification.