State Tracking and Audit Trail

Each piece of work keeps two committed records that together provide full traceability from intent to production: the state file tracks where you are in the workflow, and the audit trail, a folder of files, 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 initial description is stored beside it in project-description.json as one JSON string, exactly as typed except that anything shaped like a key, token or password is masked (see Keys and passwords you type). 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

Here is part of one, from a Claude Code run on the mvp plan just after Intent Capture was approved (shortened; the file puts a long dash between each stage and its EXECUTE or SKIP, shown here as -):

## Scope Configuration
- **Depth**: Standard
- **Test Strategy**: Minimal
- **Review Override**:
- **Guard Policy**: off (from scope mvp)
- **Sensors**: on (from scope mvp)
- **Learnings**: on (from scope mvp)
- **Summary Confirmation**: on (from scope mvp)
- **Plan Approval**: on (from scope mvp)
- **Collaborators**: off (from scope mvp)

## Phase Progress
- **Initialization**: Verified
- **Ideation**: Active
- **Inception**: Pending
- **Construction**: Pending
- **Operation**: Skipped

## Stage Progress
### IDEATION PHASE
- [x] intent-capture - EXECUTE
- [ ] market-research - SKIP
- [-] feasibility - EXECUTE
- [ ] scope-definition - EXECUTE
...

## Current Status
- **Lifecycle Phase**: IDEATION
- **Current Stage**: feasibility
- **Next Stage**: scope-definition
- **Status**: Running
- **Last Updated**: 2026-10-13T10:43:59Z

If Guard Policy and the retired Change Control both appear with different policy words, status shows strict (from conflicting state lines) until the next next, which keeps one and writes it as the only line: the one the audit trail shows was set last, else the one you set, else the scope's own, else the stricter (a GUARD_POLICY_SET row with Source: command and a Settled field records it). It says nothing when it kept your own last choice, and once otherwise, for example:

This work had two settings for how closely AI-DLC checks changes, and they disagreed. The record does not say which was set last, so AI-DLC keeps the stricter one: it checks everything. You can change it any time.

Memory-held strict still takes precedence and leaves both lines as they are. If both agree, the Guard Policy line is used. Any write of the policy line removes the retired line, leaving one setting.

Construction Verification Command records the project check reused at every Unit/batch checkpoint. A matching current-workflow human approval receipt is required before state set-construction-verification-command writes the field; the field alone never authorizes execution, and generic state set refuses it. The human's Approve / Request Changes reply counts in the chat that asked or in a new one while it is the newest question asked. Only Approve authorizes the receipt; an unrelated reply, Request Changes, or a reply to another question does not. See the recorded-command flow.

Six-state checkboxes

Stage progress uses a six-state checkbox notation:

A stage your plan leaves out never changes box: it stays [ ] with SKIP after its name, like market-research above.

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 : skipped, or jumped past
    InProgress --> Skipped : Cut mid-flight
    Revising --> Skipped : Abandon after rejection
    Awaiting --> Skipped : Forward jump
    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: none: a stage not in the plan stays [ ], marked SKIP when the work is created
• 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 records the active intent's decisions and events for later stages and recovery. AIDLC's tools and hooks write it; reads stay open by any means. The write guard is a guardrail, not a security boundary. See Audit Trail Rules for the owning commands and the read-only query contract.

134-event taxonomy

Events are organized into 27 categories:

What gets logged and when

• Every stage start and completion is logged with STAGE_STARTED and STAGE_COMPLETED events
• Every file the agent writes or edits with its file tools in the intent's record dir or the space's codekb/ (except the audit/ shards themselves) is logged by the write-audit-log hook; a file written by a shell command is not
• 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, and every helper sent is logged when it is sent
• Every error and recovery is logged

How to read the audit log

Each shard is plain Markdown, one block per event. Two from the Intent Capture stage of the run above:

## Stage Start
**Timestamp**: 2026-10-13T10:27:19Z
**Event**: STAGE_STARTED
**Stage**: intent-capture
**Agent**: aidlc-product-agent

---

## Question Answered
**Timestamp**: 2026-10-13T10:34:07Z
**Event**: QUESTION_ANSWERED
**Stage**: intent-capture
**Details**: Q9: One total per SKU
**Person Reply**: One total per SKU

