State Tracking and Audit Trail

AI-DLC maintains two persistent files that together provide full traceability from intent to production: the state file tracks where you are in the workflow, and the audit trail records every decision, action, and event along the way.

State File (aidlc-state.md)

Each intent has its own state file at aidlc/spaces/<space>/intents/<YYMMDD>-<label>/aidlc-state.md (under the intent's record dir) — the single source of truth for that intent's workflow progress. The engine reads the active intent's state file on every session start to determine what has been completed, what is in progress, and what comes next.

The exact initial description is stored beside it in project-description.json as one JSON string. aidlc-state.md names that committed source and keeps only a safe single-line Project preview, so multiline user input cannot introduce additional state fields. Pre-2.6.115 records without the source marker continue to use the existing Project field as their description; a marked new record whose file is missing or malformed fails source validation instead of silently degrading. JSON decoding preserves the original description even if Git normalizes the sidecar's final line ending.

What it contains

Six-state checkboxes

Stage progress uses a six-state checkbox notation:

Stages transition through [ ] → [-] → [?] → [x] on the happy path. When you reject at the gate, the stage moves to [R] while it's revised, back to [?] when ready, and finally to [x] on approval. /aidlc --status reads the checkbox and tells you who's blocking — "Awaiting your approval on \<stage>" for [?], "Revising \<stage> (revision N of 3)" for [R].

For the canonical state-machine reference (transition tables, audit-event emitters), see Developer Reference: State Machine.

State transitions

stateDiagram-v2
    state "[ ] Not Started" as NotStarted
    state "[-] In Progress" as InProgress
    state "[?] Awaiting Approval" as Awaiting
    state "[R] Revising" as Revising
    state "[x] Completed" as Completed
    state "[S] Skipped" as Skipped

    [*] --> NotStarted
    NotStarted --> InProgress : Stage begins
    InProgress --> Awaiting : Work done, gate opens
    Awaiting --> Completed : You approve
    Awaiting --> Revising : You request changes
    Revising --> Awaiting : Revision done, re-enter gate
    NotStarted --> Skipped : --stage/--phase jump or scope excludes
    InProgress --> Skipped : Cut mid-flight
    Revising --> Skipped : Abandon after rejection
    Completed --> NotStarted : Redo (artifacts deleted)

Normal, revision, skip, redo, and jump flows

• Normal flow: [ ] -> [-] -> [?] -> [x] (stage begins, work completes, gate opens, you approve)
• Revision flow: [?] -> [R] -> [?] -> [x] (you reject, stage is revised, gate re-opens, you approve)
• Scope skip flow: [ ] -> [S] (stage not in scope for this workflow, marked at init)
• Redo flow: [x] or [-] -> [ ] -> [-] (you request redo, artifacts are deleted, stage re-executes)
• Jump flow: [-] at stage A, you request jump to stage B, intervening stages are marked [S]

Audit Trail (audit/)

The audit trail lives in the intent's record dir at aidlc/spaces/<space>/intents/<YYMMDD>-<label>/audit/. It is an append-only event log written as per-clone shards (<host>-<clone>.md): each clone appends only to its own shard, so concurrent appends from sibling worktrees never git-conflict. Readers glob audit/*.md and merge-sort by ISO timestamp to reconstruct the full chronological history of decisions and events.

91-event taxonomy

Events are organized into 22 categories:

What gets logged and when

• Every stage start and completion is logged with STAGE_STARTED and STAGE_COMPLETED events
• Every file write to the intent's record dir (except the audit/ shards themselves) is automatically logged by the write-audit-log hook
• Every approval gate decision (approve, request changes, accept-as-is) is logged
• Every question answer you provide is recorded
• Every subagent completion is logged by the log-subagent hook
• Every error and recovery is logged

How to read the audit log

Each entry follows a structured format with these fields:

• Timestamp — ISO 8601 timestamp
• Event - One of the 91 event types
• Details — Event-specific data (stage name, decision, artifact path, etc.)

Entries are appended chronologically. To review the history of a specific stage, search for its STAGE_STARTED and STAGE_COMPLETED entries and everything in between.

Audit event flow

When a stage executes and produces artifacts, the audit trail captures the full sequence:

sequenceDiagram
    participant O as Orchestrator
    participant E as Engine
    participant S as Stage Execution
    participant H as Audit Hook
    participant A as audit/ shard

    O->>E: Request next directive
    E->>A: Emit STAGE_STARTED
    O->>S: Execute stage work
    S->>S: Write artifact to the intent's record dir
    S->>H: PostToolUse hook fires
    H->>A: Append ARTIFACT_CREATED or ARTIFACT_UPDATED
    S->>O: Stage work complete
    O->>A: Log approval gate options
    O->>O: Present approval gate to user
    O->>E: Report approved or rejected
    E->>A: Emit gate outcome
    E->>A: Emit STAGE_COMPLETED on approval

Source-bound review receipts

Code Generation writes application source outside the intent record, so its terminal per-unit review receipt binds more than markdown artifacts. The reviewed unit's strict source-manifest.json lists created, modified, or deleted source paths; Unit Source Fingerprint binds those claims and manifest bytes. At completion the engine validates each unit newest-first (a newer reviewed claim can own an intentional shared-file integration), then compares the union of fresh claims with the stage-entry source baseline. An uncovered change or a stale unit blocks all four completion routes and offers that unit's one bounded stale-receipt recovery.

The workspace-global Source Fingerprint is normally the outer post-review mutation boundary. One narrow reconciliation makes the documented “revert” recovery real: after any unclaimed baseline change (addition, modification, or deletion) is fully reverted, completion can continue only when the stage baseline is present and valid, every applicable unit still has a fresh modern binding, and the baseline-to-current delta has zero unclaimed paths. Ordinary post-review edits, stale or legacy unit evidence, and any remaining unclaimed path still refuse. Pre-upgrade fieldless receipts or baselines retain documented migration fail-open behavior; missing or corrupt modern evidence fails closed. AIDLC_SKIP_SOURCE_FRESHNESS=1 is the deterministic emergency off-switch and must be present again when consuming a bypass-marked receipt.

How State and Audit Work Together

The state file and audit trail serve complementary purposes:

The orchestrator uses aidlc-state.md as the durable cursor. Team-owned Construction additionally derives Unit cells, receipt floors, gates, and merged rows from the active intent's audit shards; solo routing keeps the state-only cursor behavior. The audit trail also lets you trace every decision from intent through to production.

If the state file is corrupted, you can reconstruct it from the audit trail by reviewing STAGE_STARTED and STAGE_COMPLETED events. See Troubleshooting for repair instructions.

Next Steps

• Session Management — How state is used for session resume
• Artifacts Reference — What gets stored in the intent's record dir
• Troubleshooting — State corruption repair
• Glossary — Definitions for state file, audit trail, checkpoint, compaction