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 created (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 creation seeds the section: Initialization lands Verified (creation 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 creation 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 or its per-unit Construction directories. A codekb stage is stricter: every registered repository directory must contain the full declared produces[] set; single/unrecorded intents use the one resolved codekb directory. 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. The same switch also bypasses the review logger's required-output existence check; without it, a stage-level review of a per-Unit stage requires every authoritative Unit's applicable required outputs. When no authored Unit DAG exists but the current attempt has merged Bolt rows, the stage-level review fingerprint instead enumerates exactly those merged Units. A Bolt merge is proven, not asserted: aidlc-bolt complete --merge emits BOLT_COMPLETED before the state and audit merges run, so a slug-backed (worktree) attempt counts as merged only once a matching later AUDIT_MERGED receipt confirms the merge sequence landed on main; a name-only, non-worktree Bolt's BOLT_COMPLETED remains terminal. A completion still awaiting merge evidence stays on the open path, a slugless completion cannot close a slug-backed attempt, and a later fragment-cleanup BOLT_FAILED cannot erase a confirmed merge. AUDIT_MERGED itself carries no reviewer authority: a same-second row in another audit shard never makes a review request, verdict, or receipt ambiguous. An open Bolt remains on the ordinary stage-level fallback path because its Unit artifacts still live outside the main tree. Merging that Bolt changes the fingerprint domain and intentionally invalidates an earlier stage-level receipt until its exact pending ordinal is rebound with --retry-pending. Per-Unit receipt filtering still recognizes both open and merged Units. A Unit may belong to both sets when an older attempt merged while a newer attempt remains open; merged membership drives gate demand and stage-level fingerprinting, while the union drives receipt filtering.

Reviewer gate guard (issue #551). A reviewer-bearing stage cannot enter AwaitingApproval through gate-start or revise until its configured reviewer has a fresh terminal REVIEW_COMPLETED receipt. The same receipt remains mandatory on all four completion paths. Re-reporting an already-open gate re-runs these guards without writing a duplicate transition. A rejection reported directly from Active moves to Revising without fabricating a STAGE_AWAITING_APPROVAL row. Synthetic transition tests that deliberately isolate another guard may set AIDLC_SKIP_REVIEWER_GATE_GUARD=1; this bypass applies only to gate opening, never to approve, advance, finalize, or complete-workflow. The adjacent summary-confirmation test bypass is AIDLC_SKIP_SUMMARY_CONFIRMATION_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. On mode: pipeline, the same report outcomes and every direct completing transition require an ordered, current-attempt PIPELINE_LINK_COMPLETED receipt for every lead/support link. Multi-repo reverse engineering requires a complete chain per scanned repo; a current-attempt repo-scoped ARTIFACT_REUSED row with Decision=keep exempts a reused repo. Isolated rows carry Workflow: single-stage:<slug> and are accepted only while the complete graph-declared Reverse Engineering artifact set remains valid and the store remains CURRENT; while modify/redo rows do not. A rejection, jump, or later stage start resets the main-workflow evidence, and isolated --single link rows never satisfy it. Bypass with AIDLC_DISABLE_ENSEMBLE_EVIDENCE=1, intended only for recovering a legitimately-run stage whose contribution files or in-flight link receipts were lost.

Source freshness and per-unit attribution (#629/#646/#662). On a workspace_requires stage, every terminal review still carries the workspace- global Source Fingerprint; the newest modern binding is normally the outer post-review-mutation boundary on all four completion routes. Per-unit receipts add Unit Source Fingerprint, which binds the raw bytes of the unit's strict source-manifest.json and the current content of every exact/directory claim. Receipts are evaluated newest-first, so a newer validated claimant may shield an older receipt for an intentional shared path. An uncovered edit, deletion, or new path in an exact/directory claim invalidates only the owning unit and enters that unit's one bounded stale-receipt recovery.

WORKFLOW_STARTED, STAGE_JUMPED, and a workspace_requires STAGE_STARTED record content-addressed source-listing baselines. After every applicable unit has fresh modern evidence, completion compares baseline to the current listing and refuses any changed application-source path outside the fresh claims union. Unit-major Construction always uses the workflow/jump boundary because source work can precede its late STAGE_STARTED. Equal-second cross-shard rows that would decide a boundary or newest claimant fail closed instead of trusting shard filename order.

A rejection resets review and run-floor accounting but never replaces that completion baseline: otherwise any unclaimed path present at rejection would be grandfathered into the next attempt. When the prior attempt has a validated SWARM_SOURCE_MERGED chain, GATE_REJECTED carries only its final Prior Accepted Source Fingerprint. The next attempt's first source merge must start from that aggregate, while completion continues to compare against the original stage-entry baseline.

There is one narrowly bounded reconciliation of the global boundary: if an unclaimed baseline change — addition, modification, or deletion — is fully reverted, completion may proceed only when the effective baseline snapshot is present and valid, every applicable unit still has a fresh modern unit binding, and the baseline-to-current delta contains zero unclaimed paths. This proves that the transient unclaimed change is gone. Any ordinary post-review edit, stale or legacy unit binding, missing evidence, or remaining unclaimed delta still takes the normal global-first refusal path.

The fingerprint and canonical per-path listing come from one bounded filesystem walk, independent of repository metadata and Git executable availability. Ordinary and ignored application bytes, external source-symlink targets, and workspace-roof files remain bound. Framework state, exact sensor caches, VCS metadata, dependency/cache directories or symlinks, and unregistered build/, coverage/, dist/, logs/, target/, and tmp/ directories or symlinks remain outside the source boundary.

Real source beneath a conditional generated-output directory, including binary or extensionless source, can be declared in root .aidlc-source-paths.json:

{"version":1,"paths":["dist/worker.js","build/source"]}

Registered paths are content-bound regardless of encoding and are included in the canonical listing and autonomous swarm Source Commit. Absolute, traversing, framework, sensor-cache, and dependency/cache paths are rejected. Missing registered repositories contribute an explicit marker; unreadable, unstable, over-budget, or malformed boundaries remain unbindable and fail closed.

Migration is deliberate: a pre-upgrade workflow with no baseline skips the unclaimed check, and a fieldless per-unit receipt retains the #629 global policy. A present but unbindable, missing, or corrupt modern baseline/unit snapshot fails closed. AIDLC_SKIP_SOURCE_FRESHNESS=1 bypasses both global and per-unit checks; missing/invalid-manifest receipts explicitly record Unit Source Binding Bypass: true, so the switch must be present again at completion. In a modern Bolt, finalize also verifies the attested base-to- worktree footprint is a subset of the reviewed manifest claims before the settled-swarm stage-level exemption applies.

Swarm footprint verification and immutable Source Commit creation apply the same boundary. Clean-filter raw-byte replacement is restricted to exact filesystem-included regular paths, so excluded generated or framework files cannot re-enter after shaping. New-submodule recovery shares one 30-second cumulative deadline and a 32-proof cap across the entire finalize call, in addition to the per-command, ref-count, refspec-size, recursion, and materialized-checkout bounds. AIDLC_SKIP_SOURCE_FRESHNESS=1 disables the check; a bypassed finalize records Source Freshness Bypass: true, and merge must repeat the same switch.

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. Reviewer-bearing stages persist [R] after that recovered rejection and require a fresh review plus the normal revised report before the gate can reopen. 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 verifies the fresh terminal receipt before accepting the revised report and re-opening the 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

91 events, grouped below into 19 categories (the canonical audit-format.md registry splits the same 91 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

Under Unit Ownership: team, these rows additionally carry Unit, Gate Scope, and Gate Stages. Per-stage approval settles only that (stage, Unit); unit-end approval settles the Unit chain. A Unit-tagged rejection floors lifecycle and review receipts only for that Unit (all Gate Stages for unit-end); legacy Unit-less rows retain stage-global behavior.

User interaction

Unit lifecycle (inline per-unit Construction stages)

Team-owned unit-major runs add a derived ## Unit Progress table to state. The engine rewrites it from these receipts, artifacts, reviews, Unit gate rows, and UNIT_MERGED receipts on each next; it is not an authority and manual cells are ignored. Once a pinned merge transaction or UNIT_MERGED receipt exists, a merged column prevents the per-unit block from settling until every merge-bound row has landed. Claims alone retain the increment-2 projection without this column.

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, rebind, and summarize 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

The sensor dispatcher emits the four SENSOR_* events and doctor emits the paired-coverage GUARDRAIL_LOADED row. Write-fired sensors dispatch from PostToolUse on matching paths. Gate-fired sensors dispatch once per existing declared deliverable before initial, revised, or approve-backstop recovered gate entry. A blocking binding proceeds only on a verified pass; findings, unavailable execution, malformed/mismatched verdicts, and budget overruns refuse. An override requires the logged offered choice, a human turn, the exact answer receipt, and matching --user-input; autonomous mode cannot override. Explicit and discovered artifact paths are canonically confined to the stage produce directories. Blocking declarations on write-fired sensors remain advisory in this release.

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

The swarm taxonomy has seven events. Six emit from the stateless referee aidlc-swarm.ts: prepare captures the exact stage-attempt token, stamps it into worktree creation metadata, and forks the batch; finalize requires that token to remain current, re-verifies every claimed Unit, snapshots its exact declared record artifacts plus bound source manifest, merges those records and AIDLC metadata, and emits convergence/failure, baton, and batch rows. SWARM_SOURCE_MERGED emits later from aidlc-worktree.ts merge, after the immutable reviewed application source lands in main. It correlates durable worktree provenance with the exact current Bolt, batch, stage, and run floor, then links the main checkout from the stage baseline, the prior attempt's accepted rejection fingerprint, or the previous current-attempt aggregate. Selector-free merges recover the creating intent from durable creation authority; explicit mismatches name the required --space/--intent recovery, and authority-path comparison canonicalizes filesystem aliases. Pre-binding fieldless convergence retains historical branch-merge behavior; modern convergence does not advance routing until its source-merge authority exists. The check subcommand remains advisory and emits nothing. The conductor handles invoke-swarm as an orthogonal directive kind beside the stage mode enum; it does not activate the reserved agent-team mode.

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.

SWARM_SOURCE_MERGED is post-result authority, not an audit-of-intent row. If the Git merge commit lands but this row cannot be appended, the tool preserves the worktree and returns [merge-succeeded:<sha>] with a non-retryable remedy. Rerunning would merge source twice and is forbidden; restart the stage attempt, or use AIDLC_SKIP_SOURCE_FRESHNESS=1 only after explicit human approval. If the row did land and only later cleanup failed, rerunning the same aidlc-worktree merge detects that authority and performs cleanup only; it never reapplies source or emits a second authority row.

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 (STAGE_COMPLETED, HUMAN_TURN, GATE_APPROVED, GATE_REJECTED, QUESTION_ANSWERED, REVIEW_REQUESTED, REVIEW_COMPLETED, PIPELINE_LINK_COMPLETED, ARTIFACT_REUSED, SWARM_STARTED, SWARM_UNIT_CONVERGED, AUTONOMY_MODE_SET, UNIT_OWNERSHIP_SET, UNIT_GATE_RHYTHM_SET, UNIT_STARTED, UNIT_PAUSED, UNIT_RESUMED, UNIT_COMPLETED, UNIT_MERGED, and the three DOCUMENT_* provenance events — 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.

Stage result validity projection

A completed checkbox records execution history. It does not prove that the result still matches the runtime artifact instances captured at completion. Execution state and result validity are therefore separate concepts.

Each main-workflow STAGE_COMPLETED event may carry a schema-3 Validation Basis. Runtime resolution remains concrete and instance-aware: the active Bolt DAG expands per-unit artifacts, produces_kinds filters unit kinds, and the artifact-vocabulary filename mapping resolves collision-safe names such as build-test-results -> test-results.md.

The audit receipt remains compact because the current projection is stage-level, not Unit-level. For each receipt-recorded canonical artifact it records the producer, required flag, instance/present counts, a structure hash over resolved path/unit/kind tuples, and a content hash over the corresponding file states.

Before normal next routing, the orchestrator recomputes each tracked basis. A mismatch projects the completed stage as stale. Downstream propagation uses artifact inputs actually recorded by completed consumers, not every possible static optional consumes declaration. A missing optional input therefore creates no edge; if it later appears, the consumer's own aggregate basis changes and becomes stale.

The basis is captured when STAGE_COMPLETED is reported. It does not prove which bytes the stage read while executing. "Observed dependency" means an input recorded in the completion receipt; changes before capture become the baseline, while later changes can be detected.

Schema-2 and earlier receipts remain untracked until normal re-completion. Schema 2 cannot distinguish its former zero-instance resolution from the stage-level zero-Unit resolution, so treating it as advisory avoids reporting unchanged in-flight workflows as stale after an upgrade.

requires_stage is not treated as an invalidation edge because the current v2 schema uses it for both semantic dependency and ordering. An explicit edge kind would be required before it can safely participate in validity propagation.

The projection remains read-only and advisory. next keeps its normal directive kind and adds a machine-readable stage_validity field for stale, revalidation, or unavailable results. Untracked-only histories appear in /aidlc --status rather than every next. The suggested recovery is /aidlc --stage <earliest-affected-stage>, but this release does not enforce it. Schema-1, receipt-less, and capture-failed histories remain untracked/fail-open until a normal re-completion writes schema 2. The scope is AI-DLC Markdown artifact validity; source-code, Git-tree, CI, deployment, and external-system validity require separate ownership and observation contracts.

Receipt lookup starts at the latest WORKFLOW_STARTED event in the selected intent audit. Historical ledgers from releases that supported forced re-init may contain a new boundary from a forced re-init in those releases; completions before that boundary read as untracked and fail open until their stages complete again.

Artifact resolution follows the approved workflow plan for per-Unit stages. When Units Generation is skipped, including express and recomposed zero-Unit plans, validity resolves one stage-level artifact instance under <record>/construction/<stage>/ and does not inspect a Bolt DAG or stale per-Unit directories. When Units Generation executes, normal Bolt DAG expansion and the legacy no-DAG directory fallback remain unchanged. Missing or ambiguous plan state makes receipt capture or inspection unavailable with a non-blocking warning rather than reporting false drift.