Run aidlc engine audit history for the event timeline as JSON, or add --stage <slug> to review one stage. Each event carries its timestamp, type, and named fields. Results are oldest first; unordered: true marks tied entries with no known order across writers. Free-form notes appear as NOTE entries with their heading and body text. --event NOTE selects notes; --stage excludes them.

A Human Turn entry records that you acted, never your words. To read what you sent in each turn, run aidlc engine audit turns: it joins each turn to the message record this machine keeps for a day, and says when a turn's words are not here.

Run aidlc engine log answers --stage <slug> (add --unit <unit> for a Unit) for paired earlier questions and answers. One reply pairs with every question logged for the menu it answered. Open questions and the rare ambiguous answer (no question before it, or writers tied at one second) are reported apart. Neither command changes files or takes a lock.

When the agent marks one of a question's choices "(Recommended)", the record keeps that choice as Recommended: on the question's Decision Recorded entry when the logged choices carry the mark, and on the Question Replied entry when you answer in Claude Code's or Codex's question box, beside the box's Options and your Reply, so you can see whether you went with it. log answers lists a logged question's Recommended as recommended beside its options and your answer. Entries written before this have no Recommended, and read as they always did.

Keys and passwords you type

The state file, project-description.json and the audit shards are committed with your work, so AI-DLC masks anything shaped like a key, token or password before it writes them: a vendor token (GitHub, GitLab, Slack, Stripe, OpenAI, Anthropic, Google, npm, Hugging Face, an AWS access key), a private key block, a JWT or Bearer token, the password in an address (postgres://app:[masked]@db), and a value set after a secret's name (password=, DB_PASSWORD=, GITHUB_TOKEN:) when the value has a letter and a digit or symbol in it (after a password's name, words joined by -, . or _ count too). A reference such as $DB_PASSWORD stays, and so does a placeholder such as your-api-key-here. The rest of your words stay as you typed them, for example **Person Reply**: Approve, the deploy key is [masked]. Your whole message stays only in aidlc/.aidlc-sessions/, which AI-DLC's .gitignore block keeps out of commits. When your message held one, AI-DLC says so once in the chat: the chat itself still received it, so change the key where it was issued if it is real. Masking goes by shape only, so a secret written another way (my password is hunter2) is kept as typed, and the doctor bundle masks the same shapes and more.

Who decided

When you approve a stage, ask for changes, skip or jump to a stage, switch a check off or on, or let a changed input through, the audit row also records your git name, for example **Git Name**: Jane Doe. It is the name git config user.name gives for this project (the repo's own setting, then your global one), the same name the Unit board shows, so in a team clone each person's rows carry their own name. AI-DLC only reads it: it never sets it, asks for it, or records your email, and with no name in git it records nothing. It says who was at the keyboard as git reports it, not a signature or proof of identity. /aidlc --status names who approved the last completed stage, for example Last Completed: Requirements Analysis (approved by Jane Doe). Which rows carry it is listed under "Git Name" in knowledge/aidlc-shared/audit-format.md in your harness folder.

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. Under Guard Policy strict, an uncovered change or a stale unit blocks all four completion routes and offers that unit's one bounded stale-receipt recovery. A file Git ignores that no unit can claim (neither tracked nor registered in .aidlc-source-paths.json, such as build output or a test run's record) is not an uncovered change, nor is a path that file's exclude list leaves out of the walk, even when the line was written after the stage started (a tool's cache the project does not ignore, a nested repository that is not this project's code); the registry file itself is AI-DLC's own, so no unit claims it. The strict refusal names the three ways through: the unit that made a change lists the path and is reviewed once more, a change nobody meant is undone, or a path that is not source is excluded there. Under relaxed or off, an uncovered change is kept: completion records it once as CHANGE_ACCEPTED and names the files in one line ("These files changed outside any unit's work in Code Generation: ... Kept them."). A stage-entry baseline that is missing on this machine (a fresh clone) skips the check with one line under every Guard Policy; one that is here and does not match still blocks completion under strict.

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.

An AI-DLC update after the review changes only AI-DLC's own files, so it leaves the review current when the receipt's Source Listing is on this machine; a receipt without one is compared by Source Fingerprint as above.

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