State Machine

This chapter is the canonical reference for AI-DLC's state machines, the audit-event taxonomy, and the rule that connects them — every state transition has exactly one tool-owned emitter. Keeping this chapter's tables in sync with the code is enforced by the drift test at tests/integration/t48-audit-event-emitters.test.ts. If the doc and the code disagree, t48 fails.

Three nested state machines drive AI-DLC: workflow, phase, and stage. A fourth, independent stream records session events emitted by Claude Code hooks. These four streams share the intent's audit trail (the audit/ shard dir under its record dir, <record>/ = aidlc/spaces/<active-space>/intents/<YYMMDD>-<label>/) but are owned by different code paths, so it's easiest to read them as separate concerns and remember that their timelines interleave.

North-star invariant: TypeScript owns deterministic bookkeeping; the LLM owns judgment. Every audit emission originates in a tool or hook, keeping LLM prose out of the emit path. If you're reading an MD file and see aidlc-audit.ts append <EVENT> as a prose instruction, that is a bug.

Audit-first atomicity: tools emit their audit entries before mutating state. If audit emission fails, the tool throws before touching state — so audit.md and the state file never disagree. The "Audit-first atomicity" section near the end of this chapter spells out the failure modes, plus the two exceptions: audit-of-intent (WORKTREE_*, AUDIT_*, MERGE_DISPATCH_INVOKED) and the audit-last DocumentKB catalog events, whose artifact is derived and rebuildable.

Why three state machines

A workflow completes by passing through phases; a phase completes by passing through its in-scope stages; a stage completes when its approval gate closes. Each layer owns a distinct decision:

• Workflow — is the overall job running, or done?
• Phase — is this lifecycle phase in progress, verified, or skipped because the scope excluded it?
• Stage — is the stage being worked on, waiting on the user, being revised after rejection, or complete?

Flattening them into one state field conflates those decisions. Separating them means /aidlc --status can answer "what's blocking this workflow?" in one read: workflow Running, phase Active, stage [?] → "awaiting your approval on \<stage>".

Workflow machine

stateDiagram-v2
    [*] --> Running : WORKFLOW_STARTED
    Running --> Completed : WORKFLOW_COMPLETED
    Completed --> [*]

Status values: Running, Completed.

A workflow starts when the first intent is born (aidlc-utility intent-create, auto-invoked on the first /aidlc or via /aidlc-init) and ends when the last in-scope stage's approval gate closes. There is no Paused status and no Waiting for Approval status — approval is a stage-level concern, pause has no UX.

A workflow's Running state persists across Claude Code sessions. You start a workflow on Monday, stop the session, resume on Tuesday — the workflow is still Running; the session ended and a new one started.

Phase machine

stateDiagram-v2
    [*] --> Pending
    Pending --> Active : PHASE_STARTED
    Pending --> Skipped : PHASE_SKIPPED
    Active --> Verified : PHASE_COMPLETED + PHASE_VERIFIED
    Verified --> [*]
    Skipped --> [*]
    note right of Verified
        At a phase boundary, advance
        emits PHASE_COMPLETED +
        PHASE_VERIFIED + PHASE_STARTED
        (next phase) in one transaction.
    end note

Status values: Pending, Active, Verified, Skipped.

Phase state is tracked in the ## Phase Progress section of aidlc-state.md. Intent birth seeds the section: Initialization lands Verified (birth completes every init stage before handing off), the first post-init stage's phase lands Active, and each later phase lands Skipped when the scope leaves it without EXECUTE stages (one PHASE_SKIPPED audit row each) or Pending otherwise. Phase completion fires both PHASE_COMPLETED and PHASE_VERIFIED at the phase boundary, then PHASE_STARTED for the next one, and the rows flip in the same state write. The section is display-only: routing reads Lifecycle Phase and the Stage Progress checkboxes, and /aidlc --status recomputes its phase block live.

At the init→post-init hand-off, aidlc-utility intent-create itself emits PHASE_COMPLETED + PHASE_VERIFIED + PHASE_STARTED + STAGE_STARTED after the final init stage so the audit trail captures the transition instead of going silent between birth and the first advance.

Stage machine

