Change lifecycle
The durable stages every change passes through - Understand, Plan, Act, Verify, Evidence - and the release, observe and recover stages that exist only when authorized.
A change is a durable state machine with fresh authority at each gate, not one long agent session.
The core loop
Understand -> Plan -> Act -> Verify -> Evidence| Stage | What happens | Typical states |
|---|---|---|
| Understand | Resolve context, classify the change. | CHANGE_STATE_UNDERSTOOD, CHANGE_STATE_CLASSIFIED |
| Plan | Produce a plan and pass the plan gate. | CHANGE_STATE_PLANNED, CHANGE_STATE_PLAN_GATE |
| Act | Agents implement work units under bounded grants. | CHANGE_STATE_IMPLEMENTING, CHANGE_STATE_INTEGRATED |
| Verify | Independent checks, bounded repair. | CHANGE_STATE_VERIFYING, CHANGE_STATE_REPAIRING |
| Evidence | Seal the record of what happened. | CHANGE_STATE_CLOSED |
Change lifecycle
What does a durable change do from objective to evidence, and where does it pause?
- Understand / Classify
- ◇ Plan gate
- Implement
- Verify
- ┄ Repair (bounded)
- Rehearse
- ◇ Release gate
- Merge
- Release
- Observe
- ┄ Recover
- Evidence seal
Step 1 of 10 · Understand / Classify
Context is resolved from authorised sources and the Change is classified.
- Lifecycle state
- Opened, Understood, Classified
- Who acts
- engine (read-only grant)
- Temporal holds (references only)
- change_id, state, context bundle artifact_ref + sha256
- Customer artifact storage holds
- Repository index, resolved context bundle, risk classification
- Evidence record emitted
- Context resolved: sources used and digests
Happy path, step 1 of 10: Understand / Classify. Context is resolved from authorised sources and the Change is classified.
Text description
A Change is a durable state machine, not one long agent session. The agent implements one work unit at a time; planning, gates, verification, release and recovery are performed by Numinance with fresh authority per stage. Orchestration payloads carry references and digests only; source, diffs, prompts, logs and findings bodies live in customer artifact storage.
Stages in order: Understand / Classify, Plan gate, Implement, Verify, Repair (bounded), Rehearse, Release gate, Merge, Release, Observe, Recover, Evidence seal. Verification failure re-enters implementation with the findings reference as the only new input, at most max_repair_attempts times (default 2 in the generated Playbook), then the Change is escalated. Plan and release gates can allow, deny or require approval; approvals come from a human other than the author.
Happy path. Every gate allows and verification passes first time.
- Understand / Classify: Context is resolved from authorised sources and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy allows the plan under the initial grant. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
- Implement: One work unit runs in a sandbox under a work-unit grant. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Deterministic checks pass; the reviewer adds findings, never a verdict. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Rehearse: A disposable environment rehearses migrations and deployment; it is destroyed at its TTL. Acts: engine with environment provider; reviewer identity. Evidence: Rehearsal evidence: timings and plan digests.
- Release gate: Policy consumes the verdict and the evidence list and allows the release. Acts: policy decides; release-pipeline identity only after allow. Evidence: Gate decision referencing the verdict, never raw findings.
- Merge: The release pipeline merges. At PR level the Change closes here; higher levels continue. Acts: release-pipeline. Evidence: Merge recorded with operation id; PR-level autonomy ends here as Closed.
- Release: Only the release pipeline deploys, and only if the autonomy level allows. Acts: release-pipeline (the only deployer). Evidence: Deployment recorded under the release identity.
- Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
- Evidence seal: The runner seals the evidence sequence and the Change closes. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Verification fails, then repair. A failing check feeds one bounded repair attempt, then verification passes.
- Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy allows the plan. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
- Implement: The author-agent produces a first candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: A deterministic check fails. The findings are stored and referenced by digest. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Repair (bounded): Attempt 1 of 2 (the default cap). The findings reference is the only new input. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
- Implement: The author-agent runs again under a fresh grant. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: All verification layers pass this time. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Rehearse: A disposable environment rehearses migrations and deployment; it is destroyed at its TTL. Acts: engine with environment provider; reviewer identity. Evidence: Rehearsal evidence: timings and plan digests.
- Release gate: Policy consumes the verdict and the evidence list and allows the release. Acts: policy decides; release-pipeline identity only after allow. Evidence: Gate decision referencing the verdict, never raw findings.
- Merge: The release pipeline merges. At PR level the Change closes here; higher levels continue. Acts: release-pipeline. Evidence: Merge recorded with operation id; PR-level autonomy ends here as Closed.
- Release: Only the release pipeline deploys, and only if the autonomy level allows. Acts: release-pipeline (the only deployer). Evidence: Deployment recorded under the release identity.
- Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
- Evidence seal: The runner seals the evidence sequence and the Change closes. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Repair exhausted, escalated. Two bounded repairs fail. The Change escalates to a human instead of trying forever.
- Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy allows the plan. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
- Implement: First candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification fails. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Repair (bounded): Attempt 1 of 2. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
- Implement: Second candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification fails again. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Repair (bounded): Attempt 2 of 2. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
- Implement: Third candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification fails a third time. The cap is reached. Acts: engine; waits for a human signal. Evidence: Escalation recorded with the findings digest; no grant is widened.
Approval required. Policy answers require approval. The workflow waits for a human other than the author.
- Understand / Classify: Context is resolved and the Change is classified as higher risk. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy answers require approval. The workflow now waits on a signal with a timer (default 7 days). Acts: policy; human approver pending. Evidence: Policy decision: require approval, approver group, author excluded.
- Plan gate: A human approver grants. The signal is rejected if the approver equals the author. Acts: human approver. Evidence: Approval record with approver principal and decision id.
- Implement: Work proceeds under the approved grant. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
- Verify: Verification passes. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
- Rehearse: A disposable environment rehearses migrations and deployment; it is destroyed at its TTL. Acts: engine with environment provider; reviewer identity. Evidence: Rehearsal evidence: timings and plan digests.
- Release gate: Policy consumes the verdict and the evidence list and allows the release. Acts: policy decides; release-pipeline identity only after allow. Evidence: Gate decision referencing the verdict, never raw findings.
- Merge: The release pipeline merges. At PR level the Change closes here; higher levels continue. Acts: release-pipeline. Evidence: Merge recorded with operation id; PR-level autonomy ends here as Closed.
- Release: Only the release pipeline deploys, and only if the autonomy level allows. Acts: release-pipeline (the only deployer). Evidence: Deployment recorded under the release identity.
- Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
- Evidence seal: The runner seals the evidence sequence and the Change closes. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Denied by policy. The plan gate denies. The denial is recorded and the Change is abandoned with no write grant ever issued.
- Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
- Plan gate: Policy denies the plan. Denials are evidence too. Acts: policy decision point. Evidence: Denial with rule ids as reasons and the policy decision id.
- Evidence seal: The runner seals the sequence. No code was written. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.
Beyond the pull request
When, and only when, the autonomy level and policy authorize it, the lifecycle continues:
- Release.
CHANGE_STATE_REHEARSING,CHANGE_STATE_RELEASE_GATE,CHANGE_STATE_MERGINGandCHANGE_STATE_RELEASING. The release gate and everything after it run under the release-pipeline identity, never the author agent. - Observe.
CHANGE_STATE_OBSERVINGwatches the released change for a window defined by the playbook. - Recover.
CHANGE_STATE_RECOVERINGandCHANGE_STATE_ROLLED_BACKwhen observation or release fails.
A change at PR level closes after the pull request is opened and never enters release states. The evidence export records that explicitly: the deployment and observation parts are marked not applicable at PR level, and the verifier checks that the chain bears this out.
Terminal and side states
| State | Meaning |
|---|---|
CHANGE_STATE_ESCALATED | A human signal is needed. Reached from failed verification, exhausted repair or a denied gate. |
CHANGE_STATE_PAUSED | The circuit breaker tripped. Work resumes only on breaker reset. |
CHANGE_STATE_ABANDONED | The change was denied, rejected or cancelled. |
CHANGE_STATE_CLOSED | Completed at the authorized level. |
CHANGE_STATE_ROLLED_BACK | Recovery restored the previous state. |
Fresh authority per stage
Authority does not carry over. Planning runs under an initial read-oriented grant. The plan gate decides again before implementation. The release gate decides again before merge. A human can be required at either gate by policy or by risk class, and the approver cannot be the author. Because each stage re-evaluates, a decision that was right at planning time cannot be reused after the situation changed.
Reference-only payloads
The orchestration layer moves change identifiers, digests, decision references and status codes. Source, diffs, prompts and logs stay in the artifact store and travel as references. This is why a workflow history can be inspected without leaking the change itself.
Failure modes
- Verification fails and repair is exhausted: the change escalates, it does not loop.
- The breaker trips mid-implementation: the change pauses.
- A gate denies: the change is abandoned with the denial recorded.