# Changelog
All notable changes to this project will be documented in this file.

## [2.11.1] - 2026-10-20

Compatibility: breaking for scripts

AI-DLC 2.11.1 rolls up the user-visible changes merged since 2.11.0: code kept in a git worktree, a nested checkout or a clone now reaches Code Generation's approval; with Guard Policy off a build carries on after the chat compacts; a jump back from the open Code Generation gate goes through on the first ask; a person who pauses the agent is not pushed on; plugins carry their author's own names, share one AI-DLC catalogue that stays put across updates, and compose without Bun on Cursor and Kiro IDE; a project on any release from 2.8.0 refreshes without stopping; and corrections at the plan question, the gates, resume and new chats, Construction, and on every harness. **Upgrade:** run `aidlc update`, then run `aidlc config --yes` in each project to refresh its harness runtime (`aidlc config --harness <name> --yes` for each harness when a project has more than one); open work carries on through the refresh. Manual-copy users replace the complete `runtime/<harness>/` tree from `aidlc-copy-runtime-2.11.1.tar.gz`. One step, only for people who use AI-DLC plugins in Claude Code or Codex: add AI-DLC's plugin catalogue once from its new folder with `/plugin marketplace add <folder>` or `codex plugin marketplace add <folder>` (on a native install the folder the installer prints and `aidlc doctor --verbose` names, `~/.local/share/aidlc/plugins` or `%LOCALAPPDATA%\aidlc\plugins` on Windows; after an update made by 2.11.0's `aidlc update`, run `aidlc use 2.11.1` once to create it; on a copied project, the runtime's `plugins` folder), and once the author of a plugin someone else built rebuilds it, install it under its new name and remove the old `aidlc-<name>@aidlc-plugins` copy that `/aidlc plugin list` names. A plugin added from a 2.11.0 folder keeps working until a later update removes that folder. Scripts that build or install plugins: see the `Breaking for scripts` bullets.

* `aidlc version` reports `2.11.1` on Claude Code, Codex CLI, GitHub Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode.
* Code Generation's approval question now opens when the code lives where the project's own git does not see it: a worktree in a child folder or under `.worktrees/`, a worktree of a repo kept outside the project and placed in a gitignored folder inside it, a clone, a submodule, a monorepo package, a junction or link to a checkout elsewhere, a worktree added after the work started, or code committed before the records. Where the review cannot see the code (a worktree in a harness folder such as `.claude/worktrees/<name>`, outside the project, or on another drive), the question says once `AI-DLC found no source changes under <where it looked>` and the person approves as usual or asks for changes, instead of a refusal with no way on. Under strict or relaxed the agent's first report is refused once with the way on and its next report opens the same question; the refusal stays only where nobody would answer the gate (autonomous Construction, the presence check off, an unattended run).
* With Guard Policy off (the default on every shipped scope but `enterprise`), a chat that compacts mid-build carries on with the build step on record (a write, a command, the brief and the developer handoff) instead of refusing in engine words; a Unit whose repeat review never finished opens its gate on the earlier ready review (under relaxed too); and two Guard Policy lines that disagree, such as one written by a teammate on a release before 2.10.0, are settled to one, with a line only when the record cannot say which was set last.
* At the open Code Generation approval question, asking to go back to an earlier stage, or to redo the stage, goes through on the first ask under every Guard Policy, instead of a refusal in engine words and the question shown again (which on Kiro CLI read as Request Changes and started a new attempt). On GitHub Copilot the first ask is still refused once and the next step carries it, as before.
* A person who pauses the agent in their own words ("hold on", "stop for today") is not pushed on by AI-DLC's end-of-turn line, and the agent never asks whether to continue, pause or take a break, however long the run has been; the person can say stop at any time. A park names where the work stands and the way back: `Paused at <Stage> with everything saved. Pick it back up any time here, or with /aidlc --resume in a new chat.`
* A plugin someone else builds now shows in Claude Code and Codex under the names its author chose: its manifest `name`, in the catalogue named by the new optional `"aidlc": {"marketplace": "<name>"}` field (the plugin's own name when left out), so two teams' plugins install side by side. AI-DLC's own plugins keep `aidlc-<name>@aidlc-plugins` (test-pro stays `aidlc-test-pro@aidlc-plugins`, now at 0.1.1 as its content changed since 2.11.0), and `aidlc plugin validate` and `aidlc plugin build` refuse a catalogue named `aidlc` or starting `aidlc-`, in any letter case. While the old copy and the rebuilt one are both installed, AI-DLC uses the rebuilt one, and `plugin sync`, `plugin list` and doctor name the old copy's remove command (`/plugin uninstall aidlc-<name>@aidlc-plugins`, or `codex plugin remove aidlc-<name>@aidlc-plugins`).
* AI-DLC's own plugins share one `aidlc-plugins` catalogue, added once. On a native install it sits in a folder that stays put across `aidlc update`, `aidlc use` and `aidlc rollback` (`~/.local/share/aidlc/plugins`, under `$XDG_DATA_HOME/aidlc/` when that is set, `%LOCALAPPDATA%\aidlc\plugins` on Windows), so a plugin added from it no longer stops loading two updates later; the installer prints the path (`Plugin marketplace for Claude Code and Codex: <path> (add it once; updates keep it current)`) and `aidlc doctor --verbose` names it under Machine. On Codex a plugin folder is added as a marketplace, with its catalogue under `.agents/plugins/`.
* On Kiro a plugin is dropped with `cp -r <projection>/.kiro <project>/` and lands in `.kiro/aidlc-plugins/<name>/`, so a second plugin never overwrites the first; a plugin dropped before this release keeps working where it is.
* A plugin installed in Cursor or dropped for Kiro IDE now composes at session start on a native install without Bun. A plugin built with 2.11.0 keeps its Bun-only session-start hook, so it still needs Bun on PATH until its author rebuilds it with this release and the person reinstalls it (Cursor) or drops the new projection (Kiro IDE).
* For plugin authors: `aidlc plugin validate` and `aidlc plugin build` work natively on every harness; a team plugin can lead a stage with its base's agent (`aidlc plugin validate --with <base root>` checks it) and run its base's stages by name in a scope's `include_stages`; a team plugin composes after its base and pauses while its base is off; a contribution can add prose to a core persona or require a stage (`adds.requires_stage`); and a build ignores another user's leftover lock folder in `/tmp`.
* Breaking for scripts: `aidlc plugin validate` and `aidlc plugin build` now exit 1 for a plugin whose stage names another plugin's stage or agent (`requires_stage`, `lead_agent`, `support_agents`, `reviewer`) without that plugin in `dependencies`; on 2.11.0 the same plugin validated and built. The error names the fix: add that plugin to `dependencies` next to `"core"` (as `"<base>@^1.2.0"`), or correct the name.
* Breaking for scripts: `aidlc plugin build` of a plugin AI-DLC does not ship names the host plugin by its manifest `name` and its catalogue by `aidlc.marketplace` (the plugin's name when left out), no longer `aidlc-<name>` in `aidlc-plugins`; a script that installs the build's output as `aidlc-<name>@aidlc-plugins` must install `<name>@<catalogue>`.
* Breaking for scripts: a plugin's own folder (`dist/plugins/<name>/<harness>` in a checkout, `plugins/<name>/<harness>` in the copy runtime) no longer carries a `marketplace.json`; a script that runs `/plugin marketplace add` or `codex plugin marketplace add` on that path, as 2.11.0's test-pro README showed, must add the `plugins` folder instead (on a native install, the catalogue folder above). On Codex a folder replaced in place makes `codex plugin list` say `marketplace root does not contain a supported manifest` until that one add.
* Plugins stay composed: an upgrade (sync puts back what it lost), `aidlc config` after a plugin update, two session starts at once, a switch from Kiro CLI to Kiro IDE, and a Windows-line-ending checkout no longer drop a plugin's additions. Turning a plugin or its base off with `plugin select` or `aidlc config` removes what it added, turning it back on says how it comes back, and every line that sends the person to plugin sync names a command that works on their tool, Kiro CLI and opencode included.
* A project on any release from 2.8.0 to 2.11.0, a composed plugin included, refreshes to this one without stopping; an update that changes how a finished stage works never asks to redo that stage; and the line after an update names the refresh step and says open work carries on.
* `aidlc update --channel preview` now reads the releases list in pages, so it keeps working once the list passes 1 MiB. On 2.11.0 itself that command fails with `exceeds the 1048576 byte download limit`; `aidlc update --version <id>` is the way past it.
* `install.sh` and `aidlc uninstall` take an opt-in `--allow-root` (or `AIDLC_ALLOW_ROOT=1`) for containers and CI jobs where root is the only user; without it, and under `sudo`, root is still refused. A project's `.env` file no longer reaches the engine or the tools it starts, and the native engine never runs a project's bunfig preload.
* First-run setup lists the Kiro options as "Kiro CLI (V2)" and "Kiro", with Enter choosing Kiro CLI (V2); a preset you pick is kept when you change the harness and change it back; and AI-DLC's status line is your choice, asked once, with nothing replacing your own setting unasked.
* `aidlc config`: a refresh stops instead of overwriting an agent file you edited to set its model or effort, keeps a team `AGENTS.md` that already mentions AI-DLC (adding AI-DLC's block after it), leaves a non-UTF-8 root file untouched and names it, and never runs the repository's fsmonitor program. A conflict names the exact config command that takes `--force`, carrying a download already agreed to; a project command run from another folder names the project folder or `--project-dir` right after `aidlc`; `aidlc config set|get|list` work at a terminal, a clear of a switch no file records says so, and one undo form is named everywhere; and turning a check back on in a file that does not record it says which file keeps it off.
* `/aidlc --status` names each piece of open work on a clone with nothing selected, counts only the stages you were shown, names the exact Unit step, and reads paused or finished work as such with the way back. Doctor warns when replies are not getting recorded, names a Kiro hook switched off under Agent Hooks, no longer reports a missing git as stale branches, and on Kiro the trust row passes, and a switch to Kiro IDE goes through, with a plugin dropped from 2.11.0.
* The plan question waits for your reply before work starts, also when your message never reached AI-DLC; a change you ask for in the message that raises it is read as your answer; Code Generation completes only from an approved plan; and an AI-DLC update after approval never asks again. While the plan waits, reads, scans, test runs and AI-DLC's own commands (an update you asked for included) still run. The approval step says what a build left out, "build it anyway" works in your own words, and approving a custom plan creates it even when its command carries an empty `--skip` or `--add`.
* At a gate the agent goes on from a recorded review to the approval question instead of stopping; every stage start says which stage of how many; the review block says only what changed since the last review; a review that did not finish says so once; one more check is offered when review passes are used up and the work changed; and the summary confirmation names only the files it creates, with no "why now" line. Skipping a stage at its own question, or while it runs, skips it and names the command that runs it again, and an approval and a skip typed in one message both happen, once each.
* Your words: "2" in a new chat at a Unit or batch checkpoint is Request Changes; "skip Functional Design and approve the rest" approves the rest too; a bare `/aidlc` in a new chat asks again a question you were asked but never answered; a question answered from your words says what it took; a project-type change states the words it came from, and saying it is existing code in the message that started the work is not asked again; and a question logged after your reply says so, instead of saying your answer was lost.
* Two chats and new chats: each piece of work keeps its own selections, so two chats never overwrite each other's picks; parked work in a fresh clone carries on without a second resume; words near finished work report it as finished with the way back; a chat that has not joined the work gets the steps to join it; a verification command question asked in one chat can be answered from a new chat; and your `/aidlc` line decides whether open work picks up or your words start something new.
* Construction: a plan of two or more Units asks once, as Inception ends, who builds them (Just me, or Several teams); a side-by-side batch lands (a conflict in a sibling repository says where and finishes landing) and runs the tests you already approved without asking again; "build them one at a time" builds each Unit from its approved plan; the first team step offers one approval per Unit; every AI-DLC git call runs with your own git setup (hooks, LFS, merge drivers, a file-system monitor) and Units land on the integration branch the team named; a sibling repo can be added or removed mid-work; a reopened plan no longer loops; the verification question names the tests it will not run and why, and the code summary lists tests not executed; `.aidlc-source-paths.json` can exclude a machine-local tree; and package-manager folders such as `node_modules`, plus `.idea`, `.codegraph` and `DerivedData`, stay outside the source boundary.
* Build and Test and the checks: a requirement marked N/A with its reason, or built through its user stories, is no longer reported as unbuilt; traceability follows sub-requirements under their parent; a check that reads a whole stage reports once; on a native install without Bun the project's own TypeScript is type-checked instead of passing silently; a TypeScript ESLint config and any ESLint major version get a real lint verdict; Requirements Analysis cites the intent statement and scope document where they exist; and generated tests build their data from the project's own types and schemas.
* Deployment Execution checks the AWS identity from the agent's own shell before it asks to deploy, when the AWS CLI is installed; a failure asks one question with the error and the fix, and deploys only after the check passes.
* Checks you switch: turning one off applies at once and offers to turn it off everywhere; turning one back on clears your own local override and says so, never changes the team's committed settings file, and says which setting still keeps it off. A missing hand-off, a late source change or a review cap is the agent's own step, not your question, and on Kiro CLI and Kiro IDE a push or a recursive delete asks first instead of being refused.
* Plans and spaces: the plan offer says how big the plan is and lists the other plans, a proposed plan says whether it splits the work into Units, a plan name typed alone asks what the work is for, a new questions file names who would answer each question and keeps each trade's questions together, a new space, or one created before its phase rules shipped, gets them so its first stage starts, and switching spaces writes a git-ignored copy of the method instead of rewriting your tracked includes. The scopes guide shows how to start a small change with `express` or `bugfix` plus a stage, and how to start a plan with learnings and summary confirmation off.
* Claude Code and Codex: `/aidlc --help` is answered by the prompt hook with no command run first, and one hook process runs the checks before a tool call or shell command. On Claude Code the carry-on line shows as Stop hook feedback, not a Stop hook error. On Codex a reply typed again with the same words seconds later in one turn (a second `1` while the turn is closing) is recorded as your reply instead of being dropped as a repeat delivery; a turn the Stop hook keeps holding with no progress is let go at the cap instead of showing the first block again; a side-by-side build starts its workers as Codex subagents without permission asks, an approvals setting of "never" included; the hook replay cache lives in the project, size-bounded; and a project copied from 2.11.0 refreshes with its own tool, leaving `config.toml` untouched.
* GitHub Copilot runs the four guard checks in one hook process, so one permission prompt instead of five; words typed after `/aidlc` reach the work; and a headless `copilot -p` run needs only a trusted folder. Cursor's native setup leaves no AI-DLC file at the project root, and a crashed guard refuses nothing. On Copilot and Cursor, `aidlc config models --check` leaves a shared effort setting to the session, as doctor does. On opencode two chats in one window each act on their own work, the `/aidlc` command carries the whole skill past opencode's 50 KiB cut, a team's `opencode.jsonc` gets AI-DLC's entries, and the only ask is before a recursive delete or a push.
* Kiro CLI: after Kiro's 3.0 upgrade AI-DLC's own commands stay pre-allowed and its agents write only what Kiro CLI 2 permits; the AI-DLC chat and its specialist agents use the MCP servers you add, asking before each call, and config keeps `.kiro/settings/mcp.json`; `aidlc` leads the agent picker; agents start on your saved model; the Kiro CLI guide says how to lower Kiro's helper idle deadline (`api.subagentTimeout`, default 3600 seconds, which AI-DLC does not set) in your own settings when a helper that never starts holds a stage for an hour; and on Windows a word with `& | < > ^` or an apostrophe reaches the engine whole.
* Kiro IDE: one agent's model and effort, and a Unit reviewer that reads only its Unit, apply by default; an MCP lookup runs while the code plan is written; a plan's name typed alone starts its first step on the Default agent; one hook card shows per message, write and command; saying yes really turns Kiro IDE Workflows off; and on Windows a request PowerShell or Command Prompt would alter reaches the engine unchanged, with a Command Prompt setup offered a one-time switch to PowerShell.
* On Windows a Unit approved on another OS stays approved, a Windows-line-ending checkout keeps every approval, a sensor's script stays in the tools folder, and an IDE open during install is told to quit and reopen.
* `--help` on an `aidlc engine` subcommand prints its flags instead of an error.
* The guides: Getting Started is one real run from nothing with every screen captured; the everyday, Core Concepts and CLI Commands pages show what AI-DLC prints today; the install guide says how to go back to an earlier version; and the install pages say Bun and Node.js are not required.

## [2.11.0] - 2026-10-08

AI-DLC 2.11.0 rolls up the user-visible changes merged since 2.10.0, including replies read and kept in the person's own words from any chat, requests carried out at once with the way back, Plan Approval asked by the engine, Construction that keeps finished Unit work when the plan changes, leaner scope defaults, configuration that runs beside open work and keeps the team's own files, far fewer permission prompts, a named step when a tool's hooks never run, and corrections on every harness. **Upgrade:** run `aidlc update`, then run `aidlc config --yes` in each project to refresh its harness runtime (`aidlc config --harness <name> --yes` for each harness when a project has more than one); open work carries on through the refresh. Manual-copy users must replace the complete `runtime/<harness>/` tree from `aidlc-copy-runtime-2.11.0.tar.gz`, which now needs Bun 1.3.8 or newer. Existing intents keep their recorded Guard Policy, sensors, learnings, and summary confirmation; Plan Approval and Collaborators, which they never recorded, follow their scope's new defaults, so outside `enterprise` an in-flight intent runs its remaining stages with the lead agent only unless `/aidlc --collaborators on` is typed.

* `aidlc version` reports `2.11.0` on Claude Code, Codex CLI, GitHub Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode.
* New work starts leaner on every shipped scope except `enterprise`: a change after an approval is said once and the run carries on, with no stood-aside line on every write, and each stage runs with its lead agent only; `/aidlc --collaborators on` brings the support agents back for one piece of work. `/aidlc --plan-approval on|off` sets whether each code plan is shown for approval (only the person turns it off), `express` and `poc` ship with it off, and `bugfix` no longer asks the learnings question or for a summary confirmation. Approval gates and human-turn checks are unchanged.
* Plan Approval is now asked by the engine, which keeps the plan's fingerprint itself. An approved plan is asked about once, even after the chat compacts, the work parks, or the stage rules arrive in parts. While the plan waits only the build waits: a review, a setting, a commit, or another small request still runs and the question stays open. If the approved plan or its test instructions change before the build, the person hears what changed and can say "go back to the approved plan".
* Replies are read in the person's own words at every question (stage gates, summary confirmations, Unit checkpoints, guard questions): "approved", a number, or "looks fine but rename the handler" each do what they say, and every recorded answer keeps what the person wrote. A question can be answered from any chat, picks from a Claude Code or Codex question box are kept as given (one box can answer several questions), a reply already kept is never asked for again, and "How would you like to answer them?" is asked once per piece of work.
* A bare `/aidlc` in a new session carries on with the work in progress, with no Resume / Redo / Jump / Start Fresh menu, and a fresh clone names the committed work and picks it up in one answer. What the person asks for is done at once, with one line naming the way back: `/aidlc --skip <stage>` and `--add <stage>`, a scope change, a Construction setting said in chat ("turn checkpoints off", "build one unit at a time"), and settings typed over parked work. Settings typed with new work reach the work the person picks, a reply answers only the question on screen, and a flag-shaped word inside a request ("add a --version flag") stays part of the request.
* Construction keeps finished work: Units already done stay done across a scope change, a switch between one Unit at a time and stage by stage, checkpoints turned on or off, a jump, or a redo of one Unit's step, and a jump back redoes only what the person named. An approved Unit stays approved on a fresh clone, an interrupted build picks up where it stopped, and the person can approve over a review that did not finish (`Approved. The <Stage> review did not finish.`) unless team memory locks Guard Policy strict. When Units are built one at a time with Unit checkpoints off, one question covers the per-Unit stage approvals due after the last Unit.
* A composed plan now belongs to its piece of work. To keep it as a reusable scope, pick **Approve and save as scope** at the gate or say "save this plan as quick-fix" later. The plan offer is short, with the stage table and scores on request, each listed plan shows the engine's own stage count, a tailored plan keeps the name the gate showed, and a custom plan starts from `classic`'s settings with Guard Policy `off`. A code-findings report is planned on `bugfix` or `security-patch` unless the person names another scope.
* `/aidlc --project-type <greenfield|brownfield>` says whether the work is a new project or existing code; typed mid-workflow, or said in plain words, it scans again and runs Reverse Engineering for existing code, and a new-project folder that gains code before Construction is asked about once. A PDF or Word file the person names is onboarded without asking them to move it, `/aidlc --status` names the project type, depth, other open work, and only the checks someone switched off, Requirements Analysis sweeps each component against a corner-case checklist, and Reverse Engineering leaves .NET `bin/` and `obj/` output unread.
* When a tool runs no AI-DLC hooks, the first message now stops with that tool's one step in its own words (in Codex type `/hooks` and trust all, in VS Code turn on Chat: Use Hooks for the folder, in Kiro CLI type `/agent` and pick aidlc, in Kiro IDE trust the folder and reload the window) instead of approvals going unrecorded; setup and doctor name the same step, and a Copilot chat says when the hooks have never run. AI-DLC's own workflow commands run without a permission prompt or approval card on Claude Code, Cursor, GitHub Copilot in VS Code, Kiro CLI, and Kiro IDE, while commands that change the machine's AI-DLC install ask first. Agents do file work with their file tools, and the new read-only `aidlc engine now`, `aidlc engine log answers --stage <slug>`, and `aidlc engine audit history` replace `date -u` and hand-read audit files.
* Any `aidlc config` run while work is open is now done instead of refused: a refresh, an added harness, a pin, or a settings change prints what changed and its undo, and a refresh ends with `Updated. Your open work (<name>) carries on.` `--download` lets a config command fetch exactly the release a project needs (natively, or `aidlc-copy-runtime-<version>.tar.gz` on a copied project), verifying its checksum and, when `gh` is installed, its attestation. `aidlc config --show` shows every section without changing anything, a refresh lists the files it removed, and config and doctor (`Harness trees on different releases`) name each harness tree on another release with the command that brings it level.
* Refreshes keep the team's own files: `.claude/settings.json` keeps the project's hooks, permissions, and `statusLine`; a Codex refresh changes only AI-DLC's keys in `.codex/config.toml`; `opencode.json` gets only AI-DLC's entries; AI-DLC's part of `.gitignore` is one `# AI-DLC: local working files` block after the team's rules; a clone with Windows line endings no longer reports config conflicts; and a settings file saved with a byte order mark no longer stops `aidlc config`. The copy archive leaves out `.gitignore`, `AGENTS.md`, `opencode.json`, Claude Code's `.mcp.json` (a copy starts with no MCP servers), Copilot's `.vscode/settings.json`, the team's memory files, and `aidlc/active-space`, so copying a newer release over a project keeps them.
* A plain `aidlc update` never installs a release older than the one running: on a stable machine running a newer preview it changes nothing and names both ways on (`aidlc update --channel stable` or `aidlc config --channel preview`). Update checks stay fast with `gh` installed, and release verification uses `github.com` even when `gh` defaults to an Enterprise host. At a terminal, `aidlc uninstall` and `aidlc system versions prune` say what they remove and proceed with no `[y/N]` question; without a terminal they still need `--yes`. On Windows, an extensionless `bin\aidlc` launcher lets Git Bash find `aidlc`, and a machine switched back to 2.10.0 can switch forward again. A lock left by a stopped command clears even when its PID was reused, transaction locking works on mounts without hard links, and Bolt worktrees work in repositories with submodules and past the Windows `MAX_PATH` limit.
* On Kiro, the `kiro-ide` install now serves Kiro IDE 1.x and Kiro CLI's v3 engine from one `.kiro/` tree and needs Kiro IDE 1.1.70 or newer, or Kiro CLI 2.24.1 or newer (the `kiro` install still needs Kiro CLI 2.6 or newer); `aidlc config --harness kiro-ide` (or `--harness kiro`) switches a Kiro project between the two installs in place. On Kiro CLI, setup asks for the session model and saves it with the preset's effort in your personal Kiro settings (`aidlc config models --session-model <id>` sets it without prompts), `/aidlc --doctor`, `--version`, and `--help` work on a native install, and a reply typed to another agent names `/agent` and aidlc as the way back. On Kiro IDE, the first run walks through trusting the folder, reloading the window, and choosing the aidlc agent, a bare `/aidlc` that Kiro's menu turns into a specialist still starts AI-DLC, AI-DLC's own commands run with no approval card, and hook cards drop to one before a tool call and one after a shell command, none for a read.
* Codex CLI no longer warns "Under-development features enabled" at every start; setup, doctor, and the hooks-off stop name Codex's own trust step (type `/hooks`, press `t` to trust all, then Esc), and the hook trust AI-DLC seeds now matches what Codex checks. Replies and refusals name `$aidlc` instead of `/aidlc`, a question box that runs out never answers for the person, and in a project shared with another tool Codex uses its own install. On opencode, setup and refreshes add only AI-DLC's entries to the team's `opencode.json`, the end-of-turn nudge and the `/aidlc` command text no longer show in the chat as the person's words, a rejected command ends the turn, and a pasted request with quotes or line breaks starts the work on every shell.
* On GitHub Copilot, AI-DLC's own commands run without an Allow click in VS Code, every step fits VS Code's 20,000-character terminal result, a Windows project carries on across VS Code's two drive-letter spellings, the chat moves on after an approval, and stage runners start only when the person types them. Cursor never throws away the person's prompt, says once which work a chat is on, says when a project is outside a git repository, and keeps background agents out of the foreground workflow. On Claude Code, the generated stage and scope runners start only when typed, and a new chat now gets the state of the work and the offer to rejoin it at session start.
* Long runs carry less: on Claude Code, Codex CLI, Kiro CLI, Kiro IDE, and opencode a step names the rules the chat already holds instead of sending them again, each harness ships only its own tool instructions, and Code Generation no longer runs the advisory linter and type-check sensors after every generated file (type-check still runs at Build and Test). Reviews are refused less often: the engine keeps each stage's findings list, so a decided finding is never reworded or asked about again, an empty placeholder row or a stray `##` heading no longer forces a second review, and the traceability sensor stops failing per-Unit stages in plans with no Units.
* Changed default: Guard Policy is `off` on every shipped scope except `enterprise` (`security-patch` and `infra` were `strict`, the others `relaxed`); a team memory holding `Mode: strict` still wins.
* Changed default: the new `collaborators` setting is `off` on every shipped scope except `enterprise`, so each stage runs with its lead agent only unless `/aidlc --collaborators on` is typed.
* Breaking for scripts: `aidlc engine testing-posture fingerprint --reapprove` is retired and fails with a line that says to run `next`; the engine asks for Plan Approval again when the plan changed.
* Breaking for scripts: a composed plan writes no scope file; `aidlc engine scope save --name <name>` writes one when the person asks to keep the plan.
* Breaking for scripts: on Windows, `install.ps1` in a "Run as administrator" window under UAC warns and asks instead of refusing, a non-interactive run there stops unless it passes `-Yes`, a full-token session (the built-in Administrator, or UAC off) installs with no warning, and `AIDLC_ALLOW_ADMIN_INSTALL` is no longer read.

## [2.10.0] - 2026-09-24

AI-DLC 2.10.0 rolls up the user-visible changes merged since 2.9.0, including conversation-aware AIDA review workflows, stronger human authority and recovery across Construction, multi-harness project coexistence, and reliability corrections across providers, worktrees, hooks, sensors, and stage routing. **Upgrade:** run `aidlc update`, then run `aidlc config --yes` in each project to refresh its harness runtime. Manual-copy users must replace the complete `runtime/<harness>/` tree from `aidlc-copy-runtime-2.10.0.tar.gz`.

* `aidlc version` reports `2.10.0` on Claude Code, Codex CLI, GitHub Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode.
* The AIDA pull-request workflow now supports conversation-aware multi-model review, security evidence, incremental lens scopes, a findings ledger, maintainer commands, severity-driven next actions, and deterministic publication validation. Issue analysis gains intent and direction review with repository labels and operator-facing summaries.
* Construction review now occurs at verified Unit and batch checkpoints. Human-held gates and agent execution boundaries are enforced more consistently, while recovery messages identify an executable next step across workflow states.
* Multiple non-colliding harnesses can coexist in one project. Shared onboarding separates harness-neutral guidance from native setup, and configuration keeps the current provider unless Amazon Bedrock is explicitly selected.
* Bolt branches, refs, and worktrees are scoped by intent; parked attempts restore byte-exactly; Construction and CodeKB resolve the correct project identity from linked Git worktrees.
* Hooks and stage tooling correct native dispatch, Kiro IDE delegation and Windows path handling, reviewer-dispatch accounting, summary-question discovery, gate reply parsing, claim-source matching, and persisted scope composition.
* Retired `--init` and `--force` flags are consumed instead of becoming intent text, unknown intent-create positionals are rejected, and common refusal paths now name accepted values or a concrete recovery action.
* Stable release publication no longer requires a separate successful Full Suite evidence artifact for the tagged commit. Tag/source validation, deterministic packaging, static checks, native smoke coverage, cross-platform builds, lifecycle installation tests, checksums, provenance attestation, and release-candidate verification remain required.

## [2.9.0] - 2026-09-15

AI-DLC 2.9.0 rolls up the user-visible changes merged since 2.8.2, including the Classic scope v1 ceremony model, commit provenance, intent archiving, on-demand Construction autonomy, review-loop corrections, and the native preview release channel. **Upgrade:** run `aidlc update`, then run `aidlc config --yes` in each project to refresh its harness runtime. Manual-copy users must replace the complete `runtime/<harness>/` tree from `aidlc-copy-runtime-2.9.0.tar.gz`. Existing in-flight Classic intents keep their recorded stage graph; the new ceremony defaults apply immediately where noted below.

* `aidlc version` reports `2.9.0` on Claude Code, Codex CLI, GitHub Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode.
* New Classic intents use the 18-stage v1 flow through Build and Test, with one approval per stage, one advisory review pass where configured, sensors and learnings enabled, and summary confirmation disabled. Existing Classic intents keep their recorded graph; use the `workshop` scope when the previous Classic graph with CI Pipeline and Operation stages is required.
* Ceremony is scope-owned and can be changed per intent with `--sensors`, `--learnings`, and `--summary-confirmation`. `aidlc engine config set` applies depth, testing, review, change-control, and ceremony settings as one transaction. Breaking for scripts: the standalone `aidlc-utility.ts change-control` route is removed, and unknown `config-change` flags now fail instead of being ignored.
* `aidlc config` now resolves provider choices per harness. Kiro CLI and Kiro IDE need no provider answer: model access comes with Kiro, so the first-run wizard and `aidlc config providers` state that and ask nothing, provider flags are refused there, and a provider record left by an earlier build is ignored (`aidlc config providers --reset --yes` clears it). The `aws-mcp` region in `.kiro/settings/mcp.json` is kept as the project has it across refreshes. Other harnesses offer Amazon Bedrock or `unchanged`, which keeps the current provider. The `balanced` preset now records medium deciding, reviewing, and writing-up effort.
* `aidlc engine orchestrate wait` provides a bounded read-only wait for collaborators, artifacts, or reviews. Record-level engine files now live under `<record>/.aidlc-engine/`; existing records remain readable through legacy-path fallbacks.
* `/aidlc intent archive <name>` retires an unfinished intent without deleting its record or audit trail. `/aidlc intent unarchive <name>` restores it, and `intent list --all` includes archived intents.
* `aidlc attest resolve` maps a commit or diff range to reviewed Units and reports `verified`, `drifted`, `unattested`, `unverifiable`, `indeterminate`, or `excluded`. `aidlc attest anchor` records commit pointers in the audit trail. Reviews created before 2.9.0 have no committed source evidence and report `unverifiable` until the next per-Unit review.
* Construction autonomy can be granted or revoked on demand. The choice persists in older records that did not already contain the state field, while the first Construction approval, Code Generation Plan Approval, and failure stops remain human-owned.
* Advisory review retries now use the engine's current ordinal after a rejected gate, avoiding false `REVIEW_BUDGET_EXHAUSTED` dead ends. Review bookkeeping stays in review records and audit data instead of becoming artifact content or new reviewer findings.
* Kiro IDE read tools remain available during Code Generation Plan Approval recovery while write, shell, MCP, and delegated mutation paths stay guarded.
* Stable and preview release packaging now separates the native `aidlc-runtime-2.9.0.tar.gz` asset from the Bun-based `aidlc-copy-runtime-2.9.0.tar.gz` manual-copy asset. Versioned installers install the release that carries them, including previews, and multiple changed `main` commits can publish previews on the same UTC date.
* Repository maintainers can run the adversarial AI pull-request review workflow for same-repository PRs, with prompt-injection, security, and project-aligned review passes plus deterministic publication validation.

## [2.8.2] - 2026-09-10

Preserve summary confirmations when an Assumption Confirmation section is appended with a decorative divider, and improve review-findings table diagnostics so malformed rows report their cell count and expected column order without guessing which column was omitted. The intended development release version is 2.8.2. **Upgrade:** `aidlc update`, or `install.sh --version 2.8.2` / `install.ps1 -Version 2.8.2`. A summary receipt recorded before this fix over a body that already contained the newly excluded divider may need one fresh confirmation after upgrading; no other migration is required.

* Short review-findings rows show the expected columns and, when applicable, suggest checking earlier cells for a missing value or `|` separator. Review completion remains refused until the row is corrected. Closes #1076.
* Review-findings rows with surplus cells report the extra count. Well-formed rows, including escaped pipes and explicit blank cells, retain their existing behavior.
* `aidlc version` reports `2.8.2`; the unpublished `2.8.6` development version is superseded.
* Appending `## Assumption Confirmation` after a confirmed summary with an adjacent, blank-delimited `---`, `***`, or `___` no longer causes `SUMMARY_CONTENT_STALE` during stage completion. Code examples before the assumption heading and follow-up answers remain covered by the receipt, so substantive edits still require confirmation. Closes #1074.
* Content appended under a `## ` heading is separated from the following `## ` heading by a blank line, keeping method files well-formed. Closes #1075.

* `aidlc-state.ts unit start|pause|resume` refuses while the engine routes the stage as a wave, leaves state and audit unchanged, and directs callers to `unit complete --wave`. Closes #1071.
* `aidlc-state.ts set-construction-iteration unit-major` leaves the remaining units completable through the serial lifecycle even when a revised stage already has wave completion receipts.

## [2.8.6] - 2026-09-09

**Superseded development entry:** No 2.8.6 release was published. The intended release version is 2.8.2, documented above; this entry is retained as development history.

Fix a markdown-hygiene defect in the shared section writer: `appendUnderHeading` inserted new content flush against the following `## ` heading, so a bullet written under a section (for example a self-learning entry under `## Decided` in `project.md`) abutted the next heading with no separating blank line. The engine re-reads `project.md` every stage and the file is human-editable, so the malformed markdown could misgroup for a re-reading model or a stricter markdown tool. **Upgrade:** `aidlc update`, or `install.sh --version 2.8.6` / `install.ps1 -Version 2.8.6`. No migration is required; existing files are corrected the next time content is appended to an affected section.

* Content appended under a `## ` heading is now separated from the following `## ` heading by exactly one blank line, keeping method files (`memory/project.md`, `project-guardrails.md`) well-formed. The terminal end-of-file append is unchanged — no spurious trailing blank line is added. Closes #1075.

## [2.8.1] - 2026-09-08

Fix defects found while exercising the 2.8.0 native install: the guided `aidlc config` setup cancelled itself when Enter was pressed to accept a default, `aidlc update` on an already-current install failed its integrity check under a normal shell umask, and every native GitHub Copilot and Cursor hook was dead because the 2.8.0 packager projected those adapters onto the one-argument core-hook route. **Upgrade:** `aidlc update`, or `install.sh --version 2.8.1` / `install.ps1 -Version 2.8.1`. Copilot and Cursor projects configured by 2.8.0 work as soon as the binary is updated: their existing `aidlc engine hook <harness>-adapter ...` wiring is accepted, and the 2.8.0 Copilot adapter still installed in the project (whose core-hook calls are the bare `aidlc hook <name>`) is accepted too. `aidlc config` in the project then rewrites the wiring to the canonical `aidlc engine adapter <harness> ...` spelling and installs the current adapter — Cursor's merged `.cursor/hooks.json` collapses every earlier AI-DLC spelling of an entry (bun-era and 2.8.0) into the one shipped entry instead of leaving duplicates that keep executing, and Copilot's `.github/hooks/aidlc.json` is regenerated.

* Pressing Enter at a bracketed default in the first-run `aidlc config` wizard (harness picker, provider, region, preset, plugins, MCP, record layer, and the final `Apply? [Y/n]` gate) now accepts the default as advertised instead of printing `Nothing written.` and exiting 2. Closing stdin (Ctrl-D) still cancels.
* `aidlc update` on an install that is already at the latest release now reports `You're on the latest version of aidlc (X.Y.Z).` regardless of the caller's umask; previously it failed with `existing X.Y.Z runtime does not match the verified release` (exit 4) unless the shell umask was `077`. Same-release identity is now decided by path set and content; the installed tree's modes are still enforced against its own recorded integrity baseline, so trees installed by 2.8.0 under any umask keep working. `aidlc update --dry-run` on a current install says so instead of `Would update aidlc from X to X.`
* `aidlc doctor` no longer tells you to copy the workspace shell from `dist/<harness>/`; the remediation is `aidlc config`.
* README: removed the pre-2.8.0 note that told users to install from a source checkout until native assets shipped.
* GitHub Copilot hooks no longer fail on every event with `aidlc: undefined is not an object (evaluating 'input.length')`; the adapter's delegated audit, sensor, guard, state, and Stop hooks now run through `aidlc engine hook <name>` under the native binary.
* Cursor IDE `failClosed` `preToolUse` hooks now emit `{"permission":"allow"}` on allowed tools instead of returning no output (`Hook ... returned no output`) and blocking every tool call; deny decisions continue to emit Cursor permission-deny JSON.
* Native hook wiring dispatches through `aidlc engine adapter copilot <target>` and `aidlc engine adapter cursor <target>`, preserving each adapter's target and stdin payload. Closes #1061 and #1058.

## [2.8.0] - 2026-09-08

AI-DLC 2.8.0 consolidates the 2.7.x release cycle into a new minor baseline without changing runtime behavior from 2.7.2. **Upgrade:** use `install.sh --version 2.8.0`, `install.ps1 -Version 2.8.0`, or replace a manual copy with `runtime/<harness>/` from `aidlc-runtime-2.8.0.tar.gz`. Existing 2.7.2 workflow records require no migration. Upgrades from earlier releases must still apply every intervening **Upgrade**, **Breaking**, and migration note below.

* `aidlc version` now reports `2.8.0` on Claude Code, Codex CLI, GitHub Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode.
* Solo Code Generation includes the 2.7.1 Plan Approval deadlock fix, so the Stop hook no longer invalidates approval authority at turn boundaries.
* Native installers and release archives include the 2.7.2 tag-bound provenance and verification flow; release assets use the `aidlc-runtime-X.Y.Z.tar.gz` naming contract.
* Breaking changes for CI/scripts: none beyond selecting the new `2.8.0` version and asset name.

## [2.7.2] - 2026-09-07

Bind native releases to the version tag that triggered them and include that version in the runtime archive name. **Upgrade:** use `install.sh --version 2.7.2`, `install.ps1 -Version 2.7.2`, or replace a manual copy with `runtime/<harness>/` from `aidlc-runtime-2.7.2.tar.gz`.

* Pushing a `vX.Y.Z` tag now starts the release workflow. The workflow rejects a tag that does not match `AIDLC_VERSION`, does not point to its checked-out commit, or does not belong to `main`.
* Release manifests and provenance now bind to `refs/tags/vX.Y.Z` instead of `refs/heads/main`.
* The runtime asset is now named `aidlc-runtime-X.Y.Z.tar.gz`, and the README documents how to use it as the release equivalent of a generated `dist/<harness>/` directory.
* GitHub CLI is optional for native installs. Compatible versions verify the signed release attestation; missing or older versions continue with source identity checks and SHA-256 verification, while online downloads remain HTTPS-only.

## [2.7.1] - 2026-09-01

Fix a Plan Approval deadlock that made Code Generation unreachable on solo (non-team) workflows. The Stop hook's read-only `next` probe published the durable active-directive marker on every turn boundary, which bumped the Code Generation authority revision and reset the plan-approval runtime, so the approval challenge minted while answering "Approve Plan" was destroyed before its receipt could be written. The probe no longer publishes that marker for any workflow, matching the read-only contract it already advertised. **Upgrade:** replace the `dist/<harness>/` tree; no workflow state migration is required. Closes #995.

* Answering **Approve Plan** on a solo workflow now yields a stable approval receipt, so Code Generation starts instead of refusing every developer dispatch as "not currently approved".
* `AIDLC_DISABLE_PLAN_APPROVAL_GUARD=1` and driving the workflow as team-owned are no longer needed as workarounds for this deadlock.

## [2.7.0] - 2026-09-01

AI-DLC 2.7.0 consolidates the 2.6.x release cycle into a new minor baseline without changing runtime behavior from 2.6.124. **Upgrade:** replace the complete `dist/<harness>/` tree in one quiescent operation, then run `/aidlc plugin sync` for every installed plugin. Existing 2.6.124 workflow records require no migration. Before replacing an older shell, finish and archive every workflow created before 2.6.1; the new shell rejects that stale state before `--new-intent` can create fresh work. Upgrades from any release before 2.6.124 must also apply every intervening **Upgrade**, **Breaking**, and migration note below; this roll-up does not replace those one-time actions.

* The lifecycle now has 33 stages: Application Design became Domain Design, Contract Design was added, and the Domain, Functional, and Infrastructure Design outputs were consolidated. Consumers of the retired artifact names must use `components.md`, `contract-summary.md`, `entities.md`, `rules.md`, `functional-spec.md`, and `infrastructure-specification.md`; a merge-copy upgrade must also remove the stale `skills/aidlc-application-design/` runner.
* Classic and Express are first-class scopes, and Classic is the implicit default. Set `AWS_AIDLC_DEFAULT_SCOPE=feature` to retain the previous full-lifecycle default.
* Human gates, plan approval, review freezes, and source-bound reviewer receipts now use deterministic authority checks. Structured-question protocol guidance requires self-explanatory prompts and reuse of answers already recorded in the current workflow. Every custom or plugin stage that declares `reviewer:` must add `review_artifact:` naming one required Markdown output from `produces[]`; for per-Unit stages that target must cover every applicable Unit kind.
* Construction resolves the team's affirmed Testing Posture or its documented fallback, supports bounded Build and Test loop-back, and binds review authority to Git and non-Git source state. Autonomous mode skips the remaining stage gates under its final-batch contract, while team-owned Units can converge from independent clones or sibling worktrees through a pinned human-gated merge.
* Reverse Engineering and CodeKB require complete current-attempt evidence and support generation-checked focused rescans that merge newly analyzed areas without replacing unrelated knowledge.
* Intent Capture and Requirements Analysis can ingest bounded project documents and existing requirements through a separate trust-marked document-input path.
* Plugin workflows gained selection-aware composition and doctor checks plus offline create, validate, build, and compose-test tooling. Engine replacement restores the stock graph, so `/aidlc plugin sync` is required after every upgrade; automation must treat exit 1 as an incomplete plugin installation when configured roots are unusable.
* Claude Code, Codex CLI, GitHub Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode now share stronger session binding, single-use continuation, hook diagnostics, human-presence checks, and delegated-agent attribution. Any unattended driver that submits prompts without a person present must set `AIDLC_UNATTENDED=1`. Codex users must run `bun scripts/package.ts codex trust --project <absolute-project-path>`, replace existing entries for those hook paths, and start a fresh Codex session. Claude Code users must approve project hooks through `/hooks` and fully restart; a reported `disableAllHooks` setting must be removed or overridden in an editable layer, while `allowManagedHooksOnly` requires an administrator policy change.
* Integrations that consume adaptive-composer proposals must rename `birthDescription` to `creationDescription`; scripts that consume the retired design artifact names must migrate before reading 2.7.0 outputs.

## [2.6.124] - 2026-08-28

Stop committing machine-local absolute paths in `aidlc-state.md`. The `Project Root` and `Worktree Path` state fields are now written in project-relative form (`.` for the root; a `relative(projectDir, worktreePath)` breadcrumb for a worktree), so a state file shared across machines or checkouts no longer carries a host-specific absolute path. Closes #937.

**Upgrade / scope:** this changes only what is written **from now on** — newly created or next-updated state records. Re-copying `dist/<harness>/` refreshes the tools but does **not** rewrite any existing `aidlc/**/aidlc-state.md` in a project; an existing state file keeps its previous absolute `Project Root` / `Worktree Path` until the engine next writes those fields in the normal course of a run. No migration is performed and none is required: both fields are re-derived at runtime (`projectRootFor` walks up to the real `aidlc/` dir; the committed `Project Root` is an unreached fallback and `Worktree Path` is a decorative breadcrumb), so a stale absolute value is inert until it is overwritten.

* `Project Root` template + writer emit project-relative `.` instead of an absolute `${projectDir}`.
* `Worktree Path` writer emits `relative(projectDir, worktreePath)` (forward-slashed), matching the audit log's existing relative form.
* Regression coverage: `t78` pins a forked worktree's `Worktree Path` to the project-relative `.aidlc/worktrees/bolt-<slug>` (never an absolute path); `t70` and the `t152` Windows-portability guard pin `Project Root` = `.`.

## [2.6.123] - 2026-08-28

Cursor now preserves delegated-agent attribution and reviewer-state integrity across POSIX and Windows path dialects, shell wrappers, Git configuration surfaces, filesystem traversal, and executable lookup changes. **Upgrade:** re-copy `dist/cursor/` into the project so the updated Cursor adapter, shared review-freeze parser, and version metadata replace the vulnerable hooks.

* Deny delegated evaluators, general-purpose interpreters, project-local or path-qualified executables, scripts, unknown command surfaces, BusyBox/Toybox execution applets, and allowlisted command names reached through altered `PATH`, `PATHEXT`, or environment-clearing lookup state.
* Protect every attributed delegated agent with an independent active-delegation witness and fail closed when either attribution store becomes unavailable, preserving nested-Task denial after attempted state removal.
* Resolve bare ancestors and cross-platform path aliases for traversal and mutation commands, including `find`, PowerShell/CMD operations, `rsync`, and data-driven `xargs` mutators whose input targets cannot be inspected; read-only data-driven commands and concrete safe mutations remain available.
* Canonicalize symlink, junction, device, trailing-dot/space, Git-Bash drive, native Windows, mixed-separator, UNC, home, wildcard, and 8.3 path forms before protected-state comparison.
* Carry every reachable shell working directory through compound commands into Git safety inspection, retaining fail-closed behavior across failures, conditionals, pipelines, backgrounds, and subshells.

## [2.6.122] - 2026-08-27

Code Generation source-freshness receipts now bind supported non-Git and missing-Git workspaces without weakening per-Unit attribution or autonomous swarm Source Commits. **Upgrade:** refresh your `dist/<harness>/` shell. In-flight `workspace_requires` reviews from earlier versions must be reviewed once more before completion because the source identity format changed.

* The source boundary is one bounded filesystem identity and canonical per-path listing, so unchanged source remains stable when repository metadata or the Git executable appears or disappears. Ordinary and ignored application bytes, external source-symlink targets, workspace-roof files, and registered binary or extensionless source are covered; framework state, VCS metadata, dependency/cache paths, and unregistered generated-output directories remain excluded.
* Real source under `build/`, `coverage/`, `dist/`, `logs/`, `target/`, or `tmp/` can be declared in root `.aidlc-source-paths.json` with schema `{"version":1,"paths":[...]}`. Invalid, unreadable, unstable, or over-budget boundaries record `unbindable` and fail closed.
* Autonomous swarm snapshots use that exact boundary for footprint verification and immutable Source Commits. Clean-filter raw-byte rewriting is restricted to filesystem-included regular paths, commit reconstruction reads immutable tree/blob bytes without checkout filters, bound merges refuse configured smudge/process filters before target mutation, external symlink targets that a Git tree cannot represent are rejected before source authority is minted, and registered generated source still carries the reviewed raw bytes.
* Initialized nested repositories and submodules resolve their checked-out commit directly from bounded Git metadata, so source identity remains stable when the Git executable is unavailable and malformed metadata fails closed without a process crash.
* New-submodule recovery shares one 30-second cumulative deadline and a 32-proof cap across the full `finalize` call, while retaining the existing per-command, advertised-ref, refspec-size, recursion, and materialized-checkout bounds.

## [2.6.121] - 2026-08-27

Reviewer receipts now bind one explicit review artifact, every dispatched artifact byte, and workspace source before dispatch, then validate the complete reviewer-owned appendix from one stable completion snapshot. Artifact snapshots reject filesystem aliases outside the workflow record or CodeKB boundary. **Upgrade:** refresh your complete `dist/<harness>/` shell. For every custom or plugin stage declaring `reviewer:`, add `review_artifact:` selecting one required Markdown entry from `produces[]`; for per-Unit stages it must apply to every relevant Unit kind. Composition and graph compilation reject reviewer stages that are not migrated.

* Reviewer-bearing stages declare `review_artifact`, a required Markdown output that remains applicable across the stage's Unit kinds; plugin-added outputs and no-DAG directory order cannot silently redefine ownership.
* `REVIEW_REQUESTED` captures stable single-link file identities, exact artifact bytes, the append boundary, and request-time workspace source. When an old review appendix exists, it also returns a per-request challenge for the replacement review. Symlinks, hardlinks, and paths escaping the active record or CodeKB root fail closed.
* `--retry-pending` reuses the original artifact, source binding, and request challenge instead of rebaselining current bytes. Recovery requests record whether artifact, source, or both kinds of staleness opened the scoped write suspension, so restoring that cause closes the window. Valid field-light legacy chains get one audited `Upgrade: legacy-request`; malformed request or completion rows carry no authority.
* `REVIEW_COMPLETED` accepts only blank separators plus one terminal canonical `## Review` section whose rendered Verdict, Reviewer, Iteration, and conditional Request Challenge fields match the request. A section whose bytes already existed when `REVIEW_REQUESTED` was recorded — including one surviving an attempt reset with the same reviewer, iteration, and verdict — must be removed and replaced; neither unrelated prose nor a one-byte mutation can mint fresh reviewer authority.

## [2.6.120] - 2026-08-27

Focused Reverse Engineering rescans now merge their newly analyzed area into the shared CodeKB instead of replacing unrelated knowledge, with generation-checked all-artifact publication so concurrent intents cannot silently lose each other's scans or label preserved stale prose as current. Full rescans still replace all nine artifacts; stale or unverified prior coverage is preserved as prose and demoted to shallow when it cannot be reverified. **Upgrade:** re-copy your `dist/<harness>/` shell so the updated utility, stage, and artifact guidance are installed.

* A focused rescan reads the existing nine artifacts before synthesis, extends sections for the new area, and preserves prior sections outside it.
* Verified-current focused merges record the union of prior and new analyzed paths/components; stale or unverified merges record the new verified area and demote prior analyzed paths to `shallow.paths`.
* `codekb-snapshot` binds a scan to the exact shared-store generation and source bytes; `codekb-publish` validates a complete nine-file candidate under a space+repo lock and refuses `CODEKB_STORE_CHANGED`, `CODEKB_SOURCE_CHANGED`, or `CODEKB_CANDIDATE_STALE` instead of overwriting. Crash recovery validates every transaction and store path component from the real project root and refuses redirected ancestors before any rename or recursive cleanup.
* The scope comparison remains the deterministic backstop: `COVERS` confirms retained verified coverage, while `NARROWER` identifies paths/components no longer claimed as verified deep coverage even though focused-merge prose was preserved.

## [2.6.119] - 2026-08-27

Stage definitions now carry compact Learn and Sensors compartments while their shared behavior lives once in the always-loaded stage protocol, reducing repeated prompt context without changing approval gates, learning capture, or sensor enforcement. **Upgrade:** refresh your `dist/<harness>/` shell so every generated stage and the shared protocol are updated together.

* All gated stages point their Learn compartment to the §13 engine-created, output-only diary, question, and persistence contract; bootstrap initialization stages retain their no-gate exception.
* Sensors compartments now mirror frontmatter through concise `Imports:` and `Upstream targets:` summaries while preserving stage-specific validation and intentional-omission notes.
* `stage-protocol.md` §14 defines shared fire timing, advisory and blocking severity, failure reporting, required-section defaults, and upstream-coverage behavior, and redundant per-stage protocol reminders are removed.

## [2.6.118] - 2026-08-27

Zero-Unit Code Generation now uses its documented stage-level record as a first-class Plan Approval authority, and inline generation cannot bypass the approval enforced on delegated workers. Workspace aliases retain the same trusted planning operations without weakening child-symlink rejection. **Upgrade:** refresh your `dist/<harness>/` shell so the updated stage, testing-posture tool, plan-approval hook, and mutation-surface registrations are installed together.

* `aidlc-testing-posture.ts fingerprint`, `verify`, and `begin` accept the stage-level Code Generation target while preserving per-Unit targets and bind approval to the active intent, directive epoch, source floor, plan, instructions, and Testing Contract.
* Protected, gitignored challenge, response, and receipt state authorizes Code Generation; the Markdown `PLAN_APPROVAL_RECORDED` event remains provenance rather than authority.
* Write, edit, patch, shell, interpreter, build-tool, and symlink or junction mutation paths refuse until approval, while exact installed `tools/aidlc-*.ts` invocations and writes inside the active Code Generation record remain available through aliased workspace roots.
* Code Generation publication and resume paths preserve or rotate the source-bound authority under the active-directive and audit locks, including swarm and legacy Kiro IDE flows.

## [2.6.117] - 2026-08-27

Minimal workflows now avoid unrelated framework knowledge, duplicate conductor source scans, and in-context scan-body handoffs while retaining the same artifacts, reviews, sensors, learnings, and approval gates. **Upgrade:** refresh your `dist/<harness>/` shell so the depth-aware context roster and file-backed Reverse Engineering handoff are installed.

* Minimal Intent Capture and Requirements Analysis load only their stage-relevant shipped knowledge; plugin-installed knowledge, Standard and Comprehensive runs, active-space rules, personas, consumes, and user/team knowledge keep the existing full context.
* Dispatched agents return path/decision/concern summaries instead of repeating artifact, scan, source, or test-output bodies that already exist on disk.
* Reverse Engineering keeps its developer-to-architect pipeline and all nine CodeKB artifacts, but transfers the developer scan through a durable record file, rejects symlinked handoffs when minting or verifying receipts, binds accepted receipts to the current-attempt path, write time, and content digest, and prevents a duplicate conductor source scan.
* Isolated pipeline stage runners now record their synthetic start boundary before the first agent dispatch, require their own receipts before completion, and resume that open attempt without touching the main workflow pointer.
* Isolated Reverse Engineering reuse now emits synthetic-workflow evidence for all-reuse and mixed-reuse runs only when the complete canonical CodeKB artifact set exists and source freshness matches; missing, redirected, invalid, or later-stale evidence cannot complete.
* Reverse Engineering keeps every recorded repo identity qualified through its handoff filename, receipt chain, resume evidence, and CodeKB destination, including an intent with exactly one registered repo.
* Plugin composition records exact recursive knowledge ownership and retains provenance for still-installed files removed from a later plugin version, so Minimal context retains active plugin files while deselected or removed plugin knowledge cannot become unowned context.
## [2.6.116] - 2026-08-27

The question protocol now reuses answers already captured in the current record, closing a top field-feedback gap where teams saw the same question resurface after they had answered it, sometimes after stating that the answer was final. **Upgrade:** refresh your `dist/<harness>/` shell.

* Before emitting a question, the orchestrator recursively reads the record's question files and correlates scope-compatible prompts and answers across every audit shard; ambiguous cross-shard ordering requires a narrow, prior-answer-naming follow-up instead of an inferred answer or a reopened topic.

## [2.6.115] - 2026-08-27

Existing vision documents, PRDs, requirements briefs, and other referenced files now feed the workflow through a deterministic, trust-marked read boundary. Multiline initial requests persist outside the line-oriented state grammar, and ambiguous, missing, redirected, out-of-workspace, non-text, or oversized document references stop for clarification instead of being guessed. **Upgrade:** refresh your `dist/<harness>/` shell so the updated utility, stage instructions, and description sidecar are installed together.

* Reference one explicit project-root-relative document path in the initial request, such as `/aidlc Read ./vision.md and build what it describes`; the stage transfers it through the active record's fixed `.aidlc-document-input-path` file, so filename metacharacters never enter a shell command. Direct reads do not search by basename or follow symlinks, and the opened descriptor must match the file identity validated inside the project.
* Direct UTF-8 text and Markdown input is emitted with the same `UNTRUSTED DATA - NOT INSTRUCTIONS` and `UNTRUSTED PATHS - NOT INSTRUCTIONS` boundary as DocumentKB. Binary and unsupported formats must use `/aidlc knowledge onboard` and `show`; oversized inputs are refused before their payload is allocated, and the one-line `.aidlc-document-input-path` transport file itself is bounded at 4096 bytes.
* Explicitly delimited pasted documents receive the same inert-data treatment. Intent Capture uses document claims only to shape clarifying questions until confirmed through `[Q<n>]`; Requirements Analysis treats bounded content as primary data without granting it workflow authority.
* Unmatched, nested, repeated, non-terminal, or directionless `<document>` input is refused before intent creation, so document bytes cannot escape their untrusted boundary and clarification cannot strand a partially initialized record.
* The exact initial description is stored as one JSON string in committed `<record>/project-description.json`; downstream stages treat that marked sidecar as authoritative across resume and clone, while pre-2.6.115 records retain the legacy state-field fallback.

## [2.6.114] - 2026-08-27

No-DAG per-Unit review continuity now follows the current attempt's audit-observed Bolt lifecycle, lifting the 2.6.76 limitation without persisting a substitute Unit graph. **Upgrade:** refresh your `dist/<harness>/` shell so review admission, artifact fingerprints, receipt filtering, and gate coverage use the same audit window. An in-flight no-DAG stage-level review request stamped before this release, or while every Bolt was still open, may no longer match after a Bolt merges and replaces the stage-level fallback path with merged-Unit paths; re-dispatch its exact pending ordinal with `--retry-pending` before recording the verdict.

* `aidlc-log.ts review --unit <unit>` remains available after that Unit's Bolt merges, including `--retry-pending` and stale-receipt recovery, while a Unit with no current-attempt Bolt history still refuses.
* A Bolt merge is proven, not asserted: because `aidlc-bolt complete --merge` emits `BOLT_COMPLETED` before the state and audit merges run, a slug-backed (worktree) attempt counts as merged only once the matching later `AUDIT_MERGED` receipt lands on main. A crash inside that window, or a worktree completion recorded without `--merge`, leaves the Unit unmerged and its per-Unit review refused; re-run `aidlc-bolt complete --merge --slug <slug>` to land the merge and unlock the review. A name-only, non-worktree Bolt keeps `BOLT_COMPLETED` as its terminal row.
* A slugless completion cannot close a slug-backed attempt, and a later fragment-cleanup `BOLT_FAILED` cannot erase a merge that `AUDIT_MERGED` already confirmed. An `AUDIT_MERGED` receipt carries no reviewer authority, so one landing in another audit shard within the same second cannot make a review request or verdict ambiguous.
* A no-DAG per-Unit stage with merged Bolts may satisfy its reviewer gate with either one fresh stage-level receipt or fresh per-Unit verdicts covering every merged Unit. Failed or discarded Bolts owe no review.
* Stage-level review fingerprints enumerate only merged Bolt Units, because open-Bolt work is not yet present in the main tree. Per-Unit receipt filtering still recognizes both open and merged Units, and forged Unit receipts outside that observed set cannot satisfy coverage.
* Same-second cross-shard Bolt reduction preserves causal append order within each shard and applies the stricter merged result only across genuinely unordered shard heads. A tied start/completion that settles merged accepts the gate's named per-Unit review command.
* Bolt lifecycle truth remains per attempt: a Unit may be both merged and open when an older attempt landed while a newer attempt is still active. The merged work still owes review and the open attempt remains eligible for receipt filtering.
* `aidlc-runtime.ts compile` cannot erase this continuity because the observed Unit set is derived from audit rows and is not written to `runtime-graph.json`.

## [2.6.113] - 2026-08-27

Kiro CLI and Kiro IDE now preserve engine-authored routing questions instead of querying intent state and replacing them with a conductor-derived prompt. **Upgrade:** refresh your `dist/kiro/` or `dist/kiro-ide/` shell so the updated conductor and numbered-prose rendering contract are installed.

* A typed `new-work-routing` ask is the sole route authority once emitted: its engine-authored `numbered_prose_question` carries routes 1-3 plus `4. Other`, which Kiro prints verbatim before ending the turn without an extra `intent --json` query or recommendation.
* On Kiro CLI and IDE, unselected-intent clones with pending new prose receive the same typed routing ask plus engine-listed `available_intents`; those values are exact record-directory selectors, so duplicate labels remain switchable through `next intent <name>`. Other harnesses retain their prior picker and scope-confirm contracts.
* Selecting `4. Other` now has a complete response route on both Kiro surfaces: a bare selection requests the missing details, while a substantive alternative is forwarded unchanged through `next` and never through `report`.
* The compiled `aidlc` dispatcher now pins both the installed harness directory and exact harness name before loading the orchestrator, preserving Kiro routing when module paths and embedded metadata cannot identify the host.
* Continuation and plan-reshape classification remain available before the first engine response; once an ask exists, both old and new Kiro versions use the same prose-only stop-and-wait path.

## [2.6.112] - 2026-08-27

Structured questions must now be self-explanatory, closing a top field-feedback gap where teams found questions too abstract and bare shorthand like `FR3`/`url1` unanswerable without asking the agent to rephrase. **Upgrade:** refresh your `dist/<harness>/` shell.

* Depth-aware question generation gains a "questions must be self-explanatory" rule: expand every identifier in each question that uses it (write what it names, then tag it in parentheses), give each question one line of context when the reason is not obvious, and prefer concrete domain phrasing over the framework's internal vocabulary.

## [2.6.111] - 2026-08-26

Plugin composition now keeps co-located tests and fixtures out of the installed engine tools tree and reports every rejected payload. **Upgrade:** refresh your `dist/<harness>/` shell and each plugin projection, then re-compose plugins; remove any already-installed file named by the new advisory and re-run compose.

* Files under a plugin's `tools/tests/`, `tools/__tests__/`, or `tools/fixtures/` directories, plus `*.test.ts` and `*.spec.ts` tool files, are skipped with an advisory drop that points authors to the top-level `tests/` convention.
* Installed test payloads remain untouched by no-clobber composition but are audited from the destination tree even after they disappear from a corrected plugin projection; legacy files without provenance are reported without attributing them to the plugin currently composing.
* The installed-payload audit record is per harness (`plugin-compose-installed-tool-payloads-<harness>.drops`), so a clean compose on one harness never erases the advisory another harness's stale payload still needs, and the destination scan never follows symlinks - a circular or external directory link in the installed tools tree can no longer abort composition or pull unrelated trees into the audit.

## [2.6.110] - 2026-08-26

Plugin composition lost to an engine reinstall is now detected and documented instead of leaving plugin stages or contributions silently absent. **Upgrade:** refresh your `dist/<harness>/` shell, then run `/aidlc plugin sync` for every installed plugin; Claude, Codex, Cursor, and Kiro IDE can also re-compose on the next session start.

* `/aidlc --doctor` now fails the **Composed plugin surface** check when an enabled plugin-owned stage is absent from the compiled graph, a contribution sidecar is unreadable or malformed, its target stage is gone, or a recorded structural or prose contribution is missing or changed; consume provenance includes `artifact`, `required`, and optional `conditional_on`, while legacy artifact-only sidecars remain accepted.
* Compose records successfully applied fragment anchor/order/hash provenance in the existing per-plugin contribution sidecar, including for prose-only plugins, so a fresh engine overlay cannot erase their only contribution undetected.
* The **Uncompiled stage files** advisory now directs plugin-owned files to `plugin sync` while retaining `aidlc-graph.ts compile` for other authored stages.
* The install, CLI, troubleshooting, plugin-authoring, and plugin-mechanism guides now make plugin re-composition an explicit engine upgrade step.

## [2.6.109] - 2026-08-26

Autonomous swarm convergence now preserves reviewed record artifacts and completes immutable application-source landing before a modern Unit can advance. **Upgrade:** refresh your `dist/<harness>/` shell so the updated referee, worktree recovery, routing guard, and swarm protocol are installed together.

* `aidlc-swarm finalize` snapshots the exact declared artifact bytes and bound `source-manifest.json` that passed the Unit review, rejects symlinked source or destination paths, applies the complete per-Unit record set with rollback on failure, and only then merges state, audit, and runtime metadata.
* Finalize result rows now include `bolt_slug`; the swarm protocol uses it to require `aidlc-worktree merge` for every converged Unit before `next`. Modern `SWARM_UNIT_CONVERGED` rows do not advance batch routing until the matching `SWARM_SOURCE_MERGED` aggregate authority exists.
* Rerunning `aidlc-worktree merge` after source authority landed but worktree, branch, or retained-ref cleanup failed derives the exact intent/repository/source/merge authority, refuses ambiguity, and performs cleanup-only reconciliation even after stage-attempt turnover. It does not reapply source or emit duplicate merge authority.
* Immutable reviewed source still lands from the `Source Commit`; bound merge and commit porcelain run with all repository hooks disabled, so post-merge and post-commit hooks cannot replace bytes after convergence.

## [2.6.108] - 2026-08-26

Unattended drivers can now explicitly withhold human-presence authority across every harness, preventing scheduled prompts from satisfying approval and interview gates. **Upgrade:** refresh your `dist/<harness>/` shell and set `AIDLC_UNATTENDED=1` on any process that submits prompts without a person present.

* `AIDLC_UNATTENDED=1` suppresses the authority-bearing `HUMAN_TURN` audit event in Claude, Codex, Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode while preserving non-authority turn markers used by forwarding hooks. An unflagged driver retains the existing interactive behavior.
* Approval, rejection, ordinary-answer, and summary-confirmation refusals now name a leaked `AIDLC_UNATTENDED=1` and instruct operators to unset it before returning to interactive mode and submitting a fresh response.

## [2.6.107] - 2026-08-26

Team-owned unit-major Construction can now fan out safely across clones or sibling worktrees, publish exact candidates, and converge through a pinned human-gated merge transaction with a deterministic dispatcher. Landing now refuses a stale local integration target, and its ownership-boundary regression is portable across case-sensitive and case-insensitive filesystems. **Upgrade:** refresh your `dist/<harness>/` shell; existing workflows remain solo unless delivery planning explicitly enables team ownership.

* `aidlc state set-unit-ownership <team|solo>` and `set-unit-gate-rhythm <per-stage|unit-end>` enable the mode; the engine derives Unit Progress from artifacts, current receipts, reviews, gates, claims, and `UNIT_MERGED` evidence, never hand-edited table cells.
* `aidlc unit claim|adopt|release|participate` provides atomic git-native ownership with generation-bumping tombstones, checkout-local routing, participant picking, fresh-clone teammate handoff that preserves the bound audit shard, partial-clone-safe payload hydration, and claim-bound fork/lifecycle authority.
* `aidlc unit publish|pin|gate|land` publishes a claim-ref candidate and converges it through an exact OID/generation, pin-transaction-bound main-shard human merge gate, candidate-exact merge, evidence-derived state fold, and final `UNIT_MERGED` receipt. Republish after rebasing onto the current integration branch to refresh the candidate base; pin, gate, and landing revalidate the live Unit contract, and landing requires the fetched integration tip to be present in the local target before Git mutation.
* Merge and release recovery journals are isolated by space, intent UUID, and Unit. A release after the git landing step has one explicit recovery: inspect the landed commit, then run `aidlc unit land <unit> --accept-released-attempt --user-input "<human acknowledgment>"`; the exact immediate tombstone, fresh main-shard human turn, acknowledgment, journal, and main audit are bound before state folding.
* Unscoped main renders a terminal Team Construction board with the derived grid, observed local claims, blockers, merge readiness, and exact claim/gate/land recovery commands. `/aidlc --status` renders the same read-only snapshot from main or a scoped checkout, including explicit space/intent selection.
* The multi-intent picker annotates team claimability, parked work, and completed intents. `/aidlc --doctor` detects stale stamps, 24-hour observed-ref inactivity, missing observation baselines, and orphan local claim refs without fetching or auto-releasing.
* Copilot retains terminal Team Construction `notice` directives, shared hook classifiers recognize `aidlc unit`, and `UNIT_MERGED` refreshes runtime state. Unit DAGs reject case-fold collisions such as `api`/`API`; intents with recorded sibling repos reject team ownership before state changes.
* Solo, knob-absent, claim-less team, and ordinary scoped execution retain their existing behavior; team Stop-hook probes remain write-free while their steering continuation is executable by the ordinary single-use `continue` flow.

## [2.6.106] - 2026-08-26

Kiro CLI and Kiro IDE numbered-prose questions now visibly expose one final Other choice, including the interaction-mode prompt that previously listed only options 1-3 and mentioned Other separately. **Upgrade:** refresh your `dist/kiro/` or `dist/kiro-ide/` shell so the corrected question-rendering annex is installed.

* The interaction-mode contract includes a canonical four-option rendering with `4. Other`, so Guide me / I'll edit the file / Chat never leave the escape path unnumbered.
* File-backed `X. Other (please specify)` choices map to the final visible number without adding a duplicate; consolidated-summary files remain unlettered and omit a file-level Other row while chat still synthesizes one final numbered escape.

## [2.6.105] - 2026-08-26

Plugin authors can now create, validate, build, and compose-test an authored plugin repository offline with shipped standalone tools, without a framework checkout or mutations to the install under test. **Upgrade:** refresh your `dist/<harness>/` shell to install the authoring tools, bundled hook templates, and harness target data.

* Run `bun <tools-dir>/aidlc-plugin-create.ts <name> [targetDir] [--json]` to emit a deterministic minimal plugin that validates green on arrival; CREATE refuses non-empty targets and never vendors `hooks/compose.ts`.
* Run `bun <tools-dir>/aidlc-plugin-validate.ts <plugin-root> [--json]`; exit codes are `0` valid, `1` findings, and `2` usage.
* `/aidlc plugin validate [path]` and `/aidlc plugin build <harness> [outDir] [--plugin-root <path>]` expose validation and projection through the top-level CLI while delegating to the same standalone implementations.
* Validation covers manifest shape, canonical `aidlc.contributes` locations, stage schema, core and plugin agent references, non-empty stage bodies, artifact namespaces, contribution targets, scope and agent identity, plugin-local duplicate artifact producers across `produces` and `optional_produces`, accidental test/fixture payloads under `tools/`, vendored compose-hook drift, and linked authored content. Configurable contribution paths and `memory/` projection remain deferred, so VALIDATE, BUILD, and TEST reject those declarations instead of silently omitting content.
* Run `bun <tools-dir>/aidlc-plugin-build.ts <plugin-root> <harness> [outDir] [--json]` to validate then emit one host-native projection; output defaults to `<plugin-root>/dist/<harness>/`.
* BUILD refuses symlinks inside its caller-owned output boundary, including a linked `<plugin-root>/dist`, before cleanup or writes can reach the linked directory; environmental path aliases above that boundary remain supported. Every projection carries an explicit plugin-and-harness ownership marker, and an output-scoped owner-stamped lock serializes marker verification, cleanup, and emission so only the same owner may rebuild that non-empty output. Dead owners and aged unstamped crash remnants are reclaimed; live, malformed, and unreadable owners fail closed.
* The checkout packager and standalone builder share one emitter. Harness manifests generate the bundled target table, and isolated proof tests byte-compare all seven externally built test-pro projections with committed `dist/plugins` output.
* Run `bun <tools-dir>/aidlc-plugin-test.ts <plugin-root> --install <project-root> [--harness <name>] [--json]` to compose into a disposable install candidate, report drops, compile the post-compose graph, verify plugin stages/scopes, and prove a second compose is idempotent.
* `--dist <version>` is reserved until RFC #722 milestone 2 supplies a released runtime-bundle channel; test against an existing install in this release.
* `tests/harness/plugin-kit.ts` now delegates its overlapping content rules, compose subprocess, and drop parsing to the shipped tools while retaining checkout-aware fixture integration.

## [2.6.104] - 2026-08-26

Error recovery now keeps the same project-focused voice as normal workflow progress without weakening terminal errors or state-aware review recovery. **Upgrade:** refresh your `dist/<harness>/` shell so every harness receives the updated conductor rules, tools, and hooks.

* Conductors translate ordinary tool, hook, and workflow-check refusals into project language, while terminal engine error directives remain verbatim, stop immediately, and are never retried.
* Retry limits follow the same project action and target across corrected arguments and unrelated successful calls; a success for that action, a human-chosen alternative, or a relevant workflow-state change resets the count.
* Gate, question, review, collaboration, plan-approval, reviewer-scope, and state-transition refusals now name the blocked project action and an actionable recovery without section cites, audit event names, or internal output-field vocabulary.
* Exhausted review recovery preserves state-aware guidance for active, revising, completed, and off-plan stages instead of always directing the conductor to an approval gate.

## [2.6.103] - 2026-08-26

Kind-vacuous Construction units no longer deadlock summary-confirmation routing when their unit kind excludes every output of a per-unit stage. **Upgrade:** refresh your `dist/<harness>/` shell so unit-major routing and per-unit approval skip confirmation evidence that an inapplicable unit cannot produce.

* Unit-major iteration now advances past kind-vacuous units to the next applicable stage and unit instead of emitting `Refusing to complete`.
* Stage-major per-unit approval now presents the normal gate when all units are kind-vacuous, without requiring nonexistent questions or summary confirmation.

## [2.6.102] - 2026-08-26

Rule files can now carry validated lifecycle metadata, and doctor separates stale team/project overlaps from live contradiction-review candidates without changing runtime rule delivery. **Upgrade:** refresh your `dist/<harness>/` shell; add lifecycle fields only where you want file-level drift triage.

* Add optional `status: active|deprecated|draft` and `stale_after: YYYY-MM-DD` rule frontmatter, with compile-time validation that names the invalid file and rejects blank or block-scalar lifecycle declarations.
* `/aidlc --doctor` keeps live rule-drift output unchanged and reports deprecated or date-expired file overlaps in one passing `Rule drift: N stale-suppressed` row.

## [2.6.101] - 2026-08-26

Human review checkpoints now show deterministic decision context before both summary confirmation and final approval, preserve accepted or rejected finding dispositions without modifying receipt-frozen artifacts, and retain concrete invalidation paths through the required recovery review. **Upgrade:** refresh your `dist/<harness>/` shell so the new review-brief tool, gate audit fields, and protocol guidance are installed.

* `aidlc-review-brief.ts summary|review|context` renders the stage, exact files, reason for the checkpoint, decision effects, hydrated finding statuses, and stale artifact/review paths across every harness.
* Approving a reviewer-backed gate records current open findings as `Accepted risk`; Request Changes can record an explicit `Rejected: <reason>` with `--reject-finding "<review-artifact>#R-NN=<reason>"`, while ordinary revision feedback leaves findings unresolved.
* A per-Unit stage's single final gate renders findings from every Unit covered by approval, exactly matching the findings dispositioned as accepted risk.
* Artifact, source, and backward-jump invalidation paths survive the required recovery review and remain visible at the final gate; executable acceptance scenarios cover READY, NOT-READY, re-review, multi-artifact, stale-review, rollback, and all three summary-confirmation modes.

## [2.6.100] - 2026-08-26

Knowledge index recovery now selects duplicate records against the live managed source even when the project path traverses a symlink, and refuses present sources that cannot be safely read. **Upgrade:** refresh your `dist/<harness>/` shell to receive the corrected recovery behavior.

* `aidlc-knowledge sync` rebuilds a missing `index.json` using digest matching through symlinked project paths, preventing a newer stale duplicate record from surviving recovery.
* When duplicate records require a digest tie-break, a present-but-refused managed source, including a dangling symlink, now stops the rebuild with the source path and refusal reason; only a genuinely absent source retains the deterministic newest-`indexed_at` fallback.

## [2.6.99] - 2026-08-26

Audit and usage-ledger read-modify-write transactions now remain serialized during Windows lock handoff instead of allowing retirement or stale recovery to displace a successor. **Upgrade:** re-copy `dist/<harness>/` so all state, audit, active-directive, and usage writers receive the generation-bound lock protocol.

* Stamp every acquisition with a canonical UUID owner generation plus the OS process generation when the optional platform probe is available; probe failure retains the PID/token stamp and leaves a live owner generation-unknown and fail-closed. In-process ownership/reentrancy is keyed by canonical lock identity while retaining request bindings for path materialization and active-space changes.
* Retire only the matching generation through bounded, collision-proof private renames; persistent retirement failure retains its receipt and exit recovery handler.
* Distinguish missing, malformed, and unreadable owner stamps. Non-canonical tokens, missing or redirected token directories, and non-regular releasable markers are invalid; malformed/unreadable and matching or generation-unknown live owners fail closed, and doctor reports them for quiescent manual recovery.
* Serialize every canonical acquire, release, cleanup, and recovery through an owner-stamped gate whose publication and retirement are protected by an OS advisory mutex (`flock` or `LockFileEx`). POSIX loading supports glibc, macOS libSystem, standard musl loader/libc names, and discovered musl libraries instead of assuming `libc.so.6`.

## [2.6.98] - 2026-08-26

Isolated pipeline stage runs now resume and complete only from their own ordered receipt chain, and stage compilation rejects repeated agents whose receipt identity would be ambiguous. **Upgrade:** refresh your `dist/<harness>/` shell; existing valid stage definitions and main-workflow pipeline receipts need no migration.

* `aidlc-orchestrate.ts next --stage <slug> --single` reports only `PIPELINE_LINK_COMPLETED` rows tagged for that isolated run, and `report --single` refuses completion until every isolated link receipt exists.
* Pipeline stage frontmatter must declare a unique agent at every lead/support chain position; `aidlc-graph.ts compile` rejects duplicate support agents and a lead repeated in `support_agents`.

## [2.6.97] - 2026-08-26

The Stop hook now recognizes background Agent/Task work per session, so a conductor can end its turn to await a still-running worker without weakening another session's forwarding loop. **Upgrade:** refresh your `dist/<harness>/` shell so dispatch, completion, Stop, and doctor hooks share the new in-flight ledger.

* Accepted background dispatches with `run_in_background: true` add a session-scoped in-flight entry only after rule delivery passes validation; rejected and oversized dispatches leave no entry.
* Subagent completion removes one entry for its own session, preserving overlapping workers in the same session and isolating concurrent sessions.
* A fresh matching entry lets an interactive Stop end cleanly. Autonomous Construction remains enforced, while entries older than two hours are ignored and cleaned up before pending-step enforcement resumes.
* `/aidlc --doctor` reports fresh background-subagent entries as advisory and stale entries as failures with `rm aidlc/.aidlc-subagent-inflight` remediation.

## [2.6.96] - 2026-08-26

Type-check sensor incremental state now stays in the project record and uses a distinct cache per tsconfig, preventing package-local `aidlc/` trees in monorepos. **Upgrade:** refresh your `dist/<harness>/` shell and drop any user-side workaround ignore rules; legacy package-local cache directories may be removed individually after confirming they contain only sensor cache data.

* Type-check keeps `--project` and the tsconfig-directory working directory while writing `.tsbuildinfo-<sha256>` files under the project record's `.aidlc-sensors/` directory, keyed by the project-relative tsconfig path.
* Every harness now ignores the full engine-shaped sensor-cache path at any depth, covering legacy package-local trees without ignoring unrelated `.aidlc-sensors` directories.

## [2.6.95] - 2026-08-25

`/aidlc --doctor` now reports consumed artifacts with multiple loaded producers before runtime silently selects the first producer by graph load order. **Upgrade:** refresh your `dist/<harness>/` shell to install the new advisory check; no workflow migration is required.

* The passing `Duplicate producers` advisory names every ambiguous consumed artifact and lists its producer stage slugs in runtime resolution order, with the selected producer first.
## [2.6.94] - 2026-08-25

AI-DLC now describes intent startup consistently as creation across generated harness guidance, user-facing errors, status text, documentation, and the lossless adaptive-composer contract. No command or flag changes are required. The retired `intent-birth` compatibility error still redirects old invocations, and the reserved legacy record name remains switch-reachable. **Upgrade:** refresh your `dist/<harness>/` shell; integrations that read composer proposals must rename `birthDescription` to `creationDescription`, and custom tools importing the renamed internal helpers must update their imports.

* User-facing errors, generated runners, harness instructions, workflow guidance, documentation, diagnostics, comments, and test names now use `create`, `created`, and `creation` terminology.
* Front/report composer proposals require nonblank `creationDescription` while preserving the existing lossless contract: task text stays verbatim, report-only and task-less plans derive grounded text, and the same-turn creation command retains the literal `--` delimiter plus POSIX-safe single-argument escaping.
* Internal aidlc-lib names now use `CreatedIntent`, `resolveIntentRepoSet`, and `workflowIsCreated`; workflow behavior is unchanged.

## [2.6.93] - 2026-08-25

`/aidlc --doctor` now detects project hooks that never start, hooks that stop during a workflow, and Claude Code managed policy that permits only managed hooks. **Upgrade:** re-copy your `dist/<harness>/` shell into the project, approve Claude project hooks through `/hooks`, and fully restart Claude Code.

* Zero hook heartbeats remain a passing first-run advisory only before workflow progress; after progress they fail with ordered hook-approval, restart, administrator-policy, and attended-session bypass guidance.
* Existing heartbeats are compared with the newest stage or gate event and fail when workflow progress is more than five minutes newer; ledgers with stage or gate events but no `HUMAN_TURN` receipt also show a passing advisory.
* Claude installs fail when effective managed `allowManagedHooksOnly: true` blocks `.claude/settings.json` hooks. The check shares the existing `AIDLC_MANAGED_SETTINGS_PATH`, current and legacy Windows locations, managed-setting precedence, and alphabetical `managed-settings.d/` fragment resolution used by `disableAllHooks`.

## [2.6.92] - 2026-08-25

Filesystem descendant checks now enforce one mixed-separator boundary on every host, preventing Windows traversal and alias escapes while preserving valid in-bound drive and UNC paths. **Upgrade:** refresh your `dist/<harness>/` shell so every tool receives the strengthened shared path guard.

* Relative descendants are parsed with Windows-aware structured path APIs before native joining, so `/` and `\` both delimit components; `..`, POSIX roots, drive-rooted and drive-relative paths, and UNC inputs are refused before filesystem access.
* Symlink and junction inspection now walks each mixed-separator component before permitting an existing or not-yet-created descendant, preventing an alias from being hidden ahead of a missing leaf.

## [2.6.91] - 2026-08-25

Lone-repository CodeKB scope fingerprints now avoid Git's unreliable combination of positive and exclude pathspecs and reject fingerprints that contain no files, while Copilot no longer asks an AI-DLC workflow question twice when the model attempts to use a native question picker. **Upgrade:** refresh your `dist/<harness>/` shell before minting or checking CodeKB scope fingerprints, and re-mint (or re-run reverse engineering for) any stored scope timestamp whose fingerprint is `4b825dc642cb6eb9a060e54bf8d69288fbee4904`, the empty-tree value written by the pre-fix bug; in-flight Copilot workflows need no migration.

* `codekbScopeFingerprint` omits exclusions outside analyzed roots, drops analyzed paths covered by exclusions, and preserves root and nested-project scope boundaries without silently rewriting malformed absolute paths.
* Scopes that stage zero paths now mint `unknown` and report `UNVERIFIED`, never a false `CURRENT` or permanent `STALE` verdict.
* Deterministic regression coverage verifies distinct narrow fingerprints, full-root exclusions, nested-project boundaries, malformed paths, and empty scopes.
* The Copilot PreToolUse adapter denies native picker execution IDs such as `ask_user` and `vscode/askQuestions` only when the session-selected workflow has valid `Status: Running` state; projects with no workflow, completed workflows, and unusable state fail open.
* Picker tool results still never count as `HUMAN_TURN`; the user's next chat message records the trusted turn used by answer and approval logging.

## [2.6.90] - 2026-08-25

`/aidlc --doctor` now distinguishes hook directories that have not had a chance to populate from dead hook seams after a workflow stage ran. **Upgrade:** refresh your `dist/<harness>/` shell so doctor can detect this condition.

* When `.aidlc-hooks-health/` exists without any `.last` files and the active audit ledger contains `STAGE_STARTED`, doctor reports `Hook heartbeat data` and exits 1; CI jobs that gate on doctor will now fail for this broken hook state.
* Missing, pre-created, and debug-only health directories still report the existing not-yet-fired pass row before any stage starts, while real heartbeat files continue to report their last-fired timestamps.

## [2.6.89] - 2026-08-25

The conductor no longer parks a workflow because context *feels* heavy. The orchestrator skill previously licensed parking when context seemed low even though the conductor cannot measure its own usage, causing unnecessary park/resume interruptions while most of the window remained free. **Upgrade:** refresh your `dist/<harness>/` shell to install the bounded parking guidance.

* Parking for context now requires a usage figure surfaced by the harness at or above 80%; without one, the conductor keeps running stages.
* User-requested parking and the rule to park instead of fabricating a `done` remain unchanged.
* The rule applies to all manifest-discovered harness orchestrator skills.

## [2.6.88] - 2026-08-25

Kiro conductors now treat stage diaries as engine-created write targets instead of pre-stage inputs. Diary observations and lifecycle behavior are unchanged. **Upgrade:** refresh `dist/kiro/` or `dist/kiro-ide/` so the corrected conductor skill is installed.

* Kiro CLI and Kiro IDE treat `memory.md` as output-only: ordinary, isolated, dispatched, and per-Unit wave paths insert observations directly under known canonical headings without a read, existence probe, read-back verification, or initialization step.
* Stage definitions no longer contradict that boundary by telling the model to create or read the diary; the deterministic `aidlc-learnings surface` tool remains the only reader when candidates are surfaced before a gate.
* Deterministic instruction-contract coverage keeps both Kiro skills and every stage definition aligned, while live ACP and TUI coverage checks diary access and the numbered-prose checkpoint flow.

## [2.6.87] - 2026-08-25

DocumentKB documents can now carry an LLM-authored summary and tags, revision-bound to the catalogued source revision so an agent can cite a document's gist without re-reading it. **Upgrade:** refresh your `dist/<harness>/` shell to install the new `summarize` verb and updated knowledge skill.

* `aidlc-knowledge.ts` gains an eighth verb, `summarize <id> --text-file <path> --source-revision <sha256> [--tags <csv>]`, which validates, bounds, and persists an LLM-authored summary plus optional tags. Running `sync` after the original changes invalidates stale summary text; tags remain available as untrusted metadata.
* `list` and `show` surface summary state and tags with untrusted-data framing, while tombstoning an original removes its generated summary derivative.
* The shared onboarding, knowledge skill, and audit-event references name `summarize` alongside the existing DocumentKB verbs.

## [2.6.86] - 2026-08-25

Bolt terminology now preserves the sprint-like Construction iteration while matching the shipped stage-major runtime. Delivery Planning still records the intended Bolt grouping, Definition of Done, confidence hypothesis, and ownership, but runtime batching and ordering remain driven by the Unit dependency graph. **Upgrade:** refresh your `dist/<harness>/` shell so the reconciled protocol, glossary, audit reference, and stage guidance are installed.

* The canonical protocol and glossary distinguish a Bolt from a Unit, worktree, swarm, and runtime batch while documenting that the default stage-major walk does not consume `bolt-plan.md` as an execution boundary.
* Construction guidance keeps current stage-level gates, unit-major's retained gate cascade, and `org.md` → `team.md` → `project.md` walking-skeleton stance executable while labeling future Bolt-major ceremony non-executable.
* `BOLT_STARTED` and `BOLT_COMPLETED` are documented as per-Unit/worktree events on the swarm path; `SWARM_COMPLETED` remains the event that closes the runtime batch.

## [2.6.85] - 2026-08-25

Kiro now relays deterministic command output through a UTF-8 plain-text hook boundary instead of the Windows shell-result transport that can append terminal debris or corrupt glyphs. **Upgrade:** re-copy `dist/kiro/` or `dist/kiro-ide/` into the project; Kiro IDE overlay installs must include the new `aidlc-terminal-command*` hook registrations.

* Kiro CLI status, doctor, help, version, navigation, plugin, and knowledge output is decoded explicitly as UTF-8; OSC, CSI, and other terminal control bytes, including unterminated sequences, are removed only from the plain-text relay, preserving ordinary Unicode, paths, whitespace, and literal escape-looking text.
* Kiro IDE runs terminal utilities at `UserPromptSubmit` when the host exposes the submitted prompt. IDE generations such as 1.0.242 that send an empty prompt fall back to the exact `execute_pwsh`/shell `PreToolUse` command, run the classified utility once, and refuse the duplicate shell call before its output enters the Windows transport.
* Per-session, per-turn latches prevent retries from re-running side-effecting diagnostics without allowing concurrent IDE chats to reuse one another's command output. Payloads without a session identity retain one explicit legacy bucket; non-terminal commands and the existing exit-2 approval, lifecycle, reviewer, and plan guards retain their refusal behavior.
* Kiro terminal-command argument parsing preserves unquoted drive paths, quoted Windows paths containing spaces, UNC paths, and trailing Windows separators when forwarding options such as `--doctor --output`, while retaining escaped-space values such as `reports\ 2026`.

## [2.6.84] - 2026-08-25

Compiled Windows executables now keep every routed command inside the native runtime instead of falling back to source-mode `bun` launches. Source installs continue to delegate through their running Bun executable. **Upgrade:** replace the executable and its adjacent `runtime/` directory, or refresh your selected `dist/<harness>/` shell for source installs.

* Compiled-mode detection now recognizes a non-Bun `process.execPath` in addition to Bun's virtual-filesystem URL marker, covering native Windows path forms that do not contain the POSIX `/$bunfs/` substring.
* Binary release gates run representative utility and doctor delegates with `PATH` empty, alongside the existing pathless routed-command matrix, and assert Windows executable classification without changing Bun source-mode classification.

## [2.6.83] - 2026-08-25

Summary-confirmation artifact-write receipts now remain valid when the same workflow workspace is moved or cloned to a different filesystem location, without weakening their causal ordering. **Upgrade:** refresh your `dist/<harness>/` shell so completion guards use the portable receipt matcher.

* Completion no longer reports `no recorded native-tool write after the human's consolidated summary confirmation` solely because an audit row contains the artifact's absolute path from the workspace's previous location.
* Moved or cloned workspaces no longer deadlock when the completion guard rejects the old absolute prefix and review-freeze blocks the prescribed artifact re-save; the full space/intent/phase/stage-relative artifact tail now identifies the same recorded write.

## [2.6.82] - 2026-08-25

`/aidlc --doctor` now catches hooks that Claude Code has globally disabled. Previously an install with `"disableAllHooks": true` could pass every check yet block at runtime because doctor verified that hook files were present and wired, but not that Claude Code would run them. **Upgrade:** refresh your `dist/<harness>/` shell to pick up the new check.

* Claude Code doctor output adds a **Hooks enabled** row that fails when the resolved `disableAllHooks` value is `true` in enterprise managed, project local, project, or user settings. The check follows Claude Code's layer precedence, names the controlling layer, and explains how to restore AI-DLC's hook-driven workflow engine.
## [2.6.81] - 2026-08-25

Agent and stage prompts now omit duplicated ownership and persona-loading prose while every delegated agent retains a mandatory shared and agent-specific knowledge preflight in its generated harness surface. **Upgrade:** re-copy your `dist/<harness>/` shell; active workflow state and project artifacts need no migration.

* Core and plugin persona sources no longer repeat stage ownership, the six-step knowledge-loading list, or Task-tool warning prose already owned by stage metadata, the protocol, and harness tool policy.
* Every Claude, Codex, Copilot, Cursor, Kiro CLI, Kiro IDE, and OpenCode delegated-agent projection carries the compact methodology/team knowledge preflight, including plugin agents.
* The remaining Construction stages start with substantive work, with execution-mode ranges, Build and Test plugin anchors, quality-target assertions, loop-back references, and reference documentation renumbered consistently.
* Codex ships `[agents] max_depth = 1`, matching the single-level delegation boundary documented by its orchestrator.

## [2.6.80] - 2026-08-25

Concurrent sessions in one checkout now keep workflow selection, usage, lifecycle events, learning candidates, and fresh-intent handoffs bound to the owning session for independent intents within the same space. **Upgrade:** refresh your `dist/<harness>/` shell; Codex users must also re-run `bun scripts/package.ts codex trust --project <absolute-project-path>` because the new Bash session-binding hook adds a trust-table entry.

* Session bindings live under the existing gitignored `aidlc/.aidlc-sessions/` runtime directory and resolve before shared cursor fallbacks. Cold sessions retain an explicit null-intent binding, while intent creation and intent or space switching move the binding, UUID attribution, and lifecycle ownership together.
* Learning surfacing, usage folding, SessionEnd, and Stop-hook fresh-intent handoffs resolve through the session binding instead of accepting a concurrently moved shared cursor.
* Hook payload identity, `AIDLC_SESSION_OVERRIDE`, and validated PID ancestry provide one session identity for spawned tools; conflicting identities refuse before workflow writes. The Codex adapter pins its validated payload into every POSIX Bash command and core-hook child, so sandboxed macOS does not depend on `ps` ancestry.
* Harness-native method includes remain one mutable checkout-wide surface, so concurrent sessions in different spaces can still race on ambient delivered rules. Windows and shared-process harness sessions retain shared-cursor behavior where no distinct identity is available.
## [2.6.79] - 2026-08-25

Stop-hook recovery now preserves an opaque load-steering continuation token ahead of the potentially large rule payload without changing the required apply-then-continue action order. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; active workflows need no state migration.

* The recovery message prints the step-two `continue` command before `rules_content` so host-output truncation cannot discard the cursor, while explicitly refusing to run it until the current rule chunk has been applied.
* `t121` independently pins transport order (token before payload) and execution order (apply the current chunk before invoking `continue`), preventing either property from masking a regression in the other.

## [2.6.78] - 2026-08-24

`aidlc plugin sync` now distinguishes a clean no-plugin setup from configured plugin roots that cannot be composed. **Upgrade:** refresh your `dist/<harness>/` shell and update automation to treat exit 1 as an incomplete plugin installation when every configured root is unusable.

* **Behavior change:** when plugin-root environment variables are configured but none points to a root containing `hooks/compose.ts`, `aidlc plugin sync` exits 1 and names every unusable root.
* Failures and mixed-root warnings distinguish a missing `hooks/compose.ts` from a root directory that does not exist.
* With no configured plugin roots, the command retains the exact `no installed plugins; nothing to sync` exit-0 no-op; mixed sets warn for each skipped root, compose valid roots, and retain the existing success line.

## [2.6.77] - 2026-08-24

Stage validity now fingerprints zero-Unit Construction outputs at the same stage-level paths the engine emits, and fresh workspace births expose an inspectable CodeKB parent without changing per-repository storage semantics. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; existing workflows need no migration.

* Validity receipt capture, inspection, status, and approval guards now share the effective-plan decision for per-Unit stages. Plans that skip Units Generation resolve exactly one stage-level artifact instance and ignore stale per-Unit directories, while ambiguous plan state remains a non-blocking warning.
* Validation Basis schema 3 distinguishes the corrected effective-plan resolver; schema-2 receipts remain untracked until normal re-completion instead of falsely reporting unchanged zero-Unit artifacts as stale.
* Zero-Unit routing, completion evidence, summary/reviewer cardinality, review fingerprints, and upstream-coverage consume filtering now ignore stale Unit DAGs consistently and bind the emitted stage-level artifact paths.
* Intent birth now ensures the active space's `codekb/` parent exists, matching the shape created for named spaces. Per-repository `codekb/<repo>/` stores remain lazy and are still created only when Reverse Engineering writes them.
* Source-freshness receipt tests that execute repeated CLI chains now carry explicit 60-second case timeouts for stable loaded-suite runs.

## [2.6.76] - 2026-08-24

Review-freeze and consolidated-summary confirmation no longer form a deadlock when unchanged answers are confirmed twice, and stale-source recovery can now replace an old Review section through a request-bound, stage/Unit-scoped freeze suspension. Reviews can no longer begin before confirmed answers or complete verifiable required outputs. Refusals now name the executable recovery for the stage's current state. **Upgrade:** refresh your `dist/<harness>/` shell so the updated logger, state checks, protocols, and review-freeze hook are installed together.

* Repeating an identical, fully scoped summary confirmation keeps the earlier confirmation's authorization for an unchanged output document; changed answers still require a fresh confirmation.
* `aidlc-log.ts review` now refuses requests until summary evidence is valid and every verifiable required output document exists. New per-Unit requests preserve base v2's strict admission: malformed Unit DAGs, a missing DAG without a matching active Bolt, and a resolved DAG that omits the named Unit refuse. `--retry-pending` re-dispatches an already accepted request without reapplying new-request membership admission, so a later resolved topology change cannot strand its verdict. Stage-level requests skip all-Unit output enumeration when the Unit set cannot resolve. Required outputs for a named Unit are still checked and rechecked when recording the result.
* When the authoritative Unit set resolves, a stage-level review request for a per-Unit stage covers every Unit and therefore requires every Unit's applicable required outputs. The existing `AIDLC_SKIP_ARTIFACT_GUARD=1` recovery switch also bypasses this new review-time existence check.
* A validated pending stale-receipt recovery request suspends review-freeze only for its stage/Unit while the stale condition remains in the current session. Restoring reviewed workspace source, recording the verdict, or restarting/resuming the session re-arms freeze; a same-second cross-shard session-boundary tie keeps the request retryable but fails closed with no write suspension. Restoring output-document bytes does not clear audit-recorded artifact staleness. `--retry-pending` reopens the scoped suspension without restoring budget.
* A new Bolt attempt floors pending review recovery from the prior attempt, including same-second cross-shard boundary ties in either shard filename order.
* Known limitation: a per-Unit stage without an authored `unit-of-work-dependency.md` requires a stage-level review receipt once its Bolts have closed. Author that document before Construction to retain per-Unit review coverage.
* Review-freeze directs reviewer suggestions to the gate without applying them. Other recovery refusals direct active stages to Request Changes, `[R]` stages to `/aidlc --stage <slug>`, completed stages to restore reviewed source or redo the stage, and off-plan stages to a scope that includes them.
* Cursor guard calls reuse one lightweight review-freeze command/target parse per invocation and skip the freeze subprocess only when that exact parse proves there is no write target, restoring margin below the per-tool timeout without weakening real-write enforcement.

## [2.6.75] - 2026-08-24

Shared write hooks now normalize project-relative file payloads before applying audit and sensor path logic, enforcing the hooks' absolute-path invariant even if an adapter boundary is bypassed. **Upgrade:** refresh your `dist/<harness>/` shell; existing workflows require no migration.

* Artifact audit logging resolves relative record paths before its path gates while preserving project-prefix redaction in the recorded `File` value.
* Sensor dispatch resolves relative paths before its recursion guard, glob match, and `--output-path` argument while preserving gate-only sensor isolation.

## [2.6.74] - 2026-08-24

Defined quality targets now remain binding from Code Generation through Build and Test: every measurable target is inventoried from NFR Requirements, NFR Design, and the approved Testing Contract, then finalized with evidence before the stage can succeed. **Upgrade:** refresh your `dist/<harness>/` shell so the updated Construction stage and protocol guidance are installed.

* Code Generation treats measurable quality targets as required inputs and forbids lowering, relaxing, or disabling a target to manufacture a pass.
* Build and Test executes every applicable generated check, permits deployed-environment deferral only to a named owning validation stage, and keeps deferred or missing evidence visibly `Unverified`.
* The target matrix records target ID and source, expected and actual values, evidence, owning stage, and a final `Met`, `Not Met`, or `Unverified` verdict on every exit path; `N/A` is valid only when no target applies.
* `Not Met` and `Unverified` targets now enter the same bounded Build-and-Test failure-escalation ladder as command failures, preserving the Code Generation loop-back added in 2.6.20.

## [2.6.73] - 2026-08-24

Scope cost previews now describe the workflow the engine will actually run, and approval gates expose how long the current gate attempt has been waiting for a person. **Upgrade:** refresh your `dist/<harness>/` shell to install the corrected preview, status, and doctor behavior; existing workflow records need no migration.

* Scope confirm and intent-creation messages omit the "per unit of work" clause when `units-generation` is skipped, because those Construction stages run once without a Unit DAG.
* Cold-start previews apply the same Greenfield reverse-engineering skip as intent creation, so their stage and approval-gate counts match the generated workflow.
* `/aidlc --status` shows the current attempt's organic approval-gate timestamp and pending duration when the current stage is awaiting approval; resolved, recovered, revalidated, prior-attempt, and causally ambiguous cross-shard ledger rows do not create or replace a waiting timestamp.
* `/aidlc --doctor` adds a passing advisory for current-attempt approval gates open longer than 24 hours, identifying them as waiting for a human rather than stuck and directing operators to `/aidlc --status`.

## [2.6.72] - 2026-08-24

Gate-bound sensors now run once against each matching final deliverable and can enforce blocking findings without accepting stale or unverified bytes. **Upgrade:** refresh your `dist/<harness>/` shell so the expanded sensor schema, compiled bindings, gate dispatcher, and audited override flow are installed.

* Sensor manifests accept `fire_on: write|gate` (default `write`) and `default_severity: advisory|blocking`; compiled `sensors_applicable` entries carry firing mode, severity, category, and path filter.
* `claim-sources`, `required-sections`, and `upstream-coverage` now run at approval boundaries, while write-fired sensors remain advisory. Gate dispatch skips deliverables outside each sensor's `matches` capability.
* Blocking gate sensors fail closed on findings, unavailable or malformed evaluation, timeout, identity mismatch, and artifact bytes changing during or after evaluation. The gate transaction rechecks matching artifact fingerprints before opening.
* A human-backed `Override blocking sensors` choice may override a stable blocking result in gated mode. The override is unavailable in autonomous mode, is recorded on `STAGE_AWAITING_APPROVAL`, and is consumed and audited when revalidating an already-open gate.

## [2.6.71] - 2026-08-24

Non-English workflows now keep the agent's human-facing conversation and structured-question prose in the resolved conversation language, including status updates and narration between tool calls from the orchestrator and delegated agents. **Upgrade:** refresh your `dist/<harness>/` shell; existing workspaces keep their own memory tree, so merge the extended `Conversation language — what to localize` rule into each `aidlc/spaces/<space>/memory/org.md` by hand and start a fresh session for it to load.

* Chat messages, status updates, progress reports, and transitional narration between tool calls now follow the resolved conversation language on every turn, for orchestrators and delegated agents alike.
* Structured-question `prompt`, `header`, `options[].description`, and free-text follow-ups are localized, while protocol-defined `options[].label` literals such as `Approve` and `X. Other (please specify)` remain unchanged English tokens.

## [2.6.70] - 2026-08-24

Bugfix and refactor workflows now carry verified changes through the existing deployment path instead of stopping after Build and Test. **Upgrade:** refresh your `dist/<harness>/` shell to pick up the expanded scope grids, deployment fallback, and skip-provenance fix.

* The `bugfix` and `refactor` scopes now execute Deployment Pipeline and Deployment Execution, matching the deployment tail already used by `security-patch`; Environment Provisioning and the remaining Operation stages stay skipped.
* When Deployment Pipeline is conditionally skipped because the workspace pipeline is already adequate, Deployment Execution receives its missing pipeline artifacts as expected absences and uses the existing workspace configuration instead of entering missing-artifact recovery.
* `STAGE_SKIPPED` records now distinguish conditional runtime skips from explicit jumps, so jumping over an on-path producer no longer hides its missing required output as an expected absence.
* Bugfix now runs 9 of 33 stages with 6 approval gates; Refactor runs 10 of 33 stages with 7 approval gates.

## [2.6.69] - 2026-08-24

Per-unit source review now binds the manifest and claimed source at dispatch, and sibling-repository Bolt worktrees preserve application source under root `aidlc/` and `.aidlc/` directories. **Upgrade:** refresh your `dist/<harness>/` shell; write a valid `source-manifest.json` before every per-unit workspace review request, and use `--retry-pending` to re-dispatch after any pre-verdict source change.

Code-generation review receipts now attribute reviewed application source per Unit and fail closed when changed source is unclaimed. **Upgrade:** refresh your `dist/<harness>/` shell. In-flight Code Generation runs retain migration-compatible behavior until their next per-unit review; that review must write `construction/<unit>/code-generation/source-manifest.json` before its terminal verdict.

* `aidlc-log.ts review` validates `source-manifest.json` before dispatch and records request-side `Source Fingerprint` and `Unit Source Fingerprint` bindings. The terminal verdict recomputes both and refuses source or manifest changes; `--retry-pending` refreshes the bindings only when the reviewer is actually re-dispatched. `AIDLC_SKIP_SOURCE_FRESHNESS=1` no longer permits dispatch without the manifest the reviewer must inspect.
* Completion validates modern receipts newest-first, invalidates only Units whose exact/directory claims changed, and lets a newer fresh claimant own intentional shared-file integration. Invalidated Units use the existing one bounded stale-receipt recovery and must stop editing declared artifacts, manifest bytes, and claimed source paths afterward.
* One shared baseline producer stamps workflow birth, stage jumps, and workspace-writing stage starts. A jump computes one content-addressed snapshot and repeats that exact `Source Baseline` on its companion `STAGE_STARTED`, so stage-major merge/completion cannot clear the jump boundary. An unchanged Git-less greenfield binds to a content-addressed empty source state, while application files without Git remain unbindable. Modernity is monotonic: if any modern source-binding evidence survives, a qualifying boundary with no `Source Baseline` now refuses as `inconsistent with other modern source-binding evidence` instead of downgrading to legacy. Cross-shard ambiguity applies only when tied boundary rows carry differing baseline values: field-free pre-upgrade ties retain migration fail-open and identical modern fingerprints remain usable, while differing modern values remain unbindable. Rejection never replaces the completion baseline; when the prior attempt has a validated swarm aggregate, `GATE_REJECTED` carries only that accepted fingerprint so reject/redo can start its next merge without grandfathering unclaimed source.
* Canonical source snapshots bind Git mode/type as well as raw-aware content, so executable-bit, symlink, and gitlink changes invalidate the owning receipt. The preceding OID-only snapshot format remains migration-compatible by content equality. Ignored exact and directory-prefix checks now use HEAD-derived evidence rather than the caller's real index, so a force-added ignored descendant is refused as `contains ignored application source`; an exact claim on an ignored directory reports the ignore rule before path-shape probing. Symlink claims also refuse ignored, missing, cyclic, or out-of-repository targets at every hop, including chains that leave the repository and re-enter, and explain that claims bind link text rather than target bytes. Slashless claims are judged from the current path shape: a current directory still requires trailing `/`, while a legitimate committed-directory-to-file replacement can use an exact claim.
* Autonomous swarm prepare stamps durable intent/Unit/batch/stage/floor provenance into each worktree creation and records the full DAG Unit obligation set on every `SWARM_STARTED`. Completion refuses a changed live DAG with `the Unit DAG changed during the current swarm attempt (missing attempt Units: ...; added Units: ...). Restore unit-of-work-dependency.md to the attempt-bound Unit set or restart the stage attempt.` Uniformly fieldless current-attempt `SWARM_STARTED` rows retain pre-upgrade migration behavior only while the attempt has no modern convergence or source-merge evidence; stripping the field after a modern `Source Commit`, bypass marker, or `SWARM_SOURCE_MERGED` row fails closed. A mix of fieldless and field-bearing rows also fails closed as inconsistent. Gate-opening refusals now say `Refusing to present the approval gate` instead of incorrectly saying `Refusing to complete`. Finalize attests the immutable base commit plus a content-addressed raw-aware `Base Source Listing`, validates the worktree-scoped unit fingerprint and manifest bytes, and refuses a base-to-worktree footprint outside reviewed claims before retaining the immutable reviewed-source commit. Source merge authority no longer depends on live autonomy or a readable DAG, is correlated to the selected intent and exact current lifecycle, canonicalizes filesystem aliases, recovers omitted selectors from the creating worktree, and emits `SWARM_SOURCE_MERGED` whose `Previous Source Fingerprint` uses the same opening-link domain as the chain validator: the stage-baseline listing hash for the first link or the prior accepted/current aggregate for later links. Durable `worktree-meta.json` or retained reviewed-source refs make modernity monotonic: removed creation/swarm fields now refuse as inconsistent instead of falling back to `bolt-<slug>`. Modern missing, stale-attempt, explicitly selector-mismatched, and ambiguous authority fails closed; true pre-upgrade fieldless convergence on a pre-binding worktree retains branch-merge compatibility.
* The unauthenticated Bolt-local pending-source-merge receipt has been removed. Squash and merge strategies capture the staged Git result, commit with `--no-verify`, and prove that exactly one commit with that tree landed before comparing the live aggregate to the landed commit's raw-aware listing. Before mutation, a bound merge refuses when the main checkout's effective configuration contains any `merge.<name>.driver` command, naming complete keys (including subsection spaces) and remedies to remove that configuration or use `AIDLC_SKIP_SOURCE_FRESHNESS=1`; builtin behavior without a configured command remains allowed. Repository merge configuration is therefore inside the trusted computing base for source attribution. This changes the Git hook profile of these framework source merges: `pre-commit`, `commit-msg`, and `pre-merge-commit` no longer run, `post-merge` no longer fires on the merge strategy, and `post-commit` now fires there too. This accepts legitimate three-way shared-file integration while still refusing uncommitted post-commit writes as `post-merge source does not match landed merge commit` and refusing a hook-created replacement/additional commit as `unexpected commit or tree change landed during the source merge`. Both use the non-retryable `[merge-succeeded:<sha>] ... no SWARM_SOURCE_MERGED authority was emitted. Do not retry this merge.` recovery, which also preserves the worktree when the post-result audit append fails. Worktree audit rows now use project-relative paths and all structured audit field values redact the local project prefix. Worktree metadata stores hashed Git common-directory provenance; legacy plaintext metadata remains readable. Merge/discard refuses a different repository before mutation; discard scans every intent, requires a creation row corroborated by live repository evidence, cross-checks metadata, and fails closed when modern authority is unreadable. Ordinary non-swarm merges clean the framework-owned root `.aidlc/` shell before non-forced worktree cleanup, so runtime attestations cannot block a successful merge while application residue remains protected.
* The source-freshness off-switch covers global binding, per-unit attribution, baselines, and swarm footprint verification. Modernity also survives whole-row audit loss when the selected intent still holds baseline/unit snapshots, source manifests, or intent-matching worktree metadata; another intent's artifacts do not affect it. Pre-upgrade fieldless receipts, missing baselines, and worktrees without durable modern evidence retain the documented migration fail-open; present but unbindable, corrupt, or bypass-marked modern evidence fails closed without the switch. Sibling-repository worktrees derive their source role from durable `repoSelector` metadata, exclude only injected worktree/record files, and retain reviewed application bytes under root `aidlc/` and `.aidlc/` through fingerprinting, footprint verification, immutable binding, merge, and cleanup.
## [2.6.68] - 2026-08-24

Summary-confirmation receipts now bind to the semantic questions and summary content the human reviewed while allowing the required post-generation assumption section. The contract is versioned, preserves legacy receipt verification, and reports an actionable recovery path for invalidated confirmations. **Upgrade:** refresh your `dist/<harness>/` shell so the scoped receipt, Markdown visibility, and recovery contracts stay aligned.

* New receipts carry `Hash Scope: confirmed-content-v1` and hash normalized semantic content in file order, including all visible Q<n> sections, repeated feedback, and follow-up questions after an assumption decision. One post-summary `Assumption Confirmation` section is excluded; any other visible Markdown or raw-HTML heading after the summary fails closed. Markdown comments and literal code/HTML contexts are parsed consistently so hidden examples cannot launder a new question. Equal-time evidence in different audit shards also fails closed when receipt or artifact-write order cannot be proven. Receipts without a scope retain legacy whole-file verification and require reconfirmation after an allowed append.
* Summary-validation errors lead with the ordinary fresh-decision and answer recovery path; terminal-review freezes retain the rejection-and-revision path. Isolated runs name their valid `--single` confirmation and completed-report sequence instead.

## [2.6.65] - 2026-08-23

Stage graph compilation now rejects ambiguous producers before consumers can resolve an artifact by file order. **Upgrade:** refresh your `dist/<harness>/` shell; existing custom stages or plugins that declare the same consumed artifact in `produces` or `optional_produces` must rename one output or update the consumer.

* `aidlc-graph compile` now reports `Duplicate producers for consumed artifact`, naming every producing stage file and slug plus one consuming stage.
* Shared artifact names remain valid when no stage consumes them, including the shipped multi-stage `traceability` output pattern.

## [2.6.64] - 2026-08-23

The Kiro IDE distribution now ships only IDE-native agent and permission surfaces. **Upgrade:** re-copy `dist/kiro-ide/` into your project, then remove any `.kiro/agents/aidlc.json`, `.kiro/agents/aidlc-*-agent.json`, and `.kiro/settings/cli.json` files left by an older overlay copy.

* Kiro IDE now ships the conductor as `.kiro/agents/aidlc.md` and all 14 personas as Markdown with native `tools:` grants and `permissions.rules`; CLI agent-v1 JSON and `settings/cli.json` files are no longer included.
* `/aidlc --doctor` accepts either the Kiro CLI JSON conductor or Kiro IDE Markdown conductor and checks `settings/cli.json` only for CLI-shaped installs.
* Plugin composition validates Kiro IDE dispatch targets by their installed Markdown capability grants, rejecting empty or malformed permissions with actionable remediation while leaving Kiro CLI trust checks unchanged.

## [2.6.62] - 2026-08-23

Completed-stage artifact drift is now detected through optional audit receipts and surfaced as an advisory without changing workflow routing. Existing workflows require no migration: receipt-less completions remain untracked and fail open, while stages become tracked on their next normal completion. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `next` keeps its normal directive kind and adds a machine-readable `stage_validity` advisory for drifted, downstream-revalidation, or unavailable results. Untracked-only completions are reported by `/aidlc --status` without adding per-turn noise for pre-upgrade histories or work to the statusline.
* Completion tools capture report-time schema-2 structure/content fingerprints for resolved artifact instances. Capture failures still complete the stage, record a visible `Validation Warning`, and leave that completion untracked.
* Artifact filenames and CodeKB ownership now come from one shared vocabulary, including `build-test-results` and `load-test-results` resolving to `test-results.md` and `traceability` resolving to `traceability.json`.
* Public audit append commands refuse `STAGE_COMPLETED`; the owning single-stage report path retains its internal atomic lifecycle pair.
## [2.6.61] - 2026-08-23

Plugins can now extend `/aidlc --doctor` with selection-aware, fail-loud install checks while preserving advisory findings that do not block CI. **Upgrade:** re-copy `dist/<harness>/` for the updated `aidlc-utility.ts`, then refresh and re-compose each plugin's `dist/plugins/<name>/<harness>/` projection to install its doctor script.

* Ship an optional `tools/<plugin>-doctor.ts` script; doctor runs it only when that installed plugin is enabled.
* Emit `{"checks":[{"pass":boolean,"label":string,"fix"?:string,"severity"?:"error"|"advisory"}]}` on stdout. Broken, timed-out, or malformed scripts become bounded doctor failures instead of crashing the diagnostic.
* Error-severity failures exit 1; advisory failures remain visible in live output and `--doctor --export` without changing the exit code.
* `test-pro` now includes a deterministic, read-only reference doctor script that verifies its composed sensors, scope, and agent.

## [2.6.60] - 2026-08-23

Kiro CLI and IDE agent Markdown no longer carries the unsupported Claude-only `disallowedTools` key; nested delegation remains blocked by Kiro's native agent tool configuration. **Upgrade:** refresh your `dist/kiro/` or `dist/kiro-ide/` shell, and re-run compose for installed Kiro plugins. An unchanged same-plugin persona is migrated automatically; if doctor reports an already-composed unsupported value, fix the plugin source, remove the named installed persona, and re-run compose.

* Kiro packaging requires exactly one authored `disallowedTools: Task` denial, then omits that inert line from all 14 projected agent personas on both Kiro distributions.
* Kiro plugin composition strips the supported `Task` denial from new personas, migrates exact unchanged same-plugin legacy copies without clobbering edits, and drop-logs duplicate, unsupported, or already-composed invalid values with recovery guidance.

## [2.6.56] - 2026-08-23

Kiro CLI agent-v1 hooks retain the literal selectors required by the host's canonical-name/alias glob semantics, while the adapter now normalizes selected payloads before shared guards and observers run. **Upgrade:** re-copy `dist/kiro/` into the project.

* The existing literal `fs_write` and `fs_read` registrations continue to select the live-proven write/read alias families exactly once; the adapter normalizes create, replace, and append payloads to Write/Edit, audits each project-relative or batched target, and forwards all supported path fields to reviewer scope and review freeze.
* Literal `subagent` registrations do not select `subagent_response`; legacy crew and defensive direct-dispatch payloads share one normalization path, and a nonblank `task` cannot be hidden by a blank higher-priority `prompt` during stage-rule delivery.
## [2.6.55] - 2026-08-22

Run-stage directive emission now creates each stage diary deterministically before the agent begins work, eliminating failed read probes for a file that is expected to be absent on first entry. Internal Stop-hook probes remain write-free, and size-bounded waves create diaries only for the Unit entries actually carried by the emitted directive. **Upgrade:** refresh your `dist/<harness>/` shell so the updated engine and stage guidance are installed.

* `aidlc-orchestrate.ts next` creates `memory.md` from the shipped template when it emits a real run-stage directive, preserves existing diary content on re-entry, and skips the Stop hook's internal read-only consultation.
* Per-Unit waves create diaries only after applying the directive transport limit, so deferred same-batch Units remain untouched until a later directive includes them.
* Stage guidance now forbids using read tools to probe maybe-absent files, provides one idempotent POSIX fallback command for the rare case where a diary is missing, and identifies `question-rendering.md` as a sibling of the orchestrator `SKILL.md`.

## [2.6.54] - 2026-08-21

Subagent completion auditing now runs only while the active workflow state is explicitly `Running`, instead of writing whenever a state file or audit shard remains from an earlier workflow. **Upgrade:** refresh your `dist/<harness>/` shell so project-wide SubagentStop hooks no longer write audit entries or health heartbeats during non-AI-DLC sessions or after workflow completion.

* SubagentStop exits when active intent state is absent, unreadable, or does not declare `Status: Running`; a running workflow still records `SUBAGENT_COMPLETED` and creates the clone's audit shard if needed.

## [2.6.53] - 2026-08-21

Kiro IDE hook guidance now reflects that tool-argument delivery varies across supported IDE generations instead of describing all payloads as empty. Hook registration and enforcement behavior are unchanged. **Upgrade:** refresh your `dist/<harness>/` shell to receive the corrected generated comments, Kiro IDE orchestrator guidance, and version metadata.

* Reviewer-scope, stage-rule-delivery, and state-transition guidance now explain that Kiro IDE leaves the relevant PreToolUse hooks unregistered because tool arguments are not uniformly delivered and payloads lack a stable reviewer identity/target contract.
* The empirical payload reference preserves the measured Kiro IDE 0.12 and 1.0.165 empty-input captures while recording issue #763's reported 1.0.309 populated PreToolUse, delegation, shell/write, and PostToolUse inputs as a non-universal later-build data point.

## [2.6.52] - 2026-08-21

Reviewer-bearing approval gates and review receipts now prove that the configured reviewer inspected the current artifact before the gate is presented. **Upgrade:** re-copy your `dist/<harness>/` shell so every harness receives the strengthened state and review-log guards. Closes #551.

* `report --result awaiting-approval` validates both new and already-open gates; direct rejection from an active stage records `Active → Revising` without fabricating an approval-gate event.
* `report --result revised` and approve-time revision recovery persist `[R]` until a fresh post-rejection review passes and the normal gate re-entry is recorded.
* `aidlc-log.ts review` fingerprints artifacts when dispatching and refuses a verdict if the bytes changed before completion; only `--retry-pending` may repeat an outstanding ordinal.
* Per-unit reviews require membership in the authoritative Unit DAG, or a matching active Bolt for legacy no-DAG swarms; Unit-scoped receipts can no longer satisfy a no-DAG stage-level fallback.

## [2.6.51] - 2026-08-21

Steering continuation tokens are now single-use on every harness: Claude, Codex, Copilot, Cursor, Kiro CLI, Kiro IDE, and opencode share one engine-owned, crash-safe continuation cursor in the active-directive marker, closing the sessionless same-token replay carve-out accepted in PR #749 (issue #762). **Upgrade:** replace the whole `dist/<harness>/` shell in one quiescent swap (no AI-DLC command or hook running) - mixed old/new tool files are unsupported - then run a fresh `next`; a matching in-flight token instead migrates atomically. Rolling back to an older release restores its sessionless replay behavior until re-upgraded.

* **Behavior change:** presenting the same continuation token twice now returns an error directive ("This continuation token is no longer current for this workflow. Run a fresh `next`; do not reuse an earlier token.") instead of repeating the successor. Concurrent uses of one token have exactly one winner on every harness; recovery is always a fresh `next`.
* `continue` keeps all native token validation, then compares the SHA-256 of the complete presented token with the persisted current token inside the active-directive transaction and atomically publishes the exact successor - or a tokenless `run-stage` - before stdout. New marker publications record the installed harness as `cursor_harness` (marker v2, optional on read); pre-upgrade markers migrate on the first matching `continue` or fresh `next`.
* Fresh `next` must now commit its first directive before emitting on every harness. Publication failure or contention yields "The directive could not be published, so no work directive was issued. Retry the command; if coordination remains busy, run `/aidlc --doctor`." - replacing the previous Copilot-only wording and the non-Copilot fail-open delivery.
* Missing, malformed, oversized, v1, cross-harness, and pre-state bare-space markers permit one natively validated recovery continuation under the same transaction; a mismatched token is stale, not a bootstrap opportunity.
* The exactly-one-winner guarantee requires the marker and lock paths on one local filesystem (atomic rename, exclusive directory creation, coherent cross-process visibility); NFS/SMB/FUSE-style shares are unsupported, and sudden power-loss durability is outside the claim. See the new "Atomic continuation cursor" section in the Developer Reference for the crash/retry matrix, migration, rollback, and per-harness residual limits.

## [2.6.50] - 2026-08-21

Approval checkpoints now reject replies that do not exactly match a currently offered decision, while change-request feedback travels separately from the selected choice. **Upgrade:** refresh your `dist/<harness>/` shell so the gate protocol, deterministic transition guards, and harness instructions stay aligned.

* Protected approvals accept only `Approve`, plus `Accept as-is` once the stage has reached three revision cycles; arbitrary prose can no longer commit `GATE_APPROVED`.
* Protected rejections require `--user-input "Request Changes"` and carry the requested revision separately in `--reason`, preventing feedback text from being mistaken for the selected decision.
* Invalid or cancellation replies leave the gate and human-turn evidence untouched and direct the conductor to re-render the original held question with every offered choice, including conditional options.
* Summary-confirmation refusals quote the unmatched reply and restate their exact two choices without recording a receipt.

## [2.6.49] - 2026-08-21

Frontmatter string-list fields now accept single-line YAML flow sequences as well as block sequences, preventing valid inline lists from silently parsing as empty. **Upgrade:** refresh your `dist/<harness>/` shell to install the corrected parser.

* Flow-style YAML lists now parse for scope keywords, agent examples, and stage list fields, including empty sequences, quoted commas, and trailing YAML comments.

## [2.6.48] - 2026-08-21

opencode and GitHub Copilot installations now ship mutable persona memory references on the `default` space seed, matching Cursor, so `/aidlc space default` no longer rewrites unchanged framework files while later space switches still repoint every managed persona. **Upgrade:** refresh your `dist/<harness>/` shell to replace placeholder-bearing persona copies with the concrete default-space seed.

* `/aidlc space default` leaves shipped opencode, GitHub Copilot, and Cursor persona files byte-identical.
* `/aidlc space <name>` continues to repoint both inline and harness-native persona copies to the selected space.
* Packaging checks reject opencode or GitHub Copilot persona emissions that retain the mutable `<active-space>` placeholder.

## [2.6.47] - 2026-08-21

Kiro plugin projections now use the composition mechanism supported by each runtime generation. **Upgrade:** rebuild or re-copy Kiro plugin projections; remove any scripted dependency on the retired `hooks/aidlc-plugin-compose.kiro.hook` filename.

* Kiro CLI plugin projections no longer emit an inert hook registration; use `aidlc plugin sync` or run `hooks/compose.ts` explicitly after the folder-drop.
* Kiro IDE plugin projections now emit `.kiro/hooks/aidlc-<plugin>-compose.json`, a v2 `SessionStart` registration that invokes a cross-platform Bun launcher from the workspace root without relying on an unsupported `PLUGIN_ROOT` variable or a POSIX shell.

## [2.6.46] - 2026-08-21

Kiro CLI `/aidlc` commands now dispatch deterministically on generations that deliver the raw typed prompt to `userPromptSubmit`: `/aidlc --status`, `space`, `space-create`, `intent`, and other routed invocations previously became a silent no-op when the hook expected only an expanded skill body. **Upgrade:** refresh your `dist/kiro/` shell to install the corrected verb interceptor.

* Raw prompts beginning with `/aidlc` now recover their complete shell-normalized argument vector for terminal dispatch, engine pre-dispatch, or guarded forwarding.
* Expanded skill bodies continue to recover arguments from the forwarding-loop anchor first, preserving existing behavior when both payload shapes are present.
* Mid-sentence `/aidlc` mentions and `/aidlc-foo` text remain inert.

## [2.6.45] - 2026-08-21

Diagnostic exports now read Kiro's turn-scoped markers from their canonical project-level location, so exported evidence accurately reflects the active latch and counter. **Upgrade:** refresh your `dist/<harness>/` shell to install the corrected diagnostic exporter; existing workflow state needs no migration.

* The diagnostic bundle now reports the read-only latch and turn counter from `<project>/aidlc/`, the path the Kiro seam writes, instead of the record directory.

## [2.6.44] - 2026-08-21

Codex structured `request_user_input` selections now mint the same `HUMAN_TURN` evidence as typed prompts, without treating empty, cancelled, timed-out, auto-resolved, error, or malformed responses as human judgment. **Upgrade:** refresh `dist/codex/`, then re-run `bun scripts/package.ts codex trust --project "/absolute/project/path"` and replace the existing hook trust tables before starting a fresh Codex session.

* The new PostToolUse registration routes `request_user_input` through the existing record-human-turn target only when `tool_response` is the Codex JSON-encoded `answers: Record<questionId,{answers:string[]}>` contract and every selected value is explicit, nonblank, and passes the shared cancellation-boilerplate floor.
* Completed-looking `{}` payloads and cancellation metadata fail closed; substantive selections remain valid, and values such as `Abort` count when they exactly match an option the question actually presented.
* Codex duplicate delivery replays the first response and emits exactly one `HUMAN_TURN`; projects without active workflow state remain untouched.

## [2.6.43] - 2026-08-21

Explicit resume now means continue immediately: `/aidlc --resume` no longer repeats the session re-entry Resume / Redo / Jump / Start Fresh menu before returning to the saved stage. Bare `/aidlc` still offers that menu when a harness session re-enters existing work. **Upgrade:** refresh your `dist/<harness>/` shell; existing workflow state needs no migration, and legacy Copilot resume markers are superseded by the next explicit resume.

* `/aidlc --resume` falls through to the normal load-steering and stage-routing path after the existing parked-workflow and no-state guards.
* Bare `/aidlc` session re-entry keeps the four-option menu and its `report --result resumed --user-input "<answer>"` routing for Resume, Redo, Jump, and Start Fresh; OpenCode performs a read-only status probe because its plugin cannot inject session-start context.
* `/aidlc --resume --stage <slug>` honors the explicit target and uses the normal jump path.
* Copilot treats `report --result resumed` as a plain report instead of requiring an engine-armed resume gate; legacy selected-marker skip recovery remains supported.

## [2.6.42] - 2026-08-21

Front/report composition now carries one approved, nonblank `birthDescription` into same-turn intent creation without shell expansion or placeholder fallback. **Upgrade:** refresh your `dist/<harness>/` shell so the composer contract, conductor instructions, and birth command quoting stay aligned.

* Task-backed proposals preserve the original task text exactly; report-only and task-less proposals derive a grounded description from the approved report/plan before birth.
* Compose and scope-routed descriptions that begin with `--` are retained as task text instead of being discarded as unknown flags.
* Engine-generated `next` commands place the description after the literal `--` delimiter, and `intent-create` uses `--arguments=<value>` with POSIX-safe single-argument quoting, so leading flags, `$()`, backticks, variables, quotes, and newlines remain literal input.

## [2.6.41] - 2026-08-21

Workspace detection now follows nested container layouts far enough to find application roots such as `services/api/src/main.py`, preventing incremental scopes from misclassifying existing code as Greenfield and skipping Reverse Engineering. The deterministic fallback evaluates eligible container directories independently up to three levels below the workspace root, aggregates every Brownfield hit without double-counting source files, and reports each hit's relative path. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `bugfix`, `refactor`, and `security-patch` workflows now detect codebases nested within up to three container levels instead of only checking top-level containers.
* `Nested Root` audit data and `nestedRoot` detect output now use slash-joined workspace-relative paths such as `services/api`, comma-joining multiple detected roots in deterministic order.
* Each visited directory is evaluated at its own depth, so sibling projects remain distinct and source files or manifests in a fourth arbitrary container remain outside the documented three-level boundary.
* Hidden dirs, case-insensitive excluded and sample/documentation names, exact-case recognized source-directory names, symlinks, and non-directories are skipped at every container level; odd-case directories such as `SRC/` remain eligible containers.
* The Greenfield advisory now describes the three-container-level detection boundary; routing remains unchanged when no code is found.

## [2.6.40] - 2026-08-21

The shared Stop hook now preserves state-bound Resume waits before probing `next`, and its no-progress cap distinguishes real directive transitions from audit or timestamp noise. **Upgrade:** refresh your `dist/<harness>/` shell so the shared Stop hook and active-directive evidence reader are updated; Copilot's session-owned Stop path remains unchanged.

* A sessionless Resume choice with an exact state-bound `ask` marker now allows the turn under the active-directive lock before the Stop hook can overwrite it with a fresh probe. Foreign-session, stale-state, autonomous, or contended evidence fails safely.
* Shared directive fingerprints now include load-steering part/token/content, run-stage wave, `invoke-swarm` units, and dispatched worker/repo identity, so advancing chunks, waves, and batches reset the streak even when progress is audit-backed.
* The state component excludes `Last Updated`, preventing status-only timestamp writes from resetting a genuinely stuck loop; semantic state changes still reset the counter.

## [2.6.39] - 2026-08-21

Reverse Engineering now requires complete, current-attempt Code Knowledge Base evidence for every registered repository before approval or completion. **Upgrade:** refresh your `dist/<harness>/` shell so the complete artifact guard, ordered pipeline receipts, repo-scoped reuse evidence, and resume directives are installed.

* Every registered repository must contain all nine declared Reverse Engineering artifacts; a partial pre-existing Code Knowledge Base no longer satisfies the completion guard.
* Pipeline stages record ordered `PIPELINE_LINK_COMPLETED` receipts for every declared link, and gate entry plus every completion route require receipts from the current main or isolated attempt.
* Multi-repository Reverse Engineering maintains an independent receipt chain per scanned repository. A current-attempt, repo-scoped `ARTIFACT_REUSED` receipt with `Decision=keep` exempts only that reused repository; rejection, jump, and later stage-start boundaries invalidate older evidence.
* Pipeline directives expose completed links so an interrupted run resumes from the first missing link without accepting stale receipts from an earlier attempt or a different workflow mode.

## [2.6.38] - 2026-08-21

Testing Posture resolution now ignores HTML-commented examples while preserving visible prose, structured fields, and fenced notes. **Upgrade:** refresh your `dist/<harness>/` shell; contracts whose Testing Posture sections contain comments will re-resolve, so re-approve affected Code Generation plans.

* Commented headings and comment-only `Testing Posture` sections no longer select, truncate, or affirm a methodology; the resolver falls through to the real visible section or next visible memory layer.
* Visible `Methodology` and `Ordering` fields remain authoritative beside comments, and visible prose and fenced content remain in `applicable_notes`.
* Testing Contract input fingerprints retain each raw resolved section, including comments and fenced content, so comment-only changes still invalidate stale approvals.

## [2.6.37] - 2026-08-21

Code-generation review receipts are now bound to the workspace source state the reviewer inspected, and every completion route refuses when that state is stale. The same binding follows autonomous swarm work from finalize through source merge. **Upgrade:** refresh your `dist/<harness>/` shell so the source-fingerprint tools, guards, audit schema, and generated harness files are installed.

* `aidlc-log.ts review --verdict` adds `Source Fingerprint` to `REVIEW_COMPLETED` for `workspace_requires` stages. The git-native temporary-index fingerprint covers tracked, staged, unstaged, untracked, deleted, recursively initialized-submodule, and raw clean/process-filtered regular-file content without touching the real index; symlinks remain link-text, ignored paths remain outside the binding, and unexpected Git failures are recorded as `unbindable` and fail closed.
* `approve`, `advance`, `finalize`, and `complete-workflow` now refuse with a source-fingerprint mismatch when current source differs from the newest modern review binding. Revert the source edit or record the one bounded stale-receipt recovery review; that recovery remains available after the normal review iteration budget is exhausted. Already-`[x]` crash recovery still compares modern source bindings while skipping only receipt existence/cardinality.
* `AIDLC_SKIP_SOURCE_FRESHNESS=1` is the deterministic off-switch. A swarm finalized under it records `Source Freshness Bypass: true`, and source merge requires the same switch again; newly unbindable receipts fail closed, while fieldless pre-#629 receipts remain migration-compatible.
* Autonomous swarm finalize validates each receipt in its own Bolt worktree, rejects dirty initialized submodules, creates an immutable reviewed-source commit retained under `refs/aidlc/reviewed-source/<bolt>/<commit>`, and records its OID. `aidlc-worktree merge` consumes that exact object, rechecks branch movement, and compare-deletes framework-owned refs/branches.
* Explicit `--intent`/`--space` source merges resolve legacy Unit names against the selected intent's DAG before reading convergence evidence, and framework-created reviewed-source commits use an internal AI-DLC Git identity rather than requiring ambient user configuration.
* Known limitation (RFC #662): the stage-level fingerprint is workspace-global while receipts are per Unit, so it proves equality with the source seen by the newest review, not per-unit path attribution. Source changed before that newest review can be revalidated by one later receipt; per-unit attribution needs a machine-readable path manifest the engine does not yet produce.

## [2.6.36] - 2026-08-21

`aidlc-learnings.ts persist`'s write-idempotency now keys on the learning's own content, not its positional candidate id, and binds provenance (space + intent + stage) at `surface()` time instead of re-resolving live state inside `persist`. Candidate ids restart at `c1` on every `surface()` call, so a later run of the same stage in the same intent previously reused `c1` for a completely different learning and silently dropped the second write; re-resolving the active intent live also meant a surface-then-switch-intent-then-persist sequence could write under the wrong intent's marker. Fixes the follow-up findings from #735's own fix, across all five rounds of PR #747 review. **Upgrade:** re-copy your `dist/<harness>/` shell into the project. A pre-upgrade selections file now fails with `selections-json is malformed: missing or non-string space`; a replay whose pinned space/intent no longer exists also fails closed. Re-run the stage's `surface` step to regenerate the file before retrying `persist`.

* `cidMarker`'s third key component is now the full SHA-256 hash of the learning's text (`<!-- cid:<intent-slug>:<stage-slug>:<content-hash> -->`), not the candidate id or a truncated digest. An exact retry still hashes identically and dedups; different learning text cannot collide through a 32-bit prefix.
* `surface`'s output and the selections-json schema now carry `space`/`intent`, bound once at surface time; `persist` reads and uses these directly rather than re-resolving `activeIntent()`/`activeSpace()` itself. The audit read, audit write, and lock identity are all pinned to the same surface-time intent.
* Multiple intent records with no valid active-intent cursor now fail closed with an explicit error, rather than silently falling back to the shared `unscoped` identity.
* Markers and audit rows written under the prior candidate-id formats (pre-#735's `<!-- cid:<stage>:<id> -->` and #735's first fix's `<!-- cid:<intent>:<stage>:<id> -->`) or the earlier 8-hex content-hash revision are recognized for upgrade-time dedup, so a retried learning is not duplicated under the full-hash marker. Short-hash compatibility is text-gated so a 32-bit collision cannot suppress different content.
* `practiceFilePath` now also takes the surface-time-pinned space (round 2 review): the lock and audit were already pinned to it, but this path alone still fell back to whichever space happened to be live-active when `persist` ran, so a learning could land in the wrong space's `project.md`/`team.md`.
* The sensor branch's own dedup now keys `SENSOR_PROPOSED` on `(stage, sensor id)` rather than `(stage, candidate_id)` (round 2 review) — the same unstable-key defect class as the first bullet above, recurring in the sensor path. Stage stays in the key: binding a manifest to a stage's frontmatter is per-stage even though the manifest file itself is a per-project singleton, so a second, unrelated stage independently recommending the same sensor still gets bound.
* A legacy-marker match is now gated on the marked line's own text equalling the current selection's text (round 2 review) — a legacy marker is keyed on candidate id alone, so a genuinely different learning landing on the same positional candidate id post-upgrade was previously mistaken for a retry of the original and silently dropped.
* An unscoped selections replay now fails closed if intent records appeared after `surface`: `intent: null` can no longer be safely attributed once a live/lone intent exists, so the error directs the user to re-run the stage's `surface` step and regenerate the selections file.
* Selections-file `space` and non-null `intent` values are validated before any path is built. Space must use the lowercase slug shape; intent must be a single safe record-directory name, so malformed provenance cannot escape `aidlc/spaces/` or redirect audit paths.
* `persist` also verifies inside the lock that the pinned space and non-null intent record still exist, and rejects a `--slug` that differs from the selections file's `stage_slug`, so stale or contradictory provenance cannot create partial records or misattribute audit rows.
* Learning hashes emitted earlier in the same selections batch participate in dedup immediately; duplicate content in one batch now produces one practice line and one `RULE_LEARNED` row instead of inflating the audit count.

## [2.6.20] - 2026-08-19

Bounded Build & Test → Code Generation failure loop-back. When Build and Test (3.6) diagnoses a failure whose root cause lies in generated code or a code-generation approach choice (a library/version, container image, instance type, algorithm, or flag), the workflow can now jump back to Code Generation and repair it instead of writing the approach off or dead-ending at a failed gate. Step 10's failure handling is a four-rung ladder: bounded in-stage fixes, classification plus estimated impact (effort, financial cost, risk), an autonomous loop-back capped at three entries per intent, and an impact-estimated halt-and-ask when human judgement is required. The contract lives in the conditional Construction protocol module (`aidlc-common/protocols/stage-protocol-construction.md`). **Upgrade:** re-copy your `dist/<harness>/` shell into the project, including the refreshed `tools/` tree; this release updates `aidlc-state.ts` as well as protocol guidance.

* The loop-back counter is a crash-safe artifact ledger: an append-only `## Loop-Back Log` in test-results.md, one `### Loop-back N — <ISO timestamp>` entry (Diagnosis / Root-cause stage / Planned fix / Estimated impact) per attempt. The entry count is the bound; human-directed jumps do not count.
* The jump routes through the engine: `aidlc-orchestrate.ts next --stage code-generation` emits the validated `aidlc-jump.ts execute` command, and the conductor runs that printed command rather than composing one.
* Re-entry is settlement-aware. Artifact-only workflows may take the all-covered gate fast path; sticky receipt-mode workflows re-emit per-Unit work and re-mint `unit start` / `unit complete`. Both paths apply fixes and Artifact Re-use decisions before the gate and require a fresh current-attempt review for every applicable Code Generation Unit because `STAGE_JUMPED` invalidates prior receipts.
* Autonomous unit-major replay now uses the inline lifecycle ledger as routed: `unit start` no longer fails with the incorrect "swarm referee owns per-unit bookkeeping" error when `Construction Iteration: unit-major` is active. `t307-loopback-unitmajor-replay` proves start, fresh review, completion, and approval, while retaining the refusal for autonomous stage-major swarm ownership.
* The approved Code Generation plan remains authoritative on a loop-back replay. The Plan Approval answer is not blanked, the plan delta is recorded in the Loop-Back Log, and gated "Retry with fix" is the human re-approval of the revised approach.
* Autonomous Artifact Re-use is deterministic: Modify targeted Units, Keep the rest, and Modify Build and Test on re-entry; Redo is forbidden because it would erase the ledger. Unit-major replays remain on the serial per-Unit path and do not invoke the autonomous swarm.
* Gated "Retry with fix" uses the same settlement-aware override. The fix and Modify/Keep decisions happen before the settle gate, and fresh per-Unit reviewer receipts are mandatory before the gate is presented.
* Rung 4 has two forms: an impact-estimated three-option question (Retry with fix / Accept failure / Abort) when a candidate exists, and a no-fix two-option question (Accept failure / Abort) when it does not.
* Swarm replays discard stale worktrees and run a fresh `prepare`; old worktrees cannot be adopted into the new attempt because `finalize` requires the current prepare stamp. The check-first cheap path still skips builder turns for already-green Units, but every claimed Unit receives a fresh terminal review and `finalize` verifies its current artifact fingerprint before merge.
* Crash resume re-executes a logged-but-not-jumped repair instead of re-diagnosing. After a recorded jump, it resumes the artifact-only or receipt-mode inline path, or follows the Construction module's Swarm interaction procedure when replay re-emits `invoke-swarm` (discard stale worktrees, fresh prepare, check-first, fresh reviewer receipts, finalize).
* Build and Test's in-stage retry remit is limited to its own test configuration, build scripts, and environment setup. Generated source and test-code defects route through the ledgered Code Generation loop-back regardless of size.
* Single-stage runs (`/aidlc --stage build-and-test --single`) stop at classification because they have no main-workflow position to move; impact-estimated options appear in the isolated-run summary.
* The stage-ritual exception is present in all seven shipped conductor SKILLs, including Cursor and GitHub Copilot, and generated distributions remain byte-aligned with their authored sources.
* Deterministic integration coverage (`t304-loopback-review-receipt-replay`) proves the replayed Code Generation gate refuses stale per-Unit reviews after `STAGE_JUMPED` and succeeds only after fresh receipts are recorded.

## [2.6.18] - 2026-08-19

Classic and Express are new scope options, and the implicit default scope is now Classic — a **declared behavior change**: invocations that name no scope and match no keyword now run the v1-style lifecycle without Ideation instead of the full-lifecycle Feature scope. Exactly two things control the implicit default: the `AWS_AIDLC_DEFAULT_SCOPE` env var (which overrides) and the framework's hard-coded `classic` fallback. Express has a deterministic requirements-to-conditional-deploy path, and conditional protocol modules reduce fixed context without dropping reviewer recovery behavior. **Upgrade:** refresh your `dist/<harness>/` shell; in-flight workflows keep their persisted scope and need no migration; set `AWS_AIDLC_DEFAULT_SCOPE=feature` (Claude: the `.claude/settings.json` `env` block, which now ships `classic`) to keep the previous full-lifecycle default.

* **Behavior change:** the implicit default scope is now `classic`. The engine's scope-resolution fallback, `/aidlc-init`, and a direct low-level `intent-create` without `--scope` (previously `poc`) all resolve `AWS_AIDLC_DEFAULT_SCOPE` first and fall back to `classic`; nothing else controls the default. Explicit `--scope`, keyword detection, and the compose offer for rich freeform input are unaffected.
* `--scope workshop` remains supported with its established `workshop`, `lab`, and `training` keywords, compatible stage grid, and Minimal test-strategy override.
* `--scope express` adds the lightweight Requirements Analysis, single-iteration Code Generation, Build and Test, and conditional deploy/observability route with reviewers, Unit DAGs, skeleton ceremony, and swarm dispatch disabled.
* Express Code Generation artifacts use stage-level paths; Build and Test executes stage-level test instructions and includes stage-level traceability in its final coverage gate alongside per-Unit artifacts.
* Reviewer, ensemble, Construction, and swarm contracts load as directive-selected protocol modules from the main orchestrator and generated stage/scope runners; converged swarm settlement cannot repeat reviews after resume, and the modules retain bounded stale-receipt recovery.
* Harness manifests may declare a nonstandard emitted orchestrator `SKILL.md` path for custom `skipRunnerGen`/`emit` layouts; standard in-tree layouts remain compatible without the field.
* The hybrid live Kiro IDE/core pre-merge gate (`t-ide-kiro`, `AIDLC_KIRO_IDE_LIVE=1`) now runs on Windows (`%LOCALAPPDATA%\Programs\Kiro\Kiro.exe`) as well as macOS, with `AIDLC_KIRO_IDE_BIN` override and `AIDLC_KIRO_IDE_CASE` / `AIDLC_KIRO_IDE_DIAGNOSTICS` controls.

## [2.6.17] - 2026-08-18

Plugin authors now have a reusable test kit and documented testing tiers for content validation, deterministic composition, and opt-in live harness checks. No upgrade action is needed.

* `tests/harness/plugin-kit.ts` exposes shared plugin projection, fixture composition, content validation, and gated harness invocation helpers.
* `validatePluginContent()` reports structured findings for manifest identity, stage schema and ownership, artifact namespacing, contribution targets, scope and agent names, and empty stage bodies.
* `composePluginFixture()` builds a real projection and composes it into a scratch install for deterministic integration checks.
* `invokeHarness()` dispatches across Claude, Kiro, Codex, Copilot, OpenCode, and Cursor, while `liveGateFor()` identifies the opt-in gate whose unset value means skip.
* Plugin tests remain auto-discovered under `plugins/<name>/tests/*.test.ts` and can be selected with `bash tests/run-tests.sh --integration --filter "plugin-<name>"`.
* The Harness Engineer Guide now includes a "Testing your plugin" section with tier tradeoffs and copyable examples.

## [2.6.16] - 2026-08-18

Code Generation now turns the team's affirmed Testing Posture into one fingerprinted execution contract shared by normal and autonomous generation. The resolver preserves additive project/team/org notes, distinguishes TDD, BDD, ATDD, test-after, and custom/mixed ordering, and binds the approved plan to the active scope and Test Strategy. **Upgrade:** re-copy your `dist/<harness>/` shell so the new `aidlc-testing-posture.ts` tool, stage contract, dispatch guard, swarm precondition, and developer persona are installed.

* Practices Discovery records explicit `Methodology` and `Ordering` fields; that structured methodology remains authoritative over its ordering prose, a project coverage/tooling note no longer erases a broader team methodology, and a contradictory narrower methodology is rejected. Existing pre-2.6.8 org sections that merely enumerate TDD/BDD/ATDD/test-after are treated as unaffirmed and use the deterministic fallback.
* Code Generation embeds the resolver's structured Testing Contract and methodology-specific plan profile: TDD uses per-layer Red/Green/Refactor across data, repository, business, API, and frontend; BDD uses scenario-first feature slices; ATDD uses acceptance-first cross-layer implementation; custom/mixed preserves its exact ordering; test-after keeps implementation before tests.
* Greenfield plans bootstrap a runnable unit-scoped test command before the first Red/scenario/acceptance step. Scope floors and the selected `--test-strategy` now combine additively instead of producing conflicting test obligations.
* Plan Approval fingerprints the exact plan, unit test instructions, and Testing Contract. A later artifact, memory, scope, strategy, or project-type change invalidates approval, and the developer dispatch must carry matching `AIDLC-UNIT` and `AIDLC-TESTING-CONTRACT` markers.
* Autonomous Code Generation must obtain the same per-unit Plan Approval before `aidlc-swarm.ts prepare`; the referee blocks worktree creation for missing/stale evidence, and every worker receives the full approved plan, instructions, and contract.
* The developer persona treats the approved Testing Contract as authoritative and performs Refactor during initial generation when the selected methodology requires it.

## [2.6.15] - 2026-08-17

Your own documents become something agents can cite. Drop PDFs, Word files,
Markdown, or plain text under `aidlc/spaces/<space>/knowledge/documents/`,
organised however you like, then run `/aidlc knowledge onboard` to index them.
The originals stay yours — AI-DLC never moves, rewrites, or deletes anything in
`documents/`. It derives a catalog next door in `knowledge/documentkb/`: lose
`index.json` and `/aidlc knowledge sync` rebuilds it from the per-document records,
tombstones included. Deleting the whole `documentkb/` tree deletes those records too,
so document ids, tombstones and intent links do NOT survive that — `sync` re-indexes
the surviving originals as new rows.
**Upgrade:** re-copy your `dist/<harness>/` shell into the project.
* Added `/aidlc knowledge <verb>` and the matching `/aidlc-knowledge` skill, on
  every harness: `onboard [path]`, `sync`, `list [--json]`, `show <id>`,
  `associate`/`dissociate <id> --intent [slug]`, and `rebind <id> --to <path>`.
  All accept `--space <name>`.
* Every `knowledge` verb refuses to run if `knowledge/` or `knowledge/documentkb/`
  is a symlink, rather than following it. A redirected container directory would
  otherwise decide where the catalog got written — off-project, or into your own
  `documents/` folder — and, for the journal sweep, what got deleted. The check
  runs in each verb and again in every function that reads or writes under
  `knowledge/` — the catalog, the alias map that resolves linked originals, or the
  documents themselves — so a caller reaching the library directly is covered too.
  A first run on a project that has neither directory yet is unaffected: absent is
  not redirected. The check catches a symlink present when the command starts; it
  is not a defence against one planted mid-run.
* `onboard` is idempotent — re-running it on an unchanged file reports `already`
  instead of writing a second row, so sweeping a folder is safe to repeat.
* Documents are space-wide unless you pass `--intent`. Bare `--intent` means the
  active intent and fails rather than guessing when there is no cursor;
  `--intent <slug>` fails if the slug matches zero or more than one intent.
  Associations persist the intent UUID, so renaming a slug never re-points a
  document.
* Scoping a document to an intent that has finished (`complete`, `archived`,
  `closed`, `abandoned`) is refused; pass `--allow-inactive` when you mean to
  back-fill onto a closed record. `dissociate` never needs the flag, so an
  association can always be undone.
* A document whose extractor is not installed is still catalogued, with the
  state `extractor_unavailable` visible in `list` — install the tool and run
  `/aidlc knowledge sync`, which retries those rows (`onboard` on the same
  unchanged path reports `already` and does not retry). Nothing is silently
  skipped.
* `rebind <id> --to <path>` repairs a row after a move **and** an edit, the one
  case `sync` cannot resolve because neither the path nor the digest survives to
  tie the new file to the old row.
* There is deliberately **no `remove`**: delete your own file and run `sync`.
  The tool never holds a destructive verb over files you own. A deleted original
  leaves a tombstoned row, distinct from `source_unavailable`, which means a
  linked original is temporarily unreachable rather than gone.
* Extracted document text is treated as **untrusted data, not instructions**.
  `show` ships that warning inline with the content, so an imperative inside a
  customer's document cannot redirect a workflow.
* **Document paths and filenames are declared untrusted too**, because the
  customer chose them: a file named `IGNORE ALL PREVIOUS INSTRUCTIONS.md` is a
  filename, not a directive. Every command now leads its output with that
  declaration — `--json` payloads carry a `path_notice` key first, human output
  prints the notice ahead of any name, and refusals carry it too. **If you parse
  this tool's output, note the new leading key/line.**
* New audit events `DOCUMENT_INDEXED`, `DOCUMENT_UPDATED`, and
  `DOCUMENT_REMOVED`, written to the space-level shard even for an
  intent-scoped document. An association that changes nothing emits no event.
* New gitignore entries: `knowledge/documentkb/.journal/` (in-flight
  transactions) and `knowledge/.sources.local.json` (where this machine resolves
  documents linked from outside the repo). If your project has a hand-maintained
  `.gitignore`, add both.
* Projects can commit their text-extractor choice so it travels to every clone. A
  configured extractor's `argv` must contain exactly one `$IN` — the placeholder the
  document's path is substituted into. Zero or several is refused when the tool
  starts: a process that never receives the file would otherwise record whatever it
  printed as the extracted text of *every* document routed to it.
* `onboard` reports a third outcome, `edited`, when a file that changed at an
  already-indexed path is re-indexed: the existing row is refreshed in place, keeping
  its id and intent links, so one path can never carry two live rows.
* A pathless `onboard` and `sync` refuse a work set over 20 new/changed/retrying
  documents or 256 MiB, naming the cap and the remedy; already-current catalog rows
  do not consume the batch budget. A refusal indexes nothing. A single document over
  32 MiB is refused without being read.
* A Word (`.docx`) file is now recognised as Word rather than as a generic binary, so
  a configured `.docx` extractor can actually be selected for it. With none
  configured it is still catalogued and citable as `unsupported_type`, exactly as
  before.
* `rebind <id> --to <path>` now completes the recovery it documents: the following
  `sync` reports `retried` and regenerates the extracted text, instead of leaving the
  row permanently invalidated.
* Scoping to one of several same-slug intents works: `--intent` accepts the full
  record-dir name (`260810-my-slug-2`) and a canonical UUID, which is what the
  ambiguity error already told you to use.
* A hand-edited or corrupted catalog is refused rather than half-trusted: a row's
  `content`/`summary` path must belong to that row, a `removed_at` that is present
  must be a non-empty ISO timestamp, and an index that would fail validation is
  refused before anything is published — so a failed run leaves the space able to
  recover with a plain `sync`.
* `sync` no longer applies a decision made before it took the workspace lock if the
  row changed underneath it (a concurrent `rebind` is the case that mattered); it
  skips that row and re-plans on the next run, and it re-reads the source under the
  lock so extraction can never be published against bytes it did not hash. The
  `DOCUMENT_*` audit rows are written after the catalog write they describe, which is
  a documented exception to the framework's audit-first rule and is explained in the
  state-machine chapter.
* `/aidlc knowledge <verb>` works. Every verb was reachable only by calling the tool
  directly; through the documented command the dispatcher answered `unknown verb`,
  because the route was registered as a top-level passthrough while sitting in its own
  noun group. If you scripted around this by invoking `tools/aidlc-knowledge.ts`, that
  still works — the public command now does too.
* A document that cannot be read is no longer reported as deleted. Growing an indexed
  file past the 32 MiB per-document cap made `sync` tombstone the row while the file
  sat on disk; such a row now reads `present_but_refused` in `list`, and a genuine
  deletion still tombstones, so the two are distinguishable.
* A catalog larger than the batch cap can still be reconciled. The cap now counts the
  documents a run must actually process, not everything in the tree, so a
  21-document catalog built one file at a time no longer refuses every later `sync`.
* Installing a missing extractor or newly configuring one for an `unsupported_type`
  row makes the waiting rows retryable on the next `sync`; the recorded detected
  media type selects the newly available extractor without requiring a file edit.
* An extractor whose `argv` puts `$IN` first is refused. The placeholder is only
  substituted in the arguments, so `["$IN"]` meant the tool tried to run a program
  literally named `$IN`; a real executable is now required at position 0.
* A `removed_at` that is present must parse as an ISO timestamp — `"not-a-date"` was
  previously accepted — and `documents/` itself is now covered by the no-symlink
  trust chain, so a redirected documents root is refused before anything is read.
* Extracted text carries its own digest in addition to the source revision. `show`
  withholds a missing or mismatched derivative, and `sync` re-extracts it, so a
  metadata/content write failure cannot serve old text under a new citation.
* `sync` revalidates newly discovered sources at commit time as well as changed and
  retried rows, and discards unchanged-file buffers while scanning so a large
  reconciled catalog does not accumulate the whole corpus in memory.
* Present non-regular sources (directories, FIFOs, devices, or symlinks) are reported
  as `present_but_refused`, not tombstoned as though the user deleted them.
* The space-level audit shard holds `DOCUMENT_*` provenance, and
  `--doctor --export` reads it explicitly so document history remains visible after
  work starts while workflow-authority readers stay scoped to the intent ledger.
* Idempotent retries repair missing `DOCUMENT_*` rows after an audit-last failure;
  edited onboard plans compare their full pre-lock row snapshot so they cannot
  overwrite a concurrent rebind or association update.
* Explicit space-level audit reads place those shards before the active intent tail,
  and every shard is opened no-follow, preserving diagnostic ordering and refusing
  redirected audit files. Workflow-authority reads remain intent-only.
* Failed or repeated `audit-fork` and `audit-merge` operations are safely retryable:
  work that already landed is an idempotent no-op, a dead partial fork is redone,
  and only a worktree carrying unmerged delta rows refuses with a merge/discard
  remedy instead of requiring a manual shard delete after a crash.
* A valueless `--space` is refused instead of silently mutating the active space,
  and tombstoned content cleanup is retried until the derived text is gone.
* A hardlinked file under `documents/` is refused (a hardlink can alias content
  from elsewhere on the filesystem into the corpus); the refusal names the
  remedy, and `list` reports hardlinked or permission-unreadable originals as
  `present_but_refused` — the same verdict `sync` reaches — instead of `indexed`.
* Extracted text over the extraction caps (50 PDF pages via `pdftotext -l`,
  200,000 characters of output) is truncated; `show` now prints a
  `truncated  yes (...)` line above the content so a partial extraction is
  never mistaken for the whole document. The flag was always recorded in the
  catalog; it is now visible.
* Concurrent `knowledge` commands no longer intermittently fail with
  `documentkb/index.json changed while opening`: the catalog files are written
  by atomic replace, and a read racing that rename now retries briefly instead
  of mistaking the inode swap for tampering (measured: 1 in ~10 concurrent
  onboards lost its run to this).

## [2.6.14] - 2026-08-17

New structured audit blocks no longer carry duplicate `**Timestamp**:` lines. `renderAuditBlock` now exclusively owns the `Timestamp` and `Event` fields, while `park`, `unpark`, and the `practices-promote` write-failure path no longer pass redundant timestamps. **Upgrade:** re-copy your `dist/<harness>/` shell into the project. Existing shards remain byte-unchanged: block-aware readers need no migration, while flat readers must split on `---` and use the first emitter-owned timestamp in each block (or deduplicate historical timestamp fields).

* `aidlc-state.ts park`, `unpark`, and the `practices-promote` write-failure path no longer pass a redundant `Timestamp` field; the emitter-written value is unchanged.
* `audit append --field Timestamp=...` remains accepted for compatibility, but the supplied value is intentionally ignored because structured emitters own `Timestamp`; sibling fields still render normally.
* Audit references now document emitter-owned fields, the accepted-but-ignored compatibility behavior, and the reader requirements for historical duplicate blocks.

## [2.6.13] - 2026-08-17

Authority-bearing commands now reject a narrow set of explicit statements that attribute the current approval, rejection, or interview answer to the conductor/model rather than the human. This is a defense-in-depth tripwire for self-labelled automation observed in issue #742; it does not prove human authorship and deliberately fails open for unlabelled or unrecognized wording. **Upgrade:** refresh `dist/<harness>/` in your project.

* `approve --user-input`, `reject --feedback`, and `aidlc-log answer --details` reject recognized high-confidence self-attribution phrases without emitting the authority receipt or mutating workflow state.
* The tripwire is scoped by decision kind and avoids generic phrases about Human Resources, response time, conductor services, unattended systems, quoted examples, or code being changed by an agent.
* Autonomous exemption applies only to ordinary Construction-stage approvals, rejections, and answers while Construction Autonomy Mode is active; Ideation, Inception, and Operation remain guarded even if that field is present, and consolidated summary confirmation remains human-backed.
* `HUMAN_TURN` remains presence/freshness evidence only. Audit and reference documentation explicitly state that caller-supplied decision prose is not an authenticated human transcript.

## [2.6.12] - 2026-08-17

GitHub Copilot now preserves the latest delivered AI-DLC directive across Stop and rejects replay through an atomic Copilot-owned engine cursor rather than relying on hook admission. The shared engine records both `load-steering` and `run-stage` routing metadata, while `sessionless:` and non-Copilot continuation remain stateless in this release. **Upgrade:** refresh `dist/copilot/` and start a fresh Copilot conversation for an in-flight workflow so pre-upgrade transport markers cannot be reused.

* Copilot PostToolUse records bounded routing metadata for successful `next`, `continue`, `report`, and `park` results. Stop reuses the current delivered `load-steering` or `run-stage` directive through the existing human-wait, autonomy, and recursion safeguards instead of probing a fresh `next` and restarting part 1.
* For exact-context Copilot-owned markers in a current Copilot installation, the engine validates and builds a continuation successor before atomically comparing the full presented-token digest and publishing the successor token or final tokenless `run-stage` before stdout. Concurrent same-token calls have one winner, and fresh `next` emits no work directive unless its reset/issuance commits. Missing, malformed, v1, stale, `sessionless:`, and non-Copilot-install contexts retain the prior stateless path; on a stable non-Copilot installation, marker-lock contention cannot deny a revalidated stateless continuation and is recorded as a dropped best-effort marker update.
* The active-directive marker stays readable while writers use a record-local, owner-stamped lock with dead-owner and post-grace unstamped recovery, live-over-age fencing, token-bound atomic publication, and `/aidlc --doctor` findings. Marker reads are bounded to the 64 KiB marker limit from a single descriptor, so an oversized or corrupt marker is rejected as absent without being loaded. Legacy `.transaction` debris still requires quiescent manual recovery.
* Copilot classification is limited to execution-shaped direct, source-dispatcher, and real compiled commands. Inspection, ambiguous wrappers, and commands with active shell-expanded arguments (`$VAR`, globs, brace expansion, or leading `~`) run untracked, one terminal `2>&1` is supported, unsafe direct compounds are refused, and a foreign explicit `--project-dir` is rejected before current-project coordination writes. Lock contention before claim tells the caller to retry the exact command because no claim was committed.
* Exact documented host IDs or adapter IDs carried through rewritten engine input can settle delivery. Missing correlation allows untracked execution and never guesses a Post mutation; CLI 1.0.79/macOS/noninteractive is live-verified, while the VS Code Preview envelope has fixture/documentation coverage only.
* Resume questions remain pending until a matching human answer. Selected Resume work stays parked across intermediate turns, foreign bare `next` is denied, and workflow or intent drift supersedes stale choices rather than applying them later.
* Copilot conversational evidence and Stop streaks are session-scoped. Progress fingerprints include directive kind, stage, Unit, part count, full token hash, state digest, and Resume status; audit-only rows no longer reset the bounded release.

## [2.6.9] - 2026-08-17

Review receipt invalidation is now recoverable without weakening normal review budgets. When a terminal receipt is voided by a later write to a declared artifact, the review logger permits one deterministic recovery pass at the next ordinal and reports stale, retry, and recovery-spent states directly instead of sending the conductor through the circular guidance seen in #755 and #742. **Upgrade:** refresh `dist/<harness>/` in your project.

* A terminal receipt invalidated by a later `produces[]` write gets exactly one marked recovery request at the next ordinal, including advisory stages and adversarial stages with unused normal iterations; either recovery verdict is terminal.
* Per-Unit waves expose `recovery-required` with the exact next ordinal and `escalation-required` after recovery is spent, while mixed stale/never-reviewed completion refusals now give both groups an actionable remedy.
* Retry and recovery-spent refusals no longer contradict each other. Interactive attempts, including autonomous inline waves after recovery is spent, reset only after a human Request Changes decision; autonomous Bolt Units halt before `finalize` and use a human-approved restart instead of waiting for an unreachable post-merge gate.
* Intact receipts retain their existing advisory normal-flow and adversarial iteration budgets; ordinary over-budget requests are still refused.

## [2.6.8] - 2026-08-15

The reviewer work loop gets a hard backstop: both review-only agents (`aidlc-architecture-reviewer-agent`, `aidlc-product-lead-agent`) now carry a 60-turn cap - authored once as `maxTurns: 60` in the persona frontmatter, enforced natively on every harness with a lever (Claude Code `maxTurns`, opencode `steps`) and mirrored as a harness-neutral `## Turn Budget` persona section everywhere - and the stage protocol closes the previously undefined branch where a reviewer that dies before writing its verdict (turn cap, crash, context exhaustion) left the conductor reading a stale, partial, or missing `## Review`. A review now counts only when it parses: exactly one current `## Review` section with exactly one canonical READY/NOT-READY verdict. Anything else is an incomplete attempt that retries the same review once with `--retry-pending` (consuming no review iteration - an advisory budget is one pass) and then records a terminal `NOT-READY` receipt with the finding "review did not complete within its turn budget", so the gate is never presented on - or deadlocked by - a silently missing verdict. Before every reviewer dispatch the conductor now deletes any existing `## Review` section (review history lives in the audit ledger), closing the revision-path gap where a stale pre-revision READY could be misread as covering revised work. The GitHub Copilot orchestrator also catches up to the review-class engine. **Upgrade:** re-copy your `dist/<harness>/` tree into the project (the reviewer agent files, `aidlc-common/protocols/stage-protocol.md`, and every orchestrator SKILL.md changed).

* `maxTurns: 60` frontmatter on the two reviewer agents, projected per harness: binding on Claude Code (the harness stops the sub-agent at the cap, no final-message turn); renamed to the native per-agent `steps: 60` on opencode (the runner grants one final text-only turn - a summary can return, but no tool call can write the review); prose-only on Codex CLI (its TOML personas have no frontmatter, so the emit rewrites the persona's citation), Cursor, GitHub Copilot, and Kiro CLI/IDE (no per-agent cap key; the inert key still ships on the tolerant .md surfaces and never enters the kiro agent JSONs, whose schema fail-closes on unknown fields). The value sits at the top of the observed legitimate range from field timing data (p90 40 / max 60 turns at the medium-effort reviewer tier), so it catches runaways without truncating real reviews.
* New harness-neutral `## Turn Budget` section in both reviewer personas: plan for the worst-case cutoff, reserve the final turns for writing the review, write exactly one `## Review` section with one canonical verdict, and a thin verdict always beats no verdict.
* Stage protocol §12a step 3 now validates the verdict: a missing `## Review` section, a verdict-less section, or duplicated sections/verdicts is an incomplete attempt - retried once via `--retry-pending` without consuming a review iteration, then recorded as a terminal `NOT-READY` receipt with the finding "review did not complete within its turn budget". Mirrored in all seven harness SKILL.md reviewer bullets.
* Stage protocol §12a step 1 now deletes any pre-existing `## Review` section before every dispatch (first entry, NOT-READY re-invoke, and post-rejection re-review alike): "no current section" means "incomplete review" on every path, no stale pre-revision READY survives a revision, and no superseded reviewer prose accumulates in artifacts or leaks into the claim-sources scan.
* GitHub Copilot reviewer step brought up to the review-class contract (`directive.review_class` branch, advisory single-pass terminality, terminal-receipt freeze wording, `--retry-pending` recovery), and the §12a dispatch-record roster now names Copilot among the reviewer-scope-enforcing harnesses.

## [2.6.2] - 2026-08-13

Follow-up fixes to the 2.6.1 design-output restructure (review items from #711). No artifact or stage-graph changes — this is a correctness/consistency patch. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Business-rule ID format is now consistently `BRx.y` (e.g. `BR1.1`) — the format the `traceability` sensor recognizes. Functional Design (`functional-design.md`), the product-agent functional-design guide, and the org-level stable-ID guidance no longer instruct the sensor-incompatible `BR-NNN` form.
* Runtime state-version guard hardened and aligned with `/aidlc --doctor`: `next` and `report` now refuse a state whose State Version is **missing, empty, malformed, or a present-but-empty (zero-byte) file**, and report a future/unknown numeric version as incompatible rather than as pre-v8. Previously a missing/empty/zero-byte version could slip through and advance an incompatible state.
* Domain Design traceability targets are constrained to the components/entities defined in `components.md` (its source of truth); method/API-level targets are pinned later in Contract Design and Functional Design.
* Inception reference documentation (`docs/reference/04-stages/inception.md`) corrected: Contract Design (2.8) section added, `contract-summary.md` listed in Delivery Planning inputs, `traceability.json` listed in Domain Design and Units Generation outputs, and Units Generation's output count corrected to four.

## [2.6.1] - 2026-08-13

Inception and Construction design-output restructure. Application Design becomes **Domain Design** (2.6): its former `components`/`component-methods`/`services`/`component-dependency` artifacts collapse into a single consolidated `components.md` — a fenced `yaml` component catalogue (source of truth) plus a derived human view (mermaid diagram + summary/ownership/rationale tables) — while `decisions.md` is retained as the Architecture Decision Record log the Inception phase rule requires. A new **Contract Design** stage (2.8, CONDITIONAL) formalises the system's formal contracts — inter-unit boundaries and any public/external API — so teams can build in parallel; it produces `contract-summary.md` and runs whenever there is a contract to pin (it skips only a single self-contained unit with no inter-unit boundaries and no external API). Delivery Planning moves to 2.9. Functional Design's outputs are restructured into `entities.md` + `rules.md` (fenced `yaml` sources of truth) + `functional-spec.md` (the source of truth for workflows and state machines, with ER-diagram and rules-summary views derived from entities/rules), replacing `business-logic-model`/`business-rules`/`domain-entities`. Infrastructure Design's five artifacts collapse to three: `deployment-architecture`, `infrastructure-services`, and `shared-infrastructure` merge into a single **tabular** `infrastructure-specification.md` (deployment + services + a CONDITIONAL shared-resources section), while `monitoring-design.md` and `cicd-pipeline.md` stay dedicated. The framework now ships **33 stages** (was 32). **Breaking for consumers that read inception/infra design artifacts:** the five old app-design names, the three old functional-design names, and `deployment-architecture`/`infrastructure-services`/`shared-infrastructure` are gone — read `components.md`, `contract-summary.md`, `entities.md`, `rules.md`, `functional-spec.md`, and `infrastructure-specification.md` instead. **Upgrade:** re-copy your `dist/<harness>/` shell into the project, then **delete the renamed stage-runner skill left behind by the merge copy** — the old `skills/aidlc-application-design/` directory (now `skills/aidlc-domain-design/`); a `cp -R` merge adds the new runner but does not remove the old one, and the stale `/aidlc-application-design` runner invokes a stage no longer in the graph. The persisted state schema version is bumped (v8), so any workflow started on the prior shell is rejected by `/aidlc --doctor` **and by `next`/`report`** with an explicit incompatibility message rather than silently breaking on the renamed stages — finish an in-flight workflow on the prior shell before upgrading, or start a fresh intent on the new shell.

* Stage `application-design` renamed to `domain-design` (2.6); its per-stage runner becomes `/aidlc-domain-design`. Its `produces` collapses from five artifacts to two: the consolidated `components` (`components.md`) plus the retained `decisions` (`decisions.md`, the ADR log).
* NEW stage `contract-design` (2.8, CONDITIONAL — runs for any inter-unit boundary or public/external API; skips only a single self-contained unit with neither); per-stage runner `/aidlc-contract-design`; produces `contract-summary`. Delivery Planning renumbered 2.8 → 2.9. The framework now ships 33 stages (was 32).
* Functional Design `produces` renamed: `business-logic-model` → `functional-spec` (now the source of truth for workflows and state machines), `business-rules` → `rules`, `domain-entities` → `entities`. Downstream consumes in `nfr-requirements`, `nfr-design`, `infrastructure-design`, and `code-generation` were rewired accordingly.
* `infrastructure-design` `produces` is now `[infrastructure-specification, monitoring-design, cicd-pipeline]` (was five). `shared-infrastructure` is no longer a separate (optional) artifact — it is a CONDITIONAL section of `infrastructure-specification.md`. Downstream consumes rewired: `code-generation`, `observability-setup`, `incident-response`, `environment-provisioning`, and `deployment-pipeline` now read `infrastructure-specification` in place of `deployment-architecture` / `infrastructure-services`.
* The persisted state schema version is bumped to v8 and enforced at runtime: `next`, `report`, and `/aidlc --doctor` refuse a pre-v8 state file with an explicit incompatibility message instead of failing later on a missing `application-design` / `domain-design` row.

## [2.5.75] - 2026-08-13

Observability is now a first-class NFR artifact flow for service units, from requirements through architecture and platform-specific monitoring design. This integrates the design of community PR #404 by jeromevdl for issue #398 while retaining the existing `monitoring-design` infrastructure handoff. **Upgrade:** refresh `dist/<harness>/` in your project.

* NFR Requirements produces `observability-requirements.md` for service units, and NFR Design consumes it as a required input.
* NFR Design asks observability-focused design questions and produces `observability-design.md` for service units.
* Infrastructure Design consumes `observability-design.md` and continues producing platform-specific `monitoring-design.md` for Observability Setup.
* Construction and artifact documentation now describes the observability flow and its service-unit applicability.

## [2.5.74] - 2026-08-13

Kiro CLI now ships the same five MCP servers as Claude Code, with every server disabled until a user explicitly enables it. **Upgrade:** refresh `dist/kiro/`, then flip `"disabled": false` on each server you want to enable in `.kiro/settings/mcp.json`.

* New `.kiro/settings/mcp.json` registry ships `context7` plus the four AWS servers, all disabled by default. Context7 ships keyless on Kiro because live verification on Kiro CLI 2.12.1 found that MCP HTTP header values are sent verbatim rather than expanding environment placeholders; API keys must not be committed to `.kiro/settings/mcp.json`. The `@latest` launchers remain aligned with the Claude registry and execute only after explicit per-server user opt-in.
* All 14 delegated persona configs set `includeMcpJson: true` and grant the five `@<server>` tools; the conductor remains excluded so orchestration itself gets no MCP access.
* Persona configs drop their upstream `$schema` declaration because that schema rejects the Kiro-supported `includeMcpJson` field through `additionalProperties: false`; the unchanged conductor retains its schema.
* Based on community PR #412 by @jeromevdl.

## [2.5.73] - 2026-08-13

Re-authored from PR #403 by @jeromevdl, unit test instructions now belong to each Code Generation unit before implementation and flow into the cross-unit Build and Test stage. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Code Generation produces `unit-test-instructions.md` per unit alongside the implementation plan, and Build and Test consumes those instructions instead of recreating them after code exists.
* Plan Approval now covers both the code generation plan and unit test instructions; changing either file requires renewed approval before developer-agent dispatch.
* Per-unit test commands must use exact test paths or an exact unit filter, and Build and Test deduplicates identical commands so each distinct command runs once.
* Code Generation now imports the advisory `required-sections` sensor so the moved markdown artifact retains the document-shape validation applied at its former stage.

## [2.5.72] - 2026-08-13

Construction design stages no longer ship implementation-ready code in design artifacts. `functional-design`, `nfr-design`, and `infrastructure-design` now carry an explicit Constraints section: artifacts describe what is needed and why at an architectural level, code is capped at short illustrative snippets (pseudocode or interface-level, 15 lines or fewer), and complete implementations (IaC modules, Lambda handlers, IAM policy documents, middleware) belong in `code-generation` (#396). **Upgrade:** re-copy your harness tree from `dist/<harness>/` to pick up the revised stage files.

* `functional-design`, `nfr-design`, and `infrastructure-design` stage prose gains a `## Constraints` section scoping artifacts to design-level content.
* No command, flag, or artifact-path changes.

## [2.5.71] - 2026-08-13

Stages now carry deterministic element-level traceability from requirements through stories, Units, design, code, and the Construction exit checks. **Upgrade:** refresh `dist/<harness>/`; for an existing intent whose current or completed in-flight stage predates `traceability.json`, revisit that stage and create its declared traceability artifact before attempting completion or downstream phase verification.

* Requirements, stories, acceptance criteria, Units, business rules, and detailed NFRs use stable IDs (`FR`, `NFR`, `US`, three-segment `AC`, `U`/Unit directory, `BRx.y`, and `NFRx.y`) in stage deliverables.
* Eight Inception and Construction stages declare and write `traceability.json`; the new advisory `traceability` sensor validates JSON shape and statuses, fails closed on missing upstream evidence, verifies deterministic targets, and derives unexplained business-rule orphans.
* Delivery Planning aggregates Inception traceability, Build and Test writes a cross-Unit final coverage deliverable, and CI Pipeline keeps the Construction phase-boundary check at the real transition while consuming those results.
* `aidlc-sensor list` now reports six framework sensors. No command or flag changes.

## [2.5.69] - 2026-08-13

Cursor IDE no longer blocks every tool call on a fail-closed PreToolUse hook that allowed with empty stdout. The Cursor adapter now emits `{"permission":"allow"}` on both allow returns, matching Cursor's required permission JSON; deny JSON and `failClosed: true` are unchanged. Cursor CLI already treated silence as allow, so CLI-only verification missed this. **Upgrade:** refresh `dist/cursor/` and rerun `bun dist/cursor/install.ts <project>`.

* Cursor `preToolUse` (`guards`) allow paths write `{"permission":"allow"}` before exit 0. Empty stdout is invalid JSON; with `failClosed: true` the IDE denied the call (`Hook "bun .cursor/hooks/aidlc-cursor-adapter.ts guards" returned no output`).
* Unit coverage in t276 asserts allow stdout is that JSON, and still deny JSON on block or malformed input.
* No command or flag changes.

## [2.5.68] - 2026-08-13

Codex balanced and templated agents now use a supported model on Amazon Bedrock. **Upgrade:** re-copy `dist/codex/` into the project.

* Codex tier projections now pin `openai.gpt-5.6-terra` for balanced and templated agents.
* Codex onboarding and harness documentation now describe the updated model pin.

## [2.5.67] - 2026-08-12

Stage-major Construction design can now run dependency-safe per-Unit waves from an engine-emitted directive, with current lifecycle, review-class, and crash-recovery contracts preserved. The engine resolves each wave from one healed Bolt-DAG snapshot and keeps the batch active until every applicable Unit has build evidence, paired terminal review evidence when enabled, crash-safe diary fan-in, and a `UNIT_COMPLETED` receipt. **Upgrade:** re-copy `dist/<harness>/` into your project and start a fresh `/aidlc` turn; an in-flight pre-upgrade steering continuation token intentionally fails closed and must be restarted with `next`.

* Eligible `run-stage` directives gain optional `directive.wave` entries with resolved Unit kind, present/absent consumes, outputs, kind-applicable `required_produces`, `unit_memory_path`, build state, completion state, and review progress (`outstanding`, `retry-required`, `repair-required`, or terminal).
* Wave builders remain confined to the four inline design stages on the default stage-major walk. Code Generation, unit-major iteration, and plugin-contributed stages remain on their existing serial or swarm paths.
* `aidlc-state.ts unit complete --wave --stage <slug> --unit <name>` verifies the live wave entry, copies new Unit diary entries verbatim into the parent stage diary with deterministic deduplication, binds the receipt to the final artifact fingerprint, and emits `UNIT_COMPLETED`; a crash before that transaction or a later artifact change leaves the entry open for recovery.
* Wave review settlement uses paired `REVIEW_REQUESTED` / `REVIEW_COMPLETED` rows and the effective review class: `none` requires no review, advisory verdicts settle after one pass, adversarial NOT-READY stays open below its iteration cap, and unmatched requests resume with `--retry-pending`.
* All seven shipped harnesses receive the same branch-before-gate contract, steering/context inheritance, kind-aware blocked-output rule, reviewer-scope serialization rule, and deterministic same-batch transport prefixing.

## [2.5.64] - 2026-08-11

Composed-workflow routing is now deterministic from proposal through execution, and the affected test-runner and live-journey paths fail closed. Stock matches present exactly the grid that will run, incomplete model-produced grids cannot match a stock scope, in-flight recomposition preserves the running plan, isolated stages no longer wait on nonexistent questions, and mid-flow new work carries one typed continuation contract with a named scope. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `aidlc-graph.ts validate-grid` returns `nearest_stock`, ranking graph/plugin-authored stock scopes by proposal distance, and requires one explicit EXECUTE/SKIP entry for every compiled stage. Missing and extra keys count as differences; composer-authored registry entries remain runnable but cannot become stock-match candidates for unrelated work.
* Front/report composition routes solely on `validate-grid.nearest_stock` for the final proposal. The earlier mechanical ARS distance is advisory and cannot erase evidence-driven folds, while a matched proposal adopts and revalidates the stock grid before rebuilding its summary and stage-decision table.
* Editing a matched stock plan converts it to a custom plan so the approved edits persist. In-flight proposals instead use `mode: in-flight`, preserve the current scope, depth, full grid, and frozen actions, and pass exact `changes.skip` / `changes.add` arrays to `recompose`.
* Isolated single-stage runs (`--stage <slug> --single`) present the pre-generation summary confirmation only after file-backed Q&A. Stages that ask no questions proceed directly to artifact work instead of waiting for an answer that cannot exist.
* Mid-flow new-work offers emit `ask_type: "new-work-routing"` with `response_route: "next"`, `new_work_description`, and `proposed_scope`; every harness uses that typed route instead of `report`, including rich prose that falls back to the selected default scope.
* Scan reports are scored as fixes rather than new projects: captured findings screen out ideation framing stages, and pre-existing test or CI gaps do not inflate the plan unless the fix cannot ship without them.
* Persona files named by `inline_context_paths` are a blocking first-read precondition across every harness, including the mob lead before drafting or support dispatch.
* Concurrency and live-journey regressions fail on contender crashes or malformed evidence, require actual persona reads and coherent completed-stage advancement, and verify that the new-work offer was rendered before confirmation.
* Test-runner verbose log directories are per-process (`tests/logs/<stamp>-p<pid>`), preventing concurrent runners started in the same second from deleting or corrupting each other's results. Consumers must read the emitted `Verbose mode: logging to <dir>` line rather than reconstructing the path.
* No command or flag changes; no breaking change for CI or scripts beyond the log-directory naming note above.

## [2.5.63] - 2026-08-11

AI-DLC now ships a Cursor harness (`dist/cursor/`) for Cursor IDE and Cursor CLI from one tree. Install it with `bun dist/cursor/install.ts <project>` and run `/aidlc` in chat or `agent -p "/aidlc ..."` headlessly. **Upgrade:** rerun the installer after refreshing `dist/cursor/`; it preserves project-owned configuration and selected-plugin state, refreshes framework routing data, removes unchanged framework files retired by the new release, and refuses symlinked targets or unresolved file collisions. Rebuild and reinstall any AIDLC Cursor plugins.

* New `dist/cursor/` distribution: engine and native surfaces under `.cursor/` (skills, agents, rules, hooks, and tools), root `AGENTS.md` onboarding, and the neutral `aidlc/` workspace tree.
* Cursor hooks use `.cursor/hooks.json` through a fail-closed adapter that normalizes shell working directories without treating cwd metadata as an accessed path, enforces reviewer scope and review freeze through wrapped shell commands, tracks delegated identities, and denies general-purpose interpreters, shell parameter expansion, and dynamic evaluation while reviewer attribution is active. Interpreter checks apply only to executable positions, ordinary arguments such as `rg node README.md` remain usable, partial ledger loss stays reviewer-ambiguous, and a top-level conversation remains identified until SessionEnd instead of expiring after inactivity.
* The method reaches context through `.cursor/rules/aidlc.mdc` plus four agent-decided phase rules; `/aidlc space <name>` re-points the rules and persona memory paths in place.
* Cursor-native `/aidlc-status`, `/aidlc-jump`, and `/aidlc-scope` skills route through the deterministic engine and disable model auto-invocation.
* Cursor plugin projections use the native hook schema and a cross-platform Bun launcher, resolve the target project from SessionStart workspace roots, and emit one authoritative native agent surface.
* `dist/cursor/install.ts` merges existing Cursor configuration, rejects symlinks in its managed trees before reading or writing them, tracks framework ownership, preserves active-space and plugin selections, restores missing files against the selected space, removes retired receipt-owned files only when their bytes remain unchanged, and recompiles selected-plugin routing data against the upgraded core. Plugin-composed stages are rebuilt from verified prior core bytes plus their recorded contributions, and contribution sidecars relinquish values adopted by core so disabling a plugin cannot remove new core requirements; unverified pre-receipt differences and user-edited or retired files are refused before any writes.
* Cursor follows the shared fresh-session boundary after creating a second intent, renders every prose question with fresh numbering and deterministic number-to-source-key mapping, and ignores hidden pre-intent runtime state.
* Release binaries, doctor checks, plugin composition, packaging parity, and deterministic adapter/installer tests now include Cursor.

## [2.5.62] - 2026-08-08

`intent-create` now fails closed when invoked without meaningful work details, and starting a second unrelated intent hands the conductor to a fresh session so the new work does not inherit the prior intent's transcript. Scope runners (`/aidlc-<scope>`) now offer the same explicit second-intent path instead of dead-ending at a completed workflow. **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the updated tools, hooks, orchestrator skill, and scope runners are installed.

* `bun .claude/tools/aidlc-utility.ts intent-create` with no `--scope`, `--arguments`, or `--label` now errors and mutates nothing; every value-bearing create option (`--scope`, `--arguments`, `--label`, `--depth`, `--test-strategy`, `--review`, `--repos`, and `--project-dir`) also rejects a valueless or blank occurrence before path resolution or mutation.
* Completed workflows advertise the human-confirmed `next --new-intent --scope <scope> "<description>"` route for unrelated work.
* `next --new-intent` requires a nonblank new-work description. Its directive tells every harness conductor to create the intent, STOP, and use the harness-native fresh-session entry (`/aidlc`, or `$aidlc` on Codex); fresh-workspace creation still continues in-session.
* The PostToolUse hook pairs a successful `intent-create` result with that exact tool event's host session ID and never overwrites existing ownership. A second creation writes a short-lived one-shot handoff receipt, so Stop allows the requested clean-session boundary instead of forcing the old conversation into the new intent. An unstamped UUID-backed SessionEnd fails closed instead of using another conversation's shared cursor, so `SESSION_ENDED` and its heartbeat land only with the session that actually ended.
* Kiro IDE now binds legacy `intent-create` calls through the synthetic session identity retained at SessionStart, and modern Stop events prefer their own `session_id` over the workspace-global marker so concurrent chats cannot consume one another's fresh-session handoff receipts. Both the direct hook entry point and the public `aidlc adapter kiro-ide <target>` dispatcher preserve this input contract.
* GitHub Copilot follows the same second-intent fresh-session boundary in both its conductor and generated scope runners: start a new Copilot CLI session or VS Code agent chat, then invoke `/aidlc`.
* Every generated scope runner carries the same recognize, confirm, create, and harness-native fresh-session handoff contract.

## [2.5.60] - 2026-08-09

Adds GitHub Copilot as a first-class harness for both Copilot CLI and VS Code agent mode, with native skills, custom agents, normalized hooks, plugin composition, and deterministic workflow safeguards. **Upgrade:** copy `dist/copilot/.aidlc/`, `dist/copilot/aidlc/`, and merge `dist/copilot/.github/` plus `AGENTS.md` into the project; trust the folder in `~/.copilot/config.json`, and set `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=1` for headless `copilot -p` runs.

* `/aidlc`, stage runners, and scope runners ship under `.github/skills/`; the 14 base personas ship as `.github/agents/aidlc-*-agent.md` custom agents and inherit the session model.
* Approval gates and structured questions use fresh numbered prose so the human's next chat message records a trusted human action; fixed resume choices accept exact numeric aliases `1` through `4`, and unresolved question waits no longer trigger continue-workflow text that Copilot can mistake for an answer.
* The Copilot adapter normalizes CLI and VS Code hook payloads, tool names, multi-file replacements, patch operation types, and response envelopes. Reviewer scope, plan approval, review freeze, workflow-transition ownership (including wrapped and substituted commands), malformed-input Stop enforcement, project path confinement, and locked per-session subagent attribution are enforced across both surfaces; interrupted ledger owners are reclaimed after a bounded stale-lock interval.
* Copilot loads the engine's bounded `load-steering` directives before stage work and injects the exact active-stage rule bundle into delegated custom-agent briefs through the shared deliver-stage-rules guard.
* Copilot plugin composition and selection emit agents and runners under `.github/{agents,skills}` and reject plugin agents that omit the required no-nested-delegation contract; `/aidlc --doctor`, compiled runtime probing, binary assets, space switching, and release tests now cover Copilot alongside the existing harnesses.
* The shared Copilot hook manifest omits VS Code's unsupported `SessionEnd`; both hosts reconcile the prior session on the next `SessionStart`.
* Copilot uses the purpose-based hook names, `intent-create` command, plain-language voice contract, and scope-aware workflow directories introduced in 2.5.57.
* Delegated lifecycle enforcement now covers scope/config mutation groups, shell `-c --` forms, nested `env`/`command`/`nice`/`nohup` wrappers, and literal command variables; simple harmless `eval` commands remain allowed, while unresolved executable expansion, dynamic/escaped eval, and uninspectable wrapper syntax fail closed.
* New deterministic coverage includes Copilot packaging, adapter, security, plugin, doctor, and cross-harness regression tests plus the `AIDLC_COPILOT_EXEC_LIVE=1`-gated status journey.

## [2.5.59] - 2026-08-08

Gives the Stop hook's conversational carve-out a second evidence source, so it stops counting a purely conversational turn mid-stage as a no-progress block on harnesses that deliver no transcript. Asking why an earlier decision was made, or reading code without advancing the workflow, previously fell through to the cap-bounded block on Kiro IDE, Kiro CLI, and opencode: the carve-out read its answer off the harness transcript, and only Claude Code and Codex deliver `transcript_path`. What that costs the user depends on the host — see the second bullet, because it is not the same everywhere. **Upgrade:** copy the tree CONTENTS for your harness, e.g. `mkdir -p your-project/.kiro && cp -R dist/kiro-ide/.kiro/. your-project/.kiro/` into your project.
* The carve-out now answers the same question from two `mtime` markers where no transcript arrives. Two runtime files appear under the active intent's record dir: `.aidlc-human-turn` (touched once per human prompt, alongside the existing `HUMAN_TURN` audit event) and `.aidlc-engine-touch` (touched by every advancing `aidlc-orchestrate next` / `report` / `park`). A human turn newer than the last engine advance is what identifies a chat turn. Both are already covered by the shipped `aidlc/spaces/*/intents/*/.aidlc-*` gitignore rule, so neither is ever committed, and read-only routing (`--status`, `--doctor`, `--help`, `--version`, and the workspace verbs) does not count as engagement.
* **What you actually see depends on your host.** On Claude Code, Codex and opencode the spurious nudge is suppressed and the turn ends clean. On **Kiro IDE nothing user-visible changes**: that host's `Stop` trigger is observational — measured live with a probe hook, neither stdout nor stderr reaches the agent — so the nudge was never delivered there to begin with; only the `stop.drops` record and the no-progress counter are corrected. On Kiro CLI 2.16.0 the block was measured live on both runtimes: legacy/V2 consumes the adapter-relayed `{"decision":"block","reason":"..."}`, reinjects `reason`, and invokes `Stop` twice across the induced continuation; `--v3`/KAS consumes the same shape through its standalone `.kiro/hooks` registration, reinjects `reason`, and invokes `Stop` once without re-firing after that continuation. The spurious nudge is therefore suppressed on both CLI runtimes.
* **Known gap, documented rather than closed.** The marker path is more permissive than the transcript path: it is blind to `aidlc-jump`, `aidlc-bolt`, `aidlc-swarm` and the mutating `aidlc-state` verbs, none of which touch the engine marker. A conductor that jumps the stage pointer and then ends its turn without consulting the engine is released on Kiro and opencode where it would be blocked on Claude Code. Those turns were nudged before this change, so it is a real if narrow relaxation. `docs/reference/06-hooks-and-tools.md` spells out the gap and the session-scope caveat (the markers are per-intent, so two concurrent sessions on one intent can cross-talk).
* Enforcement is otherwise intact: a conductor that consults the engine and then tries to end its turn without reporting is still blocked, the autonomy guard still suppresses the carve-out under `Construction Autonomy Mode: autonomous`, and both marker reads fail closed — a missing marker reads as "no evidence" rather than releasing. A marker whose write fails is now deleted instead of left stale, because a stale *engine* marker would be a persistent silent fail-open. `aidlc-orchestrate next` remains a pure read: it writes no marker before an intent is born.
* No command, flag, or output-format changes; no breaking change for CI or scripts.

## [2.5.58] - 2026-08-07

The `claim-sources` sensor no longer loses source tags that are written next to
each other. `[Q1][Q2]` is Markdown reference-link syntax only when the document
defines the label it names; with no such definition CommonMark renders both
tags as literal text, and the sensor now reads them the same way. Claims that
cite two answers without a separator stop being reported as ungrounded.
**Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Fixed `claim block has no source tag` for claims carrying adjacent tags such
  as `[Q1][Q2]` or a collapsed `[Q1][]`, which the sensor read as a link and
  discarded. Inserting a space is no longer required.
* A tag that the document really does define as a link reference, including the
  shortcut `[Q1]` form, now correctly grounds nothing, matching what a reader
  sees rendered.
* A paragraph holding only link reference definitions is no longer reported as
  a claim block missing a source tag.
* A line that only looks like a link reference definition is inspected as the
  prose it renders as. A malformed destination — unclosed `<...>`, unbalanced
  parentheses, an unescaped `(` in a `(...)` title — no longer exempts its
  paragraph from needing a source tag.
* Definitions are read inside block quotes and list items nested in any order
  and to any depth, so a tag that such a definition turns into a link no longer
  grounds a claim. Five or more spaces after a list marker remain an indented
  code block.
* Definition labels, destination boundaries, title separation, title
  continuation, and source indentation now follow the same fail-closed rule;
  malformed or code-indented definition-shaped prose cannot bypass inspection.
  Definitions with a destination on the following line still resolve links
  document-wide without making their block eligible for the definition-only
  skip.

## [2.5.57] - 2026-08-07

AI-DLC now speaks to you in your project's terms rather than its own. Three things a user reported all came from the same place: the assistant narrated its internals, hook names and messages described plumbing instead of purpose, and a new workflow opened with folders it was never going to use. Chat messages, approval gates, the composer's plan proposal, scope questions, error messages, and the onboarding doc are rewritten in plain developer terms; the sentences between steps are now written by the framework and relayed rather than improvised, with silence as the resting state; seven hooks and the intent-creation command are renamed to say what they do; and a record dir now contains only the phases your scope actually runs. Behavior is unchanged throughout: every stage, approval gate, audit event, and tool flag is identical, and the tests pinning those mechanics still pass.

**Upgrade:** re-copy your `dist/<harness>/` shell into the project. This is mandatory, not optional: the old hook files and their `settings.json` entries reference the old names, so a stale copy keeps using the old wiring. Kiro IDE users must first run the retired-hook cleanup in the [Kiro IDE install guide](docs/guide/harnesses/kiro-ide.md#install), because its overlay copy cannot delete old auto-discovered registrations and leaving them in place fires the old and new hooks together. Codex users additionally re-run the hook-trust pre-seed (`bun scripts/package.ts codex trust --project <abs-dir>`), because the trust hash covers the adapter command string and every renamed target changes it. An overlay copy can leave the retired, empty `tools/data/scaffold/` directories behind; they are harmless and can be removed manually. Existing intent records are untouched: nothing is ever deleted, so a record already carrying all five phase folders keeps them, and you can remove an empty one by hand if you want.

* Seven hooks renamed: `aidlc-audit-logger` to `aidlc-write-audit-log`, `aidlc-sync-statusline` to `aidlc-sync-workflow-state`, `aidlc-mint-presence` to `aidlc-record-human-turn`, `aidlc-runtime-compile` to `aidlc-rebuild-stage-graph`, `aidlc-stop` to `aidlc-continue-workflow`, `aidlc-dispatch-rules` to `aidlc-deliver-stage-rules`, `aidlc-sensor-fire` to `aidlc-run-sensors`. The other ten keep their names. On Claude Code the filename is the only label a waiting user sees, and `aidlc-sync-statusline` actively misled: it reconciles the Current Stage in `aidlc-state.md`, while the statusline is a separate hook that reads that file.
* `/aidlc --doctor` now reports heartbeats under the new hook names (for example `write-audit-log` rather than `audit-logger`), and the per-hook heartbeat and drop files under `.aidlc-hooks-health/` are renamed to match. The `.aidlc-stop-hook/` counter directory keeps its name so an in-flight workflow's no-progress counter is not orphaned.
* Kiro IDE registrations renamed: `aidlc-block` is now `aidlc-enforce-approval-gate` and `aidlc-mint` is now `aidlc-record-human-turn`. Every Kiro CLI and Kiro IDE registration now carries a plain-English description.
* Hook adapter target words follow the same vocabulary on Kiro CLI, Kiro IDE, and Codex (`stop` to `continue-workflow`, `mint` to `record-human-turn`, `block` to `enforce-approval-gate`, `pretool-block` to `guard-tool-call`, `state-sync` to `sync-workflow-state`, `runtime-compile` to `rebuild-stage-graph`, `dispatch-rules` to `deliver-stage-rules`). Old target words are not accepted: a hand-written registration or script that passes one is a no-op, so update it to the new word.
* `aidlc-utility intent-birth` is now `aidlc-utility intent-create`, and the workspace form `aidlc intent birth` is now `aidlc intent create` (matching `space create`). Scripts and CI that call the old name must be updated. Running the old name now tells you it was renamed and that the flags are unchanged, instead of printing the whole command list. An existing intent record named "birth" stays reachable via `intent switch birth`.
* Creating an intent now makes one artifact folder per phase the scope runs, plus `verification/` (created for every scope). A `bugfix` or `refactor` record has no `ideation/` or `operation/` folder at all; a `feature` or `enterprise` record still has all five. Previously a `bugfix` workflow opened with an empty `ideation/` and `operation/` beside the folders it would really use, reading as planned-then-abandoned work, while the audit trail already recorded the same decision as `PHASE_SKIPPED`. The folders created and the phases reported skipped now derive from one place, so they always agree.
* The `WORKSPACE_SCAFFOLDED` and stage-completion audit entries now report how many in-scope phase folders were created, instead of implying a fixed set.
* Removed `tools/data/scaffold/`, 26 empty directories shipped in every harness tree that no code read. Per-stage folders were never created up front and still are not: a stage's folder appears when it first writes an artifact. The user guide, CLI reference, orchestrator reference, and the Workspace Scaffold stage text said otherwise and are corrected.
* A "Talking to the user" voice contract now lives in the stage protocol every harness loads on every stage, so all five distributions inherit one voice. It governs wording only and states explicitly that mechanics, verbatim tool output, and audit vocabulary are unchanged.
* The sentences you read between steps are now written by the framework rather than improvised. Each instruction the workflow returns can carry the line that describes it, already worded in terms of your project, and the assistant relays that text instead of narrating what it just did. Where nothing is written for a moment, that moment passes in silence: no play-by-play, no naming the tool about to run, no reading a field back to you. The result is fewer sentences and more of them about your software. All five harnesses relay it identically.
* Entering a stage now says who is doing the work in ordinary job titles, not agent filenames: "The developer takes a look at the codebase first, then the architect builds on what comes back." The review step says what it is for ("Let me have the quality engineer check this over before you see it") rather than citing the protocol section that mandates it.
* The first thing said in a session is about your request rather than the framework starting up, and completing a workflow says your work is finished and written up.
* The welcome banner shown at session start describes scope in your terms: "Scope is set from your command, or auto-detected from what you describe" replaces "The orchestrator determines scope".
* The header on the rules delivered to each stage says what those rules are instead of which component resolved them, so an assistant quoting its own context back to you no longer quotes framework internals.
* The composer's plan proposal leads with a plain-language recommendation ("this looks like a small, well-understood change, so I suggest a short run") and the stage list, then shows the scores under a "Scoring detail (advisory)" heading. The scores, bands, and `method` line still appear in full, just below the recommendation instead of as the headline.
* Scope questions read plainly: a keyword match now asks "This looks like <name> work, so I'd run the <name> plan", and an unclear task says "None of the ready-made plans is an obvious fit" instead of "No stock scope clearly fits". The stage and gate counts and the `compose` affordance are unchanged.
* Error and refusal messages lead with a plain first sentence and keep the exact remedial command: the steering-token family, the stale-position and changed-route cases, the transport-budget warning, and the two autonomy refusals (which no longer mention the swarm). Blocked-action messages carry an `[aidlc]` prefix so a line on stderr is attributable. The refusal for changing stage status by hand explains that the workflow tools own it; the `set-status` refusal now tells you the status updates by itself and that `/aidlc --status` shows it. The creation summary says `Intent created:` rather than `Intent born:`.
* The onboarding doc (`CLAUDE.md` / `AGENTS.md`) opens with what AI-DLC does for you rather than a component inventory, and the sensors, tools, and hooks entries describe what they do in the reader's terms. `--help` wording for `compose`, `--new-scope`, and the auto-created workflow record is plainer.
* Approval-gate and completion templates ask in plain words (what was produced, what to look at, what happens next), the depth and test-strategy note explains itself, and the Bolt-planning questions drop the jargon while keeping Bolt and Unit of Work.
* Building a piece of your work now says so. Construction repeats the same stage once per unit, and those repetitions previously passed without any written line, so what filled them was the loop's own bookkeeping: which pass of the iteration it was, whether an approval gate had resolved, what a stage's output list came to. Each build pass now reads as one sentence naming the unit and the stage ("Now working on counter-core: the Functional Design pass"), and the pass that closes the stage says nothing because the approval gate follows immediately.
* "Bolt" is explained the first time you see it. Entering Construction now reads "Starting the first Bolt now: one build pass over the code, tests and checks for a piece of the work", and the delivery-planning questions and artifacts carry the same one-clause definition at first mention, for Bolt, walking skeleton, mob, Program Board, and any scoring model named by initials. Later mentions stay short.
* The walking-skeleton question in Practices Discovery asks something answerable: "Build a thin end-to-end slice first? A walking skeleton is a minimal version that runs the whole way through, built first to prove the pieces connect before the real features go in." It previously asked whether to "run the skeleton ceremony first", which was the framework's own phrasing for how it classifies your answer.
* The per-stage observation diary no longer opens by naming a framework component. Its first line, which appears in the diff every time a stage updates it, now reads "This file is kept up to date automatically while the stage runs."
* Loading a stage's rules no longer produces a sentence at all. The assistant was told not to print a progress message and wrote its own line in that slot instead ("Continuing to the stage directive", six times in one run); rule loading is not an event in your project, so no wording of it appears.

## [2.5.56] - 2026-08-07

Under `Construction Iteration: unit-major`, code-generation now joins the per-unit walk: each Unit of Work is designed (3.1-3.4) and then BUILT (3.5) before the next unit begins, so the first working code lands after one unit's design instead of after every unit's. This completes the unit-major increment shipped in 2.2.13, which deferred code-generation ("widening the walk's block filter"). The stage-major default is unchanged and byte-identical. **Behaviour change for existing unit-major users:** a workflow with the knob set resumes onto the widened walk, and the autonomous Construction swarm no longer fires while the knob is set (the walk owns the build, serially in Bolt build order; unset the knob or use stage-major for parallel batch swarms).

* Unit-major walk block widened from the four inline design stages to every per-unit Construction stage in graph order, code-generation included; per-stage approval gates are unchanged in count and machinery, cascading once the whole (stage x unit) grid, code-generation included, is covered.
* Code Generation's per-unit Step 3 Plan Approval still hard-stops before generation, including under an autonomous grant: the stop hook follows the active unit-major directive's stage and unit, and only that unit's blank Plan Approval question can release the autonomous stop; unrelated clarification questions keep the loop running.
* Final `run-stage` directives record a state-bound active-stage marker for path-only PostToolUse hooks, so linter/type-check results, audit rows, and `.aidlc-sensors/<stage>/` details from interleaved code generation are attributed to `code-generation`, not the earlier design stage. Task activation refreshes this transient marker without moving the durable first-stage cursor, preserving the full end-of-grid gate cascade.
* Autonomous swarm emission is suppressed while `Construction Iteration: unit-major` is set: the walk's coverage signal is disk artifacts and the swarm's is convergence audit rows, and two owners would re-fan already-built units. The report-side settled-swarm approve exemption is untouched, so units a prior stage-major swarm built in worktrees still approve after the knob flips.
* `delivery-planning` Step 7 classification, `stage-protocol.md`, the construction stage reference, and all five harness SKILL.md files updated to the widened semantics.

## [2.5.55] - 2026-08-07

Hardens the human-authorization boundary and adds unit-of-work lifecycle receipts, closing the reliability and authorization gaps reported in the brownfield Codex evaluation (issue 681). **Upgrade:** re-copy your `dist/<harness>/` tree into the project; if your CI drives gates against bare fixtures via the audit CLI, set `AIDLC_ALLOW_DIRECT_AUDIT_EVENTS=1` in those runs (the test suite sets it automatically).

* The public audit CLI is now a diagnostic escape hatch only: `aidlc-audit.ts append` / `append-batch` refuse authority-bearing receipts (`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) with an error naming the owning tool; `append-raw` refuses taxonomy `**Event**:` lines and line-breaking headings; audit field names use a strict single-line label grammar, closing control-character injection as well as the exact `Event` key.
* `aidlc-bolt.ts set-autonomy --mode autonomous` requires a fresh human turn (the ladder-prompt answer), and one audit lock now covers the presence check, receipt, and state write so concurrent grants consume that turn exactly once; switching back to `gated` needs no presence. The error tells the conductor to ask the human to confirm autonomy in a typed message.
* Human-presence freshness is now shard-aware: a candidate human turn must be provably newer than every latest resolution; when any resolution shares its second-precision timestamp in another audit shard, the gate fails closed and asks for a fresh turn instead of trusting shard filename order.
* Cancellation boilerplate ("Cancelled", "dismissed", "timed out", empty text) is refused as an interview answer (`aidlc-log.ts answer`), an approval choice (`approve --user-input`), and rejection feedback (`reject --feedback`) — a dismissed question widget can no longer mint a `QUESTION_ANSWERED` or commit a gate. A substantive rejection now also requires and consumes a fresh human turn, matching approval.
* New unit-of-work lifecycle receipts on inline per-unit Construction stages: `aidlc-state.ts unit start|pause|resume|complete` emits `UNIT_STARTED` / `UNIT_PAUSED` / `UNIT_RESUMED` / `UNIT_COMPLETED` (event taxonomy 78 → 82). `unit start` accepts safe legacy DAG names, including digit-leading names such as `2fa`, but must match the engine's exact routed stage/Unit pair, so dependencies and earlier same-batch Units cannot be bypassed. Autonomous swarms preserve those legacy Unit identities while deriving deterministic, collision-resistant internal Bolt slugs for worktree operations. A retained autonomy grant no longer blocks receipts after a backward jump to an inline stage; swarm-owned stages still refuse interactive receipts. State-mirrored checkpoint text stays on one line, and every receipt carries an exact stage-attempt `Run floor`; unit-major receipts survive their stage's later start, while workflow/jump/rejection boundaries invalidate them. Cross-shard same-second boundary ambiguity invalidates prior receipts instead of trusting shard filename order, and lifecycle ties preserve a possible pause or other non-terminal state instead of settling or resuming the unit. Receipt mode remains active across attempts, so stale rows cannot restore artifact-only settlement. `unit complete` requires regular artifact files; directories named `*.md` do not count. Once any receipt exists for a stage, the engine requires a receipt per unit.
* Swarm `prepare` now stamps successfully prepared worktrees with the exact stage attempt; failed re-prepares cannot relabel preserved worktrees. `finalize` refuses a stale prepared attempt before merge and carries the captured token into `SWARM_UNIT_CONVERGED`, closing same-second and late-retry convergence replay. In-flight worktrees prepared by the preceding unstamped release remain finalizable when their frozen fork evidence and hash prove they belong to the current attempt; stale or incomplete legacy preparations still fail closed.
* A paused unit hard-stops the engine: `next` emits an ask naming the unit, its recorded `--reason`, and `--next-action` (`unit_state: paused`) until an explicit `unit resume`, and `report --result awaiting-approval` is refused while a unit of the stage is paused. `unit start` refuses while another unit is open (one active unit at a time).
* The state file mirrors the active checkpoint under `## Runtime State` (`Active Unit`, `Unit State`, `Unit Pause Reason`, `Unit Next Action`) so `--status` and session resume land on the exact stopping point.

## [2.5.54] - 2026-08-07

Stage reviews now run under a review class, cutting the dominant latency cost of the human-gated prose stages. Live A/B runs against the real harness showed the adversarial refute-fix-re-review loop spending 12+ minutes per inception stage on review choreography alone (the shape behind reports of 30-minute Requirements Analysis waits); the 7 human-gated ideation/inception prose stages now default to a single advisory pass whose findings are quoted verbatim at the approval gate for the human to triage, while the 5 Construction design/build stages keep the full adversarial loop. The iteration cap is now engine-enforced rather than prose-only, and the reviewer tier runs at medium effort (measured at ~half the review wall-clock with no finding-quality loss). **Upgrade:** re-copy your `dist/<harness>/` shell into the project; existing workflows pick the classes up on the next stage directive.

* New stage frontmatter field `review_class: adversarial | advisory` (requires `reviewer`; defaults to `adversarial` when a reviewer is declared). The 7 prose stages (intent-capture, rough-mockups, requirements-analysis, user-stories, refined-mockups, application-design, units-generation) ship `advisory`; the 5 Construction stages (functional-design, nfr-requirements, nfr-design, infrastructure-design, code-generation) stay `adversarial`.
* Advisory contract: one review pass, both verdicts terminal, `reviewer_max_iterations` pinned to 1, findings ranked by severity and quoted verbatim at the approval gate; a Request Changes at the gate is how a finding becomes a revision. Evidence-grounding still applies; the reviewer personas carry the advisory stance.
* Scope ceiling: scopes may declare `review_cap: adversarial | advisory | none`; the shipped `bugfix`, `poc`, and `workshop` scopes cap to `advisory`. Invalid values fail scope metadata loading loudly.
* New per-run override `/aidlc --review <adversarial|advisory|none>`: lowers the effective class for the active workflow (low-wins against stage declaration and scope cap; `adversarial` clears the override and can never raise a class). Birth, flat-layout migration, scope-change, and same-scope config routes all preserve it; a missing value is rejected instead of silently retaining the prior policy; `none` removes both reviewer dispatch and the matching completion receipt requirement outside autonomous Bolts. Updates the `Review Override` state field, emits the new `REVIEW_CLASS_CHANGED` audit event (78-event taxonomy), and shows in `config list` / `config get review`.
* Engine-enforced iteration ceiling: `aidlc-log.ts review` requires a positive `--iteration`, derives the next ordinal from current-attempt audit history under the audit lock, and refuses duplicate, out-of-order, or over-budget `REVIEW_REQUESTED` rows (advisory 1, adversarial `reviewer_max_iterations`, override `none` 0). A failed or interrupted dispatch can explicitly reuse its unmatched request with `--retry-pending`; the retry is audit-marked and consumes no new iteration. Inline per-unit stages keep scope/run caps; only a matching autonomous Bolt attempt uses the declared class. `REVIEW_COMPLETED` receipts remain recordable after dispatch, and both review events are reserved from every public `aidlc-audit` append route.
* Autonomous swarm (Bolt) reviews are exempt from scope caps and run overrides: inside a Bolt the reviewer is the only pre-merge verification, so the declared class always applies, including advisory's single-pass limit.
* The reviewer tier (`balanced`: product-lead + architecture-reviewer) now pins `medium` reasoning effort on Claude, Codex, and opencode instead of inheriting the session effort.

## [2.5.53] - 2026-08-06

Adds a kill switch for the Claude Code token-usage and cost tracking introduced in 2.5.40. Local tracking (the usage ledger, the statusline `up/down/$` segment, and the completion-event cost rollups) remains on by default; set `AIDLC_DISABLE_USAGE_TRACKING=1` to turn all of it off. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; no action is needed to keep the default behavior.

* New `AIDLC_DISABLE_USAGE_TRACKING=1` disables the whole usage seam: the fold hooks and Stop-hook flush write nothing, the statusline renders no cost segment, and `STAGE_COMPLETED` / `WORKFLOW_COMPLETED` add no rollup fields. Any other value (or unset) leaves tracking on, matching the `AIDLC_DISABLE_*` hook-flag convention.
* An already-recorded ledger is left on disk untouched while the flag is set, so unsetting it resumes history rather than restarting it; delete `aidlc/.aidlc-sessions/usage-ledger.json` manually if the history should go too.

## [2.5.45] - 2026-08-06

Plugin management commands now route deterministically through every `/aidlc` slash-command harness instead of being misread as freeform workflow requests. **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the shared plugin parser and harness routing updates are installed.

* `/aidlc plugin list [--json]`, `/aidlc plugin sync`, and `/aidlc plugin select [names]` now dispatch to their existing utility handlers without asking to compose a scope or advancing an active workflow.
* `/aidlc plugin help`, a missing plugin verb, and unknown plugin verbs now produce deterministic help or errors across the dispatcher, orchestrator, and Kiro pre-LLM interceptor.
* Kiro terminal-command interception now latches plugin utilities for the current turn, preventing a conductor retry from rolling the workflow forward after the plugin command completes.

## [2.5.44] - 2026-08-06

Human-readable AI-DLC artifacts now follow the conversation language instead of defaulting to English. The framework rule layer gains four `## Mandated` rules in `org.md` that define how the conversation language is resolved, why it stays stable across short turns like `Approve`, which artifacts are localized, and which protocol tokens stay English. The rules travel to delegated agents and reviewers inside the active-stage rule bundle the dispatch-rules hook already delivers, so a subagent that never sees the conversation can still resolve the language from the rule layer, `aidlc-state.md`, or the upstream artifacts it consumes. **Upgrade:** fresh installs receive the rules with their seeded `default` space. An existing workspace keeps its own memory tree — runtime self-healing intentionally does not overwrite one — so merge the four rules into each `aidlc/spaces/<space>/memory/org.md` by hand and start a fresh session for them to load.

* Human-readable artifacts (requirements, user stories, plans, specs, reviews, questions, discovered practices, affirmed rules, evidence, decision rationale) are written in the workflow's established conversation language, including the descriptive text of a rule shaped as `ALWAYS …` / `NEVER …`.
* The conversation language is resolved in a fixed order — the `Conversation language:` line the orchestrator is now required to state in every delegated brief, then an explicit language rule in `project.md` — the only file a language switch is ever persisted to, and one that always outranks a `team.md` default, because the runtime rule chain concatenates `org → team → project → phase` and so bundle position is not recency: a newer team-level rule reaches an agent *before* a staler project-level one, and the winner is the stated precedence rather than the later position — then the verbatim `**Project**` description in `aidlc-state.md`, then any artifact or draft the agent was handed (the directive's `consumes[]` contracts, the artifact under review, or the lead draft it was dispatched against). The brief line ranks first because the orchestrator regenerates it from the live conversation on every dispatch, so it can never be staler than a rule already on disk. It is also mandatory because the file-reading sources can all be empty: a greenfield run of a stage whose `consumes` are every one `conditional_on: brownfield` reaches its dispatched lead with no upstream artifact at all.
* The language is stable: a turn carrying no language signal (`Approve`, `Looks correct`, an option letter or number, pasted code, a quoted error or stack trace, a bare path) never switches it. Only an explicit human request does, and that switch takes effect immediately — the orchestrator carries the new language in every subsequent brief. Recording it under `## Corrections` in `project.md` (never `team.md`) is durability, not activation, so nothing waits on the human-gated learnings ritual — and that ritual is the only sanctioned write path for persisting a language switch, so agents never hand-edit a memory file to record one, while the deterministic memory writers a stage invokes by contract (such as `aidlc-state.ts practices-promote`) are unaffected. A declined persistence is a correct outcome: the brief carries the language for the rest of the session. A persisted rule never outranks the brief or a later explicit switch request — it is the fallback for a brief that states no language — and because the learnings write path appends rather than replaces, the last conversation-language rule under `## Corrections` in `project.md` is the current one.
* That stability guarantee is scoped to the session, which is as far as the brief line can carry an unpersisted switch. A workflow outlives a session, and the resume context injected at session start carries scope, phase, stage, status, agent and next action but no language, so the first turn of a new session re-resolves the language before dispatching anything: the persisted rule, else the human-readable artifacts the workflow has already produced, else the verbatim initial description — and it asks the human rather than defaulting to English when all of those are silent. Re-resolving is not a switch, and is never announced or persisted as one. Accepting the learnings ritual is therefore what makes a switch survive a resume.
* The English exception is now scoped to machine-parsed syntax rather than whole files, and states a general principle: a literal a stage file spells in backticks and tells you to write exactly is a fixed token — including option labels and sentinel values, not just syntax. Named instances cover `[Answer]:` tags and the mandatory `X. Other (please specify)` option, the `A. Accept assumptions` / `B. Convert to follow-up questions` confirmation answers the engine compares literally, the `None.`/`None` sentinels, `AGREE:`/`OBJECT:` prefixes, the `**Collaborator:** <agent-slug>` first line the engine matches exactly on a contribution file, the `[desc]`/`[scope]`/`[assumption]`/`[Q<n>]`/`[memory:M<n>]` source-register tags, template H2 headings the sensors match verbatim, the `READY`/`NOT-READY` verdicts, fenced YAML keys and enums, `aidlc-state.md` and audit-shard field labels, stable IDs, code, paths, mermaid keywords, and cross-references. Glossing a literal when presenting it to a human is allowed; what is written into an artifact is the literal. Prose surrounding a preserved token is localized, and a Markdown artifact is no longer treated as English just because a tool parses part of it.

## [2.5.43] - 2026-08-06

Stops `/aidlc --doctor` from reporting hook decay on the Kiro IDE harness when a write simply failed. The adapter recorded a visible hook drop whenever it could not extract a file path from a write tool's result, which conflated two very different situations: a write that FAILED (no artifact exists, so declining to forward it is correct) and a write that SUCCEEDED but whose result wording could not be parsed (the genuine degradation the drop log exists to surface). Only the second belongs there. **Upgrade:** `mkdir -p your-project/.kiro && cp -R dist/kiro-ide/.kiro/. your-project/.kiro/`. If `/aidlc --doctor` still reports a Kiro adapter drop created before this fix, inspect the affected intent record's `<record>/.aidlc-hooks-health/kiro-adapter.drops`; delete only that individual file, and only after verifying its entries are historical/stale. Preserve it if it contains current failures.

* `/aidlc --doctor` no longer reports hook degradation on a workspace whose hooks are working correctly. A failed `str_replace` - for example one whose old string matched multiple times - is no longer counted as a drop. The IDE 1.x stdin channel carries no success flag, so these failures arrive only as error prose and the existing `toolSuccess` guard could not catch them; every one of them was logged as decay, which trains the reader to ignore the one channel that matters when something genuinely breaks.
* A *successful* write whose result wording matches no known path pattern is still recorded as a visible drop, unchanged. The failure classifier is deliberately narrow (start-anchored failure prefixes, not a loose "contains error" test), runs only when the payload has no structured success flag, and never overrides legacy IDE 0.12's explicit `toolSuccess: true`; the default stays biased toward reporting rather than silence.
* Of the four failure-prose patterns the classifier matches, only `Caught an error while ...` is grounded in a live capture; the other three are marked in the code as defensive guesses rather than observed shapes. A match can only suppress a drop after path extraction has already failed and structured success is unavailable, and no known success wording begins with error prose, so the risk direction is one-way.
* Docs: `docs/reference/kiro-ide-hook-payload.md` describes the failed-write/unrecognized-success split and makes `hookDebug`'s opt-in behavior explicit. No command, flag, or audit/sensor output-format changes; no breaking change for CI or scripts.

## [2.5.42] - 2026-08-06

Restores the gitignored `aidlc/active-space` cursor after cloning a committed workspace. The cursor still defaults safely to `default` when absent, but SessionStart and active-intent writes now atomically materialize it without overwriting a concurrent explicit space switch. **Upgrade:** re-copy your `dist/<harness>/` shell so the updated library and SessionStart hook are installed; no repository migration or configuration change is required.

* A fresh clone now recreates `aidlc/active-space` on SessionStart, even before an intent exists, so the shipped workspace model remains visible without committing per-user navigation state.
* Intent birth, intent switching, and flat-layout migration recreate a missing space cursor through the same best-effort cursor primitive.
* Cursor creation stages complete bytes and publishes them through an atomic no-replace link, so it cannot overwrite a concurrent `/aidlc space <name>` switch.

## [2.5.41] - 2026-08-05

Code Generation's plan-before-generation ordering is now enforced deterministically. A field report showed the conductor generating code first and backfilling `code-generation-plan.md` beside `code-summary.md`, turning the plan into a retroactive summary; the new plan-approval PreToolUse guard refuses the developer-agent dispatch until the target unit's plan is on disk and the human has answered "Approve Plan". **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the new hook and its registrations are installed.

* New framework hook `aidlc-plan-approval-guard.ts` (the 16th): while Current Stage is code-generation, a Task/subagent dispatch targeting `aidlc-developer-agent` is refused with a redirecting reason unless its explicit `AIDLC-UNIT: <unit>` marker identifies one known unit with a non-empty `code-generation-plan.md` on disk and a Plan Approval question recording the explicit "Approve Plan" response. Missing, conflicting, and unknown markers block; contextual references to sibling units do not affect the target. Numbered headings such as `Q1: Plan Approval` and `Question 1 - Plan Approval`, plus `## Q1` sections with `Plan Approval` as the question text, are accepted; blank tags, "Request Changes", unrelated answers, and examples inside comments or code fences keep blocking.
* Each refusal emits a `PLAN_APPROVAL_BLOCKED` audit event (the 77th event type) naming the tool, target agent, and marked unit.
* Wired on Claude Code (settings.json `Task` matcher), Kiro CLI (conductor agent `subagent` matcher via the adapter), Codex (hooks.json PreToolUse target), and opencode (plugin `tool.execute.before` on `task`). Kiro IDE documents the bound as prose-only, matching its other guards.
* Autonomous Construction uses the same mandatory per-unit Plan Approval evidence as every other execution mode. `AIDLC_DISABLE_PLAN_APPROVAL_GUARD=1` disables enforcement entirely. The guard fails open outside its guarded dispatch (no state file, another stage, another agent, malformed payloads), while ambiguous target markers fail closed.

## [2.5.40] - 2026-08-05

Adds per-stage and per-workflow token-usage and cost tracking plus an opt-in metrics emission seam. On Claude Code, a new fold hook registered for both PreToolUse and PostToolUse records transcript usage in a durable, gitignored `.aidlc-sessions/usage-ledger.json`; the statusline gains a current-workflow/current-session `↑in ↓out $cost` segment, and `STAGE_COMPLETED` / `WORKFLOW_COMPLETED` audit events gain correctly scoped token and cost rollups. Everything remains off by default and additive: unknown models record tokens with a null cost, metrics emit only when `AIDLC_METRICS_ENDPOINT` is set, and non-Claude harnesses simply have no producer. **Upgrade:** re-copy your `dist/<harness>/` shell into the project. No action is required to stay silent; opt into metrics with `AIDLC_METRICS_ENDPOINT`, and override rates with `AIDLC_MODEL_RATES` or the installed `tools/data/model-rates.json`.

* New Claude-only `aidlc-fold-usage.ts` registrations run before and after every tool call: PreToolUse seals the completing main-transcript call and flushes completed subagent calls before workflow-engine boundaries, PostToolUse provides the normal holdback fallback, and the Stop hook flushes every remaining main/subagent group at turn-end, including a complete final JSONL record with no trailing newline.
* Ledger updates serialize across processes, use writer-unique atomic temporary files, and retain stage, workflow, and session ownership at the transcript-message boundary so concurrent sessions and lifecycle transitions cannot lose or misattribute usage. A malformed EOF fragment also keeps the possibly related preceding group pending, preventing split-message double counts.
* The statusline reports only the active session, `STAGE_COMPLETED` reports the completed stage, and `WORKFLOW_COMPLETED` reports the full active intent. Unknown-price models remain tokens-only rather than emitting a fabricated `$0`.
* Model normalization enforces provider/model token boundaries and resolves exact generation keys from the effective rate table, including generations added through `AIDLC_MODEL_RATES`.
* Metrics emission is opt-in via `AIDLC_METRICS_ENDPOINT` and uses a detached Bun/TypeScript worker with native `fetch()`, adding no HTTP executable dependency. The endpoint, custom headers from `AIDLC_METRICS_HEADERS`, and metric body travel in a JSON envelope over stdin; endpoint and headers are removed from the child environment and nothing sensitive enters process arguments. Batch audit appends use the same metrics tap as single events.

## [2.5.39] - 2026-08-05

Fixes a live-session wedge at reviewer-bearing approval gates. A conductor that applied reviewer recommendations after recording the terminal review receipt invalidated its own receipt, then re-reviewed, re-edited, and oscillated instead of reaching the gate. The protocol now states the terminal ordering explicitly, and deterministic enforcement covers direct file tools, shell writes, compiled dispatch, and delegated Kiro writers. **Upgrade:** re-copy your selected `dist/<harness>/` shell into the project so the updated protocol, skills, hooks, tools, and agent configs are installed.

* Stage protocol section 12a makes a READY receipt terminal: fixes stay inside the reviewer iteration loop, no declared `produces[]` artifact is written between the receipt and gate approval, suggestions riding on READY are quoted for the human instead of applied, and Approve remains the first gate option.
* New `aidlc-review-freeze.ts` PreToolUse hook, the 15th framework hook, refuses file-tool, apply-patch, and mutation-capable shell writes that would invalidate a fresh READY receipt. It exports the compiled dispatcher's `run(input)` contract, covers every writable Kiro CLI conductor and delegate surface, emits `REVIEW_FREEZE_BLOCKED` as the 76th audit event, and can be disabled with `AIDLC_DISABLE_REVIEW_FREEZE_HOOK=1`.
* Every `REVIEW_COMPLETED` receipt records a SHA-256 fingerprint of the declared artifact paths and bytes. Approval and swarm finalization require that fingerprint to remain current, so an unobserved interpreter, shell, or delegated write cannot leave stale reviewed content certified.

## [2.5.38] - 2026-08-05

Every harness now treats the consolidated answer review as a mandatory, separate human checkpoint before artifact generation. The checkpoint is backed by a prompt-specific human receipt, the exact questions-file digest, and post-confirmation artifact-write evidence, so a conductor cannot satisfy it by writing `Looks correct` itself. **Upgrade:** re-copy the selected `dist/<harness>/` into the project so the updated conductor skill, tools, stage metadata, and question-rendering annex are installed.

* All five conductor skills now require consolidated summary confirmation before artifact generation in workflow, isolated, self-guided, and per-unit runs. `aidlc-log.ts decision/answer --checkpoint summary-confirmation --questions-file <path>` records the reserved `SUMMARY_CONFIRMATION_RECORDED` receipt; the public audit CLI cannot forge this event, and completion refuses missing, stale, cross-unit, changed-file, or post-generation receipts.
* Each harness renders **Looks correct / Request changes** through its native question surface as a separate turn and requires `[Answer]: Looks correct`; prefixed forms, bare letters/numbers, and self-selected answers do not satisfy the checkpoint. **Request changes** now stops again for concrete feedback before any answer is revised.

## [2.5.37] - 2026-08-03

The orchestrator must never echo a fenced ` ```question ` block as literal chat text: the fence is an authoring spec rendered through each harness's question mechanism, never printed verbatim. Dumping the raw fence yields a non-interactive wall of text and drops the answerable options and "Other" escape supplied by the harness's native tool or numbered-prose fallback. This tightens the harness-neutral stage protocol and every per-harness question-rendering annex (Claude, Codex, Kiro CLI, Kiro IDE, opencode). Literal fences remain in framework documentation, but the stage protocol's fences are normative prompt specs whose contents must still be rendered when their surrounding instructions require them; only raw fence syntax is excluded from live chat. **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the updated protocol and question-rendering annex are installed. Behavior is a documentation and contract change only; no command, flag, or state format changes.

* The harness-neutral `stage-protocol.md` section "Structured questions" now states that a ` ```question ` fence is a normative prompt spec rendered through the annex and is never printed verbatim ("spec in, answerable prompt out; never echo the fence"), whether the harness uses a native tool or numbered prose.
* Each harness question-rendering annex gains a non-negotiable "Never echo the spec" section naming the failure a protocol violation, listing non-exhaustive representative structured-question sites including consolidated-summary confirmation, and distinguishing normative stage-protocol templates from illustrative annex examples.

## [2.5.36] - 2026-08-03

Adds an optional declared workspace manifest for multi-repo teams. AI-DLC already auto-discovers sibling code repos on disk at intent birth; this release lets a team also declare that expected set in a `repos.json` file at the workspace root and reconcile it with a new `aidlc-workspace-sync` tool that clones missing repos, maintains a managed `.gitignore` block, and generates a VSCode multi-root workspace. The manifest is a convenience layer only: disk discovery remains the runtime source of truth, so a repo works the moment it is cloned whether or not it is declared. `--doctor` gains three advisory rows about manifest state. **Upgrade:** re-copy your `dist/<harness>/` shell to pick up the new tool; without `repos.json`, sync stays dormant and doctor adds only the advisory workspace-records row.

* New tool `aidlc-workspace-sync.ts` (run `bun <harness-dir>/tools/aidlc-workspace-sync.ts [--force]`): reads an optional `repos.json` (`{ "org", "repos": [{ "name", "branch"?, "url"? }] }`) at the workspace root, clones declared-but-missing repos on their declared branch, rewrites the managed block in the workspace `.gitignore`, and writes `aidlc.code-workspace`. Reconciles serialize under a workspace lock that cannot be reaped while its owner is alive; clones and generated files are staged before a reversible transaction. Concurrent manifest or output edits abort instead of applying stale state, no-replace installs close the final path race, and prior generated files are retained for recovery. Exit `0` in sync, `1` blocked/error with live paths unchanged, `2` synced with advisory warnings.
* Orphan safety: a checkout on disk but not in `repos.json` leaves the active sibling set only with `--force` after the tool overrides configurable status defaults, checks untracked and ignored content (including empty directories), hidden index state, stashes, refs and reflogs, unreachable Git objects, linked worktrees, submodules, and LFS object stores. Matching live refs must have fetchable object graphs - an advertised OID alone is not recovery proof - and local remotes whose storage or object alternates depend on the checkout cannot authorize removal. After revalidation, the checkout moves into transaction quarantine and receives the full local and live-remote proof again; its quarantined copy is retained in an ignored `.aidlc-workspace-sync-recovery-*` directory instead of being recursively deleted, so even a concurrent writer holding the directory open cannot lose a late write. Inspect and manually delete retained recovery copies when no longer needed. Existing repos are never re-cloned or branch-switched; their `branch` mismatch is advisory.
* `/aidlc --doctor` gains three advisory rows (they never change the exit code): uncommitted changes under `aidlc/`, `repos.json` vs on-disk sibling drift, and a stale managed `.gitignore` block. Doctor and sync share the same strict manifest schema, including safe immediate-child names, so invalid JSON or schema never appears synchronized. The drift and gitignore rows appear only when a `repos.json` exists, so single-repo installs do not gain manifest-specific rows.
* User Guide documents the optional manifest in Spaces and Intents and the tool invocation in CLI Commands, both stressing that the manifest never overrides runtime disk discovery.

## [2.5.35] - 2026-08-03

Reverse Engineering no longer silently discards a prior intent's code knowledge on rerun. The shared per-repository codekb now records and compares actual scan coverage before replacement, keeps full-root freshness checks stable, and resolves every repository before advancing a multi-repo stage. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; existing stores predate scope tracking and report `UNKNOWN_SCOPE` until their first post-upgrade scan writes the new scope block.

* `reverse-engineering-timestamp.md` now ends with a structured `## Scope of Analysis` block recording full/partial coverage, analyzed and shallow paths, components, intent, and a content fingerprint.
* The direct `aidlc-utility codekb-scope-diff` verb reports `NO_STORE`/`CURRENT`/`STALE`/`UNVERIFIED`/`UNKNOWN_SCOPE`, compares incoming coverage as `COVERS` or `NARROWER`, and mints working-tree fingerprints for recorded paths.
* Full-root fingerprints exclude the framework-owned `aidlc/` tree so writing codekb, scope-draft, state, and audit files does not immediately make a store stale. Invalid or unmatched pathspecs now produce `unknown`/`UNVERIFIED` instead of Git's stable empty-tree hash.
* `kind: full` now requires explicit repository-root (`./`) coverage, and a full store can only be replaced without warning by another valid full scan.
* Multi-repo reruns resolve all reuse/rescan decisions before one lifecycle report, scan only repositories that need replacement, and use repository-specific scope drafts so parallel scans cannot overwrite one another.

## [2.5.34] - 2026-08-03

The plugin contribution seam now merges `adds.scopes`: a plugin can put an existing core stage under one of its OWN scopes, so a single plugin scope can carry a run through both the plugin's stages and the core stages it routes onto. Previously the surface was declared-but-deferred (drop-logged, never merged). **Upgrade:** re-copy your `dist/<harness>/` shell and re-install/re-sync your plugins so the updated compose hook and `select-plugins` strip are in place; already-installed plugins recompose automatically on the next session start.

* A contribution's `adds.scopes` set-unions into the target stage's `scopes:` frontmatter and lands in the recompiled scope grid, exactly like `adds.produces`/`adds.consumes`/`adds.sensors`.
* Two guard rails, both dropped-with-log (visible in `/aidlc --doctor`), never merged: the scope's `scopes/<name>.md` identity file must already be installed, and that file's `plugin:` frontmatter must name the contributing plugin exactly (ownership is read from the installed file, never inferred from a name prefix; core scopes declare no `plugin:` and never merge).
* `/aidlc --select-plugins` now strips merged scope memberships when a plugin is disabled (recorded in the per-plugin contribution sidecar); re-enabling and recomposing restores them.
* Plugin compose hooks and `/aidlc --select-plugins` now share one workspace lock across stage mutations, contribution sidecars, selection changes, graph compilation, and rollback. Compose, plugin selection, intent birth, and in-flight recompose all queue for up to about 60 seconds behind live compose work, so concurrent plugin hooks cannot lose or skip each other's merges, disabling a plugin cannot race with compose and leave an untracked contribution active, and workflow mutations do not time out behind a legitimate compose.
* Workspace lock identity now resolves filesystem aliases, so the physical project path and a symlink to it cannot acquire separate compose/selection locks. Plugin identity comes from the host manifest (not plugin-authored stage/scope/contribution fields), mismatched ownership is dropped-with-log, and duplicate incoming scope identities are rejected before they can poison the installed roster.
* Quoted `adds.scopes` values participate in the same canonical set union as unquoted values. Disable removes only the membership compose actually added, preserving equivalent authored entries, and a failed graph compile rolls back newly copied plugin files and contribution writes so a corrected retry is not blocked by no-clobber.
* `adds.requires_stage` remains deferred (declared entries are still drop-logged, not merged).
* Graph compile now seeds NEW stage numbers in dependency order: each phase's batch of new stages is ordered by its own `requires_stage` edges before next-free indices are assigned (ties break by the authored `number:` hint, then slug; a cycle among new stages is a compile error). The engine owns all number values - a plugin's authored `number:` is a relative-ordering hint, never an absolute claim - so a multi-stage plugin's flow seeds validly regardless of filenames and uncoordinated plugins cannot collide on numbers. Already-pinned rows keep their JSON values unchanged; authored `name:` seeds the display name.

## [2.5.33] - 2026-08-01

Stage rules are now delivered deterministically instead of depending on the conductor choosing to read paths. The engine emits the active-space rule bundle as bounded `load-steering` directives before `run-stage`, and reviewer checklists are absorbed into reviewer agent bodies at build time - closing the observed skip where stages ran with none of their org/phase memory applied. **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the updated engine, skills, agents, and hooks are installed.

* `load-steering` delivers every substantive rule as ordered `{path, text}` content. Opaque `continue` tokens use a random machine-local MAC key and bind the stage, workflow state, bundle hash, directive hash, route, and next part; they cannot be re-signed from the public project path, and a fresh `next` restarts at part 1.
* Every directive remains below the common 28 KiB output floor. Oversized rules split at Markdown headings and then UTF-8 boundaries, with no size-based path fallback. Missing, unreadable, or invalid UTF-8 required rules stop before stage work with repair guidance.
* `run-stage.rules_in_context` now names the active-space files actually delivered. Persona and supplemental knowledge remain path-loaded pending a retrieval system; missing, unreadable, or invalid UTF-8 optional files produce actionable `context_warnings` and are omitted without blocking the stage. Large warning sets are summarized within the directive limit.
* Dispatched briefs carry the exact delivered rule content, not legacy rule paths. Claude, Codex, and opencode append a digest-framed active-stage bundle at the subagent tool boundary for every installed core or plugin agent; markerless copies cannot suppress it, and unknown path-shaped stage references fall back to the live stage. Kiro CLI cannot rewrite tool input and its agents already preload the active memory tree natively, so an incomplete or valid oversized brief proceeds with an advisory warning instead of a block (an unloadable required rule file still stops the dispatch with repair guidance); Kiro IDE retains native memory-resource preload. Comment-only rule templates remain excluded until they contain an affirmed practice.
* The two reviewer agents (`aidlc-product-lead-agent`, `aidlc-architecture-reviewer-agent`) now carry their `knowledge/<agent>/reviewing.md` checklist inside their generated agent bodies on every harness. The redundant per-agent knowledge globs were removed from the Kiro reviewer JSONs.

## [2.5.32] - 2026-07-31

Closes a silent-failure trap in the plugin mechanism: a plugin that shipped a sensor manifest under any name other than `aidlc-<id>.md` (or nested it in a subdirectory) composed successfully but was never discovered by graph compile or sensor dispatch, giving the author no signal at all. The compose hook now validates a plugin's `sensors/` manifests against the discovery contract and records a degraded drop naming the file and the required shape when a manifest could never fire; `/aidlc --doctor` surfaces that drop. **Upgrade:** re-copy your `dist/<harness>/` shell so the updated plugin compose hook is installed; if you author a plugin sensor, name its manifest `sensors/aidlc-<id>.md` at the top of `sensors/`.

* Plugin `sensors/` manifests are now checked at compose time: a manifest whose basename lacks the `aidlc-` prefix, or that sits in a subdirectory the flat sensor scan never reads, is not copied and is recorded as a degraded compose drop (surfaced by `/aidlc --doctor`) naming the file and the required `aidlc-<id>.md` shape.
* An undiscoverable sensor manifest an older compose hook already landed is reported the same way on the next compose, so an upgrade never leaves a dead sensor silently on disk.

## [2.5.31] - 2026-07-31

Sensor output parsing now tolerates leading stdout noise. When a sensor runs against a sibling repository, that repo's package manager (pnpm and similar) can print a run banner or lockfile warning before the wrapped tool's JSON; previously the dispatcher and the linter sensor did a bare parse of that stdout, so any preamble made the parse throw and the sensor's real verdict was silently discarded as an advisory PASS. Both parse sites now slice stdout to the first structural JSON character before parsing, and still degrade gracefully when even the sliced output is not JSON. **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the updated `aidlc-sensor` dispatcher and `linter` sensor are installed. No configuration or command changes.

* The sensor dispatcher (`aidlc-sensor fire`) and the `linter` sensor now strip package-manager banners and lockfile warnings that precede a wrapped tool's JSON, so a real FAILED or clean PASS verdict is no longer masked as `script-error: bad-output` when firing against a sibling repo.

## [2.5.30] - 2026-07-30

The default-scope resolver is now bundle-aware, so an install that disables the core scopes through plugin selection (a plugin-only install) no longer crashes or routes to a disabled scope when a default is needed. A scope can nominate itself as the install's freeform default with a new `freeform_default: true` frontmatter key; when the core preferred default (feature/poc) is not enabled the resolver picks the nominated scope, else the sole enabled plugin's alphabetically-first scope, else surfaces a descriptive error. Agent-facing prose that stated fixed stage and persona counts now points at the compiled graph and `--doctor` so it stays true under plugin selection. **Upgrade:** re-copy your `dist/<harness>/` shell into the project. No action is needed for a stock (no-plugin) install; behavior there is unchanged.

* New `freeform_default: true` scope frontmatter key lets a plugin nominate its own default scope for plugin-only installs.
* `intent-birth` with no `--scope`, the orchestrator's default scope, and the freeform inference fallback now resolve through the bundle-aware resolver instead of hardcoding `poc`/`feature`, so a plugin-only install resolves to a valid enabled scope instead of erroring with "Unknown scope".
* Explicit `AWS_AIDLC_DEFAULT_SCOPE` typos still fail with `Invalid AWS_AIDLC_DEFAULT_SCOPE`; only an installed scope disabled by plugin selection can enter bundle-aware fallback. Graph compilation also rejects multiple enabled `freeform_default` claimants instead of choosing one alphabetically.
* Onboarding, the stage protocol, the shared principles, and the per-harness `SKILL.md` agent-roster notes no longer assert fixed stage/persona counts that a plugin install would falsify; they point at the compiled stage graph and `/aidlc --doctor` for the live enabled set.
## [2.5.26] - 2026-07-29

The shipped workspace scaffold data and the Workspace Scaffold stage prose no longer advertise a per-intent `inception/reverse-engineering/` folder that nothing writes; the guides now describe where Reverse Engineering output actually lands. The stage writes its nine deliverables to the space-level per-repo store `aidlc/spaces/<space>/codekb/<repo>/`, one shared view per repo that each brownfield rerun overwrites; the intent record only ever receives the stage's own `memory.md` diary, created on demand. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; on installs that predate the shipped shell, an empty `inception/reverse-engineering/` directory left in an existing intent record can be deleted.

* Removed the empty `inception/reverse-engineering/` directory from the shipped workspace scaffold, where it read as "the nine artifacts belong here" and never received a file.
* Stage 0.1 Workspace Scaffold and `docs/guide/14-artifacts-reference.md` now state that the codekb store is refreshed by rerunning the scan and overwriting it (last write wins), not cached per intent, and that the record dir holds only the stage diary.

## [2.5.25] - 2026-07-29

The adaptive composer's ARS arithmetic is now deterministic: the new `aidlc-graph.ts ars` subcommand computes the weighted composite, band labels, the per-stage expected-value screen, nearest stock scopes, and both gate tables from the schema-versioned `tools/data/ars-priors.json`, so the same component scores always render the same proposal numbers — auditable and runnable without an LLM. The composer scores the five components from evidence and copies the tool's output; a model never does the multiplication. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `aidlc-graph.ts ars --iae <s> --csu <s> --ve <s> --r <s> --ua <s> [--completed <csv>] [--project-type <t>]` prints a JSON result: the advisory composite with its band, LOW/MED/HIGH component bands at the shipped 0.30/0.70 boundaries, the per-stage EV screen against the cost priors, nearest stock scopes by grid diff count, and the two gate tables pre-rendered as markdown.
* Component weights (0.20/0.30/0.25/0.15/0.10), band boundaries, stage cost priors, and EV thresholds move to `tools/data/ars-priors.json` (schemaVersion 1); the composer persona's tables now document that file instead of being the source.
* `--project-type brownfield|greenfield` screens out the stages whose compiled `condition:` restricts them to the other kind of project (today Reverse Engineering, brownfield-only), so the mechanical screen never proposes a stage that stage's own condition would skip; `--completed` keeps already-run stages EXECUTE in the derived grid and outranks that screen.
* Out-of-range scores, scores finer than the two decimals the rubric works in (`--iae 0.299` would render `0.30` against a documented `LOW < 0.30`), a `--completed` or `--project-type` flag left without a value, unknown stage slugs (`--completed`), and priors-schema violations — including a non-numeric stage `cost` or an unknown `projectTypes` value — exit 1 with a naming error, same typo discipline as `validate-grid`, never a silent fallback. Priors validate against the unfiltered stage graph, so an install whose plugin selection disables a core stage still runs `ars`.

## [2.5.17] - 2026-07-29

Hardens the Kiro CLI and Kiro IDE shell permission lists. Kiro matches each `execute_bash` pattern as a full string, not as a prefix, so the shipped patterns were both too narrow (a bare `date -u` and `bun run .kiro/tools/<tool>.ts` needed an approval the framework never asked for, stalling a workflow when no approver was available) and too broad (a trailing wildcard let `bun .kiro/tools/../../anything.ts` run unprompted). The pre-approved set is now the framework's own project-relative tool calls and nothing else, and the deny list catches the recursive-`rm` and `git push` variants full-string matching used to miss. **Upgrade:** re-copy your `dist/kiro/` or `dist/kiro-ide/` shell into the project so the corrected agent configs are installed. If you start Kiro from a directory other than the project root, start it from the root instead: out-of-root invocation forms are no longer pre-approved.

* Framework commands that previously hit an approval prompt now run as intended from the project root: `bun run .kiro/tools/<tool>.ts`, a quoted project-relative script path, and a bare `date -u` (the old `date -u .*` could not match it).
* Closed the traversal bypass in the old `bun \.kiro/tools/.*` grant. Approved script paths are now one project-relative filename under `.kiro/tools/`. Absolute paths, `KIRO_PROJECT_DIR` expansion, and `cd` chains stay gated because a pattern can only check a path's shape, not its trustworthiness: pre-approving any `/.../.kiro/tools/*.ts` would also pre-approve a script planted in a world-writable directory.
* The 14 delegated persona agents now carry the same allow and deny policy as the conductor on both Kiro harnesses.
* `deniedCommands` now catches recursive `rm` variants regardless of flag grouping or executable path, plus bare, option-prefixed, and path-qualified `git push` commands. The behavioral tests distinguish an approvable command from an unconditional denial.
* Kiro guidance now recommends ACP permission responses for unattended clients and warns that `--trust-all-tools` bypasses the deny list; the doctor cleanup hint uses the supported `aidlc-worktree discard` command instead of a denied recursive `rm`.

## [2.5.12] - 2026-07-24

Closes the payload boundary 2.5.10 left open on Kiro IDE 1.x: the hook adapter now reads the IDE's stdin context channel for the two payload-dependent hooks (`audit-and-sensors`, `log-subagent`). Artifact audit rows and sensor firing were verified live on Kiro IDE 1.0.165 (same session, no restart). Subagent tracking uses the live 1.0.89-1.0.138 evidence in #543 plus adapter regression coverage; no real delegate completion was captured on 1.0.165. **Upgrade:** copy the tree CONTENTS - `mkdir -p your-project/.kiro && cp -R dist/kiro-ide/.kiro/. your-project/.kiro/` into your project.

* `aidlc-kiro-adapter.ts` (kiro-ide) accepts both context channels and field spellings: a non-empty 0.12 `USER_PROMPT` payload (camelCase) is consumed immediately without probing that generation's never-closing stdin; otherwise the 1.x stdin payload (snake_case `{tool_name, tool_input, tool_response}`, no success flag) is read with a 2s broken-channel ceiling. The public `aidlc adapter kiro-ide` dispatcher follows the same contract. Payload fields are runtime-validated: a present non-null field with the wrong type fails open with a visible hook drop instead of crashing the hook or auditing an untrusted write. Only an explicit boolean `toolSuccess: false` drops a well-formed write from the audit (the #417 guard); the 1.x channel's absent success flag falls through to the path check.
* Payload acquisition is gated to `audit-and-sensors` and `log-subagent`; every other target - including the per-tool-call `block` floor - touches neither channel. `SUBAGENT_COMPLETED` is recorded again on IDE 1.x: that generation sends `subagent_<agent>` rather than the 0.12 `invoke_sub_agent`, so the registration matcher reaches any delegate name, the adapter drops the `subagent_response` shell, and the row's `Agent Type` comes from the platform-provided `subagent_<agent>` tool name - agent-authored result prose can no longer misattribute a completion to another persona, and the `**Reviewer:**` / `**Agent:**` marker remains the identity source on the 0.12 `invoke_sub_agent` shape (#459/#543).
* Both payload-dependent targets record a visible hook drop when neither channel yields a payload, so a broken context channel surfaces in `/aidlc --doctor` instead of exiting as a silent no-op.
* Docs updated (`docs/reference/kiro-ide-hook-payload.md` documents both context channels, the timeout override, and scopes empty inputs to captured PostToolUse events; `docs/guide/harnesses/kiro-ide.md`; `docs/reference/06-hooks-and-tools.md`; `docs/roadmap.md` marks only #555's hook-registration portion resolved). No command or flag changes; no breaking change for CI or scripts.
## [2.5.11] - 2026-07-24

Intent Capture now keeps generated intent and stakeholder claims grounded in the user's description, confirmed answers, workflow-selected scope, or explicitly registered memory. Unsupported content is omitted, elicited, or surfaced as a human-owned assumption instead of being presented as fact. **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the updated stage, Product Lead reviewer contract, and `claim-sources` sensor are installed.

* `intent-capture-questions.md` now records a `## Sources` register and asks explicitly about stakeholders, decision authority, communication needs, and whether the workflow-selected scope matches the intended product boundary.
* `intent-statement.md` and `stakeholder-map.md` now require inline source tags plus `## Assumptions & Open Questions`; unselected answer options cannot become inferred requirements or exclusions.
* Retained assumptions require the exact structured accept option before Product Lead review and the approval gate. Accepted assumptions remain labeled as assumptions downstream.
* The new advisory `claim-sources` sensor checks every existing Intent Capture deliverable on each stage write, rejecting untagged or unresolved claims, source-register values that differ from authoritative state or the stage-loaded `org.md`, `team.md`, and `project.md` memory files, hidden comment/fence sources, misplaced assumptions, non-exact assumption confirmations, and missing source registers while excluding reviewer-added `## Review` content.
* Approval & Handoff now declares `stakeholder-map` as a required consumed artifact, making the dependency visible to graph and upstream-coverage checks.

## [2.5.10] - 2026-07-23

Restores hook firing on Kiro IDE >=1.0.1xx, where the IDE silently stopped executing the legacy `.kiro.hook` format the harness shipped (field-proven on 1.0.165: no `HUMAN_TURN` minting, no `SESSION_STARTED`, no artifact audit rows, no sensor firing). Eight of the nine Kiro IDE hooks now ship in both the legacy format (for pre-1.0 IDE builds) and the IDE's v2 hook schema (for 1.x+); `session-end` stays legacy-only (see below). Coexistence is safe: on pre-1.0 IDEs the v2 files are ignored, on 1.x+ only v2 fires (legacy files appear struck-through and never execute), no double-firing observed on any generation tested. **Upgrade:** copy the tree CONTENTS - `mkdir -p your-project/.kiro && cp -R dist/kiro-ide/.kiro/. your-project/.kiro/` - a plain `cp -r dist/kiro-ide/.kiro your-project/.kiro` nests a second `.kiro` inside your existing `.kiro/` and the IDE never sees the new hooks. Do NOT delete existing `.kiro/hooks/aidlc-*.kiro.hook` files (they serve pre-1.0 IDE builds). Do NOT click the IDE's per-hook "Migrate" button on aidlc hooks (the v2 versions are already shipped; an IDE-generated twin could double-fire).

* Eight Kiro IDE hooks added in v2 schema (`.kiro/hooks/aidlc-*.json`, `{"version":"v1","hooks":[{name,trigger,matcher,action}]}`, PascalCase triggers) alongside the existing legacy files: session-start as `SessionStart` (a real once-per-session event on 1.x; the legacy file keeps its per-prompt behavior on pre-1.0), mint as `UserPromptSubmit`, block as `PreToolUse`, audit-logger as `PostToolUse` matcher `fs_write|str_replace|fs_append`, runtime-compile + sync-statusline as `PostToolUse` matcher `execute_bash`, log-subagent as `PostToolUse` matcher `invoke_sub_agent`, stop as `Stop`. Same adapter targets, same commands; v2 hooks hot-load on current IDEs without a restart.
* `session-end` ships NO v2 registration: the IDE's `Stop` trigger fires at the end of every assistant turn, not at conversation close, so a v2 registration would append a spurious `SESSION_ENDED` between prompts in the same session. It stays legacy-only (pre-1.0 behavior unchanged) until the IDE exposes a genuine session-end event. `SESSION_STARTED` IS emitted on 1.x (via the `SessionStart` trigger); `SESSION_ENDED` is NOT emitted on 1.x.
* The adapter's `log-subagent` target now no-ops with a VISIBLE hook drop when the tool payload is empty (the IDE 1.x case - the payload arrives on stdin, which the adapter does not read): previously it forwarded a real `SUBAGENT_COMPLETED` row with `Agent Type: unknown` and recorded no drop, so `--doctor` could not surface the degradation. A non-empty payload without an identity marker keeps the documented `unknown` fallback.
* The Kiro install commands in the README and harness guides now use content-copy semantics (`mkdir -p` + `cp -R <src>/. <dst>/`) for both `.kiro` and the `aidlc/` workspace shell, on both Kiro trees (CLI and IDE) - the previous `cp -r <src> <dst>` form silently nested the tree inside an existing target directory.
* Known boundary (payload-dependent targets): on IDE 1.x `audit-and-sensors` and `log-subagent` fire but no-op, because 1.x delivers the tool payload on stdin and the adapter reads only the 0.12 `USER_PROMPT` env channel (empty on 1.x). The stdin context channel lands as a follow-up.
* Known boundary (Stop trigger): the IDE's `Stop` trigger cannot block and stdout at exit 0 is ignored (platform limitation). The `aidlc-stop` hook fires for observability/audit purposes only; enforcement of the forwarding-loop contract on this harness relies on the conductor's own Stop protocol, not on the hook's `block` verdict.
* The remaining five hooks (mint, block, session-start, runtime-compile, sync-statusline) are payload-independent and fully functional on IDE 1.x: `SessionStart`/`UserPromptSubmit` stdout IS added to context and `PreToolUse` exit 2 DOES block.
* Kiro CLI (`dist/kiro/`) is unchanged: its hooks ride the agent-JSON `hooks` block, not hook files.
* Docs updated (`docs/guide/harnesses/kiro-ide.md`, `docs/guide/harnesses/kiro-cli.md`, `README.md`, `docs/reference/kiro-ide-hook-payload.md`). No command or flag changes; no breaking change for CI or scripts.

## [2.5.9] - 2026-07-23

Codex compaction no longer fails with `error: hook returned invalid PostCompact hook JSON output` on every compaction. Codex's PostCompact event cannot carry context by schema; AI-DLC now relies on Codex's compact-source `SessionStart` event to restore workflow context through the schema-supported `additionalContext` field. The minimum Codex CLI version is now 0.145.0 because earlier releases defer that hook until the next turn after a mid-turn auto-compaction, allowing one continuation without the restored workflow mission. **Upgrade:** upgrade Codex CLI to >= 0.145.0, then re-copy `dist/codex/` into the project; the leftover `post_compact` trust entry in `$CODEX_HOME/config.toml` is harmless and may be deleted.

* Removed the PostCompact hook registration Codex rejected; compact-source `SessionStart` re-injects the active workflow mission without recording a duplicate `SESSION_STARTED` audit event.
* Compact-source `SessionStart` deliveries now bypass the adapter's duplicate-delivery replay cache, so a second compaction in the same session re-renders fresh workflow state instead of replaying the first compaction's context.
* `/aidlc --doctor` now enforces Codex CLI >= 0.145.0 so compact-source `SessionStart` restores the workflow mission before the first post-compaction continuation.

## [2.5.8] - 2026-07-23

Approval gates no longer deadlock when a conductor redundantly routes the human's approval through `aidlc-log.ts answer` before reporting the approval. The logger recognizes an answer whose target stage is already awaiting approval and has no unresolved non-gate question, returns a successful skip without emitting `QUESTION_ANSWERED`, and leaves the real `HUMAN_TURN` available for `report --result approved`; ordinary interview answers remain workflow-global freshness boundaries, so one answer still cannot authorize a fabricated later approval in the same turn. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `aidlc-log.ts answer --stage <slug>` now returns `{"skipped":"QUESTION_ANSWERED",...,"reason":"approval-gate-report-owned"}` when that same stage is at `[?]` and no unresolved `DECISION_RECORDED` follows the current gate-open; it emits no answer event and exits successfully so any existing `answer && report` chain can recover regardless of how the approval was phrased. A non-gate question logged after the gate makes its next answer record exactly, even when the answer begins with a gate word such as "Approve" or "Reject".
* Approval-gate instructions now explicitly reserve `aidlc-log.ts decision` / `answer` for non-gate questions and direct every approval or rejection through `aidlc-orchestrate.ts report`.
* Human-presence regression coverage now pins the successful redundant-answer path, the rejection-path chain, the no-human refusal, and the rule that an ordinary interview answer still consumes the turn before a later gate.
## [2.5.7] - 2026-07-23

Fixes a Kiro IDE regression that silently disabled the agent-stop hooks: the forwarding-loop reminder and `SESSION_ENDED` never ran, because the IDE delivers an empty `USER_PROMPT` on agent stop and the adapter's entry guard then waited on stdin, which Kiro IDE opens but never writes. Hooks on prompt submit and after tool use were unaffected (the IDE populates `USER_PROMPT` for those events). Verified live on Kiro IDE against both the broken and fixed adapter. **Upgrade:** re-copy your `dist/<harness>/` shell into the project (on Kiro IDE the fix is in `.kiro/hooks/aidlc-kiro-adapter.ts` and `.kiro/tools/aidlc.ts`).

* Kiro IDE agent-stop hooks (forwarding loop, session end) work again: the adapter no longer reads stdin on any event (context arrives only via the `USER_PROMPT` environment variable; the stdin value was never consumed).
* The dispatcher route (`aidlc adapter kiro-ide <target>`) had the same hang - it acquired stdin before invoking the adapter - and is fixed the same way: stdin is never read for the kiro-ide harness.

## [2.5.6] - 2026-07-22

Unblocks agent delegation on the Kiro harnesses (#601): every shipped model pin is removed from the Kiro agent surfaces, so the conductor and all 14 personas inherit the session model. Previously every `invoke_sub_agent` spawn failed with `Invalid model ID` whenever the pinned IDs (`claude-opus-4.8` on the conductor JSON, `claude-sonnet-4.5` on the tier-projected persona JSONs and `.md` frontmatter) were not enabled on the user's Kiro install - blocking the subagent stages, every `reviewer:`-bound gate, the 2.5.0 ensemble dispatches, and any manual delegation. Verified fix shape (live on Kiro IDE): with both pin layers stripped, all 14 agents spawn and respond on a session model the pins never named. **Upgrade:** re-copy the entire `.kiro/` tree from `dist/kiro/` or `dist/kiro-ide/` into your project (agents, settings, tools, and knowledge all carry changes).

* The tier projection's kiro flavor no longer pins a model for any tier (`core/tools/aidlc-tiers.ts`): balanced/templated drop `claude-sonnet-4.5`, so the packager omits `"model"` from every projected agent JSON and every `model:` frontmatter line on both Kiro trees. The agent-v1 schema's documented fallback applies: agents run on the session's default model.
* The authored conductor pin (`"model": "claude-opus-4.8"` in `agents/aidlc.json`, both Kiro harnesses) is removed - the conductor inherits the session model too.
* `settings/cli.json` keeps ONLY the authored conditional effort default (`chat.modelDefaults["claude-opus-4.8"] -> xhigh`, applied when the session actually runs that model; inert otherwise and inert for spawns). The tier-derived `claude-sonnet-4.5 -> high` entry no longer ships.
* The kiro projection machinery (`TIER_PROJECTIONS[].kiro`, `KIRO_TIER_EFFORT`, `kiroModelDefaults()`) stays in place, dormant, should a per-install-resolvable pinning mechanism appear.
* Docs updated across the guide, reference, and harness-engineering trees (`docs/reference/05-agent-system.md` tier table + roster observations, `docs/guide/harnesses/kiro-cli.md`, `docs/guide/13-customization.md` per-agent override surfaces - agent JSON on Kiro CLI, `.md` frontmatter on Kiro IDE, `docs/guide/06-agents.md`, `docs/guide/agents/architect-agent.md`, `docs/reference/agents/README.md`, `docs/reference/14-claude-features.md`, `docs/harness-engineering/03-adding-an-agent.md`): every tier model/effort claim is scoped per harness - on Kiro all tiers inherit the session model and effort. Claude Code, Codex, and opencode projections are unchanged. No command or flag changes; no breaking change for CI or scripts.

## [2.5.5] - 2026-07-22

Reviewer-bearing stages now have an engine-enforced, auditable verification boundary on every completion route. Interactive, per-unit, unit-major, and autonomous Construction runs record reviewer dispatch and verdict events, and stale or incomplete reviews refuse completion without adding another human checkpoint. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `aidlc-log.ts review` records `REVIEW_REQUESTED` before dispatch and `REVIEW_COMPLETED` after a `READY` or `NOT-READY` verdict; isolated stage runs are tagged separately from the main workflow.
* `approve`, `advance`, `finalize`, and `complete-workflow` refuse reviewer-bearing stages without a fresh `READY` or `NOT-READY` verdict from the declared reviewer; a rejection, revision, workflow restart, relevant jump, or later declared-artifact write invalidates older receipts.
* Per-unit enforcement requires one review for each applicable unit, invalidates only the unit whose artifact changed, validates cached unit data against authoritative `unit-of-work-dependency.md`, self-heals stale caches, and skips units whose kind has no artifacts in the stage.
* Autonomous Code Generation keeps the #568 owner-collaborator-verifier contract: every converged swarm unit is reviewed in its Bolt worktree before finalization, without an additional human prompt.

## [2.5.2] - 2026-07-21
`/aidlc --doctor` gains an `--export` flag that writes a small, redacted diagnostic report so a misbehaving workflow can be debugged without sharing the whole project directory. One fresh doctor analysis backs both the live `--doctor` render and the export; the workflow diagnosis is advisory (it never changes the exit code - only the existing environment/config checks do, preserving the behaviour CI scripts gate on), and the export merges the legacy environment findings so `report.md`/`report.json` carry the same findings the live report shows. It reconstructs the workflow timeline from the audit trail (stage durations, gates, revisions - scoped to the latest run, events timestamp-sorted, repeated attempts paired chronologically), runs deterministic condition->remedy rules (unresolved gates, state/audit drift, stale/missing runtime graph gated on a workflow existing, cold hooks), and exports only allowlisted, normalized fields - never artifact, contribution, question, or memory bodies. Every project/home path and every custom intent/stage/agent (including `lead_agent`) identifier is hashed or redacted before serialization; secrets are scrubbed in plain, JSON-quoted, JSON-escaped, and punctuation-bearing forms; inputs whose real path escapes the project root are refused (leaf or parent symlink), platform-separator aware for Windows; a malformed runtime graph degrades to a finding instead of crashing doctor; truncation keeps the JSON artifacts valid; per-file and total size are capped. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.
* `/aidlc --doctor --export` runs a fresh doctor pass and writes a report directory (`report.md`, `report.json`, `manifest.json`, and normalized `evidence/`) under `aidlc/diagnostics/` (gitignored on all five harnesses), packaged as a timestamped `aidlc-diagnostic-report-<ts>.tar.gz` when a system `tar` is available and left as a directory (with manual-share instructions) otherwise. Override the output location with `--output <dir>`; a bare `--output` with no path errors instead of creating a directory named `true`. The export surface routes through both terminal-command deciders (`parseNextFlags` and `classifyTerminalCommand`), so it reaches the tool on Claude Code, Kiro CLI/IDE, and Codex, not only a direct invocation.
* Plain `/aidlc --doctor` also surfaces the new structured findings (`gate-unresolved`, `runtime-graph-stale`, and the rest) as an **advisory** section that never changes the exit code.
* Diagnosis is deterministic (no LLM) and recovery bypasses (any `AIDLC_DISABLE_*` env var or a workspace-reset instruction) are always reported as unsafe-to-automate with a prominent warning.
* No new package dependency is introduced; the export never includes workspace source, raw state/audit/runtime-graph files, artifact/contribution/question/memory bodies, environment variables, or command output.

## [2.5.1] - 2026-07-20
The adaptive composer now estimates implementation entropy before composing. It scores five components - intent ambiguity, codebase structural uncertainty, verification entropy, risk, and unresolved assumptions - from the task and the workspace, then composes the minimum viable workflow: the least sufficient EXECUTE/SKIP grid that still produces every artifact the outcome depends on. When CodeKB MCP tools are configured and the relevant spaces are indexed, the composer grounds its structural estimates in CodeKB call-graph and component analysis instead of scanning the workspace; without CodeKB it falls back to the bounded workspace scan. This is a prompt-only release - no new tools, schema fields, or engine changes. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.
* `/aidlc compose` proposals now carry an entropy-score breakdown alongside the EXECUTE/SKIP grid: the gate renders three blocks - the validator's summary line, a five-component score table with bands and an advisory composite, and a per-stage decision table with reasoning for every EXECUTE and SKIP.
* Composed grids fold overlapping ideation/inception stages by default (each fold names its un-SKIP trigger); the human still approves, edits, or rejects every proposal at the gate.
* In-flight recompose proposals re-estimate the entropy components from what completed stages actually resolved, name that evidence per proposed flip, and strict-validate before the gate so a starved flip is caught before approval, not after.
* With CodeKB evidence covering the affected codebase, the composer may propose skipping Reverse Engineering; the proposal must disclose that downstream stages then run without the local RE artifact store, and the human decides at the gate. CodeKB is an optional external MCP server (see the Scopes and Depth guide for per-harness setup); without it the composer scores from the workspace scan, and on Kiro CLI / Kiro IDE the fallback is always used.

## [2.5.0] - 2026-07-17

The three-role ensemble (North Star Goal 1): a stage's `mode` is now its communication topology - who talks to whom while the body runs - and support agents become real, independently dispatched collaborators instead of voices the conductor adopts. Two new modes join `inline` and `subagent`: `pipeline` (chain: the links collectively author the artifacts in declared order, each seeing all upstream work; the final link leaves them complete) and `mob` (mesh as bounded rounds: all support agents contribute in parallel against the lead's draft, mutually blind; unresolved objections are triaged - judgment calls surface to the human mid-stage, knowledge disputes get one confirm-or-maintain round; maintained dissent is quoted verbatim at the approval gate). `mode: subagent` is strengthened to hub-and-spoke: on a stage with `support_agents`, each support agent is dispatched as a mutually-blind spoke against the lead's draft and the lead integrates. The writing model mirrors a real working session - everyone writes their own work: each dispatched collaborator writes a contribution file (`<stage>/contributions/<agent-slug>.md`, identity-marker first line, Contribution + Positions) and the lead alone edits the stage's `produces[]` artifacts. Those files double as deterministic completion evidence: the engine refuses approving a mob (or subagent-with-supports) stage while a declared collaborator's contribution file is missing. The conductor is the bus on every topology (only it delegates), and the reviewer loop is unchanged - a NOT-READY re-invokes the lead alone. `practices-discovery` ships as the hub-and-spoke showcase on greenfield and brownfield work (Pipeline & Deploy lead draft, mutually blind Quality + Developer + DevSecOps spokes, human interview, lead integration); `user-stories` ships as the mob showcase (Product Manager lead, Design + Developer + Quality collaborators, Product Lead reviewer). The shipped topology is 28 inline / 2 subagent / 1 pipeline / 1 mob. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; on Kiro CLI/IDE also re-copy `.kiro/agents/` (nine new delegation-target agent configs plus an updated conductor `trustedAgents` list).

* New stage modes `pipeline` and `mob` (stage frontmatter + run-stage directive). Both require a non-empty `support_agents` - the compile rejects a chain with no links or a one-occupant room. `agent-team` stays reserved.
* Collaborator contribution files: dispatched support agents write `contributions/<agent-slug>.md` under the stage's record dir (first line `**Collaborator:** <agent-slug>` verbatim). `report --result approved` on an ensemble stage errors while one is missing or malformed, naming the gap and the fix; per-unit evidence follows only units the stage actually executes, and a no-DAG single iteration checks the ordinary stage directory. `AIDLC_DISABLE_ENSEMBLE_EVIDENCE=1` is the recovery escape hatch.
* Mob objection triage puts the human in the room: a judgment-call objection (both positions legitimate - scope, risk appetite, priority tradeoffs) surfaces mid-stage as a structured question; only knowledge disputes go to round 2. Under autonomous Construction the mid-stage turn is skipped - dissent is recorded and surfaces at the final-batch gate; it never halts the run.
* `reverse-engineering` re-modes from `subagent` to `pipeline`, recognizing the shape its body always had (developer scans, architect synthesizes and writes - a 2-link chain). No behavior change; the mode now tells the truth.
* `user-stories` flips to `mode: mob` and gains `aidlc-developer-agent` + `aidlc-quality-agent` as collaborators alongside `aidlc-design-agent`. Expect 3-6 additional bounded sub-agent dispatches on scopes that run it; each rides the collaborator's projected tier and the `tier_cap` clamp.
* `practices-discovery` flips to `mode: subagent` for both greenfield and brownfield runs: the Pipeline & Deploy lead drafts first, Quality + Developer + DevSecOps inspect it as mutually blind spokes, the human interview resolves gaps and judgment, and the lead integrates. Resume dispatches only missing spokes, and approval remains open until promotion into `aidlc/spaces/<active-space>/memory/{team,project}.md` succeeds.
* Stage lifecycle outcomes are report-owned: conductors report approval, rejection, revision, completion, or an explicit `skipped` result through `aidlc-orchestrate.ts`; the engine performs the atomic state/audit transition and routes onward. Direct `aidlc-state.ts` lifecycle mutations now fail with an engine-ownership error, so scripts must migrate those calls to `aidlc-orchestrate.ts report` (or the corresponding engine routing command). The PreToolUse redirect fires on Claude Code, Kiro CLI, Codex, and opencode (Kiro IDE relies on the CLI-level error - its hook payloads omit tool arguments). Conditional skips require the current stage slug and a nonblank reason.
* Kiro CLI/IDE delegation roster closed: all 14 personas are now dispatchable (`.kiro/agents/*.json` + conductor `trustedAgents`); the nine new collaborator configs carry read+shell plus an `aidlc/spaces/**`-scoped write grant (for their contribution files). Plugin composition requires the complete dispatch surface for every dispatched agent - agent-v1 JSON plus conductor trust registration on Kiro, an agent config TOML on Codex, a native `.opencode/agents/` subagent on opencode (a plugin's own shipped persona counts there when it projects cleanly); every harness rejects the reserved, runtime-less `agent-team` mode. If the installed parser is unavailable, Kiro/Codex/opencode accept only an explicitly inline, reviewer-free stage. Unsafe stages left by an older no-clobber compose are retained but reported as degraded instead of being silently grandfathered.
* Kiro CLI pre-dispatches unambiguous first-turn `compose`, routing/config flags, and fresh-workspace `--scope` calls with the exact recovered arguments; ambiguous active-workflow freeform still uses the turn-bound pre-tool guard. Kiro CLI/IDE pin the native `todo_list` schema (including `task_list_description`) and `subagent` crew schema, remap file-backed A-E/X choices to numbered chat options, and forward the exact human approval choice to `report`. Probing `aidlc-utility.ts intent-birth --help` is now read-only instead of accidentally birthing the fallback `poc` scope.
* Human checkpoints remain real turn stops: consolidated answer confirmation and per-unit Code Generation plan approval now persist a blank question-file answer before prompting, and the Stop hook resolves the exact active-unit question directory instead of forcing continuation or accepting another unit's stale question.
* `aidlc-graph compile` emits an `[advisory]` on stderr when the per-unit Construction build stage carries a mode other than `subagent` - that shape silently takes the stage off the autonomous swarm path.
* Scope decisions recorded: transports are conductor-simulated on all five harnesses in v1 (native nested dispatch and live-team rooms are documented follow-ups; Kiro CLI refuses nested delegation at runtime, so the hub is its permanent floor); the review loop stays the `reviewer` field, not a mode.
* Isolated runs now carry `single: true`, bypass the approval gate (`gate: false`), and expose no next stage. The conductor reports exactly once with `report --single --result completed`; the engine returns terminal `done` without routing the main workflow, surfacing learnings, or parking. `report --single` enforces the same ensemble evidence shape as the main workflow path, but an isolated per-unit stage has no main-workflow Unit context, so its collaborator files are checked at the ordinary stage-level contribution directory.
* Kiro CLI/IDE grants the Developer collaborator scoped write access to `aidlc/spaces/**`. Kiro composition now rejects plugin stages that would dispatch plugin-owned agents without a native agent-v1 configuration and `trustedAgents` registration, naming the stage, agent, and remediation in the compose drops log.
* The resume menu routes every choice: `report --result resumed` now returns a per-choice directive - resume continues from the checkpoint, redo names the `aidlc-jump.ts execute --direction redo` command, jump asks for the target then routes through `next --stage`, and start fresh routes through `next --new-intent`; an unrecognized answer errors with the accepted choices instead of silently resuming.
* Swarm convergence evidence is scoped to the stage attempt that produced it: each `SWARM_UNIT_CONVERGED` row now carries `Stage` + `Run floor` fields, and batch advance, the ensemble evidence gate, and the artifact guard count a row only when both match the current attempt - a late `finalize` retry against a prior attempt's worktree, or another swarm stage reusing the same unit names, no longer satisfies the current run. Rows written by earlier versions fail closed: an in-flight swarm crossing the upgrade re-fans its already-converged units (finalize's re-verify makes the re-run safe).
* A gate rejection on Practices Discovery invalidates the promotion receipt: `report --result approved` refuses until `practices-promote` re-runs after the rejection, so revised drafts can never ride an earlier affirmation.
* A rejection-driven revision that changes a `produces[]` artifact re-runs the stage's reviewer before the gate reopens (fresh `## Review` verdict; the learnings ritual still runs once per stage), and the learnings question is its own logged turn before the engine opens the gate - `QUESTION_ANSWERED` precedes `STAGE_AWAITING_APPROVAL` in the audit ledger on every harness.
* On opencode, a plugin agent file the native-roster projection cannot emit now drops alone with a per-file log line; previously one malformed persona aborted the plugin's entire compose (knowledge, sensors, tools, and the graph recompile were all skipped). A plugin persona whose name collides with an installed native agent no longer lets its stage compose with a dangling dispatch target.

## [2.4.6] - 2026-07-17

Adds a fifth harness distribution: **opencode** (opencode.ai, verified live on 1.17.18). `dist/opencode/` ships the same deterministic core as every other harness, projected for opencode's native surfaces: skills, subagents, a `/aidlc` command, and a hook-adapter plugin. One layout note: the engine tree ships at `.aidlc/`, not `.opencode/`, because opencode auto-imports `.opencode/tools/*.ts` as custom tool definitions and the engine's CLI scripts would crash the session; the shipped `opencode.json` points opencode's skill discovery at `.aidlc/skills` and carries the method-tree `instructions` glob plus the `bun .aidlc/tools/*` permission allowlist. **Upgrade:** existing installs on other harnesses are unaffected; to run on opencode copy `dist/opencode/` into your project per the README's opencode Quick Start.

* New `dist/opencode/` distribution: `.aidlc/` (engine: tools, hooks, skills incl. generated stage/scope runners, agents, knowledge, scopes, sensors), `.opencode/` (native shell: 14 persona subagents with `mode: subagent`, `command/aidlc.md`, `plugin/aidlc-opencode-adapter.ts`), the `aidlc/` workspace shell, a project-root `opencode.json`, `AGENTS.md`, and `.gitignore`.
* The adapter plugin maps opencode hook moments onto the shared core hook bodies: audit + sensor dispatch on write/edit, runtime-graph compile on bash, statusline sync on todowrite, subagent logging on task, human-presence minting per chat turn, state validation on `experimental.session.compacting`, and forwarding-loop enforcement on `session.idle` (advisory: a `block` verdict re-engages the loop by injecting a sentinel-marked nudge prompt that never mints presence).
* Tier projection gains an `opencode` flavor: judgment agents omit `model`/`variant` (session defaults win); balanced pins `amazon-bedrock/global.anthropic.claude-sonnet-4-6`; templated adds `variant: medium`.
* `/aidlc --doctor` on opencode checks the adapter plugin, either project-root `opencode.json` or `opencode.jsonc`, and `.opencode/command/aidlc.md`; `/aidlc space <name>` re-points every present config's AIDLC `instructions` glob without mistaking a commented block for the live setting.
* `SESSION_ENDED` is not emitted on opencode (no session-end hook moment); the swarm runs as task-tool fan-out only (`AIDLC_USE_SWARM=1` is a loud no-op). Full differences: `docs/guide/harnesses/opencode.md`.
* OpenCode AIDLC bun permissions now have a plugin-enforced command boundary: one direct invocation of an entrypoint embedded from the packaged `.aidlc/tools/` and `.aidlc/hooks/` set is allowed, while unshipped filenames, chaining, redirection, expansion, command substitution, and appended commands are rejected before execution. Edits to those engine directories prompt.
* Reviewer read-scope enforcement now runs from `tool.execute.before` for OpenCode child sessions, including the native `list` tool, with exact agent identity when OpenCode supplies it and child-session scoping as the documented fallback.
* `/aidlc space <name>` supports `opencode.jsonc` and preserves comments and trailing commas in either config filename while repointing the method include and persona memory paths.
* OpenCode transitions under `.aidlc/tools/` now trigger runtime-graph recompilation, and relative `apply_patch` paths are resolved before real audit and sensor fan-out.
* Native OpenCode subagents, including plugin-composed personas, deny the `task` tool through `permission.task`, and their method references point at the shipped active-space memory tree.
* Session-start retries until an active workflow can be stamped, turn-one workflow birth reaches Stop enforcement immediately, uncertain child-session lookups fail closed without poisoning the identity cache, and concurrent idle events during one Stop check produce at most one nudge while continuation idles remain deliverable.

## [2.4.5] - 2026-07-17

AI-DLC now ships a native dispatcher and release binaries, adds explicit workspace, config, and plugin command families, and makes the packaged runtime self-contained without allowing mutations beside an executable. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; binary users should replace the executable and its packaged runtime together.

* New `/aidlc config get <key>` command for `depth` and `test-strategy`.
* New `/aidlc config list` command, with `/aidlc config list --json` emitting `{"depth":...,"test-strategy":...}`.
* Existing `/aidlc config set <key> <value>` now routes to the legacy `config-change` handler for `depth` and `test-strategy`; `config-change` remains accepted.
* New `/aidlc plugin list` command, with `/aidlc plugin list --json` emitting installed plugin names, enabled state, and `selectionActive`.
* New `/aidlc plugin sync` command composes installed plugin roots by running each plugin's `hooks/compose.ts`; with no installed plugin trees it exits 0 with `no installed plugins; nothing to sync`.
* `/aidlc init` now errors with `init now lays down the project data tree and is not yet available in this release. To start work, describe what to build: /aidlc "build the auth service".`
* Plugin SessionStart hooks now probe for `aidlc` on `PATH` first and run `aidlc plugin sync`; a nonzero result falls back to the existing bun plus `hooks/compose.ts` command, and the hook still skips cleanly when neither executable is available.
* Native `aidlc` binaries now statically embed all 15 dispatcher delegate modules, so routed commands reach their handlers instead of failing with a missing module error.
* Native `aidlc` binaries now resolve data, sensors, scopes, agents, stages, skills, hooks, and conductor prose from the active project install or the executable's packaged harness runtime.
* Packaged harness runtimes are read-only fallbacks: mutating `plugin select` and `graph compile` commands now require an installed project harness and refuse to write beside the executable.
* Native `aidlc` binaries detect the project's harness directory (`.claude`, `.kiro`, or `.codex`, by probing for `tools/data/harness.json`) when `AIDLC_HARNESS_DIR` is unset, instead of assuming `.claude`; the env var still overrides, and `.claude` remains the fallback outside any install.
* Native orchestration, plugin selection, Bolt, Swarm, and sensor workers re-enter the compiled dispatcher for sibling-tool work, so these paths do not require a separate `bun` executable on `PATH`.
* Native plugin sync imports each plugin composer and routes graph, generated-table, and runner refreshes through the compiled dispatcher; hook, statusline, and harness-adapter routes resolve installed or packaged runtime assets and honor global `--project-dir` even when the current directory or hook payload names another project.
* Relative `--project-dir` values are normalized before Bolt/Swarm self-reentry, and non-bundled sensor workers resolve by registered sensor ID instead of accepting an arbitrary TypeScript path.
* `aidlc doctor` now reports a missing or unreadable stage graph as a failing advisory row instead of crashing before the health report is printed.
* Workspace terminal directives preserve multi-word names and labels as one shell argument, so quoted `space create`, `space switch`, and `intent birth --label` values reach the utility unchanged.
* Native binary builds now gate sensors, graph compilation, packaged-runtime immutability, output validation, generated runners/tables, plugin selection/composition, conductor persona delivery, workspace aliases/flags, relative-path Bolt/Swarm self-reentry, orchestration, hooks, statusline, Codex adapters, and explicit project routing.
* Every target now ships under `build/binaries/<target>/` with complete Claude, Codex, Kiro, and Kiro IDE distributions under `runtime/<harness>/`; `doctor` must report a non-zero complete schema count without missing-module, Bun virtual-filesystem, or missing-file crash signatures.
* Migration note for stale `init` callers: describe what to build instead, for example `/aidlc "build the auth service"`.
* `/aidlc space create teamB` now creates space `teamB`; previously it attempted to switch to a space named `create`. The legacy `/aidlc space-create teamB` spelling still works.
* `/aidlc space list` now lists spaces, and `/aidlc space list --json` or `/aidlc space --json` emits the existing structured space listing.
* `/aidlc space switch teamB` now explicitly switches to `teamB` through both the engine and dispatcher without reinterpreting a verb-shaped name; bare `/aidlc space teamB` still switches as before. `/aidlc space create` and `/aidlc space switch` now return usage errors instead of treating the verb as a name.
* `/aidlc intent list` now lists intents, and `/aidlc intent list --json` or `/aidlc intent --json` emits the existing structured intent listing.
* `/aidlc intent switch list` now preserves the explicit `switch` token through both the engine and dispatcher, so existing intents named `list` or `birth` are selected instead of listing or creating records; bare `/aidlc intent <name>` still switches as before. `/aidlc intent switch` now returns a usage error instead of switching to `switch`.
* `/aidlc intent birth --scope poc --label x` now forwards the remaining flags to `intent-birth`; previously the terminal workspace branch collapsed the command to `intent birth` and lost the flags.
* `/aidlc intent archive foo`, `/aidlc intent rename foo`, `/aidlc intent show foo`, and the matching `space` forms now return "reserved for a future workspace verb and is not implemented yet" with guidance to use explicit `switch` to reach an existing record with that name.
* New intent labels and space names may not be `help`, current workspace verbs, or reserved future verbs; creation fails with a reserved-name message asking for a descriptive label or team name. Existing records with those names remain reachable via explicit `intent switch <name>` or `space switch <name>`, and doctor reports them as an advisory.
* Kiro CLI `/aidlc` verb interception now keeps double-quoted names as one argv token, so `/aidlc space create "My Space"` reaches the utility as one name.
* The runtime compile recursion guard now rejects `aidlc runtime` only at the start of an unquoted shell command segment; prose such as `--user-input "notes; aidlc runtime compile"` no longer suppresses recompilation after a real state transition.

## [2.4.4] - 2026-07-17

The user guide, harness guides, generated onboarding, and `/aidlc --help` now agree with the implemented command, harness, agent, and audit surfaces. Kiro IDE instructions also distinguish its skill-based conductor from Kiro CLI's agent-v1 defaults. **Upgrade:** re-copy your `dist/<harness>/` shell to refresh the corrected onboarding and help text.

* `/aidlc --help` now lists only commands routed by `/aidlc`; the direct-only `aidlc-utility.ts codekb-path` and `select-plugins` helpers are documented separately.
* Kiro CLI is covered throughout the harness roster, and Kiro IDE setup no longer claims that CLI-only `settings/cli.json` selects an IDE default agent.
* Kiro IDE's conductor and primitive map now distinguish its prose-only reviewer scope and IDE-native tool surfaces from the unregistered reviewer-scope hook and Kiro CLI-only settings and headless mode; its standing rules use the shared Kiro resource glob, which follows active-space switches.
* Codex onboarding and the primitive map now point agent roles at `.codex/agents/`, while `.agents/` remains the skill-discovery tree.
* Agent documentation distinguishes the 14-agent roster (11 domain agents, two reviewers, and the composer), and the audit taxonomy is synchronized with its 72-event registry.
* Agent tool tables describe expected Bash and WebSearch use rather than access grants; every persona continues to inherit the full session toolset.
* Documentation parity tests now derive command, harness, agent, and event-count claims from authored implementation surfaces to prevent recurrence.

## [2.4.3] - 2026-07-17

Codex hook-trust entries are now generated with a standards-compliant TOML serializer, including paths with spaces, quotes, and backslashes on Unix and Windows. **Upgrade:** re-copy `dist/codex/`, run `bun install --frozen-lockfile` in the AI-DLC source checkout, regenerate the entries, and replace the existing entries for that `hooks.json` path in `$CODEX_HOME/config.toml`; appending a second copy creates invalid TOML.

* `bun scripts/package.ts codex trust --project <abs-dir> [--hooks-json <abs-path>]` preserves both native Unix and Windows paths while emitting parseable TOML.
* Forward-slash UNC project paths such as `//server/share/project` derive a native Windows UNC default for `.codex\hooks.json` instead of collapsing the server prefix.
* The trust command now rejects relative paths, rootless Windows paths, incomplete UNC paths, missing values, duplicate flags, and unknown arguments instead of printing unusable trust keys.

## [2.4.2] - 2026-07-16

The multi-harness packager now treats each `dist/<harness>/` directory as one generated root, closing drift gaps for project-root onboarding, configuration, and removed outputs. **Upgrade:** re-copy your `dist/<harness>/` shell into the project after regenerating it with this version.

* Graph compilation and runner generation now receive the manifest's actual `harnessDir`, including custom harness directories.
* An explicitly named harness without a manifest exits nonzero instead of being silently skipped.
* `bun scripts/package.ts --check` now detects modified, removed, and renamed project-root outputs, including Kiro `AGENTS.md`, `.mcp.json`, and `.gitignore`.
* Emitters write into the packager-provided distribution root; check mode builds that root in a temporary directory and applies the same complete-tree drift scan.

## [2.4.1] - 2026-07-16

Revision counting now works for the Reverse Engineering gate. Rejecting the RE approval gate ("Request Changes") previously left `Revision Count` at 0 with no `GATE_REJECTED` row when the orchestrator honored the revision conversationally without running the reject verb: codekb artifact writes were invisible to the audit trail, so the approve-time backstop that backfills unrecorded rejects had nothing to see and excluded codekb stages outright. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Codekb writes (Reverse Engineering's artifacts under `aidlc/spaces/<space>/codekb/`) now emit `ARTIFACT_CREATED`/`ARTIFACT_UPDATED` audit events like record-tree writes, with a `codekb > <repo> > <name>` context breadcrumb.
* The approve-time gate-revision backstop covers codekb stages: revising an RE artifact for a repo recorded by the active intent at an open gate, then approving, backfills the missing `GATE_REJECTED` + `STAGE_REVISING` pair and increments `Revision Count`, as it already did for record-tree stages. Intents with no recorded repo set retain the legacy any-repo fallback.

## [2.4.0] - 2026-07-14

Reviewers are now verifiers: every declared review runs under an explicit **adversarial review contract**. The reviewer's job is to refute the artifact, not confirm it - it assumes defects exist and hunts for them, and READY is the verdict it fails to reach after trying to break the artifact, not the default it starts from. Findings must ground in machine-checkable evidence where it exists: the reviewer runs the validation tools its invocation lists (via shell) and checks the artifact against its acceptance criteria, its stage definition, and the consumed upstream contracts; a finding backed only by opinion is a suggestion, not grounds for NOT-READY. This is a prompt-only release - the contract is written once into stage-protocol §12a (so any future reviewer inherits it) with short domain-voiced restatements in the two reviewer personas; no new tools, schema fields, or agents. Two scope decisions are on record: "validate deterministically" is read as grounding in machine-checkable evidence that already exists (validation tools, tests, acceptance criteria, contracts), not as building new domain validators; and the self-healing budget requirement is read as iterations OR tokens, satisfied by the existing `reviewer_max_iterations` (default 2) with human escalation at exhaustion - no token budget is added. The other two verifier properties were already in place: reviewers project a different model class than producers by default (2.3.1 tiers), and budget exhaustion already escalates to the human with full context. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Stage-protocol §12a step 2 now opens with the adversarial review contract: refute-don't-confirm posture, and evidence-grounding rules for findings. It applies to every stage that declares a `reviewer`, on all harnesses.
* Both reviewer personas restate the contract in their own domain voice - the Product Lead hunts untestable acceptance criteria, uncovered requirements, and orphan stories; the Architecture Reviewer hunts broken references, circular dependencies, and cross-unit claims the passed contracts do not back. Identity-marker and read-scope contracts are unchanged.
* The four harness orchestrator skills' reviewer steps carry a one-line restatement of the adversarial framing, following the read-scope precedent.
* No behavior change to the review loop mechanics: verdict flow, `reviewer_max_iterations`, HITL escalation, dispatch records, and the read-scope hook are all as in 2.3.4.

## [2.3.10] - 2026-07-14

The linter sensor now pins the eslint version it runs (`eslint@10`) instead of resolving whatever `eslint` bunx finds first. A bare `bunx eslint` prefers a project-local node_modules copy, then any `eslint` on PATH, before fetching from the registry - and distro packages ship ancient versions (Ubuntu's apt eslint is 6.4.0, installed as a transitive dependency of `apt install npm`). Pre-flat-config eslint cannot read `eslint.config.js`, so on such a box every linter fire silently degraded to a `Note=tool-unavailable` PASS, masking real lint findings. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `aidlc-sensor-linter.ts` invokes `bunx eslint@10` for the availability probe, the `--print-config` probe, and the lint run itself; PATH-shadowed or node_modules eslint no longer changes the verdict.
* Projects that need a different eslint can still override the sensor's `command:` in the linter sensor manifest.

## [2.3.7] - 2026-07-14

The `upstream-coverage` sensor now matches the citation forms the framework's artifacts actually use, clearing the hundreds of false `SENSOR_FAILED` audit rows a Construction run accumulated. It previously demanded each consumed artifact's bare slug in every single written file; artifacts instead cite upstream by producing-stage directory path in their provenance header, and multi-artifact stages legitimately split citations across sibling deliverables. Real coverage gaps still fail. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* A citation of the producing stage's directory (e.g. `nfr-requirements/` in a basis/trace header) now covers every artifact that stage produces; the producer slug must appear as a whole path segment, so a longer sibling slug never satisfies it.
* Coverage is evaluated over the union of the stage's declared deliverables in the output directory, not the single fired file, so a citation in a sibling artifact counts. Scaffolding (`memory.md`, `*-questions.md`, `*-timestamp.md`) is excluded from both sides: a fire on it is judged against the deliverables, and a slug appearing only there never counts.
* A scaffolding write that fires before any deliverable exists now passes vacuously with `reason: "no deliverables on disk yet"` instead of failing every consume against an empty body.
* False-positive fix: a consume slug no longer matches inside a longer kebab token (`requirements` inside `nfr-requirements` previously counted as a reference).
* Sensor JSON output gains `scanned_files`; the dispatcher threads `--consumes` as `artifact:producer` pairs plus a new `--deliverables` flag. Direct invocations with the old bare-slug `--consumes` and no `--deliverables` keep the previous per-file behavior.

## [2.3.6] - 2026-07-12

The state file's `## Phase Progress` section now advances with the workflow. Previously it was seeded once at intent birth and never touched again, so a few stages in it still showed `Ideation: Pending` above a fully-checked Ideation checkbox block - a visible contradiction for anyone reading `aidlc-state.md` directly (routing was never affected; the engine reads `Lifecycle Phase` and the checkboxes, and `/aidlc --status` recomputes its own phase block). The section now tracks every transition the tools already audit. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; a run already mid-flow keeps its stale rows for boundaries it already passed, and corrects from its next boundary onward.

* Intent birth seeds the section truthfully: `Initialization: Verified` (birth completes every init stage before handing off) and the first post-init phase `Active`; later phases stay `Pending`/`Skipped` by scope as before.
* `advance` and `finalize` at a phase boundary flip the completed phase to `Verified` and the entered phase to `Active`; non-boundary transitions leave the section byte-identical. `complete-workflow` (and a final-stage `finalize`) flips the last phase to `Verified`.
* Stage/phase jumps update the rows too: a forward jump marks the source phase `Verified`, wholly jumped-over phases `Skipped`, and the target phase `Active`; a backward jump returns reset phases to `Pending`.
* `scope-change` and `recompose` re-derive only the not-yet-reached rows (`Pending`/`Skipped`) against the new plan; `Verified`/`Active` rows record history and are never rewritten.
* A state file without the section (older installs) still transitions cleanly - the row update is a silent no-op, never an error.

## [2.3.5] - 2026-07-12

Completes the plugin mechanism with **install-time plugin selection** and the full plugin content surface, proven at scale in a customer pilot. Plugins add, the install selects: a plugin can now ship scopes, agent personas, and knowledge alongside stages, every stage-enumerating surface is generated from the compiled graph, and a new `select-plugins` command lets an install choose which plugins' content its users see (core is the implicit `aidlc` plugin and can itself be deselected; a plugin-only install shows only that plugin's commands and scopes). The ownership frontmatter field is renamed from `bundle:` to `plugin:` (the old key is rejected with an error naming the fix). **Upgrade:** re-copy your `dist/<harness>/` shell and re-run any installed plugin's compose hook; a plugin tree still authoring `bundle:` must rename the key to `plugin:`. Existing installs without a selection are otherwise unaffected (an absent `plugins` key enables everything, and the shipped trees are byte-identical on core surfaces).

* `bundle:` frontmatter renamed to `plugin:`. The old key is rejected everywhere it is read - schema validation errors with "bundle: was renamed; write plugin: for ownership", and the compose hook skips a contribution carrying it with a drop naming the same fix. The word is reserved for a possible future collection-of-plugins concept and is otherwise unused.
* Plugins can ship `scopes/`, `agents/`, and `knowledge/` - projected by the packager and composed additively (no-clobber, collision drop-logged) into the install. Plugin scope files are `<plugin>-<name>.md`, agent files `<plugin>-<role>-agent.md`. A plugin's `memory/` tree stays deferred. Three compose guards protect the install: composing onto an engine whose schema predates the `plugin:` key skips the plugin-owned content with a degraded drop naming the remediation (re-copy the shell, re-run compose) instead of permanently breaking the install's compile; every plugin stage file is validated against the INSTALLED engine's schema before it lands - an invalid one (e.g. a stale tree still authoring `bundle:`, or a frontmatter-only empty body) is skip-and-dropped naming the file and errors instead of bricking every later graph compile of the whole install; and a plugin file whose frontmatter `name:` collides with an installed agent/scope (even under a different filename) is skipped with a drop naming both files instead of bricking the loaders. The statusline degrades to raw agent slugs if the roster ever breaks anyway.
* `plugin:` ownership carries through compile onto stage-graph.json nodes. Invariants: a plugin-owned slug must start with `<plugin>-`; `plugin: aidlc` is rejected; plugin names must not start with `aidlc-` (reserved for core - an `aidlc-<x>` plugin's runner dirs would land on core runner paths and clobber them; enforced at compile, compose, scope loading, and the packager); a stage file's name stem must match its slug; duplicate scope names and agent slugs across files fail loudly naming both files.
* Runner skills are plugin-namespaced: a plugin-owned stage or scope gets a runner named by its own slug (`/test-pro-integration`), core keeps `aidlc-<slug>`. The scope-runner default batch is now data (`runner: true` scope frontmatter), not a code constant. The compose hook regenerates runners and the SKILL.md generated tables after recompile, so composed stages are typeable and visible immediately. Generated runners carry a `generated-by: aidlc-runner-gen` frontmatter marker and pruning requires it - a user-authored skill that quotes the runner commands is left alone and listed on stderr as unmanaged (pre-marker generated runners are still pruned by their exact generated dir name for one release). An empty scope batch only prunes under an active selection; otherwise it warns and preserves runners.
* New `select-plugins <name>[,<name>...]` utility verb: validates names, writes the selection to `tools/data/harness.json`, recompiles, and regenerates every generated surface in one transactional step (snapshot + rollback on failure - no torn installs). Stage numbers are selection-stable. A closure guard fails a selection that leaves an enabled stage consuming a required artifact whose only producers are disabled, naming the plugin to enable. `/aidlc --doctor` reports the selection and hard-fails on selection/graph disagreement (a stage file whose frontmatter cannot be parsed counts as missing under an active selection, with the parse error in the fix message). Composed scopes (authored by the adaptive composer at runtime) survive any selection unconditionally - grid entry, scope file, and runner all round-trip intact through deselect/re-enable. Each successful selection change emits a `PLUGIN_SELECTION_CHANGED` audit event recording the previous and new selection. On installs without a harness `skills/` dir (Codex) the runner regeneration steps are skipped with a note instead of erroring.
* Disabling a plugin removes what it merged, not just its own files: compose records the structural adds it actually applied to core stages in a per-plugin sidecar (`tools/data/plugin-contrib-<key>.json`), and `select-plugins` strips a disabled plugin's merged produces/sensors/consumes/required_sections (via the sidecar) and spliced prose (via the fragment sentinels) from installed stage source, inside the same rollback transaction. Re-enabling restores everything on the next session start (the plugin's compose hook re-merges byte-identically). Compose no longer merges contributions for a plugin the current selection disables (its stage/scope/agent copies still land - those are runtime-filtered).
* `select-plugins` refuses a change that would strand an active workflow: disabling the plugin that owns a running workflow's scope, or one owning a pending EXECUTE stage in its plan, is rejected naming each dependency and the remediation (complete or park the workflow, or keep the plugin enabled). `/aidlc --doctor` gains a matching hard-fail row for a selection that already strands one, plus an advisory listing `requires_stage` ordering edges the selection silently drops (an enabled stage requiring a disabled one - legitimate in plugin-only installs, but now explainable).
* The SKILL.md Stage Graph table is now generator output (`stage-table` verb, BEGIN/END markers, `--check` drift guard), and `state-template.md` documents the state-file contract instead of hand-enumerating stages - both surfaces follow the filtered graph under a selection. The scope-table BEGIN marker now uses a hyphen (matching the stage-table grammar); installed SKILL.md copies refresh on the next compose, and a stale-marker install degrades to an advisory drop, not an error.
* The walking-skeleton ceremony reads a new `skeleton: on|off` scope frontmatter field instead of a hardcoded core-scope name set, so plugin scopes are first-class in the ceremony. `AWS_AIDLC_DEFAULT_SCOPE` naming a disabled scope now falls back to the sole enabled plugin's first scope instead of dying, so a plugin-only install starts from plain `/aidlc` - and the substitution is announced on stderr naming both scopes instead of happening silently.
* Plugin stages must have a non-empty body after the frontmatter fence - a frontmatter-only stage compiles and routes while being behaviorally dead; it fails the plugin content tests, and the compose stage-file precheck skip-and-drops it at install time.
* Breaking for CI/scripts: none.

## [2.3.4] - 2026-07-10

The per-unit reviewer read-scope bound is now enforced deterministically, not just by prose. A new PreToolUse hook (`aidlc-reviewer-scope.ts`, the framework's 12th hook and second flow-altering one) refuses a dispatched reviewer's tool calls that reach into sibling units' `construction/` paths - file reads, writes, and grep/glob/shell patterns that span siblings - while a review is in flight, redirecting the reviewer to the contract paths it was passed. The conductor grants the enforcement window by writing `<record>/.aidlc-reviewer-dispatch.json` before invoking a per-unit reviewer (stage-protocol §12a step 1) and deleting it when the verdict is read (step 3); the record's `exempt` list is where the named-integration-point spot-check carve-out is granted. Hard-block on Claude Code, Kiro CLI, and Codex CLI. Kiro IDE ships no registration: its hook payloads carry no tool inputs (`toolArgs` is always empty), so a pre-tool matcher has nothing to inspect there and the prose bound governs. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; Codex users also re-run the hook-trust pre-seed (`bun scripts/package.ts codex trust --project <abs-dir>`) - the new PreToolUse registration needs one new trust entry.

* New hook `aidlc-reviewer-scope.ts` (PreToolUse): blocks with exit 2 + a self-explaining stderr reason; every refusal emits a `REVIEWER_SCOPE_BLOCKED` audit event (Tool, Target, Stage, Unit) so runs show when the bound bit.
* Reviewer-scope matching is path-aware: recursive searches rooted above `construction/`, pathless `Grep`/`Glob`, case variants on case-insensitive filesystems, quote-split or wildcard `construction` components, and `cd` + relative sibling paths are blocked while current-unit and exact-exempt reads remain allowed.
* Stage-protocol §12a: per-unit reviewer dispatches now write the dispatch record before step 1 and delete it at step 3; the four harness orchestrator skills carry the same instruction in their reviewer bullets.
* Set `AIDLC_DISABLE_REVIEWER_SCOPE_HOOK=1` to disable enforcement (the escape hatch for false positives, e.g. a source tree with its own `construction/` directory); a stale dispatch record (older than 6h, a crashed review) is ignored and cleaned up automatically.
* Registration per harness: Claude Code `settings.json` gains its first `PreToolUse` entry for file/search/shell tools; Kiro CLI wires the adapter's `reviewer-scope` target inside the two reviewer agents' JSON configs; Codex `hooks.json` gains a `PreToolUse` row (hence the new trust entry); Kiro IDE deliberately ships none (unenforceable seam, documented in the porting guide).
* A reviewer-agent tool call touching `construction/` paths with no dispatch record is never blocked; it records an advisory drop surfaced by `/aidlc --doctor` (the conductor skipped the step-1 write).
## [2.3.3] - 2026-07-10

`scope-change` now refuses to run under autonomous Construction, closing the gap its sibling `recompose` closed in 2.2.8: both verbs re-shape the live plan's EXECUTE/SKIP stage inclusion, and an unattended autonomous run has no human at the gate to approve the new shape. Previously the "never re-shape the plan under autonomy" rule was engine-enforced for `recompose` but prose-only for `scope-change`. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `scope-change` (and `/aidlc --scope <name>` on a running workflow) exits non-zero with a clear error when `Construction Autonomy Mode` is `autonomous`, naming the remediation (`aidlc-bolt set-autonomy --mode gated`, or let the swarm finish). Gated and unset modes proceed exactly as before; starting a fresh workflow with `--scope` is unaffected.

## [2.3.2] - 2026-07-10

`/aidlc --doctor` now surfaces recorded hook drops. Hooks fail open by design - an audit-emission failure or a swallowed error must never break your tool call - and each such swallow is recorded to `aidlc/.../.aidlc-hooks-health/<hook>.drops`, written specifically for doctor to surface. Doctor never read those files, so the silent-failure telemetry was invisible. It now reports them as an advisory row. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `/aidlc --doctor` gains a `Hook drops` row: `none recorded` when clean, or an advisory naming each hook with a drop count and the last drop's timestamp plus the remediation (inspect the `.drops` file for the reasons, delete it once investigated). Advisory only - it never flips doctor's exit code, so a long-fixed historical drop cannot pin CI red.
## [2.3.1] - 2026-07-10

Authored agents no longer carry raw model pins: the authored contract on every agent is now a work-shaped `tier:` (`judgment` | `balanced` | `templated`), which the build projects into each harness's native model/effort keys. On Claude Code the nine judgment agents stop pinning Opus; the balanced/templated agents still project to a Sonnet-class model. The nine judgment agents (architect, aws-platform, compliance, composer, design, developer, devsecops, product, quality) become `model: inherit` with no effort pin on Claude Code, so a session running Fable (or any other model, at any effort) keeps it in delegated work - the framework never silently downgrades your session choices. The two balanced reviewers and three templated planners keep a Sonnet-class model; only the templated tier steps effort down (`medium`). To restore the old always-Opus behavior for one agent, edit the projected value in your installed copy (e.g. set `model: opus` in that agent's `.claude/agents/*.md`); to cap every agent when building from source, set `tier_cap:` in `core/memory/org.md`/`project.md` frontmatter or run the packager with `AIDLC_TIER_CAP=<tier>`. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Claude Code: judgment agents ship `model: inherit` and no `effort:` line (session model and effort win); balanced ships `model: sonnet` with no effort pin; templated ships `model: sonnet` + `effort: medium`. A pinned `effort:` overrides the session in both directions, so absence is deliberate.
* Codex CLI: judgment agent TOMLs omit `model` and `model_reasoning_effort` and inherit the shipped `.codex/config.toml` session defaults (verified live on codex-cli 0.142.5); balanced pins `openai.gpt-5.4` with inherited effort; templated pins `openai.gpt-5.4` + `medium`.
* Kiro CLI/IDE: judgment agent JSONs omit `"model"` (the agent-v1 schema falls back to your default model); balanced/templated pin `claude-sonnet-4.5`. Behavior change on Kiro: ALL five delegation-target agent JSONs previously pinned `claude-opus-4.8`, so the three judgment targets (architect, composer, developer) now follow your default model, and the two balanced reviewers (product-lead, architecture-reviewer) step down from opus-4.8/xhigh to sonnet-4.5/high. The authored agent JSONs no longer carry a `"model"` field at all - the build owns it. `settings/cli.json` gains a `claude-sonnet-4.5 -> high` entry in `chat.modelDefaults` beside the existing `claude-opus-4.8 -> xhigh` (effort rides on the model on Kiro; when two tiers share a model the higher tier's effort wins; cli.json is CLI-only - the IDE applies its extension defaults).
* New pack-time cost cap: `tier_cap:` in the space-memory frontmatter (`org.md` -> `team.md` -> `project.md`, last writer wins) collapses higher tiers for every projection; the `AIDLC_TIER_CAP` env var overrides it per invocation. An invalid value fails `bun scripts/package.ts` loudly.
* Authored agent frontmatter no longer carries `model:` - a raw `model:`/`effort:` in `core/agents/*.md` is a projection bypass and the tests now pin its absence. Custom user-authored agents in your own project keep using `model:` as before; only the shipped roster is tier-projected.
## [2.3.0] - 2026-07-07

Adds the **AIDLC plugin mechanism**: an optional, owned set of new stages plus an additive contribution seam onto existing core stages, authored in `plugins/<name>/` and emitted by the packager as a **real host plugin** per harness (`dist/plugins/<name>/{claude,codex,kiro,kiro-ide}/`). A compose hook merges the plugin into an install — copying new stages and set-unioning the contribution seam (`produces` / `consumes` / `sensors` / `required_sections` into the target stage, prose fragments spliced into the stage body) — then recompiling the graph so the orchestrator routes the new stages. Distribution is the hybrid: host-native `/plugin` install where a store exists (Claude, Codex), folder-drop + explicit compose for Kiro; trust is host-native (no AIDLC trust layer). Core stays byte-identical when no plugin is active. Ships the `test-pro` reference plugin, validated across all four harness projections. **Upgrade:** re-copy your `dist/<harness>/` shell; existing installs are unaffected (plugins are opt-in, and the base trees are unchanged).

* Stage schema (`aidlc-stage-schema.ts`) accepts `number`, `name`, `bundle`, `when`, and `required_sections` (optional, shape-validated); `required_sections` also parses as a list in `parseStageFrontmatter`. Core stages omit them and compile byte-identically.
* `bun scripts/package.ts` discovers `plugins/<name>/` and emits a per-harness host-plugin projection (claude, codex, kiro, kiro-ide), each derived from that harness's manifest so a new harness is covered automatically. `bun scripts/package.ts --check` now byte-parity drift-guards `dist/plugins/` too (including a top-level orphan sweep) and never touches `dist/<harness>/`. A new `package.ts plugin build <plugin> <harness> <outDir>` seam builds one projection into an arbitrary dir.
* The compose hook is a single portable `compose.ts` (bun, no GNU-specific shell): no-clobber stage copy, per-entry `consumes` merge (preserves `required` + `conditional_on`), content-hashed idempotent fragment splicing (upgrade-aware, order-deterministic across plugins), self-healing graph recompile, and drop records written to the installed hooks-health dir — surfaced by `/aidlc --doctor`. The hook skips gracefully (exit 0) when bun is absent instead of erroring on every session.
* New tests: `tests/integration/t188-plugin-compose.test.ts` guards the compose mechanism (builds into a temp dir, never the committed trees); each plugin's own `tests/` is now discovered by the integration tier.
* Design consolidated into the single chapter `docs/reference/18-plugin-mechanism.md` (+ authoring guide `docs/harness-engineering/10-authoring-a-plugin.md`), with an explicit Status list of deferred surfaces (plugin `agents/`/`scopes/`/`memory/`/`knowledge/` projection, `adds.scopes`/`adds.requires_stage` merge, `when:` evaluation, marketplace/managed-settings/lockfile, and the Kiro `.kiro.hook` auto-fire + `aidlc plugin compose` CLI).

## [2.2.19] - 2026-07-09

Hooks and the statusline no longer break when the project path contains spaces. Every `$CLAUDE_PROJECT_DIR` reference in the shipped Claude settings is now double-quoted, so the hook commands survive word-splitting shells (bash) as well as zsh. **Upgrade:** re-copy `dist/claude/.claude/settings.json` into your project (or re-copy the whole `dist/claude/` shell).

* Fixed: all 11 hook commands, the statusline command, and the pre-approved bun-tools permission glob in the Claude `settings.json` quote `$CLAUDE_PROJECT_DIR` (`bun "$CLAUDE_PROJECT_DIR/.claude/hooks/<hook>.ts"`); previously a workspace path with a space made every hook fail with `Module not found` under bash-backed hook runners (#519).

## [2.2.18] - 2026-07-09

Unit kinds prune the per-unit construction design matrix. Tag each Unit of Work in units-generation's edge block with an optional `kind:` (service, spec, ui, packaging, or library) and the four construction design stages (functional-design, nfr-requirements, nfr-design, infrastructure-design) now emit and require only the artifacts that apply to that kind: a spec unit owes no scalability doc, a packaging unit no business-logic model. A unit with no kind, a stage with no per-kind map, or an artifact left unannotated all behave exactly as before (the full matrix), so existing workflows are unchanged. A unit whose required set prunes to empty is covered by definition (the stage does not apply to it). **Upgrade:** re-copy your `dist/<harness>/` shell into the project; an older engine run against a kind-tagged edge block fails the units-generation gate loudly (re-copy dist to fix) rather than pruning wrong.

* NEW optional `kind:` key on each unit in units-generation's `unit-of-work-dependency.md` edge block: one of `service | spec | ui | packaging | library`. An invalid value fails the `required-sections` sensor at the units-generation gate (edge block reported malformed), the same fail-loud channel a dangling dependency uses; omit the key to keep a unit on the full design-artifact matrix.
* NEW `produces_kinds:` stage frontmatter field (a map of artifact name to the unit kinds it applies to) on the four construction design stages. An artifact may live in `produces:` or `optional_produces:`; the schema validator rejects a map key that names no entry in either list, an unknown kind, or an empty kind list. An artifact not listed in the map applies to all kinds.
* The engine prunes both the run-stage directive's `produces` paths (required and optional alike) and the per-unit coverage check to the current unit's kind, so the conductor is never pointed at, and the approve-path guard never demands, an artifact the unit does not owe. Kind pruning composes with `optional_produces:`: an optional artifact still resolves into the directive for the kinds it applies to and stays exempt from coverage.
* A per-unit construction stage where every unit's required set prunes to empty now approves as a no-op (the stage does not apply to any unit) instead of deadlocking at the artifact guard.

## [2.2.17] - 2026-07-09

Fixes the Kiro IDE harness's hooks, which previously no-op'd for everything that
needed to know what the agent just did. Kiro IDE delivers hook context through
the `USER_PROMPT` environment variable (not stdin, which it opens but never
writes), and it leaves the tool arguments empty — so the IDE adapter now reads
`USER_PROMPT`, recovers the written file path from the tool result text, and
drives the command/payload-free hooks off the audit trail instead. The audit
logger, sensor firing, runtime-graph recompile, and statusline sync now work in
Kiro IDE without the agent having to compile the graph by hand. Dropping the
stdin read also removes the 2s stdin-race timeout the CLI adapter paid on every
hook; the human-presence mint/block hooks now resolve the project dir from
`process.cwd()`. The Kiro CLI harness is unaffected (it uses a separate adapter
and a working stdin channel). Re-copy your `dist/kiro-ide/.kiro/` to pick up the
fix.

* **Kiro IDE hooks fire correctly** — `aidlc-audit-logger`, `aidlc-sensor-fire`,
  `aidlc-runtime-compile`, and `aidlc-sync-statusline` now do real work on Kiro
  IDE. Artifact writes are audited, sensors run, the runtime graph recompiles on
  transitions, and `Current Stage` stays in sync.
* **File paths are resolved relative to the workspace root.** Kiro IDE reports
  the written path relative to the project root in the tool-result text; the
  adapter resolves it to absolute so `audit-logger`'s record-root check passes.
* **`aidlc-runtime-compile` and `aidlc-sync-statusline` are payload-free on the
  IDE** — both gate on the audit tail (latest transition / latest
  `STAGE_STARTED`) instead of the tool command or task payload the IDE does not
  surface. `aidlc-sync-statusline` is wired to the `shell` tool event.
* **The IDE audit-tail gating is forward-only and idempotent.**
  `aidlc-sync-statusline` never rewinds `Current Stage`: it skips when the
  workflow is not `Running`, when the pointer is `none`, or when the audit's
  latest stage is already completed/skipped. `latestStartedStageSlug` ignores
  synthetic `--single` stage-runner rows. `aidlc-runtime-compile`'s IDE path
  adds an mtime idempotency guard so a lingering transition (e.g. after
  `WORKFLOW_COMPLETED`) does not recompile on every subsequent shell command.
* **The `str_replace`/`fs_append` path extraction is robust.** The adapter
  tolerates trailing newlines, strips a `str_replace` ` (N occurrences)`
  suffix, and records a visible hook-drop when a write-class tool yields no
  extractable path (no silent no-op).
* **The human-presence mint/block hooks survive the stdin removal.** The
  `promptSubmit` mint (`HUMAN_TURN`) and the `preToolUse` block floor now
  resolve the project dir from `process.cwd()` (the IDE gives no `cwd` payload),
  so the Kiro IDE human-presence gate keeps working; dropping the stdin read
  also removes the 2s stdin-race the block hook paid on every `preToolUse`.
* **`log-subagent` records the delegate's identity.** The adapter no longer
  hardcodes `agent_type: "unknown"`; it extracts the self-identifying first line
  (`**Reviewer:** <name>` / `**Agent:** <name>`) from the subagent result and
  forwards the result text, so `SUBAGENT_COMPLETED` carries the real agent. The
  two reviewer agents (`aidlc-product-lead-agent`,
  `aidlc-architecture-reviewer-agent`) now emit that identity marker as the
  first line of their response (an Output Contract in their persona, reinforced
  in stage-protocol §12a), so the audit trail names which reviewer ran instead
  of recording `unknown`.
* **Failed tool calls are not audited as writes.** `audit-and-sensors`
  explicitly guards `toolSuccess === false`, so a failed op no longer relies on
  its error prose failing to match the path regexes.
* **Opt-in hook debug log.** Enable it to have every hook append its decision
  path to `<record>/.aidlc-hooks-health/hook-debug.log` — either set
  `AIDLC_HOOK_DEBUG=1`, or `touch aidlc/.aidlc-hook-debug` (the filesystem
  marker takes effect on the next hook fire with no IDE restart). Off by
  default (no log, no overhead); see the Kiro IDE harness guide.
* **Behaviour for Kiro CLI, Claude Code, and Codex is unchanged.** The shared
  core hooks are edited and re-shipped to all four dists, but the new branches
  are gated behind the IDE-only `ide-audit-sync` marker (and the opt-in
  `AIDLC_HOOK_DEBUG` env var), so the CLI/Claude/Codex payload paths behave
  exactly as before.

## [2.2.16] - 2026-07-09

The architecture reviewer's read scope is now bounded to the artifacts under review plus the shared inception contracts the stage `consumes:`. On per-unit Construction stages (`functional-design`, `nfr-requirements`, `nfr-design`, `infrastructure-design`, `code-generation`) the reviewer previously had no read-scope constraint and its persona pushed a "cross-reference everything" sweep, so reviewing unit N read sibling units' `construction/<other-unit>/` directories and per-unit cost grew linearly with unit count. Stage-protocol §12a now extends the per-unit reviewer pass-list with `directive.consumes`, the persona and knowledge scope "cross-reference" to what was passed, and the four harness orchestrators (Claude Code, Kiro CLI, Kiro IDE, Codex CLI) append the same bound to their reviewer step. Cross-unit contract verification runs against the shared inception artifacts; sibling-unit files may be spot-checked only when the current unit's design explicitly names an integration point in them. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Per-unit reviewer invocations now receive the resolved paths in `directive.consumes` in addition to the `produces` paths, so cross-unit contract claims can be verified against the shared inception artifacts (`components.md`, `component-methods.md`, `services.md`, `unit-of-work.md`, plus any other upstream artifacts the stage declares) without opening sibling units' design directories.
* The four harness orchestrator skills (`.claude/`, `.kiro/`, `.kiro-ide/`, `.codex/`) carry the same read-scope bound in their `Reviewer step (§12a)` bullet: read what was passed, spot-check only the file the current unit's design explicitly names as an integration point.
* `aidlc-architecture-reviewer-agent` persona gains a `## Review Scope` section and the "Cross-reference everything" line is scoped to the artifacts under review and the passed contracts; the knowledge file's Functional Design checklist names the shared contracts as the verification source instead of "cross-unit contract boundaries respected?" in isolation.

## [2.2.15] - 2026-07-09

Agent frontmatter now uses Claude Code's real `model:` key instead of the inert `modelOverride:` key, preserving the same Opus/Sonnet policy while keeping Codex and Kiro behavior stable. **Upgrade:** re-copy your dist/<harness>/ shell into the project.

* Claude Code now honors the shipped `model: sonnet` pins for architecture-reviewer, product-lead, delivery, pipeline-deploy, and operations; those five delegated agents run on Sonnet instead of the session model.
* Codex TOML emission is byte-identical; it now reads the renamed `model` key before applying the same Opus/Sonnet mapping.
* Kiro CLI and Kiro IDE agent JSON configs are untouched and unaffected; they continue to use their hand-authored `"model"` fields.

## [2.2.14] - 2026-07-09

Fixes a silent-data-loss failure in Construction: when the compiled runtime graph was missing its bolt_dag node (a stale or deleted runtime-graph.json, for example when the runtime-compile hook never fired), every per-unit Construction stage silently degraded to a single iteration, so a multi-unit project shipped only its first unit with no error and the workflow completed as if done. The engine now self-heals on the read side: when the cached bolt_dag is absent it recomputes the unit batch DAG directly from inception/units-generation/unit-of-work-dependency.md (the same pure parse the compiler uses), so per-unit iteration, the approve-side coverage guard, and the autonomous swarm all see the full unit list regardless of whether a hook refreshed the graph. Scopes that never run units-generation are unaffected. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Per-unit Construction stages (functional-design, nfr-requirements, nfr-design, infrastructure-design, code-generation) now iterate every unit even when runtime-graph.json is missing or lacks its bolt_dag node, recomputing batches from unit-of-work-dependency.md on the fly. A recompute writes a one-line stderr note naming the stale graph.
* `report --result approved` on a per-unit stage now enforces the all-units coverage guard against the recomputed unit list too, so a stale graph can no longer let an early approve commit a partially built stage.
* A unit-of-work-dependency.md whose fenced units block is missing, malformed, or cyclic (with no cached bolt_dag to fall back on) now surfaces as an error directive naming the artifact and the parse failure, instead of silently building one unit.
* Workflows with no units-generation dependency artifact on disk keep the existing single-iteration behaviour, byte-identical.

## [2.2.13] - 2026-07-09

Opt-in unit-major iteration for the inline construction design stages. By default the engine still walks those stages stage-major (functional-design for every unit, then nfr-requirements for every unit, and so on). When you record `Construction Iteration: unit-major`, the engine instead authors one unit's four design documents (functional-design, nfr-requirements, nfr-design, infrastructure-design) consecutively before moving to the next unit, giving the approved bolt-plan its first executable effect on design order. The four per-stage approval gates are unchanged in count and machinery, but under unit-major they fire late, in a cascade at the end of the design block, one human approval per stage. code-generation and the autonomous swarm are untouched. This is zero-risk for existing users: with no field set, behaviour is byte-identical. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* NEW `aidlc-state.ts set-construction-iteration <unit-major|stage-major>` subcommand: records the `Construction Iteration` runtime-state field. Strict read - only the exact value `unit-major` activates the new walk; absent, `stage-major`, or any other value is stage-major (today's behaviour).
* delivery-planning now classifies whether the approved plan calls for unit-first design execution and, if so, records `set-construction-iteration unit-major`; a human can set or unset it at any time with the same subcommand.
* Under unit-major, a run-stage directive's `directive.stage` may name a later design stage than the state's Current Stage, and a stage's `STAGE_STARTED` audit event may land after that stage's per-unit artifacts were written; the audit trail stays complete and stage-keyed. Always act on the directive's own stage and unit.

## [2.2.12] - 2026-07-09

The scope confirmation now previews the cost before you commit to it. A cold-start confirm and the compose offer carry exact stage and approval-gate counts read from the compiled grid (never estimates), the birth print and `scope-change` output name the same counts, and the composer proposal leads with a validator-computed `N stages EXECUTE / M SKIP, G approval gates` line. So confirming a scope tells you what you are consenting to (a `feature` runs 32 stages and 29 gates; a `bugfix` runs 7 and 4) instead of only a name. No upgrade action needed beyond re-copying your `dist/<harness>/` shell to pick up the regenerated strings.

* The keyword-hit confirm now reads `Starting a "<scope>" workflow for: "<intent>" - N of T stages, G approval gates. ...`, with a trailing clause naming per-unit fan-out when the scope's Construction stages repeat per Unit of Work. The compose offer's example scope list carries counts too (`bugfix = 7 of 32 stages, poc = 8, feature = all 32`).
* Explicit-scope birth prints (`next bugfix`, `next --scope <name>`, new-intent births) name the stage/gate counts in the run-then-continue message.
* `scope-change` stdout gains an `Approval gates: <n>` line alongside the existing `Stages in scope:` line, and the `SCOPE_CHANGED` audit event gains an `Approval Gates` field.
* `validate-grid` JSON output gains a `summary` field (stage/gate/per-unit counts of the validated grid). This is additive - existing parsers that read only `valid`/`errors`/`advisories` are unaffected.

## [2.2.11] - 2026-07-08

Gate-revision backstop: the conductor sometimes revises a stage's artifact at an open approval gate but forgets to run the `reject` verb that records it, leaving `Revision Count: 0` and no `GATE_REJECTED`/`STAGE_REVISING` audit pair for a revision the user actually saw happen. The `approve` command now detects this deterministically and backfills the missing pair (tagged `Recovered: true`) before it commits, so the on-disk state and audit trail reflect the revision. It reconciles the record rather than refusing the approval you already gave, and it will not fire on the reviewer's pre-approval `## Review` append. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `Revision Count` now reflects a revision made at an open gate even when the conductor skipped the `reject` verb: `approve` backfills the count and the audit pair. Run `reject` yourself when you request changes so your feedback text is still recorded.
* NEW `Recovered: true` variants of the `GATE_REJECTED` and `STAGE_REVISING` audit rows, emitted by the approve-time backstop when it backfills a skipped rejection.
* NEW `AIDLC_SKIP_REVISION_BACKSTOP=1` off-switch disables the backstop (mirrors `AIDLC_SKIP_ARTIFACT_GUARD`); the test suite sets it globally so existing approve flows are unaffected.

## [2.2.10] - 2026-07-06

Workspace detection now recognizes git submodules. A workspace whose code lives in uninitialized submodules (empty dirs plus a `.gitmodules` file) previously scanned as Greenfield, so reverse-engineering was auto-skipped and every design stage ran with zero code understanding. The scanner gains a sixth brownfield signal: a parseable `.gitmodules` with at least one submodule path entry classifies the workspace Brownfield. When submodule paths are uninitialized, the scan warns and names the remedy (`git submodule update --init --recursive`) at birth, in the doctor report, and on `detect`. Languages stay as scanned (Unknown is truthful until the submodules are fetched). **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Workspace detection classifies a workspace with a parseable `.gitmodules` (at least one submodule path entry) as Brownfield, so reverse-engineering is no longer skipped for submodule-based projects.
* The `WORKSPACE_SCANNED` audit event gains a `Submodules` field (`N declared, M uninitialized`) when submodules are present, and its `Details` names the `git submodule update --init --recursive` remedy when any submodule path is uninitialized. Projects without a `.gitmodules` produce a byte-identical event.
* Birth stdout prints a one-line warning when submodule paths are uninitialized, telling you to fetch them before proceeding so reverse-engineering can read the code.
* `/aidlc --doctor` gains an advisory `Submodules:` row: no `.gitmodules`, all initialized, uninitialized (names the count, the paths, and the remedy), or present-but-unparseable. Advisory only - it never flips doctor's exit code.
* The read-only `detect` utility gains a `submodules` key in its `--json` payload and a `Submodules:` line in its human output when submodules are present.
## [2.2.9] - 2026-07-06

Per-unit Construction stages no longer demand CONDITIONAL artifacts before a unit counts as covered. A new optional stage-frontmatter key `optional_produces:` names artifacts a stage writes only when the unit needs them - `functional-design`'s `frontend-components` (only when the unit has a UI) and `infrastructure-design`'s `shared-infrastructure` (only when units share infrastructure). Those names moved out of `produces:` into `optional_produces:`, so a backend-only unit completes without an N/A stub file and the stage gate is reachable. The conductor still gets the artifact's write path in the run-stage directive when the unit does produce it, and the artifact name stays in the vocabulary registry. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Per-unit `next` now advances past a unit that skipped a CONDITIONAL artifact (e.g. a backend-only unit with no `frontend-components.md`); previously the unit was re-emitted on every `next` and the stage gate never opened.
* `approve` for `functional-design` / `infrastructure-design` is no longer blocked when a unit legitimately omitted its conditional artifact - coverage keys off the required `produces:` only. A missing REQUIRED artifact still blocks, unchanged.
* NEW stage-frontmatter key `optional_produces:` (a plain kebab string list, parallel to `produces:`): artifacts a stage may write per unit but that are exempt from the per-unit coverage check. Documented in the stage-definition field reference; every entry must pair with a `(CONDITIONAL - ...)` marker in the stage body.
* No new commands or flags; no breaking change for CI or scripts.
## [2.2.8] - 2026-07-05

Hardens two 2.2.0 Adaptive Workflows follow-ups so the "never under autonomous Construction" rules have deterministic anchors instead of prose alone. The in-flight compose carve-out is now bounded: a crashed or abandoned session can no longer leave a marker that permanently disables the Stop hook's forwarding-loop enforcement, and `/aidlc --doctor` surfaces an orphaned marker if one exists. Recompose refuses to run under an autonomous swarm/Bolt run rather than flipping stages with no human at the gate. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* A crashed compose gate no longer permanently disables the Stop hook. The forwarding-loop carve-out for an in-flight compose proposal now honours the `aidlc/.aidlc-compose-pending` marker only while it is fresh (younger than 24h by mtime); an older orphaned marker is ignored and best-effort cleaned up, so enforcement is restored automatically instead of staying silently off until the file is hand-deleted. The hook stays fail-open on any read error.
* `/aidlc --doctor` now reports a present `aidlc/.aidlc-compose-pending` marker with its age. A fresh marker (younger than 24h, the normal state while a compose gate is open) is an advisory pass row and does not affect the exit code; a stale one (an orphan) is a failing row with a remediation hint (delete it if no compose gate is pending, or resolve the gate) and makes doctor exit non-zero. Silent when the marker is absent; read-only.
* `recompose` refuses under autonomous Construction. `bun .../aidlc-utility.ts recompose` (and the chat-first in-flight reshape it backs) now exits non-zero with a clear error when `Construction Autonomy Mode` is `autonomous`, naming the remediation (`aidlc-bolt set-autonomy --mode gated`, or let the swarm finish). Gated and unset modes proceed as before.
## [2.2.7] - 2026-07-05

Workspace detection now finds projects nested in a container folder. A project whose source lives one folder down (e.g. `wordbook/`, `backend/`) was classified Greenfield because the scanner only looked at the workspace root plus a fixed source-dir list, so Reverse Engineering was skipped and no codebase understanding was produced. When no top-level signal fires, the scanner now falls back to a one-level-deep scan of each subdirectory (skipping the excluded, sample, and hidden dirs), so a nested codebase is detected as Brownfield. Starting an incremental workflow (`bugfix`, `refactor`, `security-patch`) on a workspace that still scans Greenfield now prints a one-line advisory pointing at fixing the Project Type or the layout; routing is unchanged, since an empty workspace has nothing to reverse-engineer. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Workspace detection classifies a nested project (source in an arbitrarily-named subdirectory) as Brownfield instead of Greenfield, so Reverse Engineering runs. The fallback is depth-1 only and does not change classification for a normal top-level project. The detected subdirectory is surfaced as `Nested Root` in the `WORKSPACE_SCANNED` audit event and as `nestedRoot` in `/aidlc detect --json`.
* Starting a `bugfix`, `refactor`, or `security-patch` workflow on a Greenfield-scanned workspace prints a stderr advisory (the scope targets existing code but none was found); it does not change routing or Project Type.
## [2.2.6] - 2026-07-05

Approval options during Construction now name the real next stage instead of always saying Code Generation. The run-stage directive carries a computed `next_stage` field (the display name of the following in-scope stage, honouring the active scope and any recomposed EXECUTE/SKIP plan), and the harness question-rendering annexes render the Approve option's "Continue to ..." text from that field verbatim, showing "Complete workflow" on the final in-scope stage. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* The Approve option at each approval gate now reads "Continue to <the actual next stage>" (e.g. "Continue to NFR Requirements"), not a fixed "Continue to Code Generation". No command or flag changes.

## [2.2.5] - 2026-07-05

An autonomous Construction run now advances through every Bolt batch of a multi-batch swarm instead of stalling on the first. Previously, once the first parallel batch merged, the engine re-emitted that same batch forever and the run could not reach the later batches or the stage's approval gate; any project whose Units of Work have dependency edges (more than one topological batch) hit this. The engine now climbs the compiled Bolt DAG batch by batch, re-fanning only the units a partially-converged batch still owes, and presents the single stage gate once every batch has converged. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Autonomous Construction (`Construction Autonomy Mode: autonomous`) with a multi-batch Bolt DAG now progresses: `next` emits the next unconverged batch as `invoke-swarm`, then presents the stage's approval gate after the final batch converges, rather than re-emitting the first batch indefinitely.
* The converged-unit read is scoped to the stage's current run: rows recorded before the stage's latest start (a backward/redo jump re-running Construction with the same unit names) no longer count as coverage, so a re-run rebuilds its batches instead of silently settling on the prior run's ledger.
* `aidlc-swarm.ts finalize` no longer records `SWARM_UNIT_CONVERGED` for a converged unit whose merge-back failed (named in the envelope's `merge_failures`, exit 2). Resolve the blocker and re-run `finalize` scoped to that unit - the worktree is preserved; do not re-run `prepare` for it.
* Single-batch autonomous swarms and gated (non-autonomous) Construction are unchanged.

## [2.2.4] - 2026-07-05

The two review-only agents now record a real UTC timestamp and their own name on the `## Review` section they append. The Review template's `Date` field was a bare `[ISO timestamp]` placeholder with no sourcing instruction, so reviewers filled it in from memory; it now instructs the reviewer to run `date -u +"%Y-%m-%dT%H:%M:%SZ"` in the shell and paste the actual output, matching the `[ISO timestamp from Bash]` convention already used elsewhere. The template's `Reviewer` field also named the PRODUCER agent (the artifact's author) instead of the reviewer persona, so every review on disk was attributed to the agent whose work was being reviewed; it now names the reviewer persona. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Reviewer `## Review` sections (product-lead and architecture-reviewer agents) now carry a real shell-sourced UTC timestamp in the `Date` field rather than an inferred date.
* The `Reviewer` field in those sections now records the reviewer persona (`aidlc-product-lead-agent` / `aidlc-architecture-reviewer-agent`) instead of the producer agent whose artifact was under review.

## [2.2.3] - 2026-07-05

Fixes a fragile process respawn in the Kiro CLI, Kiro IDE, and Codex hook adapters. Each adapter dispatches the framework's core lifecycle hooks (and, on Kiro, the off-band utility commands) by spawning a child process named `bun` by bare name. That child inherits the hook environment's `$PATH`, which on GUI-launched apps and minimal server environments often omits the bun install dir (`~/.bun/bin`), so the spawn fails with `Executable not found in $PATH: bun` and the whole hook layer dies. The adapters now respawn via the absolute path of the bun binary already running them (`process.execPath`), so the hooks themselves run again without `bun` on `PATH`: audit logging, session lifecycle, state validation, and subagent tracking are fully restored. Known limitation: four core hooks spawn a further `bun` child of their own (the stop guard's engine consult, the statusline state sync, the runtime-graph compile, and the sensor dispatch), and those children still resolve `bun` off `PATH`, so on a `bun`-less `PATH` they stay degraded (the stop guard fails open, the statusline does not update, the runtime graph is not recompiled, sensors do not fire); a follow-up threads the running binary down to those spawns. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* Kiro CLI, Kiro IDE, and Codex hook adapters no longer fail with `Executable not found in $PATH: "bun"` when the hook environment lacks the bun install dir; they reuse the exact bun binary running the adapter instead of resolving `bun` off `PATH`.
* Known limitation when `bun` is not on the hook environment's `PATH`: the stop guard, statusline sync, runtime-graph compile, and sensor dispatch respawn `bun` by bare name one level deeper and remain degraded there; the other lifecycle hooks are fully restored.
* No new commands or flags; no breaking change for CI or scripts.

## [2.2.2] - 2026-07-05

Fixes the learnings gate returning zero candidates (or the wrong phase) once a project moved to the per-intent workspace layout. The runtime-graph row's `memory_path` was recorded without the active intent's record dir, and the learnings surface read the phase from the wrong path segment, so `learnings surface` looked for the diary in the wrong place and mislabeled its phase. Both the write side (runtime-graph compile and the state advance transition) and the read side (surface's phase extraction) now use the per-intent record path. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `learnings surface` now finds a stage's captured learnings under the workspace layout instead of surfacing zero candidates: the runtime-graph `memory_path` it reads now includes the active intent's record dir.
* The `phase` field in the `learnings surface` JSON is now correct under the workspace layout (it previously reported `spaces` for any per-intent project); the legacy flat layout still reports the right phase.

## [2.2.1] - 2026-07-04

Stops help requests from accidentally creating intents. `/aidlc intent help` was parsed as "switch to an intent named help"; the failed switch died with an error inviting the agent to "describe what to build to start a new one", which a conductor mid-task read as an instruction and birthed an unwanted intent. Bare `/aidlc help` and `/aidlc -h` were worse: they fell into the freeform-description funnel and offered to birth an intent literally named "help" (or silently advanced the active stage). All help-shaped inputs now route to the help text. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `/aidlc intent help` (or `-h`) and `/aidlc space help` (or `-h`) now print the global help instead of attempting a switch to a record named "help". Applies in the engine, the Kiro verb-intercept seam, and the `aidlc-utility.ts` handlers themselves.
* A sole bare `help` or `-h` after `/aidlc` now prints help. It no longer reaches the scope-confirmation ask on a fresh workspace or advances the active stage on a live one. `help` inside a longer description (e.g. `/aidlc "help desk app"`) is still treated as what to build.
* "help" is now a reserved record name: `intent-birth` refuses a label that slugifies to "help" and `space-create help` errors, since a record with that name could never be switched to by name. Both refusals happen before any mutation.
* The "Unknown intent" error from a failed `/aidlc intent <name>` switch no longer suggests describing new work; it points at the read-only `/aidlc intent` listing and explicitly says not to start a new workflow to recover. The "Unknown space" error likewise no longer instructs creating the missing space - creation stays a separate, deliberate move.
* The orchestrator skill's second-intent CONFIRM step named the wrong binary (`aidlc-utility.ts next ...`, which dies with a usage error listing `intent-birth` - a guard-bypass temptation); it now names `aidlc-orchestrate.ts next` on all four harnesses.
* The Codex orchestrator skill's forwarding loop now tells the conductor to drop the leading `$aidlc`/`/aidlc` invocation marker and forward the remaining text as separate arguments (observed live on Codex exec: the conductor echoed the whole slash line as one quoted token, which hid `intent help` from the router and dead-ended on a scope ask). The engine deliberately does NOT try to repair marker-prefixed input - a mangled echo lands in the scope-confirmation ask, a safe human gate.

## [2.2.0] - 2026-07-04

Adaptive Workflows (roadmap Goal 3): a composer agent under `/aidlc` that fits the ceremony to the task. Describe the work and the engine routes by keyword inference - a clear match gets a one-line confirm naming the matched scope, rich or unmatched prose gets a compose offer instead of the old silent feature default. The composer reads the task and the workspace scan, proposes the EXECUTE/SKIP stage grid with a per-SKIP rationale, and after your approval authors it as a scope and starts the workflow in the same turn. Point it at a scan report (`/aidlc compose --report sonar.json`) to triage findings into a compact fix-and-ship run, or run `/aidlc compose` mid-workflow to re-shape the pending stages in place. Composed scopes ship with `keywords: []` so a one-off plan never rewires future keyword routing; making a scope inferable is an explicit gate choice. (The roadmap's 2.2.0/2.3.0 assignments swap: adaptive workflows ships now as 2.2.0; reviewer-as-verifier moves to 2.3.0 and carries the Full GA declaration - this cut does NOT declare GA.) **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* NEW `/aidlc compose "<task>"` (and the `/aidlc-compose` shortcut skill): force the composer even when a stock scope matches. `--new-scope` forces synthesizing a custom scope; `--report <path>` composes from a scan report. The compose verb is deliberately NOT a workspace verb, so Kiro's off-band verb-intercept never captures it.
* Cold-start freeform routing changed: `/aidlc "<description>"` now runs keyword inference. A clear keyword hit asks a one-line confirm naming the MATCHED scope (e.g. bugfix, not feature); no hit or rich prose asks the compose offer. The old static feature-default confirm is gone.
* NEW read-only `detect` utility subcommand (`--json`): prints the workspace scan (project type, languages, frameworks, build system) plus the resolved scopes dir and scope-grid path - how the composer is told where scope data lives per harness.
* NEW `validate-grid --proposal <path> [--strict] [--project-type <t>] [--keywords <csv>]` on `aidlc-graph.ts`: validates an arbitrary EXECUTE/SKIP grid. Lenient mode mirrors `validate-scope` (off-path required producer = advisory); `--strict` (the recompose mode) hard-rejects a starved required input; `--keywords` hard-rejects any granted keyword an existing scope already claims, naming the incumbent (the composer runs this before writing gate-granted keywords). `validate-scope` behavior is unchanged.
* NEW `recompose --skip <slugs> --add <slugs>` utility subcommand: flips PENDING, ahead-of-cursor stages' plan suffixes on the live state file under the audit lock, strict-validated against NEW starvation, derived state fields rebuilt, `RECOMPOSED` audited. Rejects flips of completed/in-progress/skipped stages, behind-cursor stages, and the first EXECUTE stage of Construction (the walking-skeleton gate anchor). The rebuilt Stages-to-Skip row preserves birth's annotated entries verbatim for stages whose skip-membership did not change, so a skip+add round trip leaves the row byte-identical.
* Chat-first in-flight reshape: mid-workflow, plain chat that names skipping/dropping/adding stages of the running workflow ("can we skip market research?") is recognized by the conductor and routed through the same approve/edit/reject gate and the same `recompose` verb - no literal `compose` needed. When the request names specific stages imperatively, the conductor may present the gate directly without dispatching the composer agent (the verb's validation guards both paths identically); open-ended requests ("what can we cut?") still dispatch the composer. Never under autonomous Construction. On Kiro and Codex the literal `/aidlc compose "<request>"` verb remains the documented reliable path.
* Jump, finalize, lookup, and `--status` now honour the live plan: per-stage EXECUTE/SKIP suffix overrides (a recomposed plan) win over the static scope grid in jump target validation, the forward-skip/backward-reset loops, phase targeting, the Next Stage projections, and status counts.
* NEW `RECOMPOSED` audit event (the taxonomy is now 69 events).
* NEW `aidlc-composer-agent` (14 agents now): dispatched by the conductor for compose requests; on Kiro it ships a hand-authored agent config whose sandbox grants the two scope-registry write paths (the conductor's own sandbox still cannot write them).
* Kiro IDE: delegated subagents now get their tools. The IDE resolves a delegate's tool grants from the agent `.md` frontmatter, not from the agent-v1 JSON the Kiro CLI reads, so dispatched agents (the composer first among them) ran toolless there - "terminal tool not available". The kiro-ide packaging now injects `tools: ["read", "write", "shell"]` into the five delegation-target agent files (reviewers included - the stage protocol has them append a `## Review` section to the artifact); the other harnesses are untouched. Note the IDE grant is unscoped, wider than the CLI JSON sandbox. The composer persona also gains an explicit degraded rule: if it cannot run its deterministic steps it returns a structured failure status, never an unvalidated grid.
* Stop hook: a pending in-flight compose proposal (the conductor's `aidlc/.aidlc-compose-pending` marker) lets the turn end at the approve/edit/reject gate; autonomy-guarded and fail-open.
* The scope-grid "regenerated, never hand-edited" rule gains one carve-out: the dispatched composer appends approved composed scopes to the runtime scope registry. Note a maintainer `aidlc-graph.ts compile` still drops a composed grid entry (composed scopes have no per-stage frontmatter tags); the composer is instructed never to run compile.

## [2.1.8] - 2026-07-03

Brings the 2.0.0 reviewer mechanism up to scratch across harnesses so it actually runs everywhere and can't write outside its lane. Three self-contained defects are fixed: the reviewer step was missing entirely from the Codex orchestrator (a stage's `reviewer:` was silently ignored on Codex), the Kiro reviewer sub-agents were not trusted by the conductor (so invoking them prompted/blocked), and the Kiro reviewer agents were granted unrestricted `fs_write` (broader than the builders they review). No change to per-unit / swarm reviewer behaviour. Re-copy your `dist/<harness>/` to pick up the regenerated trees — the Codex reviewer step, the Kiro trust entries, and the Kiro write cap all ship in the dist.

* **The reviewer now fires on the Codex harness.** The Codex orchestrator's `gate: true` flow gained the §12a reviewer step (it was present on Claude and Kiro but absent on Codex), so a stage's `reviewer:` directive is honoured on Codex instead of silently ignored.
* **On Kiro, the reviewer sub-agent no longer prompts for trust.** `aidlc-architecture-reviewer-agent` and `aidlc-product-lead-agent` are added to the conductor's `subagent.trustedAgents` on both Kiro CLI and Kiro IDE, so the conductor can invoke the reviewer without a trust prompt blocking the workflow.
* **On Kiro, the reviewer can only write under the `aidlc/` workspace.** The reviewer agent configs cap `fs_write` to `aidlc/spaces/**` (where the per-intent artifacts carrying the `## Review` section live), matching the conductor's path-cap pattern instead of granting unrestricted writes.
* No new commands or flags; no breaking change for CI or scripts.

## [2.1.7] - 2026-07-03

Closes the dangling-consume gaps behind the incremental scopes (issue #461). The lean scopes deliberately skip upstream producer stages, but three downstream consumers of the stage `consumes:` contracts did not honor that design: the run-stage directive pointed the executing agent at input files that can never exist (leaving the fallback to per-run improvisation), the upstream-coverage sensor demanded the output prose reference artifacts that were never produced (a guaranteed recurring `SENSOR_FAILED` in six scopes), and nothing distinguished a deliberate scope shortcut from an accidental new dangling edge. Also widens `security-patch` with `requirements-analysis` — the one dangling edge with no in-scope substitute — so a CVE response records an auditable statement of the vulnerability and its remediation criteria. **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `security-patch` now includes `requirements-analysis` (10 of 32 stages, was 9). The `requirements` artifact that `nfr-requirements` and `code-generation` hard-require now has an in-scope producer; the scope stays Minimal depth so the requirements pass scales with the patch.
* The run-stage directive splits declared inputs by on-disk presence: `consumes` lists only inputs that exist; a new optional `consumes_absent` field lists the missing REQUIRED ones, each annotated `expected: true` (producer skipped by the active scope — absence is by design) or `expected: false` (producer on the path but the file is missing). Absent optional (`required: false`) inputs are dropped silently — an optional input that does not exist is not a gap. The conductor is instructed to proceed with the stage's documented fallback on expected-absent inputs and to surface unexpected gaps via the recovery protocol, instead of failing a read and improvising.
* The upstream-coverage sensor now checks only consumed artifacts that exist on disk, eliminating the false `SENSOR_FAILED` audit rows the lean scopes produced on every run of a stage whose upstream producer is skipped.
* Stage bodies that read inputs unconditionally (functional-design, nfr-requirements, nfr-design, infrastructure-design, ci-pipeline, deployment-pipeline, deployment-execution, refined-mockups, code-generation) now read each input "(if exists)" with an explicit fallback (requirements, the reverse-engineered code knowledge base, or the workspace's existing configuration), and the recovery protocol gains the producer-is-SKIP branch (re-running the producer is not an option when the scope excludes it).
* The exact per-scope advisory edge set (the deliberate producer-skipped shortcuts) is pinned in the test suite, so a new dangling required consume fails CI as a scope-authoring error instead of hiding among the accepted advisories.

## [2.1.6] - 2026-07-03

Gates the approval and interview checkpoints on deterministic proof that a real human acted (issue #451). Deep into a long session, an agent under an autonomous IDE mode (observed on the Kiro IDE harness with autopilot) could fabricate the user's own approval ("Approve") or interview answer inside one un-ended turn and advance the workflow, because the gate recorded the conductor-supplied `--user-input` verbatim after only the artifact-existence check (issue #366) with no check that a human actually responded. Now a real human prompt records a `HUMAN_TURN` event in the audit ledger, and the approve/answer gate refuses unless a `HUMAN_TURN` was recorded since the last gate resolution (`GATE_APPROVED` / `GATE_REJECTED` / `QUESTION_ANSWERED`) in ledger order. There is no marker file, no turn counter, and no consumed flag: the ledger itself is the record. On the Kiro CLI and Kiro IDE harnesses a `preToolUse` hook hard-blocks tool calls while a gate is open and no human has acted since, as the enforcement floor. The gate is scoped off under autonomous Construction (swarm / Bolt) so unattended runs do not deadlock, and fail-opens on an empty ledger, so existing flows are unaffected until a `HUMAN_TURN` has been recorded. **Upgrade:** re-copy your `dist/<harness>/` shell into the project; no action is needed for normal interactive use. For synthetic CI that drives `approve`/`answer` against bare fixtures with no human turn, set `AIDLC_SKIP_HUMAN_PRESENCE_GUARD=1` (mirrors the existing `AIDLC_SKIP_ARTIFACT_GUARD`).

* `aidlc-state.ts approve` and `aidlc-log.ts answer` now refuse to commit unless a real human acted at the checkpoint: the gate scans the audit ledger and requires a `HUMAN_TURN` event recorded since the last gate resolution (`GATE_APPROVED` / `GATE_REJECTED` / `QUESTION_ANSWERED`), so a fabricated cascade in one un-ended turn cannot rubber-stamp multiple gates. Refusals exit non-zero and leave state untouched.
* Per-harness mint seam: the prompt-submit hook records a `HUMAN_TURN` audit event on Claude (new `UserPromptSubmit` hook `aidlc-mint-presence.ts`, also fired on every answered `AskUserQuestion` widget so clicking Approve or answering an interview question counts as human presence), Kiro IDE (new `promptSubmit` hook), Codex (`user_prompt_submit`), and Kiro CLI. The mint is a no-op in a project with no active workflow state, so carrying the harness shell without running AI-DLC never creates audit files.
* The Kiro CLI and Kiro IDE harnesses also ship a `preToolUse` hook that hard-blocks tool calls (exit code 2) while a stage actually awaits approval (`[?]`) and no human has acted since the last gate resolution; after a legitimate approval the floor stands down so the same-turn advance into the next stage proceeds normally.
* Autonomous Construction (`Construction Autonomy Mode: autonomous`, i.e. swarm / Bolt) is exempt: the gate does not require a human there, so unattended runs never deadlock. An empty ledger fails open (the gate is enforced only once a `HUMAN_TURN` has been recorded). The presence check orders ledger events chronologically across audit shards, so a second clone's committed shard (a re-clone or another machine) never masks a fresh human turn.
* New bypass `AIDLC_SKIP_HUMAN_PRESENCE_GUARD=1` for synthetic CI runs that drive transitions against bare fixtures with no human turn (mirrors `AIDLC_SKIP_ARTIFACT_GUARD=1`); it disables the approve/answer gate and the Kiro `preToolUse` floors alike.

## [2.1.5] - 2026-07-01

Extends the 1M-context window to tier-pinned subagents, not just the orchestrator. The shipped `.claude/settings.json` already ran the orchestrator at `opus[1m]`, but the `ANTHROPIC_DEFAULT_*_MODEL` Bedrock pins carried bare model IDs, so a subagent selected by tier (the agent roster's `opus`/`sonnet` overrides, or any `sonnet`/`fable` usage that does not go through the `opus[1m]` alias) ran at 200K. The Fable, Opus, and Sonnet pins now carry the `[1m]` suffix so every use of those aliases gets the 1M window; Claude Code strips the suffix before the model ID reaches Bedrock, and the suffix is idempotent with the existing `opus[1m]` orchestrator pin. Haiku is left bare (Haiku 4.5 is a 200K model with no 1M variant). **Upgrade:** re-copy your `dist/claude/.claude/` shell into the project, or append `[1m]` to `ANTHROPIC_DEFAULT_OPUS_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_FABLE_MODEL` in your own `settings.json` / `settings.local.json`. The 1M-context window requires Bedrock model access for those models.

* `dist/claude/.claude/settings.json` — `ANTHROPIC_DEFAULT_FABLE_MODEL` is now `global.anthropic.claude-fable-5[1m]`, `ANTHROPIC_DEFAULT_OPUS_MODEL` is `global.anthropic.claude-opus-4-8[1m]`, and `ANTHROPIC_DEFAULT_SONNET_MODEL` is `global.anthropic.claude-sonnet-4-6[1m]` (were bare model IDs). `ANTHROPIC_DEFAULT_HAIKU_MODEL` is unchanged.

## [2.1.4] - 2026-06-29

Removes the `--test-run` flag and Test Run Mode entirely (issue #369). The flag let an agent auto-approve gates and skip the structured-question and learnings rituals, so an agent in an interactive session could rubber-stamp its own incomplete work by appending `--test-run`. The SDK and TUI test drivers answer gates the normal way (the SDK driver auto-answers each `AskUserQuestion`, the TUI driver drives the real gate), so the harness no longer needs an auto-approve bypass; the mechanism is removed rather than gated behind an env var. **Breaking:** `--test-run` is gone everywhere (the `report`/`approve`/`decision`/`answer` commands, the `/aidlc <scope> --test-run` slash form) and no longer does anything; the `enable-test-run` utility subcommand is removed and errors; the `TEST_RUN_MODE_ENABLED` audit event is removed. Any CI or script that passed `--test-run` or ran `enable-test-run` must drop them and drive gates normally. The artifact guard added in 2.1.3 (issue #366) previously listed `--test-run` as a bypass; with the flag gone its only bypass is now `AIDLC_SKIP_ARTIFACT_GUARD=1`. **Upgrade:** re-copy your `dist/<harness>/` shell into the project, remove `--test-run` / `enable-test-run` from any automation, and use `AIDLC_SKIP_ARTIFACT_GUARD=1` for synthetic CI runs that drive transitions against bare fixtures.

* `--test-run` is removed from `aidlc-orchestrate.ts report`, `aidlc-state.ts approve`, `aidlc-log.ts decision`/`answer`, and `aidlc-runtime.ts compile`; passing it is no longer recognized. Gates, structured questions, and the §13 learnings ritual now always run (no auto-approve / auto-skip path).
* The `aidlc-utility.ts enable-test-run` subcommand and the `Test Run Mode` state-file field are removed. A forward `--stage`/`--phase` jump no longer auto-terminates the workflow; it always lands on the target stage with `Status: Running`.
* The `TEST_RUN_MODE_ENABLED` audit event is removed; together with the 2.1.3 park events the audit taxonomy is now 68 events. The `GATE_APPROVED`, `QUESTION_ANSWERED`, and `DECISION_RECORDED` events no longer carry the optional `Test-Run: true` field, and `MEMORY_EMPTY` rows are never stamped `Test-Run`.
* The 2.1.3 artifact guard (issue #366) is unchanged and still enforced; its `--test-run` bypass is gone, leaving `AIDLC_SKIP_ARTIFACT_GUARD=1` as the sole bypass.
* `--test-strategy <level>` is unaffected and continues to work.

## [2.1.3] - 2026-06-28

Closes the rubber-stamp trap that let an agent on a long (enterprise-scope) workflow mark every remaining stage complete with no real output, and stops the Stop hook from nagging a human who just wants to chat mid-workflow. Four interlocking fixes land together (they all touch `aidlc-state.ts` / the Stop hook, so shipping separately would force hard conflicts): a first-class **park** command gives the conductor a clean multi-session exit, a deterministic **artifact guard** refuses to complete a stage with no evidence of work on disk, an **autonomy guard** keeps an unattended swarm/Bolt run from self-parking, and a **conversational carve-out** lets a chat turn end without being nudged back into the loop. **Upgrade:** re-copy your `dist/<harness>/` shell into the project. CI/scripts breaking change: every `aidlc-state.ts` subcommand that completes a stage (`approve`, `advance`, `finalize`, `complete-workflow`) now refuses to mark it `[x]` when the stage's declared `produces[]` artifacts are absent; pass `--test-run` or set `AIDLC_SKIP_ARTIFACT_GUARD=1` for automated dry runs.

* **Park (#365, #367):** `bun .claude/tools/aidlc-orchestrate.ts park` parks the workflow at the current inter-stage boundary and emits a new `parked` directive; the Stop hook treats `parked` as a terminal allow, so a long workflow can pause and resume in a later session with `/aidlc --resume` instead of rubber-stamping stages to reach `done`. No stage is advanced and nothing is marked complete.
* **Artifact guard (#366):** `approve`, `advance`, `finalize`, and `complete-workflow` now verify on-disk evidence before marking a stage `[x]`: a declared `produces[]` artifact must exist under the intent's record dir, and a `workspace_requires` stage (today only `code-generation`) must additionally show real source work outside the `aidlc/` workspace tree (git-aware when the workspace is a git repo, else a filesystem-existence check). Bypass with `--test-run` or `AIDLC_SKIP_ARTIFACT_GUARD=1`.
* **Autonomy guard (#365):** an autonomous Construction run (`Construction Autonomy Mode: autonomous`) can never self-park: both `aidlc-state.ts park` and the Stop hook's `parked` allow decline under autonomous mode, so an unattended run keeps moving.
* **Conversational carve-out (#365):** the Stop hook no longer nags a human who is just chatting mid-workflow. When the harness delivers a transcript (Claude and Codex pass `transcript_path`), the hook reads it and, if the most recent human prompt was answered with no workflow-engine call (`aidlc-orchestrate` / `aidlc-state`), it allows the turn to end with zero nudges. As a portable backstop on every harness (including Kiro, which delivers no transcript), the no-progress block cap now defaults to **2 in an interactive run** (down from 8 - issue #365's own recommended workaround) so a chatting or pausing human is released after one nudge; an **autonomous** Construction run keeps the long cap of 8 and the carve-out is disabled there (the unattended loop must keep moving). `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` still overrides both.
* New audit events `WORKFLOW_PARKED` / `WORKFLOW_UNPARKED` and state subcommands `park` / `unpark`; the audit taxonomy grows from 67 to 69 events.

## [2.1.2] - 2026-06-28

Fixes issue #368: a multi-unit Construction phase now runs every Unit of Work through each per-unit design stage before that stage completes, instead of producing artifacts for only the first unit. The orchestration engine now drives the per-unit `for_each` loop for the inline per-unit Construction stages (functional-design, nfr-requirements, nfr-design, infrastructure-design) the same way it already did for the code-generation swarm: on each `next` it emits one `run-stage` directive for the next unit whose artifacts are not yet on disk, carries the resolved unit name in a new `directive.unit` field, and suppresses the approval gate on every uncovered unit, so the stage's single approval gate is presented only once every unit is built. The non-autonomous code-generation fallback iterates the same way (the autonomous swarm path is unchanged). **Upgrade:** re-copy your `dist/<harness>/` shell into the project to pick up the engine and skill changes; in-flight workflows continue iterating from wherever their per-unit artifacts left off (the artifacts on disk are the coverage ledger, so no state migration is needed).

* Per-unit Construction stages (functional-design, nfr-requirements, nfr-design, infrastructure-design) now iterate across every Unit of Work; the conductor runs each unit and re-runs `next` to get the following one, and the single stage approval is presented only after every unit is built.
* `run-stage` directives gain an optional `unit` field naming the concrete Unit of Work the engine resolved for a per-unit stage (absent on non-per-unit stages and when no compiled unit list exists).
* Approving a per-unit stage early is now refused: `report --result approved` errors and names the units still outstanding until every unit's artifacts are present.
* A scope with no compiled unit list (refactor, security-patch, infra, bugfix, poc) is unchanged: the stage runs once, exactly as before.

## [2.1.1] - 2026-06-26

Makes custom stages work end-to-end and surfaces stage-graph drift (issue #364). The runtime resolves stages from the compiled `stage-graph.json` only, so a stage `.md` dropped into `aidlc-common/stages/<phase>/` without a recompile was silently never executed, and `aidlc-graph compile` then rejected the new stage until its `{slug, number, name}` row was hand-edited into the JSON first. Compile now auto-seeds a new slug instead of throwing, and `/aidlc --doctor` plus session start now warn when on-disk stages are missing from the compiled graph. No new commands or flags, no breaking changes; compile stays a deliberate manual step (no auto-compile on session start). **Upgrade:** re-copy your `dist/<harness>/` shell into the project.

* `aidlc-graph.ts compile` now auto-seeds a stage `.md` that has no `stage-graph.json` row instead of failing with "Pre-seed new rows": the number is the next free index in the stage's phase and the name defaults to the title-cased slug, both pinned into the regenerated JSON (byte-stable across recompiles, additive only, existing stages are never renumbered). A stage `.md` in a non-canonical phase directory still fails compile loudly.
* `/aidlc --doctor` adds an advisory "Uncompiled stage files" row (does not change the exit code) naming any stage files on disk that are missing from the compiled graph, plus the `aidlc-graph.ts compile` command to include them.
* Session start now emits a non-blocking NOTE when a workflow is active and uncompiled stage files exist on disk (an in-flight workflow keeps its original stage set; recompile and start a fresh workflow to pick up new stages).

## [2.1.0] - 2026-06-24

Moves AI-DLC from a single flat `aidlc-docs/` record to a per-intent **workspace** layout: spaces, multiple coexisting intents, multi-repo, space-level knowledge and code-KB, and a method (memory) that follows the active space. A project root now holds `aidlc/spaces/<space>/intents/<slug>-<id8>/`, so many intents (and non-default spaces) live side by side without colliding; read-only/navigation `/aidlc` commands are reliable mid-workflow. **Upgrade:** re-copy your `dist/<harness>/` shell into the project — it ships the workspace pre-scaffolded, so there is no more `/aidlc --init` (the engine auto-births the first intent on your first `/aidlc`). A project still on the old flat `aidlc-docs/` layout is migrated automatically and crash-safely on first run (copy → atomic rename into the per-intent record; the tracked flat tree is git-rm'd post-move; idempotent on a `.migrated` marker). The audit trail is now **committed as per-clone shards** (`intents/<id>/audit/<host>-<clone>.md`) rather than a single `audit.md`, so concurrent clones never merge-conflict the trail; readers glob and merge by timestamp. A confirmed learning now lands as a **practice** in the relocated `aidlc/spaces/<space>/memory/` (the `*-learnings.md` files are gone), and team **domain knowledge** is **space-level** at `aidlc/spaces/<space>/knowledge/` (a free-form, empty-at-bootstrap sibling of memory/codekb/intents, shared across every intent in the space; a migrating project's flat `aidlc-docs/knowledge/` is relocated there automatically — the engine's per-agent methodology knowledge stays shipped under `<harness>/knowledge/`). This release rebases onto and consolidates the v2 line (reviewer mechanism + Kiro IDE harness, 2.0.0–2.0.2), so it ships the 13-agent roster and both Kiro distributions alongside the workspace refactor. A new user-guide chapter, [Spaces and Intents](docs/guide/03-spaces-and-intents.md), documents the model.

**Workspace layout**

* `/aidlc --init` is **retired** — the shipped shell scaffolds the workspace and the first intent auto-births; `--force`/state-wipe is gone. Re-copy `dist/<harness>/`.
* `--repo`/`--repos` make an intent multi-repo: the repo set is captured at birth and Construction worktrees fork against the right sibling repo.
* The record tree, audit shards, `intents.json`, memory, codekb, and knowledge are committed; the per-user cursors (`active-space`, `active-intent`) and machine-local runtime are gitignored.
* **CI/scripts (breaking):** the flat `aidlc-docs/` path no longer resolves for new projects — resolve state/audit/artifacts under `aidlc/spaces/<space>/intents/<slug>-<id8>/` (the migration keys on `aidlc-docs/aidlc-state.md` as its sole detection trigger).
* Engine-only installs self-heal: if the `aidlc/` workspace shell wasn't copied alongside the engine dir, the first `/aidlc` seeds `aidlc/spaces/default/memory/` from a copy bundled in the engine (idempotent — a normal install that copied `aidlc/` is left untouched).

**Navigation verbs**

* New intent + space verbs: `/aidlc intent` (list/switch), `/aidlc space` (list/switch), `/aidlc space-create <name>`, `/aidlc intent-birth`; a `--json` query layer on the list handlers. They route through the conductor and are recognised only as the LEADING token, so a freeform request that merely contains "space" or "intent" mid-sentence (e.g. `/aidlc add a settings space`) is still treated as new-work input.
* While an intent is active, describing a genuinely new, unrelated piece of work prompts the orchestrator to **offer a second intent alongside** (you confirm Y/n before anything is born); switch between them any time with `/aidlc intent <name>`.

**Active-space following**

* `/aidlc space <name>` re-points the active harness's rule include (Claude `@`-stub, Kiro `agents/*.json` resources glob, Codex `AIDLC_RULES_DIR`) to the switched space — the next turn loads that space's method into ambient context. The includes stay committed and are re-pointed in place; at `default` the re-point is a byte-identical no-op, so a single-team committed tree never churns.
* The method resolver and the learnings/practices writers follow the active space: a learning promoted under `active-space=<name>` lands in `aidlc/spaces/<name>/memory/`; a cursorless resolve still yields `default`.
* `/aidlc space-create <name>` seeds the full space shape — `codekb/` and `knowledge/` siblings (with `.gitkeep` floors) alongside `memory/` and `intents/`, matching `default`.
* The `required-sections` sensor and the stage-protocol template clause resolve templates as team → framework-default → generic floor (override-before-default). No framework-default templates ship at GA, so resolution is unchanged until one is authored.

**Per-repo code knowledge base**

* New read-only `/aidlc codekb-path [--repo <name>] [--json]` verb prints the deterministic per-repo codekb directory without mutating state.
* Reverse-engineering's 9 artifacts now land at the space-level per-repo path `aidlc/spaces/<space>/codekb/<repo>/` — a durable store shared across every intent in the space — rather than at the agent's discretion under the per-intent record dir.

**Kiro read-only/navigation determinism**

* On Kiro, `/aidlc --status` / `--doctor` / `--help` / `--version` and `/aidlc space` / `space-create <name>` / `intent <name>` now run reliably while a workflow is active — they print/switch as documented instead of occasionally advancing the active intent. A `userPromptSubmit` hook runs these deterministic commands directly; re-copy your `dist/kiro/` shell to pick up the new hooks (`agents/aidlc.json` → `hooks.userPromptSubmit`, plus a `hooks.preToolUse` backstop).
* The dispatch is enforced by a turn-scoped guard: the engine emits a terminal stop (and a Kiro `preToolUse` backstop blocks) when a bare `next` would otherwise roll a workflow forward in the same turn a read-only/navigation command was already handled. On every harness the `next --status` / `--doctor` / `--help` / `--version` print directive now names the exact `aidlc-utility.ts` subcommand and instructs the conductor to stop.
* Mutating commands are unaffected: `--scope` / `--test-strategy` changes and intent birth still run and then resume the workflow.

## [2.0.2] - 2026-06-18

Validates the stage `reviewer:` / `reviewer_max_iterations` frontmatter fields, which were carried through schema → graph → directive by the 2.0.0 reviewer mechanism but never checked. A malformed cap, a non-positive-integer cap, a cap declared with no reviewer, or a `reviewer:` naming an agent with no `.claude/agents/*.md` file all passed validation before and surfaced only as a runtime failure or a silently-disabled review loop; they now fail validation/compile loudly and deterministically. This is a behaviour change at authoring time only — the reviewer's runtime behaviour is unchanged. Re-copy your `dist/<harness>/` to pick up the regenerated tools. Refs #389.

* **Authoring impact (action required if you hand-edit stages):** a stage whose `reviewer:` names an unknown agent, or whose `reviewer_max_iterations` is non-numeric / zero / negative / non-integer / present-without-a-reviewer, now FAILS `validateStageFrontmatter` and the graph compile where it previously passed. Fix the value or remove the field.
* **`reviewer_max_iterations` is now parsed as a number.** `parseStageFrontmatter` coerces an integer-literal cap to a real number (and `emitStageFrontmatter` round-trips it as an unquoted number), so the type is correct end-to-end instead of relying on a `Number()` coercion at compile.
* **`reviewer` is roster-checked like `lead_agent`.** A reviewer slug with no matching agent file is rejected (stage-schema Rule 9), closing the silent-failure path.
* **Directive validation** type-checks `reviewer` (string) and `reviewer_max_iterations` (positive integer), and the graph compiler guards the cap so a bad value can never ship NaN to `stage-graph.json`.
* No new commands or flags; the only breaking change is that previously-accepted malformed reviewer config now errors.

## [2.0.1] - 2026-06-18

Greens the default-tier test suite (smoke + unit + integration) after the 2.0.0 reviewer-mechanism merge, with no behaviour change to the reviewer feature itself. Three independent, mechanical defects rode in with the merge: the frontmatter emitter dropped the two `reviewer` fields on a round-trip, the version trio was inconsistent, and three agent-count assertions still expected the pre-merge roster of 11. This release reconciles all three so CI is green on a clean 2.0 baseline. No re-copy of `dist/<harness>/` is required for behaviour — the changes are test-correctness, metadata, and the regenerated dist copies of `aidlc-version.ts`. Refs #387.

* **Frontmatter round-trip now carries the reviewer fields.** `emitStageFrontmatter` lists `reviewer` and `reviewer_max_iterations` in its `FIELD_ORDER` (right after `mode`, matching the order the stage files author them), so a parse → emit → parse cycle no longer drops them for reviewer-bearing stages (t65). The emitter has no runtime callers; this is a test-correctness fix.
* **Agent-count assertions and the designer-export golden reflect the 13-agent roster.** The structure guard and element-count assertions now expect 13 agents, and the export golden fixture was regenerated via the CLI to include the two reviewer personas (t37, t66).
* **Version trio reconciled** — `aidlc-version.ts`, the latest CHANGELOG heading, and the README badge all agree at 2.0.1 (t68).
* No new commands or flags; no breaking change for CI or scripts.

## [2.0.0] - 2026-06-18

Adds **LLM-based quality verification** to the workflow: a stage may declare an optional `reviewer:` in its frontmatter, and after the stage body runs the conductor invokes that reviewer sub-agent as an advisory quality gate before the approval gate (stage-protocol.md §12a). The review loop runs up to `reviewer_max_iterations` times (default 2) and is strictly advisory — the human keeps the final say at the approval gate. Two reviewer personas ship with this release, growing the agent roster from 11 to 13. This release also lands the **Kiro IDE** harness (`dist/kiro-ide/`). It back-fills the reviewer-feature changelog entry that the 0.7.12 graph-compile fix did not record. Re-copy your `dist/<harness>/` to pick up the reviewer-bearing stages and, on Kiro IDE, the new distribution.

* **Optional `reviewer:` stage field** — declare a reviewer in a stage's frontmatter and it runs after the stage body as an advisory quality gate; `reviewer_max_iterations` (default 2) caps the review loop. The reviewer never auto-approves — the human approval gate is unchanged.
* **Two reviewer personas** — `aidlc-product-lead-agent` and `aidlc-architecture-reviewer-agent`, taking the roster from 11 to 13 agents.
* **New `dist/kiro-ide/` distribution** — the Kiro IDE harness, alongside the existing Claude Code, Kiro CLI, and Codex CLI trees.
* No breaking change for CI or scripts; reviewer behaviour is opt-in per stage.

## [0.7.12] - 2026-06-17

Fixes a bug where the **reviewer step never ran**: stages declare a `reviewer:` in their frontmatter, but the graph compiler dropped the field, so the compiled `stage-graph.json` and the `run-stage` directive never carried it. The conductor correctly treats the directive as authoritative (stage-protocol.md §12a — invoke a reviewer only when the directive includes one), so with the field missing it always skipped the review. The compiler now carries `reviewer` and `reviewer_max_iterations` through to the compiled graph (and coerces the iteration cap to a number). Re-copy your `dist/<harness>/` to pick it up; reviewer-bearing stages (requirements-analysis, user-stories, application-design, code-generation, and others) now run their review loop before the approval gate.

* **Reviewer now fires on stages that declare one.** No surface change — the fix is in the graph compile; `reviewer` + `reviewer_max_iterations` (default 2) now appear on the relevant `stage-graph.json` nodes and in the `run-stage` directive.
* No new commands or flags; no breaking change for CI or scripts.

## [0.7.11] - 2026-06-17

Adds a dedicated **Kiro IDE** harness (`dist/kiro-ide/`) so AI-DLC's hooks fire inside the Kiro IDE, where the agent-JSON `hooks` block the Kiro CLI relies on is ignored. The IDE recognises only `.kiro.hook` files, so the new harness ships those (each routing through the shared `aidlc-kiro-adapter.ts`) alongside an `aidlc.json` that drops the dead `hooks` block. Both Kiro distributions are now supported — `dist/kiro/` (CLI, agent-JSON hooks) and `dist/kiro-ide/` (IDE, `.kiro.hook` files). Run AI-DLC on Kiro with **Claude Opus 4.8** (requires a paid Kiro plan): weaker models skip optional stage steps (reviewer pass, learnings ritual) and rush approval gates. Re-copy `dist/kiro-ide/.kiro/` (+ `dist/kiro-ide/AGENTS.md`) or `dist/kiro/.kiro/` (+ `dist/kiro/AGENTS.md`) into your project to install.

* **New `dist/kiro-ide/` distribution** — copy `dist/kiro-ide/.kiro/` → `<project>/.kiro/` and `dist/kiro-ide/AGENTS.md` → `<project>/AGENTS.md`, then open the project in Kiro IDE. `/aidlc` is the default agent; the framework hooks appear in the Agent Hooks panel.
* **Approval-gate hardening:** the stage protocol and Kiro orchestrator skills now carry a HARD STOP rule — at an approval gate the conductor ends its turn and waits for the user, and the gate cannot be inferred or auto-approved unless `--test-run` is active.
* **Adapter robustness:** `aidlc-kiro-adapter.ts` now races the stdin read against a 2s timeout (the IDE may open stdin without writing or closing it) and adds a `session-end` target.
* **New guide:** `docs/guide/harnesses/kiro-ide.md` (install, the Opus 4.8 requirement, how `.kiro.hook` hooks work, what differs on Kiro IDE).
* Removed the stale legacy `kiro/dist/kiro-ide/` tree (an older, unrelated prototype) from the repository.
* No new commands or flags; no breaking change for CI or scripts.

## [0.7.10] - 2026-06-16

Raises the shipped reasoning-effort default to **xhigh** for the AI-DLC orchestrator on both the Claude Code and Kiro CLI harnesses (the model pin — Opus 4.8 — is unchanged). The orchestrator runs a long forwarding loop where deeper reasoning earns its cost, so xhigh is now the out-of-the-box default rather than high. Codex is unaffected (it ships a different model family by design). Re-copy your `dist/<harness>/` to pick it up; override per session if you prefer a lighter tier.

* **Claude Code:** `settings.json` now sets `"effortLevel": "xhigh"` (was `high`), and `settings.local.json.example` carries the same so a copied override starts at parity. Lower it per session via the effort selector, or edit `effortLevel` in your local settings.
* **Kiro CLI:** `.kiro/settings/cli.json` now ships `chat.modelDefaults` defaulting `claude-opus-4.8` to `xhigh` effort. Override per session with `/effort <level>` or `kiro-cli chat --effort <level>` (low|medium|high|xhigh|max); a session flag and your user-level `~/.kiro/settings/cli.json` both take precedence over the workspace default.
* No new commands or flags; no breaking change for CI or scripts.

## [0.7.9] - 2026-06-16

Extends the Stop-hook human-wait carve-out (v0.7.8) to the last common case: a **mid-stage clarifying question**. When the conductor asks you something mid-stage, the stage stays `[-]` in-progress — indistinguishable, by checkbox state alone, from a conductor that quit mid-work — so v0.7.8 deliberately left it to the block cap. The hook now reads the stage's `<slug>-questions.md`: when it carries an unanswered `[Answer]:` tag (a question is genuinely pending) the stop is allowed, so the workflow waits for your answer instead of nudging itself (and, as issue #356 saw, self-answering). The carve-out is strictly gated — it never fires under autonomous Construction (`Construction Autonomy Mode: autonomous`), where the loop must keep running unattended — and is positive-confirmation + fail-open like its siblings. Re-copy your `dist/<harness>/` to pick it up.

* **A mid-stage clarifying question no longer triggers the repeated forwarding-loop nudge** when the conductor recorded it in the stage's questions file with a blank `[Answer]:` tag. The conductor now pauses and waits for your answer.
* **Autonomous Construction is unaffected.** The pending-question carve-out is suppressed when `Construction Autonomy Mode` is `autonomous`, so an unattended swarm/Bolt run keeps moving (a failure still halts-and-asks via its own path). A genuine mid-stage quit with no open question, or an all-answered file, still falls through to the existing block cap.
* **Conductor protocol hardened:** the stage protocol now requires that any pending question (including follow-ups and chat-mode questions) is written into `<slug>-questions.md` with a blank `[Answer]:` tag before the turn ends, so the Stop hook can reliably see it across all answer modes.
* No CLI surface change; no new commands or flags. The recursion bounds and `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` are unchanged; the env-var mitigation remains available.

## [0.7.8] - 2026-06-16

Stops the interactive `/aidlc` Stop hook from spamming the forwarding-loop nudge while you are answering a gate. When the conductor parks at an approval gate or in the Request-Changes loop, it ends its turn waiting for you — but the engine still reports the stage as in-flight, so the forwarding-loop Stop hook used to block the stop and re-inject the "you haven't finished the forwarding loop" nudge repeatedly until its 8-block cap bled out. The hook now reads the current stage's checkbox state and **allows** the stop when the stage is awaiting approval (`[?]`) or being revised (`[R]`) — the two states that exist only because the workflow is waiting on you. This is a positive-confirmation, fail-open carve-out: it only ever releases the stop more readily, never blocks more; a genuine mid-stage quit (or any other state) still falls through to the existing cap-bounded block. One core edit fixes the Claude and Kiro (and Codex) harnesses; re-copy your `dist/<harness>/` to pick it up.

* **Interactive approval gates and the Request-Changes loop no longer emit the repeated forwarding-loop nudge.** Previously up to ~8 "Stop hook" nudges could appear at a single gate while you typed your answer; now the hook allows the stop as soon as it sees the stage is awaiting approval or being revised.
* **Known follow-up — a mid-stage clarifying question still relies on the cap.** A question asked *before* the gate leaves the stage `[-]` in-progress, which is indistinguishable from a lazy mid-stage quit by checkbox state alone, so it is deliberately NOT carved out (a blanket `[-]` carve-out would gut the hook). The safe fix needs an engine-side "question pending" signal and is tracked as a follow-up. Immediate mitigation for either case: set `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=1` (or `=2`) in `.claude/settings.local.json` `env` (or export it) to collapse the spam to a single nudge.
* No CLI surface change; no new commands or flags. The recursion bounds (`stop_hook_active`, the no-progress counter, and `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`) are unchanged.

## [0.7.7] - 2026-06-15

Makes the "one core, many harnesses" promise literally true at runtime: adding a harness is now one `harness/<name>/` dir + one `manifest.ts` row (+ optional `emit.ts`), with **zero edits to shared code**. Previously the runtime carried two hardcoded harness lists — the harness-dir set and the rules-subdir rename map in `core/tools/aidlc-lib.ts`, plus the packager's `HARNESS_NAMES` — so a genuine 4th harness would have mis-resolved its directory (falling back to `.claude`) and its renamed rules dir. The packager now discovers harnesses by scanning `harness/` for manifests, the harness dir is derived open-set from the shipped layout, and the rules-subdir rename ships per-tree in a new generated `tools/data/harness.json` the runtime reads. No behavior change to the Claude, Kiro, or Codex distributions — every existing tree regenerates byte-identical except for the new descriptor file. Maintainers regenerate (`bun scripts/package.ts`) and re-copy `dist/<harness>/`.

* **New generated file `tools/data/harness.json`** ships in every distribution (`{"harnessDir": ".claude", "rulesSubdir": "rules"}` for Claude, `"steering"` for Kiro, `"aidlc-rules"` for Codex). It is the open-set source of truth for the rules-subdir rename; `package.ts --check` drift-guards it like every other generated file. Never hand-edit it — it regenerates from the harness manifest.
* **`bun scripts/package.ts` now builds whatever harnesses exist under `harness/`** (any dir with a `manifest.ts`), instead of a hardcoded `claude`/`kiro`/`codex` list. A new harness is picked up by the default build and `--check` with no packager edit.
* No CLI surface change; no new commands or flags. The `AIDLC_HARNESS_DIR` / `AIDLC_RULES_SUBDIR` test seams are unchanged.

## [0.7.6] - 2026-06-15

Reconciles cross-harness drift in the three orchestrator `SKILL.md` files so the Kiro and Codex conductors carry the same routing guidance Claude already had. A follow-up to the v0.7.5 backward-jump fix: several SKILL.md divergences surfaced where Kiro (and in one case Codex) under-specified an instruction the other harnesses carried. None caused a guaranteed failure — the `report --stage` guidance also lives in the always-loaded stage protocol, and the engine self-corrects loud when it is omitted — but the divergence let a SKILL.md contradict the stage protocol. This brings the conductor contract back into alignment without touching the legitimate per-harness mechanism differences (question rendering, swarm fan-out, harness notes). Re-copy your `dist/<harness>/` to pick it up.

* **`report --stage <directive.stage>` is restored to the Kiro and Codex orchestrator SKILL.md** (report step, gate branches, and test-run line) — matching Claude and the shared stage protocol. Reporting the acted stage explicitly pins the transition the conductor committed, which matters in the recovery case where `Current Stage` was advanced by a direct state-tool repair.
* **Kiro's SKILL.md regains the `## Stage Graph` table** (the 32-stage human-readable mirror Claude and Codex carry) and the fuller "six directive kinds" explanation.
* **A "report once per directive; never call the state tools directly" clause is now in all three SKILL.md files**, and all three point at `docs/reference/12-state-machine.md` as the canonical state-machine reference.
* No CLI surface change; no new commands or flags. Legitimate per-harness mechanism differences (the `ask` widget vs numbered prose, the swarm fan-out mechanism, the harness-notes sections) are deliberately preserved.

## [0.7.5] - 2026-06-15

Makes the Kiro conductor reliably obey backward-jump directives. On Kiro, `/aidlc --phase <earlier-phase>` (and `--stage`) from mid-workflow would intermittently run the *forward* stage instead of the jump: the conductor re-ran the engine with the user's flag dropped, or skipped the jump command the engine's `print` directive named, and the workflow advanced to the wrong stage. Root cause was a delivery gap, not the engine or the model — Kiro's conductor decided its move without the forwarding-loop contract reliably in context (the orchestrator `SKILL.md` is a lazy `skill://` resource on Kiro, where Claude's skill loader injects it deterministically). The fix moves the forwarding discipline into channels guaranteed to be in context. Re-copy your `dist/<harness>/` to pick it up.

* **The session-start hook now injects the forwarding-loop contract** (all harnesses): the engine owns all routing; the user's original arguments go on the FIRST `next` verbatim — never drop `--phase`/`--stage`; and when a `print` directive names a command to run (a jump `execute`, scope/config change, or `init`), that exact command is the immediate next action — do not re-run `next` or read files before it. Harmless and correct on Claude/Codex (which already carry these rules via their skill loaders); load-bearing on Kiro. The hook still only fires when an AIDLC workflow is active.
* **The Kiro conductor agent (`aidlc.json`) prompt is hardened** with the same first-call-verbatim-args and run-the-named-command-first invariants.
* **Cross-harness `SKILL.md` parity:** Kiro's orchestrator `print`-directive row regains the "the mutation lives in the named tool, never in `next`; act on its instruction rather than improvising the routing" clause that Claude and Codex already carried.
* No CLI surface change; no new commands or flags.

## [0.7.4] - 2026-06-14

Absorbs the v0.6.8 engine hardening, the test-harness's Windows wave, and main's v0.6.9/v0.6.10 repo-review batches into the one-core-many-harnesses model, so every harness (Claude / Kiro / Codex) carries them. The v0.6.8 birth-seam and single-stage fixes were authored against the single-harness `.claude/` tree; here they are re-homed into `core/` (and `harness/<name>/` for the orchestrator skill) so `bun scripts/package.ts` regenerates them into all three distributions — a naive copy into the generated `dist/` would have been clobbered on the next build. The v0.6.10 batch adds lost-update safety to state writes, makes `/aidlc --doctor` cover all 10 hooks and run cold-safe, and lets the swarm convergence check run on native Windows. Re-copy your `dist/<harness>/` to pick it up.

* **Workflow-birth, idempotent re-reports, and reject self-heal now ship to every harness.** Explicitly naming a scope on a fresh project (`/aidlc --scope <scope>` or `/aidlc <scope>`) births the workflow; a stale re-report after the workflow moved on is an idempotent `done`; Request Changes works even when the optional `gate-start` was skipped (backfilled gate rows carry `Recovered=true`); single-stage runs no longer leak into the main workflow's runtime graph or counts. The birth directive resolves its tools through the harness-dir seam, so it names the correct tree on Kiro and Codex, not a hardcoded `.claude/`.
* **Windows platform-invariance.** Path resolution across the engine and sensors is backslash/drive-letter aware (`fileURLToPath`, normalized glob comparison); the test runner is the native `bun tests/run-tests.ts` with `tests/run-tests.sh` kept as a POSIX wrapper; the Windows EC2/SSM harness (`tests/harness/windows/`) ships.
* **New tests:** `t143-scope-start-birth` (live scope-birth journey), `t152-windows-portability` (the renumbered Windows guard — `t144` is the harness-seam test on this branch), and `t153-engine-directive-harness-seam` (guards that no engine directive hardcodes `.claude/tools/` instead of the harness-dir seam). `BOLT_FAILED` and `SENSOR_FAILED` are now covered (audit floor 27).
* **Also absorbs the v0.6.9 repo-review batch.** State-file writes are now atomic (`core/tools/aidlc-lib.ts` `writeStateFile` routes through `writeFileAtomic` — temp + rename — with a read-only-target guard preserving the deliberate write barrier). The learning gate's `--test-run` skip is restored (`aidlc-learnings.ts` read the state field as `Test-Run Mode` (hyphen) while every writer uses `Test Run Mode` (space), so the skip was dead code). CHANGELOG version link references were removed (a distributed file should not embed a repository host); `t68` is redesigned — the version pin is the heading, headings must be unique, and a net-new guard fails if any link reference or host URL reappears. `LICENSE` is now MIT-0; the `--debug` failures-file extractor matches bun's `(fail)`/`error:` output.
* **And the v0.6.10 C2b + doctor + swarm batch.** State transitions are now lost-update safe: the 11 state-mutating subcommands (`set` / `set-skeleton-stance` / `checkbox` / `advance` / `finalize` / `complete-workflow` / `gate-start` / `approve` / `reject` / `revise` / `skip`) each wrap their read→decide→audit→write inside the audit lock, so concurrent writers (the swarm referee, parallel Bolts, hooks) serialise instead of clobbering each other (`fork` / `merge` were already locked; v0.6.9's atomic write didn't cover the lost update). No CLI surface change. `/aidlc --doctor` now presence-checks every hook `settings.json` wires — all 10 framework hooks, sourced from the wiring rather than a hardcoded list that silently skipped 3 (`aidlc-runtime-compile.ts`, `aidlc-sensor-fire.ts`, and the flow-altering `aidlc-stop.ts`) — and a wired-but-missing hook now fails loudly. `--doctor` is also read-only / cold-safe: on a project with no `audit.md` it creates nothing (it previously scaffolded `aidlc-docs/` + `audit.md` via its own emits, though `--doctor` runs before `--init`); initialized projects still record both events. And the swarm convergence check runs its check command through the OS shell instead of a hardcoded `bash` argv, so it no longer spuriously fails on native Windows PowerShell — still using `/bin/bash` on POSIX where present so a bash-specific check keeps its interpreter.

## [0.7.3] - 2026-06-14

Single-source onboarding docs. The three shipped onboarding docs (`dist/claude/.claude/CLAUDE.md`, `dist/kiro/AGENTS.md`, `dist/codex/AGENTS.md`) now all render from one hand-authored skeleton — `core/templates/onboarding.md` + per-harness fills — instead of being three independently-maintained artifacts (Claude hand-authored, Codex a regex-rewrite of Claude's CLAUDE.md, Kiro a hand-fork that had drifted to "two harnesses" and was missing whole sections). Adding a harness now means authoring one `onboarding.fills.ts`; the doc generates complete and drift-guarded. No behavior change to any distribution. Maintainers and Kiro/Codex users should regenerate (`bun scripts/package.ts`) and re-copy `dist/<harness>/`.

* **Onboarding docs are generated, not hand-maintained.** `bun scripts/package.ts` renders each harness's CLAUDE.md/AGENTS.md from `core/templates/onboarding.md`; `--check` drift-guards them like every other generated file. The Codex `AGENTS.md` no longer derives from Claude's CLAUDE.md, so Claude-specific prose can no longer leak into it.
* **Kiro's onboarding doc gained the Documentation and Automated-Testing coverage it was missing**, and its identity is anchored to the shared core (not "vs Claude").
* **New test** `t151-onboarding-skeleton` proves a brand-new harness renders a complete onboarding doc from the skeleton (every section present, no unsubstituted tokens) — the "4th harness for free" guarantee.

## [0.7.2] - 2026-06-14

Documentation re-architecture, framing pass. Reframes the project from "one core, three harnesses" to "one core, many harnesses" — the harness set is an open, growable family (today Claude Code, Kiro CLI, Codex CLI), not a hardcoded three — across the README, the repo `AGENTS.md`, the three guide front doors, and the architecture/porting reference. The Kiro and Codex shipped onboarding docs (`dist/<harness>/AGENTS.md`) change: their identity is now anchored to the shared core rather than to Claude, and the Codex `AGENTS.md` no longer leaks "Claude Code runs your shell non-interactively" in its bun bullet. No behavior change to any distribution. Maintainers and Kiro/Codex users should regenerate (`bun scripts/package.ts`) and re-copy `dist/<harness>/`.

* **README per-harness badges.** The single combined `harnesses-Claude · Kiro · Codex` badge is replaced by one badge per harness (Claude Code · Kiro CLI · Codex CLI), so adding a harness appends one line. The version badge is unchanged.
* **Codex `AGENTS.md` bun bullet corrected.** It inherited Claude Code's PATH prose ("Claude Code runs your shell non-interactively"); it now describes the non-interactive shells the harness spawns in harness-neutral terms. Kiro `AGENTS.md` no longer says "two harnesses" and anchors its tools to `core/tools/` rather than "the Claude Code harness".
* **Anti-rot guard.** `t55` gains a check (test 8) that fails CI if closed-count harness framing ("three harnesses", "generated three ways", "add a fourth", …) re-enters the authored docs, outside a carve-out for `CHANGELOG.md` and the directory-name "three senses of harness" note.

## [0.7.1] - 2026-06-13

Hardening pass over the one-core-three-harnesses build. Fixes a harness-neutrality bug that broke two core methodology paths on the Kiro and Codex distributions, closes a drift-guard blind spot, and corrects a generated install doc. No change to the Claude distribution's behavior. Maintainers and Kiro/Codex users should regenerate (`bun scripts/package.ts`) and re-copy `dist/<harness>/`.

* **Kiro/Codex: rule-directory paths now resolve correctly.** The tools hardcoded a `rules/` path segment, but Kiro ships rule layers at `.kiro/steering/` and Codex at `.codex/aidlc-rules/`. On those harnesses the Inception practices-discovery promotion gate failed closed ("aidlc-team.md not found"), §13 learnings were written to an unread directory, and the doctor's rule-drift check saw zero rules. A new `rulesSubdir()` seam (mirroring `harnessDir()`) resolves the right directory per harness; the Claude distribution is unaffected.
* **`.mcp.json` and `.gitignore` are now drift-guarded.** Both Claude project-root install files shipped outside `package.ts --check`; a hand-edit or stale `.mcp.json` passed CI green. They are now authored under `harness/claude/` and regenerated + checked like every other file.
* **Codex `AGENTS.md` install doc corrected.** It described a Claude config (Opus/Bedrock anthropic model IDs, a Read/Edit/… tool allowlist, a `.mcp.json`, and `.codex/skills/`) that the Codex distribution does not ship. It now documents the real `config.toml` (Bedrock `openai.gpt-5.5`/`gpt-5.4`), `[mcp_servers]` tables, the Starlark `default.rules` allowlist, and `.agents/skills/`.
* `t150` test 6 now pins the real shipped `trust-seed.toml` hashes via the exported `trustEntries()` (it previously hashed a non-shipped spike path); the statusline hook uses the shared project-dir seam instead of a `.claude`-hardcoded copy; contributor docs (`05-agent-system.md`, `10-knowledge-system.md`) and the Kiro guide corrected to the `core/` authoring model.

## [0.7.0] - 2026-06-13

**One core, three harnesses.** This consolidating minor closes the dist-unified effort: AI-DLC now ships from a single hand-authored source — a harness-neutral `core/` plus a thin `harness/<name>/` surface per CLI — that `bun scripts/package.ts` regenerates into three committed, drift-guarded distributions: `dist/claude/`, `dist/kiro/`, and `dist/codex/`. The Claude distribution is byte-identical to 0.6.x; Kiro and Codex are now first-class, regenerated from the same core rather than maintained on separate branches. It also closes the version-stream deferral both ports carried ("the real minor settles at unification"). Install by copying `dist/<harness>/` into your project as before — no build step for users; maintainers run the packager and never hand-edit `dist/`.

* **Three harnesses, one install table.** Claude Code (`dist/claude/.claude/`), Kiro CLI (`dist/kiro/.kiro/` + `AGENTS.md`), Codex CLI ≥ 0.139.0 (`dist/codex/`). See the README "Pick your harness" table and `docs/harness-engineering/`.
* **`bun scripts/package.ts`** regenerates all three dists from `core/` + `harness/`; `--check` is the CI drift guard; `codex trust --project <dir>` prints the Codex hook-trust pre-seed. Contributors edit `core/` or `harness/<name>/`, never `dist/`.
* **No user-facing command/flag/behavior change** for existing Claude Code users — `dist/claude/.claude/` is byte-identical to 0.6.x; this release changes where maintainers edit and adds two new harnesses.
* New "porting AIDLC to a new harness" guide in `docs/harness-engineering/`; architecture reference updated for the core/harness/dist split.

## [0.6.12] - 2026-06-13

Adds the Codex CLI distribution to the one-core-three-harnesses build: `harness/codex/` (manifest + `emit.ts` + the authored orchestrator skill and `aidlc-codex-adapter.ts`) regenerates `dist/codex/` from the shared `core/` via `bun scripts/package.ts codex`. emit.ts owns the Codex-specific surfaces no declarative row can express: `config.toml`, `hooks.json`, the hook trust pre-seed, the AGENTS.md merge, the 11 agent TOML transpositions (model map), and the `.agents/skills/` tree (orchestrator + runners + session skills, each with the implicit-invocation guard). Install Codex by copying `dist/codex/` into your project.

* `bun scripts/package.ts` now regenerates `dist/codex/` alongside claude + kiro; `--check` drift-guards all three. New `bun scripts/package.ts codex trust --project <dir>` prints the hook-trust entries for `$CODEX_HOME/config.toml`.
* The packager now reads renamed rule dirs at compile time (`AIDLC_RULES_DIR`) and realigns the compiled graph's rule paths — fixes empty `rules_in_context` in the kiro and codex distributions (their stage graphs now carry `.kiro/steering/` and `.codex/aidlc-rules/` rule paths).
* New tests: `t149-codex-hook-adapter` (12-case adapter contract), `t150-codex-packaging` (rename, hooks-wiring, trust-hash recipe, openai.yaml guards). The codex-exec journey ships as e2e gated on `AIDLC_CODEX_EXEC_LIVE=1` + codex ≥ 0.139.0.
* No change to the Claude distribution — `dist/claude/.claude/` stays byte-identical.

## [0.6.11] - 2026-06-13

Adds the Kiro CLI distribution to the one-core-three-harnesses build: `harness/kiro/` (manifest + the Kiro-authored orchestrator skill, agent JSON configs, the `aidlc-kiro-adapter.ts` stdin shim, `settings/cli.json`, and `AGENTS.md`) now regenerates `dist/kiro/` from the shared `core/` via `bun scripts/package.ts kiro`. Install Kiro by copying `dist/kiro/.kiro/` (and `dist/kiro/AGENTS.md`) into your project, exactly as before.

* `bun scripts/package.ts` now regenerates `dist/kiro/` alongside `dist/claude/`; `--check` drift-guards both. The packager gained a rules-dir rename (Kiro: `rules/` → `steering/`) and project-root file placement (AGENTS.md).
* New deterministic tests: `t147-kiro-hook-adapter` (the stdin-shim contract against live-captured payloads) and `t148-kiro-file-structure` (dist/kiro structural smoke). The Kiro ACP + TUI journeys ship as e2e that skip cleanly without `AIDLC_KIRO_ACP_LIVE=1` / `AIDLC_KIRO_TUI_LIVE=1` and a logged-in `kiro-cli`.
* No change to the Claude distribution — `dist/claude/.claude/` stays byte-identical.

## [0.6.10] - 2026-06-13

Restructures the repository to the one-core-three-harnesses layout (dist-unified keystone). The hand-authored source now lives in `core/` (harness-neutral: tools, stages, agents, rules, knowledge, hooks) and `harness/claude/` (the orchestrator skill, CLAUDE.md, settings); `bun scripts/package.ts` regenerates `dist/claude/` from them, and `bun scripts/package.ts --check` is the byte-parity drift guard. The shipped `dist/claude/.claude/` is byte-identical to the previous release — re-copy it as before; this release moves where maintainers edit, not what you install.

* No user-facing command, flag, or behavior change — `dist/claude/.claude/` is regenerated byte-for-byte identical to 0.6.9.
* Contributors now edit `core/` (or `harness/claude/`) and run `bun scripts/package.ts`; hand-editing `dist/` fails the new `package.ts --check` drift guard in CI. See `docs/reference/11-contributing.md`.
* Core `.md` prose carries a `{{HARNESS_DIR}}` token that the packager substitutes per harness; truthful Claude-specific references (the `$CLAUDE_PROJECT_DIR` note, the harness-dir enumeration in workspace-detection) stay literal.

## [0.6.9] - 2026-06-13

Ports the multi-harness runtime seam onto the framework core ahead of the one-core-three-harnesses restructure: the deterministic tools and hooks now resolve their harness directory (`.claude` / `.kiro` / `.codex`) through a single `harnessDir()` seam instead of hardcoding `.claude/`, and `/aidlc --doctor` grows per-harness wiring checks (Kiro agent config, Codex `config.toml`/`hooks.json`/version pin) plus a multi-harness-coexistence advisory. No layout change and no behavior change for Claude Code — in a `.claude/` tree every path still resolves to `.claude/`, so the regenerated distribution is byte-identical. Re-copy the shipped `.claude/` to pick it up.

* `/aidlc --doctor` now reports harness-specific wiring: on a Kiro tree it checks `agents/aidlc.json` + `settings/cli.json`; on a Codex tree it checks `config.toml`, `hooks.json`, `rules/default.rules`, and a `codex >= 0.139.0` version pin; on any tree it flags a detected multi-harness install (advisory, never blocking).
* Stage prose and the orchestrator skill present approval gates as "structured questions" (the harness binds the rendering — `question-rendering.md` ships beside the Claude orchestrator) rather than naming `AskUserQuestion` directly, so the same core text is correct under every harness.
* No new commands or flags. Existing `/aidlc` behavior under Claude Code is unchanged.

## [0.6.8] - 2026-06-13

Hardens the 0.6.7 recovery paths against the defects found shipping inside them, and changes the workflow-birth contract: explicitly naming a scope on a fresh project now starts the workflow instead of erroring. A stale stage re-report can no longer demote a gate-held next stage; Request Changes works even when the optional `gate-start` was skipped; single-stage runs no longer leak into the main workflow's runtime graph or session counts. Re-copy the shipped `.claude/` to pick it up. (Landed on the single-harness `main` line; this branch carries it into the multi-harness core in 0.7.4.)

* `/aidlc --scope <scope>` (and `/aidlc <scope>`) on a fresh project now births the workflow: the engine names the `init --scope <scope>` move and continues, instead of the old circular "Start a workflow with /aidlc <scope>" error. Bare `/aidlc` with no named scope still errors; its guidance now reads "Name a scope to start a workflow (/aidlc --scope <scope>) or scaffold one with /aidlc --init." An explicit `--scope` flag outranks a positional scope, and `--resume` never starts a new workflow.
* `bun .claude/tools/aidlc-orchestrate.ts report --stage <prev>` replayed after the workflow has moved on is now an idempotent `done` — previously it silently demoted an awaiting-approval (`[?]`) or revising (`[R]`) next stage back to in-progress and double-logged `STAGE_STARTED`. The `aidlc-state.ts advance` replay guard covers the same gate-held states.
* `bun .claude/tools/aidlc-state.ts reject <slug>` now accepts an in-progress stage: when `gate-start` was skipped, reject backfills the missing `STAGE_AWAITING_APPROVAL` row before recording the rejection instead of erroring with "requires one of: awaiting-approval".
* Backfilled gate rows (report recovery and reject self-heal) carry `Recovered=true` in the audit trail, so a gate held for a human decision is distinguishable from a gate backfilled at commit; `gate-start` gained an internal `--recovered` flag.
* Single-stage runs (`--single` / the `/aidlc-<stage>` runner skills) no longer contaminate the main workflow: runtime-graph compile and the state tool's audit dedup skip rows tagged `single-stage:`, so graphs, summaries, and replay counts cover only the main workflow.
* Live TUI test harness recognises the Windows npm shims `claude.cmd` / `claude.ps1`, keeping `--setting-sources` isolation intact on Windows runs.
* New live journey `tests/integration/t143-scope-start-birth.test.ts` drives `/aidlc --scope bugfix` end-to-end on a fresh project; docs reconciled (gate-start optional + engine backfill; 0.6.7 summary-reconciliation wording corrected to its real Status=Completed boundary).

## [0.6.7] - 2026-06-12

Hardens the engine handoff after live `/aidlc` runs exposed recovery paths a human conductor can naturally hit. Stage reports can now pin the acted directive with `--stage <slug>`, recover a missing approval gate before approving, and treat a completed workflow re-report as idempotent. Runtime graph refresh and summary output now follow the public `report` path and reconcile completed state so session summaries do not show stale pending counts after recovery. Re-copy the shipped `.claude/` to pick it up.

* `dist/claude/.claude/tools/aidlc-orchestrate.ts` — `report` uses `--stage <slug>` for the acted stage, opens a missing gate before approval on explicit-stage reports, advances a manually completed active stage, and returns an idempotent `done` when the workflow is already complete.
* `dist/claude/.claude/hooks/aidlc-runtime-compile.ts` and `dist/claude/.claude/tools/aidlc-runtime.ts` — runtime compile now watches `aidlc-orchestrate.ts report`, and `summary` reconciles completed `aidlc-state.md` checkboxes over stale or incomplete runtime graph rows.
* `dist/claude/.claude/skills/aidlc/SKILL.md`, scope runners, and `aidlc-common/protocols/stage-protocol.md` — conductor guidance now reports approvals with `--stage <directive.stage>` and leaves forward transition bookkeeping to the engine.

## [0.6.6] - 2026-06-11

Refreshes the shipped Bedrock model aliases so accounts using global inference profiles have the same path across the model family. The orchestrator still defaults to `opus[1m]`; Fable is now pinned for users who opt into `fable`/`fable[1m]`, and Sonnet plus Haiku move from `us.` to `global.` profile IDs. Re-copy the shipped `.claude/` or edit your existing `.claude/settings.json` model aliases to pick this up.

* `dist/claude/.claude/settings.json` — adds `ANTHROPIC_DEFAULT_FABLE_MODEL=global.anthropic.claude-fable-5`, changes `ANTHROPIC_DEFAULT_SONNET_MODEL` to `global.anthropic.claude-sonnet-4-6`, and changes `ANTHROPIC_DEFAULT_HAIKU_MODEL` to `global.anthropic.claude-haiku-4-5-20251001-v1:0`.
* `docs/guide/01-getting-started.md` and the shipped `.claude/CLAUDE.md` — document the Fable alias and the global Bedrock profile defaults.

## [0.6.5] - 2026-06-10

Moves the framework's default Opus model from the US-regional Bedrock inference profile to the global one, and teaches the statusline to abbreviate every Bedrock profile prefix. Under Bedrock's account-level data retention modes, an account set to `provider_data_share` (required for Claude Fable 5) can no longer invoke `us.anthropic.claude-opus-4-8` — requests fail with a Bedrock `InternalServerException` — while the `global.` profile works under every retention mode. If your account uses `provider_data_share`, re-copy the shipped `.claude/` (or edit `ANTHROPIC_DEFAULT_OPUS_MODEL` in your existing `settings.json`) to pick this up; accounts on the `default` retention mode work with either profile.

* `dist/claude/.claude/settings.json` — `ANTHROPIC_DEFAULT_OPUS_MODEL` is now `global.anthropic.claude-opus-4-8` (was `us.anthropic.claude-opus-4-8`).
* `dist/claude/.claude/hooks/aidlc-statusline.ts` — `abbreviateModel` recognises all Bedrock inference-profile prefixes (`us.` / `eu.` / `apac.` / `global.`), so the statusline renders `BR:opus-4-8[1m]` for the global profile instead of the unabbreviated model id.

## [0.6.4] - 2026-06-09

Closes a build-time gap for harness engineers and fork authors: `bun .claude/tools/aidlc-graph.ts compile` now rejects a stage whose `lead_agent` or any `support_agents` entry names an agent with no matching `.claude/agents/*.md` file. Previously the compile skipped this cross-check, so a stage pointed at a misspelled or missing agent compiled clean and only surfaced at run time as a "subagent not registered" `Task` error during the stage it leads (e.g. Code Generation). The check is the same agent-registration rule `/aidlc --doctor` already runs against your installed graph — now wired one layer earlier, at the build step that regenerates `stage-graph.json`. The reserved `orchestrator` pseudo-agent (the conductor itself, named as `lead_agent` on the bootstrap initialization stages) is exempt by design — it has no agent file. This is a build-step guard only; the shipped graph is unchanged and `/aidlc` runtime behaviour is identical, so there is no upgrade action for users who only run workflows. Re-copy the shipped `.claude/` to pick it up.

* `dist/claude/.claude/tools/aidlc-graph.ts` — `compileStageGraph` now passes `ctx.agents` (the slugs from `loadAgents()`) into `validateStageFrontmatter`, activating the agent-registration cross-check (Rule 9) at compile. A stage referencing an unknown agent fails the compile with `lead_agent "<name>" has no matching .claude/agents/*.md`, naming the offending stage file.
* `dist/claude/.claude/tools/aidlc-stage-schema.ts` — adds the exported `RESERVED_AGENT_SLUG` (`"orchestrator"`) constant and exempts it from Rule 9 for both `lead_agent` and `support_agents`, so the bootstrap initialization stages stay valid.

## [0.6.3] - 2026-06-09

Clarifies two pieces of conductor guidance so the orchestrator stops misreading them at run time. First, on a multi-agent stage that runs `mode: inline` (every multi-agent stage in the shipped graph), `support_agents` are perspectives the conductor adopts in its own context — it loads each support agent's file and knowledge the same way it loads the lead, and never calls `Task` for them; `Task` is reserved for `mode: subagent` stages. This removes the "support-agent subagent types aren't registered" fallback you would see when a support agent on an inline stage (e.g. AWS-platform or compliance during Feasibility / Application Design) was dispatched as a Task instead of read as a persona. Second, new reference material handed in mid-stage (a reference code package, an example repo, a spec) is now explicitly classified as evidence for the *current* stage, never an instruction to advance — so supplying a package during Functional Design no longer skips the remaining design/NFR stages and jumps to Code Generation; routing changes only on an explicit `--stage` / `--scope` action through the normal impact/gate flow. No upgrade action; re-copy the shipped `.claude/` to pick it up.

* `dist/claude/.claude/aidlc-common/conductor.md` — "Framing the persona" now ties support-agent handling to `directive.mode`: inline support agents are loaded as personas in the conductor's context, `Task` is reserved for `mode: subagent`, and a missing Task subagent-type registration on an inline stage is called out as expected (not an error to route around).
* `dist/claude/.claude/aidlc-common/protocols/stage-protocol.md` — §5 "Multi-agent stages" mirrors the same rule: inline support agents are adopted perspectives, not Task dispatches.
* `dist/claude/.claude/aidlc-common/protocols/stage-protocol-recovery.md` — §7 Change Handling adds "New reference material supplied mid-stage": treat it as evidence/input, stay on the current stage, fold it into the current questions/artifacts/memory, and continue through the normal `report → next` transition; advance only on an explicit user jump/scope change.

## [0.6.2] - 2026-06-09

Hardens two framework sensors and lands the test suite's all-TypeScript port. The `type-check` sensor no longer reports a clean PASS when `tsc` fails to load its config: a config-load failure (e.g. TS18003 "No inputs were found", which exits non-zero but carries zero parseable diagnostics) now propagates `tsc`'s exit code so the dispatcher records it as `script-error` rather than a false green. The sensor dispatcher gains an `AIDLC_SENSOR_SCRIPT_DIR` seam so per-sensor scripts resolve from an overridable directory — unset in production (sibling resolution against the tools dir, exactly as before), set only by tests that exercise stub scripts so they never write into the shipped `.claude/tools/` tree. No upgrade action; re-copy the shipped `.claude/` to pick it up.

* `dist/claude/.claude/tools/aidlc-sensor-type-check.ts` — propagates `tsc`'s non-zero exit when zero diagnostics parse, so a broken `tsconfig` surfaces as `script-error: exit-<n>` instead of a silent clean PASS. A genuine type error (non-zero exit with parsed diagnostics) still flows through as `pass:false`/FAILED, unchanged.
* `dist/claude/.claude/tools/aidlc-sensor.ts` — `resolveScriptPath` honours an optional `AIDLC_SENSOR_SCRIPT_DIR` override (mirroring `AIDLC_SENSORS_DIR` for manifests); unset, it resolves against the tools dir as before.

## [0.6.1] - 2026-06-08

Normalizes the path strings the compiled stage graph records for rules and sensors to POSIX form (forward slashes) on every platform. On macOS and Linux this is a no-op — the emitted paths are byte-identical to before. On Windows the compiled graph previously recorded backslash paths in each stage's `rules_in_context` / `sensors_applicable` rows, which mismatched any forward-slash comparison; they are now consistent with the rest of the framework. No upgrade action; re-copy the shipped `.claude/` to pick it up.

* `dist/claude/.claude/tools/aidlc-lib.ts` — adds an exported `toPosix(path)` helper (a no-op when the OS separator is already `/`).
* `dist/claude/.claude/tools/aidlc-graph.ts` — the `.claude/rules` and `.claude/sensors` path-emit sites in `loadRules` / `loadSensors` now pass through `toPosix`, so the compiled graph's resolution rows are POSIX-form on Windows as on macOS/Linux.

## [0.6.0] - 2026-06-07

**The orchestrator is unbundled: a deterministic engine decides what happens next, the `/aidlc` session carries it out, and the framework gained a family of typeable runner commands plus an autonomous build swarm.** For everyone running `/aidlc`, invocation is unchanged — the recomposition is internal. What's new is the surface around it: one-word `/aidlc-<stage>` and `/aidlc-<scope>` runner commands; a `--single` mode that runs a stage in isolation without touching your workflow; and, under human-granted Construction autonomy, a swarm that fans out independent build units in parallel and converges them behind a deterministic referee. Under the hood, the routing logic moved out of `SKILL.md` (now a ~170-line forwarding loop) into the `aidlc-orchestrate` engine, which emits a typed directive on every turn; scope membership is now file-authored (`.claude/scopes/aidlc-<name>.md` + a `scopes:` tag on each stage) and the old `scope-mapping.json` is gone.

**Upgrade.** Re-copy the shipped `.claude/` over your project's `.claude/` (`cp -r dist/claude/.claude/ your-project/.claude/`). Because every framework hook is now registered project-wide in `settings.json` (the skill-scoped hooks moved there), re-copy the shipped `settings.json` or merge its `hooks` block so the relocated hooks are registered — `aidlc/SKILL.md` no longer carries a `hooks:` block. The state template is unchanged, so existing workspaces stay schema-compatible.

**For everyone running `/aidlc`**

* **`/aidlc` works exactly as before** — full orchestrator, scope detection, every flag. No breaking changes to how you invoke a workflow.
* **New `/aidlc-<scope>` runner commands.** `/aidlc-bugfix`, `/aidlc-feature`, `/aidlc-mvp`, `/aidlc-security-patch` drive a workflow with a fixed scope and no detection — the same workflow as `/aidlc --scope <name>`, as their own typeable command. Every other scope stays reachable via `/aidlc --scope <name>`.
* **New `/aidlc-<stage>` runner commands + `--single`.** One command per runnable stage (e.g. `/aidlc-code-generation`) runs that stage in isolation via `--single` and never advances your main workflow's stage pointer — the isolation is tool-enforced. `/aidlc-init` packages `/aidlc --init`.
* **An autonomous build swarm.** After you grant Construction autonomy, eligible independent build units fan out in parallel (across isolated worktrees) and converge behind a deterministic referee that re-verifies every unit before merge — a unit that fails, or is falsely claimed converged, returns the baton to you. Set `AIDLC_USE_SWARM=1` to drive the fan-out with an inline workflow; unset it for the parallel-subagent floor.
* **Skill-picker discoverability.** Every `/aidlc-*` runner surfaces in Claude Code's `/` picker, no manual registration.

**For harness engineers and contributors**

* **Scope is a file-authored primitive.** A scope is a `.claude/scopes/aidlc-<name>.md` file (identity) plus a `scopes:` tag on each member stage (membership), transposed at compile into `scope-grid.json`. The `scope-mapping.json` data file is removed; adding a scope is now purely additive, no code edit.
* **Runners are generated, not hand-written.** `aidlc-runner-gen.ts` emits a runner per runnable stage and per shipped scope from the compiled graph; drift guards fail CI if the on-disk set diverges. "To add a stage, write a stage file" then regenerate — the runner follows.
* **The orchestration engine + typed directive contract.** `aidlc-orchestrate.ts` (`next`/`report`) owns all between-stage routing and emits a validated typed directive; `SKILL.md` is the conductor that acts on it. New reference chapter [Engine and Skill System](docs/reference/17-skill-system.md) and User Guide chapter [Skills and Runner Commands](docs/guide/17-skills.md) document both.
* **Audit taxonomy grows to 67 events** — six `SWARM_*` events for the batch lifecycle (`SWARM_STARTED`, `SWARM_UNIT_CONVERGED`, `SWARM_UNIT_FAILED`, `SWARM_BATON_RETURNED`, `SWARM_COMPLETED`, `SWARM_DEGRADED`).
* `dist/claude/.claude/tools/aidlc-version.ts` — bumped 0.5.21 → 0.6.0.

## [0.5.21] - 2026-06-06

Wires the swarm live: the engine now emits an `invoke-swarm` directive and the conductor acts on it natively, so an eligible Construction batch fans out automatically once a human grants autonomy at the walking-skeleton ladder. When a Construction workflow is at the per-unit build stage (code-generation) with `Construction Autonomy Mode: autonomous` and an eligible batch is ready on the compiled `bolt_dag`, the engine answers with `invoke-swarm` naming that batch; the conductor — the live `/aidlc` session — fans the batch out in-session (N parallel `Task` calls by default, or an inline Dynamic Workflow when `AIDLC_USE_SWARM=1`), consults the `aidlc-swarm.ts` referee (`prepare` / `check` / `finalize`) for the convergence verdict, and on the tool's failure envelope (exit 2) takes the baton back and re-engages the human — the swarm never escapes the conductor. The three previously-reserved batch-level swarm audit events now emit from the deterministic referee. `invoke-swarm` is an orthogonal directive kind beside the stage `mode` enum — it does NOT activate the reserved `agent-team` mode, which stays reserved. No upgrade action.

* The engine emits `invoke-swarm` for an eligible Construction batch under an `autonomous` grant; with a gated or unset autonomy mode it keeps emitting a normal `run-stage`, so nothing fans out until you grant autonomy after the walking skeleton ships.
* On an `invoke-swarm` directive the conductor owns the fan-out and the retry loop in-session — N parallel `Task` calls (the floor) or an inline Dynamic Workflow (`AIDLC_USE_SWARM=1`) — and consults the `aidlc-swarm.ts` referee for the verdict: `prepare` forks the worktrees, `check <unit>` reports per-unit convergence (exit 0 = genuine), and `finalize --claimed` re-verifies + merges the genuine passes. `finalize` exit 0 means the batch converged and merged (the loop continues); exit 2 means a unit failed or a merge failed and the conductor takes the baton — it halts and asks the human via the existing halt-and-ask seam, regardless of autonomy mode.
* The three batch-level swarm audit events now emit from `aidlc-swarm.ts`: `SWARM_STARTED` (`prepare` forks the batch), `SWARM_BATON_RETURNED` (one per failed unit, naming the unit and its typed reason), and `SWARM_COMPLETED` (batch closed, with the converged/failed tally). All six swarm events now have a real emitter; the taxonomy count is unchanged from v0.5.20 (which introduced `SWARM_DEGRADED`).
* A human may optionally type `/goal` at the autonomy grant to run the batch until a condition holds (e.g. the referee reports all units converged) — Claude Code's built-in run-until-a-condition loop. `/goal`'s judge reads the transcript and never runs the check itself, so the referee's `finalize` exit code stays the sole convergence verdict; `/goal` is a human overlay, not part of the framework's machinery.

## [0.5.20] - 2026-06-06

Ships the swarm's deterministic convergence **referee**, `aidlc-swarm.ts`. The swarm fires only under human-granted Construction autonomy inside a live `/aidlc` session, so the conductor (that session) owns the fan-out and the retry loop; the tool owns only what must be deterministic — the convergence verdict, the anti-tamper guard, the serialised merge-back, and the typed failure envelope. It is stateless (no iteration counter) and re-exposed as three subcommands. `prepare` forks an isolated git worktree per unit (composing `aidlc-worktree create` + `aidlc-bolt start --worktree`) and records batch start. `check <unit>` returns a stateless verdict from the project's own check command (exit 0 = green — a worker's self-claim is never trusted) plus an anti-tamper compare of a protected file against its forked-git baseline. `finalize --claimed` re-verifies every unit the conductor claims converged before any merge, serialised-merges only the genuine passes (the existing HOLD-MERGE lock), and returns the typed envelope (`unsatisfiable`, `budget-exhausted`, `cap-exhausted`, `error`). Because `finalize` re-verifies, a red unit cannot merge even if the conductor lies or misremembers — the lying-conductor guard. Nothing invokes the referee automatically yet; it is wired to the conductor in v0.5.21. No upgrade action.

* New tool surface `bun .claude/tools/aidlc-swarm.ts prepare|check|finalize`. `prepare --batch <n> --units <a,b,c> [--base <branch>] [--degraded-from <subagent|ultracode>]` forks the worktrees; `check <unit> --check-cmd <cmd> [--test-file <path>]` prints `{converged, tampered, reason}` and exits 0 iff genuinely converged (emits no audit); `finalize --batch <n> --units <a,b,c> --claimed <a,b> --check-cmd <cmd> [--test-file <path>] [--reasons <unit>=<reason>,…]` prints the JSON envelope (`{units, converged, failed, merge_failures}`) and exits 0 when every claimed unit re-verified and merged, 2 when any unit failed or a merge failed (the conductor takes the baton). `--reasons` lets the conductor attribute a typed reason (`unsatisfiable` / `budget-exhausted` / `cap-exhausted`) to a *declined* unit it did not claim — recorded faithfully on `SWARM_UNIT_FAILED`, defaulting to `cap-exhausted`, and never able to override a claimed-but-red unit's `error` verdict. The retired headless `run` verb, the `claude -p` worker, the triple cap, and the `AIDLC_SWARM_CLAUDE_BIN` test seam are all gone — the runaway backstop is now the harness 8-block Stop-hook ceiling.
* A new audit event `SWARM_DEGRADED` records a loud downgrade — `AIDLC_USE_SWARM=1` was requested but the Workflow tool was unavailable, so the conductor ran the subagent floor (the referee makes the substrate difference invisible to convergence). The two previously-reserved per-Unit events now emit from `finalize`: `SWARM_UNIT_CONVERGED` (re-verified green and untampered) and `SWARM_UNIT_FAILED` (not claimed, claimed-but-red, or tampered, with the typed reason). The batch-level trio stays reserved until the conductor wiring lands. The audit taxonomy grows from 66 to 67 events.

## [0.5.19] - 2026-06-06

Makes the unit dependency graph machine-readable end-to-end, the first step toward the headless build swarm. The units-generation stage (Inception 2.7) now requires a fenced `yaml` `units:` edge block on `unit-of-work-dependency.md` beside the existing prose, and `aidlc-runtime compile` parses that structured data into a `bolt_dag` node on `runtime-graph.json` — a deterministic batch DAG (topological levels of units with no mutual dependency) with no model in the compile path, so a re-compile stays byte-identical. Nothing in your workflow invokes the swarm yet; this release only lays the deterministic batch shape it will read. No upgrade action — an existing workflow simply re-runs 2.7 (or the conductor adds the block) before a batch is computed.

* Stage 2.7 (units-generation) now expects a required fenced `yaml` `units: [{name, depends_on: [...]}]` block on `unit-of-work-dependency.md`. The `required-sections` sensor validates it at the 2.7 gate and reports `edge_block` as `ok`, `absent`, `malformed`, or `cyclic` — a malformed or cyclic block fails the sensor there, upstream, instead of being silently mis-read later.
* `bun .claude/tools/aidlc-runtime.ts compile` emits a new optional `bolt_dag` node (`{units, batches}`) on `runtime-graph.json` when that block is present and valid; an absent, malformed, or cyclic block omits the node and writes a stderr diagnostic naming the reason, leaving the rest of the envelope unchanged.

## [0.5.18] - 2026-06-04

Adds the runner-skill layer over the engine and moves every framework hook into project-wide `settings.json`. **(1) Stage-runners + `--single`:** a per-stage runner skill for every runnable stage, behind a new engine `--single` mode, so you can run one stage on its own without advancing your main workflow. Each `/aidlc-<stage>` command (e.g. `/aidlc-application-design`, `/aidlc-code-generation`) drives that single stage — the engine emits one run-stage directive and its gate, the conductor runs it, and a synthetic-id record is committed to the audit log. The load-bearing guarantee is tool-enforced: a `--single` run NEVER touches your main workflow's `Current Stage`, and an attempt to advance the main workflow from a single run returns an error. The three bootstrap **initialization** stages get no per-stage runner — they have no standalone meaning (you cannot scaffold half a workspace), so the whole initialization phase is packaged as one `/aidlc-init` command wrapping `/aidlc --init`. **(2) Scope-runners:** a typeable one-word command per scope (`/aidlc-bugfix`) that drives the workflow with a fixed scope and no scope detection — first batch `bugfix`, `feature`, `mvp`, `security-patch`; every other scope stays reachable via `/aidlc --scope <name>`. Both runner families are generated from a single `aidlc-runner-gen.ts` (stage-runners from the compiled stage list, scope-runners over `.claude/scopes/*.md`) and kept in step by drift guards. **(3) The hooks move:** the six workflow-spine hooks (audit-logger, sensor-fire, sync-statusline, runtime-compile, validate-state, log-subagent) plus the `Stop` hook move out of `aidlc/SKILL.md` frontmatter into the project-wide `settings.json` hooks block, joining SessionStart + SessionEnd. Every hook self-gates (it no-ops when no workflow is active), so always-on is safe — and every entry point, including the new runners and any hand-written customer runner, inherits the deterministic spine with no per-runner `hooks:` block. Upgrade action: when you take this version, re-copy the shipped `.claude/settings.json` (or merge its `hooks` block) so the relocated hooks are registered; the `aidlc/SKILL.md` frontmatter no longer carries a `hooks:` block.

* New typeable commands: one `/aidlc-<stage>` per runnable stage (29 — e.g. `/aidlc-functional-design`, `/aidlc-deployment-execution`), each running that stage in isolation and stopping with your main workflow pointer untouched; plus `/aidlc-init`, which runs the whole initialization phase (`/aidlc --init`: scaffold + detect + state-init) in one step.
* New typeable scope commands `/aidlc-bugfix`, `/aidlc-feature`, `/aidlc-mvp`, and `/aidlc-security-patch` run the full workflow with that scope baked in (no scope detection). Every other scope is still reachable via `/aidlc --scope <name>`.
* New engine flow `aidlc-orchestrate next --stage <slug> --single` (emit one run-stage directive for the stage) and `aidlc-orchestrate report --single --stage <slug> --result completed` (commit a synthetic-id STAGE_STARTED/STAGE_COMPLETED pair, audit-only). A `report --single` with no `--stage`, or any single-stage run of an initialization stage, returns an `error` — single runs cannot advance or bootstrap the main workflow (which is why initialization ships as `/aidlc-init`, not per-stage runners).
* New tool `bun .claude/tools/aidlc-runner-gen.ts`: `write` regenerates the 29 stage-runner dirs + the `/aidlc-init` wrapper from the compiled stage list (pruning any stale per-init-stage runner) and `check` is its drift guard asserting the stage-runner set equals the runnable-stage set; `scopes [--all] [--check]` emits/validates scope-runner skills over `.claude/scopes/*.md`; `list` prints the slugs.
* All framework hooks now live in `.claude/settings.json` (project-wide). The six workflow-spine hooks and the `Stop` hook moved out of `aidlc/SKILL.md` frontmatter. Re-copy the shipped `settings.json` hooks block when you upgrade; without it the relocated hooks will not fire.
* Extensibility: to add a stage, write a stage file and recompile — the stage is immediately runnable via `/aidlc --stage <slug> --single`; a dedicated `/aidlc-<slug>` runner is optional sugar you regenerate with `aidlc-runner-gen write`. See `docs/harness-engineering/02-adding-a-stage.md`.

## [0.5.17] - 2026-06-04

Moves scope membership off the hand-edited `tools/data/scope-mapping.json` blob onto the same file-authored pattern every other primitive already uses. A scope is now authored as one `.claude/scopes/aidlc-<name>.md` file (frontmatter `name`/`depth`/`keywords`/`description`, prose body) plus a per-stage membership tag: each stage's frontmatter carries a `scopes: [<name>, …]` list naming the scopes under which it runs. The build step `bun .claude/tools/aidlc-graph.ts compile` transposes those per-stage lists into the EXECUTE/SKIP grid (`.claude/tools/data/scope-grid.json`, a new compiled artifact drift-guarded by `compile --check` exactly like `stage-graph.json`), and the runtime resolves scopes from the grid + the `.md` files instead of the JSON. Behaviour is unchanged — every scope resolves and runs exactly as before (proven byte-identical across all 9 scopes by an `AIDLC_GRAPH_RESOLVE=1` parity test) — and `tools/data/scope-mapping.json` is deleted. Adding a scope is now the same muscle memory as authoring a sensor or agent: drop `.claude/scopes/aidlc-<name>.md` and tag the stages; no code change. Upgrade action: customisers who edited `scope-mapping.json` should re-express those choices as `.claude/scopes/*.md` files plus per-stage `scopes:` tags, then run `compile` to regenerate the grid.

* Scopes are now authored as `.claude/scopes/aidlc-<name>.md` files (one per scope) plus a `scopes:` list in each stage's frontmatter. Dropping a new `.claude/scopes/aidlc-x.md` makes `x` a valid scope — `/aidlc --scope x`, `/aidlc --doctor`, and NL keyword inference all pick it up with no code change.
* `bun .claude/tools/aidlc-graph.ts compile` now emits a second compiled artifact, `.claude/tools/data/scope-grid.json` (the EXECUTE/SKIP transpose). `compile --check` fails (exit 1) if either `stage-graph.json` or `scope-grid.json` is stale.
* New `bun .claude/tools/aidlc-graph.ts resolve <scope>` subcommand emits the active scope's plan (`.aidlc-plan.json`); it is gated behind `AIDLC_GRAPH_RESOLVE=1` during rollout.
* `tools/data/scope-mapping.json` is removed. Any script reading that file directly must read `tools/data/scope-grid.json` (same `{scope: {stages}}` shape) for the EXECUTE/SKIP grid, or the `.claude/scopes/*.md` frontmatter for depth/keywords/description.

## [0.5.16] - 2026-06-04

Relocates the framework's shared methodology spine into a new `.claude/aidlc-common/` directory, a peer of `.claude/skills/`, and brings the `aidlc` skill into conformance with the published Agent Skills specification. The 32 stage bodies move from `.claude/skills/aidlc/stages/<phase>/` to `.claude/aidlc-common/stages/<phase>/`, and the four protocol files (`stage-protocol.md`, `stage-protocol-governance.md`, `stage-protocol-recovery.md`, `stage-definition.md`) move from `.claude/skills/aidlc/` to `.claude/aidlc-common/protocols/`; they join the conductor persona already homed at `.claude/aidlc-common/conductor.md`. The relocation is transparent to the engine — `stage-graph.json` regenerates byte-identically and every tool that resolves a stage file (the orchestration engine, the graph compiler, the learnings gate, the doctor) now reads from the new location. Customisers who edit stage files should look under `.claude/aidlc-common/stages/` rather than `.claude/skills/aidlc/stages/`. Upgrade action: when you take this version, your on-disk stage and protocol files move to `.claude/aidlc-common/`; re-apply any local stage customisations there.

* Stage files now live at `.claude/aidlc-common/stages/<phase>/<slug>.md` and the stage-protocol / stage-definition reference files at `.claude/aidlc-common/protocols/`. `/aidlc --doctor` resolves them from the new location; customising a stage means editing it there.
* The `aidlc` skill validates clean against the Agent Skills specification, and a conformance guard (`tests/unit/t123-skills-spec-conformance.sh`) now checks every shipped skill dir on each test run (`name` matches its directory, `description` present, `SKILL.md` body within the 500-line limit).

## [0.5.15] - 2026-06-04

Restores `--test-run` persistence at both workflow birth AND resume, which the orchestration-engine cutover (0.5.12) silently dropped on both legs. When that release moved orchestration from `SKILL.md` prose into the engine, two re-stamp paths were lost. (1) Birth: the engine's `--init` directive builder threaded `--scope`/`--depth`/`--force` but not `--test-run` — so `/aidlc <scope> --test-run` scaffolded state WITHOUT the `Test Run Mode: true` field that `init` writes only when it receives the flag. (2) Resume: the old prose ran `aidlc-utility.ts enable-test-run` whenever `--test-run` re-entered an already-scaffolded workflow, re-stamping the field; the cutover deleted that instruction with no replacement, so a `--test-run` resume over a stamp-less workflow never re-stamped. That field is what the jump tool reads on resume to detect test-run mode (it reads the field, not the CLI flag), so either drop meant a `--test-run` run could lose its automation marking and start prompting at gates. The engine now restores both: it threads `--test-run` into the scaffold command at birth, and on resume it emits a run-then-continue `print` naming `enable-test-run` when `--test-run` re-enters a workflow whose state lacks the field — the same engine-names-the-move / conductor-runs-the-tool shape it already uses for scope-change and jumps, so `next` stays read-only. This makes good on 0.5.12's "behaviour is unchanged" promise. No action is needed for existing workflows. No upgrade action required.

* `/aidlc <scope> --test-run` (and `/aidlc --init --test-run`) once again records `Test Run Mode: true` in `aidlc-docs/aidlc-state.md` at workflow birth, so test-run mode survives across resume in a fresh session.
* `/aidlc <scope> --test-run` re-entering an EXISTING workflow whose state file lacks the `Test Run Mode` field (e.g. a workflow first started without `--test-run`, then resumed with it) now re-persists the field instead of silently running without it — restoring the resume-time `enable-test-run` re-stamp the prose orchestrator ran before the cutover. Between 0.5.12 and this release the flag was dropped on both the birth and resume legs, so an automated/CI run could lose its test-run marking and start prompting at gates.

## [0.5.14] - 2026-06-04

Adds the framework's first flow-altering hook: a `Stop` hook (`aidlc-stop.ts`, wired into the `aidlc` skill frontmatter) that enforces the interactive forwarding loop. When the conductor tries to end its turn, the hook runs the orchestration engine (`aidlc-orchestrate next`); if the workflow is complete (`done`) it lets the turn end, and if a step is still pending it blocks the stop and re-feeds the next move so the loop runs to completion regardless of whether the LLM remembered to consult the engine. The injected message is phrased only as the work still owed — never an override-shaped instruction — so a buggy or compromised engine can only ever continue sanctioned work, never hijack the session. Recursion is bounded two ways so a stuck loop can never trap a session: a no-progress block counter under an 8-block ceiling (`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`, default 8) and Claude Code's own `stop_hook_active` signal; once the ceiling is reached the hook releases the turn. User interrupt (Esc) is never affected — Stop hooks do not fire on interrupt. The hook is a no-op outside an AIDLC workflow and fails open on any unexpected error, so a non-AIDLC session is never blocked. No upgrade action required.

* The shipped `aidlc` skill now registers a `Stop` hook. On the interactive path the forwarding loop is harness-enforced: a turn that ends with a pending workflow step is blocked and the next step is injected back, until the engine reports the workflow is `done`. Set `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` to tune the recursion ceiling (default 8); when the no-progress block streak reaches it, the hook lets the turn end. The hook does nothing outside an AIDLC workflow and never affects a manual interrupt.
* The framework now ships 10 hooks (was 9).

## [0.5.13] - 2026-06-04

Extracts the conductor's execution-quality prose out of the orchestrator's `SKILL.md` into a shared `aidlc-common/conductor.md`, and the engine now delivers that persona in-context on the first stage of a workflow (so framework and hand-written runners get the same conductor with no per-skill wiring). The same release names and tools the one workflow decision the engine cannot compute on its own: the first Construction Bolt's approval gate depends on a team's walking-skeleton stance, which is read from free-form `## Walking Skeleton` practices prose. Rather than put that judgement in a deterministic tool, the engine emits that gate as `"unresolved"`, the conductor classifies the prose and hands the stance back via a new `report --skeleton-stance` flag, and the next `next` emits the now-determined gate. Behaviour is unchanged for anyone running a Construction workflow — the gate still presents at the first Bolt — and the engine still owns the transition. No upgrade action required.

* `bun .claude/tools/aidlc-orchestrate.ts report` accepts a new `--skeleton-stance <on|off|scope-dependent>` flag. It records the classified walking-skeleton stance and does not commit a stage transition; the following `next` reads it and resolves the first Construction Bolt's gate. An invalid stance value, a stance reported when the workflow is not parked on the first Construction Bolt, or a stance reported with no workflow state each return a clear error.
* The `run-stage` directive emitted by `bun .claude/tools/aidlc-orchestrate.ts next` may now carry `gate: "unresolved"` (instead of a boolean) for the first Construction Bolt before its stance is classified. Every other stage still carries a boolean gate. Scripts that parse the directive's `gate` field should treat it as `boolean | "unresolved"`.
* The first `run-stage` directive of a workflow now carries an optional `conductor_persona` string (the shared execution-quality persona, read from `.claude/aidlc-common/conductor.md`); later directives omit it. No skill references that file by path — the engine delivers it.

## [0.5.12] - 2026-06-03

Cuts the `/aidlc` orchestrator over to the deterministic orchestration engine (`aidlc-orchestrate.ts`), which was built and proven in the prior releases but until now stood beside the prose orchestrator unused. The orchestrator's `SKILL.md` drops from 895 lines of inter-stage dispatch prose to a short forwarding loop — get a directive from the engine, do that one move, report the outcome, repeat — bringing the file under the Agent Skills 500-line limit. Behaviour is unchanged: scope resolution, stage walking, gates, jumps, resume, and workflow completion all now flow through the engine that a differential corpus already proved reproduces the prose's directive stream across all 9 scopes. The change is reversible by a single revert. This release also corrects four latent no-state engine defects in the workflow-birth paths the cutover leans on (a bare known-scope positional, a no-state skip-stage jump, an invalid `--scope` over an active workflow, and a no-state coverage hole in the differential corpus). No upgrade action required.

* `/aidlc` now consults the deterministic engine for every between-stage decision instead of running dispatch prose — no observable change to starting, resuming, jumping, or completing a workflow, but the routing is now tool-owned and reversible.
* `bun .claude/tools/aidlc-orchestrate.ts next bugfix` (a bare known-scope name with no workflow yet) is recognised as the scope rather than read as freeform intent — it returns the same "no workflow state" error as `next --scope bugfix`, instead of a scope-confirmation defaulting to `feature`.
* `bun .claude/tools/aidlc-orchestrate.ts next --scope <scope> --stage <stage>` with no workflow yet now errors `Stage "<stage>" is skipped for scope "<scope>". Choose a different stage or change scope.` when the stage is out of scope, matching the with-workflow behaviour (previously it emitted a run-stage directive).
* `bun .claude/tools/aidlc-orchestrate.ts next --scope <invalid>` now errors `Unknown scope "<invalid>". Valid scopes: …` even when an active workflow supplies a valid scope (previously the invalid flag was silently ignored and the current stage ran).

## [0.5.11] - 2026-06-02

Extends the internal `aidlc-orchestrate next` engine to cover every non-happy-path the prose orchestrator handles — jumps, resume, init, scope/config changes, and environment-scope validation — each emitted as a typed directive. The engine still stands beside the prose orchestrator and nothing in the workflow calls it yet, so your `/aidlc` runs are unchanged. `next` remains read-only: it never mutates state, validates the jump direction and the environment scope by composing the existing pure-read tools, and emits `ask` rather than ever calling AskUserQuestion. No upgrade action required.

* `bun .claude/tools/aidlc-orchestrate.ts next` now emits the full directive surface: jump targets (`--stage`/`--phase`) resolve their forward/backward/redo direction and in-scope validity through `aidlc-jump.ts resolve`, so a jump to a stage your scope skips comes back as an `error` with the same wording the jump tool prints; `--resume` over an existing workflow and a freeform request with no workflow yet come back as `ask` (the engine never calls AskUserQuestion); `--init` on an existing workspace returns the verbatim `aidlc-state.md already exists … Use --force to reinitialize.` guard as an `error`, while a clean-workspace `--init` and a scope/config change return a `print` naming the command to run (the engine performs no mutation). An invalid `AWS_AIDLC_DEFAULT_SCOPE` returns an `error` carrying the verbatim `Invalid AWS_AIDLC_DEFAULT_SCOPE "…". Valid scopes: …` message.

## [0.5.10] - 2026-06-02

Teaches the deterministic orchestration engine (`aidlc-orchestrate next`) to resolve artifact paths. The compiled stage graph stores each stage's artifacts as vocabulary *names* (e.g. `decisions`), not file paths; the engine now turns those names into canonical `aidlc-docs/...` paths when it builds a `run-stage` directive, and drops `conditional_on: brownfield`/`greenfield` consumes-entries that don't match your workflow's Project Type. This is still engine-only groundwork — the engine stands beside the prose orchestrator and nothing in the workflow calls it yet, so your `/aidlc` runs are unchanged. No upgrade action required.

* The directive emitted by `bun .claude/tools/aidlc-orchestrate.ts next` now carries fully-resolved `consumes`/`produces` file paths instead of bare vocabulary names. A `produces` entry resolves under the directive's own stage (`aidlc-docs/<phase>/<stage>/<name>.md` for a non-per-unit stage); a `consumes` entry resolves under the stage that *produces* that artifact, because a consumed artifact lives in its producing stage's directory — so e.g. `application-design`'s consume of `requirements` resolves to `aidlc-docs/inception/requirements-analysis/requirements.md`, not under `application-design`. The five per-unit Construction stages (`nfr-requirements`, `nfr-design`, `functional-design`, `infrastructure-design`, `code-generation`, detected via their `for_each: unit-of-work` graph field) resolve to `aidlc-docs/construction/{unit-name}/<stage>/<name>.md`.
* A consumed artifact marked `conditional_on: brownfield` (or `greenfield`) is included only when it matches the `Project Type` recorded in `aidlc-docs/aidlc-state.md`; when the project type is unknown the engine keeps every entry. Path resolution and this filter both run in the engine (a deterministic tool), never delegated to the conductor.

## [0.5.9] - 2026-06-02

Adds the commit-the-transition half of the deterministic orchestration engine — the internal `aidlc-orchestrate report` command. After the conductor acts on a directive, `report` records what happened so the next `aidlc-orchestrate next` reads fresh state. It is a thin dispatcher: it shells out to exactly one of the existing state-transition commands (approve, advance, or complete-workflow), chosen by the acted stage's gate status and then finality — it reimplements none of the transition logic. The engine stands beside the prose orchestrator and nothing in the workflow calls it yet, so your `/aidlc` runs are completely unchanged. No upgrade action required.

* New internal command `bun .claude/tools/aidlc-orchestrate.ts report --result <outcome> [--user-input <text>] [--reason <text>] [--test-run] [--project-dir <dir>]` commits the active stage's transition and prints a terminal directive. A gated stage routes through `approve` (which owns the full transition and self-advances); a non-gated stage routes through `advance`, or `complete-workflow` when it is the final in-scope stage. A rejected transition surfaces as an error directive carrying the underlying tool's message; the engine itself writes no state and holds no lock — every mutation happens inside the already-atomic state command it dispatches.

## [0.5.8] - 2026-06-02

Adds the first piece of the deterministic orchestration engine — a new internal `aidlc-orchestrate next` command. It reads your workflow state and the compiled stage graph and prints exactly one typed "directive" (JSON) describing the single next move, mutating nothing. This is groundwork only: the engine stands beside the prose orchestrator and nothing in the workflow calls it yet, so your `/aidlc` runs are completely unchanged. No upgrade action required.

* New internal command `bun .claude/tools/aidlc-orchestrate.ts next [--project-dir <dir>] [--scope <scope>] [--stage <slug>] [--phase <name>]` prints one validated directive to stdout and exits. It is read-only — it never writes state, never asks questions, and never spawns agents. Scope resolves by precedence: an existing state file's scope wins, then `--scope`, then `AWS_AIDLC_DEFAULT_SCOPE`, then the default. Read-only flags (`--status`/`--help`/`--doctor`/`--version`) and the mutually-exclusive `--stage`+`--phase` combination map to terminal directives. The companion `report` subcommand is reserved and returns a clear not-implemented message for now.

## [0.5.7] - 2026-06-02

Pre-registers the five swarm-lifecycle audit events as reserved registry rows ahead of the swarm executor. This is a paperwork-only change: the event names are now valid (the audit CLI accepts a `SWARM_*` event and the registry, headings, and docs all know about them) but nothing emits them yet — the emitters are wired with `aidlc-swarm.ts` in a later release. No behaviour change; no upgrade action required.

* New reserved audit events `SWARM_STARTED`, `SWARM_UNIT_CONVERGED`, `SWARM_UNIT_FAILED`, `SWARM_BATON_RETURNED`, and `SWARM_COMPLETED` are now accepted by `bun .claude/tools/aidlc-audit.ts append <EVENT>`; they have no emitters yet (Reserved rows), so they will not appear in any workflow's `audit.md` until the swarm executor ships.
* Audit registry count moves from 61 to 66 events (17 to 18 categories); the `tests/unit/t28-audit-event-sync.sh` count pin and the `audit-format.md` / `12-state-machine.md` / `09-state-and-audit.md` taxonomy tables are bumped in lockstep.

## [0.5.6] - 2026-06-02

Relocates the shipped framework from `aidlc-claude-code/` to `dist/claude/` (history-preserving move). The shipped directory is still `.claude` (with the dot) — only the source-repo wrapper changed. **Upgrade action:** the install command is now `cp -r dist/claude/.claude/ your-project/.claude/` (was `cp -r aidlc-claude-code/.claude/ your-project/.claude/`); update any scripts or docs that referenced the old path. No change to the framework's runtime behaviour.

* The distributable now lives at `dist/claude/.claude/`; copy it in with `cp -r dist/claude/.claude/ your-project/.claude/`.
* The `isFrameworkDistributionPath` guard (which refuses to scaffold a learnt sensor manifest into the framework tree) now recognises the relocated `dist/claude/.claude/sensors` path; a new `t112-learnings-distribution-guard.sh` pins it.
* Removed the stale `dist/` entry from `.gitignore` so the relocated framework is tracked (it guarded build output the repo never produced).

## [0.5.5] - 2026-06-01

Bumps the shipped framework's default orchestrator model from Opus 4.7 to Opus 4.8 (`us.anthropic.claude-opus-4-8`), still run at the 1M-context variant (`opus[1m]`) via AWS Bedrock. No upgrade action required if you use the shipped `.claude/settings.json`; if you pin the model in your own `.claude/settings.local.json`, update `ANTHROPIC_DEFAULT_OPUS_MODEL` to pick up 4.8. Requires Bedrock model access for `us.anthropic.claude-opus-4-8`.

* `ANTHROPIC_DEFAULT_OPUS_MODEL` in the shipped `.claude/settings.json` is now `us.anthropic.claude-opus-4-8` (was `...-4-7`); the Sonnet and Haiku defaults are unchanged.
* Getting-started env-var table and the shipped `CLAUDE.md` Bedrock prerequisite updated to name Opus 4.8.

## [0.5.4] - 2026-06-01

Removed the silently-ignored `allowedTools` frontmatter field from all 11 agents. Agents intentionally inherit the full session toolset and are restricted only by `disallowedTools: Task`; adding an optional `tools:` allowlist is the documented way to narrow an agent (which drops inherited MCP access unless `mcp__<server>__<tool>` ids are listed). No upgrade action required.

* The `allowedTools` field is removed across the 11 agent files, and the docs are reframed to the inherit-all model.
* Agent files now carry an inline note documenting inherit-all / `tools:`-to-restrict / `disallowedTools: Task`.
* The t04 frontmatter guard is inverted to assert the ignored field stays absent.

## [0.5.3] - 2026-06-01

MCP servers are now declared once in a shipped registry and inherited by every agent. A new `aidlc-claude-code/.mcp.json` declares five public MCP servers — `context7` (HTTP, third-party; auth via `${CONTEXT7_API_KEY}` env passthrough) and four AWS servers run through `uvx` (`aws-mcp`, `aws-pricing`, `aws-iac`, `aws-serverless`) that authenticate with your standard AWS credential chain. Declared servers are provisioned to the Claude Code session, and subagents inherit all session MCP tools by default — so there is no per-agent grant step: the developer and aws-platform agents reach the servers they need by inheritance. (An agent that must be *prevented* from a server is narrowed via its `tools:` allowlist with fully-qualified `mcp__<server>__<tool>` ids; that is a separate concern this release does not exercise.) A new guard test pins the registry shape and the inheritance invariant — no agent carries a bare `mcp__<server>` grant token, which would be a no-op. No committed credentials: the registry carries only env-var placeholders. **Prerequisite:** the four AWS-backed servers require an AWS account with IAM credentials available to your shell; `context7` requires `CONTEXT7_API_KEY` in your environment. Servers you have no credentials for are simply unavailable — they do not block the framework. No upgrade action required.

* `aidlc-claude-code/.mcp.json` (new) — the shared MCP server registry. Declares `context7` (HTTP endpoint, `${CONTEXT7_API_KEY}` header) and `aws-mcp` / `aws-pricing` / `aws-iac` / `aws-serverless` (each launched via `uvx`). Credentials flow through environment passthrough only; no keys are committed.
* `tests/unit/t110-mcp-server-grants.sh` (new, 32 assertions) — guard test pinning the registry contract and the inheritance access model: `.mcp.json` is valid JSON and declares exactly the five expected servers as the sole top-level key (with `threat-composer-ai` deferred); each server's config shape is usable (context7 `type: http` + url + key header; each aws-* `command: uvx` + the expected `<pkg>@latest` first arg, aws-mcp carrying `AWS_REGION=us-east-1`); no committed secrets (credential-position values are `${VAR}` placeholders, no literal-key shapes); and no agent carries a bare `mcp__<server>` grant token while every fully-qualified `mcp__<server>__<tool>` entry names a declared server (access is by inheritance, not per-agent grants). Deterministic, bun-only (no `jq`).
* `aidlc-claude-code/.claude/CLAUDE.md` — documents the MCP registry, the inheritance model, and the AWS-account / `CONTEXT7_API_KEY` prerequisite.
* User-facing docs: a new "MCP Servers (optional)" setup section in `docs/guide/01-getting-started.md`, an "MCP servers are shared, not per-agent" note in `docs/guide/05-agents.md`, a full "MCP Servers" architecture section (registry schema, provisioning→inheritance, why there is no per-agent grant) in `docs/reference/14-claude-features.md`, an inheritance pointer in `docs/harness-engineering/03-adding-an-agent.md`, and an "MCP server" glossary entry.
* `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.5.2 → 0.5.3.

## [0.5.2] - 2026-05-31

Three read-only session skills become typeable: `/aidlc-session-cost`, `/aidlc-replay`, and `/aidlc-outcomes-pack`. Each pulls every count — stage outcomes, per-phase rollup, memory entries, sensor firings, learnings, duration — from `aidlc-runtime.ts summary --json` (shipped in 0.5.1) rather than counting by reading files. They are classified `read-only`: none advances the workflow stage pointer and none emits an audit event. `/aidlc-session-cost` and `/aidlc-replay` print to the terminal only; `/aidlc-outcomes-pack` is the only one that writes a file (`OUTCOMES.md`). The previous design's `characters ÷ 4` token estimate is dropped, not ported — token guesswork from file sizes is gone. No upgrade action required; the new skills appear in the `/` skill picker on next session.

* `aidlc-claude-code/.claude/skills/aidlc-session-cost/SKILL.md` (new) — read-only cost view; renders the `summary --json` fields verbatim, prints no token estimate, writes no file.
* `aidlc-claude-code/.claude/skills/aidlc-replay/SKILL.md` (new) — read-only session narrative; counts from `summary --json`, prose from `audit.md` + artefacts; renders to the terminal, writes no file.
* `aidlc-claude-code/.claude/skills/aidlc-outcomes-pack/SKILL.md` (new) — read-only handover doc; counts from `summary --json`, content from artefacts + delivered code; writes `OUTCOMES.md` (the only session skill that writes a file).
* `tests/feature/t107-session-skills-readonly.sh` (new) — asserts frontmatter (`name` / `user-invocable` / `classification: read-only`), `summary --json` sourcing, no retired token heuristic, no audit/state-advance, and that only outcomes-pack writes a file.
* `aidlc-claude-code/.claude/CLAUDE.md` — documents the three session skills under AI-DLC Structure.
* `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.5.1 → 0.5.2.

## [0.5.1] - 2026-05-31

`aidlc-runtime.ts` gains a `summary` subcommand that prints deterministic aggregates over `runtime-graph.json` — stage/phase outcome tallies, memory-entry counts by category, sensor 4-state tallies, learnings captured, and workflow duration. This is the first step of the session-tooling recomposition: the read-only session skills (session-cost, replay, outcomes-pack — landing in a later release) will consume the `--json` shape so every number they render comes from the data plane, not from LLM-side prose counting. Read-only; no audit emit; no behavioural change to any existing surface. No upgrade action required.

* `aidlc-claude-code/.claude/tools/aidlc-runtime.ts` — new `summary [--json]` subcommand. Reads `runtime-graph.json`, flattens `instances[]` per stage, and tallies stage outcomes (approved/failed/pending), per-phase rollups, memory entries by canonical heading, sensor results (passed/failed/budget-override/incomplete), and `learnings_captured`. `duration_minutes` spans first start to latest completed (null on pending-only workflows). Missing `runtime-graph.json` exits 1. Human-readable render by default; machine shape behind `--json`.
* `tests/feature/t106-runtime-summary.sh` (new) — behavioural contract for `summary`: outcome aggregation, phase rollup, memory tallies, duration computation, `--json` determinism, and the missing-graph exit-1 case.
* `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.5.0 → 0.5.1.

## [0.5.0] - 2026-05-31

**The framework now learns from you, checks the work automatically, and is reshapeable without writing code.** Two things change for anyone running `/aidlc`: every approval gate now offers to capture what you corrected so the same correction is never needed twice, and deterministic checks (linter, type-check, required document sections, upstream coverage) fire automatically as agents write — an advisory second opinion you never have to ask for. The larger change is for harness engineers: stages, agents, scopes, rules, and sensors are all editable declarative files now, so you can reshape how AI-DLC behaves for your team by editing Markdown and JSON — no TypeScript. A new Harness Engineer Guide documents exactly that. Under the hood, this is the control-plane / data-plane cut: one compile at workflow start resolves rules and sensors per stage, and a runtime graph mirrors each run. This release also carries a **BREAKING** rename — every framework file now has an `aidlc-` prefix and the rules directory is flat (the `.claude/practices/` folder is gone). This entry consolidates the `0.4.1` → `0.4.13` patches; those headings stay below for historical reference.

**Upgrade.** Re-copy `aidlc-claude-code/.claude/` over your project's `.claude/`. Framework files now carry an `aidlc-` prefix and the rules directory is flat — re-target any customisations from `.claude/practices/` or `.claude/rules/aidlc/guardrails/` to `.claude/rules/aidlc-<scope>.md`, and rename hand-authored hooks that pin the old unprefixed hook filenames. The state template is unchanged from v0.4.0 (v7), so existing workspaces stay schema-compatible. A workspace mid-workflow with overlay customisations you can't easily re-target archives and re-inits per the pre-1.0 no-migration policy:

    mv aidlc-docs aidlc-docs-v04-archive && /aidlc --init --force --scope <scope>

**For everyone running `/aidlc`**

* **Gates now capture what you teach them.** Between a stage finishing and you approving it, the framework surfaces what the agent noticed during the stage — interpretations it had to make, places it deviated, tradeoffs it weighed — and asks "anything to add for next time?" You tick what is worth keeping and pick one of four headings; the framework saves it as a standing rule so the correction carries into the next workflow. Most stages surface nothing, which is healthy — the prompt only has substance when something genuinely came up. See [Rules and the Learning Loop](docs/guide/08-rules-and-the-learning-loop.md).
* **Automatic checks on every file write.** Four deterministic sensors — a linter, a type-checker, a required-sections check, and an upstream-coverage check — now run by themselves whenever an agent writes a stage's output. They are advisory: a finding leaves a note in the audit log pointing at exactly what is missing, but it never blocks your gate. The first time one fires in a workspace, a one-line banner points you at the guide.
* **`/aidlc --doctor --rule-drift`** flags where your team or project rules have drifted from the framework defaults — it quotes the conflicting default inline so you can review it. Advisory; it never fails the health check.
* **Architecture choices now get a written trade-off.** When a design decision has more than one viable approach, the design stage lays out Option A / Option B with reversibility and a recommendation tied to your non-functional requirements, then records the rejected alternatives in the ADR.
* **Richer post-compaction recovery.** A fresh session after a compaction can reconstruct more of where a workflow was, by reading the artifact tree, each stage's observation diary, the audit log, the state docs, and the new runtime graph.

**For harness engineers — reshape AI-DLC without code**

* **A new [Harness Engineer Guide](docs/harness-engineering/00-overview.md)** (`docs/harness-engineering/`, 8 chapters) is the headline. It walks through every change you can make by editing declarative files rather than TypeScript: the anatomy of a stage, adding a stage, adding an agent, defining a scope, authoring rules, authoring sensors, and giving agents team knowledge.
* **Rules are flat, layered Markdown you can read and edit.** `.claude/rules/aidlc-{org,team,project}.md` plus a file per phase. Scope comes from the filename — no `scope:` field. Resolution is **strict-additive**: every applicable rule from org → team → project → phase reaches the agent, nothing is silently overridden. The old `enforcement:` / `overrides:` keywords are gone; conflicts are caught when a rule is written, not hidden at runtime.
* **Sensors are authorable, and stages choose which ones fire.** A sensor is a small Markdown manifest under `.claude/sensors/` describing a check and how to run it. It says nothing about which stages use it — a stage imports the sensors it wants through a `sensors:` list in its frontmatter. Author a manifest, add its id to a stage, and the check rides along on that stage's file writes. The four shipped sensors are the worked examples.
* **The learning loop can wire a sensor in for you.** When a captured learning is "this stage should always run check X," the framework scaffolds the sensor manifest and adds it to that stage's `sensors:` import in one step.
* **Stages, agents, and scopes stay declarative.** A stage is a Markdown file with a frontmatter contract (what it consumes, produces, and which agent leads it); an agent is a persona file; a scope is an entry in `scope-mapping.json` deciding which of the 32 stages run for a kind of work. Editing any of them is a data change, documented end-to-end in the new guide.

**For developers — under the hood**

* **Control plane.** `aidlc-graph.ts compile` walks `.claude/rules/` and `.claude/sensors/` at workflow start, resolves the five-layer chain per stage, and bakes `rules_in_context` + `sensors_applicable` into every node of `stage-graph.json`. Runs under `withAuditLock` with atomic temp-rename writes. The `enforcement:` / `overrides:` keywords are removed; admission-time conflict checks (practices-discovery, the learning gate) replace runtime override resolution.
* **Data plane.** A new tool, `bun .claude/tools/aidlc-runtime.ts` (`compile` / `read`, plus `fragment-fork` / `fragment-merge` for parallel Construction Bolts), materialises a per-workflow `runtime-graph.json` by walking `audit.md` + per-stage `memory.md`. A PostToolUse hook recompiles it deterministically after every gate/transition write.
* **Sensor dispatch.** `bun .claude/tools/aidlc-sensor.ts` (`list` / `describe` / `fire`) routes to the four per-sensor scripts; the `aidlc-sensor-fire.ts` PostToolUse hook reads the active stage's `sensors_applicable` and fires the matching sensors on Write/Edit.
* **The learning gate is a tool.** `bun .claude/tools/aidlc-learnings.ts` (`surface` / `persist`) reads a stage's `memory.md`, emits candidates for the orchestrator's AskUserQuestion, and writes confirmed learnings to `.claude/rules/aidlc-{project,team}-learnings.md` — plus the two-write sensor bind — inside one `withAuditLock`.
* **Two new framework hooks (7 → 9):** `aidlc-sensor-fire.ts` and `aidlc-runtime-compile.ts`.
* **Test coverage for the learning-gate call seam.** `t86` now also pins the `SKILL.md` Stage-Advancement wiring that makes the orchestrator actually invoke `aidlc-learnings.ts surface` + `persist` at a gate (TEST_RUN_MODE-guarded), plus the Test-Run-block skip declaration — closing the gap where the tool (`t97`/`t99`) and the §13 prose (`t86`) could both pass while the orchestrator never called the gate.
* **Audit taxonomy 55 → 61 events.** Five sensor slots pre-registered, `MEMORY_EMPTY` for silent-diary detection, four `SENSOR_*` emitters wired, `RULE_LEARNED` + `SENSOR_PROPOSED` for the learning gate, and `GUARDRAIL_LOADED` for the doctor coverage row. The dead guardrail-*learning* subsystem (`GUARDRAIL_TRIGGERED` / `GUARDRAIL_LEARNED`, `aidlc-guardrail.ts`) was retired, netting 61. If you grepped audit logs for the two retired events, those rows are no longer emitted.
* **BREAKING — `aidlc-` filename prefix + flat rules layout + practices folder removed.** Every framework-shipped file under `.claude/` (tools, hooks, agents, knowledge directories) carries an `aidlc-` prefix. `.claude/rules/aidlc/{guardrails,phases}/` flattens to `.claude/rules/aidlc-{org,team,project,phase-<phase>}.md`; `.claude/practices/` is removed (team config now lives in `.claude/rules/aidlc-team.md`). `aidlc-knowledge/` becomes `knowledge/` with `aidlc-<role>-agent/` and `aidlc-shared/` subdirectories.
* **Documentation + install.** Docs are split three ways by reader — User Guide, Harness Engineer Guide, Developer Reference — all linked from the README. Install switched to Claude Code's native installer, Getting Started gains a full AWS Bedrock Setup section, and the shipped `.claude/settings.json` now sets `AWS_REGION`.
* `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.4.13 → 0.5.0.

## [0.4.13] - 2026-05-30

Makes the documentation surface public-GitHub-ready and integrates the shipped v0.5.0 chapters into a coherent book. The docs are now split by reader into three guides — a **User Guide** (build software with AIDLC), a new **Harness Engineer Guide** (reshape how AIDLC behaves through configuration — stages, agents, scopes, rules, sensors, knowledge — without writing code), and the **Developer Reference** (change the AIDLC codebase itself). The Developer Reference is renumbered along conceptual dependency — Plane Architecture moves to the front as the lens, Sensor and Rule chapters sit paired after the agent/hook mechanics, and Runtime Graph follows the State Machine. The stability-policy chapter folds its rename=major/addition=minor rule into the artifact-vocabulary chapter. The User Guide gains v0.5.0 coverage: the Rules and the Learning Loop chapter (with a worked example), user-facing Sensors, the three new CLI tools, a planes orientation, and the runtime-graph artifact. The README header is rewritten and now links all three guides. The first time a Sensor fires in a workspace, a one-line banner points you at the loop chapter. A per-page coherence pass across all three guides reconciled the docs with the shipped v0.5.0 code — agent support matrices, hook counts, stage-count and audit-event totals, the §13 Learnings Ritual / Phase Boundary Verification split, sensor `matches` and prefix semantics, and the scope/stage tables now match the graph and tools. The dead guardrail-learning subsystem is retired in the same pass (audit taxonomy drops to 61 events). No upgrade action required.

* The first time a Sensor fires in a workspace, the `aidlc-sensor-fire` hook prints a one-line first-fire banner (pointing at the Rules and the Learning Loop guide chapter) and drops a `.first-fired` marker so it shows once, not on every fire.
* `docs/reference/` chapters are renumbered: Plane Architecture is now `02`, Sensor System `07`, Rule System `08`, Runtime Graph `13`; `09-testing.md` and `12-state-machine.md` keep their numbers. If you bookmarked reference chapters by number, re-check the links.
* `docs/guide/08-guardrails.md` is renamed to `docs/guide/08-rules-and-the-learning-loop.md` and rewritten for the v0.5.0 strict-additive rule model (org → team → project → phase → stage). The dead `org-guardrails.md` / `project-guardrails.md` / `overrides:` / `enforcement:` model is gone from the guide.
* New `docs/harness-engineering/` **Harness Engineer Guide** (8 chapters) documents reshaping AIDLC through configuration rather than code — anatomy of a stage (surfacing the stage-definition schema), adding a stage, adding an agent, scopes, rules and the learning loop, sensors, and team knowledge. Each chapter links down to the authoritative Developer Reference chapter. The `docs/guide/12-customization.md` "Extending AI-DLC" section now points into this guide, and the README Documentation table lists all three reader guides.
* The stability-policy chapter (`docs/reference/15-stability-policy.md`) is removed; all cross-references are updated.
* The dead guardrail-learning subsystem is retired: the `GUARDRAIL_TRIGGERED` and `GUARDRAIL_LEARNED` audit events, the `aidlc-guardrail.ts` tool, and the stage-protocol §12 governance flow are removed (superseded by the live §13 Learnings Ritual). The audit taxonomy drops from 63 to **61 events**. The separate live `GUARDRAIL_LOADED` doctor event is unaffected, and the word "guardrail" still denotes a Rule throughout the docs. If you grepped audit logs for `GUARDRAIL_TRIGGERED` / `GUARDRAIL_LEARNED`, those rows are no longer emitted.
* Documentation now consistently reports 9 framework hooks (was 7 — adds `aidlc-sensor-fire` and `aidlc-runtime-compile`) and the 61-event audit taxonomy.
* The shipped `.claude/settings.json` now sets `AWS_REGION` (`us-east-1`) — Bedrock requires it and Claude Code does not read it from `~/.aws`. If your Bedrock region isn't `us-east-1`, override `AWS_REGION` in `.claude/settings.local.json` (the example file gains a commented `AWS_REGION`/`AWS_PROFILE` pair). Getting Started gains a full **AWS Bedrock Setup** section (model-access form, IAM policy, credential options, region override, and the `claude` sign-in wizard), linking the AWS quick-setup guide. Install instructions switched to Claude Code's native installer (`curl … claude.ai/install.sh | bash` / `irm … claude.ai/install.ps1 | iex`), with separate Windows PowerShell and CMD blocks.
* `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.4.12 → 0.4.13.

## [0.4.12] - 2026-05-30

Application Design now prompts an explicit architecture trade-off block whenever a design choice has more than one viable approach. The `application-design` stage's Step 5 (decisions.md guidance) gains an "Architecture options" sub-section: present Option A / Option B with pros, cons, and reversibility, give a recommendation tied to NFRs, let the team choose at the gate, then record the chosen option plus an **Alternatives Rejected** section in the ADR. Single-option choices state why and skip the block. No behavioural change to tooling — this is additive stage-authoring guidance that aligns the stage body with the inception phase rule's ADR requirement (Context, Decision, Consequences, Alternatives Rejected). No upgrade action required.

* `aidlc-claude-code/.claude/skills/aidlc/stages/inception/application-design.md` — added the "Architecture options (when >1 viable approach)" sub-section to Step 5, using the field name **Alternatives Rejected** to match `aidlc-phase-inception.md`.
* `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.4.11 → 0.4.12.

## [0.4.11] - 2026-05-29

Closes the management-plane half of the control/data-plane redesign. `/aidlc --doctor` gains two new advisory rows that observe rule/sensor state without changing how rules concatenate at runtime. No new flags — doctor stays single-purpose; both rows render quietly when there's nothing to surface. No new audit event types: this wires the emitter for the reserved `GUARDRAIL_LOADED` event, so the v0.5.0 audit count stays at 63.

* `/aidlc --doctor` now reports **Rule drift**: it surfaces team/project (and team/project-learnings) rule files whose `##` headings overlap a populated heading in `aidlc-org.md`, quoting the org sentence inline so you can review for contradiction. The row is advisory — it never fails the health check or blocks a workflow. The semantic contradiction verdict is the orchestrator's at observation time, not doctor's; doctor surfaces the candidate, you (or the orchestrator) judge it.
* `/aidlc --doctor` now reports **Paired sensor coverage**: `Paired sensor coverage: P/(M-X) guardrails paired (X feedforward-only)`, where the denominator counts guardrails that need a sensor (M-X) and the numerator counts those whose named sensor resolves (P). For each rule carrying `pairing: <sensor-id>`, doctor asserts the named sensor exists in at least one stage's resolved sensor set; `pairing: feedforward-only` rules count separately. This is a file-existence check, not a semantic one — it confirms the binding resolves, not that the sensor fits the rule.
* The doctor paired-coverage row now emits the reserved `GUARDRAIL_LOADED` audit event when it resolves the guardrail set. No new event type; the audit registry count is unchanged.

No action needed on upgrade. If you script against `/aidlc --doctor` exit codes, note both new rows are advisory and never change the exit status.

## [0.4.10] - 2026-05-29

The headline learning gate: a new `aidlc-learnings.ts` tool implementing the §13 Learnings Ritual as tool-as-actor (replaces the prior LLM-as-actor §13 prose; the "steering loop" is renamed to the "learning loop" throughout). Between a gated stage's completion verification and its approval, the orchestrator runs `aidlc-learnings.ts surface --slug <slug>`; the tool reads the stage's `memory.md` (via the new `parseMemoryEntries` helper), surfaces each non-blank entry under Interpretations / Deviations / Tradeoffs verbatim as a candidate plus a read-only "parked open questions" list, and emits a structured JSON candidate set. The orchestrator renders AskUserQuestion; the user ticks candidates to keep and may type free-text additions, picking which of the four headings each belongs under — **the heading pick is the user's only classification, and the destination is derived from it, not picked.** Before any write, the orchestrator runs a single-line section-level admission conflict check against `aidlc-org.md`'s matching section; a contradicting entry is rejected with the org sentence quoted inline and the user revises, skips, or escalates (no override path). Conflict-clear selections are persisted via `aidlc-learnings.ts persist`, which writes dated rolling entries to the two-surface `.claude/rules/aidlc-project-learnings.md` (default) and `aidlc-team-learnings.md` files — a separate surface from the practices files, never `## Corrections` and never the practices-discovery topical sections. A one-click "promote scope" affordance widens a candidate from project to team; there is no org-learnings file and no widen-to-org path. All writes go through one `withAuditLock` with a decide-inside-lock transaction and content-presence idempotency (a `<!-- cid:<slug>:<id> -->` marker per written line) so a crashed run recovers without double-appending. Audit count grows 61 → **63**: `RULE_LEARNED` and `SENSOR_PROPOSED`.

When a learning is a sensor-binding addition, the same locked transaction does the pull-authoring two-write install: it scaffolds a project-tier `<project>/.claude/sensors/aidlc-<id>.md` manifest (with a `matches:` capability glob) AND atomically appends the new id to the originating stage's `sensors:` frontmatter list. The sensor binds and fires from the next workflow's compile — the never-edits-stage-files rule is lifted for sensor-binding frontmatter edits only (the immutable `## Steps` / `## Sensors` / `## Learn` body is untouched; stage files are now framework-and-loop-edited, documented in CLAUDE.md). `SENSOR_PROPOSED` records the manifest path, the bound stage(s) (`Destinations`), and `source: orchestrator | user_addition`.

This also closes the `runtime-graph.json sensor_firings[]` work carried since the runtime-graph compile shipped: `aidlc-runtime.ts compile()` now walks `SENSOR_FIRED` / `SENSOR_PASSED` / `SENSOR_FAILED` / `SENSOR_BUDGET_OVERRIDE` rows in each stage's window, pairs by 8-hex `fire_id` correlator (positional pairing breaks under the 4-sensors-per-Write fan-out), and populates `sensor_firings[]` on every `RuntimeStage` and `BoltInstance`. Orphan FIRED rows are `result: "incomplete"` — immediately in a closed stage window, or after a deterministic 60s cutoff (computed from the max audit timestamp, no wall-clock) in an open window. The same compile pass wires `learnings_captured.{from_orchestrator, from_user_addition}` from the new audit rows (the previously reserved slot). `SensorFiring` gains `fire_id` and widens `result` to `passed | failed | budget-override | incomplete`.

Skipped in TEST_RUN_MODE: the gate ritual surfaces no candidates and persists nothing.

**Deferred / named (not built here):** `RuntimeStage.consumes[]` (a dispatcher perf win) is deferred; the SIGKILL/uncaught-SIGTERM lock-leak in `withAuditLock` is deferred to the mtime-lock-reap (the lock-acquire-failure stderr now names the lock path and manual remedy); a migration helper for v0.4.x forks that customised sensor manifests with `applies_to:` is deferred to a dedicated fork-upgrade task; edit-inferred learning candidates from artefact diffs (§13 "Source 3") are deferred.

**Pre-registration:** the two events are added directly to `VALID_EVENT_TYPES`, so no `t28` count-collision; the doctor change only flips the already-reserved `GUARDRAIL_LOADED` cell to its emitter (count stays 63).

- `aidlc-claude-code/.claude/tools/aidlc-learnings.ts` (new) — `surface` + `persist` subcommands. `surface` reads `memory.md` (via `parseMemoryEntries`), partitions candidates vs parked open questions, emits structured JSON (no AskUserQuestion field names). `persist` routes learnings by scope to `aidlc-{project,team}-learnings.md` (dated entries tagged by heading, cid-marker idempotency), does the two-write sensor bind (project-tier manifest + originating stage `sensors:` frontmatter), and emits `RULE_LEARNED` / `SENSOR_PROPOSED` — all inside one `withAuditLock` (decide-inside-lock). Framework-distribution sensor paths are rejected. Imports `appendAuditEntryUnlocked` from `aidlc-audit.ts`.
- `aidlc-claude-code/.claude/tools/aidlc-lib.ts` — new `parseMemoryEntries` (one-entry-per-counted-line; `parseMemoryEntries(raw).length === parseMemoryHeadings(raw).total` for any input). `parseMemoryHeadings` unchanged.
- `aidlc-claude-code/.claude/tools/aidlc-runtime.ts` — `SensorFiring` gains `fire_id` + widens `result` to the 4-state enum; `sensor_firings[]` populator on parent `RuntimeStage` and `BoltInstance` (fire_id pairing, baseline_ts orphan cutoff); `learnings_captured` populator (`from_orchestrator` / `from_user_addition`, null on non-approved).
- `aidlc-claude-code/.claude/tools/aidlc-audit.ts` — `VALID_EVENT_TYPES` += `RULE_LEARNED`, `SENSOR_PROPOSED` (after `MEMORY_EMPTY`); `EVENT_HEADINGS` += the two.
- `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.4.9 → 0.4.10.
- `aidlc-claude-code/.gitignore` — added `aidlc-docs/.aidlc-learnings/` so the `<slug>-selections.json` replay artefact is not committed.
- `aidlc-claude-code/.claude/skills/aidlc/SKILL.md` — `## Stage Advancement` gains the §13 learnings-gate call between completion verification and the approval gate.
- `aidlc-claude-code/.claude/skills/aidlc/stage-protocol.md` — §13 rewritten tool-as-actor: two-surface learnings routing, BUILT admission conflict-check, sensor two-write bind, dropped the `applies_to` / `## Corrections` / "use `Edit`" model, renamed steering loop → learning loop.
- `aidlc-claude-code/.claude/CLAUDE.md` — tool-list bullet for `aidlc-learnings.ts`; documents the new stage-frontmatter edit boundary (stage files are framework-and-loop-edited, not framework-only).
- `aidlc-claude-code/.claude/knowledge/aidlc-shared/audit-format.md` + `docs/reference/12-state-machine.md` — event count 61 → 63 + the two new backticked event rows; "Steering loop" → "Learning loop".
- `docs/reference/16-sensor-system.md` — filled the "Gate-ritual handoff" section; corrected the scaffold target to project-tier; dropped the `applies_to` fossil prose.
- `docs/reference/17-rule-system.md` — corrected the `:86` learnings-routing bullet to the two-surface model; cross-referenced the memory gate as the live admission-conflict-check implementer.
- `tests/unit/t97-learnings-primitives.sh` (new, 32 tests), `tests/feature/t98-sensor-firings-populator.sh` (new, 16 tests), `tests/integration/t99-learnings-gate-flow.sh` (new, 16 tests), `tests/fixtures/v05-mr12-learnings/`; `tests/unit/t28-audit-event-sync.sh` count pin 61 → 63; `tests/smoke/t86-stage-protocol-section-13.sh` §13 routing-vocabulary updated to the new model; `tests/feature/t96-runtime-instances-compile.sh` populated-array assertions; `tests/README.md` + `docs/reference/09-testing.md` registered the three new tests.
```

## [0.4.9] - 2026-05-28

Closes the per-Bolt fork/merge triad with its third leg. v0.4.0 shipped state-fork + audit-fork; this release adds runtime-graph fragment-fork + fragment-merge so parallel Construction Bolts each get a coherent `runtime-graph.json` entry post-merge. The orchestration sits in `aidlc-bolt.ts` `start --worktree` (after audit-fork, before the success-JSON) and `complete --merge` (after audit-merge, before the success-JSON), mirroring the existing fork/merge dance. The load-bearing piece is a `compile()` extension that populates `RuntimeStage.instances[]` for any Construction-phase stage whose `[started_at, completed_at OR now)` window contains ≥ 2 distinct `Bolt slug` values from `STATE_FORKED` rows; single-Bolt stages stay single-instance per the schema's optional `instances?` reservation. Audit count stays at **61** — no new event types; the fragment lifecycle rides on the existing BOLT_STARTED + STATE_FORKED + AUDIT_FORKED (fork) and BOLT_COMPLETED + STATE_MERGED + AUDIT_MERGED (merge) boundaries.

The fragment file lives at `<worktree>/aidlc-docs/runtime-graph.json` (gitignored, mirrors main). It's substrate-only in v0.5.0 — no v0.5.0 reader; v0.6.0's `--resume` is the consumer. fragment-fork's source-absent fallback (brownfield projects with no main runtime-graph.json yet) writes an empty graph anchored to the worktree's state cursor and emits `source_present: false` on stdout. fragment-merge is idempotent: re-runs after a successful merge or against a Bolt whose fragment-fork step failed exit cleanly with `status: "fragment-absent"`. Defense-in-depth removal pairs explicit fragment-merge during `complete --merge` with the implicit `git worktree remove` invoked by `aidlc-worktree merge` / `discard` — same pattern state-merge uses on the state side.

**Three forward-notes:**

* **`instances[].sensor_firings[]` per-Bolt attribution deferred.** This release introduces the per-Bolt nesting via `BoltInstance[]`, which means a later compile patch must populate BOTH the parent stage's `sensor_firings[]` AND each `BoltInstance.sensor_firings[]`. The parent rule is straightforward (per-stage filter by Timestamp window); the per-instance rule needs an attribution mechanism, likely Output-path under the Bolt's worktree path. This release leaves both empty arrays in lockstep so the next consumer sees a uniform substrate.
* **`instances[].memory_entries` + `memory_breakdown` deferred to per-stage memory.md lifecycle.** Per-Bolt memory.md doesn't exist yet; the per-stage memory.md lifecycle ships that shape in a later release. Every BoltInstance currently emits both fields as `null` (matches the v0.4.0 backfill rule — null = no per-Bolt memory.md history).
* **Defense-in-depth fragment removal is documented but not relied on.** The worktree fragment is removed by `aidlc-runtime fragment-merge` during `complete --merge` AND transitively by `git worktree remove` during `aidlc-worktree merge` / `discard`. The pair mirrors how state-merge + `git worktree remove` already pair on the state side. If fragment-merge fails after audit-merge succeeds, the unusual `BOLT_COMPLETED → STATE_MERGED → AUDIT_MERGED → BOLT_FAILED (Reason: fragment-merge-failed)` audit signature is the recovery surface; subsequent compile against main produces a coherent runtime-graph (the BOLT_FAILED at this position scores the instance `"approved"` because STATE_MERGED is already on record).

**Doc-drift correction (`docs/reference/19-runtime-graph.md` §10):** the prior wording said fork fires on `BOLT_FORKED` and merge on `AUDIT_MERGED`. `BOLT_FORKED` was a forward-reference doc-drift (not in `VALID_EVENT_TYPES`); §10 now reads "closed in v0.5.0 by `fragment-fork` (no new audit event; rides on STATE_FORKED + AUDIT_FORKED) and `fragment-merge` (no new audit event; rides on STATE_MERGED + AUDIT_MERGED)". §4 also gains a `failed` row covering the parent-stage rollup path; §7 retires the "deferred" framing for parallel-Bolt mid-flight recovery; new §11 documents the full fragment lifecycle including failure modes.

* `aidlc-claude-code/.claude/tools/aidlc-runtime.ts` — added `fragment-fork` (~50 lines) and `fragment-merge` (~25 lines) subcommand handlers; refactored `writeEmptyGraph` to take an optional `{ acquireLock?: boolean }` opts arg (default `true` preserves compile's existing call-sites; fragment-fork's source-absent path passes `false` for its worktree-local write); extended `compile()` with the `BoltInstance[]` populator (~70 lines) — walks `STATE_FORKED` / `STATE_MERGED` / `BOLT_FAILED` audit rows in each Construction-phase stage's window, groups by slug, alphabetical-by-slug ordering, parent-stage null-out + L10 rollup; extended `main()` with explicit `--project-dir <path>` pre-strip mirroring `aidlc-state.ts` / `aidlc-audit.ts` (without it, `spawnSibling`'s `--project-dir <pd>` first-arg protocol would silently break fragment-fork from `aidlc-bolt.ts`); updated help text to list both new subcommands. New imports: `worktreePath`, `validateBoltSlug` from `./aidlc-lib.ts`; `writeFileSync`, `unlinkSync` from `fs`; `createHash` from `crypto`.
* `aidlc-claude-code/.claude/tools/aidlc-bolt.ts` — widened `spawnSibling`'s `toolName` union to include `"aidlc-runtime.ts"`; inserted `fragment-fork` wiring in `handleStart` after audit-fork's failure-block close (~22 lines); inserted `fragment-merge` wiring in `handleComplete` after audit-merge's failure-block close (~22 lines); extended success-JSON's `forked` / `merged` arrays to include `RUNTIME_GRAPH_FORKED` / `RUNTIME_GRAPH_MERGED` informational tokens (NOT new audit event names — those tokens are output-JSON markers consumed by test fixtures and orchestrator-introspection code); updated file-header comment block to mention the runtime-graph leg of the fork/merge triad.
* `aidlc-claude-code/.claude/tools/aidlc-version.ts` — bumped 0.4.8 → 0.4.9.
* `docs/reference/19-runtime-graph.md` — §4 gains a `failed` row for the parent-stage rollup path; §7 "Parallel-Bolt mid-flight recovery deferred" rewritten to reflect closure; §8 CLI surface lists the two new subcommands; §10 corrects the `BOLT_FORKED` doc-drift; new §11 "Fragment lifecycle" documents fork → evolve → merge → defense-in-depth removal → failure modes.
* `aidlc-claude-code/.claude/CLAUDE.md` — new tool-list bullet under `aidlc-runtime.ts`: `fragment-fork` / `fragment-merge` subcommands manage the per-Bolt runtime-graph fragment lifecycle, invoked by `aidlc-bolt.ts start --worktree` / `complete --merge`. Mirrors the audit-fork / state-fork pattern. No new audit events.
* `aidlc-claude-code/.claude/skills/aidlc/SKILL.md` — Step 1 + Step 6 audit-trail expectations updated. Step 1 (fork side) now mentions the third leg of the fork triad (`aidlc-runtime.ts fragment-fork --slug <slug>` byte-copies main `runtime-graph.json` to the worktree fragment after `aidlc-audit audit-fork`; no audit emit — the fragment lifecycle rides on STATE_FORKED + AUDIT_FORKED). Step 6 (merge side) keeps the audit row order on success as `BOLT_COMPLETED → STATE_MERGED → AUDIT_MERGED`; a parenthetical now notes that after AUDIT_MERGED the runtime-graph fragment is removed and the post-Bash hook recompiles main runtime-graph with `instances[]` for the merged slug.
* `tests/unit/t96-runtime-fragment-primitives.sh` (new, 14 cases) — fragment-fork / fragment-merge primitive coverage: happy paths, source-absent fallback, one-shot guard, worktree-missing guard, slug validation (missing flag + regex rejection), fragment-merge idempotency, `--help` listing, unknown subcommand error path, `--project-dir` plumbing.
* `tests/feature/t96-runtime-instances-compile.sh` (new, 10 cases) — compile extension coverage: single-Bolt → no instances[]; 2/3-Bolt parallel → instances[]; outcome rollup (all approved → approved, any failed → failed, pending mix → pending); alphabetical-by-slug ordering with shuffled audit timestamps; determinism (re-compile byte-equivalent); contract placeholders (`sensor_firings: []`, `memory_entries: null`, `memory_breakdown: null` on every BoltInstance).
* `tests/worktree/t12-bolt-runtime-graph-fork.sh` (new, 9 cases) — three-scenario worktree-tier coverage: (a) single-Bolt round-trip; (b) 3-Bolt parallel batch with deterministic alphabetical merge ordering regardless of user complete order; (c) abort-discard leaves no orphan fragments + manual `aidlc-worktree discard` defense-in-depth fallback.
* `tests/integration/t49-bolt-sensor-failures.sh` (new, 8 cases) — end-to-end real-tool flow: 3-Bolt parallel batch with synthesized SENSOR_FAILED in pay's worktree (sensors are advisory; SENSOR_FAILED ≠ Bolt failure); Bolt failure rollup; idempotent re-merge; lock-acquire failure ordering; soft-gap closure for fragment-merge-fails-after-audit-merge-succeeds (the unusual `BOLT_COMPLETED → STATE_MERGED → AUDIT_MERGED → BOLT_FAILED` partial-success audit signature); determinism under failure mix.
* `tests/fixtures/v05-mr11-bolt-runtime-graph/` (new) — 3 static audit fixtures for the t96 feature test: 3-bolts-parallel (canonical example), 3-bolts-1-failed (rollup test), single-bolt (no-instances test).
* `tests/README.md` + `docs/reference/09-testing.md` — registered the four new tests.

## [0.4.8] - 2026-05-27

Lands the headline data-plane integration: a `Write|Edit` PostToolUse hook (`aidlc-sensor-fire.ts`) that reads the compile-resolved `sensors_applicable` array off the active stage's `stage-graph.json` node and spawns the dispatcher per matching `matches:` glob. Authoring direction is invisible past compile — the hook reads a list regardless of how the resolver populated it ("the dispatcher does no resolution walks at runtime. Stage entry reads `sensors_applicable` off the node — already looked up, already attached."). After this release ships, customers using AIDLC for actual TS/JS coding work see eslint + tsc integrated automatically into Construction; Inception/Operation markdown writes get `required-sections` + `upstream-coverage` advisory checks. Workflow continues advisory — no gate veto, no blocking; the ralph driver upgrades this to blocking semantics for Construction-phase sensors in a later release.

G1.5 lock-in: the two unscoped framework manifests gain `matches: "**/aidlc-docs/**"` (the leading `**/` consumes any absolute-path prefix Claude Code passes via `tool_input.file_path`; the trailing `/**` matches every artifact under `aidlc-docs/` at any depth, including flat `aidlc-docs/foo.md` paths). Manifest declares its own scope; no hook-side default. The compile snapshots `matches` from each manifest into every importing stage's `sensors_applicable[].matches`, so the hook reads cached glob strings without re-opening manifests at fire time. The `**/aidlc-docs/**` form (vs the draft `**/aidlc-docs/**/*.md`) is load-bearing: the dispatcher uses a home-grown `globToRegex` that translates `**` → `.*` and rejects flat-aidlc-docs paths under the `*.md`-suffixed form, even though `Bun.Glob` (the hook's matcher) accepts both. Two glob engines, one common form.

**Three forward-notes:**

* **`runtime-graph.json` `sensor_firings[]` population deferred.** This release ships the surface that emits `SENSOR_*` audit rows via the dispatcher; `aidlc-runtime.ts:319` continues to hardcode `sensor_firings: []` on every compiled `RuntimeStage`. A later gate ritual is the first consumer that walks `audit.md` since each stage's `started_at` to populate the array.
* **First-fire banner deferred.** A one-line stderr banner on first invocation against a workspace pointing users at `docs/guide/<NN>-learning-loop.md` is envisioned. The doc ships later; banner with no link is dead weight, so it lands together.
* **`sensor-fire.last` mtime semantics for the doctor.** The hook touches `aidlc-docs/.aidlc-hooks-health/sensor-fire.last` after passing the input + recursion + audit-existence + state + test-run-mode guards but BEFORE the active-stage and graph-read guards. This means "fresh heartbeat + zero `SENSOR_FIRED` rows" can mean either (a) healthy hook firing on a stage with empty `sensors_applicable` like `workspace-scaffold`, or (b) hook crash mid-dispatch. The doctor must distinguish by reading `Current Stage` from state, looking up the stage's `sensors_applicable` length, and only flagging when (`length > 0` AND `gap > 24h` AND intervening Write/Edit audit rows exist). The runtime-compile equivalence "post-heartbeat ≡ reached dispatch" does NOT carry to this hook because Steps 9-10 add additional post-heartbeat early-exits.

* `aidlc-claude-code/.claude/hooks/aidlc-sensor-fire.ts` (new) — PostToolUse Write|Edit hook. Twelve-step flow: `resolveProjectDirFromHook` → TTY guard → stdin parse → file_path extract → `.aidlc-sensors/` recursion guard (dual-separator) → audit-existence guard → state-existence + Test Run Mode skip (touches `sensor-fire.skipped` per G2) → heartbeat → active-stage lookup via `getField(state, "Current Stage")` → `loadGraph().find(s => s.slug === currentStage)` typed-wrapper read → per-entry `Bun.Glob` filter + `spawnSync("bun", [...aidlc-sensor.ts, fire, <id>, --stage, <slug>, --output-path, <path>], {timeout: 90_000})` → `process.exit(0)` advisory always. Hook-level failures (timeout SIGTERM/ETIMEDOUT, true spawn failure, non-zero dispatcher exit) recorded via `recordHookDrop(...)`; sensor verdicts surface through the dispatcher's audit rows and detail files — hook never propagates exit codes (G5).
* `aidlc-claude-code/.claude/sensors/aidlc-required-sections.md` — added `matches: "**/aidlc-docs/**"` to frontmatter (G1.5).
* `aidlc-claude-code/.claude/sensors/aidlc-upstream-coverage.md` — same as above (G1.5).
* `aidlc-claude-code/.claude/tools/data/stage-graph.json` (regenerated) — `bun .claude/tools/aidlc-graph.ts compile` snapshots the new `matches` field from each manifest into every importing stage's `sensors_applicable[].matches`. Ships the post-regen JSON; `compile --check` exits 0 on a clean tree.
* `aidlc-claude-code/.claude/skills/aidlc/SKILL.md` — sibling entry under the existing `Write|Edit` matcher block. Both hooks fire per Write/Edit, in registration order, independent of each other (`audit-logger.ts` first emits ARTIFACT_CREATED/UPDATED, then `sensor-fire.ts` reads `sensors_applicable` and spawns the dispatcher per match).
* `aidlc-claude-code/.claude/CLAUDE.md` — new tool-list bullet under § Hooks: `aidlc-sensor-fire.ts — PostToolUse hook on Write/Edit. Reads compile-resolved sensors_applicable for the active stage; spawns aidlc-sensor.ts fire per match. Advisory; never blocks.`
* `tests/unit/t94-sensor-fire-hook-unit.sh` (new, 18 tests) — per-guard unit coverage for the 12-step flow.
* `tests/feature/t95-sensor-fire-hook-feature.sh` (new, 19 tests) — end-to-end behaviour against a mock dispatcher: argv shape, single + multi-entry fire, multi-glob filtering at the stage level (TS write fires only code sensors at a Construction stage; markdown write at the same stage fires only doc-shape sensors), subprocess timeout / exit-1 / exit-code contract, heartbeat coexistence, skipped-file accumulation.
* `tests/fixtures/v05-mr10-sensor-fire/` (new) — PostToolUse JSON payload fixtures + a Test Run Mode state.md fixture.
* `tests/README.md`, `docs/reference/09-testing.md` — registry rows for t94 + t95.

The integration-tier slot (`tests/integration/t49-sensor-environmental.sh`) is reserved but not landed here — the end-to-end test exercises the real dispatcher and ships once that lands, so the integration test runs against the genuine CLI rather than a stub. The t94 + t95 tiers fully cover the hook's contract surface against a mock dispatcher in the meantime.

## [0.4.7] - 2026-05-27

Ships the first emitter of the four `SENSOR_*` audit events pre-registered earlier. The `aidlc-sensor.ts` dispatcher CLI is a thin routing surface (Q4/Q5): it looks up a manifest by id, generates an 8-hex Fire id correlator, emits `SENSOR_FIRED` under one `withAuditLock`, spawns the per-sensor script (no lock held), and emits the paired terminal row (`SENSOR_PASSED` | `SENSOR_FAILED` | `SENSOR_BUDGET_OVERRIDE`) under a second `withAuditLock`. Two lock windows split across the spawn solve the spawn-window starvation that one-lock-across-spawn would create — long-running sensors (60s tsc) no longer pin the audit lock during their work.

Four framework sensors become real tool calls via their own scripts (`aidlc-sensor-required-sections.ts`, `aidlc-sensor-upstream-coverage.ts`, `aidlc-sensor-linter.ts`, `aidlc-sensor-type-check.ts`). Pull authoring at the manifest level: each manifest's `command:` declares HOW the sensor runs; the dispatcher routes; the per-sensor script does the work. Forks adding custom sensors write a manifest plus a script — no framework-code change.

**Three known limitations are documented forward:**

* **`sensor_firings[]` population deferred.** `aidlc-runtime.ts:319` continues to hardcode `sensor_firings: []` on every compiled `RuntimeStage`. This release emits the audit rows for the four `SENSOR_*` events; a later gate ritual is the first consumer that walks `audit.md` since each stage's `started_at` to populate the array. That consumer must also tolerate orphan FIRED rows (FIRED with no terminal pair, e.g., from a process crash between lock window A and lock window B); pair them as `result: "incomplete"` rather than discarding the FIRED. The current `SensorFiring.result` enum is `"passed" | "failed"`; a later release extends it to cover the four audit-emit terminals: `"passed" | "failed" | "budget-override" | "incomplete"`. The `SensorFiring` interface also gains a `fire_id: string` field so audit-walking can pair by Fire id (load-bearing under the parallel 4-sensors-per-Write fan-out — terminal rows interleave by spawn duration, not by FIRED order; positional pairing breaks). The dispatcher emits `Fire id` on every row.
* **Lock-orphan recovery covers `process.exit()` paths only.** The on-exit handler installed by `withAuditLock` reaps the lock dir on Node's normal exit (including `process.exit()`). SIGKILL — and external SIGTERM with no signal handler — does NOT trigger Node's exit event; the lock dir survives, and the next fire burns the 5s mkdir-EEXIST retry budget before throwing. There is no mtime-based lock-reap in `aidlc-lib.ts` today. Mtime-reap deferred to v0.6.0.
* **Type-check sensor attributes diagnostics to the file tsc reports, not the file that introduced the regression.** The wrapper post-filters tsc's whole-project output to errors whose `file` field equals or contains `--file-path`. Cross-file regressions (e.g., a removed export breaking the consumer) report against the consumer file in tsc's output, not against the file that triggered the change. The sensor emits PASS for `<path>` while the consumer file shows the error; the regression surfaces only when the consumer is later edited and re-fired against. Multi-file attribution model deferred to v0.6.0+.
* **Audit event taxonomy is closed by design.** `aidlc-audit.ts` carries a closed `VALID_EVENT_TYPES` Set (61 events) and throws on unknown types. Forks adding custom sensors plug into the existing four `SENSOR_*` event slots (FIRED, PASSED, FAILED, BUDGET_OVERRIDE); fork-defined event names (e.g., `SENSOR_BENCHMARK_REGRESSED`) are NOT v0.5.0 scope. The closure is intentional: open-ended event names break audit grep regexes, doctor-row counts, downstream parser determinism, and the t28 audit-event-sync drift gate. Pull authoring at the manifest/stage level (forks add their own manifest + script and import via `sensors:`) is fully supported within the closed taxonomy. Custom-event-name extensibility revisited in v0.6.0+ if fork pressure surfaces.

* `aidlc-claude-code/.claude/tools/aidlc-sensor.ts` (new) — dispatcher CLI. Subcommands: `list`, `describe <id>`, `fire <id> --stage <slug> --output-path <path>`. Validates inputs + resolves graph + generates Fire id pre-lock (so a malformed stage file fails validation and exits 1 without ever opening a lock — orphan-FIRED prevention). Truth table for outcome decision (branch-a-precedes-branch-0 ordering: timeout-SIGTERM → BUDGET_OVERRIDE before true-spawn-failure → script-error). Detail-file path keyed on Fire id makes collisions a 1-in-4-billion event by construction; `wx`-flag write + `renameSync` retained as defence-in-depth. CLI exits non-zero only on dispatcher invocation errors; sensor outcomes are advisory and always emit a paired terminal row. Subprocess primitive is `node:child_process spawnSync` (matches `aidlc-bolt.ts:84` precedent — Bun's sync return shape doesn't expose `signal === "SIGTERM"` cleanly).
* `aidlc-claude-code/.claude/tools/aidlc-sensor-required-sections.ts` (new) — counts distinct `^## ` headings (dedupe by exact text); pass = (count ≥ 2). Stdout JSON carries `pass`, `h2_count`, `headings`, and `findings_count` (the script computes `max(0, 2 - h2_count)` itself; dispatcher reads the field generically). Dispatcher is sensor-id-agnostic for findings derivation — adding a new framework sensor in v0.6.0 doesn't require a switch arm in the dispatcher.
* `aidlc-claude-code/.claude/tools/aidlc-sensor-upstream-coverage.ts` (new) — case-insensitive word-boundary check for each artifact in `--consumes`, accepting either `\b<slug>\b` literal or `[[<slug>]]` wikilink form. Pass = every consumed artifact appears at least once. `--consumes` empty or absent collapses to `pass=true reason="no upstream"`.
* `aidlc-claude-code/.claude/tools/aidlc-sensor-linter.ts` (new) — wraps `bunx eslint --format json --max-warnings=-1`. Probes config via `bunx eslint --print-config <path>`; on no-config or eslint-unavailable, exits 127 (dispatcher → PASSED Note=tool-unavailable per branch b). `pass = errorCount === 0` only — warnings DO NOT FAIL (real configs ship `no-unused-vars: warn`; warning-as-failure would spam SENSOR_FAILED on every Write under the fan-out).
* `aidlc-claude-code/.claude/tools/aidlc-sensor-type-check.ts` (new) — wraps `bunx tsc --project <tsconfig> --incremental --tsBuildInfoFile <under aidlc-docs/.aidlc-sensors/> --noEmit --pretty false`. `--project` honours the project's actual settings (bare-file `tsc foo.ts` ignores tsconfig and falls back to ES3 defaults — checked-but-meaningless on any real project). Continuation lines (indented related-info) appended to the previous error's `message` rather than dropped (Findings count would otherwise under-report).
* `aidlc-claude-code/.claude/sensors/aidlc-{linter,required-sections,type-check,upstream-coverage}.md` — `command:` rewritten to point at the per-sensor script (e.g., `bun .claude/tools/aidlc-sensor-linter.ts`). The dispatcher reads the manifest, extracts the .ts basename, and resolves it sibling-style to itself (mirrors `aidlc-bolt.ts:84`).
* `aidlc-claude-code/.claude/knowledge/aidlc-shared/audit-format.md` — four SENSOR_* Emitter cells flipped from `Reserved` to `` `tools/aidlc-sensor.ts` `fire` ``. Required Fields columns extended with `Fire id` correlator + `Output path`; `SENSOR_FAILED` row's detail-path string updated `aidlc-docs/.sensors/<stage>/<sensor>-<iso>.md` → `aidlc-docs/.aidlc-sensors/<stage>/<sensor>-<fire-id>.md`. Optional `Note` field on `SENSOR_PASSED` documented in a footnote (`tool-unavailable` | `script-error: <reason>`).
* `docs/reference/12-state-machine.md` — same four cell flips at lines 313-316 with backticked path-token format (t48's forward-check regex). Detail-path string updated `<iso>` → `<fire-id>`.
* `aidlc-claude-code/.gitignore` — `aidlc-docs/.aidlc-sensors/` added to runtime-files block.
* `aidlc-claude-code/.claude/CLAUDE.md` — `aidlc-docs/.aidlc-sensors/` added to user-facing gitignore list; new tool-bullet under Tools: "`aidlc-sensor.ts` — fired by the PostToolUse hook on Write/Edit matches; also human-callable for debugging."
* `tests/feature/t92-sensor-fire.sh` (new) — full fire round-trip per sensor; argv parsing; audit-row shape; detail-file path; concurrent fire (5 parallel + happy-path / lock-released-across-spawn variants); budget override; tool-unavailable PASS path; script-error fall-through; lock-orphan recovery for graceful exit.
* `tests/feature/t93-sensor-list-describe.sh` (new) — read-only subcommand contract.
* `tests/feature/t55-test-suite-drift.sh` — path-drift sweep extended: `aidlc-docs/.aidlc-sensors/` is blessed; legacy `aidlc-docs/.sensors/` rejected.
* `tests/README.md`, `docs/reference/09-testing.md` — registry rows for t92 and t93.

## [0.4.6] - 2026-05-27

Ships the data-plane substrate for the steering loop: a per-workflow `runtime-graph.json` accumulator that fires deterministically on every approval gate. `runtime-graph.json` is the data-plane mirror of `stage-graph.json`, populated by walking `audit.md` + per-stage `memory.md` files. Three downstream consumers now have a stable surface to read from: the gate ritual (silent-diary-skip detection via `memory_entries` count), the doctor (diary-discipline metric via `MEMORY_EMPTY` rows), and v0.10.0's cross-workflow observer (pattern detection across many runs).

The compile is hook-driven, never LLM-tool-coupled. A new PostToolUse hook on the `Bash` matcher fires on every `bun aidlc-(state|jump|bolt|utility).ts` invocation that appends a transition-class audit row (`GATE_APPROVED | STAGE_STARTED | AUDIT_MERGED | WORKFLOW_COMPLETED`); the orchestrator's actual subprocess invocation is the deterministic anchor, regardless of what the LLM does next. `WORKFLOW_COMPLETED` is in the transition set so the final-stage approve fires the compile (otherwise `handleCompleteWorkflow`'s 5-row emit would never record the final stage as approved). v0.4.0-backfill: stages without a `memory.md` file get `memory_entries: null` and emit no `MEMORY_EMPTY` row, distinguishing "never tracked" from "tracked and empty" so v0.4.x users don't see an audit storm on first post-upgrade workflow.

* `aidlc-claude-code/.claude/tools/aidlc-runtime.ts` (new) — `compile` walks audit + memory.md to materialise `aidlc-docs/runtime-graph.json`; chronological `STAGE_STARTED ↔ STAGE_COMPLETED` pairing yields `outcome: "approved" | "pending" | "failed"` per row; emits `MEMORY_EMPTY` for zero-entry approved stages (per audit-format §13). `read <stage-slug>` prints one row for debug. Both subcommands respect `CLAUDE_PROJECT_DIR`.
* `aidlc-claude-code/.claude/tools/aidlc-lib.ts` — new `parseMemoryHeadings()` export. Pure function. Counts non-blank lines under each of the four canonical §13 H2 headings (`Interpretations`, `Deviations`, `Tradeoffs`, `Open questions`); BOM/CRLF tolerant; fence-aware via toggle walker; never throws on missing headings. Single source of truth shared by compile, gate ritual, and lifecycle.
* `aidlc-claude-code/.claude/hooks/aidlc-runtime-compile.ts` (new) — PostToolUse Bash-matcher hook. Filter pipeline: TTY guard → JSON parse → command regex → audit-existence guard → heartbeat → tail-read last 3 audit blocks → transition-event regex → Test-Run extract → `spawnSync` dispatch. `aidlc-runtime.ts` excluded from the matcher (recursion guard at command level); `MEMORY_EMPTY` excluded from the event regex (recursion guard at content level). Heartbeat at `aidlc-docs/.aidlc-hooks-health/runtime-compile.last` for `--doctor` silent-failure detection.
* `aidlc-claude-code/.claude/skills/aidlc/SKILL.md` — new PostToolUse `Bash` matcher block registers the runtime-compile hook alongside the existing `Write|Edit` (audit-logger) and `TaskUpdate` (sync-statusline) matchers.
* `aidlc-claude-code/.claude/knowledge/aidlc-shared/audit-format.md` — `MEMORY_EMPTY` Emitter cell flips from `Reserved` to `tools/aidlc-runtime.ts compile`. Five sensor-event rows (`SENSOR_FIRED`, `SENSOR_PASSED`, `SENSOR_FAILED`, `SENSOR_BUDGET_OVERRIDE`, `GUARDRAIL_LOADED`) stay reserved.
* `aidlc-claude-code/.claude/CLAUDE.md` — gitignore list extended with `aidlc-docs/runtime-graph.json` (mirrors v0.4.0 `.aidlc-recovery.md` precedent — generated artefact, not intended for commit).
* `docs/reference/19-runtime-graph.md` (new) — chapter documenting schema (locked TS interface), compile lifecycle, outcome enum + chronological pairing rule (re-jump handling), `MEMORY_EMPTY` semantics + idempotency, v0.4.0 backfill rule, snapshot + suffix-replay recovery model with freshness caveat for pending rows, parallel-Bolt mid-flight recovery deferred.
* `docs/reference/18-plane-architecture.md` — cross-link added from the data-plane substrate paragraph to chapter 19.
* `tests/unit/t88-parse-memory-headings.sh` (new, 18 tests) — pure-function coverage for `parseMemoryHeadings()`.
* `tests/feature/t90-runtime-compile.sh` (new, 29 tests) — `aidlc-runtime.ts compile` behavioural contract, including `--init --force` re-init filtering (latest WORKFLOW_STARTED wins, prior-workflow rows discarded), ISO-second collision deterministic ordering, the approved+non-zero negative case, MEMORY_EMPTY re-emit suppression (exactly one per (slug, gate-completion) tuple), re-approve still-empty fresh-emit, and schema nullability on instance-bearing parent rows.
* `tests/feature/t91-runtime-compile-hook.sh` (new, 13 tests) — PostToolUse Bash hook filter + dispatch contract, including the load-bearing `WORKFLOW_COMPLETED` terminal-workflow case, gate-start dispatch via `STAGE_AWAITING_APPROVAL`, and the explicit-reject recursion guard for composite Bash commands.
* `tests/integration/t48-runtime-graph-end-to-end.sh` (new, 10 tests) — drives a real `bugfix` workflow through one approval gate, asserts pre/post-approve row transitions + idempotency.
* `tests/README.md`, `docs/reference/09-testing.md` — registry rows for the four new tests.
```

## [0.4.5] - 2026-05-25

Both halves of the control-plane substrate now flip to pull authoring: each stage explicitly imports its sensors via a `sensors:` field in frontmatter, and the rule resolver's `paths:` glob mechanism on phase rules disappears in favour of the stage's existing `phase:` field as the pull import for its matching phase rule. Both halves now mirror how stages already declare `consumes`, `requires_stage`, `produces` — frontmatter declares; the resolver looks up. Org/team/project rules continue to attach to every stage automatically by filename. There is now one authoring direction across all stage relationships: stage frontmatter is the single source of truth for what fires when this stage runs.

`aidlc-graph compile` now also walks `.claude/sensors/`, indexes manifests by id, looks up each stage's imports, and bakes a per-stage `sensors_applicable` array into every node of `data/stage-graph.json`. Manifest schema simplifies: `applies_to:` is gone (scope lives on the stage side); `matches` moves to a top-level capability filter consumed by the PostToolUse hook at fire time. The rule resolver's glob machinery (`globToRegex`, synthesised concrete-path matching) deletes entirely.

The 32 stage YAML files gain explicit `sensors:` import lists. The `## Sensors` body compartments are rewritten from "bulleted inventory" to per-stage prose — naming what the stage produces, what each imported sensor checks on those outputs, what failure looks like. The list-of-sensors duplication goes (frontmatter owns that); the per-stage narrative stays. Stage YAML files become framework-and-loop-edited: the learning-loop ritual will append new sensor ids to a stage's `sensors:` list during the gate, where push authoring would have just edited a manifest. Stage files were never strictly framework-immutable on disk; pull authoring makes the edit boundary honest. Every stage node now carries the full resolved control-plane view that the dispatcher and PostToolUse hook read directly.

Sensor pull (the new resolver):

* `aidlc-claude-code/.claude/tools/aidlc-sensor-schema.ts` (new) — capability-descriptor schema. No `applies_to`. BOM-tolerant. Cross-checks `id:` against filename. Tolerates unknown keys.
* `aidlc-claude-code/.claude/tools/aidlc-lib.ts` — extends `parseStageFrontmatter` ARRAY_KEYS with `"sensors"` and `emitStageFrontmatter` FIELD_ORDER with `"sensors"`, so the new field round-trips through parse + emit cleanly.
* `aidlc-claude-code/.claude/tools/aidlc-stage-schema.ts` — adds optional `sensors: string[]` field to stage frontmatter.
* `aidlc-claude-code/.claude/tools/aidlc-graph.ts` — `loadSensors()` walker (returns `Map<id, SensorFile>` for O(1) lookup); `resolveSensorsForStage()` (id-lookup with throw-on-unknown); `SensorResolution` type and `GraphStage.sensors_applicable` field. `FIELD_ORDER` extends with `sensors_applicable` after `rules_in_context`. New `AIDLC_SENSORS_DIR` and `AIDLC_STAGES_DIR` env-seams.
* `aidlc-claude-code/.claude/sensors/aidlc-{required-sections,upstream-coverage,linter,type-check}.md` — `applies_to:` and `icon:` removed; `matches` moved to top level on `linter` and `type-check`.
* 32 stage YAML files under `aidlc-claude-code/.claude/skills/aidlc/stages/` — each gains a `sensors:` field with explicit id list. `## Sensors` body compartments rewritten from list-with-bullets to per-stage prose. Heading retained.
* `tests/feature/t89-compile-sensors-applicable.sh` (new) — 22 TAP assertions covering import-lookup, matches-passthrough, schema rejections (null/scalar/empty-string), unknown-id-throw, duplicate-id-throw, id-filename-mismatch, unknown-keys-tolerated (forward-compat), BOM-frontmatter, round-trip determinism, compile-snapshot semantics, and `--check` drift on sensor-manifest edits.
* `tests/feature/t66-graph-library.sh` — 6 new cases (82 → 88) for `sensors_applicable` shape, FIELD_ORDER position, AIDLC_SENSORS_DIR seam, drift, round-trip, `resolveSensorsForStage`.
* `tests/unit/t86-sensor-manifest-schema.sh` — pivots from "applies_to has a base shape" to "applies_to absent" (pull authoring removed it).

Rule pull (the resolver flip):

* `aidlc-claude-code/.claude/tools/aidlc-rule-schema.ts` — drops `paths:` field from `RuleFrontmatter` interface and validator.
* `aidlc-claude-code/.claude/tools/aidlc-graph.ts` — `resolveRulesForStage` simplified to four explicit lookups; `globToRegex` and concrete-path synthesis deleted.
* 4 phase-rule files in `.claude/rules/aidlc-phase-{construction,ideation,inception,operation}.md` — `paths:` frontmatter stripped; prose updated from "activate when working with files in aidlc-docs/X/" to "apply to every stage whose phase: X declaration imports them".
* `tests/feature/t88-compile-rules-in-context.sh` — drops 5 cases exercising the `paths:` mechanic (phase-paths-match, phase-paths-no-match, phase-no-paths, glob-anchor regression). BOM fixture rebuilt with `pairing:` instead of `paths:`. Plan 16 → 11.
* `tests/fixtures/v05-mr7a-rule-resolution/` — three fixture sub-dirs removed (`phase-paths-match`, `phase-paths-no-match`, `phase-no-paths`).

Documentation:

* `docs/reference/16-sensor-system.md` — substantial rewrite for the pull authoring shape. § `applies_to evaluation rules` deleted; new § `How stages import sensors` describes the frontmatter `sensors:` field shape; new § `matches filter` documents the top-level capability filter.
* `docs/reference/17-rule-system.md` — strips `paths:` glob mention; describes `phase:` as the pull import for the matching phase rule (mirrors how `requires_stage` imports upstream stages).
* `docs/reference/18-plane-architecture.md` (new) — control / data / management plane separation chapter. Pulls from the v3 design explainer's networking-discipline framing, the compile-boundary cut, and recovery as emergent property of the data plane. Sits alongside 16 and 17 as the third surface explaining how rules and sensors flow through compile.
* `aidlc-claude-code/.claude/CLAUDE.md` and `aidlc-claude-code/.claude/knowledge/aidlc-shared/rules-reading.md` — Rules + sensors prose aligned with pull authoring.
* `tests/unit/t87-stage-compartment-headers.sh` — unchanged. Both H2s (`## Sensors` + `## Learn`) still ship across all 32 stages; only the body of `## Sensors` rewrites.
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.4.5`.

## [0.4.4] - 2026-05-25

Ships the rule-resolution half of the control-plane substrate. `aidlc-graph compile` now walks `.claude/rules/`, resolves the strict-additive chain (org → team → project → phase, where the phase rule's `paths:` glob matches the stage's synthesised artefact path), and bakes a per-stage `rules_in_context` array into every node of `data/stage-graph.json`. Strict-additive runtime: every applicable rule appears in the chain; nothing drops; the `enforcement:` and `overrides:` keywords are removed from the schema. Conflicts (narrower contradicting broader policy) are rejected at admission gates (practices-discovery, memory gate) by section-level LLM check — not at runtime. Compile now runs under `withAuditLock` with atomic temp-rename writes (`writeFileAtomic`); concurrent invocations serialise and crash mid-write leaves consumers reading the previous compile, never a half-written file. Filename regex permits future `aidlc-{team,project}-learnings.md` surfaces. The compile-output schema change drives the version bump; `data/stage-graph.json` grows about 25% (~+6KB on the 32-stage graph).

* `aidlc-claude-code/.claude/tools/aidlc-rule-schema.ts` (new) — sibling of `aidlc-stage-schema.ts`. Parses and validates rule frontmatter (`paths:` string list + `pairing:` scalar — `feedforward-only` or `aidlc-<sensor-id>` shape). Strips a leading UTF-8 BOM (U+FEFF) before matching the `^---\r?\n` anchor — macOS/Windows editors occasionally save markdown with a BOM; without stripping, the file would parse as frontmatter-less and silently drop `paths:` and `pairing:`. Tolerates unknown keys for forward-compat; throws `<file>: <message>` on schema violations.
* `aidlc-claude-code/.claude/tools/aidlc-graph.ts` — `RuleResolution` and `GraphStage.rules_in_context` interface fields; new `loadRules()` walker (anchored filename regex, deterministic `(scope-priority, filename)` sort, `AIDLC_RULES_DIR` env-seam for fixture isolation); new `resolveRulesForStage()` strict-additive chain builder; zero-dep `**`/`*` glob matcher synthesising `aidlc-docs/<phase>/<slug>/` from each stage. `FIELD_ORDER` extends with `rules_in_context` after `outputs`. `compile` write site wraps in `withAuditLock` + `writeFileAtomic`.
* `aidlc-claude-code/.claude/tools/aidlc-lib.ts` — `listField` and `scalarField` promoted from file-private to exported (rule-schema reuses the zero-dep YAML primitives). New `writeFileAtomic(path, data)` helper — temp + POSIX rename, with cleanup of the temp on write failure. `withAuditLock` is now reentrant within a single process for the same `projectDir` — nested calls bump a depth counter rather than self-deadlocking on the OS-level lock (the prior behaviour burned the 5-second mkdir retry budget before throwing). Cross-process locking is unchanged. The signature is also tightened to forbid `async` callbacks (`fn: () => T extends Promise<unknown> ? never : T`) so a future caller can't pass a Promise-returning function and have the lock release before the work settles.
* `aidlc-claude-code/.claude/tools/data/stage-graph.json` — regenerated. Every stage node grows `rules_in_context`; lengths are 3 (org+team+project) on Initialization stages and Construction stages whose synthesised path doesn't match the phase rule's globs, 4 (org+team+project+phase) elsewhere.
* `tests/fixtures/designer-export/export.json` — regenerated. `aidlc-graph export` propagates `rules_in_context` through `.stages[]`; the byte-equal pin in `t66:879` would otherwise drift.
* `tests/feature/t88-compile-rules-in-context.sh` (new) — 16 TAP assertions across 9 fixture sub-directories under `tests/fixtures/v05-mr7a-rule-resolution/` (org-only, org-team-project, phase-paths-match, phase-paths-no-match, phase-no-paths, all-four, pairing-feedforward-only, zero-rules, bom-frontmatter); covers `--check` drift detection on rule-file edits, round-trip determinism, glob-anchor regression (prefix-only globs don't match concrete paths), schema rejection of invalid `pairing` values, and BOM-prefixed frontmatter parsing.
* `tests/feature/t66-graph-library.sh` — eight new cases (74 → 82 tests): `loadGraph()` carries `rules_in_context` as array; `FIELD_ORDER` places it after `outputs`; canonical-emitter pin proves the field populates from `AIDLC_RULES_DIR`; `compile --check` detects rule-file drift via the env-seam; round-trip stability; concurrency wrap (parallel compiles serialise to a byte-equal serial result); `withAuditLock` reentrancy regression guard (nested same-pd is fast and holds the lock throughout outer scope); exit-handler deregistration regression guard (sequential calls don't accumulate listeners).
* `docs/reference/17-rule-system.md` — chain block at `:42` rewritten from six items to five-layer (`org → team → project → phase → stage`); `enforcement: enforced` and `overrides:` sections deleted in favour of strict-additive runtime + admission-time conflict-rejection prose.
* `aidlc-claude-code/.claude/CLAUDE.md` — Rules bullet rewritten: drops the `enforcement: enforced` + `overrides:` sentence; states the five-layer chain and the strict-additive runtime model directly.
* `aidlc-claude-code/.claude/knowledge/aidlc-shared/rules-reading.md` — opening paragraph rewritten from "three layers" to the five-layer chain; agent-readable runtime content stays consistent with the resolver's emitted shape.
* `tests/README.md` and `docs/reference/09-testing.md` — drift-quartet rows for t88 (new, 16 tests) and t66 count update (74 → 82).
* The doctor conflict-detection flag is renamed `--conflicts` → `--rule-drift`.
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.4.4`.

## [0.4.3] - 2026-05-22

Appends stage-protocol §13 (the Learnings Ritual) and pre-registers its companion audit event `MEMORY_EMPTY`. The ritual is the framework's human steering loop: between every stage's completion message and approval gate, the orchestrator surfaces interpretations / deviations / tradeoffs / open-questions from the per-stage memory.md and proposes promotion targets under `.claude/rules/` or `.claude/sensors/`. §13 will be rewritten to tool-as-actor once the runtime ritual handler ships in `aidlc-learnings.ts`. Audit registry grows 60 → 61 events across 16 → 17 categories; the new `### Steering Loop` category reserves capacity for `MEMORY_EMPTY` (the runtime-graph compile wires the emitter). This release also ships a placeholder `docs/reference/17-rule-system.md` skeleton (filename-derived scope, 5-layer inheritance, `enforcement: enforced` keyword, `overrides:` block schema, `pairing:` field, forward-compat policy) so the resolver and conflict detector read a frozen schema; full usage prose ships later.

* `aidlc-claude-code/.claude/skills/aidlc/stage-protocol.md` — appends `## 13. Learnings Ritual`: per-stage memory.md discipline (four canonical H2 headings — Interpretations / Deviations / Tradeoffs / Open questions), promotion proposals via `AskUserQuestion` before approval gates, three-shape routing (`stages:` / `phase:` / `all_stages:`), and the immutability invariant for stage files. Skipped under `TEST_RUN_MODE`
* `aidlc-claude-code/.claude/tools/aidlc-audit.ts` — `VALID_EVENT_TYPES` and `EVENT_HEADINGS` both gain `MEMORY_EMPTY`; canonical-events comment bumped (60) → (61)
* `aidlc-claude-code/.claude/knowledge/aidlc-shared/audit-format.md` — heading bumped to `## Event Registry (61 events, 17 categories)`; new `### Steering Loop (1 event)` section appended after Sensor Events with `MEMORY_EMPTY` row carrying a bare `Reserved` Emitter cell (matches the no-version-markers convention v0.4.2 set across the registry). `tests/feature/t48-audit-event-emitters.sh`'s line-101 case-insensitive `Reserved` skip preserves green
* `docs/reference/12-state-machine.md` — count-pin and parity-mirror updated to 61 events / 17 categories; new `### Steering loop` registry section
* `docs/reference/17-rule-system.md` (new) — placeholder chapter outlining filename-derived scope, five-layer inheritance, `enforcement: enforced` keyword, `overrides:` block schema, `pairing:` field, forward-compat policy. Tier 2/3 audience tag. Full enforcement semantics ship later
* `tests/unit/t28-audit-event-sync.sh` — assertion bumped from `assert_eq 60` to `assert_eq 61`; pin label updated to "VALID_EVENT_TYPES.size === 61 (v0.5.0)"
* `tests/unit/t81-bolt-plan-override.sh` — three count strings updated 60 → 61 (lines 18, 68, 71-74)
* `tests/smoke/t86-stage-protocol-section-13.sh` (new) — 5-assertion smoke pin: §13 heading present, four canonical memory.md headings present, three routing shapes (stages / phase / all_stages), MEMORY_EMPTY registered in all three sources, immutability invariant subsection present. `tests/README.md` and `docs/reference/09-testing.md` registries updated in lockstep. Coexists with `tests/unit/t86-sensor-manifest-schema.sh` (different tier) per the existing `unit/t06` + `worktree/t06` precedent
* Two further audit events, `RULE_LEARNED` and `SENSOR_PROPOSED`, are forward-noted for the learning gate that ships later; the final v0.5.0 audit count remains 63
* Doc count-pin sweep across 10 surfaces (60 → 61, where present in prose): `README.md`, `docs/guide/{00-introduction, 07-knowledge, 09-state-and-audit, glossary}.md`, `docs/reference/{00-overview, 01-architecture, 06-hooks-and-tools, 07-knowledge-system, 12-state-machine, 15-stability-policy}.md`. The `### 60-event taxonomy` table in `09-state-and-audit.md` becomes `### 61-event taxonomy` and gains a new `Steering Loop | 1 | MEMORY_EMPTY (pre-registered for v0.5.0)` row
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.4.3`.

## [0.4.2] - 2026-05-22

**BREAKING — framework rename + flat rules layout + practices folder removed.** Three structural reorgs ship together. (1) All framework-shipped files in extension-point directories now carry an `aidlc-` filename prefix so users distinguish framework files from their own at a glance — three tools (`aidlc-lib.ts`, `aidlc-stage-schema.ts`, `aidlc-version.ts`), six hooks (the `aidlc-audit-logger.ts` / `aidlc-log-subagent.ts` / `aidlc-session-end.ts` / `aidlc-session-start.ts` / `aidlc-sync-statusline.ts` / `aidlc-validate-state.ts` set), eleven agents (the `aidlc-<role>-agent.md` set), plus the `.claude/aidlc-knowledge/` directory renamed to `.claude/knowledge/` with each per-agent subdirectory gaining the `aidlc-` prefix. (2) `.claude/rules/aidlc/{guardrails,phases}/` flattens to `.claude/rules/aidlc-{org,team,project,phase-<phase>}.md` — three scope-layer files plus four phase-scoped files, all in one flat directory. The team layer (`aidlc-team.md`) is genuinely new — populated by practices-discovery's affirmation gate. (3) `.claude/practices/` is removed entirely; team-authored harness config now lives in the same `.claude/rules/` namespace as guardrails, with a section mapping that folds `## Branching` / `## Testing posture` / `## Deployment cadence` / `## Code style` into `## Way of Working` / `## Testing Posture` / `## Deployment` / `## Code Style`.

Migration: customisations under `.claude/practices/` or `.claude/rules/aidlc/guardrails/` re-target to `.claude/rules/aidlc-<scope>.md`. Hand-authored hooks pinning old hook filenames need rename. Users mid-workflow archive `aidlc-docs/` and re-init per the existing pre-1.0 no-migration policy.

* **Framework filenames carry `aidlc-` prefix** across `tools/`, `hooks/`, and `agents/`. The 20 file renames preserve git history via `git mv`. The shipped `.claude/CLAUDE.md` reflects the new prefix discipline.
* **`aidlc-knowledge/` → `knowledge/`** with per-agent subdirectories renamed `aidlc-<role>-agent/` (11 directories, 55 knowledge files relocate). The `shared/` subdirectory also gains the prefix → `aidlc-shared/` so framework-shipped files stand apart from team-authored ones at a glance; `--init` scaffolds `aidlc-docs/knowledge/aidlc-shared/` to match. `practices-reading.md` renamed to `rules-reading.md`; agent Knowledge Loading entries cite the new filename.
* **Flat rules layout** at `.claude/rules/`: seven files total (`aidlc-org.md`, `aidlc-team.md`, `aidlc-project.md`, `aidlc-phase-construction.md`, `aidlc-phase-ideation.md`, `aidlc-phase-inception.md`, `aidlc-phase-operation.md`). The phase files retain their `paths:` frontmatter; the scope files derive scope from filename pattern.
* **Practices folder removed.** `aidlc-state.ts practices-promote` writes to `.claude/rules/aidlc-team.md` (section-replace × 5: Way of Working / Walking Skeleton / Testing Posture / Deployment / Code Style) and `.claude/rules/aidlc-project.md` (append-under-heading × 2: Mandated / Forbidden). Behavioural changes you'll see: `bun aidlc-state.ts practices-promote` errors mention `aidlc-team.md` / `aidlc-project.md` instead of the old paths; `practices-discovery` stage prose presents the new heading set in the AskUserQuestion options.
* **`bun .claude/tools/aidlc-guardrail.ts`** writes to the flat layout — `--scope project` writes `.claude/rules/aidlc-project.md`; `--scope org` writes `.claude/rules/aidlc-org.md`.
* **Settings + skill hooks** updated. `.claude/settings.json` SessionStart/SessionEnd hooks point at the new prefixed filenames. `.claude/skills/aidlc/SKILL.md` PostToolUse / PreCompact / SubagentStop hook entries match.
* **Stripped release-version markers** from framework code. Comments under `aidlc-claude-code/.claude/` describe what code does, not which release added it. Version content remains in `aidlc-version.ts` and `CHANGELOG.md` because version is their domain. The `Reserved` placeholder cells in `audit-format.md` are now bare `Reserved` tokens; downstream consumers flip the cells to actual emitter paths.
* **Test fixtures + assertions** rewired. `t75-practices-promote.sh` builds the new layout in its fixture and asserts on the new heading set. The `t55-test-suite-drift.sh` extension catches stale `aidlc-knowledge/`, `.claude/practices/`, and `rules/aidlc/` strings if any are reintroduced.

## [0.4.1] - 2026-05-20

Pre-registers the audit taxonomy slots that v0.5.0's deterministic-sensor system will fill. Five new event types appear in the registry with `Reserved` Emitter cells; no emitters ship in this release. Downstream work can now import the new event constants without colliding on the registry's pinned count — `tests/unit/t28-audit-event-sync.sh` would otherwise force serialised access to `VALID_EVENT_TYPES`, `audit-format.md`, and `12-state-machine.md` across the v0.5.0 sensor work. The reserved cells point at the dispatcher (`aidlc-sensor.ts`) which owns the four `SENSOR_*` emissions; `GUARDRAIL_LOADED` is reserved for the paired-coverage doctor row. Audit taxonomy grows 55 → 60 events across 15 → 16 categories. The new Sensor Events category reserves capacity for four Fowler-aligned deterministic sensors (`required-sections`, `upstream-coverage`, `linter`, `type-check`); `weasel-words` is deferred to v0.9.0's LLM-judge sensor mix.

* `aidlc-claude-code/.claude/tools/aidlc-audit.ts` — `VALID_EVENT_TYPES` and `EVENT_HEADINGS` both grow by five new entries: `SENSOR_FIRED`, `SENSOR_PASSED`, `SENSOR_FAILED`, `SENSOR_BUDGET_OVERRIDE`, `GUARDRAIL_LOADED`. The Sensors block carries a pre-registration comment matching the v0.4.0 Merge Dispatch precedent so future maintainers reading the .ts file see the same forward-note discipline as future readers of audit-format.md
* `aidlc-claude-code/.claude/aidlc-knowledge/shared/audit-format.md` — heading bumped to `## Event Registry (60 events, 16 categories)`; new `### Sensor Events (5 events)` section appended after Merge Dispatch with the five rows. `Emitter` cells are `Reserved` for the four `SENSOR_*` events and for `GUARDRAIL_LOADED`. `tests/feature/t48-audit-event-emitters.sh`'s line-101 case-insensitive `Reserved` skip preserves t48 green during the wait for emitters
* `docs/reference/12-state-machine.md` — count-pin and parity-mirror updated. Heading sentence now reads "60 events across 16 categories"; new `### Sensors` registry section appended after Merge dispatch with the same five rows in the chapter's `Event | Emitter | Trigger` shape. v0.4.0's md↔md parity invariant (audit-format.md and 12-state-machine.md ship the same rows) is preserved
* `tests/unit/t28-audit-event-sync.sh` — assertion bumped from `assert_eq 55` to `assert_eq 60`; pin label updated to "VALID_EVENT_TYPES.size === 60 (v0.5.0)"
* Doc count-pin sweep across 11 surfaces: `README.md`, `docs/guide/{00-introduction, 07-knowledge, 09-state-and-audit, glossary}.md`, `docs/reference/{00-overview, 01-architecture, 06-hooks-and-tools, 07-knowledge-system, 12-state-machine, 15-stability-policy}.md`. The `### 60-event taxonomy` table in `09-state-and-audit.md` gains a new `Sensors | 5 | SENSOR_FIRED, SENSOR_PASSED, SENSOR_FAILED, SENSOR_BUDGET_OVERRIDE, GUARDRAIL_LOADED (pre-registered for v0.5.0)` row. `15-stability-policy.md`'s count-pin example updates from `assert_eq 55` to `assert_eq 60`
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.4.1`.

## [0.4.0] - 2026-05-20

Construction worktrees + split-safe state/audit + practices discovery. Construction Bolts now execute in their own git worktree at `.aidlc/worktrees/bolt-<slug>/`, eliminating race conditions on shared state, audit, and working tree across parallel Bolt batches and workshop scenarios. State and audit fork to the worktree on Bolt start and merge back on gate approval, with deterministic conflict resolution.

A new Inception stage `practices-discovery` at slot 2.2 captures team branching strategy, walking-skeleton stance, testing posture, deployment, and code style — affirmed once per project, then read by Construction so worktree dispatch and walking-skeleton sequencing reflect the team's voice rather than scope-hardcoded defaults. State template bumps from v6 to v7 with three real field additions; v6 workspaces archive-and-reinit:

    mv aidlc-docs aidlc-docs-v6-archive && /aidlc --init --force --scope <scope>

* **BREAKING — state template v6 → v7.** Three new fields populated by Construction worktree dispatch and the practices-discovery affirmation gate: `Worktree Path`, `Bolt Refs`, `Practices Affirmed Timestamp`. `/aidlc --doctor` exits non-zero on a v6 state file with archive-and-reinit advice. No migration tooling — see `docs/reference/15-stability-policy.md` for the precedent
* **Construction-phase worktree isolation** — every Bolt runs in its own git worktree at `.aidlc/worktrees/bolt-<slug>/` on branch `bolt-<slug>`. Parallel Bolt batches no longer race on shared state, audit, or working tree. Aborted Bolts' worktrees are preserved by default for inspection; `aidlc-bolt abort --discard` cleans up explicitly. Halt-and-ask AUQs render the worktree path and branch name verbatim
* **New Inception stage `practices-discovery` at slot 2.2** — discovers team branching strategy, walking-skeleton stance, testing posture, deployment patterns, and code style from evidence (brownfield: multi-agent scan of git, configs, code, and reverse-engineering artifacts) or `AskUserQuestion` (greenfield); affirmation gate promotes drafts to `.claude/practices/team.md` and `.claude/rules/aidlc/guardrails/project-guardrails.md`. Inception phase grows from 7 → 8 stages; total 31 → 32
* **`bun .claude/tools/aidlc-worktree.ts`** new subcommands: `create --slug <slug> --base <branch>`, `merge --slug <slug> --target <branch> --strategy <squash|merge|rebase>`, `discard --slug <slug>`, `list`, `verify --event <WORKTREE_*> --slug <slug>`, `info --slug <slug>`. The `info` JSON envelope returns `{slug, path, branch_name, audit_timestamp, merge_held}` — the `merge_held` field powers the multi-failure HOLD-MERGE invariant during halt-and-ask
* **`bun .claude/tools/aidlc-bolt.ts`** new flag-driven branches: `start --worktree --slug <slug>`, `complete --merge --slug <slug>`, `abort --slug <slug> --reason <text> [--discard]`, `hold-merge --slug <slug>`, `release-merge --slug <slug>`, and `dispatch-event --event MERGE_DISPATCH_INVOKED|RETURNED|FALLBACK --slug <slug>`. The `hold-merge`/`release-merge` pair routes the HOLD-MERGE invariant through tooling instead of prose contract; `dispatch-event` wires the three pre-registered `MERGE_DISPATCH_*` events around every pipeline-deploy-agent dispatch
* **`bun .claude/tools/aidlc-state.ts`** new subcommands: `fork --slug <slug>`, `merge --slug <slug>` (per-Bolt state isolation with workflow-level fields untouched + alphabetical-slug tiebreak), `practices-event --type discovered|affirmed|override|empty`, and `practices-promote --team-practices <path> --discovered-rules <path>` (the cross-row write that takes practices-discovery drafts to team harness config)
* **`bun .claude/tools/aidlc-audit.ts`** new subcommands: `audit-fork --slug <slug>`, `audit-merge --slug <slug>`. Per-Bolt audit isolation with SHA-256 prefix-hash sanity check on merge — refuses with `prefix-hash` error if main audit's prefix at the recorded `Fork Boundary` byte offset has been edited or truncated since fork. `AIDLC_AUDIT_LOCK_RETRIES` and `AIDLC_AUDIT_LOCK_RETRY_MS` env-var overrides for the lock budget
* **`/aidlc --doctor`** extends with four new orphan-reconciliation rows that print between the State Version line and the graph-level checks: orphan worktrees (classified as active fork / preserved-by-abort / cleanup-orphan / unmatched), stale `bolt-*` branches (worktree gone but no terminal `WORKTREE_DISCARDED`/`MERGED` audit row), orphan state files (worktree state file with no entry in main's `Bolt Refs`), and orphan audit (three reconciliation surfaces under one label: `AUDIT_FORKED`-without-disk, orphan-delta drift, `PRACTICES_OVERRIDE` Reason discriminator routing)
* **`/aidlc --doctor`** also gains two new advisory rows: practices staleness (90-day threshold against `Practices Affirmed Timestamp`) and `MERGE_DISPATCH` orphan-INVOKED count (pair-matched per slug against terminal `_RETURNED`/`_FALLBACK` rows)
* **Multi-failure halt-and-ask** — when ≥2 Bolts in a parallel batch fail, AUQs render sequentially in slug order; all successful Bolts hold their merge-dispatch via per-Bolt `Merge-Held: true` marker until every failed AUQ resolves. Marker survives session-kill via worktree-state persistence; `aidlc-bolt complete --merge` refuses with `{ok:false, reason:"merge-held", ...}` envelope while held
* **Practices-aware orchestration in SKILL.md** — Construction reads team practices once at start (`extractMarkdownSection` over `team.md → org.md → hardcoded defaults`). Walking-skeleton stance is dynamic from practices; bolt-plan marker conflicts emit `PRACTICES_OVERRIDE` with `Reason: bolt-plan-marker-conflict` (discriminator field on the existing event, not a new event type). Ten agents (architect, aws-platform, compliance, delivery, design, developer, devsecops, operations, product, quality) gained Knowledge Loading entries citing `.claude/practices/`
* **Audit taxonomy 41 → 55 events across 12 → 15 categories.** Seven worktree-lifecycle events (`WORKTREE_CREATED`, `WORKTREE_MERGED`, `WORKTREE_DISCARDED`, `STATE_FORKED`, `STATE_MERGED`, `AUDIT_FORKED`, `AUDIT_MERGED`), four practices events (`PRACTICES_DISCOVERED`, `PRACTICES_AFFIRMED`, `PRACTICES_OVERRIDE`, `PRACTICES_SECTION_EMPTY`), three merge-dispatch events (`MERGE_DISPATCH_INVOKED`, `_RETURNED`, `_FALLBACK`). `tests/unit/t28-audit-event-sync.sh` pins the count
* **Configuration-layers principle** — new section in `docs/reference/01-architecture.md` documents the two-axis routing model (authorship × consumption) for `.claude/` vs `aidlc-docs/`. New `.claude/practices/` namespace with three layers: `org.md` (framework defaults in team voice), `team.md` (this team's affirmed practices, populated by practices-discovery), `project.md` (project-specific overrides). Anchors v0.5.0+ routing decisions
* **New chapter `docs/guide/workshop-mode.md`** — multi-developer manual recipe for the `workshop` scope. Claim semantics ride on `git push` of `bolt-<slug>` to the shared remote (first push wins, late claimants get a non-fast-forward rejection). No new CLI; the manual recipe is the contract until a real workshop dogfood surfaces concrete requirements for an automated `--claim-bolt` utility (deferred)
* **Performance baseline** — `time bun aidlc-worktree.ts create --slug <s> --base main` measured at **520ms median** (range 485–567ms across 6 warm runs; 819ms cold-cache; 30ms bun startup baseline) on a 100MB synthetic fixture (101MB `.git` of `dd if=/dev/urandom` blobs — pathological worst case for `git worktree add` because random data does not compress). Of that, raw `git worktree add` accounts for ~336ms median; the framework adds ~190ms for slug validation, branch existence check, audit emission, and lock acquisition. Slightly above the <500ms target on this adversarial fixture; real repositories with compressible assets will perform better. First baseline of its kind — informative, not a regression. Track in v0.5.0 if customer-facing fixtures push it higher
* **Phase 0 Harness Setup precursor** — practices-discovery is the operational-truth precursor to v0.10.0's Phase 0 Harness Setup, which will own architectural rules via the fitness-contract compiler. Distinct concerns: practices captures the team's voice on how they work; Phase 0 captures the harness engineer's contract on what the project commits to. v0.10.0 plan-time decision resolves the boundary

## [0.3.14] - 2026-05-20

Doctor extensions for the worktree / state-fork / audit-fork / practices surfaces. Six new sequential check rows insert into `aidlc-utility.ts` `handleDoctor()` between the existing state-version block and the graph-level checks (Check 4 internally covers three reconciliation surfaces — orphan AUDIT_FORKED-without-disk, orphan-delta drift, and PRACTICES_OVERRIDE Reason discriminator routing — under one row label). Each check is read-only and pushes onto the same `results` accumulator existing checks use; doctor preserves its single existing `appendAuditEvent("HEALTH_CHECKED")` row at handler exit unchanged. Threshold constants `PRACTICES_STALENESS_DAYS = 90` and `MERGE_DISPATCH_TIMEOUT_SEC = 60` are tagged for v0.5.0+ relocation to `practices/team.md` and per-stage Sensors-compartment binding parameters. Two reconciliation surfaces explicitly deferred to v0.5.0+: orphan `Merge-Held: true` markers (requires net-new doctor capability — walk per-Bolt forked state + parent-batch BOLT_FAILED resolution graph, with workshop-resume false-positive guard per `SKILL.md:735`) and workshop `git ls-remote` stale-claim detection (remote-aware doctor composes with the post-1.0 visual-designer offline-mode story). Both deferrals carry forward-note comments in source pointing at the v0.5.0+ implementer.

* `bun .claude/tools/aidlc-utility.ts doctor` — six new check rows print between "State Version: 7" and "Cycle detection: 0 cycles":
  * `Orphan worktrees: N` — walks `.aidlc/worktrees/bolt-*/`, classifies each as active fork (slug in main `Bolt Refs` → ✓), preserved-by-abort (slug in Bolt Refs + `BOLT_FAILED` row carries `Reason: aborted` — multi-failure AUQ aborted at index k, awaiting `/aidlc --resume`), cleanup-orphan (WORKTREE_MERGED landed or `[merge-succeeded:<sha>]` ERROR_LOGGED tag — directory persists), or unmatched (no audit trail). Reports `0 worktrees observed` with pass=true on a fresh project, a fail-clean guarantee
  * `Stale branches: N` — runs `git branch --list 'bolt-*'`, flags any `bolt-<slug>` branch whose worktree directory is gone but no terminal WORKTREE_DISCARDED / WORKTREE_MERGED audit row landed. Skips silently on non-git-repo paths (smoke / fresh fixtures)
  * `Orphan state files: N` — walks `<wt>/aidlc-docs/aidlc-state.md`, flags any worktree state file whose slug is not in main's `Bolt Refs` and has no WORKTREE_DISCARDED pairing
  * `Orphan audit: N` — three reconciliation surfaces under one row: (a) AUDIT_FORKED-without-disk-state (no `<wt>/aidlc-docs/audit.md` on disk; only fires when no terminal pairing exists, so a successfully-merged-and-cleaned Bolt with AUDIT_MERGED in main does NOT flag), (b) orphan-delta (no matching AUDIT_MERGED, no active fork, no WORKTREE_DISCARDED), (c) PRACTICES_OVERRIDE Reason discriminator routing per `audit-format.md:138` (write-failure-* without follow-up PRACTICES_AFFIRMED → flagged via `Date.parse()` ms comparison so millisecond-precision AFFIRMED satisfies seconds-precision OVERRIDE; bolt-plan-marker-conflict → expected behaviour, not flagged; unknown Reasons → tracked in advisory count for v0.5.0+ reconciliation)
  * `Practices staleness: N days ago` — reads `Practices Affirmed Timestamp` from main state and compares to now. Empty / missing / template-default → informational pass; within 90 days → pass with day count; older → advisory pass=true (does NOT fail exit code); future-dated (clock skew or hand-edit) → advisory pass with explanatory label; invalid ISO 8601 string → fail readable
  * `MERGE_DISPATCH: N orphan INVOKED` — advisory pass=true. Pair-matches per slug: each terminal row (RETURNED or FALLBACK) consumed by at most one preceding INVOKED in chronological order, so two INVOKED + one RETURNED for the same slug correctly reports one orphan. The v0.10.0 cross-workflow observer + ralph driver takes over LLM-dispatch-timeout reconciliation
* `lib.ts` gains four new exports — `findAllEvents(audit, event, slug?)` (multi-match audit-walker; mirrors `findLatestEvent`'s signature; normalises CRLF → LF before splitting on the `\n---\n` block separator so audits authored or edited on Windows parse identically to Unix), `SLUG_TAG_REGEX` (`\[slug=([a-z0-9-]+)\]`), `FORK_EMITTED_TAG_REGEX` (`\[fork-emitted:([^\]]+)\]`), `MERGE_SUCCEEDED_TAG_REGEX` (`\[merge-succeeded:([^\]]+)\]`). Promotes the slug correlation tags from inline literals at `aidlc-worktree.ts:787-792` / `aidlc-audit.ts:301,385` / `aidlc-state.ts:1538` to a single shared definition so v0.5.0+ sensors and v0.8.0 observers reuse one regex
* `aidlc-utility.ts` exports `PRACTICES_STALENESS_DAYS = 90` and `MERGE_DISPATCH_TIMEOUT_SEC = 60`. Both tagged for v0.5.0+ relocation
* `aidlc-bolt.ts` near `handleHoldMerge` carries a forward-note comment naming the orphan `Merge-Held: true` reconciliation deferred to v0.5.0 doctor — walk per-Bolt forked state for held flag, cross-check parent batch's BOLT_FAILED resolution status, flag if all siblings resolved but `release-merge` never ran. Workshop-resume false-positive guard required per `SKILL.md:735`
* New tests: `tests/unit/t83-doctor-orphan-worktree.sh` (16 tests) covers Checks 1, 3, 4, 6 plus regression tests for the review fixes (merged-and-cleaned no-orphan, multi-INVOKED pair-matching, ms-precision PRACTICES_AFFIRMED reconciliation, preserved-by-abort sub-classification, unknown-Reason advisory); `tests/unit/t84-doctor-stale-branch.sh` (5 tests) covers Check 2 across non-git-repo, clean-repo, stale, live, and terminated cases; `tests/unit/t85-doctor-practices-staleness.sh` (6 tests) covers the 90-day threshold + the five corner cases (empty, within, beyond, invalid, missing, future-dated). `tests/unit/t37-utility-doctor-drift.sh` extended 17 → 23 with six new assertions pinning the lib.ts exports' shape contract, the three tag-regex constants' capture groups, both threshold constants' values, `PRACTICES_SECTION_EMPTY` recognition by the audit-walker, and CRLF normalisation of audit content
* `tests/README.md` gains a "Test numbering" subsection documenting the rebase-and-renumber convention — the drift quintet (t55) catches the rename across five sites: file header line 1-3, TAP `plan N`, `tests/README.md` row, `docs/reference/09-testing.md` row, and the README↔09-testing cross-check
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.3.14`

## [0.3.13] - 2026-05-19

Workshop-mode docs. New chapter `docs/guide/workshop-mode.md` documents the multi-developer manual recipe for running the `workshop` scope: each participant clones the shared remote, runs `aidlc-worktree create --slug <slug> --base <per-team-practices>` locally, then publishes the claim by pushing `bolt-<slug>` to origin (first push wins, late claimants get a non-fast-forward rejection). The recipe uses only primitives that already ship today — `aidlc-worktree create/discard`, `aidlc-bolt complete --merge`, plus ordinary `git push` — so no new CLI, audit events, or state changes. The chapter aligns with practices-aware orchestration: walking-skeleton stance, branching strategy, and merge target are all read from the team's affirmed `practices/team.md`, not chosen on the command line. Multi-failure halt-and-ask with `Merge-Held` survivors, batch-level gates, the `MERGE_DISPATCH_*` audit trail, and resume semantics are all documented as the user-facing surface. A future release may automate slug claiming once a real workshop dogfood surfaces a concrete requirement; until then, the recipe is the contract. Linked from `docs/guide/00-introduction.md`'s Guide Map.

* `docs/guide/workshop-mode.md` is the new chapter — claim semantics, facilitator setup, participant flow, 2-developer 3-Bolt worked example, multi-failure halt-and-ask with `aidlc-bolt hold-merge` / `release-merge` enforcement, `MERGE_DISPATCH_*` audit forensics, workshop resume semantics via `aidlc-worktree info --slug`'s `merge_held` field
* `docs/guide/00-introduction.md` Guide Map gains a Workshop Mode row between Worked Examples and Glossary
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.3.13`

## [0.3.12] - 2026-05-19

The SKILL.md Construction-flow rewrite — the most user-facing change of the release. The orchestrator now reads team practices once at Construction start (`extractMarkdownSection` over `team.md → org.md → hardcoded defaults` per `aidlc-knowledge/shared/practices-reading.md`), drives a parallel-batch dispatch model with explicit phase contracts (Phase 0 worktree creation in one assistant message, Phase 1+2 per-Bolt serial Q+A, Phase 3 parallel `Task` invocations pinned via prompt path, Phase 4 batch-level approval gate, Phase 5 N parallel `aidlc-bolt complete --merge` calls), and brackets every pipeline-deploy-agent dispatch with `MERGE_DISPATCH_INVOKED` (pre-call) and either `MERGE_DISPATCH_RETURNED` or `MERGE_DISPATCH_FALLBACK` (post-call) audit rows via the new `aidlc-bolt dispatch-event` subcommand. Walking-skeleton stance is now dynamic — read from `practices/team.md`'s `## Walking Skeleton` section with scope-mapping fallback for unaffirmed teams; bolt-plan-marker-vs-practices conflicts emit `PRACTICES_OVERRIDE` with `Reason: bolt-plan-marker-conflict` (discriminator-field disambiguation, not a new event — t28 stays at 55). Halt-and-ask gains explicit multi-failure semantics: when ≥2 Bolts in a parallel batch fail, AUQs render sequentially in slug order, ALL successful Bolts hold their merge-dispatch via a `Merge-Held: true` per-Bolt-state marker until every failed AUQ resolves. Two new italic carve-outs document the audit-merge prefix-hash mismatch failure mode and the orphan-BOLT_STARTED recovery seam. Ten agents now cite `aidlc-knowledge/shared/practices-reading.md` in their Knowledge Loading sections.

* `bun .claude/tools/aidlc-bolt.ts dispatch-event --event MERGE_DISPATCH_INVOKED --slug <kebab-slug> --practices-excerpt "<text>"` — new subcommand for the orchestrator's pre-call dispatch instrumentation. Audit-of-intent semantic: emit precedes the `Task(pipeline-deploy-agent, ...)` LLM call. Reconciled by doctor via slug + timestamp window (no correlation tag — the LLM call has no disk artifact to sequence against)
* `bun .claude/tools/aidlc-bolt.ts dispatch-event --event MERGE_DISPATCH_RETURNED --slug <slug> --strategy <squash|merge|rebase> --target <branch> --confidence <0-1> --notes "<text>"` — post-call emit on a parsable JSON envelope from pipeline-deploy-agent. Validates `--strategy` enum and `--confidence` range
* `bun .claude/tools/aidlc-bolt.ts dispatch-event --event MERGE_DISPATCH_FALLBACK --slug <slug> --reason <enum> --defaults "<text>"` — post-call emit on timeout, malformed YAML, or low-confidence return; orchestrator proceeds with org.md defaults. Critical observability hook for "we silently used trunk defaults instead of the team's affirmed strategy"
* `bun .claude/tools/aidlc-state.ts practices-event --type empty --field "Section: <heading>" --field "Fallback: <source>"` — new fourth case for the practices-event subcommand. Emits `PRACTICES_SECTION_EMPTY` (advisory only) when the orchestrator's layer-3 fallback fires (both `team.md` and `org.md` were empty for the requested section)
* `bun .claude/tools/aidlc-state.ts practices-event --type override --field "Reason: bolt-plan-marker-conflict" --field "Practices Stance: <stance>" --field "Bolt-Plan Marker: <marker>" --field "Bolt slug: <slug>"` — orchestrator emits `PRACTICES_OVERRIDE` with discriminator field when practices' stance overrides bolt-plan's marker. Coexists with the `Reason: write-failure-*` path under the same event name; t28 stays at 55
* SKILL.md per-Bolt loop: U1 italic preamble reads practices once at Construction start; U2 parallel-batch dispatch with explicit phase contract (Phase 0 worktree creation, Phase 1+2 serial, Phase 3 parallel Task pinning via prompt path, Phase 4 batch gate, Phase 5 parallel merges); U3 dynamic skeleton stance (practices wins over bolt-plan marker; scope-mapping fallback list); U4 dispatch instrumentation wraps Step 0 + Step 6.5 pipeline-deploy-agent dispatches; U5 multi-failure halt-and-ask with HOLD-MERGE invariant + sequential AUQ rendering + abort-sequence semantics
* SKILL.md halt-and-ask region gains two italic carve-outs: `_Audit-merge prefix-hash mismatch:_` (quote the error verbatim, options retry/abort) and `_Orphan-BOLT_STARTED recovery:_` (`aidlc-worktree discard --slug` cleanup, doctor reconciles)
* SKILL.md §8 edge-case carve-outs: `_Resuming a batch in flight:_` (Bolt Refs / STATE_FORKED / STATE_MERGED reconciliation, Merge-Held marker resume-persistence) and `_Workshop resume:_` (Construction Autonomy Mode inheritance via git pull — explicit not magical)
* 10 agent files (architect, aws-platform, compliance, delivery, design, developer, devsecops, operations, product, quality) gain a Knowledge Loading entry citing `.claude/practices/` per `aidlc-knowledge/shared/practices-reading.md`, scoped to each agent's actual decisions (developer reads `## Code Style`; quality reads `## Testing`; devsecops/operations read `## Deployment`; etc.). Pipeline-deploy-agent was already wired
* `audit-format.md:147-149` Reserved cells flipped to `tools/aidlc-bolt.ts dispatch-event` for the three MERGE_DISPATCH_* events. `PRACTICES_OVERRIDE` row updated to document the discriminator-field pattern and both emitter contexts (write-failure + bolt-plan-marker-conflict). `PRACTICES_SECTION_EMPTY` row flipped to `tools/aidlc-state.ts practices-event --type empty`
* `docs/reference/12-state-machine.md` audit-of-intent doctrine extended: the section is renamed to "Audit-of-intent semantics (`WORKTREE_*`, `AUDIT_*`, and merge-dispatch `MERGE_DISPATCH_INVOKED`)" with explicit doctrine clarification that the pattern applies to side-effects whose outcome cannot be pre-checked before emission — including disk operations AND LLM Task dispatch. `MERGE_DISPATCH_RETURNED`/`_FALLBACK` are post-call emits (audit-of-result, strict-first) and don't take the exception
* New `tests/unit/t79-dispatch-event-validation.sh` (12 assertions) — `dispatch-event` subcommand contract per event variant, literal-per-branch emit verified, JSON envelope shape, flag validation
* New `tests/unit/t80-practices-runtime.sh` (6 assertions) — extractMarkdownSection regex edges + `PRACTICES_SECTION_EMPTY` emit via the new `--type empty` case
* New `tests/unit/t81-bolt-plan-override.sh` (4 assertions) — discriminator-field disambiguation: practices-event --type override accepts the full field set; t28 stays at 55; write-failure + marker-conflict coexist under the same event
* New `tests/workflow/t60-t67-construction-worktrees-<scope>.sh` (8 tests, 9 or 8 assertions each = 69 total) — Construction-worktrees per-scope contracts for enterprise / feature / mvp / poc / workshop / bugfix / refactor / security-patch. Each pins scope-mapping code-generation EXECUTE, SKILL.md prose surfaces intact, dispatch-event runs cleanly, U3 names the scope correctly in the skeleton-stance fallback list, v7 state has the three v0.4.0 fields. The `infra` scope has `code-generation: SKIP` so no Construction phase exists to test
* `tests/feature/t76-halt-and-ask-prose-shape.sh` plan extends 13 → 15 (+2 line-anchored assertions for the new italic carve-outs in SKILL.md halt-and-ask region)
* `aidlc-audit.ts:89` comment updated: "pre-registered v0.4.0; emitter wired v0.4.0 via aidlc-bolt.ts dispatch-event"
* Review fold-ins (BLOCKER + MAJOR + 2× MINOR):
  * `bun .claude/tools/aidlc-bolt.ts hold-merge --slug <slug>` and `bun .claude/tools/aidlc-bolt.ts release-merge --slug <slug>` — new subcommands that set / clear the `Merge-Held` field in the per-Bolt forked state file. The orchestrator's multi-failure halt-and-ask sequence calls these instead of expecting the LLM to remember to manually call `setFieldStrict` on each successful Bolt's worktree state. Routes deterministic state mutation through tool subcommands (tools-for-determinism)
  * `aidlc-bolt complete --merge --slug <slug>` now refuses with non-zero exit and `{ok:false, reason:"merge-held", ...}` envelope when the per-Bolt forked state's `Merge-Held` field reads `true`. The HOLD-MERGE invariant is now enforced in tooling, not just prose — a successful Bolt's merge cannot land mid-AUQ-sequence even if the orchestrator forgets the contract
  * `bun .claude/tools/aidlc-worktree.ts info --slug <slug>` JSON envelope gains a `merge_held: boolean` field; on resume, the orchestrator checks this without parsing state files manually
  * `extractMarkdownSection` (`lib.ts:1081`) now ignores `## Heading` lines inside fenced code blocks (` ``` `) — a teaching example with `## Walking Skeleton` syntax inside a fence no longer masquerades as the live section
  * `audit-format.md` `PRACTICES_OVERRIDE` row clarifies the per-path field set: write-failure path emits Reason + Failure detail only; bolt-plan-marker-conflict path emits Reason + Bolt slug + Practices Stance + Bolt-Plan Marker. The two field sets do not overlap so doctor filters by Reason cleanly
  * `aidlc-knowledge/shared/worktree-info-schema.md` documents the new `merge_held` field and its semantics
  * New `tests/unit/t82-hold-merge-invariant.sh` (10 assertions) — pins hold-merge / release-merge / complete --merge refusal contract end-to-end
  * `tests/unit/t80-practices-runtime.sh` plan extends 6 → 7 (+1 assertion for the code-fence exclusion)

## [0.3.11] - 2026-05-19

`aidlc-bolt.ts` worktree subcommands — the per-Bolt lifecycle integration on top of the `aidlc-worktree` primitive, state fork/merge, and audit fork/merge. Three new flag-driven branches mirror the lifecycle's three terminal states: `start --worktree` (delegates to `aidlc-state fork` + `aidlc-audit audit-fork`), `complete --merge` (delegates to `aidlc-state merge` + `aidlc-audit audit-merge`), `abort [--discard]` (third terminal verb, optional worktree tear-down). Atomicity follows the shipped `handleSetAutonomy` precedent: validate inputs FIRST, emit primary audit event AFTER validation, THEN delegate to the state/audit subprocess CLIs which emit their own events inside `withAuditLock`. Failures emit a `BOLT_FAILED` recovery row plus a `{ok:false, slug, stage, reason, detail}` envelope for halt-and-ask consumption. SKILL.md per-Bolt loop is updated to use the new flags as single-call lifecycle boundaries (replaces the separate Step 0.6 / Step 6.8 prose with `aidlc-bolt --worktree`/`--merge` invocations that own the audit + delegate ordering). The three pre-registered `MERGE_DISPATCH_*` events get their emitter wiring at SKILL.md Steps 0 and 6.5 via `bun aidlc-audit.ts append --event MERGE_DISPATCH_* ...` — no new tool code, no new audit registration.

* `bun .claude/tools/aidlc-bolt.ts start --name "<bolt-names>" --batch <n> [--walking-skeleton true|false] [--worktree --slug <kebab-slug>]` — `--worktree` requires `--slug`, rejects csv `--name`. After BOLT_STARTED, spawns `aidlc-state.ts fork --slug <slug>` (emits STATE_FORKED, registers slug in main's Bolt Refs, byte-copies state to `<worktreePath>/aidlc-docs/aidlc-state.md`) then `aidlc-audit.ts audit-fork --slug <slug>` (emits AUDIT_FORKED audit-of-intent, byte-copies main audit). Audit order: `BOLT_STARTED → STATE_FORKED → AUDIT_FORKED`
* `bun .claude/tools/aidlc-bolt.ts complete --name "<bolt-names>" --batch <n> [--merge --slug <kebab-slug>]` — `--merge` requires `--slug`, rejects csv `--name`. After BOLT_COMPLETED, spawns `aidlc-state.ts merge --slug <slug>` (emits STATE_MERGED, removes slug from Bolt Refs, applies per-field merge rule from worktree state) then `aidlc-audit.ts audit-merge --slug <slug>` (emits AUDIT_MERGED, appends post-fork delta from worktree audit). AIDLC metadata consolidates BEFORE SKILL.md Step 6.5's git-merge dispatch
* `bun .claude/tools/aidlc-bolt.ts abort --name "<name>" --slug "<slug>" --reason "<text>" [--discard]` — third terminal verb. Emits BOLT_FAILED with `Reason: aborted` (sub-classifier; no new event type, audit count stays at 55). Default preserves the worktree directory for inspection. With `--discard`, spawns `aidlc-worktree.ts discard --slug <slug>` (audit-of-intent emits WORKTREE_DISCARDED before tear-down) and reports `discarded: true` in the JSON response
* `bun .claude/tools/aidlc-bolt.ts fail` gains optional `--slug <kebab-slug>` for halt-and-ask correlation — `aidlc-worktree info --slug` reads the most-recent WORKTREE_CREATED entry and joins on the slug field downstream
* All three new flag branches print a `{ok: false, slug, stage: "start-worktree"|"complete-merge"|"abort-discard", reason, detail}` envelope on stdout when sub-step delegation fails. Distinct from `aidlc-worktree merge`'s `{status: "conflict", conflict_files, ...}` envelope so halt-and-ask can render different prompts. Subprocess timeouts at 30s match the merge-dispatch budget; on SIGTERM the reason is `*-timeout` rather than `*-failed`
* SKILL.md Construction Flow per-Bolt loop refactored: Step 1 now invokes `aidlc-bolt start --worktree --slug <slug>` as a single tool call replacing the previous Step 0.6 (state-fork) + Step 1 (BOLT_STARTED) split. Step 6 now invokes `aidlc-bolt complete --merge --slug <slug>` replacing the previous Step 6 + Step 6.8 split. Steps 0.6 / 6.8 prose removed (delegation now lives inside `aidlc-bolt`)
* `MERGE_DISPATCH_INVOKED` / `_RETURNED` / `_FALLBACK` events at `audit-format.md:147-149` stay Reserved — emitter assignment deferred. Reason: SKILL.md prose telling the LLM to call `aidlc-audit.ts append` for these events would violate the t48 "no prose audit emission" invariant the project enforces (the LLM under `claude -p` can hallucinate permission policies on prose-directed tool calls; the documented fix is to route emission through a dedicated tool subcommand). A later change owns the per-Bolt orchestrator rewrite and will absorb dispatch instrumentation via a new `aidlc-bolt dispatch-event` (or equivalent) subcommand. Audit count stays at 55 — events were pre-registered, no new registration needed
* `abort --discard` now spawns `aidlc-worktree discard` BEFORE emitting `BOLT_FAILED` (was the reverse). Reason: emit-then-discard left audit + reality divergent on discard timeout — audit said "aborted" while the worktree still existed on disk and the slug remained in main's Bolt Refs. Default-path (no `--discard`) ordering unchanged
* `audit-format.md:113` and `docs/reference/12-state-machine.md:236` BOLT_FAILED rows updated to document the new optional fields (`Bolt slug`, `Reason: aborted`) and the new emitter (`tools/aidlc-bolt.ts abort` alongside `fail`)
* New `tests/unit/t77-bolt-worktree-flags.sh` (28 assertions) — pins atomicity ordering, complete 5-field envelope shape (`ok`, `slug`, `stage`, `reason`, non-empty `detail`), abort sub-classifier, default-abort worktree directory preservation, regression guards on existing no-flag paths
* New `tests/feature/t78-bolt-worktree-lifecycle.sh` (13 assertions) — end-to-end Bolt-with-worktree lifecycle: start --worktree → simulate per-Unit work → complete --merge round-trip with the canonical 6-event audit sequence; abort --discard with real git worktree verifies BOLT_FAILED emit AFTER successful discard AND directory teardown; abort-without-discard preservation; two parallel-batch Bolts (alpha + beta) cleanly round-trip without state interference
* New `tests/fixtures/state-construction-with-worktree.md` (v7 fixture, populated `Bolt Refs: [foo]`) consumed by t77 + t78
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.3.11`

## [0.3.10] - 2026-05-19

Adds `audit-fork` and `audit-merge` subcommands to `aidlc-audit.ts`, completing the audit half of the per-Bolt fork/merge primitive (alongside worktree create/merge and state fork/merge). Both subcommands follow audit-of-intent semantics extended from the `WORKTREE_*` events: `AUDIT_FORKED` and `AUDIT_MERGED` emit to the main audit *before* the disk operation, so a kill-9 between emit and disk surfaces as a phantom audit row reconciled by `--doctor`. The worktree audit is byte-for-byte self-contained at fork instant — its copy includes the `AUDIT_FORKED` entry by virtue of the emit-then-copy order. Delta detection at merge is parse-driven (locate the AUDIT_FORKED block in the worktree audit, take everything after its closing separator); the `Fork Boundary` field on AUDIT_FORKED anchors a SHA-256 prefix-hash sanity check that refuses to merge if main audit's prefix has been tampered with mid-Bolt. Solo Bolts as of this patch — no SKILL.md call sites yet (wired in a later release).

* `bun .claude/tools/aidlc-audit.ts audit-fork --slug <slug>` emits `AUDIT_FORKED` to the main audit, then mkdirs `<worktree>/aidlc-docs/` and copies the main audit byte-for-byte to the worktree. The `Fork Boundary` field records the byte offset of the main audit immediately BEFORE the AUDIT_FORKED row landed; `Source Audit Hash` records SHA-256 of those same prefix bytes. The worktree's copy of the AUDIT_FORKED row carries the same fields, so audit-merge can recover them without inspecting main
* `bun .claude/tools/aidlc-audit.ts audit-merge --slug <slug>` reads the worktree audit's most recent AUDIT_FORKED entry for the slug, recomputes main audit's prefix-hash at byte `Fork Boundary` and refuses with `prefix-hash` error if it disagrees with the recorded `Source Audit Hash`. On success, locates the byte position immediately after the AUDIT_FORKED block's closing `\n---\n`, appends the post-fork delta to main, and emits `AUDIT_MERGED` (with `Entries Merged`, `Source Audit Hash`, `Fork Boundary`) to the main audit only. Lock budget extended from 5s default to 20s (`acquireAuditLock(projectDir, 200, 100)`) to absorb N=4-8 Bolt-merge contention
* All `aidlc-audit audit-fork` / `audit-merge` failures route through `appendAuditEntry("ERROR_LOGGED", ...)` with `[slug=<slug>]` for `--doctor` correlation; post-emit failures additionally tag the message with `[fork-emitted:<timestamp>]` so doctor can distinguish "intent recorded, disk operation never landed" from earlier failure modes
* `audit-format.md:127-128` and `docs/reference/12-state-machine.md:283-284` Emitter cells for `AUDIT_FORKED` / `AUDIT_MERGED` now point at `aidlc-claude-code/.claude/tools/aidlc-audit.ts`. Required Fields cells updated to include `Fork Boundary` and the per-event extra fields
* `docs/reference/12-state-machine.md` § "Audit-of-intent exception" renamed to § "Audit-of-intent semantics" — the pattern now covers 5 events (3 `WORKTREE_*` + 2 `AUDIT_*`). `STATE_FORKED` / `STATE_MERGED` deliberately stay under the strict audit-first invariant — state writes are idempotent where `git worktree add` is not, so a failed state write surfaces as recoverable drift instead of an unrecoverable orphan. The 2-row event-group/emitter/disk-op table documents only the audit-of-intent half; STATE_* lives under the strict-first section above
* New worktree-tier test `tests/worktree/t07-audit-fork-merge.sh` (31 assertions across three phases): smoke (fork creates byte-identical worktree audit; AUDIT_FORKED in both audits with matching Fork Boundary; merge appends delta; AUDIT_MERGED in main only), edge cases (empty delta; missing aidlc-docs subdir auto-created; missing main audit fails loud; prefix-hash mismatch refusal; N=2 lock contention via 50ms stagger; lock-timeout failure path with planted stuck lock; 65-char slug rejected with length error; post-emit failure ERROR_LOGGED carries `[fork-emitted:<iso-ts>]` for doctor correlation), and property (N=4 alphabetical / reverse-alphabetical / same-second-timestamps / one-empty-delta scenarios all preserve per-Bolt fork→merge bracket order in the merged main audit)
* `BOLT_SLUG_REGEX` and `validateBoltSlug(slug)` exported from `lib.ts` — centralises the kebab-case Bolt slug regex (was previously duplicated as `SLUG_RE` in `aidlc-worktree.ts` and `SLUG_REGEX` in `aidlc-audit.ts`). Adds 64-char max-length check so pathologically long slugs fail fast with a clear error instead of surfacing as cryptic mkdir/copy failures. `aidlc-audit.ts` adopts the helper now; `aidlc-worktree.ts` keeps its tool-local `SLUG_RE`
* `AIDLC_AUDIT_LOCK_RETRIES` and `AIDLC_AUDIT_LOCK_RETRY_MS` env-var overrides for `audit-merge`'s lock budget — defaults stay at `200 × 100ms = 20s` for parallel-Bolt contention; tests dial these down so the lock-timeout failure path runs in ~100ms instead of 20s. Lock-timeout error message now reports the actual budget exhausted (`Failed to acquire audit lock after N × Mms = X.Xs retries; another merge in flight?`)
* `audit-merge` prefix-hash mismatch error now distinguishes truncation from mid-prefix mutation: when `mainBuf.length < boundary`, the error reads "expected at least N bytes, got M" so doctor can surface the right failure mode
* `appendAuditEntryUnlocked` is adopted on both the happy and error paths of `audit-merge` so the delta-append + AUDIT_MERGED emit (happy) and the delta-append + ERROR_LOGGED emit (catch) each run inside a single locked critical section, with no release-and-reacquire across either boundary

## [0.3.9] - 2026-05-18

Practices-discovery stage at slot 2.2. New Inception stage that discovers a team's branching, walking-skeleton, testing, deployment, and code-style stance from evidence (brownfield) or AskUserQuestion (greenfield), then at an affirmation gate promotes the affirmed content from per-workflow audit trail (`aidlc-docs/inception/practices-discovery/`) into team-authored harness config (`.claude/practices/team.md` + `.claude/rules/aidlc/guardrails/project-guardrails.md`). The cross-row promotion is the structurally distinctive pattern this stage introduces — every other stage writes to one row of the two-axis configuration model; practices-discovery writes both, and the affirmation gate is what makes the cross-row write legitimate. Inception phase grows from 7 stages to 8 stages (slot 2.2 filled). Total stages 31 → 32.

* `bun .claude/tools/aidlc-graph.ts topo` now lists `practices-discovery` between `reverse-engineering` and `requirements-analysis`. Stage executes for `enterprise`, `feature`, `mvp`, `workshop`, `infra` scopes; skipped for `poc`, `bugfix`, `refactor`, `security-patch`
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.3.9`
* New `replaceSection(content, heading, newContent)` helper in `.claude/tools/lib.ts` — overwrites section content under an existing heading. Required for the team.md cross-row promotion (re-runs would otherwise accumulate duplicates via `appendUnderHeading`)
* New `bun .claude/tools/aidlc-state.ts practices-event --type <discovered|affirmed|override> [--field "Key: Value"]...` subcommand that emits the corresponding `PRACTICES_*` audit event from tool code (preserves the audit-first invariant — t48 emitter-pairing check finds explicit `emitAudit` literals at the call site)
* New `bun .claude/tools/aidlc-state.ts practices-promote --team-practices <path> --discovered-rules <path> [--affirming-user <name>]` subcommand performs the cross-row write atomically: reads the two drafts, applies `replaceSection` × 5 to `.claude/practices/team.md` and `appendUnderHeading` × 2 to `.claude/rules/aidlc/guardrails/project-guardrails.md`, then emits `PRACTICES_AFFIRMED` (or `PRACTICES_OVERRIDE` on failure). Step 6 of the stage now calls this subcommand instead of describing the file writes in prose. Reason: the LLM running non-interactively under `claude -p` was hallucinating a sensitive-file permission policy on `.claude/rules/aidlc/guardrails/` and halting the workflow at the affirmation gate without ever attempting the write — routing the writes through a tool subcommand removes the LLM from the path so the hallucinated policy never fires
* New unit test `tests/unit/t71-markdown-section-helpers.sh` (12 assertions) pinning the behavioural contract for `extractMarkdownSection`, `appendUnderHeading`, and `replaceSection` — load-bearing for the cross-row promotion
* Stage body uses `mode: inline` with parallel four-Task dispatch for the discover step (pipeline-deploy + quality + developer + devsecops). Pre-registered audit events `PRACTICES_DISCOVERED` and `PRACTICES_AFFIRMED` emit at draft-completion and affirmation respectively. `PRACTICES_OVERRIDE` emits on write-failure recovery
* Five downstream Inception stage frontmatters (`requirements-analysis`, `user-stories`, `refined-mockups`, `application-design`, `delivery-planning`) gain optional `team-practices` consumes entry. Slot reservation only — `delivery-planning` is the sole stage that wires actual consumption (reads `## Branching` / `## Walking Skeleton` / `## Deployment` from `team.md` via `extractMarkdownSection` when populating `bolt-plan.md`); the other four reserve the slot for later wiring
* Statusline `STAGE_DISPLAY` map gains `practices-discovery: "Practices Discovery"` so workflows render the friendly name; `aidlc-statusline.ts:74`
* User-visible `companyAnnouncements` welcome banner in `.claude/settings.json` — `(31 stages across 5 phases)` → `(32 stages across 5 phases)`; INCEPTION row `2.1, 2.3–2.8 (7)` → `2.1–2.8 (8)`; INCEPTION abbreviation row gains `PD=Practices Discovery`. Scope summary table on `SKILL.md` rewrites every `/31` divisor to `/32` and bumps numerators per scope (enterprise=32, feature=32, mvp=22, workshop=25, infra=13; bugfix/poc/refactor/security-patch unchanged)
* State template (`.claude/aidlc-knowledge/shared/state-template.md`) gains `practices-discovery` row in INCEPTION block; Step 7 of the stage writes `Practices Affirmed Timestamp` (the v7 field). Nine of ten state fixtures at `tests/fixtures/state-*.md` updated. Designer-export (`tests/fixtures/designer-export/export.json`) and `mr9-parity/*.json` fixtures (27 files) regenerated
* New `docs/reference/04-stages/inception.md` § Stage 2.2 prose section (~80 lines) covering metadata, purpose, inputs, outputs, steps, and notes for the new stage. `stage-protocol-recovery.md` adds INCEPTION — Practices Discovery resume-context block. `audit-format.md` and `docs/reference/12-state-machine.md` Reserved cells for `PRACTICES_DISCOVERED` / `PRACTICES_AFFIRMED` filled with `tools/aidlc-state.ts practices-event --type ...`
* State fork/merge (no version bump). New `bun .claude/tools/aidlc-state.ts fork --slug <slug>` and `merge --slug <slug>` subcommands isolating per-Bolt state inside Construction worktrees. Fork copies main `aidlc-docs/aidlc-state.md` byte-identically to `<worktreePath>/aidlc-docs/aidlc-state.md`, registers the slug in main's `Bolt Refs`, and emits `STATE_FORKED` (strict audit-first — the audit-of-intent exception at `docs/reference/12-state-machine.md:322` stays bounded to the three `WORKTREE_*` events because state fork is idempotent where `git worktree add` is not). Merge reads the worktree state, applies workflow-level-fields-untouched + alphabetical-slug tiebreak as defence-in-depth, emits `STATE_MERGED` with a `Conflict resolution` audit field, then removes the slug from `Bolt Refs`. Both subcommands validate slug against kebab-case `^[a-z][a-z0-9-]*$` before any path construction (path-traversal guard) and embed `[slug=<slug>]` in error messages for doctor correlation. Idempotent: re-running `merge` for an already-merged slug exits non-zero with `already merged: not in Bolt Refs` and emits no second audit row; re-running `fork` for an already-active slug exits non-zero with `slug already in Bolt Refs` (recovery hint in the message) and emits no phantom STATE_FORKED row. New helpers `parseRefsList` / `emitRefsList` / `appendSlug` / `removeSlug` in `lib.ts` handle the list-shaped `Bolt Refs` value (with `[empty list]` literal placeholder when empty) — `setFieldStrict` is a scalar primitive that cannot append. New `withAuditLock(projectDir, fn)` helper in `lib.ts` — atomic locked-section primitive with a `process.on("exit")` safety net so `process.exit(1)` inside the body still releases the lock dir (Bun's `process.exit` skips `finally`, which would otherwise poison the project for ~5s on the next invocation). New `appendAuditEntryUnlocked(...)` in `aidlc-audit.ts` — the locking variant's body without the lock acquisition, for callers (fork/merge) that already hold the lock via `withAuditLock`; `emitError` detects whether a `withAuditLock` is in flight and uses the unlocked variant accordingly so `ERROR_LOGGED` lands without deadlocking on its own lock acquisition. Bug-fix in same change: `getField`/`setField`/`setFieldStrict` regex tightened from `\s*` to `[ \t]*` so empty-value fields no longer return / replace the next bullet line (latent bug surfaced by `Bolt Refs:` empty default — no caller before read or wrote a legitimately-empty field). New SKILL.md per-Bolt Steps 0.6 (state fork after worktree-create-verify, before BOLT_STARTED) and 6.8 (state merge after worktree-merge-verify). `audit-format.md:125-126` and `docs/reference/12-state-machine.md:281-282` Emitter cells now point at `tools/aidlc-state.ts`. New `tests/unit/t76-state-fork-merge.sh` (16 assertions) pinning the contract — happy round-trip, slug validation, missing worktree dir, v6-state failure, audit-first Parts A+B, workflow-level-untouched, alphabetical-slug tiebreak, idempotency, lock-timeout, concurrent forks, plus three regression tests: B2 (no phantom STATE_FORKED on duplicate fork), B1 (lock dir released even when `errorWithSlug` calls `process.exit` inside the locked block), M1 (audit `Target state hash` matches the actual post-write main state SHA, computed inside the lock against the final merged content). Solo Bolts and parallel batches now run on isolated state files

## [0.3.8] - 2026-05-18

Adds the `aidlc-worktree` CLI primitive with `create`, `merge`, `discard`, `list`, and `verify` subcommands. The orchestrator dispatches `pipeline-deploy-agent` (which reads team practices to pick branching flags) and then calls `verify` as a deterministic post-dispatch backstop confirming the audit event landed. The three `WORKTREE_*` events follow audit-of-intent semantics — emit fires before `git`, and `doctor` reconciles disk vs audit drift if a kill-9 / OS-crash interrupts the operation between those points. **Constraint:** `aidlc-worktree` must run from the main repo checkout, not from a sibling worktree under `.claude/worktrees/<slug>/`. Solo Bolts as of this patch — the dispatch creates worktrees, but state and audit don't fork yet. The Construction orchestrator's per-Bolt loop in `SKILL.md` now includes Step 0 (worktree create dispatch + verify) and Step 6.5 (worktree merge dispatch + verify); the verify backstop is what makes the agent dispatch deterministic without prose-grepping audit.md.

* `bun .claude/tools/aidlc-worktree.ts create --slug <slug> --base <branch>` adds a per-Bolt worktree at `.aidlc/worktrees/bolt-<slug>` on a new `bolt-<slug>` branch, emits `WORKTREE_CREATED` audit event before invoking git
* `bun .claude/tools/aidlc-worktree.ts merge --slug <slug> --target <branch> --strategy <squash|merge|rebase> [--message <msg>]` performs the merge per the chosen strategy from the current cwd (which must be on `<target>`), emits `WORKTREE_MERGED`, removes the worktree and deletes the branch on success. Conflicts leave the worktree intact and exit non-zero with a JSON conflict envelope including `conflict_files` and a `detail` field the orchestrator's halt-and-ask quotes verbatim. Rebase strategy fetches `<target>`'s remote first and errors when no remote is configured
* `bun .claude/tools/aidlc-worktree.ts discard --slug <slug>` removes the worktree and deletes the branch, emits `WORKTREE_DISCARDED`. Idempotent — succeeds silently when the worktree is already gone
* `bun .claude/tools/aidlc-worktree.ts list` returns the JSON-shaped list of `bolt-*` worktrees (read-only, no audit emission)
* `bun .claude/tools/aidlc-worktree.ts verify --event <WORKTREE_*> --slug <slug> [--max-age-seconds <n>]` greps `aidlc-docs/audit.md` for the most recent matching block, exits 0 within the staleness window (default 60s), exits non-zero with `{verified: false, reason: "absent" | "stale (last seen <ts>)"}` otherwise. The orchestrator's deterministic post-dispatch backstop — same code path for production and tests
* All `aidlc-worktree` failures route through `emitError` with `[slug=<slug>]` prepended to the error message so the `ERROR_LOGGED` row carries the affected Bolt slug for `doctor` correlation
* Sibling-worktree rejection: running `aidlc-worktree` from inside a non-main worktree errors pre-audit with `aidlc-worktree must run from the main repo checkout, not from a sibling worktree at <cwd>`. Teams dogfooding the framework from `.claude/worktrees/<dev-slug>/` should `cd` to the main checkout before running `/aidlc`
* `pipeline-deploy-agent` now loads `.claude/practices/` between agent-specific KB and team-shared knowledge in its Knowledge Loading order. New `aidlc-knowledge/shared/practices-reading.md` documents the empty-template detection, semantic-topic matching, and `team.md → org.md → hardcoded defaults` fallback chain other agents will adopt later
* `aidlc-knowledge/pipeline-deploy-agent/branching-strategies.md` rewritten: each of the five strategies now has an Execution-runbook + Failure-modes sub-section with the explicit `bun .claude/tools/aidlc-worktree.ts create ...` incantation; new top-level Response-contract section documents the JSON envelope the agent returns to the orchestrator
* `audit-format.md:122-124` and `docs/reference/12-state-machine.md:278-280` Emitter cells for `WORKTREE_CREATED`, `WORKTREE_MERGED`, `WORKTREE_DISCARDED` now point at `aidlc-claude-code/.claude/tools/aidlc-worktree.ts`. New paragraph in `docs/reference/12-state-machine.md` § Audit-first atomicity documents the audit-of-intent exception: `WORKTREE_*` events record the orchestration intent, not the on-disk outcome

## [0.3.7] - 2026-05-18

Bumps the state-template version from 6 to 7 and adds three new fields used by downstream worktree and practices work: `Worktree Path` (set when a Bolt forks state into a worktree), `Bolt Refs` (active Bolt slugs for cleanup), `Practices Affirmed Timestamp` (ISO 8601 stamp written on the practices-discovery affirmation gate). Doctor now fails loud on v6 state files with archive-and-reinit advice. **No migration code** — following the v5→v6 precedent at commit `c084c2c`. v6 users archive their workspace (`mv aidlc-docs aidlc-docs.v6-archive`) and re-run `/aidlc --init` to scaffold v7.

* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.3.7`
* Fresh `/aidlc --init` produces a v7 state file with `Worktree Path`, `Bolt Refs`, `Practices Affirmed Timestamp` fields present (empty by default until populated)
* `/aidlc --doctor` exits non-zero on a v6 state file with the message `state version current — v${match[1]} state detected. Archive your workspace and re-run /aidlc --init to scaffold a v7 workspace.` On a malformed or missing State Version line, doctor reports `state version readable` failure with the same archive-and-reinit advice
* 9 of 10 state fixtures bumped (`tests/fixtures/state-corrupted.md` retained at v6/empty for parse-failure tests). 6 test grep assertions updated (t12, t21, t50, t52, t70, t71)
* `docs/reference/02-orchestrator.md` State File Schema description updated to reference State Version 7 + the 3 new Project Information fields

## [0.3.6] - 2026-05-18

Renumbers Inception stages 2.2–2.7 down by one (slugs unchanged) to free slot 2.2 for the `practices-discovery` stage. No graph-topology changes — `requires_stage` chains stay slug-keyed and topo-sort output is identical (numbers are a tiebreak, not a primary sort key). Inception phase temporarily exhibits a number gap at 2.2, filled when practices-discovery lands. A permanent stage-number drift-sweep test is deferred — encoding "expect a gap at 2.2" in a permanent test would be more noise than signal.

* `bun .claude/tools/aidlc-graph.ts topo` returns the same slug order as before. The numeric labels in `stage-graph.json`, `tests/fixtures/designer-export/export.json`, `SKILL.md` routing table + INCEPTION flow, and ~30 `docs/reference/` + `docs/guide/` files shift per the chain: `requirements-analysis` 2.2 → 2.3, `user-stories` 2.3 → 2.4, `refined-mockups` 2.4 → 2.5, `application-design` 2.5 → 2.6, `units-generation` 2.6 → 2.7, `delivery-planning` 2.7 → 2.8
* `bun .claude/tools/aidlc-utility.ts version` prints `aidlc 0.3.6`
* State fixtures (9 of 10 at `tests/fixtures/state-*.md`) and the embedded heredoc in `tests/unit/t11-hook-statusline.sh` updated for the gap-shift — `Stages to Execute` lists now read `... 2.1, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, ...`
* User-visible `companyAnnouncements` welcome banner in `.claude/settings.json` updated — Phases table INCEPTION row now reads `2.1, 2.3–2.8 (7)` to match the temporary gap; the count remains 7 (slot 2.2 is reserved, not removed)

## [0.3.5] - 2026-05-17

Configuration-layers documentation, `.claude/practices/` namespace, and a five-strategy branching-strategies knowledge file. These deliverables are scaffolding consumed by later work; they exercise no user-facing surface yet but ship a new top-level `.claude/practices/` directory and a new architecture chapter section that contributors will route through.

* New "Configuration layers" section in `docs/reference/01-architecture.md` documents the two-axis routing model (authorship × consumption) for placing new concerns in `.claude/` and `aidlc-docs/`. Four quadrants — three populated, one intentionally empty. Boundary tests, sub-categories of harness config, and a callout for practices-discovery's cross-row promotion. Anchors v0.5.0+ routing decisions
* New `.claude/practices/` namespace: `org.md` (framework methodology defaults written in team-voice), `team.md` (empty template populated by practices-discovery affirmation), `project.md` (empty override template). Loaders read in order org → team → project; later layers replace earlier
* New `.claude/aidlc-knowledge/pipeline-deploy-agent/branching-strategies.md` covering trunk-based, GitHub Flow, GitFlow, release branches, and monorepo with diagrams, when-to-use, common problems, AIDLC worktree mapping (`base`/`target`/`strategy`), and parallel-Bolts notes. Cross-linked with the existing `cicd-patterns.md` § "Branch Strategies" so the two files stay coherent as the deeper menu (this) vs the CI-flow context (cicd-patterns)
* `## Mandated` and `## Forbidden` headings appended to `.claude/rules/aidlc/guardrails/project-guardrails.md`. Mirrors the heading shape of `org-guardrails.md`. Empty under this release; populated by the practices-discovery affirmation step
* Two markdown-section helpers added to `.claude/tools/lib.ts`: `extractMarkdownSection(content, heading)` returns the prose between `## Heading` and the next `## ` heading or EOF (empty string when absent); `appendUnderHeading(content, heading, newContent)` inserts before the next `## ` heading (throws when absent). Both pure-string functions; consumed by the practices-discovery affirmation copy under guardrail headings and the orchestrator stance lookup in `practices/team.md`

## [0.3.4] - 2026-05-17

Adds the `worktree` test tier — a new dispatch surface in `tests/run-tests.sh`, four shell helpers in `tests/lib/worktree-helpers.sh`, and a meta-test under `tests/worktree/`. Downstream consumers — `aidlc-worktree.ts`, state fork/merge, audit fork/merge, `aidlc-bolt` worktree subcommands — populate the tier with real coverage; on day one it ships with a single 7-assertion meta-test that pins the helper contract.

* `bash tests/run-tests.sh --worktree` runs the new tier. Joined into `--ci`, `--release`, and `--all` profiles so CI gates don't silently skip worktree coverage as consumers land. No LLM dependency — fires after the preflight gate. Pinned to serial in `run_tier` until parallelism is proven safe under interleaved `git worktree` registry mutations
* `tests/lib/worktree-helpers.sh` exports `setup_worktree_fixture`, `assert_worktree_at`, `assert_worktree_absent`, `cleanup_worktree_fixture`. Setup creates a per-test `mktemp` git repo with one seed commit on `main` (uses `git init -q` + `git symbolic-ref` for git ≥ 2.5 portability — `git init -b` requires 2.28). Failure-loud: any setup step failing returns 1 and removes the partial fixture. Cleanup is idempotent and refuses to act on paths whose basename does not start with `aidlc-worktree-` — defence-in-depth so `cleanup_worktree_fixture ""` or a typo can't `rm -rf` `/`, `$HOME`, or other system paths
* `tests/worktree/t01-helpers.sh` (7 assertions) exercises the helpers against a fresh fixture and probes the cleanup-guard's path-prefix check with a sentinel directory
* `tests/smoke/t05-run-tests-parallel.sh` extended (plan 11 → 14) to cover `--worktree` dispatch under direct invocation and via `--ci`. `tests/feature/t55-test-suite-drift.sh` `TIERS` array updated so the drift sweep walks the new tier

## [0.3.3] - 2026-05-17

Adds the path-helper primitive that downstream Construction-worktree work (`aidlc-worktree.ts`, state fork/merge, audit fork/merge) composes over, plus the `.gitignore` reservation for the runtime namespace at repo root. No behaviour change in this patch — `worktreePath()` has no callers yet; it ships ahead of its consumers so test fixtures and the keystone can reference the path.

* `worktreePath(projectDir, boltSlug)` exported from `.claude/tools/lib.ts` returns `<projectDir>/.aidlc/worktrees/bolt-<slug>`. Pure path construction; mirrors `stateFilePath` and `auditFilePath`. Composes with them so `stateFilePath(worktreePath(p, slug))` and `auditFilePath(worktreePath(p, slug))` yield the in-worktree state and audit paths state fork and audit fork will read and write
* `.gitignore` reserves `/.aidlc/` at repo root for AIDLC runtime state. Anchored (leading `/`) so a stray `.aidlc/` inside `node_modules/` or a nested package isn't silently swallowed. Distinct from the existing `.claude/worktrees` entry — `.aidlc/worktrees/` is the Construction-Bolt runtime path; `.claude/worktrees/` is the framework-development worktree convention. Both coexist intentionally
* `tests/unit/t69-worktree-path.sh` pins the helper's behavioural contract: `.gitignore` entry present, output absolute when `projectDir` is absolute, output ends with `/bolt-<slug>`, and slug passes through unsanitised (validation deferred to the `aidlc-worktree.ts` create-time check)

## [0.3.2] - 2026-05-17

Pre-registers 14 audit events (worktree, practices, merge-dispatch) so downstream work can `import` constants without racing on `tests/unit/t28-audit-event-sync.sh`'s pinned count. No emitters ship in this patch — each pre-registered event has a `Reserved` Emitter cell in `audit-format.md` and `docs/reference/12-state-machine.md` that the consumer replaces with the real file path in the same commit it adds the emit call. The audit taxonomy now declares 55 events across 15 categories (was 41 across 12).

* `bun .claude/tools/aidlc-audit.ts append <name>` accepts 14 new event names: 7 worktree-lifecycle (`WORKTREE_CREATED`, `WORKTREE_MERGED`, `WORKTREE_DISCARDED`, `STATE_FORKED`, `STATE_MERGED`, `AUDIT_FORKED`, `AUDIT_MERGED`), 4 practices (`PRACTICES_DISCOVERED`, `PRACTICES_AFFIRMED`, `PRACTICES_OVERRIDE`, `PRACTICES_SECTION_EMPTY`), 3 merge-dispatch (`MERGE_DISPATCH_INVOKED`, `MERGE_DISPATCH_RETURNED`, `MERGE_DISPATCH_FALLBACK`)
* `tests/unit/t28-audit-event-sync.sh` pin bumped from 41 to 55, matching the new `## Event Registry (55 events, 15 categories)` header in `aidlc-knowledge/shared/audit-format.md` and the `**55 events across 15 categories.**` prose in `docs/reference/12-state-machine.md`
* Three new `### ` category subsections (Worktree, Practices, Merge Dispatch) added to both audit reference docs in matching shape
* `tests/feature/t48-audit-event-emitters.sh` forward-emitter check skips rows whose Emitter cell starts with `Reserved` (existing behaviour at line 101) — pre-registered rows pass until the consumer replaces `Reserved` with the real `tools/*.ts` path in the same commit it adds the emit call

## [0.3.1] - 2026-05-15

Adds a runtime version surface so `/aidlc --version` prints the framework version, and formalises the per-release changelog cadence.

* `/aidlc --version` prints the framework version (e.g. `aidlc 0.3.1`). Equivalent to `bun .claude/tools/aidlc-utility.ts version`. Like `--status`, `--help`, and `--doctor`, it runs without a workflow and never prompts to resume one
* Every user-visible release now bumps the version and adds a matching `## [X.Y.Z]` heading to `CHANGELOG.md` in the same commit, replacing the prior release-cut-time policy. Pure doc sweeps and internal refactors don't bump. Tagging (`git tag vX.Y.Z`) remains a post-merge ritual, not a CI gate. Pinned by `tests/unit/t68-version-changelog-sync.sh`

## [0.3.0] - 2026-05-15

Foundation release. v0.3.0 reshapes how stages, scopes, agents, and artifacts are defined so later releases can ship Construction worktrees, three-compartment stages, sensors, the Ralph loop driver, the fitness compiler, and the visual workflow designer without rewriting plumbing. By design no new user-facing workflows — your v0.2.0 workflows run the same way. State file format bumps from v5 to v6 with no field changes; in-flight workflows archive-and-reinit:

    mv aidlc-docs aidlc-docs-v5-archive && /aidlc --init --force --scope <scope>

* **BREAKING for CI and shell automation**: `/aidlc --doctor` now exits non-zero when any check fails (previously always exited 0). Any CI job or `set -e` shell script that invoked doctor and continued on will now abort. Restore the old behaviour with `|| true`
* New `bun .claude/tools/aidlc-graph.ts` lets you inspect the stage dependency graph from the command line — see which stages produce or consume an artifact, list every artifact, view a scope's stage path, validate a scope, find cycles. The visual workflow designer shipping in v0.11.0 will read from `aidlc-graph.ts export`
* `/aidlc "<freeform description>"` now infers your scope from natural language — `/aidlc "debug the auth flow"` picks `bugfix`, longer descriptions fall back to `feature` unless a clear keyword matches. Word boundaries prevent `debug` from matching the substring `bug`
* Stage files now use YAML frontmatter for their dependency contracts (slug, phase, lead agent, artifacts produced and consumed, required upstream stages). Stage bodies are unchanged — the prose your orchestrator reads is the same. Adding or modifying a stage now means editing one place: the YAML at the top of its `.md` file. The format is documented in `docs/reference/13-stage-definition.md`
* Adding a custom scope no longer requires editing TypeScript. Edit `.claude/tools/data/scope-mapping.json`, run `bun .claude/tools/aidlc-utility.ts scope-table`, commit
* Adding a custom agent no longer requires editing TypeScript. Drop a `.md` file with the right frontmatter into `.claude/agents/`
* Agent files now reference stages by slug (`intent-capture`, `code-generation`) rather than numeric ID (`1.1`, `3.5`). Slugs are the canonical stage identifier; numeric display orders stay in `stage-graph.json` for graph machinery. Contributors writing custom agent files should use slugs
* `/aidlc --help` output is now generated from your live scope configuration, so per-scope stage counts always match what the orchestrator will actually run. Previously the help text had hardcoded counts (`bugfix ~8`, `mvp ~25`, etc.) that drifted as scopes evolved
* New stability-policy chapter at `docs/reference/15-stability-policy.md` codifies pre-1.0 semantics, the archive-and-reinit pattern for state-schema bumps, and the count-pin pattern that keeps numbers in docs from drifting away from the code
* `/aidlc --doctor` reports a missing `aidlc-docs/` directory as a failure now (was passing silently); also gains graph-level health checks (cycle detection, orphan stage files, scope validation, keyword-overlap detection)
* `/aidlc --init` on an existing workspace exits with a clear error instead of hanging or asking clarifying questions in non-interactive mode
* Statusline progress bar now tracks the current phase rather than the full workflow — previously the bar could appear stuck for several stages because it was workflow-scoped while the N/M ratio was phase-scoped
* `tests/run-tests.sh --parallel N` runs test files concurrently within a tier. Integration and workflow tiers drop from ~30 minutes to ~8–10 minutes at `--parallel 4`
* Welcome-message scope table fix: `--scope sec-patch` (a typo in the welcome banner that previously produced an `Unknown scope` error) now correctly maps to `security-patch`, and the missing `workshop` row is included

## [0.2.0] - 2026-05-03

Breaking release. State file format is now v5 and cannot be migrated from v4 — in-flight workflows must be restarted:

    mv aidlc-docs aidlc-docs-v4-archive && /aidlc --init --force --scope <scope>

* Workflow `Status` values simplified to `Running` and `Completed`. Replaces `In Progress`, `Paused`, and `Waiting for Approval` — pause has no UX and approval waits moved to the stage level (see next bullet)
* Two new stage states: `[?]` means the stage is waiting for your approval, `[R]` means you rejected the gate and it's being revised. Previously both situations looked like `[-]` and you couldn't tell them apart from `--status`
* `/aidlc --status` now tells you who the blocker is. When a stage is `[?]`: "Awaiting your approval on <stage>". When `[R]`: "Revising <stage> (revision N of 3)". Previously always read "Running" even when the workflow was waiting on you
* `/aidlc --doctor` gains a drift check — catches the rare case where the audit log records a workflow completion but the state file disagrees
* `/aidlc --init` is now one fast deterministic call (under a second). Replaces the previous multi-tool-call flow that sometimes hit timeouts
* `--force` flag on `/aidlc --init` — rewrites `aidlc-state.md` and warns about any unrelated artifacts found in `aidlc-docs/`. Without `--force`, re-running init on an existing workflow exits with a helpful message instead of hanging
* Approving a stage now advances the workflow atomically. The approval flips the gate, marks the stage complete, and moves you to the next stage in one step. Fixes the previous failure mode where `/aidlc --status` could show "Awaiting your approval" after you'd already approved
* Compaction-aware resume. If your Claude Code context is compacted during a stage, resuming surfaces a three-option prompt (continue / review prior artifact / restart stage) instead of silently picking up stale context
* `--test-run` early stops emit `WORKFLOW_COMPLETED` with `Reason=test-run-stopped-at-<target>` so CI harnesses get a clean terminal state to assert on
* `--scope <x>` can be used mid-workflow to change scope in place. The stage plan re-derives and skipped stages flip to `[S]` if the new scope excludes them
* Welcome message now renders at session start via `settings.json` `companyAnnouncements` instead of running as a workflow stage. Total stage count dropped from 32 to 31
* Statusline progress bar now tracks the current phase. Previously the bar was workflow-scoped (e.g. 15/31) while the numeric ratio was phase-scoped (e.g. 5/7), so the bar could appear stuck for multiple stage advances
* Invalid `AWS_AIDLC_DEFAULT_SCOPE` values now error cleanly and exit without creating state. Previously could hang or ask clarifying questions in non-interactive mode
* New reference documentation chapter at `docs/reference/12-state-machine.md` covering the workflow, phase, and stage state machines, the audit event taxonomy, and the same-commit doc/code consistency rule
* Canonical state file schema is documented as State Version 5. Audit log consumers that parse free-form markdown headings (`## Artifact Update`, `## Subagent Completed`) must switch to the `**Event**:` field shape — these sections are no longer emitted
* Audit event taxonomy rebalanced: 5 auto-event types removed (test-run selections now tag canonical events with `Test-Run: true`), session lifecycle events now emitted by hooks (SessionStart / SessionEnd / PreCompact), artifact lifecycle events now emitted by the PostToolUse hook. Taxonomy: 47 → 41 events, each with a tool-owned emitter

## [0.1.0] - 2026-04-24

Initial public release.

* `/aidlc` orchestrator skill with 5 phases (Initialization, Ideation, Inception, Construction, Operation) and 32 stages
* 11 domain-expert agents: product, design, delivery, architect, aws-platform, compliance, devsecops, developer, quality, pipeline-deploy, operations — invoked by the orchestrator based on stage and scope
* 9 adaptive scopes (enterprise, feature, mvp, poc, bugfix, refactor, infra, security-patch, workshop) that route through different stage subsets
* `--depth` flag with three levels (minimal, standard, comprehensive) to control process rigor per stage
* `--test-strategy` flag with three levels (Nyquist Minimal, Standard, Comprehensive) independent of depth — workshop scope defaults to Minimal
* `--stage`, `--phase`, `--scope` jump flags for moving directly into a specific point in the workflow
* `--status`, `--doctor`, `--help`, `--init`, `--test-run` utility handlers
* Bolt-by-Bolt Construction: dependency DAG execution with walking skeleton mode, autonomy mode, and per-bolt quality gates
* Stage protocol with approval gates at every stage, structured question format, and session resume from any checkpoint
* TypeScript hooks for audit logging (37-event taxonomy), state preservation, statusline sync, and session recovery — runs natively on Windows without Bash
* `AWS_AIDLC_DEFAULT_SCOPE` environment variable so organizations can pin a default scope at the shell or profile level
* Statusline showing current phase, stage, agent, model, and context usage with phase-scoped progress
* Three-tier test suite (smoke, unit, feature, integration) with LLM-behavioral tests via `--test-run`
* `BOLT_*` audit event taxonomy for Construction phase tracking
* Two-tier documentation: User Guide (`docs/guide/`) and Developer Reference (`docs/reference/`)
* Promoted 7 agents (architect, compliance, devsecops, developer, quality, pipeline-deploy, operations) to Opus; shipped Bedrock model IDs as defaults
* Pinned orchestrator to Opus with 1M context on Bedrock
* `/aidlc --help` documents all CLI utilities and flags with examples
* Windows compatibility: hooks and the statusline ported from Bash to TypeScript; `--doctor` is platform-aware; no jq or Bash prerequisites
* macOS compatibility across the test suite (BSD vs GNU utilities, whitespace padding, AppleDouble sidecar files)