Skip to Content
Numinance
Guides

Release and incident response

A designed walkthrough of a governed release with a canary window and rollback, event-driven incident response, the four breaker positions, and human-only break-glass.

View as .mdUpdated
Under development

This is a storyboard of the Numinance engine, which is proprietary and not generally available. The StageRegistry and AutonomyPolicy documents shown are real and validate with the open CLI. The breaker, canary, rollback and break-glass behavior is designed and cannot be run from the open build.

Sourcedsha256/numinance-spec@ 3c74d59
Numinance does not deploy. Your release pipeline deploys, under its own identity, after policy and a human have allowed it, and the same machinery that releases also watches and reverses.

When to use this

Read this guide when you want to know who can do what between a merged change and production, how a bad release is detected and reversed, and how you stop everything at once. Use it with Choose an autonomy level and Circuit breaker.

Who deploys

Four identities exist in the design: author-agent, reviewer-agent, release-pipeline and a human approver. Only the release-pipeline identity may invoke deployment, and only through your customer pipeline. An author or reviewer agent never holds a production-capable grant. Autonomy levels beyond merge (AUTONOMY_LEVEL_STAGE, AUTONOMY_LEVEL_RELEASE, AUTONOMY_LEVEL_OPERATE) are ceilings that the policy must be configured to reach, and the generated default is the pull-request level.

The release path in configuration

A release gate is a StageRegistry stage mapped to CHANGE_STATE_RELEASE_GATE. The spec ships two organization examples. The first routes release through a change advisory board with a timeout:

schemas/examples/StageRegistry/trunk-with-cab.yaml (release gate)
    - name: cab
      maps_to: CHANGE_STATE_RELEASE_GATE
      gate:
        kind: GATE_KIND_HUMAN
        approver_role: change-advisory-board
        sod: {distinct_from: [author-agent, reviewer-agent]}
        timeout: 86400s
      requires: [build]

The second names a release-managers role and asks for two approvals:

schemas/examples/StageRegistry/two-person-release.yaml (release gate)
    - name: release-approval
      maps_to: CHANGE_STATE_RELEASE_GATE
      gate:
        kind: GATE_KIND_HUMAN
        approver_role: release-managers
        required_approvals: 2
      requires: [build]

Approval counts are not enforced yet

The spec example notes that required_approvals is preserved but nothing enforces the count yet. Do not rely on it for two-person control until the engine documents enforcement.

A floor can also hold production back. In the organization ladder example, a floor on environment: production caps the level at AUTONOMY_LEVEL_MERGE, so no rule can resolve a production-environment change to release or operate. Raising that cap is a reviewed org policy change.

The lifecycle after the gate

Change lifecycle

What does a durable change do from objective to evidence, and where does it pause?

Illustrative · simulated
Scenario
Speed
  1. Understand / Classify
  2. ◇ Plan gate
  3. Implement
  4. Verify
  5. ┄ Repair (bounded)
  6. Rehearse
  7. ◇ Release gate
  8. Merge
  9. Release
  10. Observe
  11. ┄ Recover
  12. 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.

▣ current✓ visited◇ gate┄ not on this pathnext action is yellow
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.

  1. 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.
  2. 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.
  3. 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.
  4. Verify: Deterministic checks pass; the reviewer adds findings, never a verdict. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
  10. 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.

  1. Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
  2. Plan gate: Policy allows the plan. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
  3. Implement: The author-agent produces a first candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
  4. 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.
  5. 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.
  6. 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.
  7. Verify: All verification layers pass this time. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
  13. 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.

  1. Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
  2. Plan gate: Policy allows the plan. Acts: engine plans; policy decides. Evidence: Policy decision with reasons, plan digest frozen before any write grant.
  3. Implement: First candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
  4. Verify: Verification fails. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
  5. Repair (bounded): Attempt 1 of 2. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
  6. Implement: Second candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
  7. Verify: Verification fails again. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
  8. Repair (bounded): Attempt 2 of 2. Acts: engine re-enters Implementing; author-agent. Evidence: Repair attempt recorded with its number and findings digest.
  9. Implement: Third candidate. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
  10. 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.

  1. 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.
  2. 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.
  3. 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.
  4. Implement: Work proceeds under the approved grant. Acts: author-agent (work-unit grant). Evidence: Author run completed: candidate digest, grant id, budget used.
  5. Verify: Verification passes. Acts: reviewer-agent (read-only) and deterministic verifiers. Evidence: VerdictIssued: layers, findings reference.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. Observe: The canary window is evaluated against the declared SLOs. Acts: engine evaluates canary window. Evidence: Canary result against declared SLOs.
  11. 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.

  1. Understand / Classify: Context is resolved and the Change is classified. Acts: engine (read-only grant). Evidence: Context resolved: sources used and digests.
  2. 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.
  3. Evidence seal: The runner seals the sequence. No code was written. Acts: runner identity (evidence writer). Evidence: Sequence sealed with an outcome record.

