StageRegistry

Purpose and scopesCopy Anchor Link

Every Change moves through a fixed state machine (opened, understood, classified, planned, plan gate, implementing, integrated, verifying, repairing, rehearsing, release gate, merging, releasing, observing, recovering, escalated, paused, closed, abandoned). A StageRegistry lets your organization call those states by its own names, add human gates where it wants them, and say which stage must complete before which.

A registry can be written at any scope, but only the org scope selects one: SDLCProfile.spec.stages is FORBID, so a narrower scope cannot pick a registry without the org's gates. A repo-scoped registry, like the one numi init writes, is defined but not selected until an org profile names it. See Change lifecycle.

Field referenceCopy Anchor Link

Example: trunk with a change advisory boardCopy Anchor Link

apiVersion: numinance.dev/v1
kind: StageRegistry
metadata: {name: trunk-with-cab, scope: SCOPE_ORG}
spec:
  stages:
    - {name: triage, maps_to: CHANGE_STATE_CLASSIFIED}
    - {name: design-review, maps_to: CHANGE_STATE_PLAN_GATE, gate: {kind: GATE_KIND_PLAN}, requires: [triage]}
    - {name: build, maps_to: CHANGE_STATE_IMPLEMENTING, requires: [design-review]}
    - 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]

cab is your name for the release gate. A human from change-advisory-board, who is neither the author-agent nor the reviewer-agent, decides. After 86400 seconds an undecided gate escalates; it does not approve.

Example: two-person releaseCopy Anchor Link

apiVersion: numinance.dev/v1
kind: StageRegistry
metadata: {name: two-person-release, scope: SCOPE_ORG}
# required_approvals is only preserved today; nothing enforces the count yet.
spec:
  stages:
    - {name: triage, maps_to: CHANGE_STATE_CLASSIFIED}
    - {name: build, maps_to: CHANGE_STATE_IMPLEMENTING, requires: [triage]}
    - name: release-approval
      maps_to: CHANGE_STATE_RELEASE_GATE
      gate:
        kind: GATE_KIND_HUMAN
        approver_role: release-managers
        required_approvals: 2
      requires: [build]

Example: PR-only registry from numi initCopy Anchor Link

The generated registry names no stage for the Merging state, so no stage of it can merge. The last stage is a human gate.

apiVersion: numinance.dev/v1
kind: StageRegistry
metadata: {name: pr-only, scope: SCOPE_REPO}
spec:
  stages:
    - {name: triage, maps_to: CHANGE_STATE_CLASSIFIED}
    - {name: plan-review, maps_to: CHANGE_STATE_PLAN_GATE, gate: {kind: GATE_KIND_PLAN}, requires: [triage]}
    - {name: implement, maps_to: CHANGE_STATE_IMPLEMENTING, requires: [plan-review]}
    - {name: verify-static, maps_to: CHANGE_STATE_VERIFYING, requires: [implement]}
    - {name: ci-github-actions, maps_to: CHANGE_STATE_VERIFYING, requires: [verify-static]}
    - name: pr-gate
      maps_to: CHANGE_STATE_RELEASE_GATE
      gate:
        kind: GATE_KIND_HUMAN
        approver_role: maintainer
        sod: {distinct_from: [author-agent, reviewer-agent]}
        required_approvals: 1
      requires: [ci-github-actions]

$ numi validate --files schemas/examples/StageRegistry
revision: "files"
ok       file "trunk-with-cab.yaml" StageRegistry "trunk-with-cab"
ok       file "two-person-release.yaml" StageRegistry "two-person-release"

Fixed states cannot be removedCopy Anchor Link

Your stages map onto states; they do not define them. The registry cannot delete a state, skip a gate state, or make a weaker gate. A stage mapped to CHANGE_STATE_PLAN_GATE or CHANGE_STATE_RELEASE_GATE still gets the policy decision for that state even if you declare no gate or a weaker one. CHANGE_STATE_PAUSED is an overlay that the circuit breaker sets and a registry cannot use as a stage (the profile context refuses it). Several stages may map to the same state, as the two verifying stages above do.

Security implicationsCopy Anchor Link

• Only an org-scoped profile selects the registry, so a repository cannot swap in one with fewer gates.
• sod.distinct_from only adds exclusions. The approver is never the author and the approver's run is never the author's run.
• A timeout escalates; no gate approves on its own.
• GATE_KIND_HUMAN approval is a human decision, and agents cannot satisfy it.

Common misconfigurationsCopy Anchor Link

$ numi validate --files bad-approvals.yaml
revision: "files"
invalid  file "bad-approvals.yaml": kind: invalid: required_approvals is set on a gate that is not GATE_KIND_HUMAN

Using a short enum (HUMAN instead of GATE_KIND_HUMAN) fails with "/spec/stages/3/gate/kind": enum, exit 3.

What validation checks, and what it does notCopy Anchor Link

Checked by the open build: keys, enum names, durations, non-empty stages, required_approvals only on human gates and never 0. Not checked: a copy where requires names a stage that does not exist, and another that maps a stage to CHANGE_STATE_PAUSED; both passed numi validate --files with exit 0. The proto says the profile context checks the requires DAG and refuses PAUSED, which is the engine build. Do not treat a green open validation as proof the registry is sound.

Next stepsCopy Anchor Link