stateDiagram-v2
    state "[ ] Pending" as Pending
    state "[-] Active" as Active
    state "[?] AwaitingApproval" as Awaiting
    state "[R] Revising" as Revising
    state "[x] Completed" as Completed
    state "[S] Skipped" as Skipped

    [*] --> Pending
    Pending --> Active : STAGE_STARTED
    Active --> Awaiting : STAGE_AWAITING_APPROVAL
    Awaiting --> Completed : GATE_APPROVED + STAGE_COMPLETED
    Awaiting --> Revising : GATE_REJECTED + STAGE_REVISING
    Revising --> Awaiting : STAGE_AWAITING_APPROVAL
    Pending --> Skipped : STAGE_SKIPPED
    Active --> Skipped : STAGE_SKIPPED
    Revising --> Skipped : STAGE_SKIPPED
    Completed --> [*]
    Skipped --> [*]

Checkbox legend (in aidlc-state.md):

[?] and [R] disambiguate two situations that would otherwise both look like [-]. On resume, [R] tells the conductor to present the prior artifact and feedback before re-entering the gate, instead of re-executing the stage from scratch.

The approved report owns the full post-gate transition: it emits GATE_APPROVED + STAGE_COMPLETED, then routes to the next in-scope stage, emitting STAGE_STARTED plus any PHASE_* events at boundaries. On the final in-scope stage it emits PHASE_COMPLETED + PHASE_VERIFIED + WORKFLOW_COMPLETED and sets Status=Completed. The conductor does not call state lifecycle verbs before or after reporting.

Routed skip. report --result skipped is accepted only on the main workflow with an explicit nonblank --stage and --reason, when the named stage is declared execution: CONDITIONAL, equals Current Stage, and is Active or Revising. It runs before artifact, per-unit, and ensemble-evidence guards because a justified skip owes no completion evidence. The engine invokes the internal skip transition with its routing marker: the transaction preserves [S], emits exactly one STAGE_SKIPPED, never emits STAGE_COMPLETED, and either starts the next stage (including boundary events) or completes the workflow. If onward routing fails, recovery leaves the skipped marker and cursor at the same stage so the route can be retried without duplicating the skip event. report --single --result skipped is rejected.