Release gate

Policy evaluates all evidence: verification results, declared evidence, the plan digest and the autonomy level. A human gate waits for a named approver who is not the author or reviewer. The decision and its reasons are recorded.

Merging and releasing

At the pull-request level the change ends at the PR. Where policy allows, the merge happens, and the release child workflow invokes your pipeline as the release identity. Orchestration payloads carry references and digests, never source or secrets.

Observing: the canary window

After release, the change enters the observing state for a canary window that comes from the playbook. The observability port evaluates service level objectives and declared invariants. If they hold, the change closes and its evidence is sealed.

Recovering: rollback

If the window shows a regression, the change enters the recovering state. Rollback goes through your CD provider under the release identity, and a corrective change is opened. The original change ends as rolled back with its evidence sealed. Rollback rate is also one of the qualification thresholds a playbook must satisfy before promotion.

illustrative stage log
release-gate     approved             approver_role=release-managers
releasing        pipeline invoked     identity=release-pipeline
observing        canary window open   SLOs and invariants evaluated
observing        regression detected
recovering       rollback requested   through the CD provider
rolled-back      evidence sealed      corrective change opened

Event-driven incident response

Incidents enter as events, not as a person typing a command. An incident detection signal reaches the running change or opens a new one, and the response is the same governed workflow with tighter defaults:

  1. The affected runs freeze at the next checkpoint.
  2. Credential handles for the change are revoked.
  3. The component's effective autonomy is lowered, to pull-request-only or read-only.
  4. The sandbox is snapshotted and the evidence sequence is sealed.
  5. An incident change is opened and the paging and security tooling you configured is notified.
  6. Recovery requires an explicit human decision with a reason.

An incident change is still a change: it runs under a grant, passes gates, and emits evidence. Incident status does not buy extra authority.

Breaker positions

The circuit breaker is customer-local: its state lives in your runtime and it works without any connection to the vendor's control plane. It has four positions.

PositionEffect
FULL_AUTONormal operation. Autonomy is whatever policy resolves.
PR_ONLYEffective autonomy is capped at opening pull requests. No merge, no release.
READ_ONLYEffective autonomy is capped at reading. No writes.
STOPPEDRuns are halted.

PR_ONLY here is a breaker position. It is not an autonomy ladder level; the ladder level is AUTONOMY_LEVEL_PR. The breaker only ever lowers what policy would allow.

A trip comes from a human through the dashboard, the CLI or an API, or from the incident detector, a budget or policy anomaly, an evidence-write failure or provider drift. A trip revokes credential handles, pauses runs at the next checkpoint, caps effective autonomy and records evidence. Paused is an overlay on any active state, so the change remembers where it was. Reset is a human action and needs a reason.

Break-glass is human-only

Break-glass exists for the moment policy is wrong and production is down. It is a human act:

  • It is invoked by a named human principal, not a shared account.
  • A reason is required.
  • Its scope is limited to what the emergency needs.
  • It expires.
  • It is logged separately from ordinary evidence.
  • No agent identity can invoke it, and an agent cannot ask a human to widen its own grant on its behalf.
  • A post-event review is created after use.

Dual control can be configured per control pack.

What a human approves

  • The release gate, with the role your StageRegistry names.
  • Resetting the breaker, with a reason.
  • Any break-glass, with a name and a time box.
  • Raising a cap such as the production floor, through a policy change.

Failure modes and safeguards

FailureSafeguard
Evidence cannot be writtenThe breaker trips; the design does not proceed without evidence.
Provider behavior driftsTreated as a trip condition.
Rollback itself failsThe change escalates to a human.
Budget exhaustedThe run pauses and escalates.
An approver is also the authorPolicy denies it structurally.

After the fact, the evidence is checkable offline under keys you pin. A verified result proves the chain and signatures, not that the release was a good idea. See Verify a run.

Check the configuration today

revision: "files"
ok       file "org-ladder.yaml" AutonomyPolicy "org-ladder"
✓ verifiednumi validate --files on the AutonomyPolicy example· numinance-spec @ 3c74d59 · 2026-11-09· 0
validate the StageRegistry examples
go run ./cli/numi validate --files schemas/examples/StageRegistry

Next steps

Circuit breaker

Positions, triggers and reset.

Rollback and recovery

Recovery loops and escalation.

Stage registry

Gate fields and state mapping.

Bugfix with verification

A designed walkthrough of a bug fix that ends in a pull request, showing independent verification, bounded repair, escalation and the evidence each stage emits.

Configuration

How the typed YAML under .numinance/ works, the shared envelope, every configuration kind with its scope and owning page, and how scopes layer.

On this page

When to use thisWho deploysThe release path in configurationThe lifecycle after the gateRelease gateMerging and releasingObserving: the canary windowRecovering: rollbackEvent-driven incident responseBreaker positionsBreak-glass is human-onlyWhat a human approvesFailure modes and safeguardsCheck the configuration todayNext steps