Artifact guard (issue #366). Every report outcome that marks a stage [x] runs a deterministic artifact check before completing it, so a stage cannot be marked complete without evidence of work on disk. A stage that declares produces[] must have at least one of those artifacts present (under the active intent's record dir, its per-unit Construction directories, or the active space's codekb/<repo>/ for codekb stages); workspace_requires: true also requires source-work evidence outside aidlc/ and the harness dir. A failure writes nothing. Optional outputs do not participate. For produces_kinds, units whose kind prunes the required set to zero owe no artifact; any applicable unit remains strict. Bypass with AIDLC_SKIP_ARTIFACT_GUARD=1.

Ensemble evidence gate. On a mob or subagent-with-supports stage, the report path refuses awaiting-approval, revised, and approved while a declared support agent's contribution file (<stage>/contributions/<agent-slug>.md) is missing or lacks its **Collaborator:** identity-marker first line — the deterministic proof the ensemble actually convened. A settled autonomous swarm is exempt (its per-unit convergence ledger is the evidence); report --single checks stage-level evidence only. Bypass with AIDLC_DISABLE_ENSEMBLE_EVIDENCE=1, intended only for recovering a legitimately-run stage whose contribution files were lost.

Gate-revision backstop. If the conductor revises an artifact at an open gate without first reporting rejection, the approved report reconciles the missing GATE_REJECTED + STAGE_REVISING pair before completion when audit evidence proves a post-gate human turn followed by an artifact write. The backfilled rows carry Recovered: true; reviewer writes before the human turn do not count. Bypass with AIDLC_SKIP_REVISION_BACKSTOP=1.

Park (issue #365/#367). aidlc-orchestrate park writes a Parked / Parked At Stage runtime marker (via aidlc-state.ts park, which emits WORKFLOW_PARKED) without advancing any stage; a subsequent plain next re-emits a terminal parked directive and the Stop hook lets the turn end, so a long workflow can pause across sessions instead of rubber-stamping the remaining stages to reach done. /aidlc --resume clears the marker (unpark emits WORKFLOW_UNPARKED) before continuing. An unattended autonomous Construction run (Construction Autonomy Mode: autonomous) refuses to park: both the tool and the Stop hook's parked allow decline under autonomous mode, so the loop keeps moving with no human to resume it.

Revision loop

report awaiting-approval  →  [?] AwaitingApproval
          ↘ report rejected  →  [R] Revising  (Revision Count += 1)
                   ↓ report revised
                   [?] AwaitingApproval
                   ↘ report approved  →  [x] Completed

Revision Count lives in the state file and increments on each rejected report. The conductor uses this to detect the revision-loop escape hatch (default is 3 cycles before offering to skip).

When a revision changes a produces[] artifact on a stage whose directive carries a reviewer, the conductor re-runs the stage-protocol-reviewer.md §12a step before reporting revised (stage-protocol Part 0) — the engine's own checks on the revised report remain structural (completion evidence + artifact existence); the reviewer re-run is conductor prose, not an engine gate.

Session stream (hook-owned, independent)

Session events are emitted by Claude Code hooks, not by AI-DLC tools. A session is a single Claude Code conversation; a workflow is a long-lived directory state. The relationship is many-to-many — one workflow can span multiple sessions, one session can touch multiple workflows — so the streams are independent by design.

Session hooks check for the active intent's aidlc-state.md (under aidlc/spaces/<space>/intents/<YYMMDD>-<label>/) before emitting. If no such file exists (no active AI-DLC workflow in the cwd), the hook exits silently without writing to any audit log. Session events exist to annotate an active workflow's timeline — a session in a directory with no workflow has nothing to annotate.

Compaction awareness

aidlc-state.ts resume scans the audit tail for the latest SESSION_COMPACTED. If no stage activity (STAGE_STARTED, STAGE_COMPLETED, GATE_APPROVED, SESSION_RESUMED, RECOVERY_COMPLETED) follows it, resume returns compaction_pending: true and the conductor surfaces a three-option prompt (continue / review / restart) before proceeding. RECOVERY_COMPLETED is emitted by acknowledge-compaction once the user picks an option, satisfying the activity gate so subsequent compactions detect a fresh boundary.

Audit event taxonomy

85 events, grouped below into 19 categories (the canonical audit-format.md registry splits the same 85 into 22 - the grouping is presentational, the event set is the invariant). Every event has exactly one tool or hook emitter, except for events pre-registered for an upcoming release whose Emitter cell reads Reserved (v0.4.0 PR N), Reserved (v0.5.0 PR N), or Reserved (v0.6.0 PR N) - these are skipped by the drift test's forward check until the consumer PR ships the emitter. The drift test tests/integration/t48-audit-event-emitters.test.ts enforces forward/reverse/tertiary/pairing/MD-MD consistency between this chapter's tables and the code.

Workflow lifecycle

Phase lifecycle

Stage lifecycle

Gate decisions

User interaction

Unit lifecycle (inline per-unit Construction stages)

Scope and configuration

Artifacts

Construction Bolts

Session

Diagnostics and workspace

Documents

The DocumentKB is space-level, so all three land in one space-level shard even for an intent-scoped document — the intent UUID is a field on the event, not the shard selector.

That shard is spaces/<space>/intents/audit/, not spaces/<space>/audit/. The intents/ segment is inherited from intentsDir(), which is where every shard in a space lives; the space-level shard is a sibling of the per-intent record dirs rather than a directory one level up. An earlier version of this line documented the shorter path, which does not exist on disk — measured by onboarding a document and finding the written shard.

Workflow-authority readers enumerate only the resolved intent's shards. Consumers that need space-level provenance request it explicitly; --doctor --export does so and reads the space shard before the resolved intent shards, keeping document events visible without widening lifecycle authority beyond the intent ledger.

All three ship with tools/aidlc-knowledge.ts (DocumentKB S1). Emitting verbs per event are listed in each row below — onboard, sync, associate, dissociate, and rebind all emit.

All three land in the space-level audit shard even when the document is scoped to an intent: a document outlives any intent, and its scope can move later, so filing its provenance under whichever intent happened to be active would split one document's history across shards and make it unreconstructible.

Error and recovery

Worktree

Pre-registered for v0.4.0; the three WORKTREE_* rows ship with aidlc-worktree.ts (milestone 7); STATE_* lands in milestone 9 (state fork/merge); AUDIT_* lands in milestone 10 (audit fork/merge). t48 forward check skips rows whose Emitter cell still reads Reserved.

Practices

Pre-registered for v0.4.0; emitters land in milestone 8 (stage 2.2 practices-discovery) and milestone 13 (Construction orchestrator runtime).

Merge dispatch

Pre-registered for v0.4.0 in milestone 1; emitters land in milestone 13 via the new aidlc-bolt dispatch-event subcommand. The conductor brackets each aidlc-pipeline-deploy-agent dispatch — pre-call INVOKED, post-call RETURNED on successful YAML parse, FALLBACK on timeout / malformed-YAML / low-confidence.

Sensors

Pre-registered for v0.5.0 in milestone 1; emitters land in milestone 9 (sensor dispatcher) for the four SENSOR_* events and milestone 14 (paired-coverage doctor row) for GUARDRAIL_LOADED. Coverage is environmental — every Inception/Construction/Operation stage that writes markdown emits at least one SENSOR_FIRED row from the registry-default sensors. Advisory-only in v0.5.0; v0.8.0 ralph driver introduces blocking semantics for Construction-phase sensors.

Learning loop

Pre-registered for v0.5.0 in milestone 4; MEMORY_EMPTY emitter lands in milestone 8 (aidlc-runtime.ts compile). The §13 Learnings Ritual writes a per-stage memory.md during execution; on stage approval, the runtime-graph compile reads memory.md and emits MEMORY_EMPTY for any stage with zero non-blank entries under the four standard headings. milestone 12's learning-gate tool (aidlc-learnings.ts persist) emits RULE_LEARNED when a kept learning lands as a dated practice entry in aidlc/spaces/<active-space>/memory/{project,team}.md, and SENSOR_PROPOSED when a learning installs a sensor binding (manifest + originating stage sensors: frontmatter). Doctor reads these rows for diary-discipline observability.

Swarm

Pre-registered for v0.6.0 in milestone 2. All six swarm events now emit from the swarm referee aidlc-swarm.ts — the deterministic verdict surface the conductor consults. The referee is stateless: prepare captures the exact stage-attempt token, forks the per-unit worktrees, and emits stamped SWARM_STARTED (plus SWARM_DEGRADED, born live in Wave 4 milestone 16, when the conductor reports a loud downgrade); finalize first requires that prepared token to match the current attempt, then re-verifies the conductor's claimed-converged set, including each configured unit's post-Bolt terminal reviewer receipt, and preserves the token on each convergence row. A stale finalize is refused before merge. The referee emits the per-Unit pair, the per-failed-Unit baton row, and the batch tally. The check subcommand is advisory and emits nothing. The engine is read-only and the conductor never emits audit events, so the deterministic tool owns the whole swarm taxonomy. These rows track the lifecycle of a batch of dependency-linked Units: fan-out at batch start, per-Unit convergence or re-verify failure, return-the-baton handback to the conductor, and batch completion. The conductor handles invoke-swarm as an orthogonal directive kind beside the stage mode enum — it does NOT activate the reserved agent-team mode, which stays reserved. t48 forward check skips rows whose Emitter cell still reads Reserved.

Every event in the taxonomy is either backed by a real emitter or marked Reserved (v0.4.0 PR N) / Reserved (v0.5.0 PR N) / Reserved (v0.6.0 PR N) for a pre-registered upcoming consumer. The drift test enforces both halves — the Reserved early-skip applies only while the cell literally contains "Reserved"; consumer PRs replace it with the real emitter file path in the same commit they ship the emit call.

Audit-first atomicity

State-mutating commands emit their audit entries before mutating the state file — with two documented exceptions: the audit-of-intent group below (audit first, side-effect second, for outcomes that cannot be checked before emission) and the DocumentKB catalog events (audit last — see "Audit-last for derived catalogs"). Two consequences:

1. If audit emission fails (lock timeout, disk error, invalid event type), the tool throws before touching state. The state stays at its previous value; audit.md stays clean.
2. If state writing fails after audit emission, the audit has an "intent" entry but the state didn't move. The drift is visible and diagnosable; --doctor surfaces it.

The case test("65: approve is audit-first ...") in tests/unit/t17.test.ts proves this for approve: chmod'ing audit.md to read-only forces an audit failure and asserts the state file stays at [?] (not [x]). The same invariant holds for gate-start, reject, revise, skip, advance, complete-workflow, reuse-artifact, aidlc-bolt.ts set-autonomy, and aidlc-state.ts fork / aidlc-state.ts merge (the v0.4.0 milestone 9 state fork/merge subcommands — see tests/unit/t76.test.ts for the equivalent chmod-the-lock-dir Part A and chmod-the-target-after-emit Part B proofs).

State fork/merge are deliberately NOT in the audit-of-intent exception below: re-reading and re-writing a state file is idempotent (unlike git worktree add, which leaves the worktree present after a kill-9 between emit and git), so the strict invariant applies cleanly. A failed state write after a successful audit emit becomes a phantom STATE_FORKED row that doctor (v0.4.0 milestone 15) reconciles against the worktree's record-dir aidlc-state.md existence.

Audit-last for derived catalogs (DOCUMENT_INDEXED, DOCUMENT_UPDATED, DOCUMENT_REMOVED)

The DocumentKB events invert the ordering: aidlc-knowledge.ts collects them during a commit and emits them only after index.json, every metadata.json, and every content.md write has succeeded. This is the one place in the framework where audit follows state, and it is a deliberate consequence of the catalog being derived.

Workflow state is authoritative — nothing can rebuild aidlc-state.md, so an audit row recorded ahead of a failed write leaves a phantom entry that --doctor can reconcile against the state file, and that diagnosable drift is the better trade. The DocumentKB catalog is the opposite: it is reconstructible from disk, because sync rebuilds a lost index.json from the surviving per-document metadata.json records, tombstones included. So the two failure modes are not symmetric here:

• Audit before state (rejected): a DOCUMENT_UPDATED row asserting a revision the catalog never took. Every later reader of the ledger — --doctor, an export, an agent citing provenance — is misled by a change that did not happen, and no rebuild removes the false row.
• Audit after state (chosen): a committed catalog change with no ledger row. The catalog itself remains authoritative; an idempotent retry rewrites any missing derived metadata and emits a repair row that describes the already-committed source/digest/scope. The missing row is therefore recoverable without inventing a state transition that did not occur.

A missing entry understates what happened; a phantom entry asserts something untrue. For a derived artifact that can be rebuilt, understating is the safer failure. The same reasoning does not extend to any authoritative state file, which is why this exception is scoped to these three events and not generalised.

Audit-of-intent semantics (WORKTREE_*, AUDIT_*, and merge-dispatch MERGE_DISPATCH_INVOKED)

Audit-of-intent semantics apply to side-effects whose outcome cannot be checked before emission — including disk operations (worktree creation / removal, audit byte-copy) and LLM Task dispatch (aidlc-pipeline-deploy-agent). The emitting tool writes the audit entry first, then performs the side-effect. If the side-effect fails after the emit, the tool calls emitError with the slug embedded in the message ([slug=<slug>]); the audit-fork / audit-merge handlers additionally tag failures with [fork-emitted:<timestamp>] so --doctor (v0.4.0 milestone 15) can distinguish "intent recorded, side-effect never landed" from earlier failure modes. For MERGE_DISPATCH_INVOKED, doctor reconciliation matches orphan INVOKED rows to a missing MERGE_DISPATCH_RETURNED or MERGE_DISPATCH_FALLBACK partner via slug + timestamp window (no correlation tag needed because the LLM Task call has no disk artifact to sequence against). appendAuditEntry records an ERROR_LOGGED entry on disk-side-effect failure; doctor reconciles audit drift at observation time.

This is a deliberate departure from the strict audit-first invariant for stage transitions, motivated by the kill-9 / OS-crash window where neither the rollback emit nor ERROR_LOGGED can be guaranteed. The pattern is bounded to the events listed above. STATE_FORKED / STATE_MERGED (milestone 9) deliberately do NOT take this exception — see the previous section for the strict-first rationale (state writes are idempotent, so a failed write surfaces as recoverable drift instead of unrecoverable orphan state). MERGE_DISPATCH_RETURNED / MERGE_DISPATCH_FALLBACK are post-call emits (audit-of-result, not intent — strict-first) and don't take the exception. All other state-mutating commands stay strict-first per the section above.

Forbidden patterns

Don't emit audit events from LLM prose. The following anti-patterns are the reason this refactor exists:

• bun .claude/tools/aidlc-audit.ts append WORKFLOW_STARTED ... as a step in SKILL.md — replaced by the tool emitting it internally
• **Event**: STAGE_COMPLETED markdown block written by a stage file — events only come from appendAuditEntry in a tool or hook
• Freeform ## Artifact Update sections written by hooks — replaced by canonical ARTIFACT_CREATED / ARTIFACT_UPDATED

The public CLI enforces the sharpest slice of this mechanically: append / append-batch refuse the authority-bearing receipts the engine's guards read as authorization evidence (HUMAN_TURN, GATE_APPROVED, GATE_REJECTED, QUESTION_ANSWERED, REVIEW_REQUESTED, REVIEW_COMPLETED, SWARM_STARTED, SWARM_UNIT_CONVERGED, AUTONOMY_MODE_SET, and the four UNIT_* lifecycle receipts — the CLI_PROTECTED_EVENT_TYPES set in aidlc-audit.ts), every field name must match a strict printable single-line label grammar (and Event remains reserved), values have line terminators escaped, and append-raw refuses taxonomy event lines or line-breaking headings. The structured renderer exclusively owns Timestamp and Event, so every block it writes contains exactly one of each; free-form append-raw blocks sit outside that guarantee (they carry the emitter's **Timestamp**: line, no **Event**: line, and a verbatim body). Timestamp remains accepted by generic --field parsing for compatibility, but a supplied value is intentionally ignored; park/unpark and other owning tools do not pass it. Historical shards are not rewritten: block-aware readers need no migration, while flat readers must split on --- and use the first emitter-owned timestamp in each block or deduplicate older duplicate timestamp fields. Owning tools and hooks emit through the library import (appendAuditEntry), which the floor does not touch. Test fixtures that simulate owning emitters set AIDLC_ALLOW_DIRECT_AUDIT_EVENTS=1.

The drift test at tests/integration/t48-audit-event-emitters.test.ts catches drift between this chapter's tables and the code: every event in the tables must have a matching appendAuditEntry(..., "EVENT", ...) call in the declared emitter file, and every emission call site in the codebase must appear in the tables. The test also guards against deleted events being resurrected and against pairing invariants (e.g., handleApprove must emit both GATE_APPROVED and STAGE_COMPLETED).

Same-commit rule

When you change state-machine behavior, update both the code and this chapter in the same commit. The rule catches itself via the drift test, but the cost of fixing drift after the fact (chasing down who owns which event across three files) is much higher than updating one table.

Specifically: - Adding an event → add to VALID_EVENT_TYPES in aidlc-audit.ts, add the emitter, add to the appropriate table above. - Deleting an event → remove from VALID_EVENT_TYPES, remove emitter, remove the row here, grep the codebase for any stale prose or tests. - Renaming an emitter file → update the Emitter column in every table row that points at it.

Known limitations

• Multi-project sessions. Claude Code doesn't fire a hook on cd within a session, so if a user runs /aidlc in project A and then cds to project B, the session hooks won't re-fire against B's audit.md. Session events may not perfectly reflect every workspace switch. This is a Claude Code limitation, not an AI-DLC design flaw.

Related reference

• Orchestrator — how /aidlc --status, session check, and the resume path consume state-machine signals.
• Stage Protocol — the stage-level behavioral contract, including the approval-gate UX that drives [?] / [R] transitions.
• Hooks and Tools — hook lifecycle, CLI tool reference, and the audit-event catalog.
• Testing — how the drift test works and when to run it.