CHANGELOG.md

# Changelog

All notable changes to Stagecraft.

Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org).

---

## [Unreleased]

---

## [0.11.0] — 2026-08-09

### Added

- Add proposal-first conversational refinement for requirements and design: captured no-tool turns produce an exact local diff, explicit apply/reject rechecks artifact hashes, and apply atomically invalidates downstream gates.

- **Route-aware ceremony pricing and simpler assurance choices.** `devteam assess`
  now compares the three primary assurance levels (`loop`, `quick`, `full`)
  while preserving specialist tracks for change shapes such as dependency
  updates and incident response. Static cost previews price explicit
  per-stage/per-role model pins immediately and fall back to the most recently
  observed model only when routing does not pin one. Each dispatch reports
  whether its model came from configuration or observation. *Honest scope
  note:* output-token volume remains unknown before a run, so static dollars
  are explicitly labeled as an input-cost floor; empirical dollars are
  observed total cost. Unpriced models still suppress the figure rather than
  showing a misleading partial cost.

- **Grounded conversational coordinator** (BACKLOG E9 first slice). `devteam chat`
  adds one-shot and TTY conversation over a bounded deterministic snapshot of
  config, run state, stage summary, cost, blockers, and the pure next action. It
  recommends exact commands but cannot execute them, persists no transcript,
  redacts secret-shaped strings, runs adapters from a disposable workspace,
  disables OpenAI-compatible tools, and rejects all ACP permission requests.
  Adapter output capture is additive and bounded. *Honest scope note:* same-user
  CLI hosts are not OS-sandboxed; write-capable conversational requirements or
  design refinement remains deferred behind an explicit approval contract.

- **Current documentation now matches the shipped track and roadmap surface.** The active entry points describe all ten tracks, distinguish the recommended `loop` workflow from the conservative `full` factory fallback and the assessor's current behavior, replace the evaluator's manual 18-stage/PASS-gate walkthrough with an autonomous bounded run, mark phases 36/37 and ADR-017 accurately, and remove the obsolete fixed test-duration claim. The consistency checker now recognizes written track counts through ten and scans the root README, with a regression fixture proving a stale written count is rejected.

### Added

- Add fingerprinted `trusted` and fail-closed Docker `contained` execution profiles with disposable worktrees, scoped environment, default-deny network, resource limits, and validated output reconciliation. Reserve `remote` without silently degrading it.

### Fixed

- Add the canonical global `devteam --version` flag backed by `package.json`,
  and keep help plus the generated CLI reference locked to that surface.

- Authorize the exact runtime gate path when `active_roles` or a track collapses
  a normally multi-role stage to one workstream, preventing the required gate
  from being rejected by the post-hoc write audit.

- Fall back to the project's canonical lint command when a build workstream's
  declared directory targets do not exist, avoiding false verifier failures on
  narrow repairs and repositories with nonstandard layouts.

- **`devteam review`'s ACP review-mode execute allowlist denied nearly every realistic exploration command, so reviewing agents gave up before ever writing a review.** `hosts/acp/permissions.js`'s deny-by-default execute gate (phase-36 item 36.1) denied any command containing `&&`, `|`, `;`, or a redirect outright, regardless of what the command actually was. A real reviewing agent's natural exploration style — `cd <dir> && find . | head -50 && echo "---" && cat file 2>/dev/null` — had every piece of that refused, and three of four peer-review workstreams in a real `devteam review` run gave up and asked for permission instead of writing `by-<role>.md`, cascading into missing gates and a `structural-input` halt with 0 findings.

  This was explicitly anticipated in the original design comment: *"if [this] turns out to make real reviews impractical, the fix is the exec_allowlist extension point or a narrower parse, not silently loosening the default."* Implemented that narrower parse rather than weakening the security model: a command is now split (quote-aware — handles an operator glued directly onto a preceding quoted argument or redirect with no space, e.g. `echo "---";next`) on `&&`/`||`/`;`/`|`, and **each resulting piece is validated independently** against the same read-only allowlist — a chain or pipe of read-only commands is itself read-only, by construction. `cd`, `echo`, `sort`, `head`, and `tail` were added to the allowlist (zero security cost — none can write or execute arbitrary code). A real file redirect (`>`, `>>`, `<`) or backgrounding (`&`) still denies the **entire** command outright; only filesystem-inert stream redirects (`2>/dev/null`, `2>&1`) are recognized as safe and skipped. Command substitution (`` ` ``, `$(...)`) is still denied unconditionally, unparsed.

  Verified against the exact commands a real ACP review dispatch produced and had denied: all now allow. Verified every pre-existing malicious pattern (`rm -rf`, `git checkout`, piping to a non-allowlisted binary, command substitution, `cd /tmp && rm -rf *`) still denies. 4 new tests in `tests/host-acp.test.js` (2 confirmed to fail without the fix); all 29 pre-existing tests in that file pass unchanged.

### Fixed

- **A `devteam review` run could still halt with `resolve-escalation` on `red-team` or `security-review`, not just `peer-review`.** The earlier fix that made a peer-review disagreement terminal in tracks with no build stage (`review-only`, `review-pr`) checked `stageDef.stage === "stage-05"` specifically — it only ever covered peer-review. Every other stage in those tracks has the identical characteristic: no build stage exists to act on its findings, so re-dispatching the same stage against unchanged code always reproduces the same must-fix findings, and escalating asks a human to rule on someone else's code the review was never going to change anyway. A real `devteam review` run against an external repo hit this exact wall on `red-team` (stage-04c) instead.

  `core/orchestrator.js#next()`'s check is now generalized to `!stageList.includes("build")`, independent of which stage it's evaluating — any track with no build stage treats a `FAIL`/`ESCALATE` gate as terminal for *every* stage in it, not one hardcoded name. Tracks with a real build stage (`full`, `quick`, `nano`, `loop`, `hotfix`, `dep-update`, `config-only`, `refactor`) are unaffected — verified explicitly for `red-team` there too.

  5 new tests in `tests/next.test.js` (3 confirmed to fail without the fix, one using the real halt message verbatim as a fixture) cover `red-team`/`security-review` FAIL and ESCALATE in `review-only`, a multi-stage progression to `pipeline-complete`, and the `full`-track regression check.

### Fixed

- **`README.md` was never writable by any role in the entire pipeline, and no Python project manifest file (`pyproject.toml`, `requirements.txt`, etc.) was writable either.** A real Python/FastAPI build's `design-spec.md` explicitly assigned `pyproject.toml` and `README.md` to `platform` (its acceptance criteria required both), but `build`'s `allowedWrites`/`roleWrites` only ever anticipated a JS/Node project shape — `package.json`, `tsconfig.json`, ESLint configs, `Dockerfile`. `platform` correctly refused to write outside its own authorized boundary rather than sneak around it, and QA could never pass acceptance criteria that depended on files nothing was ever allowed to create.

  `README.md`, `pyproject.toml`, `requirements.txt`, `requirements-dev.txt`, `setup.py`, `setup.cfg`, `Pipfile`, and `Pipfile.lock` now sit alongside the existing JS/Node project files in `build`'s stage-level `allowedWrites` and in `backend`'s and `platform`'s `roleWrites` — the same two roles that already carry `package.json`/`Dockerfile`/etc. 2 new contract tests (confirmed to fail without the fix).

### Fixed

- **A real headless `devteam run --track loop` on codex refused to build anything, citing `"pipeline/context.md is missing... creating it is outside this dispatch's allowed writes"` as a blocker.** `coding-principles.md` — read by backend/frontend/platform/qa/reviewer/security via their own Standing Rules — mandates appending `## Assumptions`/`QUESTION:`/`CONCERN:` entries to `pipeline/context.md` before the first `Write`/`Edit` of any build task, but `stages.js`'s `allowedWrites` for `build`, `pre-review`, `security-review`, `peer-review`, `qa`, `accessibility-audit`, `observability-gate`, `performance-budget`, `verification-sweep`, and `deploy` never listed it. claude-code masked this gap — its real permission grant is a blanket `Write(pipeline/**)`, broader than the advisory `allowedWrites` list it renders into the prompt — but codex's post-hoc write-audit enforces the literal list, so it correctly refused to follow its own mandated protocol, then refused to build at all rather than proceed with an unauthorized write.

  `pipeline/context.md` is now in `allowedWrites` (and each affected role's `roleWrites`, for `build`) on every stage whose dispatched role brief reads `coding-principles.md`. A new contract test (`tests/contract.test.js`, confirmed to fail without the fix) checks every stage/role combination generically, so a future stage or role gaining the same mandate without the matching write authorization is caught automatically instead of waiting for a live codex run to surface it. Two existing golden-snapshot tests (`tests/compact-qa-fold.test.js`) updated to reflect the intentional `allowedWrites` change for `accessibility-audit`/`observability-gate`/`performance-budget`.

### Fixed

- **A long-running claude-code subagent dispatch could silently self-truncate at claude's own internal 10-minute background-task ceiling, completely independent of `--timeout-ms`.** Every stagecraft role prompt says "Use the X subagent for this workstream" — claude-code dispatches that via its own Task tool. That subagent dispatch has an internal background-task ceiling (`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`, default 600000ms) that `core/adapters/headless.js`'s own `ctx.timeoutMs`/`DEFAULT_TIMEOUT_MS` has no visibility into or control over. When a subagent's turn ran long — a retry, a connection error, genuinely thorough verification work — claude silently terminated the wait and the top-level `--print` invocation exited anyway, reporting exit 0 with no gate: the exact "structural-input" failure ("clean exit, no output") the guard exists to catch, except here there *was* a real cause devteam never got to see (claude prints it to its own transcript: `Background tasks still running after 600s; terminating. Set CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0 to wait indefinitely.`). `--timeout-ms 0` ("wait indefinitely" at the devteam level) had zero effect on this — it's an unrelated mechanism that fired regardless.

  `runHeadless()` now propagates `ctx.timeoutMs` into whatever env var the adapter declares for this via a new `printBackgroundCeilingEnv` capability (`claude-code` → `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`; the only host declaring `capabilities.subagents: true`, so codex/antigravity/acp/omnigent are untouched), with `0` meaning "wait indefinitely" identically on both sides — matching devteam's own `timeoutMs: 0` convention. Never overrides a value already set in the environment.

  Verified against a real stuck run, not just synthetic tests: a `verification-beyond-tests` (stage-06d) dispatch that had hung 45 minutes and produced no gate under the old behavior completed cleanly in ~32 minutes with a real `WARN` gate once this fix was live — well past the 600s ceiling that used to cut it off. The same run then drove cleanly through `sign-off` → `deploy` → `retrospective` to `pipeline-complete` with zero further structural halts.

  4 new tests in `tests/headless.test.js` (2 confirmed to fail without the fix) cover: the env var being set to `ctx.timeoutMs`, `0` propagating as `"0"`, an operator-set value never being overridden, and no env override at all for a host that doesn't declare `printBackgroundCeilingEnv`.

### Fixed

- **A real `pre-review` dispatch on codex escalated after exhausting its retry budget: `"Python dependency vulnerability review is incomplete because pip-audit cannot resolve pypi.org on this host."`** codex's `workspace-write` sandbox blocks network access by default — confirmed directly from the codex binary's own embedded guidance ("In `workspace-write`, network access still depends on your Codex configuration (for example `[sandbox_workspace_write] network_access = true]`)"), and empirically: `curl https://pypi.org` failed to resolve under the stagecraft-configured sandbox and succeeded (HTTP 200) once the flag was added, same sandbox mode otherwise. `hosts/codex/capabilities.json` had already (incorrectly) declared `enforces.network: true` — without this fix that was aspirational, not actual: every codex-routed project's dependency-vulnerability scan, and any other network-dependent build step, was unconditionally broken, and no retry could ever fix an environmental constraint like this one.

  `hosts/codex/capabilities.json`'s `headlessCommand` now passes `-c sandbox_workspace_write.network_access=true`, enabling network access while keeping `workspace-write`'s filesystem restriction intact (a narrower grant than jumping to `danger-full-access`). 1 new test (confirmed to fail without the fix). Verified against the real project: `pre-review` re-dispatched after clearing the escalated gate.

### Fixed

- **A real `devteam run` on `hello-world-codex-loop` silently dropped `frontend` and `platform` from every `build` dispatch — including both retries — then exhausted its retry budget and escalated, because the same wrong role set could never actually fix what QA reported failing.** `inferActiveRoles()`'s `out_of_scope_items` keyword inference matched "frontend" in the requirements brief's "Frontend framework, build pipeline, or client-side routing" (scoping OUT heavy tooling, not frontend work entirely) and "infrastructure" in "... or cloud infrastructure" (scoping out deployment infra, not basic scaffolding like `pyproject.toml`/`README.md`), suppressing both roles from every build dispatch even though `design-spec.md`'s own `file_ownership` map explicitly assigned `src/frontend/**` to `frontend` and `pyproject.toml`/`README.md` to `platform`. QA then correctly failed on files that could never get built (missing `src/frontend/index.html`, `README.md`, `pyproject.toml`), and the driver kept re-running the same incomplete role set until the retry budget (2/2) was exhausted.

  `inferActiveRoles()` now takes design (stage-02)'s `file_ownership` map as an optional fourth argument: any role design explicitly assigns owned files to is exempt from the `out_of_scope_items` keyword-inference suppression, since design is a later, more specific refinement of the initial brief. This override applies only to the weaker keyword-inference path, never to an explicit `active_roles` decision — a PM decision that conflicts with design's `file_ownership` is a real conflict, not something to silently paper over.

  5 new tests in `tests/workstream-suppression.test.js` (the key case confirmed to fail without the fix — it suppressed both `frontend` and `platform`, not just the one keyword directly hit). Verified against the real project: `computeDispatchPlan` for `build` now includes all four roles instead of just `backend`/`qa`.

### Fixed

- **The same real headless `devteam run --track loop` on codex also cited `pipeline/design-spec.md` as an unconditional blocker** — "no implementation, lint run, or test run is possible against an absent approved design" — even though lean tracks (`quick`, `nano`, `loop`, `config-only`, `dep-update`) never run Stage 2 design, so its absence there is expected, not a defect. Build-role briefs assumed `design-spec.md` always exists with no fallback guidance for lean tracks; codex treated the gap as a hard blocker, claude-code happened to proceed anyway.

  `coding-principles.md` — read by every build role via Standing Rules — now says explicitly: on a track with no `design-spec.md`, treat `pipeline/brief.md`'s acceptance criteria as the authoritative implementation contract, note the fallback as an `## Assumptions` entry, and proceed rather than refuse or escalate. A new contract test (confirmed to fail without the fix) pins the guidance's presence.

### Fixed

- **`devteam review`'s findings report rendered `[object Object]` for every peer-review finding, `(no summary provided)` for every red-team finding, and silently dropped a passing security-review's own informational findings entirely.** `core/report/collect-findings.js`'s collectors assumed the exact field names each stage's own JSON schema documents (`summary` for a finding's description, blockers as plain strings) — but real gate output drifts from that in practice: a real `devteam review` run against an external repo produced a `stage-05.json` whose `blockers` were structured objects (`{id, area, severity, file, scenario, workstream}`, adversarial-mode reviewer objections) rather than strings, a `stage-04c.json` using `.scenario` for `must_address_before_peer_review` items and `.text` for `noted_for_followup` items instead of the schema's `summary`, and a `stage-04b.json` (security-review) with a fully-populated `noted_for_followup` array (modeled on red-team's own convention, which isn't in stage-04b's schema at all) that the collector never read — it only ever scanned `pipeline/security-review.md` for literal `BLOCKER:` lines, so a clean PASS with only informational notes surfaced zero findings despite carrying four.

  Two shared helpers — `describeItem()` (tries `.summary`/`.scenario`/`.text`/`.description`/`.claim` in order, passes a plain string through unchanged) and `fileLineFromItem()` (prefers an item's own `.file` field, including the `path:NN-MM` range form, before falling back to parsing the description text) — replace direct field access across every collector (red-team, security-review, peer-review, mutation, verification-beyond-tests). `mkFinding()` itself gained a last-line-of-defense guard so a future collector regression handing it a raw object degrades to the existing "(no summary provided)" placeholder instead of ever reproducing `[object Object]` again. `collectSecurityReviewFindings` now reads `gate.noted_for_followup` in addition to `BLOCKER:` lines, regardless of which one (or both) a gate happens to carry findings in.

  5 new tests in `tests/findings-report.test.js` (all 5 confirmed to fail without the fix) lock in each case using the real pegasus gate shapes verbatim, plus the defense-in-depth guard directly.

### Fixed

- **The C2 guard against claude-code's 4000-char headless prompt limit was dead code on every real dispatch — fixed at its actual composition point, and against the real constraint.** `core/orchestrator.js` always pre-composes the invocation prompt before dispatch — prepending `/goal "<goalCondition>"\n\n` for goal-loop hosts (claude-code, codex) — and hands that already-composed string to `core/adapters/headless.js`'s `runHeadless()` as `preRenderedPrompt`. The existing C2 fallback chain is gated on `!preRenderedPrompt`, so it never once ran in production — only in unit tests that call `runHeadless` directly. A dispatch carrying enough `patchItems` (the normal auto-fix/targeted-retry mechanism) to push the *composed* prompt over 4000 chars — even when the base role prompt alone was comfortably under — silently hit claude-code's "Goal condition is limited to 4000 characters" rejection, exit 0, no gate written, no error surfaced.

  The fallback chain now lives where the prompt is actually assembled: `core/orchestrator.js`'s `dispatchWorker`, via a new shared `core/adapters/render-helpers.js#shrinkComposedPrompt` (used by both call sites, so the drop-patchItems / drop-inlined-framework logic isn't duplicated). It tries, in order: drop `patchItems`, drop inlined framework content, drop the `/goal` directive itself.

  That last step turned out to matter more than expected. Reading claude-code's own binary (`strings` against the compiled executable) and confirming against the real CLI: the 4000-char check lives *only* inside the `/goal` slash command's own handler, measuring whatever text follows `/goal ` — in `--print` mode the whole piped stdin is one message with no way to separate "the goal" from "the rest of the prompt", so the check sees the entire composed string, not just the short `goalCondition` template. A plain prompt with no `/goal` prefix has no such ceiling at any size (verified directly: identical filler text with the prefix removed dispatches fine). The check is therefore skipped entirely when there's no `goalCondition` to prefix, and once the prefix is dropped as a last resort the dispatch simply proceeds — there is nothing left to enforce, so no further fallback or rejection is needed.

  Scoped precisely to the hosts that actually enforce this ceiling: a new `promptCharLimit: 4000` capability on `claude-code`, `codex`, and `antigravity` (the only three adapters that route through `runHeadless`'s CLI-pipe transport) — ACP, generic, openai-compat, and omnigent are untouched, since none of them share this constraint or even call `runHeadless`.

  Two tests in `tests/orchestrator.test.js` (a real headless dispatch through `runStageHeadless`, `DEVTEAM_HEADLESS_COMMAND=cat` to capture the exact bytes sent) cover the patchItems-drop recovery and the drop-the-/goal-directive-and-still-dispatch case; both verified to fail without the fix.

### Fixed

- **claude-code headless dispatches no longer silently stall once a prompt carries phase-37.2's inlined framework content.** `core/adapters/headless.js`'s "C2" guard against claude-code's `--print` mode 4000-char "Goal condition" limit (which rejects the prompt and exits 0 with no gate written — a silent, structural-input halt) only ever backed off `patchItems`. It never accounted for `prompts.inline_framework` (default `true` since 37.2), which inlines `AGENTS.md`, `.devteam/rules/*.md`, and the role brief — ~18-22 KB — directly into the prompt. Every claude-code headless dispatch past the first couple of stages was therefore guaranteed to exceed the limit regardless of `patchItems`, with no error surfaced.

  The fallback chain now backs off in order: drop `patchItems`, then drop the inlined framework/role-brief content (`core/adapters/render-helpers.js#shouldInlineFramework` gained a per-call `ctx.inlineFrameworkOverride === false` escape hatch, independent of `.devteam/config.yml`), and — if still over budget after both — reject with a clear error instead of spawning a dispatch that would silently no-op.

  Three new tests in `tests/headless.test.js` cover each branch of the chain (patchItems-only overflow, framework-only overflow, and the hard-reject case), verified to fail without the fix.

  Honest scope note: projects on `prompts.inline_framework: true` (the default) with a large `AGENTS.md`/rules set routed to claude-code headless may still want `inline_framework: false` set explicitly for that host — this fix stops the silent stall, but a run that leans on the fallback loses the cache-prefix benefit 37.2 was for on every affected dispatch.

### Fixed

- **A headless dispatch could end its turn with only a prose clarifying question and no gate at all, halting the run with a "structural-input" error indistinguishable from a crash.** A real `devteam run` sign-off dispatch on a `quick`-track promotion asked "What would you like me to do here?" instead of writing `pipeline/gates/stage-07.pm.json` — even though `roles/pm.md`'s own "Gate Writing Rules" already said to use `status: ESCALATE` when blocked, and `pipeline/context.md` already carried a `PRINCIPAL-RULING` resolving the exact ambiguity the model raised. Root cause: the composed stage prompt is entirely declarative (`## Objective`, `## Read first`, `## Allowed writes`, `## Artifact`, `## Gate to write`) with no imperative line telling the model this is a one-shot, non-interactive dispatch — it read as reference material rather than an actionable task.

  Two reinforcing fixes: `rules/gates-core.md` (read first by every role, every stage) gained a "Non-interactive execution: always write the gate" section explaining there is no human to answer a question, that `status: ESCALATE` with `escalation_reason` is the normal way to raise a blocking concern, and to check `pipeline/context.md` for an existing `PRINCIPAL-RULING` before escalating on something already settled. `core/adapters/render-helpers.js`'s `appendGateFooter` — shared by every host adapter, always the last thing rendered — repeats the same directive as the very last line before the gate JSON skeleton, for maximum recency.

  2 new tests (`tests/render-helpers.test.js`, `tests/contract.test.js`, both confirmed to fail without the fix) pin the directive's presence. Verified against the real failure: re-dispatching the same stage/role/track with the fix in place now produces a correct `PASS` gate with a genuine `signoff_basis` instead of a question.

### Fixed

- **A real `devteam run --track loop` halted with `(merge-failed) — reason: single-workstream stage; no merge needed` right after its one dispatched workstream (backend) passed.** `next()` correctly identified the completed workstream and asked to merge, but `mergeWorkstreamGates()` refused unconditionally for any stage with one dispatched role — even though `workstreamId()` already collapses a single-workstream stage's gate path to the bare `pipeline/gates/<stage>.json`, the same path the merged stage gate would use, so there's normally nothing left to merge by the time `next()` asks. The actual trigger: `roles/backend.md` (and `roles/frontend.md`) still hardcoded the multi-role `pipeline/gates/stage-04.<role>.json` suffix unconditionally in their "On a Build Task" procedure, so the dispatch wrote a role-suffixed gate instead of the bare one — and an already-`devteam init`'d project's installed role brief won't pick up a source fix until it's re-initialized, so the same stale write can still happen even after this fix ships.

  `mergeWorkstreamGates()` now handles the single-workstream case instead of refusing: if the bare stage gate already exists, treat the merge as a no-op success; if only a legacy role-suffixed gate exists, promote it to the stage gate path. `roles/backend.md`/`roles/frontend.md` now defer to the dynamic path stated in each dispatch's "## Gate to write" section rather than hardcoding a suffix that's wrong whenever a track collapses the stage to one workstream. A contract test from an earlier fix in this area was tightened to allow a *qualified* mention of the bare path (explaining the collapse) while still catching an *unqualified* one (the original drift class).

  3 new/updated tests (`tests/orchestrator.test.js`, `tests/contract.test.js`, all confirmed to fail without the fix). Verified against the real stuck project: `mergeWorkstreamGates` promoted its existing `stage-04.backend.json` to `stage-04.json` and the pipeline advanced to `qa`.

### Fixed

- **`devteam next`/`devteam run` stalled forever on a `loop`-track build even after the single dispatched workstream passed**, reporting `1/4 workstreams complete... remaining: frontend, platform, qa` for roles the `loop` track never dispatches in the first place. The multi-role completed/remaining computation used the static 4-role `stageDef.roles` matrix instead of `rolesForStage()` (which correctly narrows `build` to `["backend"]` on `loop`) — a fix already applied for `stage-05` (peer-review's own track-dependent role narrowing) but never generalized to `stage-04` (build), which varies by track in exactly the same way.

  Both affected spots in `core/orchestrator.js` (`next()`'s driving decision and `summary()`'s status display) now call `rolesForStage()` unconditionally instead of special-casing `stage-05` — a strict superset since `rolesForStage()` already falls back to `stageDef.roles` for every stage/track it doesn't special-case, so behavior elsewhere is unchanged. New regression test in `tests/next.test.js` (confirmed to fail without the fix) pins a `loop`-track build with only `backend`'s gate present resolving to `merge`, not `continue-stage` waiting on roles that will never run.

### Fixed

- **A `review_shape: "matrix"` peer-review stage no longer halts with a false "produced no gate" when it fully passed.** A matrix-shaped gate (e.g. `stage-05.<role>.json`) is derived from *sibling* workstreams' `by-*.md` review files via the idempotent rescan in `core/adapters/headless.js`, which runs at each workstream's own process close. The role that finishes first sees none of its later-finishing peers' review files yet and closes with `gatePath: null` — even though a slower sibling's own rescan, minutes later, derives and writes that exact gate as a side effect of finishing. That `null` was baked permanently into the early-finishing role's dispatch result, so `core/driver-dispatch.js`'s `wroteGate` check (every workstream needs a gate) evaluated false and the driver halted with `"structural-input"`, even though every gate on disk was `PASS`.

  `core/orchestrator.js#runStageHeadless` now re-checks disk once more after each dispatch wave settles — i.e. once every sibling in that wave has actually finished — for any clean-exit result still missing a gate, and patches it in if one materialized late. Scoped tightly to `exitCode === 0`, not timed out, not a stub gate, so a genuine no-gate failure still halts exactly as before.

  Two new tests in `tests/orchestrator.test.js` (real headless dispatch via `DEVTEAM_HEADLESS_COMMAND`, four concurrent roles) cover both the recovery case and the still-halts-on-a-genuine-failure case; the recovery test is verified to fail without the fix.

  Honest scope note: this recovers the gate *path* onto the dispatch result so the run doesn't falsely halt. It does not retroactively run the observed-usage/prompt-pack-version/tool-budget telemetry patches that normally stamp a gate as it completes — a late-recovered gate can end up missing `_orchestrator_observed` and similar stamps that its on-time siblings carry. Cosmetic, not blocking; a follow-up if the missing telemetry turns out to matter for corpus/eval analysis.

### Fixed

- **`roles/pm.md`'s "On a Sign-off Request" section told the model to write `pipeline/gates/stage-07.json` — the merged *stage* gate path — but PM's actual per-workstream gate (per `buildDescriptor`/`stages.js`'s `roleWrites`) is `pipeline/gates/stage-07.pm.json`.** Sign-off is a multi-role stage (`pm` + `platform`, each writing its own workstream gate that the orchestrator later merges); the role brief's prose never caught up to that split. A new contract test (`tests/contract.test.js`, confirmed to fail without the fix) checks every multi-role stage's role briefs for a hardcoded reference to the bare, unqualified stage gate path, so this class of drift is now caught for `build`, `peer-review`, and `sign-off` alike, not just this one instance.

### Fixed

- **A real build flagged `platform`'s gate FAIL over `"[write-audit] unauthorized write: pipeline/verification-receipts/<hash>.json"` — a file `platform` never touched.** That file is written by the orchestrator's own post-dispatch stamping step (`core/verify/runner.js#writeReceipt`), never by the dispatched agent, and the directory is shared across every workstream's own stamp step rather than scoped per-role — a concurrently- or previously-stamped sibling workstream's receipt can show up in a different workstream's own before/after write-audit diff. `isIgnoredRuntimeArtifact()` (already used for the same purpose with Python/test cache directories) now also excludes `pipeline/verification-receipts/`. 1 new test (confirmed to fail without the fix). Verified against the real project: re-dispatching the previously-affected workstream no longer flags the receipt file.

### Fixed

- **`devteam review`/`devteam review-pr` halted with `resolve-escalation` on any real peer-review disagreement, even though the disagreement was already fully captured as a finding.** `core/orchestrator.js#next()`'s peer-review retry/escalation logic assumes a build stage sits between retry attempts — the same reviewers see *different* code next time because a build workstream acted on their blockers. `review-only` and `review-pr` have no build stage at all (they exist specifically to review code the pipeline never touches). Retrying there just re-dispatches the same reviewers against the same, unchanged code, reproduces the identical disagreement, burns a full `retryDelayMs` wait for nothing, and then escalates asking a human to rule on someone else's code the review was never going to change anyway. The disagreement itself *is* the review's output — `core/report/collect-findings.js` already reads it straight from the merged gate's blockers and the `by-*.md` `CHANGES_REQUESTED` content, independent of what `next()` recommends.

  A `FAIL` or `ESCALATE` peer-review gate — including the case where an individual reviewer writes `ESCALATE` directly into its own workstream gate (`mergeWorkstreamGates` then propagates that to the merged gate) — is now terminal in any track with no build stage to depend on (checked generically via `!stageList.includes("build")`, so it covers any future read-only track too, not just `review-only`/`review-pr` by name): `next()` returns `pipeline-complete` instead of `resolve-escalation`, exactly like PASS/WARN. The gate file itself is untouched — still genuinely `FAIL`/`ESCALATE` for anything reading it directly (`devteam validate`, etc.) — only the orchestration decision changes. Tracks with a real build stage (`full`, `quick`, `nano`, `loop`, `hotfix`, `dep-update`, `config-only`, `refactor`) are unaffected — verified explicitly, peer-review still `fix-and-retry`s and eventually escalates there exactly as before.

  Six new tests in `tests/next.test.js` (3 confirmed to fail without the fix) cover: `review-only`/`review-pr` FAIL and ESCALATE both resolving to `pipeline-complete`, the gate file staying untouched, and `full` track's unchanged behavior for both statuses.

### Fixed

- **`devteam review` had no way to raise (or disable) the per-dispatch timeout, unlike `devteam run`.** Every dispatch is hardcapped at `core/adapters/headless.js`'s `DEFAULT_TIMEOUT_MS` (10 minutes) unless the caller overrides `ctx.timeoutMs` — `devteam run` has exposed `--timeout-ms` for this since it was added, but `core/cli/commands/review.js` never accepted or passed one through to `core/driver.js#run()`. A thorough adversarial/security-review stage over a large diff can legitimately run past 10 minutes; one real run was killed mid-`Write` while producing its final report, with no way to ask for more time short of editing `headless.js` directly.

  Added `--timeout-ms` to `devteam review`, threaded through to `runDriver({ timeoutMs })` exactly as `devteam run` already does — `0` disables the timeout entirely, matching `run`'s own contract. `docs/reference/cli.md` regenerated (`npm run docs:generate`) to pick up the new flag.

  Two new tests in `tests/review-command.test.js`: a dispatch that outlives a short `--timeout-ms` is killed (confirmed to fail without the fix — the flag was previously either silently ignored or rejected as unrecognized, so no transcript was ever produced to inspect), and `--timeout-ms 0` disables it entirely.

### Fixed

- **A real `hello-world-codex-loop` run escalated on `pre-review` over a genuine Starlette CVE, but `devteam next` reported an unrelated, stale "build" ruling as current — so `devteam fix-escalation` kept applying instructions about a completely different, already-resolved problem and never touched the real blocker.** `core/driver.js` injects an identical boilerplate `decision_needed` template on every convergence-exhausted escalation ("Add fix instructions to pipeline/context.md above devteam markers, then: devteam restart `<stage>` && devteam run"), and `devteam ruling`'s documented `--topic` auto-derivation echoes that same boilerplate into the ruling's own topic text. Since two convergence-exhausted escalations for completely different stages always shared this instructional filler, `devteam next`'s ruling-staleness check treated the token overlap as a real content match regardless of substance — the single most common escalation type in practice, effectively defeating staleness detection for it.

  `instructions`, `above`, `devteam`, `markers`, `then`, and `restart` now join the existing weak-token exclusion list used by that match. 1 new test reproduces the exact real-world data end-to-end through the CLI (confirmed to fail without the fix). Verified against the real project: `devteam next` now correctly reports the stale ruling doesn't match and asks for a fresh one targeting the actual gate.

### Fixed

- **The safety stoplist false-triggered on a brief that explicitly excluded the flagged topic**, halting a `--track loop` run on a hello-world app with no auth at all because its own out-of-scope paragraph said "It does not include authentication..." — naming the word was enough to trip the keyword match regardless of the negation right in front of it. `findStoplistMatches` now scans the full sentence around each candidate match for a negation cue (`does not include`, `out of scope`, `excludes`, `without`, `never`, etc.) in either direction relative to the keyword; a genuinely negated mention no longer counts, while any non-negated mention — including a later, different sentence — still triggers exactly as before. The "err toward false positives" bias documented in the file is preserved for real ambiguity.

- **The stoplist's remedy message told the user to run a command that doesn't exist.** `"Use /pipeline instead"` is a stale ghost-command reference — no `/pipeline` command exists anywhere in `devteam` (a prior sweep already replaced this exact class of leftover slash-command prose in `rules/`/`roles/`, but missed this file and two doc examples) — and is especially unhelpful in headless mode, where there's no chat surface to type a slash command into. Changed to the actual actionable instruction: `"Re-run with --track full instead."`

  6 new tests in `tests/stoplist.test.js` (all confirmed to fail without the fix). Verified against the real project's brief text that previously false-positived — the stoplist now clears.

- **All one-off model work now crosses the host-adapter invocation boundary.** Accessibility remediation, Principal rulings/escalation application, and the optional run-end Reflector previously contained core-owned `headlessCommand` parsing or model-process spawning paths. They now use `core/adapters/invoke-task.js`, which creates a narrowly scoped synthetic descriptor and calls the resolved adapter's existing `invoke()` transport. This gives those calls the same timeout, transcript, telemetry, HTTP/ACP support, and write-audit behavior as stage dispatches. Reflector output is an ephemeral allowlisted JSON file rather than captured process stdout, so HTTP-native and protocol adapters can participate without a CLI escape hatch. A regression test prevents those three core workflows from importing `node:child_process` or parsing a host command. Honest scope note: this restores the existing locked adapter boundary; it does not isolate the underlying in-place write audit or add a new adapter method.

- Add opt-in `pipeline.workstream_isolation: git-worktree` for parallel build roles. Each role starts from the same dirty/untracked-aware snapshot, runs in a detached worktree, and reconciles only authorized paths; clean text overlap is three-way merged while unauthorized writes, unsafe symlinks, and unresolved conflicts fail visibly.
- Clarify that feature artifact isolation (`pipeline.isolation`) and coding-agent checkout isolation are independent controls, and record the core-managed reconciliation contract in ADR-019.

**Honest scope note:** worktree isolation currently applies only to multi-role headless stage-04 builds in Git repositories. It is a correctness/attribution boundary, not an OS sandbox, and does not isolate peer-review fan-out.

### Added

- **`devteam run` now materializes `pipeline/run-plan.json` before any model dispatch.** The versioned plan records track provenance, the ordered preflight stage-disposition snapshot and skip reasons, candidate role/host/model routes, track-aware workstream counts, ceremony estimates, and a SHA-256 execution fingerprint. `--resume` reuses the original plan only when stable track/config/routing controls still match; changed configuration now fails with `ERUNPLANDRIFT` instead of silently changing an in-progress run. Dynamic right-sizing and conditional decisions are marked for runtime reevaluation. Terminal preflight output links the plan and shows its fingerprint.

### Changed

- **Ordinary feature assessment now defaults to the four-slot `loop` track instead of the 18-slot `full` track.** Specialized hotfix, dependency, config-only, nano, and quick signals retain precedence; explicit `--track`, track records, custom stages, and the factory `default_track` fallback for description-less runs are unchanged. Security-triggered code work on `loop`, `nano`, or `quick` now promotes to `full`, because none of those tracks includes security-review. See ADR-018.

- Raise the supported runtime floor to Node.js 22 after Node 20 reached end-of-life, test
  Node 22 and 24, deduplicate CI checks, collect informational coverage after merges, and
  cancel superseded runs.

- **OpenAI-compatible explicit cache markers now survive real orchestrated dispatch.** `runStageHeadless()` always passes a pre-rendered prompt to adapters, but `hosts/openai-compat/invoke.js` previously emitted its `cache_control` content blocks only when that argument was absent. With `hosts.openai-compat.caching.enabled: true`, `invoke()` now recovers the four layers when their joined text exactly matches the pre-rendered prompt; a transformed prompt remains a plain string so cache recovery cannot discard orchestration content. The regression test exercises the same pre-rendered third argument used by `devteam run`, rather than the adapter-only null-prompt path.

### Added

- Add cross-run/project `devteam performance calibration`, privacy-bounded track-fit feedback, cache and knowledge-selection counters, explicit Phase 41 readiness gates, and `devteam log --timeline` over durable execution events.

- **Bounded Project Knowledge Pack with evaluated learning.** Stage prompts now
  combine detected repository conventions, reviewed project patterns, and
  retrieved semantic history under one provenance-labeled knowledge block.
  `devteam init`, first stage use, and `devteam standards discover` maintain a
  fingerprinted `.devteam/knowledge/project.json` containing safe, compact stack
  and verification facts. Promoted patterns carry an evaluation window; guidance
  that reaches the configured recurrence threshold is quarantined from prompt
  selection until explicitly demoted, revised, and re-promoted. Lifetime counters
  and audit history remain intact. *Honest scope note:* non-recurrence is reported
  as observation, not causal proof, and semantic-memory retrieval remains
  headless-only and opt-in.

---

## [0.10.0] — 2026-08-05

### Fixed

- **Review-mode write targets now resolve into the workspace, not the subject (follow-up to phase-36 item 36.4, `plans/phase-36-external-review-mode.md`).** `core/adapters/render-helpers.js#appendGateFooter`'s `Write to pipeline/gates/<id>.json` line and `core/adapters/markdown-host.js`'s `Produce <artifact>` line were still *relative* paths even under the two-root split (36.1). A real ACP agent resolves a relative path against its own session cwd, which review mode sets to the subject (`ctx.processCwd`), not the workspace — so a real (non-scripted) agent following the prompt literally would either get the write denied (36.1's `codeRoot` check; safe but broken) or would need to infer the workspace's absolute path from context the prompt never gave it. Both now resolve through `resolveFrameworkPath()`, the same helper 36.2 already used for `readFirst` framework entries — byte-identical to today when `ctx.processCwd` is unset or equals `ctx.cwd` (every non-review run), absolute-into-`ctx.cwd` only when they differ. A literal `<name>` placeholder token (peer-review's `pipeline/code-review/by-<reviewer>.md`) survives the resolution unresolved, exactly as before. Four new tests in `tests/external-framework-paths.test.js` (verified to fail without the fix) cover: the gate path, the artifact path, placeholder survival, and the equal-roots byte-identical regression.

- **ACP peer-review dispatches now derive their gate from the review file, matching every other `hooks: false` host.** `hosts/acp/adapter.js` declares `clientCapabilities.fs = {readTextFile:false, writeTextFile:false}` at `initialize` — it has no claude-code-style PostToolUse hook, and until now never called `core/hooks/approval-derivation.js#deriveForProject` the way `core/adapters/headless.js` already does for codex/openai-compat. A real ACP-routed peer-review dispatch therefore had no automatic path from a `pipeline/code-review/by-<role>.md` review file to a derived `stage-05.<role>.json` workstream gate — stage-05's own gate schema documents that gate as "written by the approval-derivation hook only, never authored by an agent," a contract ACP silently didn't honor. Fixed by adding the identical `by-*.md` scan + `deriveForProject` call to `hosts/acp/adapter.js`'s dispatch-close handler, gated on `!timedOut`, idempotent — verbatim mirror of `headless.js`'s block. `tests/review-command.test.js`'s end-to-end test now exercises this directly: `tests/fixtures/acp-stub-review-agent.js` writes cross-review content into each role's `by-<role>.md` (backend reviews frontend/platform/qa, etc.) instead of hand-writing `stage-05.<role>.json`, and relies on the real derivation path to produce it.

  Honest scope note: wiring the second fix surfaced (and required respecting) a third pre-existing behavior — `deriveForProject`'s self-review guard (a reviewer's own area verdict in their own `by-<role>.md` is skipped, never derived, per `.devteam/rules/pipeline.md` §Stage 5). The test stub originally had each role review its own area, which silently produced zero approvals per area with real derivation on; fixed in the stub, not in `approval-derivation.js`, since the guard itself is correct and pre-existing behavior, not a gap.

### Added

- **Two-root permission model for the ACP host — phase-36 item 36.1 (`plans/phase-36-external-review-mode.md`).** `hosts/acp/permissions.js#evaluateToolCall` accepted a single `cwd`; it now also accepts `{ codeRoot, stateRoot, mode }`, the mechanical primitive a future external-review entry point needs to make "read-only review" an enforced guarantee rather than a prompt instruction. A bare cwd string still works exactly as before (`mode: "normal"`, one root doing double duty as both — byte-identical, no existing permission test was touched) — `hosts/acp/adapter.js`'s `invoke()` now builds this roots object every call (`codeRoot: processCwd, stateRoot: ctx.cwd, mode: ctx.externalReviewMode ? "review" : "normal"`), migrating the one production call site in the same commit rather than leaving two code paths.

  In `mode: "review"`: any `edit`/`delete`/`move` resolving inside `codeRoot` is denied outright — read-only, regardless of `allowedWrites` — with a reason naming read-only mode; writes under `stateRoot` are still checked against `allowedWrites` relativised to `stateRoot`; paths outside both roots stay denied, as today.

  **Closed the `execute` gap**, the substantive half of this item: `WRITE_KINDS` (`edit`/`delete`/`move`) never covered `kind: "execute"`, so a shell call (`sed -i`, `git checkout`, a build script) could mutate the subject under review with no check at all — while review genuinely needs shell for `rg`/`grep`/`git log`. In review mode, `execute` is now deny-by-default with a read-only allowlist (`rg`, `grep`, `git log`/`diff`/`show`/`status`, `ls`, `cat`, `find`, `wc`, extendable via `hosts.acp.review.exec_allowlist` in `.devteam/config.yml`), parsed to argv via the existing `core/command-line.js#parseCommandLine` — never substring-matched — with any redirection or shell metacharacter (`> >> | ; & $( \``) denied outright before the binary name is even looked at, since those decide what a *real* shell (the reviewing agent's own) would do with the command, not this evaluator. Deny reasons quote the offending command. `normal` mode's `execute` handling is unchanged — only the pre-existing dangerous-command stoplist applies.

  Tests (`tests/host-acp.test.js`): a same-descriptor, same-toolCall write into `codeRoot` denied in review mode / allowed in normal mode; a `stateRoot` write matching `allowedWrites` allowed, one not matching denied; a write outside both roots denied; `codeRoot` absent (36.5's diff-only review shape) falls through to the `stateRoot` check without crashing; `rg foo` allowed and `sed -i ...` denied in review mode while `sed -i ...` stays allowed (unrestricted) in normal mode; `rg foo > out.txt` denied (redirection), plus pipes/backgrounding/`$()`/backticks/semicolons denied even behind an allowlisted leading binary; `git` restricted to `log`/`diff`/`show`/`status` in review mode; the `exec_allowlist` config extension point adds to, not replaces, the defaults; a no-command `execute` call denies by default; `read`-kind calls stay ungated by location in review mode, matching normal mode (deliberately unclosed — see `plans/acp-read-scope.md`'s 36.0 caution note, needed for 36.2's absolute-framework-path mechanism); and one adapter-level wiring test (`adapter.invoke` with `ctx.externalReviewMode: true`) proving the same write is allowed with the flag off and denied with it on, not just the unit-level function. All 14 pre-existing `hosts/acp` permission/adapter tests pass completely untouched.

  Honest scope note: `ctx.externalReviewMode` is read by `hosts/acp/adapter.js` but set by no orchestrator path yet — 36.3/36.4 (review workspace + `devteam review`) are what will flip it on for real. The redirection/metacharacter check is deliberately conservative: it denies a character match anywhere in the raw command string, including inside quotes (e.g. `rg "a>b"` is denied), because this evaluator only ever grants *permission* — the command still runs in the reviewing agent's own shell, and a quote-aware parse here would have to correctly model that shell's quoting rules to stay safe. If that turns out to make real reviews impractical, the fix is the `exec_allowlist` extension point or a narrower parse, not silently loosening the default. As already flagged in `plans/phase-36-external-review-mode.md`'s 36.0 note, `read`-kind calls carry no location check in review mode either, by design — 36.2 depends on a review/build agent being able to read outside `codeRoot` — so this item does not make review mode read-only for `read`; it makes it mechanically write-and-execute-safe.

### Changed

- **docs(adr): ADR-017 (stage DAG waves) decided — Accepted, scoped to two named regions — phase-37 item 37.6.** ADR-017 sat at `Status: Proposed` since 2026-08-02, leaving `plans/phase-32-performance-parallelism.md` item 32.2 blocked and `full` paying 18 sequential stage slots against the project's own speed analysis naming ~13 as reachable. This is a decision-only item — no wave-execution code is added, per the item's explicit instruction not to implement in the same session as the decision.

  `docs/adr/017-dag-wave-execution.md` gains a `## Resolution (2026-08-05)` section: **Accepted**, exactly as scoped in the ADR's own Decision section — the two curated regions (`{stage-04a ∥ stage-04c}`, `{stage-06b ∥ stage-06c ∥ stage-06d ∥ stage-06e}`) with `autonomy.max_parallel_stages` defaulting to 2 (not 4, the larger region's size). The resolution also answers the ADR's three open "questions for a human reviewer" so none is left dangling: the conservative default of 2 stands absent corpus evidence on 4-way concurrent host/provider load; the `stage-04c` `readFirst` trim stays narrow rather than adopting phase-35's general artifact-tolerant-readFirst fix; and this ADR's authorization stays strictly the two named regions, with 32.6's implementation required to add a code comment on `dependsOn` stating that any future region needs its own curation pass.

  `plans/phase-32-performance-parallelism.md`: 32.2 marked complete (decided); a new item **32.6 "Stage DAG wave execution (implementation of accepted ADR-017)"** carries the concrete implementation scope (files, fields, and acceptance criteria) as a separate follow-up. `plans/README.md`'s phase table and "What is not delivered yet" section updated so 32.2/32.6 and phase-37's status agree with the ADR. Light-touch sync in `docs/adr/README.md` (index row), `docs/BACKLOG.md` (D11), and `plans/landscape-review-2026-07.md` (§5 roadmap table), which all quoted ADR-017's old `Proposed` status.

  Honest scope note: the decision resolves the ADR and scopes 32.6; it does not build `dependsOn`, `max_parallel_stages`, `wave_id`, or critical-path wave reporting. `full` still pays 18 sequential stage slots today — that only changes once 32.6 ships.

### Added

- **Adversarial reviewer/critic mode for stage-05 — Phase 31.3.** New `review.mode: "panel" | "adversarial"` config (default `panel`, byte-identical to today — no behavior change without opt-in). Adversarial mode replaces the four-area review matrix with exactly two sequential workstreams: a single **reviewer** covers every applicable area in one pass (`pipeline/code-review/by-reviewer.md`), then a **critic** — new role brief `roles/critic.md` — is dispatched only after the reviewer's gate lands and attacks the review itself: missed findings, unsupported approvals, and an explicit "what would make this approval wrong?" for every approved area, with file:line evidence required for every challenge. `core/hooks/approval-derivation.js` reuses `parseReviewFile()` verbatim for `by-reviewer.md` (rolled into one combined `stage-05.reviewer.json` gate rather than four per-area gates) and adds a parallel `parseCriticFile()`/`applyCriticVerdict()` for `by-critic.md`'s `challenges[]`/`challenges_resolved`; a challenge missing parseable `FILE:<path>:<line>` evidence is mechanically forced to `unresolved` regardless of what the critic wrote. `mergeWorkstreamGates()` surfaces `challenges`/`challenges_resolved` on the merged `stage-05.json`; the merge PASSes only when the reviewer gate PASSes AND `challenges_resolved` is true — an unresolved challenge blocks the stage regardless of the reviewer's own approval.

  Routing: `core/config.js#resolveHost` defaults the critic to a different host than the reviewer when ≥2 hosts are configured anywhere in `routing` (collusion counter-measure — 2026 evidence cited in `plans/phase-31-verification-depth.md` §31.3 found review panels underperform and are collusion-prone relative to an adversarial reviewer/critic pair); `routing.roles.critic` overrides. Mutually exclusive with `routing.review_fanout` per run — adversarial mode wins if both are configured.

  Scheduling: `core/scheduler.js`'s `mapByHostConcurrency` has no dependency-ordering primitive (only per-host concurrency caps — confirmed via `[verify-first]`, ADR-015 flags DAG-wave ordering as unimplemented future work). Implemented per the plan's documented fallback — "two orchestrator steps": `core/orchestrator.js#dispatchWavesFor` splits adversarial stage-05 into a reviewer wave and a critic wave inside `runStageHeadless`, awaiting the reviewer wave's `mapByHostConcurrency` call before starting the critic's, so the critic always sees the reviewer's completed file. Every other stage (and panel-mode stage-05) gets a single wave — identical to pre-31.3 behavior. `next()`/`_nextImpl`'s completed/remaining bookkeeping for stage-05 now resolves the actually-dispatched role list via `rolesForStage(stageDef, track, config)` instead of the static 4-area list, so adversarial mode's `stage-05.reviewer.json`/`stage-05.critic.json` gates are recognized and the stage can reach `merge` — panel and nano tracks are unaffected (`rolesForStage` returns the same role list they already used).

  Tests: `tests/adversarial-review.test.js` — `rolesForStage`/`computeDispatchPlan` return `["reviewer","critic"]` only under `review.mode: adversarial`; `dispatchWavesFor` splits into two waves for adversarial stage-05 and returns a single unchanged wave for every other stage/mode; `parseCriticFile`/`applyCriticVerdict` (unresolved challenge → FAIL, resolved → PASS, missing evidence forced unresolved); `applyAdversarialReviewerFile` (approved areas → PASS, a changes-requested area → FAIL); `resolveHost` cross-host default for critic (1 configured host → no diversity; ≥2 → different host; explicit `routing.roles.critic` always wins); merged-gate stubbed flow (reviewer PASS + critic unresolved → merged FAIL; reviewer PASS + critic resolved → merged PASS) via seeded gates, mirroring `tests/pipeline-e2e.test.js`'s style. Full existing suite (`tests/fanout.test.js`, `tests/approval-derivation.test.js`, `tests/next.test.js`, `tests/pipeline-e2e.test.js`, `tests/schemas.test.js`) re-run unchanged to confirm panel mode stays byte-identical.

  Honest scope note: the critic's `disposition` field is written by the critic itself (there is no second-round "someone else confirms the fix" step in this phase) — a critic marking its own challenge `RESOLVED` on a re-run is trusted, the same trust model panel-mode reviewers already operate under for `REVIEW: APPROVED`. Combining `review.mode: adversarial` with `routing.review_fanout` is not supported (adversarial mode silently wins); a future phase could define what N-host adversarial fanout even means. `core/orchestrator.js`'s experimental Omnigent-director path was not extended for adversarial stage-05 — it already requires every workstream to route to the `omnigent` host, which is orthogonal to this item's host-diversity goal.

### Added

- **`devteam run` assesses inline when no track is decided — phase-29 item 29.2 (ADR-016, supersedes [ADR-006](../docs/adr/006-track-inference-under-autonomy.md) §1).** When `devteam run` starts with no `--track`, no `pipeline/track.json`, and no `pipeline.custom_stages`, and there is a `--feature`/description to assess, `core/driver.js`'s `resolveTrack` now calls the same `assess()` heuristic `devteam assess` uses (`core/stage-shopping/assess.js`) — at *any* confidence level, not just the "high"-only downgrade the pre-existing `right-sizing.md` behavior shipped — and returns the result with `source: "inferred"`. `run()` persists that decision to `pipeline/track.json` itself (`assessed_by: "devteam run <version> (assess-inline, ADR-016)"`), so the file `devteam assess` would have produced exists regardless of whether an operator ran it first; the unchanged `checkTrackConfidence` guard (ADR-006 §3/4) still warns or halts on medium/low confidence exactly as it does for a hand-run `devteam assess`. `--track` always wins and records `source: "human"`; an existing `pipeline/track.json` is never re-assessed or overwritten. `core/cli/commands/run.js` prints the recommendation, its reasons, and — until [29.3](../plans/phase-29-scale-adaptive-ceremony.md) lands the token/cost ceremony estimate — the stage-slot/dispatch counts already computed for the run plan, with a `TODO` citing 29.3. No interactive prompt anywhere; behavior is identical in CI and interactive use. Docs: `docs/tracks.md`, `docs/adr/016-assess-by-default.md` (new), `docs/adr/006-track-inference-under-autonomy.md` (addendum), `docs/adr/README.md`. Tests: `tests/run.test.js` — inline-assess writes `pipeline/track.json` and resolves the expected track/confidence; `--track` overrides and writes no file; a pre-existing `pipeline/track.json` is untouched byte-for-byte; a CLI-level "snapshot" test of the printed recommendation/rationale/ceremony-count/TODO block and the resulting `pipeline/track.json` contents. Honest scope note: `assess()` cannot recommend the `loop` track (phase-29 item 29.1) — its heuristic only returns `hotfix | dep-update | config-only | nano | quick | full`, so a `loop`-shaped change (e.g. a one-paragraph feature) will still be inferred as `quick` or `full` rather than `loop`; teaching `assess()` about `loop` is out of scope for this item. Also out of scope: the ceremony *cost* estimate (token/dollar range) that 29.3 is meant to add in place of today's slot/dispatch-count placeholder, and rendering the recommendation in `--watch` mode (the watch renderer has its own compact format and does not currently surface `assess_inline`).

### Added

- **Attestation export: gate chain → in-toto-Statement-shaped signed evidence bundle — phase-34 item 34.2 (`docs/evidence.md` "Attestation export").** `devteam evidence export --attestation [--out <file>] [--sign] [--allow-unverified] [--track <t>]` productizes the existing Phase 16–18 evidence subsystem and the C6/ADR-011 gate chain into a full per-stage-fidelity proof of ONE run/commit — the opposite shape from `evidence export`'s privacy-preserving cross-run aggregate, and never mixed with it. `core/evidence/attestation.js` runs `verifyChain` first and refuses to attest a broken chain unless `--allow-unverified`, which proceeds anyway and stamps `predicate.unverified: true` with the full `chain_verification` detail rather than hiding the problem. `predicate.stages` carries one entry per stage gate: per-field provenance distinguishing model-asserted values from orchestrator-observed/stamped ones (reusing the `_orchestrator_observed`/`model_requested` convention `core/orchestrator.js` already established), the C4 reproducibility fingerprint via `core/reproducibility.js`'s existing `reproducibilityFingerprint` (not reimplemented), `prompt_pack_version` (33.3) when present, this gate's chain-hash linkage plus HMAC presence (never the raw HMAC value), and C6/Phase-2 `resolved_by` authority-resolution provenance when applicable. `predicate.resolutions` lists every ADR-012 accepted fix/retry resolution from the run log as its own entry. `subject` is the commit(s) the run produced — `auto-commit` run-log events when present, falling back to the current git `HEAD` for the common manual-commit workflow.
  - **Schema (`core/evidence/schemas/attestation.schema.json`).** A checked-in, strict, closed JSON Schema mirrors `validateAttestation`'s hand-rolled reader (same house convention as `evidence-export.schema.json`/`bundle.js` — no ajv dependency added); every emitted bundle is validated against it before being written, and `payload_sha256` (canonical-JSON digest, the same technique `core/gates/chain.js`/`core/evidence/bundle.js` already use) lets `devteam evidence verify-attestation <bundle>` offline re-check both schema conformance and tamper evidence without touching the live pipeline.
  - **`--sign`.** Shells to `cosign sign-blob --output-signature <file>.sig <file>` only when `cosign` is found on PATH (probed the same way `core/verify/redteam-floor.js` probes for `semgrep`); a missing or failing `cosign` exits non-zero with a clear error, but the attestation bundle itself is still written first — signing is a best-effort layer on top of an already-valid, already-useful bundle. Stagecraft never bundles or manages signing keys.
  - Tests (`tests/attestation.test.js`, 18 cases): schema-valid bundle from a fixture pipeline; per-field provenance and C4 fields on stage entries; orchestrator-observed vs model-asserted divergence; ADR-012 accepted resolutions appear as their own entries; broken-chain refusal and the `--allow-unverified` escape hatch; no-producible-commit refusal; write/read round-trip and tamper detection via the payload digest; full CLI coverage of `export --attestation` and `verify-attestation`; `--sign` against a stubbed `cosign` on PATH, a cosign failure, and cosign's absence.
  - Honest scope note: "in-toto-Statement-shaped", not in-toto/SLSA-compliant — `predicateType` is Stagecraft-namespaced (`urn:stagecraft:attestation:1.0`), not a registered SLSA/in-toto predicate, and `payload_sha256` is a Stagecraft-local tamper check, not a DSSE envelope. `--sign` produces a detached `cosign` signature file alongside the bundle rather than an embedded DSSE signature. Signing-key management (cosign keyless/KMS/Fulcio setup) is entirely the operator's responsibility, per the phase-34 plan's explicit scope boundary. Subject-commit resolution requires a git repository with at least one commit; a project with no commits and no `--auto-commit` history cannot be attested yet.

### Added

- Record autonomous `skip-stage` audit events for configured and conditional skips, and add `pipeline.force_stages` to override skip decisions when an operator needs the stage to run.

- **`--budget-usd` prefers orchestrator-observed cost (phase-28 item 28.4).** `core/driver.js`'s cost total (`costUsdDetail`, backing `totalCostUsd`) now prefers each gate's `_orchestrator_observed.cost_usd` (written by items 28.1–28.3) over the model-asserted top-level `cost_usd`, falling back to the model's self-report only when no observed figure exists. The budget cap, heartbeat `cost_usd_so_far`, and the final run summary all read through this. A `cost_basis` (`"observed"` / `"model-asserted"` / `"mixed"` / `null`) is recorded once per run onto both the returned summary and `run-state.json`, and `devteam status` / `devteam report` (JSON and HTML) display it next to the cost figure. A single run-log `cost-basis-warning` event fires the first time any model-asserted value is included in the total, rather than once per heartbeat. Halt semantics and the pre-dispatch budget check itself are unchanged (ADR-003 refinement of decision #8 stands) — only the cost figure they compare against is now trust-boundary-correct. *Honest scope note:* `dispatchObservation`'s per-dispatch telemetry event (feeding the future run corpus, item 28.5) still records only the model-asserted `cost_usd` — updating it to prefer observed cost is follow-up work, tracked alongside 28.5.

### Added

- **Cache-first prompt assembly — Phase 32.1.** Every `renderStagePrompt` implementation (`core/adapters/markdown-host.js` — shared by codex/gemini-cli/openai-compat/antigravity/omnigent — plus `hosts/claude-code/adapter.js` and `hosts/generic/adapter.js`) now assembles the stage prompt in a fixed four-layer order: (1) framework preamble/rules (`core/pipeline/stages.js`'s new `FRAMEWORK_READ_FIRST` — the constant `AGENTS.md` + rule-file prefix every dispatched stage's `readFirst` already shared), (2) role brief (the role-prompt pointer, or the inlined brief itself for the `generic` adapter), (3) learned context (Known Project Patterns + Prior Project Knowledge, unchanged content, just repositioned), (4) the volatile tail (stage header, objective, the stage-specific `readFirst` remainder, changed-file manifest, allowed writes, gate shape). Layers 1–2 are now byte-identical across every dispatch in a run that shares the same role — the prefix providers/CLIs can cache automatically. Each adapter also exports `renderStagePromptLayers()`, returning the per-layer text alongside the full joined string, for callers that need the layer boundaries (e.g. cache_control placement).

  For `openai-compat` against Anthropic-compatible endpoints, opt in via `hosts.openai-compat.caching.enabled: true` — `invoke()` then sends the prompt as separate content blocks with `cache_control: {type: "ephemeral"}` after layers 1–3 (empty layers, e.g. no learned context yet, are dropped rather than sent as empty blocks; the volatile tail never carries a breakpoint). OpenAI-style endpoints need no config — they get prefix caching for free from the stable ordering alone. `cached_tokens`, when the API reports it under `usage.prompt_tokens_details`, continues to be recorded via the existing phase-28.2 mechanism onto the gate's `_orchestrator_observed` block.

  Tests: `tests/prompt-layout.test.js` — `splitReadFirst`/`renderFrameworkPreamble` unit coverage; a meta-test asserting every dispatched stage's `readFirst` starts with `FRAMEWORK_READ_FIRST`; the prefix-stability regression (two different stages, same run, same role → layers 1–2 byte-identical, layers 3–4 legitimately differ) across every adapter that exposes `renderStagePromptLayers`; `buildCacheAwareContent` fixtures for breakpoint placement and empty-layer dropping; an `invoke()` fixture proving `cache_control` content blocks are only sent when `caching.enabled` is true, plain-string content otherwise. Reordering required no changes to any pre-existing test — the full suite (`npm test`, `CI=true DEVTEAM_HEADLESS_COMMAND=cat npm test`) stayed green throughout, and `docs/reference/prompt-budget.md` regenerated byte-identical (the generator sources stage/role file sizes directly, independent of rendered-prompt section order).

  Honest scope note: `renderStagePromptLayers()`'s layer-3 "learned context" is only *positioned* as constant-per-run — its actual content (`descriptor.knownPatterns` / `descriptor.priorKnowledge`) is still selected per stage/workstream by phases 30/31's existing retrieval logic, so it can legitimately vary dispatch-to-dispatch within a run; only layers 1–2 carry the byte-identical guarantee the regression test checks. Claude Code, Codex, Gemini CLI, Antigravity, and Omnigent get the ordering benefit only (whatever automatic prefix-caching their own CLI/API already does); Stagecraft has no hook into those CLIs' own request construction to add explicit cache breakpoints there. `cache_control` support is opt-in and unverified against a real Anthropic-compatible proxy in this change — the fixture stubs `fetch`, so the request shape is proven, not a live cache hit.

### Added

- **Per-track ceremony cost preview — phase-29 item 29.3.** `devteam assess` (text + `--json`) and the top of `devteam run` pre-flight output now print a per-track estimate before any dispatch: stage slots, dispatch count (`{min, max}` — `min` excludes stages that are conditional at runtime, e.g. `stage-04b` security-review, `stage-04d` migration-safety), a token range, and a cost range, all under a new `core/ceremony-preview.js`. Two estimate sources, always labelled via `estimate_basis` (house honesty rules — every number is an explicit estimate, never presented as a bill):
  - **`"static"`** (default): tokens come from the same per-dispatch framework-overhead numbers `scripts/prompt-budget.js` generates into `docs/reference/prompt-budget.md` — read via its `computeStageStats()` machine source, not the rendered doc — plus the real on-disk byte size of any `pipeline/*` artifact a stage's `readFirst` would load (the gap `prompt-budget.js` itself deliberately leaves as "project-dependent, unknown at analysis time"). Cost requires a model; since a routed *host* (e.g. `claude-code`) is a CLI adapter, not a model, the actual model is only ever known from orchestrator-observed telemetry. The static path resolves "currently-routed model" per `(role, host)` as the most recent `model_observed` for that pair in `.devteam/corpus/dispatches.jsonl` (28.5) — independent of the empirical run-count threshold below. If *any* dispatch's model can't be resolved this way, the whole track's `cost_usd` is `null` (never a partial, misleadingly-precise total) and the unresolved `role@host` pairs are listed in `unresolved_models`.
  - **`"empirical"`**: once the corpus has ≥5 completed runs (`run_id`) of the exact same track, tokens/cost are the median observed totals across those runs instead of the static formula.
  `devteam run`'s pre-flight `run-plan` event now carries `ceremony_preview`, computed against the same right-sized stage list `summarizeRunPlan` already derives (respects `pipeline.skip_stages` and right-sizing skips), so the estimate matches what will actually dispatch; this replaces the `TODO: cost estimate — plans/phase-29-scale-adaptive-ceremony.md 29.3` placeholder line 29.2 shipped. Computing the preview is advisory-only (wrapped in `try/catch` in both `devteam assess` and `core/driver.js`) — a preview failure never blocks a run or an assess recommendation. Tests: `tests/ceremony-preview.test.js` (static estimates for `loop`/`quick` with no corpus history; model resolution from a single sub-threshold corpus record; unknown-model path never invents a partial dollar figure; on-disk artifact sampling widens the token range; empirical-basis median switch at the 5-run threshold and its two negative cases; `devteam assess` `--json`/text surfacing); `tests/run.test.js` updated (the 29.2 "TODO" placeholder assertion now asserts the real `Ceremony estimate (static): ... — (unknown model)` line, since the fixture has no corpus history).
  Honest scope note: the static estimate does not model stage-01 `active_roles` suppression or per-workstream right-sizing beyond the stage-level skips `summarizeRunPlan` already applies — it assumes every track-shape role dispatches, so a run that later suppresses e.g. an inactive `frontend` workstream will come in under the static estimate, never over. `devteam assess` (no run context) always uses the nominal track shape; only the `devteam run` pre-flight path narrows to the right-sized stage list.

- **Orchestrator-observed token/cost telemetry for claude-code (phase-28 item 28.1).** The claude-code headless command now requests `--output-format stream-json --verbose`; `core/adapters/headless.js` parses the resulting stream for the final result message's `usage`/`total_cost_usd`/model, tees only the readable text (not raw JSONL) into `pipeline/logs/<workstreamId>.log`, and the orchestrator writes `tokens_in`/`tokens_out`/`cost_usd`/`model_observed` onto the workstream gate under `_orchestrator_observed` — distinct from and never overwriting the model's self-reported `tokens_in`/`cost_usd`/`model` fields. If the CLI's output isn't parseable JSON, the dispatch degrades to today's plain-text behavior with `telemetry: "unavailable"` and no gate mutation — a telemetry parse failure never fails a dispatch. *Honest scope note:* this covers claude-code only; codex, gemini-cli/antigravity (items 28.2/28.3), and `--budget-usd`/`devteam status` preferring observed cost over self-reported (item 28.4) remain follow-up work.

### Added

- **Compact-QA fold on `quick` — phase-29 item 29.4.** Tracks flagged `compact_qa` (currently just `quick`) now dispatch a single combined `verification-sweep` stage (`stage-06x`) instead of one dispatch per specialty-QA stage they include. On `quick` this folds `accessibility-audit` (06b) and `performance-budget` (06e) — the two of the four specialty-QA stages (`accessibility-audit`/06b, `observability-gate`/06c, `verification-beyond-tests`/06d, `performance-budget`/06e) `quick` actually lists — into one dispatch, same PASS/FAIL bar per section, one gate instead of two. `full` and `hotfix` are untouched: they aren't flagged `compact_qa`, so they keep dispatching all applicable specialty-QA stages standalone. Implementation: `core/pipeline/stages.js` gains a new `"verification-sweep"` stage definition, `isCompactQaTrack()`/`foldQaSweep()`, and applies the fold inside `orderedStageNamesForTrack()` — the single call site every consumer (driver dispatch, `verifyChain` predecessor derivation, right-sizing, `devteam assess`/ceremony-preview) already goes through, so `devteam next`/`merge`/`summary` handle `stage-06x` like any other stage with no further changes. `STAGES_BY_TRACK` itself is untouched — it stays the declarative "which specialty QA does this track need" answer; folding is a presentation-layer transform. New schema `core/gates/schemas/stage-06x.schema.json` embeds the four existing stage-06[b|c|d|e] shapes as optional, individually-`$ref`'d sections behind a `sections_included[]` discriminator — a document with any subset of the four populated (the folded form) validates, and the four original schemas are unchanged (the unfolded form full/hotfix still produce). Right-sizing (`core/pipeline/right-sizing.js`) skips the folded slot only when none of the four constituent triggers fire, mirroring how each standalone stage was skipped independently before.
  Tests: `tests/compact-qa-fold.test.js` (fold mechanics; full-track stage definitions + rendered prompts are byte-identical to their pre-29.4 shape; stage-06x schema accepts both the folded and unfolded gate shapes; right-sizing skip logic for the combined slot); `tests/pipeline-e2e.test.js` (new `quick` track e2e: exactly one `verification-sweep` dispatch where it previously made two, single `stage-06x.json` gate on disk carrying both sections); `tests/performance-budget.test.js` and `tests/run.test.js` updated — both encoded `quick`'s pre-fold track shape (performance-budget dispatching standalone, a 2-item right-sizing skip list) and needed to reflect the fold.
  Honest scope note: the plan item's acceptance text ("quick-track stubbed run makes 1 dispatch where it made 4") describes the aspirational four-section fold; `STAGES_BY_TRACK.quick` has only ever listed two of the four specialty-QA stages (`accessibility-audit`, `performance-budget` — not `observability-gate` or `verification-beyond-tests`), so the actual, verified change is 2 dispatches folded into 1. The fold mechanism (`foldQaSweep`) is generic over however many of the four a `compact_qa` track lists, so a future track that includes all four would get the full 4-in-1 fold with no further code change. Auto-remediation (`core/a11y-fixer.js`), the per-stage fix-recipe registry (`core/pipeline/fix-recipes.js`), and the dashboard's stage-specific renderers (`core/report/`, `core/ui/static/app.js`) still key off the standalone `stage-06b`/`stage-06c`/`stage-06d`/`stage-06e` gate files and are not wired to the folded `stage-06x` shape — out of scope for this item (see the final report's Out-of-scope findings).

### Added

- **Control mapping documentation — phase-34 item 34.3 (`docs/compliance.md`).** A table
  mapping compliance control families (change approval, segregation of duties, testing
  evidence, security review, deployment control, tamper evidence) to the exact pipeline
  artifact and runnable command that produces/verifies it today: `pipeline/gates/stage-07.json`
  + `devteam verify-chain` / `devteam evidence verify-attestation` for change approval; the
  base gate schema's `host` field for per-role dispatch provenance; stamped `stage-04a`/`stage-06`
  gates plus `pipeline/verification-receipts/` for testing evidence; the Phase 31.2 mechanical
  red-team floor on `stage-04c` for security review; `CONSEQUENCE_CEILING`/`--allow-stage`
  ceiling-halt events for deployment control; and ADR-011 chain hashes/HMAC plus the Phase 34.2
  attestation bundle for tamper evidence. Scoped explicitly as "evidence your auditors can map,
  not certified compliance." Linked from `docs/README.md`'s Evaluator section and `README.md`'s
  documentation map.
  - Honest scope note: `stage-04b` (the conditional `security-review` stage, which actually
    carries veto power) is deliberately called out as model-asserted only — it is not in
    `STAMPABLE_STAGES`, so it has no orchestrator-run mechanical check today. Segregation of
    duties is verifiable (per-workstream `host` fields) but not mechanically enforced: an
    operator can still route reviewer and author to the same host without Stagecraft blocking
    the run, except for the adversarial-mode critic, which auto-diverges from the reviewer's
    host when ≥2 hosts are configured (31.3). No code changed; docs only.

### Added

- **`pipeline/context.md` diet: byte budget + auto-compaction, and a per-workstream context-changes delta — phase-32 item 32.5 (`plans/phase-32-performance-parallelism.md`).** Verify-first confirmed `context.md` grows via `devteam:*` marker sections written by `core/gates/validator.js` (red-team-blockers, qa-build-blockers) and `core/driver.js` (run-blockers, right-sizing, deploy-target), that `devteam compact` unconditionally strips every marker section (unchanged by this item), that every dispatched stage's `readFirst` only ever points at the whole file (never inlines it), and — new finding — that no event previously recorded a marker section write/strip, so that was added first as its own commit. New `core/context-log.js` (`logContextSectionEvent`, fire-and-forget) records every marker add/remove to `run-log.jsonl` as a `context-section-change` event. New `pipeline.context_budget_bytes` config (default `8192`) is enforced by new `core/context-budget.js` right after every marker write: over budget, the oldest RESOLVED marker section (in document order; a section is "resolved" only when this module has a rule mapping it to a stage gate whose status is PASS/WARN — currently `right-sizing`→stage-01, `deploy-target`→stage-08, `red-team-blockers`→stage-04c, `qa-build-blockers`→stage-04.qa) is replaced with a one-line digest pointing at its full text, archived append-only under `pipeline/context-archive/<ts>-<section>.md`. New `core/context-delta.js` (`computeContextDelta`) derives, purely from `run-log.jsonl` history, which sections changed since a workstream's *own* previous dispatch (correct across retries — only counts events after that workstream's most recent prior `workstream-started` event); `core/orchestrator.js`'s `plan()` computes it per workstream and threads it onto the descriptor, and a new `renderContextDelta` (`core/adapters/render-helpers.js`) renders a "## Context changes since your last dispatch" section in every host adapter's volatile-tail layer (`core/adapters/markdown-host.js`, `hosts/claude-code/adapter.js`, `hosts/generic/adapter.js`) — omitted on a workstream's first-ever dispatch or when nothing changed. `core/markers.js` gained `parseSections` (promoted out of `core/cli/commands/compact.js`, which now imports it) so both the manual compactor and the new budget auto-compactor walk the same section-parsing logic.
  - Tests: `tests/context-log.test.js` (event shape, fire-and-forget, changeId-scoping, validator/driver call sites), `tests/context-budget.test.js` (under-budget no-op, resolved-section compaction + archive round-trip, unresolved/no-rule sections survive arbitrarily over budget, multi-section compaction order, idempotent re-run, missing-file no-op), `tests/context-delta.test.js` (first-dispatch null, cross-workstream isolation, retry-sequence correctness, changeId scoping, malformed-line tolerance), `tests/render-helpers.test.js` and `tests/orchestrator.test.js` (delta section rendered/omitted end-to-end through `runStage`), `tests/config.test.js` (`context_budget_bytes` default/override/invalid-value fallback).
  - Honest scope note: event logging and budget enforcement are wired only into the writers the verify-first claim named (validator.js, driver.js) — `core/advise.js`'s `devteam:advise` section and `core/cli/commands/restart.js`'s generic strip are not instrumented, so advise-authored growth isn't tracked or auto-compacted (still fully covered by manual `devteam compact`). "Resolved" detection is a static 4-section allowlist keyed to a single gate file each; any other marker section (present or future) is always treated as active and never auto-compacted, so budget pressure from those never self-relieves. "Oldest" is document order, not a true write timestamp (none is recorded per-section), so it's an approximation for sections written via `insert: "prepend"`. `pipeline/context-archive/` was not added to ADR-010's canonical `.gitignore` block (`core/gitignore.js`) — out of scope for this item since it means editing an accepted ADR; a follow-up should add `pipeline/context-archive/` and `pipeline/changes/*/context-archive/` alongside the existing `pipeline/gates/archive/` entry.

### Added

- Added `devteam performance critical-path`, a run-log based report for dispatch wall time, merge time, retry delay, workstream compute, parallel savings, telemetry coverage, and repeated verification-command candidates.
- Persisted `dispatch-started`, `merge-started`, `merge-finished`, and retry `delay_ms` events so critical-path reports do not depend on model-authored claims.

- **Escalation guidance now ignores stale Principal outputs.** `devteam next` no longer treats any prior `PRINCIPAL-RULING:` or `PRINCIPAL-CANNOT-DECIDE:` line in `pipeline/context.md` as proof that the current escalation has been resolved. It checks whether existing Principal outputs match the active escalating gate, lets a newer matching ruling supersede an earlier cannot-decide line, and tells the operator to run `devteam ruling --target-gate ...` before `devteam fix-escalation` when nothing matches.
- **Escalation applicators can now keep documentation-only fixes.** `devteam fix-escalation` now permits README, CHANGELOG, `docs/`, and `changelog.d/` writes when a Principal ruling asks for documentation remediation, and unauthorized applicator writes fail the command instead of being removed while still reporting success.
- **Stage 8 now has a no-config local deploy default.** Projects that omit `deploy.adapter` receive a `local` adapter instead of an escalation: Stage 8 records local/in-place verification, marks `adapter_result.external_deploy: false`, and keeps concrete publish targets opt-in. If Stage 7 records `deploy_requested: false`, the orchestrator now writes the local/no-external-deploy Stage 8 gate and deploy log directly instead of dispatching a deploy agent or escalating for a deployment choice.
- **Write-audit now ignores narrow runtime caches.** Post-hoc `allowedWrites` enforcement no longer fails a stage when Python/test tooling creates interpreter cache files such as `__pycache__/*.pyc`, `.pytest_cache/`, `.mypy_cache/`, or `.ruff_cache/`; real source writes outside `allowedWrites` are still reported as violations.
- **Observability-gate repairs now route back to build workstreams.** Stage 06c blockers with `assigned_to` or file-path hints now clear the owning Stage 4 build gate, re-dispatch build with `--from observability-gate`, merge, and re-run the observability gate instead of repeatedly re-running the audit until convergence escalation.

### Added

- **Stage DAG wave execution (ADR-017, phase-32 item 32.6).** `full`-track runs paid 18 sequential stage slots even where two regions are independent. `core/pipeline/stages.js` gains a curated `dependsOn: string[]` field on exactly the two regions ADR-017 authorizes — `red-team` now depends on `build` instead of its declared-order predecessor `pre-review`, and each of `accessibility-audit` / `observability-gate` / `verification-beyond-tests` / `performance-budget` depends on `qa` — with a header comment on the STAGES table warning that any future region needs its own readFirst-vs-`dependsOn` curation pass, not a mechanical extension. **`red-team`'s `readFirst` drops `pipeline/pre-review.md` and `pipeline/security-review.md`** — a model-visible prompt change, not an incidental side effect of adding `dependsOn`: leaving them in would make `{pre-review ∥ red-team}` an unsafe pairing (see ADR-017's own design-conflict analysis).

  `core/orchestrator.js#_nextImpl`'s loop body is extracted into `evaluateStageInPipeline` (a pure per-stage readiness/action check) with zero behavior change — verified by the full pre-existing test suite before any wave code was added on top. The new `nextWave()` (exported alongside `next()`) is a thin wrapper: it runs the identical sequential scan for the first ready action, then — only when that action is a fresh/resuming dispatch and `autonomy.max_parallel_stages` (new config, default **2**, validated like `max_retries`) allows more — looks ahead for `dependsOn` stages whose named dependencies already hold PASS/WARN, regardless of declared order. A one-member result is byte-identical to `next()`.

  `core/scheduler.js` gains `waveMemberKey` (`(host, stage)` composite) so a caller batching wave members through `mapByHostConcurrency` doesn't let `routing.host_concurrency` — designed to bound workstream fan-out *within* one stage — incorrectly throttle concurrency *across* stages that happen to share a host.

  `core/driver.js`'s main loop now calls `nextWave()` and, for a real 2+ member ready set, dispatches every member concurrently (`dispatchWaveMember`/`dispatchWave`, mirroring the pre-017 run-stage/continue-stage handling exactly, just returning a control signal instead of directly break/continue-ing the loop) through `core/scheduler.js#mapByHostConcurrency` keyed by `waveMemberKey` — the same dispatcher `core/orchestrator.js` already uses for within-stage workstream fan-out, per ADR-017 §2's explicit "no second concurrency implementation" instruction — one member failing halts wave *advancement* (the driver won't form a new wave until every current member reaches a terminal state) without touching an already-passing sibling's gate. One monotonic-per-run `wave_id` is assigned per formed wave and stamped on every member's dispatch events; `state.iterations`/`--max-iterations` count one wave as one iteration. A `opts.next` single-action stub (the pre-existing test DI seam, used by ~120 call sites across the test suite) is automatically wrapped into a size-one wave when no `opts.nextWave` is given, so no existing test needed to change.

  **Fix-up (same day, post-review):** the first cut of `dispatchWave` added `waveMemberKey` but never actually routed dispatch through `mapByHostConcurrency` — it used a bare `Promise.all`, leaving `waveMemberKey` exercised only by its own unit test. Caught in review, not by CI: because a wave's members are always distinct stages by construction, `(host, stage)` keying guarantees no two members ever share a queue within one `dispatchWave` call, so `Promise.all` and `mapByHostConcurrency` are behaviorally identical for both authorized regions — `routing.host_concurrency` was never actually going to throttle cross-stage wave concurrency either way (ADR-017 §2 scopes that cap to *within* one member's own dispatch). This was a spec-literalism/dead-code gap, not a live concurrency bug; the fix wires `dispatchWave` through `mapByHostConcurrency` (host resolved per member via `resolveRoute(config, stage, role)`) so the code now matches the ADR's "no second concurrency implementation" instruction and `waveMemberKey` is exercised by real dispatch, not just its own test. Full suite green before and after, unchanged test counts (proving the no-op).

  `devteam performance critical-path` (`core/performance/critical-path.js`) gains a `waves` array and `wave_realized_savings_ms` (`sum(member durations) − max(member durations)`, grouped by `wave_id`) — additive to the existing sequential dispatch-wall-time accounting, not a correction to it.

  Docs: `docs/runbooks/autonomous-run.md` gains a "Stage DAG waves" section and a `wave-formed` entry in the non-halt events list; `docs/FEATURES.md` gains a matching bullet. `plans/phase-32-performance-parallelism.md`, `plans/README.md`, and `plans/prompts/roadmap-2026-prompts.md` updated so no document still shows 32.2/32.6 as open.

  Tests: `tests/dag-wave-execution.test.js` (27 cases) — curated `dependsOn`/readFirst trim; config validation and fallback; `waveMemberKey`; wave formation (`{pre-review, red-team}` and all four QA-sweep stages becoming ready together, `max_parallel_stages` capping and splitting, a size-one wave byte-identical to `next()`, a FAIL not removing a ready sibling); driver integration (concurrent dispatch writing both gates in one iteration, a shared monotonic `wave_id`, a size-one wave carrying no `wave_id` field at all, a FAIL not corrupting the passing sibling's gate, `verify-chain` passing on a waved run); legacy `opts.next` stub compatibility; critical-path realized-savings math and markdown rendering. `tests/compact-qa-fold.test.js`'s four hard-coded pre-29.4 stage snapshots updated to include the new `dependsOn` field — deliberately, since that's new authorized behavior this item adds, not drift the snapshot should catch.

  Honest scope note: only fresh/resuming dispatches (`run-stage`/`continue-stage`) are batched into a real concurrent wave. A ready set containing a `fix-and-retry` (or any other non-dispatch action) always collapses to a single-member wave and runs through the exact pre-017 code path unchanged — concurrent convergence/archiving bookkeeping for multiple *simultaneously failing* wave members was judged materially riskier than this item's wall-clock claim requires (that claim comes from concurrent fresh dispatch, not concurrent retry), and ADR-017 §6 itself only says a wave-aware `next()` "may" return more than one `fix-and-retry` action, not that it must.

### Added

- **`devteam review <path>` — the zero-install external-review entry point (phase-36 item 36.4, `plans/phase-36-external-review-mode.md`).** No `init`, no config, nothing written to `<path>`. Creates (or reuses, via `--workspace <path>`) a review workspace under `~/.stagecraft/reviews/<slug>/` (`core/review-workspace.js`, item 36.3), then dispatches `--track` (default `review-only`) through the normal bounded driver (`core/driver.js#run()`) with `ctx.cwd` = the workspace and `ctx.processCwd` = the subject and `ctx.externalReviewMode = true` — the two-root split 36.3 wired through `runStage()`/`runStageHeadless()` but that, until this item, no caller ever set to `true`. `hosts/acp/adapter.js` reads that flag to flip its permission evaluator (`hosts/acp/permissions.js`, item 36.1) into review mode: any write into the subject is denied, and `execute` becomes a read-only allowlist. `--scope <path>` (repeatable) narrows the review the same way `devteam run --scope` already does (35.1). On completion, runs 35.4's severity-ordered findings collector/renderer against the workspace and prints the report path (`--open` launches it in a browser).

  **Host honesty.** `acp` is the only host whose enforcement is mechanical rather than advisory (`hosts/acp/permissions.js`'s two-root evaluator vs. every other host's prompt-only or post-hoc-audit `allowed_writes` — `core/adapters/render-helpers.js#allowedWritesCaption`). `--host` naming anything else prints a one-line warning that writes to the subject are **not** prevented (enforcement degrades to a post-hoc write audit) and refuses to proceed without `--allow-unenforced-writes` — the house "allow-&lt;compromised-guarantee&gt;" convention (`evidence.js`'s `--allow-unverified`), chosen so the flag itself states what's being given up, not just that the user consents. The warning still prints even when the flag is passed; this command never prints a read-only claim a host cannot keep.

  **`devteam review --list`** enumerates `core/review-workspace.js#reviewsRoot()`, pairing each workspace's `subject.json` (what's being reviewed) with a new `last-run.json` (recorded by this item, not 36.3 — run outcomes, not review-target identity) for subject path / last run date / last status. An empty list renders as "no review workspaces yet," not an error.

  **`--json`** is schema-checked against two new checked-in schemas: `core/review/schemas/review.schema.json` (single-run output: subject identity, workspace path, host/track, `review_mode_enforced`, driver completion state, findings-report summary) and `core/review/schemas/review-list.schema.json` (`--list` output).

  **The test that matters** (`tests/review-command.test.js`): end-to-end against a fixture subject repo, driven by a new scripted ACP agent (`tests/fixtures/acp-stub-review-agent.js`) that completes the *entire* three-stage `review-only` track (security-review, red-team, and all four peer-review areas) in one process invocation by parsing each dispatch's own rendered prompt for its workstream id/role, artifact path, and gate path — `tests/fixtures/acp-stub-agent.js`'s fixed-env-var approach only covers one dispatch per process, which a full `devteam review` run can't offer since the CLI's single invocation drives every stage's dispatch with the same env. Asserts the subject tree (file list + content hash, `.gitignore`/`AGENTS.md` included) is byte-identical before and after, a findings report is written, and `--list` picks up the completed run afterward. Also covers: `--list`'s empty case; the non-acp host warn-and-refuse-without-ack / proceed-with-ack paths (no workspace created on refusal); and both `--json` shapes against their schemas.

  Honest scope note: this item does not change how `Produce <artifact>` / `Write to pipeline/gates/<id>.json` are rendered (`core/adapters/render-helpers.js`) — those instructions are still *relative* paths, which a real (non-scripted) ACP agent would resolve against its own session cwd. In review mode that cwd is the subject (36.1's `processCwd`), not the workspace, so a real agent following the prompt literally would either get its write denied (safe: review-mode's codeRoot check catches it) or would need to independently infer the workspace's absolute path from context this prompt doesn't currently give it. 36.2 solved exactly this ambiguity for *read* targets (framework `readFirst` entries render absolute when roots differ); the same fix for *write* targets (artifact + gate paths) is not part of this item — flagged as an out-of-scope finding, not fixed here. The scripted test stub sidesteps it by being told the workspace's absolute path directly via `ACP_STUB_WORKSPACE_ROOT`, the same way `tests/fixtures/acp-stub-agent.js` already sidesteps path ambiguity for 36.3's own test. Also unaddressed here: `hosts/acp/adapter.js` never calls `core/hooks/approval-derivation.js#deriveForProject` the way `core/adapters/headless.js` does for non-ACP headless hosts, so a *real* ACP-routed peer-review dispatch has no automatic path from a `by-<role>.md` review file to a derived `stage-05.<role>.json` gate — this item's test stub writes that gate directly (a scripted stub, not bound by the "never authored by an agent" contract stage-05's schema describes), which is fine for testing this command's orchestration plumbing but does not exercise or fix that gap.

- **Docker-based headless runner** (closes #282). Adds `hosts/docker/` with a
  non-root Dockerfile, a small entrypoint that delegates to the normal `devteam`
  CLI, lock-state reporting for mounted projects, explicit stale-lock cleanup
  via `STAGECRAFT_RUNNER_CLEAR_STALE_LOCK=1`, and operator docs for build, run,
  resume, UID/GID alignment, secrets, host choices, and resource limits. ADR-014
  locks the trust boundary: the runner is containerized local orchestration, not
  a scheduler, cloud worker, per-stage sandbox, or new host adapter. Offline
  tests cover the packaging surface and entrypoint behavior without requiring
  Docker or model credentials.

### Changed

- **Docs: reposition `full` as the audited path, `loop` as the day-to-day default — phase-29 item 29.5.** `README.md`, `docs/tracks.md`, `docs/user-guide.md`, and `docs/adoption-guide.md` now lead with `loop` for bounded, day-to-day iteration and frame `full` as the **audited** path chosen when stakes or compliance justify the ceremony, rather than the safest-looking default. `README.md`'s Quick start (`--headless` path) now runs `--track loop` first; a new "Which track?" section adds a ceremony-cost decision table pointing at `devteam assess --json` (phase-29.3) for the actual per-track estimate. `docs/tracks.md`'s "Pick by what you're shipping" table gained a ceremony-cost column and was reordered `loop`-first/`full`-last; its decision tree gained an explicit `loop` branch. One sentence in each of `README.md`, `docs/tracks.md`, and `docs/adoption-guide.md` forward-references the Phase 34 roadmap item (exportable, regulator-shaped attestations building on the `full`-track audit trail), each marked as roadmap / not yet built. `docs/user-guide.md`'s "Daily loop" heading (the `next`/`stage` habitual cycle) now disambiguates itself from the `loop` track by name.
  Honest scope note: this is a repositioning pass, not a rewrite — every existing caveat (stoplist behavior, the `pipeline.default_track: full` factory-default note, per-track stage lists, the `nano`/`quick`/`hotfix` guidance in the adoption guide) is preserved verbatim or extended, never deleted. No code changed; `npm run consistency`'s doc-drift checks are the acceptance gate for this item.

### Added

- **Failed gates become replayable eval cases — Phase 33.1.** Every stage FAIL/ESCALATE, and every orchestrator stamp `status_overridden` (the model-lied class — always captured, since it's already a FAIL), now writes a case under `.devteam/evals/cases/<ts>-<stage>-<hash>/`: `case.json` (stage/role/host/track, an orchestrator-computed `prompt_hash`, the gate's C4 reproducibility fields via `core/reproducibility.js#reproducibilityFingerprint`, a sanitized gate snapshot, framework/stamper versions) and `inputs/manifest.json` describing the stage's `readFirst` artifact set. Artifact content is content-addressed (sha256) into `.devteam/evals/blobs/`, deduped across cases; a file that scans positive through `core/hooks/secret-scan.js` (the same path the stage-04c mechanical red-team floor uses) is excluded from the blob store entirely — the manifest records the exclusion and which pattern fired, never the content. `core/verify/stamp.js` finding lint/tests actually failing after a model claimed PASS flips the gate as before; the new capture path just observes whatever status lands.

  Single-role stages are captured in `core/orchestrator.js#runStageHeadless` (alongside the existing `core/corpus.js` fire-and-forget dispatch record — same point, so the post-stamp status is what's captured, never the model's pre-stamp claim). Multi-workstream stages (build, peer-review) are captured in `core/driver.js`'s merge branch, after `stampMerged` — that's the only place the stage's true final status (post per-role stamps *and* the merge-time stage-05 approval re-derivation) is known.

  A resolution-linker pass runs at the end of every `devteam run` (fire-and-forget, same slot as pattern auto-collection/reflector/memory-ingest): for each captured case with no `resolution.json` yet, it looks for a `fix-retry` run-log event on the same stage logged after capture, and — if the stage's current on-disk gate is no longer FAIL/ESCALATE — appends `resolution.json` naming which retry cleared it.

  New config: `evals.capture` (default `true`) opts a project out entirely. New command: `devteam evals gc` removes `.devteam/evals/blobs/` entries no case's `inputs/manifest.json` references anymore. `.devteam/evals/` joins the managed `.gitignore` block (local-only, like `.devteam/corpus/` — no cross-project or cross-run aggregation).

  Tests: `tests/evals-capture.test.js` — a stubbed FAIL dispatch (via `runStageHeadless`) produces a complete case directory; a real `stampStage04a` status_overridden is captured with `capture_reason: "stamp-override"`; a multi-workstream merge FAIL is captured via `core/driver.js#run` with an injected `mergeWorkstreamGates`; a fix-retry run-log event followed by the stage's gate turning PASS links a `resolution.json`; two cases sharing identical artifact content dedup to one blob; `evals.capture: false` captures nothing; a planted secret in a readFirst file is excluded from the blob store; `devteam evals gc` removes only unreferenced blobs.

  Honest scope note: capture is local-only and per-project (mirrors `core/corpus.js`'s scope decision) — there is no bounded-isolation (`pipeline/changes/<id>/`) plumbing for `.devteam/evals/`, matching the run corpus's own precedent. The resolution-linker's "which retry cleared it" is a best-effort correlation by stage id and timestamp ordering against `run-log.jsonl`, not a strict causal proof — a stage that flaps FAIL→PASS→FAIL→PASS within one run links every earlier unresolved case to the same final clearing retry. `devteam evals run` (the replay harness) and `prompt_pack_version` (33.2/33.3) are separate, not-yet-implemented plan items — this item only builds the capture substrate they'll consume.

### Added

- **`devteam evals run` — the eval flywheel replay harness (Phase 33.2).** Replays cases captured by `core/evals/capture.js` (33.1) against the CURRENT framework — today's `core/pipeline/stages.js` stage definitions, role briefs, rules, templates, and `render-helpers.js` prompt layout — to catch framework regressions independent of the model. `devteam evals run [--stub | --headless-host <h>] [--filter <stage|id>] [--budget-usd <n>] [--json]`.

  For each matching case, `core/evals/run.js` rebuilds the descriptor via `core/orchestrator.js#buildDescriptor` against today's stage definitions (never the descriptor at capture time — that's the whole point), materializes a scratch project that overlays the case's captured `inputs/manifest.json` blobs onto the target project's own currently-installed `.devteam/` framework files (or this package's bundled defaults, for a target with no live install — e.g. this repo's own fixture corpus), and renders through the same adapter the case recorded.

  `--stub` (default, free, no model): scores the re-rendered prompt structurally — the always-present scaffold sections (`## Objective`, `## Read first`, `## Allowed writes`, `## Gate to write`, the framework preamble when the stage's `readFirst` starts with `FRAMEWORK_READ_FIRST`) are still there, the rendered bytes are within the stage's committed dispatch-budget ceiling (`docs/reference/prompt-budget.md`'s `parseCommittedBudget`), and how far the prompt hash has drifted from the case's recorded one (always reported, never gated — the replay context legitimately differs from the original run's).

  `--headless-host <h>` dispatches for real via the existing `core/adapters/headless.js#runHeadless` machinery (`DEVTEAM_HEADLESS_COMMAND` respected, same as every other headless path). A case whose original failure was later RESOLVED (`resolution.json` present) must come back PASS/WARN now — still FAIL/ESCALATE is a regression and exits 1. An unresolved case has no known-good target status, so its current gate is reported but never fails the sweep. Prints a 29.3-style cost preview (`core/ceremony-preview.js`'s `mostRecentModelObserved`/`pricingFor`, byte-sampled from the actual re-rendered prompts) before any dispatch and refuses to run without `--budget-usd`.

  Output: a human table by default, or JSONL (one line per case + a trailing summary line) with `--json`, for CI consumption. New CI job (`.github/workflows/test.yml`) runs `--stub` over a small checked-in fixture corpus (`tests/fixtures/evals/`) on every push/PR — this repo's own framework regression gate.

  Tests: `tests/evals-run.test.js` — stub scoring on the fixture corpus (all-OK, exit 0); `--filter` by stage id; a case whose stage no longer exists in `stages.js` scores `error` (exit 1); `--headless-host` without `--budget-usd` refuses with a printed cost preview (exit 1); a resolved case redispatched to PASS via a scripted `DEVTEAM_HEADLESS_COMMAND` scores `pass`; the same case scripted back to FAIL (a seeded re-break) scores `regression` (exit 1); an unresolved case still failing scores `still-failing` without failing the sweep.

  Honest scope note: a merge-level case (multi-role stage, `role: null` — see 33.1's capture split between `core/orchestrator.js` and `core/driver.js`) replays against the stage's first currently-configured role only; the case format doesn't identify which per-role workstream actually owned the failure, and this item doesn't add per-role fanout for that class. The committed dispatch-budget ceiling used for the `--stub` budget check (`docs/reference/prompt-budget.md`) includes the role-brief's own bytes, but adapters built on `render-helpers.js` reference the role brief by path rather than inlining it — so the check is a loose sanity ceiling against accidental scaffold bloat (e.g. a runaway learned-context section), not a tight budget for the rendered text itself. GEPA-style offline optimization (33.4) is a separate, not-yet-implemented plan item; `prompt_pack_version` comparison shipped as phase-33 item 33.3 (see `changelog.d/prompt-pack-version.md`).

### Added

- **feat(pipeline):** framework files (`.devteam/rules/*.md`, role briefs, templates) now resolve
  correctly when a review workspace's state root differs from the subject being reviewed
  (`plans/phase-36-external-review-mode.md`, item 36.2). `core/pipeline/stages.js` gains
  `isFrameworkReadFirstPath()`, derived from the existing `FRAMEWORK_READ_FIRST` constant, and
  `core/adapters/render-helpers.js` gains `resolveFrameworkPath(relPath, ctx)`: when
  `ctx.processCwd` (the subject, 36.1's `codeRoot`) differs from `ctx.cwd` (the review workspace,
  `stateRoot`), a framework path renders as an absolute path into `stateRoot` instead of a
  relative path that would resolve into the subject, where it does not exist.
  `core/orchestrator.js#buildDescriptor` applies this to `readFirst` entries;
  `core/adapters/markdown-host.js` (the acp/codex/gemini-cli shared renderer) applies it to the
  role-brief and template pointers. `AGENTS.md` is deliberately left "subject"-rooted — a
  reviewer must read the subject's own `AGENTS.md`, not Stagecraft's init stub.

  Every pre-36.3 caller leaves `ctx.processCwd` unset (36.3 is what will start setting it for a
  real review workspace), so `codeRoot === stateRoot` everywhere in production today and this
  change is a byte-identical no-op until then — covered by
  `tests/external-framework-paths.test.js`'s equal-roots regression, run against both
  `buildDescriptor()`'s output and the fully rendered acp-host prompt.

  Honest scope note: implemented via a small path-based lookup derived from
  `FRAMEWORK_READ_FIRST` rather than annotating every one of `core/pipeline/stages.js`'s ~20
  per-stage `readFirst` arrays with an explicit `{path, root: "framework"}` object — the object
  form (`{path, root, optional}`) is real and honored when present, but marking the two known
  rule files by path keeps this a two-function, zero-`stages.js`-diff change instead of one that
  also has to fix `scripts/prompt-budget.js`'s and `scripts/prompt-optimize.js`'s existing
  strict-shape/`.includes()` readFirst consumers. See the PR description for the full
  deviation rationale.

### Added

- **Docs: external review guide — phase-36 item 36.6 (`plans/phase-36-external-review-mode.md`).** New `docs/external-review.md` documents `devteam review <path>` and `devteam review-pr <number|url>` (36.4/36.5): the two entry points, a per-host enforcement table naming the exact file that backs (or fails to back) each host's read-only claim, the review workspace layout (`core/review-workspace.js`), where a review's evidence lands, and the honest limits — the `acp` `execute` allowlist (`hosts/acp/permissions.js#findReviewExecViolation`) and that `read`-kind calls carry no location check today. Cross-linked from a new `docs/compliance.md` § Reviewing code you don't own; `README.md`'s `--host acp` paragraph now names it as the recommended host for reviewing code you don't own; added to `docs/README.md`'s index.

  Writing the enforcement table surfaced (and now documents) a real gap: in review mode, the non-`acp` post-hoc write-audit (`core/adapters/headless.js`'s `snapshotWritables(ctx.cwd)`) snapshots the review *workspace*, never `ctx.processCwd` (the subject) — it cannot see a subject write at all, and typically no-ops outright since the workspace isn't a git repository. That is weaker than `checkHostHonesty`'s own warning text ("post-hoc audit of what the agent actually wrote") implies for any `--host` other than `acp`.

  Honest scope note: no code changed. The write-audit gap above is documented, not fixed — fixing it (e.g. pointing the audit at `codeRoot` when `ctx.externalReviewMode` is set) is out of scope for a docs item and is left as a follow-up.

### Added

- **Run corpus: one sanitized JSONL record per headless dispatch, plus `devteam corpus stats` — Phase 28 item 28.5.** After every headless dispatch (`devteam run`, `devteam stage --headless`, `devteam replay`, the a11y-fixer), the orchestrator appends one line to `.devteam/corpus/dispatches.jsonl` (project-local, gitignored by the managed block, never uploaded): `{ts, run_id, stage, role, host, model_observed, track, prompt_hash, prompt_bytes, tokens_in, tokens_out, cost_usd, cost_basis, duration_ms, queue_ms, gate_status, blockers, retry_of, framework_version}`. Fields missing for a given dispatch are `null`, never omitted. `model_observed`/tokens/`cost_usd` prefer the gate's `_orchestrator_observed` block over model-asserted top-level fields (same trust-boundary pattern as `core/verify/stamp.js`); `cost_basis` records which one won. `blockers` are sanitized through the same secret-scan path (`core/hooks/secret-scan.js scanContent`) `core/patterns.js` collection uses — a blocker containing secret-shaped text is fully redacted before it ever reaches disk. Writes are fire-and-forget: an unwritable `.devteam/corpus/` directory logs one warning and never fails the run. New `devteam corpus stats [--json]` reports total dispatches, per-stage pass rates, and per-(role, host) dispatch counts — worded to answer the D5/H3 evidence-gate questions in `docs/BACKLOG.md` directly. `.devteam/corpus/` added to the managed gitignore block. `scripts/routing-suggest.js` (D5) now reads the corpus as an additional data source alongside `pipeline/gates/` archives, so dispatch history survives gate archiving/pruning. Docs: `docs/observability.md` "Run corpus" section. Tests: `tests/corpus.test.js` (14 new) — one corpus line per dispatch with correct fields via a stubbed multi-stage headless run, a planted secret in a blocker never reaching disk (both the parsed field and the raw file content), `--skip-completed` no-op dispatches excluded, an unwritable corpus directory logging exactly one warning without throwing or failing a real dispatch, `devteam corpus stats` aggregating a fixture corpus (including a malformed line being skipped) via both the module API and the CLI, and `scripts/routing-suggest.js` merging corpus records into `aggregatePerformance`. Honest scope note: the experimental `--experimental-omnigent-director` dispatch path is not yet recorded to the corpus (it predates per-dispatch usage telemetry entirely); cross-project D5/H3 aggregation remains a manual step — the corpus itself is local-only and never combined across projects automatically.

### Added

- **`loop` track: a 4-slot minimal-ceremony pipeline — phase-29 item 29.1.** New track `loop` (`STAGES_BY_TRACK.loop` in `core/pipeline/stages.js`): `requirements` (stage-01, one-screen brief) → `build` (stage-04, single workstream) → `qa` (stage-06) → `peer-review` (stage-05, single reviewer). Note the order — `qa` runs before `peer-review` on this track, the reverse of every other track; `verifyChain`'s nearest-earlier-gate predecessor rule already walks the track array in declared order rather than by numeric stage ID, so the tamper-evident chain still links correctly (new tests in `tests/chain.test.js` prove this explicitly). Build and peer-review each dispatch one config-overridable workstream (`pipeline.loop_build_role` in `.devteam/config.yml`, default `backend`) instead of the four-role matrix — `loopBuildRole()` in `core/pipeline/stages.js` is the single source of truth both `rolesForStage()` and `requiredApprovalsFor()` read, so the reviewed area always matches what build actually touched. Stage-01 renders a new one-screen template (`templates/loop-brief-template.md`: intent, AC-N list, affected files) on this track only, via a new `trackOverrides` mechanism on the stage definition (parallel to the existing `repairOverride`). `loop` has no design, no red-team, and no sign-off/deploy — `devteam run --track loop` ends at `peer-review`; promoting to a deploy-capable track is a re-run with `--until` on a bigger track or a `custom_stages` config, not a `loop` feature. `loop` is also added to `core/guards/stoplist.js`'s `STOPLIST_TRACKS` — the consequence ceiling applies to the lightest track exactly like the other lighter tracks. Docs: `docs/tracks.md` (new "The `loop` track" section + matrix row), `rules/pipeline-tracks.md`, and every other stage/track-count claim the consistency checker flagged (`docs/concepts.md`, `docs/FEATURES.md`, `docs/README.md`, `docs/comparative-analysis.md`, `docs/presentation-notes.md`, `docs/adr/006-track-inference-under-autonomy.md`, `docs/verification-beyond-tests.md`, `docs/user-guide.md`, `rules/gates-core.md`, `rules/orchestrator.md`, `roles/red-team.md`). Tests: `tests/tracks.test.js` (track shape + role/approval sizing, including the config override and its unrecognized-value fallback), `tests/pipeline-e2e.test.js` (a full stubbed `loop` run completes in exactly 4 dispatches, no merges, with an audit trail identical in shape to the other tracks), `tests/chain.test.js` (the inverted stage-06→stage-05 predecessor link stamps and verifies, and tamper detection still locates the break), `tests/orchestrator.test.js` (the track-based template override reaches the rendered prompt end-to-end via `runStage`, and repair intent still wins over the loop override), `tests/run.test.js` (the stoplist halts a `loop` run exactly like `quick`), `tests/config.test.js` (`loop_build_role` default and override), `tests/contract.test.js` (every `trackOverrides` template exists on disk). Honest scope note: track *selection* — `devteam assess` inferring `loop` from a change description — is out of scope for this item (phase-29 item 29.2); `loop` is opt-in via `--track loop` or `pipeline.default_track: loop` only.

### Added

- **Severity-ordered findings report with mitigations — Phase 35.4.** Today, "put an existing codebase through reviews and get one list of things to fix" means hand-assembling it from `pipeline/security-review.md`, `red-team-report.md`, `code-review/by-*.md`, `pipeline/gates/stage-06d.json`, and `docs/audit/*.md` separately. `devteam report --findings [--out <file>] [--json]` collects one ranked table instead: severity, `file:line`, what's wrong, suggested mitigation, rough effort, and provenance.
  - **Sources** (`core/report/collect-findings.js`): security-review (stage-04b `BLOCKER:` lines, escalated to `critical` on veto), red-team including the 31.2 mechanical floor (stage-04c `must_address_before_peer_review[]` / `noted_for_followup[]`, cross-enriched with `red-team-report.md` prose for mitigation/effort/file:line), peer-review + critic (stage-05 blockers, stage-05.critic.json unresolved challenges), the 31.4 mutation smoke gate (stage-06), verification-beyond-tests (stage-06d `blocking_findings[]` / `non_blocking_findings[]`), and `docs/audit/*.md` once `docs/audit/status.json` shows the audit workflow has run.
  - **Provenance is the important column**, reusing the existing `_orchestrator_stamped`/`_orchestrator_observed` distinction rather than inventing a new one: a finding is `orchestrator-observed` only when it traces to code the orchestrator itself ran — a mechanical red-team floor check (`source: "mechanical"`), an executed mutation gate, a stage-06d method the orchestrator actually confirmed with real evidence (not downgraded to `attempted_but_blocked:*`), or a peer-review approval mismatch the approval-derivation hook derived from the review file. Everything else — a reviewer's or auditor's judgment, even when well-evidenced in prose — is `model-asserted`.
  - A generic markdown finding-block parser (`core/report/parse-markdown-findings.js`) reads the "heading + bullet fields" shape shared, with drift, by `red-team-report.md` (`### RT-1 — <title>`) and `docs/audit/*.md` (`#### Finding S1: <title>`) — used only for best-effort enrichment (mitigation/effort/file:line), never as the source of truth for counts or provenance.
  - Self-contained HTML (`core/report/render-findings-html.js`, same offline-file discipline as `devteam report`) plus `--json`, schema-checked against `core/report/schemas/findings-report.schema.json`. The no-findings case renders an honest empty state, not a broken table.

  Honest scope note: file:line extraction is regex-based best-effort text parsing (`path/to/file.ext:NN` token matching), not a structured field on every source — security-review and peer-review blockers, in particular, only have a file:line when the reviewer happened to write one inline. Critic-challenge provenance is `model-asserted` for the claim content even when the hook mechanically forced its disposition to `unresolved` for missing evidence — this module doesn't split provenance within a single finding.

### Added

- **One front door for 103 doc files, and a check that keeps it that way — Phase 37.5.** `docs/START-HERE.md` names the five documents a new user actually needs (`EXAMPLE.md`, `docs/adoption-guide.md`, `docs/user-guide.md`, `docs/tracks.md`, `ARCHITECTURE.md`); `README.md` and `docs/README.md` both point to it ahead of the existing exhaustive four-reader-path map, which is unchanged and still there for everyone else.

  `docs/historical/` and `docs/reference/` each gained a `README.md` index (the former lists the one archived doc that already lived there plus the archive convention from `CONTRIBUTING.md`; the latter lists all five generated/hand-maintained reference docs and which is which). `docs/audit/README.md` — already existing — is now linked from `docs/README.md` too.

  `scripts/consistency.js`'s existing `docs-index` check (added under an earlier phase, D2) wholesale-excluded `historical/`, `reference/`, and `audit/` from the "every doc must be reachable from `docs/README.md`" requirement. Rather than add a second, overlapping check, this narrows that exclusion list down to a single deliberate exception — `audit-archive/`, a dated-snapshot pipeline-output archive indexed by its own `HISTORY.md` rather than a `README.md`, and not part of the hand-authored-doc sprawl this check exists to catch. `historical/`, `reference/`, and `audit/` now rely on the same directory-index-coverage rule `adr/` and `runbooks/` already used — no new mechanism, just closing three exemptions that had outlived their reason. `npm run consistency` went from 376 to 397 checks passed with the new indexes in place; zero files were deleted or moved.

  Tests: `tests/consistency-meta.test.js` gained a positive test that `historical/`, `reference/`, and `audit/` are covered once each has a linked `README.md`, and a negative test that a `historical/` doc without one is still (correctly) flagged as an orphan. The pre-existing "excluded dir is not required" test encoded the old wholesale `historical/` exemption; renamed and repointed it at `audit-archive/`, the one exemption this item keeps, since that's the behavior it actually verifies now.

  Honest scope note: no documentation was moved. The only file that ever lived under `docs/historical/` (`GAP-ANALYSIS.md`) was already there from an earlier phase; this item indexed it rather than relocating anything else, because nothing else in `docs/` was found to be genuinely superseded — see the PR description for the full list the generalized check would have flagged before these fixes (all of it indexed, none of it deleted). `CONTRIBUTING.md`'s Archive policy section claims `docs/historical/` "already uses" a datestamp-prefix naming convention "for the self-audit archive" — that's actually true of `docs/audit-archive/`'s dated subdirectories, not `docs/historical/`'s one undated file; left as-is and flagged for a human, since fixing it means picking between renaming the file (and its stub redirect) or correcting the sentence.

- **gemini-cli retired from a first-party host to a plugin package (phase-34 item 34.4, completes 28.6).** `hosts/gemini-cli/` moved to `packages/host-gemini-cli/`, a `@devteam/host-gemini-cli` package resolved through the existing A4 pluggable-adapter mechanism (`core/router.js`) rather than the first-party `hosts/` enumeration. First-party surface is now claude-code, codex, antigravity, openai-compat, acp, omnigent, and generic. `devteam init --host gemini-cli` now fails with an exact install instruction (`npm install @devteam/host-gemini-cli`) when the plugin isn't present, and succeeds identically to before once it is. `devteam doctor`'s existing gemini-cli deprecation warning (phase-28 item 28.6) now fires independent of whether the plugin is installed, and reports a plugin-specific "not available" message instead of the generic `no adapter at hosts/<name>/` text. The adapter's own behavior is unchanged — same capabilities, same contract — only its location and packaging moved; its README documents the honest scope note that this package isn't published to any registry, and that its relative `require()`s into Stagecraft's core only resolve inside a Stagecraft checkout (tracked as `docs/BACKLOG.md` item A10).
  - **Bugfix surfaced along the way:** `core/router.js`'s `listExternalHosts()` used `Dirent.isDirectory()`, which reflects a directory entry's own type — false for a symlink, even one pointing at a directory. npm workspaces and `npm link` install local packages as symlinks under `node_modules/<scope>/`, so any first-party-maintained plugin installed that way (not just gemini-cli) was invisible to `listHosts()`/`loadAdapter()`. Fixed with an explicit `fs.statSync` follow when the entry is a symlink; regression test in `tests/router.test.js`.
  - Tests: `packages/host-gemini-cli/tests/adapter.test.js` (adapter's own contract, moved from `tests/adapter-contract.test.js` and friends), `tests/gemini-cli-plugin.test.js` (init error path + plugin-installed round-trip via a symlinked fixture), plus updates across `tests/adapter-contract.test.js`, `tests/audit.test.js`, `tests/capabilities.test.js`, `tests/doctor.test.js`, `tests/fanout.test.js`, `tests/goal-loop.test.js`, `tests/orchestrator.test.js`, `tests/prompt-layout.test.js`, `tests/router.test.js`, and `tests/write-audit.test.js` to reflect gemini-cli no longer being a first-party, always-loadable host in this dev checkout. Root `package.json`'s test script now also globs `packages/*/tests/*.test.js`.
  - Honest scope note: this package is shaped to be publishable but is not actually published anywhere as part of this change (see `packages/host-gemini-cli/README.md` and `docs/BACKLOG.md` item A10).

### Changed

- **`devteam --help` collapses from 343 lines to one screen, grouped by what you're trying to do — Phase 37.4.** The default listing doubled as the full flag reference, which meant a new user's first screen was 343 lines long. `core/cli/commands/help.js` now defaults to a ~27-line grouped view (`Start here`, `Daily`, `Review`, `Verify`, `Fix & retry`, `Learn`, `Audit`, `Setup & tools` — one line per group, commands separated by `·`) built from every entry in `core/cli/command-list.js`. The full listing — same content, nothing lost — moves behind `devteam --help --all` / `devteam help --all`, and still backs the generated `docs/reference/cli.md` (unchanged apart from documenting the new `--all` flag itself). `bin/devteam`'s `-h`/`--help`/no-argument branch now runs the shared flag parser against `help`'s own flag schema instead of ignoring everything after the flag, so `--all` reaches `help.run()`. Unknown-command messages (`devteam help <typo>`, `devteam <typo>`) now show the grouped view instead of the full one, for the same one-screen reason.

  No command renames or removals — presentation only. Grouping decisions belong in one place: `GROUPS` in `help.js`, exported for tests.

  Tests: `tests/help-cmd.test.js` gained — default help ≤ 45 lines; `help --all` and `--help --all` both print the full reference (`Commands:`/`Quickstart:`); a coverage test that every command in `command-list.js` appears in `GROUPS` exactly once, so a future command can't be added without being grouped; unknown-command fallback shows the grouped view. Updated three pre-existing tests that encoded the old "default help is the full listing" behavior: `help-cmd.test.js`'s no-argument and unknown-command assertions now check for the grouped view (their old assertions moved to the new `--all` test); `cli.test.js`'s per-command coverage regex loosened from start-of-line matching (which assumed one command per line) to a word-boundary match, since commands now share a line within a group; `evidence-status.test.js`'s help-listing assertion split into a default-help check (`evidence` — the bare command name) and an `--all` check (`evidence status` — the subcommand detail that moved).

  Honest scope note: `docs/reference/cli.md` is *not* byte-unchanged as the plan item's acceptance criterion literally states — adding the `--all` flag itself to `help`'s schema (needed so `parseFlags` accepts it and `generateHelp`/`docs:generate` stay the single source of truth for flag docs) adds one documented flag row to the generated reference's `help` section. The alternative — special-casing `--all` outside the flag schema — would have made `devteam help --all` and `devteam --help --all` diverge in how they parse the flag, which seemed worse than a four-line doc diff.

### Fixed

- `devteam help`'s top-level command listing was missing `corpus` and `evals` entirely — both are real, working, `--help`-documented commands (registered in `core/cli/command-list.js`, phase 37.1), just never added to this hand-written summary list. Added one-line entries for each, matching the surrounding style. `tests/cli.test.js` gained a regression test asserting every command in `core/cli/command-list.js` appears in the top-level listing, so a future command can't silently go missing from it again.

  Honest scope note: this listing is still hand-maintained prose, not generated from the flag specs like `docs/reference/cli.md` (which already listed both commands correctly) or the per-command `--help` output (phase 37.1) — unifying it with the generated doc is a larger change than this fix and out of scope here.

### Added

- **Agent Client Protocol (ACP) host adapter — phase-34 item 34.1 (`docs/user-guide.md` "Using ACP", `core/adapters/host-adapter.md`).** `hosts/acp/` speaks [Agent Client Protocol](https://agentclientprotocol.com) (Zed, JetBrains, Google, GitHub, 25+ agents) as a *client* over stdio, so any ACP-compatible coding agent becomes a Stagecraft host with zero adapter code written per agent — verified against the published schema (`zed-industries/agent-client-protocol` `schema/v1/schema.json`, protocol version 1, pinned in `hosts/acp/capabilities.json`'s `acpProtocolVersion`) rather than prose docs alone, since the docs site omits transport framing (newline-delimited JSON-RPC 2.0 over stdio; stdout carries only protocol messages, stderr is agent logging). `hosts/acp/jsonrpc.js` is a from-scratch ~130-line bidirectional JSON-RPC client (no new npm dependency — same house style as the existing `claude-stream-json`/`codex-exec-json` line-JSON extractors) since ACP requires both directions: Stagecraft sends `initialize`/`session/new`/`session/prompt`, and the agent sends `session/request_permission` back plus `session/update` progress notifications. Dispatch = initialize → session/new → one `session/prompt` turn with the rendered stage prompt → stream `session/update` into `pipeline/logs/<workstreamId>.log` → best-effort `session/close` → resolve once the turn ends (`stopReason`) and the gate file is checked (the existing hooks:false poll fallback in `core/orchestrator.js` covers the rest).
  - **Enforcement mapping (`hosts/acp/permissions.js`).** Every ACP tool call is a `session/request_permission` round-trip *before* it executes, carrying `kind`/`locations`/`rawInput` — real structure to decide on, unlike claude-code's own tool-call-time enforcement (static per-project permission globs configured once at install, `hosts/claude-code/adapter.js` `renderSettingsLocal`). The adapter checks the *live* per-dispatch `descriptor.allowedWrites` (via `core/guards/write-audit.js`'s `isAllowed`) for edit/delete/move tool calls, and a claude-code-parity dangerous-command stoplist (`rm -rf`, `git push --force`/`-f` — mirroring `renderSettingsLocal`'s `permissions.deny`, not `core/guards/stoplist.js`'s topic-based auth/crypto/PII patterns, which gate track selection for a whole run and would false-positive on ordinary full-track work touching e.g. `auth.js`) against the tool call's title/rawInput. `capabilities.json` declares `allowed_writes`/`stoplist: "tool-call-time"` — **the first non-claude-code host with call-time enforcement**, closing part of the enforcement-parity gap the landscape review flagged. Deny/allow always selects a real offered `PermissionOption` (`reject_once`/`allow_once` preferred over the `_always` variants, since Stagecraft re-decides every call from the current descriptor); silence never defaults to permissive — an unmatched deny cancels the turn rather than falling through to allow.
  - **Routing (`core/config.js`, `core/router.js`, `core/orchestrator.js`).** `routing.roles.<role>`/`routing.stages.<stage>` gain a third string shape, `"acp:<agent-command>"` — there's no single default ACP binary the way there is for claude/codex/gemini, so the launch command travels with the route itself. `normalizeRouteValue` parses it into `{host: "acp", agentCommand}`; the object form (`{host: "acp", agentCommand: "..."}`) works too. `resolveRoute`/`resolveAdapter` surface `agentCommand` alongside `hostName`/`model` (same "rides on the descriptor" pattern 32.3 established for `model`) — added *only* when non-empty, so every pre-34.1 route shape stays byte-identical (verified by re-running the existing `deepEqual`-based back-compat tests unchanged). `hosts/acp/adapter.js`'s `resolveAgentCommand` resolution order: `DEVTEAM_HEADLESS_COMMAND` → `descriptor.agentCommand` → `.devteam/config.yml` `hosts.acp.command` → `capabilities.headlessCommand` (a runnable reference default, `npx -y @agentclientprotocol/claude-agent-acp` — the official ACP bridge for Claude Code; any other agent needs an explicit command).
  - **Wording fix (`core/adapters/render-helpers.js`).** `allowedWritesCaption`'s tool-call-time wording hardcoded "hooks" — accurate for claude-code but wrong for ACP, which enforces via permission requests, not hooks. Added an optional `mechanism` parameter (default `"hooks"`, byte-identical for every existing caller) that `core/adapters/markdown-host.js` now threads from a new optional `capabilities.enforcementMechanismLabel` field; `hosts/acp/capabilities.json` sets it to `"permission requests"`.
  - Tests: `tests/host-acp.test.js` (end-to-end stage completion via a scripted stub agent, an out-of-allowedWrites edit denied at call time via a real `reject_once` option, the `rm -rf` stoplist denied the same way, a malformed non-JSON protocol line terminating the session with a reported `protocolError` instead of hanging, an agent that never responds bounded by `ctx.timeoutMs`, plus unit coverage of `permissions.js`), `tests/fixtures/acp-stub-agent.js` (the scripted agent — speaks the wire protocol directly, independent of `hosts/acp/jsonrpc.js`, so a framing bug there can't hide behind a shared implementation), `tests/config.test.js` and `tests/router.test.js` (the `acp:<command>` routing form + back-compat), `tests/adapter-contract.test.js` (added to `PROMPT_ONLY_HOSTS`, `HOSTS_WITH_RENDER`, `SHARING_HOSTS`, and the 6.1 tool-budget-resolution host list — the shared gate-footer equivalence check passes unmodified, confirming the enforcement-level wording fix above didn't leak into the footer boundary).
  - Honest scope note: `telemetry: "estimated"` — ACP has no standardized usage/cost field, so this adapter falls back to the same promptBytes/4 estimate every non-native host uses. `subagents`/`hooks`/`goalLoop`/`worktrees` are all `false` — Stagecraft doesn't wire into any ACP-side equivalents here. Enforcement only covers tool calls the agent honestly reports via `kind`/`locations`/`rawInput`; an `execute`-kind tool call that writes files via shell redirection isn't checked against `allowedWrites` (same gap claude-code's own Bash permission model has — Bash isn't glob-restricted to allowed directories either, only the dangerous-command deny-list applies). No post-hoc write-audit backstop is layered on top, matching the precedent every other `"tool-call-time"`-declaring host (claude-code) already sets. ACP server mode (Stagecraft driven *by* another tool) is explicitly out of scope, per the phase-34 plan.

- **Antigravity CLI host adapter (phase-28 item 28.6) — Gemini CLI continuity.** Gemini CLI stopped serving free/Pro/Ultra requests 2026-06-18; Google's supported successor is Antigravity CLI (binary: `agy`). `hosts/antigravity/` is a thin shell over `makeMarkdownHostAdapter`, structurally identical to `hosts/codex/` and `hosts/gemini-cli/`: plain-markdown role prompts at `.agents/prompts/roles/`, skills at `.agents/skills/<name>/SKILL.md`, no hooks/slash commands/native-subagent dispatch, post-hoc git-diff write audit, headless via `agy --print --dangerously-skip-permissions` (prompt piped to stdin). Every capability was verified against the actual installed binary rather than public docs alone — `agy --help`, an authenticated live `agy --print` dispatch, and the CLI's own embedded customization-root documentation (`strings` on the binary) — because several third-party "cheat sheet" sites surfaced by web search disagreed with the real binary (e.g. claiming plugins stage under `~/.gemini/antigravity-cli/` when the actual global customization root is `~/.gemini/config/`). `devteam doctor` now warns whenever routing resolves any role or stage to `gemini-cli`, pointing at `devteam init --host antigravity`; `gemini-cli` itself is untouched and stays installed-and-functional (full retirement is a separate later item). Updated `docs/user-guide.md`'s multi-host section, README's host lists, and `tests/adapter-contract.test.js`'s shared-host arrays (gate-footer equivalence, PATCH MODE rendering, tool-budget rendering) to include the new host. *Honest scope note:* `telemetry: "estimated"` — no native usage/cost parsing was implemented for `agy`'s own JSON output in this item (that's tracked separately under item 28.3, which already shipped `estimated` for gemini-cli/generic/omnigent); `subagents`/`hooks`/`goalLoop` are declared `false` even though `agy` has some native equivalents (an `--agent` flag, plugin `hooks.json`) because Stagecraft doesn't wire into them here, matching the existing codex/gemini-cli stance of only declaring capabilities Stagecraft itself dispatches through.

- **Orchestrator-observed token telemetry for codex; honest `estimated` fallback elsewhere (phase-28 item 28.3).** The codex headless command now requests `--json`; `core/adapters/codex-exec-json.js` parses the resulting JSONL for the `turn.completed` event's `usage.input_tokens` / `usage.cached_input_tokens` / `usage.output_tokens` (codex reports neither a model id nor a dollar cost in this stream, so `model_observed`/`cost_usd` stay `null` rather than guessed), tees only the readable `agent_message` text into the transcript log, and `core/orchestrator.js`'s shared `patchGateForObservedUsage` writes it onto the workstream gate under `_orchestrator_observed` with `source: "codex:exec-json"`. Every host's `capabilities.json` now declares `telemetry: "native"` or `telemetry: "estimated"` (enforced by `tests/adapter-contract.test.js`; claude-code and openai-compat are `native` per items 28.1/28.2, codex per this item, gemini-cli/generic/omnigent are `estimated`). For `estimated` hosts, a new `patchGateForEstimatedUsage` records `_orchestrator_observed: { tokens_estimated: true, tokens_in_estimate, source: "orchestrator:prompt-bytes-estimate", at }` — a `promptBytes / 4` heuristic, distinctly named from `tokens_in` and always paired with the `tokens_estimated` flag so it can never be silently mixed with an observed value. *Honest scope note:* gemini CLI's `-o json`/`-o stream-json` do carry token stats in principle (confirmed by reading the installed CLI's bundled source), but its backend has returned 404s since 2026-06-18 and the host is being retired in favor of Antigravity (item 28.6) — a native parser was not built for a host on its way out; it falls back to the estimate. `--budget-usd`/`devteam status` preferring observed cost over self-reported (item 28.4) remains follow-up work.

### Added

- **Inline the framework set and role brief into the cacheable prompt prefix (phase-37 item 37.2).** Layers 1-2 of every stage prompt — `AGENTS.md`, `.devteam/rules/pipeline.md`, `.devteam/rules/gates-core.md`, and the role brief — now carry those files' actual content, in the stable order phase 32.1 established, instead of just naming their paths. The verify-first measurement in `plans/phase-37-interface-and-token-efficiency.md` §37.2 found the pointer-only prefix shared across two same-role dispatches was 213 B (12.7% of the prompt; the plan's own prior measurement cited 268 B/15.2%) — the ~22 KB framework block was paid at full price every dispatch via 4+ sequential tool-call reads, with almost nothing cacheable. Inlining moved the shared prefix to 18,932 B (92.8%) in the same measurement, and eliminates those reads entirely. New config `prompts.inline_framework` (default `true`) gates this; `false` reproduces the pre-37.2 path-pointer rendering byte-for-byte, for a host with no prefix caching and a small context window. `openai-compat`'s existing `cache_control` breakpoints (32.1) land after the now much larger inlined block unchanged. `core/evals/run.js`'s structural scoring now recognizes both the inlined and pointer framework headings.

  Honest scope note: `docs/reference/prompt-budget.md`'s per-dispatch byte totals are unchanged by this item — that doc already counted the full framework + role-brief bytes as consumed per dispatch regardless of whether they arrived inline or via a tool-call read, so there is nothing to re-baseline there; the growth this item causes is in the *literal* rendered-prompt size (measured above), not in that file's metric, and `npm run consistency`'s prompt-budget advisory does not fire. Rewriting the role briefs to be smaller (tempting now that their size is cacheable) is explicitly out of scope for this phase.

### Added

- Added p50/p95 duration and retry-adjusted completion metrics to performance and routing suggestions, plus capacity guidance for remote runners, prompt caching, and persistent-session boundaries.
- Added bounded changed-file manifests with path/status/byte/digest facts so stage prompts can slim repeated context while preserving on-demand reads.
- Added per-dispatch prompt byte and manifest-count telemetry to run logs, status state, and evidence aggregates without storing prompt text.

### Added

- **Memory retrieval into stage prompts + auto-ingest at run end — phase-30 item 30.4 (`docs/memory.md`).** When `.devteam/memory/` already exists and `memory.inject` isn't `false` (both true by default once a project has run `devteam memory ingest` at least once), every **headless** stage dispatch (`devteam run`, `devteam stage --headless`) now queries the store for the top `memory.inject_top_k` (default 3) chunks similar to the stage's feature/brief text, filters by `memory.inject_similarity_floor` (default `0`), and renders a bounded (≤1,200 bytes) `## Prior Project Knowledge` section with kind + source attribution per entry — same greedy accumulate-skip-oversized budget discipline as `Known Project Patterns` (`core/patterns.js` `selectForDescriptor()`). Stage 2 (design) descriptors additionally query the org-shared store for `kind: adr`, making `devteam architecture lookup` automatic instead of a role-brief-only suggestion (`roles/principal.md` updated; the manual command remains for deeper/broader queries). `core/driver.js` also auto-ingests once at a clean `pipeline-complete`, gated on the same `.devteam/memory/`-exists condition and reusing `memory.inject` as the single on/off switch for both sides of the loop — fire-and-forget, an ingest failure (including the optional `@huggingface/transformers` dependency being absent) is logged (`memory-ingest-failed`) and never fails the run. New config: `memory.inject` (default `true`), `memory.inject_top_k` (default `3`), `memory.inject_similarity_floor` (default `0`). New module `core/memory/inject.js` (`priorKnowledgeForStage()`) and `renderPriorKnowledge()` (`core/adapters/render-helpers.js`, wired into all seven host adapters). *Honest scope note:* `buildDescriptor()`/`runStage()` (`core/orchestrator.js`) are and remain synchronous — 37 direct `runStage()` calls and 25+ `buildDescriptor()` calls across the test suite, plus three preview-only CLI commands (`devteam stage` without `--headless`, `devteam reproduce`, `devteam replay`), assume a plain synchronous return, and embedding is inherently async. Retrieval is therefore pre-fetched in `runStageHeadless()` (the one dispatch path that was already async) and threaded through as a plain `opts.priorKnowledge`/`descriptor.priorKnowledge` field; the interactive (non-headless) preview path does not query memory. Tests: `tests/memory-injection.test.js` — gating (blank query text, no store, `memory.inject: false`), similarity-floor filtering + kind/source attribution, deterministic budget truncation favoring highest similarity, stage-02-only org query, one-warning embedder-absent degradation, `renderPriorKnowledge()` rendering, `buildDescriptor()`/`runStage()` threading (byte-identical prompts when absent), an end-to-end `runStageHeadless()` wiring test with a hand-seeded store record (deterministic similarity via an identical query/stored embedding), a stage-02 org-ADR end-to-end test, and driver auto-ingest (store-present/absent, `memory.inject: false`, and the fire-and-forget failure contract). `tests/config.test.js` covers the new config defaults/overrides. No pre-existing tests required changes: gating auto-ingest on `.devteam/memory/` already existing means the many driver tests built on `makeTargetProject()`'s bare fixture (no memory store) see zero new run-log events.

### Added

- **Per-role/per-stage model-tier routing + escalate-on-retry — phase-32 item 32.3 (`docs/user-guide.md` "Pinning a model in routing config", `docs/cost.md`).** `routing.roles.<role>` and `routing.stages.<stage>` now accept either the pre-32.3 bare host-name string (unchanged, still the only form `devteam init` writes) or `{host, model}` to also pin a model for that role/stage. `core/config.js`'s new `resolveRoute(config, stage, role)` implements the unchanged stage→role→critic-diversity→default_host precedence but returns `{hostName, model}`; `resolveHost` stays a byte-identical wrapper around `.hostName` for every pre-32.3 caller. `core/router.js`'s `resolveAdapter` surfaces the resolved model alongside the adapter. Verify-first inventory found the routed model reaches every headless host by an identical `--model <value>` CLI flag (`claude`, `codex`, `gemini`, `agy`) — `core/adapters/headless.js`'s shared `runHeadless` appends it generically when `descriptor.model` is set, so claude-code/codex/gemini-cli/antigravity needed no adapter-specific code. `hosts/openai-compat/invoke.js` and `hosts/omnigent/adapter.js` (both non-`runHeadless` paths) were extended so the routing-pinned model takes precedence over their existing `hosts.openai-compat.models`/`hosts.omnigent.model` config, preserving that config as the fallback. The model actually requested is stamped onto the dispatch's gate as `model_requested` (orchestrator-set, fire-and-forget, mirroring the `_orchestrator_observed`/`_orchestrator_stamped` provenance pattern — distinct from the model-asserted `model` field and from `_orchestrator_observed.model_observed`) and threaded into `.devteam/corpus/dispatches.jsonl`. New `routing.tiers` (per-host ordered cheap→frontier model ladder) + `routing.escalate_on_retry` (default `false`) bump a pinned model exactly one tier on a fix-and-retry re-dispatch (`core/config.js`'s `escalateModel`, applied in `core/orchestrator.js` when the driver signals `opts.isRetry`), recorded as `_orchestrator_escalated: {from_model, to_model, reason, at}`. The "frontier plans, cheap executes" preset is documented as an opt-in config block in `docs/user-guide.md` + `docs/cost.md` — not a changed default. `scripts/performance.js` gains an additive `aggregatePerformanceByModel` (groups `(role, host, model)` instead of `(role, host)`, leaving the existing aggregation untouched) feeding a new "per-tier cost delta" section in `npm run routing:suggest`'s report.
  - Tests: `tests/config.test.js` (`resolveRoute` back-compat + object-form + critic-diversity-with-object-routes + `escalateModel`), `tests/router.test.js` (`resolveAdapter` surfaces `model`), `tests/headless.test.js` (`--model` reaches the spawned command; absent when unpinned), `tests/openai-compat-adapter.test.js` and `tests/omnigent-adapter.test.js` (routing pin overrides host-native config; falls back when unset), `tests/orchestrator.test.js` (`model_requested` stamped on the gate; escalate-on-retry bumps/doesn't bump per config; three fire-and-forget cases for the new patch function), `tests/run.test.js` (driver passes `isRetry: true` only on a fix-and-retry re-dispatch), `tests/corpus.test.js` (`model_requested` round-trips into the corpus record), `tests/performance.test.js` and `tests/routing-suggest.test.js` (`aggregatePerformanceByModel` / `buildTierDeltas` / `renderTierDeltas`).
  - Honest scope note: escalation is a single one-tier bump per fix-and-retry dispatch, not cumulative across repeated retries of the same stage — a second retry re-escalates from the route's pinned model, not from wherever the first retry landed. Escalation isn't yet folded into pre-dispatch `--budget-usd` enforcement (same gap as D7/28.4's cost-preference work). Fanout entries (`routing.review_fanout`) don't carry a routing-resolved model in this pass — only the primary stage/role resolution path does.

### Added

- **Opt-in mutation smoke gate for stage-06 — Phase 31.4.** `core/verify/mutation.js`, wired into `core/verify/stamp.js#stampStage06`. Disabled by default (`pipeline.verify.mutation.enabled: false`); when enabled, the orchestrator detects a supported mutation-testing runner already present in the target project — Stryker via a `@stryker-mutator/core` package.json devDependency (JS/TS), mutmut via the binary already on PATH/venv (Python), never installed by devteam — and runs it against the changed-file set only (`pipeline/changed-files.txt`, the same source `redteam-floor.js` uses), intersected with an optional `pipeline.verify.mutation.paths` scope. The run is time-boxed via `pipeline.verify.mutation.timeout_ms` (default 5 min), reusing `runCommand`'s existing `core/process-kill.js` machinery — a hung run is killed and recorded as a skip, never a false pass. The parsed score, runner, and scope are stamped onto the gate as `mutation_score` / `mutation_runner` / `mutation_scope`. Below `pipeline.verify.mutation.threshold` (default `0.7`) is advisory: a gate warning plus a `noted_for_followup` entry (`severity: "high"`) so it surfaces in `devteam advise` classification (routes to `PEER_REVIEW_RISK`) rather than being silently absorbed; it only becomes a blocking FAIL when `pipeline.verify.mutation.threshold_hard: true`. An absent runner, an empty scope, a timeout, or unparseable tool output are all recorded as an honest skip. `docs/verification-beyond-tests.md` now documents this mechanical gate distinctly from stage-06d's model-driven, full-track-only mutation pass, which it does not replace.

  Tests: `tests/verify-stamp-mutation.test.js` — disabled-by-default leaves stage-06 untouched; no-runner and empty-scope cases record honest skips; a below-threshold fixture WARNs and its `noted_for_followup` item classifies `PEER_REVIEW_RISK` via `core/advise.js#classifyItem`; an at/above-threshold score does not warn; `threshold_hard: true` flips a model-PASS gate to FAIL; a hung mutation command is killed cleanly at `timeout_ms` and recorded as a skip; unit coverage for runner detection, path-scope intersection, and Stryker output parsing.

  Honest scope note: mutation-tool output parsing is regex-based against each tool's documented clear-text summary format (Stryker's `N/M mutants killed (X%)` line, per `skills/verification-beyond-tests/SKILL.md`'s worked example; mutmut's emoji progress line) rather than a structured report file — unparseable output is always an honest skip, never a fabricated score, but a future tool version that changes its summary format will silently downgrade to skips until the regex is updated. `pipeline.verify.mutation.command` is an added override beyond the plan item's literal config shape (`{enabled, threshold, threshold_hard, timeout_ms, paths}`), mirroring the existing `dependency_audit_command` override from 31.2 — without it there is no way to exercise the run/parse/threshold pipeline in tests without a real Stryker/mutmut install, which devteam must never do. mutmut's real-world output format is inferred from documented CLI behavior, not verified against a live install; the Stryker-format branch is exercised end-to-end via the same override, but neither runner's auto-detection path (real `npx`/`mutmut` invocation) is exercised in CI, the same limitation `runSemgrepFloor`'s tests already accept for a binary devteam cannot assume is installed.

### Added

- Add experimental `devteam stage --headless --experimental-omnigent-director` mode for all-Omnigent multi-workstream stages, preserving normal child gate validation and merge behavior.

### Changed

- Add `hosts.omnigent` launch profile config for harness/model/server/session selection while preserving `DEVTEAM_HEADLESS_COMMAND` override precedence.

### Changed

- Add opt-in Omnigent policy-file generation for allowed writes, shell/network requirements, and role tool budgets.

### Changed

- Use Omnigent's current `--prompt` transport by default, with stdin and opt-in `--prompt-file` compatibility modes.

- **Omnigent runtime adapter** (closes #291). Adds a first-party `omnigent` host adapter that
  installs Stagecraft role prompts, skills, rules, templates, and a default
  Omnigent agent bundle under `.omnigent/stagecraft/agent/`, then invokes Omnigent's
  one-shot `omnigent run ... --no-session --prompt <prompt>` path for headless
  workstreams. The design and Phase 24 plan document the intended evolution:
  configurable harness/model launch profiles (#292), hardened prompt transport
  (#293), Omnigent-policy bridging (#294), session evidence (#295), and a later
  director-mode experiment (#296). *Honest scope note:* this first slice treats Omnigent as a
  conservative host runtime with Stagecraft post-hoc write auditing; Omnigent-managed
  Codex runtime-home cache writes under `.codex-tmp/omnigent-codex-home-*` are ignored, but it does
  not yet claim Omnigent-native tool-call-time enforcement, sub-agent
  consolidation, or remote-session evidence.

### Changed

- Record adapter-private Omnigent session evidence sidecars with session/conversation IDs and policy verdict counts.

### Fixed

- Exempt OpenAI-compatible adapter orchestrator state and transcript files from
  post-hoc write audit in bounded isolation, matching the in-place behavior.

- **Orchestrator-observed token/cost telemetry for openai-compat (phase-28 item 28.2).** `hosts/openai-compat/invoke.js` now sums `usage.prompt_tokens` / `usage.completion_tokens` / `usage.prompt_tokens_details.cached_tokens` across every turn of the tool loop and computes `cost_usd` via `core/pricing.js` `computeCostUsd` (unknown model → `cost_usd: null`, never a guess). `core/orchestrator.js`'s shared `patchGateForObservedUsage` (introduced for claude-code in item 28.1) writes the result onto the workstream gate under `_orchestrator_observed`, now generalized to record a per-adapter `source` (`"claude-code:stream-json"` / `"openai-compat:usage"`) and an optional `cached_tokens` field — distinct from and never overwriting the model's self-reported `tokens_in`/`cost_usd`/`model` fields. A response with no `usage` object degrades to `telemetry: "unavailable"` and no gate mutation, same fire-and-forget contract as 28.1. *Honest scope note:* codex and gemini-cli/antigravity (item 28.3) and `--budget-usd`/`devteam status` preferring observed cost over self-reported (item 28.4) remain follow-up work; openai-compat's `cost_usd` is a token × pricing-table estimate (no cache discount applied), not a provider-billed figure like claude-code's.

- **Project-local pattern learning begins.** Added `devteam patterns collect/list/review/promote/retire/stats`, local `.devteam/patterns/` storage, sanitized observation collection from gates and archived retry failures, explicit promotion with secret-shaped text rejection, retired-pattern suppression, and a bounded `Known Project Patterns` prompt section for promoted guidance. *Honest scope note:* this first slice is advisory and project-local; live retry hooks, positive first-pass reinforcement, import/export, noise reporting, and deterministic-gate graduation recommendations remain follow-up work.

- **Patterns collect automatically at run end.** `devteam run` now calls pattern collection itself, fire-and-forget, on a clean `pipeline-complete` and on any halt that left a gate on disk — closing the loop that previously required a manual `devteam patterns collect` after every run. Collection also now consults `retired.json`: a candidate matching a retired pattern's identity is dropped and counted as `suppressed` in the collection summary instead of silently re-entering the candidate pool. `devteam patterns collect` is unchanged for manual and backfill use. *Honest scope note:* `devteam patterns list`/`review`/`promote` still recompute candidates independently from raw observations and do not consult `retired.json` or `pending-review.json` — retired-key suppression only guards the auto/manual collection path, not those commands directly (tracked as an out-of-scope finding).

### Added

- **Wire the pattern-learning outcome-feedback counters and add a demotion flow — phase-30 item 30.2 (`docs/pattern-learning.md`).** `stats.injected` and `stats.recurrence_after_injection` on a promoted pattern were initialized at promotion and never incremented anywhere; this closes that loop. `core/patterns.js` gains `recordInjection()`, called at real DISPATCH time only — `core/orchestrator.js`'s `runStageHeadless` (both the normal per-workstream path and the omnigent-director path) and `core/cli/commands/stage.js`'s non-headless "print the prompt for a human to paste into a host" path — never at a preview/render-only call to `runStage()` (`devteam reproduce`, `devteam replay --dry-run`), since no model ever sees those renderings. Each real dispatch increments every injected pattern's `stats.injected` once and appends a `pattern-injected` run-log event. `collect()` reads those events back and increments `recurrence_after_injection` when a blocker maps to a pattern id that was injected into that same stage's dispatch this run; detection is keyed by gate file identity (a new `.devteam/patterns/recurrence-checked.json`), not observation fingerprint, because a recurring blocker shares its fingerprint with the observation that got the pattern promoted in the first place. `devteam patterns review` now flags a promoted pattern as a demotion candidate once `recurrence_after_injection` reaches `patterns.demotion_recurrence_threshold` in `.devteam/config.yml` (default `3`) — flagging only, never automatic. `devteam patterns demote <id>` is the new explicit operator action that moves a promoted pattern back to candidate status into `.devteam/patterns/demoted.json`, recording an audit line (`demoted_by`, `demoted_at`, `reason`, `counters_at_demotion`) that survives a later `devteam patterns promote <id>` re-promotion. Docs: `docs/pattern-learning.md` (new "Outcome-Feedback Counters" section, updated Storage/Open Decisions), `docs/reference/cli.md` (regenerated). Tests: `tests/patterns.test.js` — a real headless dispatch increments `stats.injected` exactly once while a preview-only `runStage()` call never does; a seeded three-attempt recurrence scenario flags the pattern in `devteam patterns review` and stays idempotent on a second `collect()`; demote → promote round-trips preserve `demotion_history` and re-enable selection; counters persist across `collect()`/`promote()` cycles without one pattern's write clobbering a sibling's stats. Honest scope note: `stats.noise_reports` remains unwired — no command produces a noise report yet, so review can only ever flag on recurrence, not operator-reported noise. Auto-demotion and auto-retirement remain explicitly out of scope, consistent with the design doc's "promotion is explicit" stance.

### Added

- **`devteam patterns export --skill` — SKILL.md export of promoted patterns, phase-30 item 30.5 (`docs/pattern-learning.md`).** Serializes every currently-promoted pattern (`prompt_text`, `tier`, `domain`, and a short evidence-based rationale — never raw observations) into a `SKILL.md` file following the [Agent Skills open standard](https://agentskills.io/specification) (spec fetched 2026-07-31: `name` 1-64 chars, lowercase alnum/hyphen, no leading/trailing/consecutive hyphen, and must match the parent directory name; `description` 1-1024 chars), so the same learned knowledge loads natively in Claude Code, Codex, Cursor, and Gemini/Antigravity outside a devteam run. Because `name` must match its directory, `[--out <dir>]` is treated as a *parent* directory rather than the skill directory itself — the skill always lands at `<out>/learned-patterns/SKILL.md` (`.devteam/learned-patterns/SKILL.md` by default) — so the constraint holds unconditionally instead of only for the default path. The generated file opens with `<!-- Generated by devteam patterns export; regenerate to update; do not hand-edit. -->` and groups patterns into one Markdown section per `domain`; re-exporting with an unchanged `promoted.json` produces a byte-identical file (no timestamps embedded). The rendered output is re-scanned with the same secret-scan path `devteam patterns promote` already uses (`core/hooks/secret-scan.js`'s `scanContent`) before anything is written — defense in depth against a hand-edited `promoted.json`, since `prompt_text` is otherwise only scanned once, at promotion time. `devteam init` now mentions the export path in its summary output — never auto-installs it — whenever promoted patterns already exist and at least one host being initialized declares a `skillsDir` in its adapter capabilities (read per-adapter, not hardcoded, so a new host adapter picks this up automatically). Docs: `docs/pattern-learning.md` (new "SKILL.md export (30.5)" subsection under Privacy and Export, plus a history update), `docs/reference/cli.md` (regenerated). Tests: `tests/patterns.test.js` — export produces spec-conformant frontmatter (name/description constraints, name-matches-directory-name) and a domain-grouped body; two exports over an unchanged `promoted.json` are byte-identical; `--out` always resolves to `<out>/learned-patterns/`; a `promoted.json` hand-edited to contain a secret-shaped `prompt_text` is rejected and no file is written; the CLI subcommand round-trips end-to-end and errors with exit code 2 when `--skill` is omitted. `tests/init.test.js` — the export tip appears only when promoted patterns exist *and* the initialized host has a skills directory, confirmed both ways plus for `generic` (no `skillsDir`) with patterns present. Honest scope note: only the Agent Skills format is supported (`--skill` is currently mandatory, not a choice among formats); `devteam init` never copies the exported directory into a host's skills directory itself — that copy step stays manual, consistent with the item's "no auto-install without the existing init overwrite rules."

### Added

- **Stage-05 (peer-review) quorum re-derivation — Phase 31.5.** Approval state was only kept honest by the claude-code PostToolUse hook (`core/hooks/approval-derivation.js`); on every other host — and any claude-code save that happens outside the hook, which is why `devteam derive-approvals` exists — a workstream gate could claim `PASS` off a status that was never actually derived from `pipeline/code-review/by-*.md`. `core/verify/stamp.js#stampStage05Merged` closes that gap: after stage-05 merges, the orchestrator re-derives approval state itself by calling the hook's own `parseReviewFile()` directly (never reimplementing the `REVIEW:`/`CHANGES REQUESTED` grammar) over every `by-*.md` file, on every host, unconditionally. A panel-mode workstream gate (`backend`/`frontend`/`platform`/`qa`) claiming `PASS` whose review file says `CHANGES REQUESTED` — or has no parseable verdict for that area at all — flips the merged stage-05 gate to `FAIL`, with a `{field: "approval_state", workstream, gate_said, file_said}` record on `_orchestrator_stamped.fields` and a matching blocker. `stage-05` joins `STAMPABLE_MERGE_STAGES` alongside `stage-04`, wired through the existing merge-time stamping call site in `core/driver.js` (no new call sites needed).

  Tests: `tests/verify-stamp.test.js` — a seeded mismatch (gate says `APPROVED`, review file says `CHANGES REQUESTED`) flips the merged gate to FAIL with the field-level record; agreeing states leave the merge untouched (no fields recorded, no status override); a workstream claiming `PASS` with no matching review-file section at all is recorded as its own `NO_PARSEABLE_VERDICT` mismatch class; adversarial mode's `reviewer`/`critic` workstreams are left untouched. Also updated `tests/verify-stamp.test.js`'s pre-existing "stampMerged rejects a stage with no merged stamping defined" test, which used `stage-05` as its not-yet-stampable example — swapped to `stage-06`, which still has no merged stamper.

  Honest scope note: scoped to panel mode's per-area workstreams only. Adversarial mode's (31.3) `reviewer`/`critic` workstreams aren't area-named — `by-reviewer.md` rolls every area into one combined gate and `by-critic.md` uses a different (challenge) grammar entirely — so re-deriving them against a per-area map isn't a valid comparison; they're left to their own existing verification path (evidence-required challenge disposition). This re-derivation also doesn't recompute *how many* distinct reviewers approved an area (the `required_approvals` count) — only whether any review file for a `PASS`-claiming area contradicts or is silent on that claim. Re-verifying quorum counts independently would be a natural follow-up but is out of scope for this item.

### Fixed

- **`devteam help <command>` and `devteam <command> --help` now print real, command-scoped help — Phase 37.1.** Previously `devteam help <anything>` ignored its argument and printed the identical 343-line full command list regardless of what was passed. Both forms now generate help from that command's own flag spec (`core/cli/flags.js#generateHelp`) — a synopsis/usage line, then each flag with its `(type)` and description — with no hand-written per-command prose to drift out of sync. `devteam help <command>` delegates to the target command's own `--help` handling (`cmd.run([], { help: true })`), so the two forms are guaranteed byte-identical: it's the same code path, not two implementations kept in sync by hand. `devteam help` with no argument is unchanged. An unknown command name (either form) now prints the full command list plus a "did you mean" suggestion from a small Levenshtein-distance helper (`core/cli/nearest-match.js`, no new dependency). The `bin/devteam` → command-module map moved to `core/cli/command-list.js` so `help.js` and `bin/devteam` resolve command names from one shared list instead of two.

  Also fixed: `devteam hosts --help` and `devteam stages --help` previously exited 2 ("Unknown flag: --help") since neither command declared a `help` flag; both now support it like every other command.

  Tests: `tests/help-cmd.test.js` — `help run` and `run --help` produce byte-identical output under 60 lines covering all 21 of `run`'s flags with their types; output differs between two different commands (the regression this item fixes); an unknown command name suggests a near match via both entry points; `help` with no argument is unchanged; and a meta-test asserting every flag in every one of the 44 command modules has a non-empty description (all already did — no spec fixes were needed). `tests/flags.test.js` gained a unit test for `generateHelp`'s new `(type)` tag.

  Honest scope note: the "synopsis line" called for in the plan item is realized as the existing generated `Usage: devteam <command> [options]` line rather than a new hand-authored one-line blurb per command — adding a separate synopsis field to all 44 modules would have created a second place (beyond the flag spec) to keep in sync, working against the single-source-of-truth goal this item is for.

### Added

- **Per-role orchestrator stamping for stage-04 (Build) — Phase 31.1.** Orchestrator-stamped verification previously stopped at `plan.workstreams.length === 1`, so build's four role workstreams (backend/frontend/platform/qa) and their merged gate were never independently verified — only model self-report. Two new stamp scopes in `core/verify/stamp.js`: `stampStage04Workstream` runs a lint check scoped to each role's `allowedWrites` directories (paths appended as extra args to the configured lint command — best-effort; tools that ignore extra positional args just lint the whole project, but `scoped_paths` records what was requested) and stamps `lint_passed`/`tests_passed` onto that role's own gate as it completes (wired into `core/orchestrator.js`'s per-workstream dispatch loop); `stampStage04Merged` runs the full test suite exactly once, after `mergeWorkstreamGates` writes the merged `stage-04.json` (wired into `core/driver.js`'s merge handler), and overrides a model-claimed `tests_passed` that disagrees with the observed suite result. `mergeWorkstreamGates` now rolls any per-role `tests_passed` self-report into the merged gate so the merged-level check has a claim to compare against. Verification receipts (already content-addressed by command+workspace+config+env) mean the per-role test checks and the merged check collapse to one real subprocess execution rather than one per workstream — proven via receipt-hit counting, not new dedup logic. Tests: `tests/verify-stamp.test.js` (lint scoping, status-flip + model_said audit trail, skip messaging, merged override, receipt-collapse across 4 roles + merge, dispatch rejection paths), `tests/orchestrator.test.js` (`tests_passed` roll-up aggregation, end-to-end `runStageHeadless` wiring including `stamp: false`), `tests/run.test.js` (driver wires the merged stamp in after merge and it wins over the model's claim). Existing single-workstream stamping (stage-03b/04a/06) is untouched — same code path, same behavior.

  Honest scope note: lint scoping is best-effort (path args aren't guaranteed to be honored by every lint tool/config); the standalone `devteam merge` CLI command does not yet trigger the merged-level stamp (only the `devteam run` driver loop does); `devteam verify stage-04` does not yet support on-demand multi-workstream re-stamping. All are natural follow-ups, not required for this item's acceptance criteria.

### Changed

- **Docs: phase 35 marked complete; track-list and stage-06d drift fixed.** `plans/phase-35-existing-codebase-mode.md`, `plans/README.md`, and `plans/landscape-review-2026-07.md` still described `review-only`/`devteam review-pr` (35.1/35.2) as not-started and phase 35 overall as proposed, despite all five items being merged (#373, #375, #376, #377, #378) — reconciled against `git log`. `docs/concepts.md`/`docs/FEATURES.md`'s "Nine tracks" was stale after the `refactor` track landed (now "Ten tracks"); the stage-06d ("verification beyond tests") description still described pre-35.3 model-self-report-only behavior — added a note on `core/verify/stamp.js#stampStage06d`'s orchestrator-verified re-run/downgrade. `docs/FEATURES.md` gained a `devteam review-pr` write-up next to the existing outbound "GitHub PR integration" section, checked against `core/cli/commands/review-pr.js`'s actual `--post`/`--yes`/partial-vs-FAIL behavior before writing.
  - **Also fixes three pre-existing gaps** flagged as out-of-scope findings in #378: `core/gates/schemas/gate.schema.json`'s `track` enum was missing `"loop"`; `templates/README.md`'s "eleven templates" table hadn't been updated in several phases (now lists all 21, including `characterization-template.md`, and fixes a stale destination path); `rules/orchestrator.md`'s inline track-list comment was missing `loop`/`review-pr`/`refactor`.

  Honest scope note: no behavior changed — `gate.schema.json`'s `track` enum isn't ajv-validated at runtime in this repo (structural/meta-tested only, per `tests/schemas.test.js`), so adding `"loop"` is a documentation-accuracy fix, not a behavior change. No new tests were needed for a docs-only pass; existing `npm run consistency` checks are the acceptance gate.

### Fixed

- **Read-only reporting commands no longer invent a pipeline outside a Stagecraft project (phase-37 item 37.3, `plans/phase-37-interface-and-token-efficiency.md`).** `devteam next`/`summary`/`status`/`log`/`validate` had no initialisation check, so running any of them in a directory that was never `devteam init`-ed silently fell through to `core/config.js`'s defaults and reported a fabricated stage-01 zero-state (`▶️ run-stage — requirements (stage-01)`) as though a real pipeline were waiting there. Added one shared guard, `core/cli/project-guard.js#requireProjectContext`, wired into exactly those five commands: it detects a missing `.devteam/config.yml`, exits non-zero, and prints what's missing plus the fix (`devteam init --host <name>`); `--json` callers get a structured `{error, command, cwd, message, fix}` object instead of a silent zero-state. Commands that legitimately run without a project (`init`, `review`, `review-pr`, `hosts`, `stages`, `help`, `doctor`) are explicitly exempted and asserted so by a meta-test in `tests/project-guard.test.js`, which also checks that the guarded list is actually wired and the unguarded list isn't accidentally guarded — the split can't drift silently as commands are added.

  Honest scope note: the plan's verify-first claim pointed at `core/cli/commands/review-pr.js` as the precedent for this refusal shape, but `review-pr.js` doesn't refuse at all — it silently falls back to a review workspace when `.devteam/config.yml` is absent (phase-36 item 36.5), which is correct behavior for that command, not a refusal. The actual existing refusal-shape precedent is `core/cli/commands/stage.js`'s warn-before-printing check; this fix reuses its wording (adapted from a warn-and-continue into an exit(1) refusal, since these five commands have nothing honest left to report without a project).

### Added

- **GEPA-style offline prompt optimizer — Phase 33.4.** `scripts/prompt-optimize.js` (out-of-band, like `scripts/budget.js` — deliberately not a `devteam` command): given a `--target roles/<role>.md` or `rules/<name>.md` and a mandatory `--budget-usd`, samples the captured eval cases (`.devteam/evals/cases/`, phase-33.1) that exercise the target's stages, runs a bounded (default 4) reflective loop — one frontier-model diagnosis call per iteration proposing a revised file body — and scores each candidate against a real, unmodified `core/evals/run.js` structural baseline, `scripts/prompt-budget.js`'s byte-ceiling accounting recomputed with the candidate's size, and a budget-capped real-model dispatch subset (the candidate patched into a scratch project, never the real repo file). Candidates are kept as a Pareto frontier (pass-rate vs. token size, `arXiv:2507.19457` §3.2) rather than a single greedy winner. Output: a unified diff for exactly the target file (generated by diffing original vs. winning-candidate content directly — never a model-produced diff) plus an evidence table, printed to stdout and written under `.devteam/evals/optimize/`. **Never writes the target file itself** — the diff is for human review like any PR. A candidate whose structured response proposes a different `target_path` than requested is rejected outright (the diff-scope guard).

  Tests: `tests/prompt-optimize.test.js` — end-to-end against the checked-in fixture corpus with a scripted headless host produces a diff touching only the target file plus an evidence table; refuses to run without (or with a non-positive) `--budget-usd`, before any dispatch; a candidate proposing a different `target_path` is rejected with no diff produced; the diagnosis model is invoked exactly `--iterations` times, never more; Pareto-frontier dominance pruning.

  Honest scope note: every host adapter renders a role brief or rule file as a path pointer, never inlined content — confirmed by reading `core/adapters/markdown-host.js` and `hosts/claude-code/adapter.js` (a VERIFY-FIRST check against this item's own claim). A candidate's content therefore never changes the rendered dispatch prompt text, only what a real host CLI reads from disk when it acts on the pointer. "Structurally valid" is checked via the real `core/evals/run.js` stub path (content-invariant, a sanity floor); "within prompt budget" is checked via `scripts/prompt-budget.js`'s own byte accounting with the candidate's size substituted in (this DOES vary per candidate). Locating a role brief's installed copy inside a scratch project for the real-model subset is done generically, by byte-matching installed `.md` files against the original content — untested against any host beyond `claude-code` (verbatim rule-file installs are uniform across every host and don't need this). `--model` selects a dispatch HOST adapter (the `evals run --headless-host` convention), not a raw model id — Stagecraft always resolves an actual model indirectly via host + `routing.tiers`, so this follows that precedent rather than inventing a new flag. Cost tracking reuses `core/evals/run.js#costPreview`'s posture exactly: an input-token estimate priced off the most recently observed model for `(role, host)` in the run corpus — an estimate, never a bill, and `null` (untracked) when no prior dispatch exists to price against, same as a brand-new project's first `evals run --headless-host` sweep.

### Added

- **`prompt_pack_version` — a content-hash version for the prompt surface, recorded everywhere, comparable (Phase 33.3).** New `core/prompt-pack.js#computePromptPackVersion`: a sha256 (truncated to 12 hex chars) over every file under `roles/` + `rules/` + `templates/` (stable sorted ordering), so the version changes if and only if a role brief, rule file, or template changes. It's orchestrator-computed, never model-asserted — recorded on the gate two ways, mirroring `dispatched_tool_budget`'s dual-path convention: `core/orchestrator.js#patchGateWithPromptPackVersion` stamps it onto every workstream gate (and the merged stage gate) for headless runs; `core/gates/validator.js#autoInjectMetadata` injects it for user-driven runs. The same value is also recorded on every run-corpus row (`core/corpus.js`, phase-28 item 28.5) and every eval case (`core/evals/capture.js`, phase-33 item 33.1), read straight off the gate.

  New `devteam evals compare --pack <A> --pack <B> [--min-n <n>] [--json]` (`core/evals/compare.js`): per-stage pass-rate deltas between two `prompt_pack_version` values from the run corpus, with dispatch counts, so "did the new principal brief help?" is a query instead of a feeling. Honesty rule: a stage with fewer than `--min-n` dispatches (default 5, the same floor D5 uses in `core/corpus.js#computeStats`) on either pack is reported `refused` and never assigned a delta.

  Docs: `docs/reproducibility.md` new "Prompt-pack version (C4's consumer)" section; `docs/observability.md` corpus record example updated; `docs/reference/cli.md` regenerated.

  Tests: `tests/prompt-pack.test.js` — version changes iff any file's content or path under roles/rules/templates changes, unaffected by files outside those three directories, stable across repeated calls. Propagation, added to the existing suites for each stamping/read site: `tests/orchestrator.test.js` (headless workstream + merged-gate stamping, idempotent — a pre-existing value is never overwritten — and the fire-and-forget contract), `tests/gate-validator.test.js` (the validator's auto-injection for user-driven gates), `tests/corpus.test.js` (a corpus row via `recordDispatch`, `null` when the gate has none), `tests/evals-capture.test.js` (a captured eval case). `tests/evals-compare.test.js` — per-stage deltas on a fixture corpus, the minimum-n refusal (default and custom `--min-n`), stages that only appear for one pack, an empty corpus, and the CLI's `--pack`/`--json` wiring including the "exactly two `--pack` values" guard.

  Honest scope note: `prompt_pack_version` hashes this framework installation's own bundled `roles/`/`rules/`/`templates/` directories, not a target project's installed `.devteam/{rules,templates}/` copy — those can diverge if a project hand-edits its installed rules (`core/adapters/base-install.js`'s `installRules`/`installTemplates` skip existing files by default), and role briefs are rendered into per-host formats with no single installed `roles/` directory to hash consistently across hosts (see `base-install.js`'s header comment). The version therefore answers "did the framework's own prompt surface change" reliably; it does not detect a project's local customization drifting from what it was installed with.

### Added

- Add `devteam prototype build <id>` as an explicit host-run step for
  prototype packets. The command runs the packet's `build-prompt.md` through a
  headless host, records the build in `prototype.json`, and keeps output in
  `pipeline/prototypes/<id>/workspace/` by default.
- Add `--apply-to-project` for the deliberate escape hatch where prototype code
  should touch the project root. Prototype builds remain pre-SDLC learning
  records, not gate evidence.

- **Prototype mode workflow.** Add `devteam prototype start|note|promote`
  for fast pre-SDLC learning loops under `pipeline/prototypes/<id>/`,
  including feedback capture, promotion handoff into normal Stagecraft tracks,
  documentation across the operator guides, and openai-compat coverage for
  allowed prototype packet writes. *Honest scope note:* prototype packets are
  committable learning records, not gates, sign-off evidence, or deploy
  evidence.

- Add `devteam prototype`, a pre-SDLC workflow for fast prototype packets, feedback capture, and explicit promotion into normal Stagecraft tracks.

### Added

- **Mechanical red-team floor for stage-04c — Phase 31.2.** Red-team's adversarial pass stayed 100% model self-report: a gate claiming `findings_count: 0` was believed, in the one stage whose job is distrust. `core/verify/redteam-floor.js` adds four orchestrator-run checks post-dispatch: (a) `npm audit --json` (or `pipeline.verify.dependency_audit_command` override; explicit `null` disables) — a network-unavailable audit records `skipped: "offline"`, never a pass; (b) the existing `core/hooks/secret-scan.js` reused as a library over the changed-file set (`pipeline/changed-files.txt`, falling back to `git diff --name-only HEAD`); (c) semgrep, only when the project already has a semgrep config file **and** the binary is already on PATH — devteam never installs either; (d) a lockfile delta (new/removed top-level `package-lock.json` entries) against the previous stage-04c attempt, read from `core/gates/archive.js`'s per-attempt archives, so a first attempt records a baseline snapshot rather than a false empty diff. `core/verify/stamp.js#stampStage04c` merges these into the gate: `findings_count := max(model_reported, mechanical)`, `severity_breakdown` is raised per-band the same way, and any mechanical `high`/`critical` finding is appended to `must_address_before_peer_review` with `source: "mechanical"` — which pushes a blocker onto the gate, so `finalizeStamp`'s existing PASS/WARN→FAIL override fires exactly like every other stamped stage. Rather than re-implementing the `pipeline/context.md` blockers-injection, `core/gates/validator.js#injectRedTeamBlockers` is now exported and called directly from `stampStage04c` so a mechanically-forced FAIL surfaces to the next build re-run the same way a model-authored FAIL always has. `stage-04c` joins `STAMPABLE_STAGES` (`devteam verify stage-04c` now works) using the existing single-workstream dispatch path in `core/orchestrator.js` — no orchestrator wiring changes were needed there.

  Tests: `tests/verify-stamp-04c.test.js` — a seeded critical dependency vulnerability flips a model-PASS gate to FAIL; an offline dependency audit records `skipped: "offline"` and does not affect gate status; explicit-disable and non-Node-project skips are recorded with distinct reasons; missing semgrep config skips honestly; model `findings_count: 0` + 2 mechanical (medium-severity) secret-scan findings merges to `2` without forcing FAIL (severity floor, not count floor, drives the forced-blocker path); a model-reported count already above the mechanical count is never lowered; missing/first-attempt lockfile-diff cases; every tool's stamp record carries `{ran, skipped, reason, findings}`.

  Honest scope note: **[verify-first] finding** — the plan item's claim that a "polyglot equivalent" of `npm audit` already exists via the Phase 19/PR #264 suite-detection does not hold; that work (`core/verify/runner.js`) discovers *test* commands (Node/pytest/go test) only, with no dependency-audit/SCA analog for non-Node ecosystems (no pip-audit/govulncheck wiring). The dependency-audit check therefore only runs for Node projects (`package.json` present) or via the `dependency_audit_command` override; other project types record an explicit skip rather than guessing at unvetted tooling. The lockfile-delta check only understands `package-lock.json` (npm lockfileVersion 1–3), matching the same Node-first scope. Semgrep is scoped to the changed-file set (not a full-repo scan) to keep the mechanical floor time-boxed. The lockfile-delta's "previous attempt" lookup reuses `core/gates/archive.js`, which only archives a stage-04c attempt when it was `FAIL` — a `PASS` attempt is never archived, so a diff run after an unbroken PASS streak has no prior snapshot to compare against and records a fresh baseline rather than a true delta. A dedicated snapshot store (independent of FAIL-only archiving) would close this gap but is out of scope for this item.

### Added

- **Opt-in Reflector pass — phase-30 item 30.3 (`docs/pattern-learning.md`).** `learning.reflector: true` in `.devteam/config.yml` (default `false`) makes the driver dispatch one extra headless call after a *clean* `pipeline-complete` — never on a halt — routed like any role (`routing.roles.reflector`, falling back to `routing.default_host`) so it can go to a cheaper model than the build agents. `core/learning/reflector.js` builds the dispatch prompt from the new `roles/reflector.md` brief plus embedded JSON (this run's gate summaries, `run-log.jsonl` events with heartbeats stripped, and the current promoted-pattern set — the model gets no live tool access to re-read them) and spawns the resolved host's headless command directly (same one-off-dispatch shape as `core/a11y-fixer.js`, not a stage dispatch — there is no gate footer telling the model to write a gate, because this isn't one). Output must be a single JSON object matching the new `candidates-delta` schema (`core/gates/schemas/learning/candidates-delta.schema.json`, deliberately filed under a `learning/` subdirectory so it isn't picked up by the stage↔schema 1:1 sweeps in `contract.test.js`/`scripts/consistency.js`), hand-validated by `core/learning/validate-candidates-delta.js` (no ajv dependency, matching this repo's existing `core/gates/validator.js` convention). Valid `new_candidates` — including the new `tier: "positive"`, which gate-derived collection structurally cannot produce — land in the same observations store via the new `patterns.ingestReflectorCandidates()`, tagged `source: "reflector"` and fingerprint-deduped exactly like gate-derived observations, so a reflector proposal can reinforce an existing candidate's `pattern_key` instead of always minting a new one. `counter_adjustments`/`dedup_merges` are advisory-only — logged in full as a `reflector-proposal` run-log event for an operator to act on through the existing `devteam patterns demote`/`promote` flow, never auto-applied. Malformed output (invalid JSON, or JSON failing schema validation) is discarded *in full* — one `reflector-output-malformed` event, nothing partially ingested. Any dispatch failure (no adapter, no `headlessCommand`, non-zero exit, timeout) is the same fire-and-forget contract as pattern auto-collection: one `reflector-dispatch-failed` event, never fails the run. Role brief registered in `core/roles.js` (`ROLE_TOOLS.reflector`, read-only: `Read, Glob, Grep`) and `hosts/claude-code/adapter.js` (`ROLE_FRONTMATTER.reflector`, `model: haiku`). Docs: `docs/pattern-learning.md` (new "Reflector (ACE-lite)" section, citing Zhang et al. arXiv:2510.04618, plus an Open Decisions/history update). Tests: `tests/reflector.test.js` — `validateCandidatesDelta` unit coverage; an end-to-end scripted-headless-output run lands a `source: "reflector"` candidate and logs the proposal event; invalid-JSON and schema-invalid outputs are each discarded whole with exactly one malformed-output event and zero observations written; disabled-by-default runs never invoke the reflector and emit no `reflector-*` events; a throwing `runReflector` is caught and logged without failing the run (fire-and-forget contract); `roles/reflector.md` stays under a single-page byte budget. Honest scope note: `counter_adjustments` and `dedup_merges` are recorded for audit but have no dedicated review-surface UI yet (no CLI command reads them back out) — they're visible today only via `run-log.jsonl`; auto-promotion remains explicitly out of scope, per the design doc's "the Curator is the existing human promote flow."

### Fixed

- **Non-`acp` hosts' post-hoc write-audit was blind to the subject in review mode — phase-36 item 36.6 follow-up (`plans/phase-36-external-review-mode.md`).** In review mode (`ctx.externalReviewMode`), the existing post-hoc write-audit for `codex`/`antigravity`/`omnigent`/`openai-compat` snapshotted `ctx.cwd` (the review workspace) before and after a dispatch, never `ctx.processCwd` (the subject under review) — so it structurally could not see a write into the subject, and typically no-op'd entirely since the workspace isn't a git repository. `core/adapters/headless.js` and `hosts/omnigent/adapter.js` now run a second, independent snapshot/audit pass against `ctx.processCwd` when review mode is active and the subject differs from the workspace, treating any new path there as a violation unconditionally (`subject:<path>`, mirroring `hosts/acp/permissions.js`'s own rule that `codeRoot` is unconditionally read-only) — flipping the gate to `FAIL` with a named blocker. This is detection, not prevention: it cannot stop the write, only report it after the fact, and it inherits the write-audit's existing blind spots (no-ops on a non-git subject; can't see a re-edit of a file already dirty before the review started). Guarded to never double-audit when `ctx.processCwd === ctx.cwd`, and to stay a no-op for prototype mode (`ctx.processCwd` set without `ctx.externalReviewMode`).

  Five new tests (`tests/write-audit.test.js`, `tests/omnigent-adapter.test.js`) cover: detection when the workspace isn't a git repo but the subject is; no detection without `externalReviewMode` (prototype-mode parity); and no double-audit when `codeRoot === stateRoot`. Confirmed to fail without the fix.

  `docs/external-review.md`'s per-host enforcement table, `README.md`'s `--host acp` note, and this plan's 36.6 entry are updated to describe the new three-tier picture precisely: `acp` prevents, `codex`/`antigravity`/`omnigent`/`openai-compat` now detect, `claude-code` still gets neither (a known, separately-tracked gap — `--state-dir` for claude-code, phase-36's own Out-of-scope list).

  Honest scope note: `claude-code`'s hook-discovery gap in review mode is unchanged by this fix — it is out of scope for this phase by the plan's own design, not an oversight here.

### Added

- **`review-only` track + artifact-tolerant readFirst — phase-35 item 35.1 (`plans/phase-35-existing-codebase-mode.md`).** Reviews code that already exists — a brownfield repo, an inherited module — instead of assuming the intent→code direction every other track takes. `devteam run --track review-only [--scope <path>]` dispatches `security-review` → `red-team` → `peer-review` only: no requirements, design, build, sign-off, or deploy. `--scope <path>` (repeatable) narrows the review to a subtree; it renders as a "Scope: ..." prompt line and lands on the gate (`scope: [...]`) for audit, both only when passed (every other track's prompts/gates are unaffected).

  **Soft readFirst.** `core/pipeline/stages.js`'s pipeline-artifact `readFirst` entries for `security-review`, `red-team`, `peer-review` (including the 31.3 adversarial override), and `verification-beyond-tests` are now `{path, optional: true}` — the same form 31.3/G3 already established for `by-reviewer.md`/`production-feedback.md`, extended rather than duplicated into a parallel array. `core/orchestrator.js#buildDescriptor` now backs `optional: true` with a real filesystem check (`existsForReadFirst`, glob-aware for `pipeline/pr-*.md`) instead of the pre-35 behavior of always rendering the entry annotated `"(if present)"`: an absent optional path is omitted from the `## Read first` section entirely, a present one renders plainly (indistinguishable from a required entry). No `cwd` in scope (a preview/eval-replay path with nothing to check against) fails open — assume present, matching every pre-35 caller. This closes the "review stages instructed to read files that don't exist, degrading instead of failing" gap the phase exists to close.

  `security-review`'s `conditionalOn: {stage: "stage-04a", ...}` already treats a missing prerequisite gate as "run it anyway" (existing `core/orchestrator.js` behavior, not new here) — since `review-only` never dispatches `stage-04a`, security-review runs unconditionally on this track, same as red-team and peer-review.

  Tests: `tests/review-only-track.test.js` — optional-entry omission/inclusion (plain path, glob, no-cwd fallback); full-track byte-identical regression for all four touched stages (rendered prompt identical to a hand-authored plain-string-readFirst copy when every artifact is present); `devteam run --track review-only` walks to `pipeline-complete` on a fixture with **no `pipeline/` directory at all**; no dispatched `## Read first` section mentions a nonexistent artifact; `verify-chain` passes on the 3-stage track; `--scope` reaching the prompt and the gate, and its absence changing nothing on every pre-35 track. `tests/compact-qa-fold.test.js`'s `verification-beyond-tests` snapshot and `tests/tracks.test.js`'s "build is in every track" assertion updated for the new readFirst shape and the one track that legitimately never builds anything.

  Honest scope note: item 2's plan text called for gate-schema conditionals making "AC-referencing fields null-permitted when track: review-only" (the 29.4 stage-06x precedent). **Verify-first check found this premise false**: none of `security-review`/`red-team`/`peer-review`'s gate schemas (`core/gates/schemas/stage-04b|04c|05.schema.json`) have any required field that references acceptance criteria — the AC↔Scenario↔test contract lives entirely in stage-01/03b, neither of which this track includes. No schema conditional was added; there is nothing to relax. `core/gates/schemas/gate.schema.json`'s `track` enum gained `"review-only"` (it was already missing `"loop"` — pre-existing drift, not fixed here, out of scope). Peer-review sizing on `review-only` falls through to `PEER_REVIEW_SIZING.full` (the 4-area matrix, 2 approvals) rather than a scoped single-reviewer variant — unlike `nano`/`loop` there's no single-workstream build to size the review to, and an arbitrary existing subtree can span every area.

### Added

- **`devteam review-pr <number|url>` works with no checkout and no initialised project — phase-36 item 36.5 (`plans/phase-36-external-review-mode.md`).** Running from an already-initialised project (`.devteam/config.yml` present in `--cwd`) is byte-identical to before. Otherwise, `review-pr` now materializes the PR into a 36.3 review workspace (`core/review-workspace.js`) instead of the invoking directory: `gh pr view`/`gh pr diff` are fetched once, then written into `<workspace>/pipeline/review-input/` and dispatched exactly as the in-place path does, with `pipeline/gates/stage-05*.json` and `pipeline/code-review/by-*.md` landing under the workspace. The workspace is derived from the PR's own URL (`core/review-workspace.js#slugForIdentity`/`resolveWorkspacePathForIdentity`, new — `slugForSubject`'s `path.resolve()` would otherwise resolve a non-path identity against the invoking cwd, making the slug vary by invocation directory instead of by PR), so repeat reviews of the same PR reuse the same workspace regardless of where the command is run from. `--workspace <path>` overrides the derived path, mirroring `devteam review`.

  **No clone, ever, in this path.** The diff *is* the subject — `core/review-workspace.js#createReviewWorkspace()`/`writeSubjectManifest()` now accept `subjectPath: null` (required as an explicit key, not merely omitted, so a caller can't silently forget it) plus directly-supplied `remote`/`commitSha`/`pr` fields instead of shelling `git` against a path that doesn't exist; `subject.json` records `subject_path: null` and a `pr: {number, url, title}` block in that case. Dispatch sets `ctx.externalReviewMode: true` and a new `ctx.noCodeRoot: true` (threaded through `core/orchestrator.js#runStage()` exactly like 36.3's `processCwd`/`externalReviewMode` — unset on every other caller, so byte-identical there).

  **Fixed a real gap this surfaced in `hosts/acp/adapter.js`.** `hosts/acp/permissions.js#findWriteViolation` already special-cased a falsy `codeRoot` for this exact scenario (comment naming 36.5 was already in the file from an earlier item), but `adapter.js`'s own `codeRoot: processCwd` — where `processCwd = ctx.processCwd || ctx.cwd` — never actually produced a falsy `codeRoot`: with `ctx.processCwd` unset, `codeRoot` silently became `ctx.cwd` itself (i.e. `codeRoot === stateRoot`), which `findWriteViolation` reads as "every write target is inside the subject" and denies outright. `ctx.noCodeRoot` is the fix: `codeRoot` is `null` only when explicitly opted into, leaving the existing fail-closed default (deny when `processCwd` is merely omitted, protecting against a review-mode dispatch that forgot to set up a real code/state split) completely intact for every other caller.

  **Publishing safety is untouched.** `--post` stays opt-in, the confirmation still throws (not a silent no-op) and actually stops the command, non-interactive still requires `--yes`, and a partial/incomplete dispatch still refuses to post even with `--yes` — re-verified with a parallel copy of every 35.2 publishing-safety test run against the new no-project-directory path, plus the original in-place suite re-run unmodified.

  Tests: `tests/host-acp.test.js` — an end-to-end `adapter.invoke()` case proving a write under `ctx.cwd` matching `allowedWrites` is allowed with `ctx.noCodeRoot: true` and no `ctx.processCwd` (fails without the `adapter.js` fix), plus a sibling case proving the same paths are still denied when `ctx.noCodeRoot` is merely omitted (guards against re-loosening the pre-existing fail-closed test). `tests/review-workspace.test.js` — `slugForIdentity`/`resolveWorkspacePathForIdentity` stability and cwd-independence, `createReviewWorkspace`/`writeSubjectManifest` with `subjectPath: null`, the required-key throw, and `runStage()` threading `ctx.noCodeRoot`. `tests/review-pr.test.js` — a scripted `gh` stub drives `devteam review-pr <url> --json` from a plain tmpdir with no `.devteam/` and `STAGECRAFT_REVIEWS_DIR` pinned to a fresh tmpdir: asserts the workspace path reported in `--json`, that nothing lands under the invoking cwd, that `subject.json` records the PR's identity, that a repeat run reuses the same workspace, and re-runs the non-interactive-refusal / `--post --yes` / partial-review-never-posts cases from 35.2 against this path. The full original `tests/review-pr.test.js` suite (in-place mode) passes unmodified.

  Honest scope note: no `--host`/adversarial-mode support in workspace mode — the workspace's generated `.devteam/config.yml` pins `routing.default_host: claude-code` and sets no `review.mode`, so a bare-PR review from an uninitialised directory always runs single-reviewer panel mode; adversarial mode and a different host still require an initialised project (`--cwd` pointed at one) until a future item exposes equivalent flags, mirroring `devteam review`'s `--host`. A bare PR *number* (as opposed to a full URL) still requires being run inside an actual checkout of the repo — `gh` infers the target repo from the invoking directory's git remote, which a URL doesn't need; this is a pre-existing `gh` behavior, not something this item's code decides, and isn't newly broken by it. Also found, and left as documentation only: `core/cli/commands/review-pr.js`'s pre-36.5 precondition check (`.devteam/config.yml` absent) never actually refused — it printed a cosmetic stderr warning and then dispatched into the invoking `cwd` regardless (no downstream guard existed either, confirmed by reading `core/config.js#loadConfig`'s silent-defaults fallback and `core/orchestrator.js#runStageHeadless`). The in-place code path is left exactly as it was; the new workspace routing described above is this item's actual fix for that gap, not a hardening of the old warning.

### Added

- **`devteam review-pr <number|url>` — phase-35 item 35.2 (`plans/phase-35-existing-codebase-mode.md`).** Review an inbound GitHub PR with the existing reviewer/critic machinery instead of hand-assembling a brief. Materializes the PR via `gh pr view`/`gh pr diff` into `pipeline/review-input/` (`pr.md` — title/body as the stated intent; `diff.patch` — the unified diff; `changed-files.md` — the changed-file list), then dispatches `peer-review` (stage-05) against it on a new `review-pr` track: a single "reviewer" workstream in panel mode (`PEER_REVIEW_SIZING["review-pr"]`, sized like `nano` rather than `review-only`'s four-area matrix — a PR is already one bounded, diffed unit of change), reviewer-then-critic when `review.mode: adversarial` (31.3) — that override is config-driven exactly as it is everywhere else, no new flag needed. Output is a normal stage-05 gate (`pipeline/gates/stage-05.json`, or the merged adversarial gate) plus `pipeline/code-review/by-*.md`, dispatched through the unmodified `runStage`/`runStageHeadless`/`mergeWorkstreamGates` path — 35.1's soft-readFirst already made `peer-review` tolerant of a repo with no `pipeline/brief.md`/`design-spec.md`, and three new optional `readFirst` entries (`pipeline/review-input/{pr.md,diff.patch,changed-files.md}`) were added to both the panel and adversarial-override shapes so the materialized PR is only ever mentioned in the prompt when it actually exists.

  `gh` auth/error handling is reused verbatim from `scripts/pr-publish.js` (the only existing place that shells to `gh`) — `gh`/`ensureGh` are now exported from there rather than duplicating a second pattern.

  **Publishing is opt-in and gated.** Default is local-only: findings land on disk, nothing is sent anywhere. `--post` publishes the combined `by-reviewer.md`(`+by-critic.md`) content as a `gh pr review --comment` PR review comment: it prints the exact payload (to stderr, so `--post --json` still emits one clean JSON object on stdout), then requires interactive confirmation — auto-confirmed with `--yes`, required in a non-interactive context (no TTY) since there's no one to prompt. Refuses outright, before ever building a payload, when the dispatch was partial (a workstream timed out, exited non-zero, wrote no gate, or the adversarial merge failed) — a FAIL/ESCALATE gate that *completed* is still postable (that's the point — post the findings), only an *incomplete* dispatch is refused.

  Tests (`tests/review-pr.test.js`): a scripted `gh` stub + a `DEVTEAM_HEADLESS_COMMAND` writer script (mirrors `tests/replay.test.js`'s pattern) drive a full `devteam review-pr` CLI invocation end to end — materialization content, panel-mode single-workstream gate, a bare-number vs. full-URL positional argument, adversarial mode's reviewer+critic merge, `--post` refusing (and posting nothing) in a non-interactive context without `--yes`, `--post --yes` actually calling `gh pr review` with the expected body, missing `gh` giving an actionable error instead of a stack trace, and a partial dispatch (`DEVTEAM_HEADLESS_COMMAND=true`, no gate written) refusing `--post` even with `--yes`.

  Docs: `docs/tracks.md` gained a `## The review-pr track` section and its generated stage matrix regenerated (`scripts/generate-tracks-matrix.js` now marks review-pr's peer-review `✓ˢ`, same annotation as nano's single-reviewer scoping); `docs/concepts.md`, `docs/FEATURES.md`, `rules/pipeline-tracks.md`, `rules/gates-core.md` updated from eight to nine tracks; `docs/reference/cli.md` regenerated (`npm run docs:generate`) to include the new command.

  Honest scope note: `core/gates/schemas/gate.schema.json`'s `track` enum gained `"review-pr"` — it was already missing `"loop"` (pre-existing drift flagged, not fixed, by the 35.1 changelog; still not fixed here). `rules/pipeline-tracks.md`'s per-track approvals table predates `review-only` and still doesn't list either `review-only` or `review-pr` — flagged inline with a pointer to `docs/tracks.md` rather than expanded, to avoid widening this item's diff into an unrelated table rewrite. `review-pr`'s single "reviewer" workstream reuses the exact role name the 31.3 adversarial override already treats specially (`by-reviewer.md` → `applyAdversarialReviewerFile`) purely as a filename-matching side effect of `core/adapters/headless.js`'s post-dispatch approval-derivation fallback — harmless (the model's own direct gate write to `pipeline/gates/stage-05.json`, per every stage's "## Gate to write" contract, is what the orchestrator actually reads) but it does mean a redundant `stage-05.reviewer.json` gets written alongside the real gate on panel-mode runs, exactly as nano's `backend`-named single workstream already leaves behind an unused `stage-05.backend.json` today. Not fixed here — pre-existing characteristic of the single-workstream shape, not something 35.2 introduces.

### Added

- **Review workspace + dispatch plumbing — phase-36 item 36.3 (`plans/phase-36-external-review-mode.md`).** `core/review-workspace.js` creates `~/.stagecraft/reviews/<slug>/` (`--workspace <path>` overrides), where `<slug>` is the subject's basename slugified plus a short stable hash of its absolute path (collision-safe across two checkouts sharing a basename; stable across repeat reviews of the same path). The workspace mirrors the parts of `devteam init` a review needs — `pipeline/gates/`, a minimal `.devteam/config.yml` pinning `routing.default_host`/`pipeline.default_track`, and the given host adapter's own `install()` for role prompts/rules/templates/skills (ACP's `.acp/stagecraft/{roles,skills}` per `hosts/acp/capabilities.json`) — reusing the existing adapter contract rather than hand-rolling a second install path. `.devteam/patterns`, `corpus`, and `evals` are deliberately not pre-created: every consumer already `mkdirSync(..., {recursive:true})`s on first write, same as a freshly-`init`'d project.

  `createReviewWorkspace()` also writes `subject.json`, recording the subject's absolute path, its `git remote get-url origin` (null if none/not a git repo), and the commit SHA at workspace-creation time — so a future attestation pass can name **what was reviewed**, not what was produced (34.2's `resolveSubjectCommits()` reads `ctx.cwd`'s own git history, which is empty for a review workspace; wiring that read is left to a later item, not this one — see honest scope note).

  **Orchestrator plumbing.** `core/orchestrator.js#runStage()` now threads `opts.processCwd`/`opts.externalReviewMode` onto `ctx`, the same passthrough `opts.scope` already gets (phase-35 item 35.1); `core/driver.js#run()`'s single `_runStageHeadless()` call site threads them the same way. Both default to `null`/`false` when absent, so every existing caller is byte-identical. This is the wiring `hosts/acp/adapter.js` and `core/adapters/render-helpers.js#resolveFrameworkPath` (36.1/36.2) were already waiting on — `ctx.externalReviewMode` was previously set by no orchestrator path at all.

  New env var `STAGECRAFT_REVIEWS_DIR` (default `~/.stagecraft/reviews/`), same precedent as `STAGECRAFT_ORG_MEMORY_DIR` (`core/memory/index.js`) — see `docs/reference/environment-variables.md`.

  **The test that matters** (`tests/review-workspace.test.js`): a real dispatch through `hosts/acp`'s adapter (driven by the existing `tests/fixtures/acp-stub-agent.js` scripted agent — no network, no real model) against a `createReviewWorkspace()`-built workspace and a genuinely separate fixture subject repo, with `ctx.processCwd` = subject and `ctx.cwd` = workspace. The subject tree (file list + content hash, `.gitignore`/`AGENTS.md` included) is snapshotted before and after and asserted completely unchanged — both immediately after the real dispatch and again after the rest of the `review-only` track completes. Also covers: gates/logs landing under the workspace (not the subject); `subject.json`'s path/remote/SHA fields, including the no-git-repo fallback; `runStage()`/`driver.run()` opts passthrough (present and byte-identical-when-absent); and `devteam verify-chain --cwd <workspace>` passing against the resulting chain.

  Honest scope note: this item wires the workspace and the ctx split; it does not yet flip `ctx.externalReviewMode` on for any real CLI command (that's item 36.4's `devteam review <path>`) or wire `subject.json` into `core/evidence/attestation.js`'s subject resolution (flagged above, left for a later item since 36.3's own acceptance criteria doesn't require it). `driver.js` currently has exactly one `_runStageHeadless()` call site, so the passthrough only needed one edit; if a future item adds a second dispatch path, thread the same two fields there.

### Added

- Added per-workstream start/finish progress for `devteam run`, including host, outcome, elapsed time, and gate/log pointers.
- Added `active_workstreams` and `last_workstream` to run state and `devteam status --verbose`.
- Expanded `devteam run --watch` with active workstreams, the last settled workstream, and transcript/gate pointers.

### Added

- Added deterministic run right-sizing: active workstream candidates for Stage 01 confirmation, auditable applicability skips, expected workstream counts, and `pipeline.right_sizing: false` opt-out. (The high-confidence-only auto-track selection this originally shipped with is superseded before release by `assess-by-default.md` below — it now runs at any confidence and is audited via `pipeline/track.json`.)

### Added

- Emit a `devteam run` plan preview, and durable `run-plan` event, with effective track, stage counts, configured skips, conditional stages, and base workstream count before dispatch.

### Added

- Added per-host workstream concurrency limits, queue-wait telemetry, critical-path queue reporting, and retry reason/backoff fields for transient no-gate dispatch retries.

### Added

- **docs(analysis):** ACP read-scope evidence review (`plans/acp-read-scope.md`), item 36.0. Ran the real `@agentclientprotocol/claude-agent-acp` agent (0.64.2, real model, real cost) against a session cwd with an unrelated absolute-path target outside it, plain and symlinked, plus a denial control. Finding: the agent's own filesystem access is not sandboxed to the ACP session cwd — reads succeed unsandboxed either way, gated by one `session/request_permission` round-trip that `hosts/acp/permissions.js`'s `WRITE_KINDS` (`edit`/`delete`/`move` only) already auto-allows for `read`/`execute`-kind calls today. Recommendation for 36.2: render framework paths as absolute paths into `stateRoot`, no permission-layer change required.

  Honest scope note: report-only spike, no production code changed. Tool choice (Read vs. shell `cat`) was observed to be non-deterministic across turns for the same prompt — both succeeded identically once permission was granted, so this doesn't change the recommendation, but it means a single run isn't a guarantee of which tool a given dispatch will use.

### Added

- **Orchestrator-verified evidence for stage-06d (verification-beyond-tests) — Phase 35.3.** `STAMPABLE_STAGES` was `{stage-03b, stage-04a, stage-04c, stage-06}` — stage-06d, the stage whose entire value is verification depth, was 100% model self-report: a gate claiming `methods_attempted: ["property"]` was believed with no orchestrator check. `core/verify/stamp.js#stampStage06d` closes that gap: for every method the model claims with a bare tag (`"property"`, `"mutation"`, `"formal"` — not an already-honest `attempted_but_blocked:*`), the orchestrator tries to produce real executable evidence before the claim is accepted.
  - **Property-based** (`core/verify/property.js`): detects fast-check (JS/TS, package.json dependency), hypothesis (Python, requirements.txt/pyproject.toml), or proptest (Rust, Cargo.toml) — never installs any of them. Runs the property tests found under `pipeline.verify.property.paths` (default `src/tests/property/`) and parses the runner's own summary for an executed-property count and pass/fail. fast-check runs via Node's built-in test runner (`node --test --test-reporter=tap`); a genuine counterexample (`Property failed after N tests`) FAILs the gate on orchestrator evidence, and a claim backed by zero executed properties downgrades to `attempted_but_blocked:property`.
  - **Mutation**: reuses the phase-31.4 runner (`core/verify/mutation.js#runMutationGate`) directly — no second implementation. Honors the model's own pre-declared `threshold` (the schema calls this "audit-grade: prevents goal-post moving"); a re-run score below it FAILs the gate, unlike stage-06's smoke gate where below-threshold is advisory by default.
  - **Formal** (`core/verify/formal.js`): presence-and-exit-code only. TLA+/Alloy/Lean/Coq output is too varied to parse reliably, so the orchestrator stamps `{tool, ran, exit_code}` and nothing more — a non-zero exit raises a warning for human triage, never an automatic FAIL. No manifest auto-detection (no single signal the way fast-check has one); the project declares its check via `pipeline.verify.formal.command`.

  `stage-06d` joins `STAMPABLE_STAGES` (`devteam verify stage-06d` now works) using the existing single-workstream dispatch path in `core/orchestrator.js` — no orchestrator wiring changes were needed there. A method the model never claimed (a legitimate `methods_skipped` entry, or an already-honest `attempted_but_blocked:*`) is left untouched; the orchestrator verifies claims, it doesn't invent new ones. `.devteam/config.yml` gains commented `pipeline.verify.property` / `pipeline.verify.formal` documentation alongside the existing `mutation` block.

  Tests: `tests/verify-stamp-06d.test.js` — a fixture with a real fast-check-shaped counterexample FAILs on orchestrator evidence while the method claim stays confirmed (it did run); a model claiming `property` with zero executed properties downgrades to `attempted_but_blocked:property` with the model's original claim preserved under `_orchestrator_stamped.runs.property.model_claim`; absent toolchain (no fast-check/hypothesis/proptest signal) records the same downgrade; mutation claims below/above the model's declared threshold FAIL/PASS respectively using a `command`-override fixture (mirroring `tests/verify-stamp-mutation.test.js`); formal claims downgrade when unconfigured, stamp `{tool, ran, exit_code}` on exit 0 without touching the model's other formal fields, and warn-without-failing on a non-zero exit; a legitimately skipped method and an already-honest `attempted_but_blocked:*` claim are left untouched; unit tests for `detectRunner`/`parseOutput`/`buildCommand`/`walkFiles` (property.js) and `resolveFormalConfig` (formal.js) against canned tool output. No pre-existing `tests/verification-beyond-tests.test.js` test required changes — that suite covers the model-facing schema/skill/template/prompt surface, which this change doesn't touch.

  Honest scope note: only the fast-check/Node-built-in-test-runner path is integration-tested end-to-end (via a `command`-override fixture, following `tests/verify-stamp-mutation.test.js`'s existing pattern — this repo carries no real fast-check dependency, matching the "never install" doctrine). hypothesis (pytest-style summary) and proptest (`cargo test`-style summary) detection and output-parsing are unit-tested against canned strings only, since this repo has no Python or Rust toolchain to run them against for real. Formal-method exit codes are intentionally never interpreted as pass/fail by the orchestrator — a non-zero exit could mean a genuine counterexample or a tool/config error, and the plan explicitly asks for presence-and-exit-code evidence only; this is a deliberate, narrower guarantee than mutation's, not an oversight.

### Added

- **`refactor` track — behavior-preservation for structural changes (phase-35 item 35.5, `plans/phase-35-existing-codebase-mode.md`).** `devteam run --track refactor` dispatches the same 3-stage shape as `nano` (`build` → `peer-review` → `qa`, single-reviewer sizing) but with a different bar: no new acceptance criteria, the existing test suite must pass **unchanged**, and a surviving mutant is treated as evidence the refactor didn't preserve behavior.
  - **Build (stage-04)** gets a `trackOverrides.refactor` on `core/pipeline/stages.js`: the objective and template (`templates/characterization-template.md`) swap to a CHARACTERIZATION brief — document current behavior (inputs/outputs, edge cases, error handling, existing test coverage) *before* touching structure. Gate shape is unchanged from `nano`.
  - **QA (stage-06)** gets a matching `trackOverrides.refactor`: `all_acceptance_criteria_met` and `criterion_to_test_mapping_is_one_to_one` are seeded `null` (no brief.md exists on this track, same as `nano` — `core/verify/stamp.js#checkAcceptanceCriteria` already treats a missing brief as not-applicable and leaves the field untouched, so `null` is the honest initial value rather than `false`). `core/gates/schemas/stage-06.schema.json` widens both fields' type to `["boolean", "null"]`.
  - **The 31.4 mutation smoke gate defaults to *enabled*** on the `refactor` track only (`core/verify/mutation.js#defaultMutationEnabledFor`) — every other track keeps its pre-35.5 opt-in-off default. An explicit `pipeline.verify.mutation.enabled` in config always wins over the track default, in either direction. `core/verify/stamp.js#stampStage06` now threads `gate.track` into `runMutationGate`.
  - `PEER_REVIEW_SIZING.refactor` mirrors `nano`'s (single reviewer, 1 approval) — without this entry the track would silently fall back to the full 4-area matrix. `core/gates/schemas/gate.schema.json`'s `track` enum gained `"refactor"`.

  Tests: `tests/refactor-track.test.js` — track/stage-list/sizing contract identical to `nano` except the two documented differences; `build`/`qa` descriptors diverge from `nano` only on the objective/template/gate fields called out above; `resolveMutationConfig` defaults on for `refactor` and off for every other track (explicit config always wins); `stampStage06` integration proving the mutation gate actually runs by default on `refactor` and stays skipped on `nano` with the same unconfigured verify block; a behavior-changing edit (existing test suite failing) FAILs stage-06 on `refactor` via the ordinary test-command blocker — no new mechanism needed, it's the same check every other track already has; `--track refactor` walks `build → peer-review → qa` to `pipeline-complete` on a fixture with a complete, correctly-null audit trail.

  Honest scope note: the plan's "AC-mapping gate fields null-permitted as in 35.1" language describes a JSON-Schema `if/then` conditional keyed on `track`; this codebase's schemas are not ajv-validated at runtime (`tests/schemas.test.js`'s own header notes this — "avoids adding ajv as a dep"), so the schema change here is a type-widening (`["boolean", "null"]`), not an enforced per-track conditional — the actual per-track behavior lives in the `trackOverrides.refactor` gate skeleton and in `checkAcceptanceCriteria`'s pre-existing not-applicable handling. "The existing suite must pass unchanged" is enforced exactly as far as every other track already enforces "tests must pass" (the stage-06 test-command blocker) — this item does not add a mechanical check that test *files themselves* were left untouched during the refactor; that would be a further-reaching, unrequested mechanism.

### Added

- Reuse successful orchestrator-run verification commands through content-addressed receipts keyed by command, suite, purpose, workspace bytes, verify config, material env/toolchain data, and Stagecraft verifier version; failed or uncertain receipts rerun pessimistically.

### Added

- Run orchestrator-discovered verification suites with bounded concurrency, deterministic result ordering, optional resource-group exclusivity, and capped stdout/stderr capture.

---

## [0.9.0] — 2026-06-28

### Added

- Authenticate stage-gate chains with optional HMAC-SHA256 signatures from `DEVTEAM_SIGNING_SECRET`, with `--require-signed` and `pipeline.require_signed_gates` anti-downgrade enforcement.

### Added

- **`devteam report` — post-run HTML pipeline report.** New command that collects all pipeline data and renders a self-contained `pipeline/report.html`, opened automatically in the default browser. The report is a three-tab SPA (no external dependencies, works offline): **Summary** (status badge, progress bar, header stats, brief problem statement, clickable AC and scenario count chips), **Pipeline** (per-stage timing, dispatch counts, stage document links, workstream breakdown, blocker log), and **Documents** (all pipeline artifacts embedded inline — brief, spec, design-spec, build-plan, code reviews, ADRs, test report, accessibility/observability reports — with a sidebar navigator). Status classification reads terminal events correctly: `COMPLETED` (complete event), `HALTED` with halt-type subtitle (ceiling-halt, convergence-halt), or `INCOMPLETE` (no terminal event, waiting for manual advance). Heartbeats written after a halt no longer mask the real state. Header shows wall-clock time, total model compute time (sum of all `dispatch-observation` durations from `run-log.jsonl`), retry and stall counts, and cost. Per-stage rows show compute time and a "(N dispatches)" annotation for retried stages. Clicking a stage pill in the progress bar jumps to that row in the Pipeline tab. Stage document links (small blue pills per row) and clickable stat chips navigate directly to the relevant embedded document. `--json` emits raw `ReportData` for scripting. Documented in `help.js`, `docs/reference/cli.md`, `README.md`, and `docs/user-guide.md`.

- **OpenAI-compatible host adapter.** Adds a first-class `openai-compat` host for OpenAI-compatible Chat Completions providers, including HTTP-native tool calls, per-role model configuration, installed host prompts and skills, write-audit integration, and direct command execution for stages that require command-line verification. The command executor now parses model-provided commands into argv, rejects shell syntax and non-allowlisted executables, and keeps CI prompt-echo smoke tests explicit with `DEVTEAM_HEADLESS_TEE=1`. *Honest scope note:* command execution is not an OS sandbox; allowlisted commands still run with the invoking process's project permissions.

- **Three `active_roles` filtering bugs fixed — infinite dispatch loops on non-build and multi-role stages.** When a stage-01 gate carries `active_roles: ["backend", "platform", "qa"]` (no frontend), three interacting defects caused dispatch loops:
  1. **`inferActiveRoles` zeroed out non-build stages** (`computeDispatchPlan`): for stages like design (`roles: ["principal"]`) the intersection with build-workstream `active_roles` was empty — an empty array is truthy, so `roles` was set to `[]`, the stage dispatched zero workstreams, wrote no gate, and looped until `max-iterations`. Fix: return `null` (no filter) when the intersection is empty.
  2. **`_nextImpl` used `stageDef.roles` (unfiltered) for multi-role completion check**: after all active workstream gates were written, `stage-04.frontend.json` was absent (frontend was suppressed), so `remaining=[frontend]` was always non-empty and `next()` always returned `continue-stage` — all three active workstreams were skipped every iteration. Fix: compute `effectiveRoles` via `inferActiveRoles` before the gate-existence loop.
  3. **`summary()` showed suppressed workstreams as pending**: same root cause as (2) in the display path — `devteam plan` showed `frontend: pending` for projects with no frontend workstream. Fixed alongside (2).
  Four regression tests added to `tests/workstream-suppression.test.js` (three for `next()`, one for non-build stage dispatch).

### Fixed

- **Targeted-fix false-positive halt when blocker `file` includes a line-number suffix** (`src/backend/server.ts:5`): `blockerFiles()` now strips the `:\d+` suffix before hashing, so a genuine source-file change is correctly detected and the pipeline continues instead of escalating with `convergence-exhausted`. Closes #269.

### Fixed

- **Structural-input halt when patchItems push headless prompt over Claude Code's 4000-char goal-condition limit**: `runHeadless()` now detects prompts that exceed the limit and re-renders without `patchItems` before spawning the agent. A warning is emitted to stderr. The agent reads `pipeline/context.md` for blocker guidance instead of the inline patch block — the auto-fix mechanism already writes blockers there before dispatch, so no information is lost. Closes #277.

### Fixed

- **Spec drift false positive when AC line carries an inline backtick annotation** (e.g. `` **AC-10** `[deploy-deferred]` — … ``): `AC_LINE_RE` in `core/spec/verify.js` now optionally consumes a `` `[tag]` `` token between the AC identifier and the separator, so the drift checker extracts the correct AC count and stage-03b no longer halts with `orphan_scenarios=1`. Closes #274.

- **`spec drift: orphan_scenarios=N` false positive when brief uses numbered-list AC format fixed.** `AC_LINE_RE` in `core/spec/verify.js` accepted dash/star/plus bullet markers but not numbered-list markers (`1. **AC-N**`). When the PM agent writes ACs as a numbered list (e.g. `1. **AC-1 — HTTP endpoint exists**: ...`), no ACs were extracted from the brief; every scenario's `@AC-N` tag then referenced an ID absent from the empty brief, orphaning all scenarios and halting stage-03b with `spec drift: orphan_criteria=[none], orphan_scenarios=N`. Fix: extend the optional bullet-prefix alternation to also match `\d+\.\s+`.

### Fixed

- **Targeted-fix ghost-workstream cycle**: when a post-build stage (accessibility-audit, peer-review, QA) triggers a `fix-and-retry` for a file whose `file_ownership` points to a workstream that stage-04 never dispatched (e.g. `frontend` in a backend-only project), the driver now rejects the inferred workstream and falls back to a regular build dispatch instead of silently cycling until fix-retry budgets are exhausted. Closes #271.

- **Durable dispatch evidence (Phase 17).** Autonomous runs now retain one privacy-bounded `dispatch-observation` per non-skipped workstream, allowing `devteam evidence status` and consented bundles to measure D5 routing history without treating current or archived gate snapshots as durable evidence. Legacy projects remain readable and explicitly unready for the durable-history condition.

### Added

- Add explicit, privacy-bounded `devteam evidence accept-resolution --yes` records and
  cross-project H3 readiness for human-accepted derivable retry resolutions.

### Added

- Discover and aggregate Node, pytest, and Go test suites during orchestrator-stamped
  pre-review, QA, and repair verification while preserving explicit command overrides.

- **Rolling autonomous-run watch mode.** `devteam run --watch` renders current stage,
  dispatch elapsed time, log growth, heartbeat age, and observed stall status on an
  interactive terminal, with cursor cleanup and ANSI-free redirected-output fallback.
  This is display-only; ADR-007 Tier 2 process termination remains evidence-gated.

---

## [0.8.0] — 2026-06-19

### Added

- **Adapter conventions auto-injected into `pipeline/context.md` — Phase 15.2. Phase 15 complete.** When `deploy.adapter` is set in `.devteam/config.yml`, `devteam run` and `devteam stage` (requirements/design/build) now write a deploy-target context block into `pipeline/context.md` before the first agent dispatches. The block is idempotent (written via `upsertSection`), adapter-specific, and removed cleanly when the adapter changes and pipeline state is reset. Two adapter conventions files ship: `core/deploy/gizmos.conventions.md` (language, runtime, required file structure, no-build-step rule, file tracking, secrets model, health check requirements for Gizmos/Cloudflare Workers) and `core/deploy/cloud-run.conventions.md` (runtime, structure, `PORT` env var, state/persistence model, health check requirements for GCP Cloud Run). The new `seedDeployContext(cwd, config, changeId, opts)` function in `core/driver.js` reads the adapter name from `config.deploy.adapter`, resolves the companion `.conventions.md` file, and upserts it into `pipeline/context.md`. `loadConfig()` in `core/config.js` now exposes `config.deploy` directly (previously only available via `config._raw.deploy`). `core/deploy/README.md` documents the conventions file pattern. 6 new tests in `tests/deploy-conventions.test.js` cover the false-on-null, false-on-missing-file, write+content, idempotency, update, and auto-mkdir cases. **Phase 15 complete.** All items shipped: pre-work `devteam init --adapter` (PR #173); 15.1 gizmos auth fix / `GIZMOS_API_KEY` (PR #176); 15.2 conventions injection (this item, feat/adapter-conventions).

- **Dogfooding guide — `docs/guides/dogfooding.md` (Phase 14.5). Phase 14 complete.** New user-facing guide covering the complete dogfooding workflow: prerequisites (dedicated clone, `npm link`), one-time setup with `devteam init --profile dogfood` + `devteam doctor`, per-feature workflow (branch → `devteam run --budget-usd` → review → commit → clean up), recommended budget table ($3–25 depending on depth), infrastructure guard explanation, failure-mode table, and expected `devteam doctor` output for "Dogfood mode". Cross-referenced from `docs/user-guide.md` § What's not covered here and indexed in `docs/README.md`. `devteam --help` updated to document `--profile dogfood` on the `init` command. **Phase 14 complete.** All five items shipped: 14.1 `--profile dogfood` (PR #163); 14.2 doctor dogfood checks (PR #164); 14.3 preflight artifact guard (PR #165); 14.4 budget warning (PR #166); 14.5 this guide.

- **`devteam run` now warns on stderr when no `--budget-usd` cap is set (Phase 14.4).** When the driver starts without a budget cap (`budgetUsd === null`), it immediately writes a two-line warning to stderr: `[devteam run] Warning: no --budget-usd cap set. The run will not halt on spend.` / `Use --budget-usd <amount> to prevent runaway cost.` This appears before the first stage dispatch so operators can abort early. The warning does not affect exit codes or pipeline behavior — it is purely advisory. 2 new tests in `tests/driver.test.js`: warning present without cap, absent when cap is set.

- **`devteam preflight` now blocks PRs that contain staged pipeline artifacts (Phase 14.3).** A new check (`checkStagedPipelineArtifacts`) runs `git diff --cached --name-only` and emits a BLOCKER if any file matching the artifact prefix list (`pipeline/brief.md`, `pipeline/context.md`, `pipeline/spec.feature`, `pipeline/gates/`, `pipeline/code-review/`, `pipeline/changes/`, and nine other runtime paths) appears in the git index. Applies to all projects — staging these files into a peer-review PR is always a mistake. Handles non-git directories gracefully (returns `[]`, no error). 8 new tests in `tests/preflight.test.js` using real git tempdirs.

- **`devteam doctor` now shows a "Dogfood mode" section when `profile: dogfood` is set (Phase 14.2).** Six checks are shown: pre-commit infrastructure guard present, hook executable, `# BEGIN stagecraft-dogfood` block in `.gitignore`, `pipeline/stages/deploy.md` in `.git/info/exclude`, no `npm publish` script (warn if present — anti-pattern for dogfooding), and a budget-usd reminder (info). The section is entirely absent when the profile is not set. Profile is read from the raw parsed YAML (`config._raw?.profile`); no changes to `loadConfig()` needed. 14 new tests in `tests/doctor.test.js`.

- **`devteam init --profile dogfood` writes four dogfooding safeguards (Phase 14.1).** Running `devteam init --host <x> --profile dogfood` now writes a supplemental `# BEGIN stagecraft-dogfood` gitignore block covering generated pipeline documents (`brief.md`, `context.md`, `spec.feature`, `runbook.md`, `test-report.md`, `code-review/`, and their `pipeline/changes/*/` counterparts), installs a pre-commit hook that blocks accidental commits to `core/`, `bin/devteam`, `pipeline/stages/`, `roles/`, or `rules/`, adds `pipeline/stages/deploy.md` to `.git/info/exclude`, and writes a `profile: dogfood` marker to `.devteam/config.yml`. All writes are idempotent — re-running the command skips already-correct state.

- **Gizmos deploy adapter — Phase 13.2. Phase 13 complete.** `core/deploy/gizmos.md` is a new built-in deploy adapter for stage-08 targeting the Gizmos platform (Cloudflare Workers, `gizmos.run`). It pushes source code via `gizmos push`, smoke-tests the live `$APP.gizmos.run` URL with `curl --retry 3`, and writes a compliant stage-08 gate with `deploy_completed`, `smoke_tests_passed`, and `rollback_executed`. Config: `deploy.gizmos.app` (required; must match `wrangler.toml name`) and `deploy.gizmos.src` (required). Precondition checks: PM sign-off gate, `wrangler.toml` existence, `app`/`name` match, runbook `§Rollback` section, `gizmos whoami` auth. **Platform constraints** section documents the Cloudflare Workers runtime limits (TS/JS or Python only; no persistent filesystem; stateless `fetch()` handler; ~30s CPU per request). `core/deploy/README.md` table updated. `tests/deploy-adapters.test.js` extended with 11 new tests (README table sync, file existence, all required sections including `## Platform constraints`, three schema-required gate fields). Suite: 1793 pass (CI mode), lint clean, consistency 319 checks green.

- **GCP Cloud Run deploy adapter — Phase 13.1.** `core/deploy/cloud-run.md` is a new built-in deploy adapter for stage-08. It builds a Docker image, pushes to GCP Artifact Registry, deploys a new Cloud Run revision via `gcloud run deploy`, smoke-tests the live URL with `curl --retry 3`, records the active revision name for rollback, and writes `pipeline/deploy-log.md`. Gate body uses the three schema-required fields: `deploy_completed`, `smoke_tests_passed`, `rollback_executed`. Config: `deploy.cloud_run.project` / `.region` / `.service` (required); `.repository` (default `"cloud-run"`); `.image_tag` (default: git short SHA); `.extra_flags`. Universal fields `deploy.environment` and `deploy.smoke_test_path` introduced for all adapters. `core/deploy/README.md` table updated with the new row. New `tests/deploy-adapters.test.js` (10 tests) validates adapter-file existence, all required sections, the three schema-required gate fields, and README table sync — catches future adapter drift. Suite: 1782 pass (CI mode), lint clean, consistency 319 checks green.

- **`devteam commit` command — Phase 12.2 (ADR-010).** New first-class command that stages exactly the right pipeline artifacts for completed stages and generates a meaningful commit message — without any manual `git add` decisions from the operator. Reads `pipeline/run-state.json`, determines which stages have not yet been committed (idempotency cursor `last_committed_stage_index`), stages the gate file for each PASS/WARN stage plus named artifacts from `core/pipeline/artifacts.js` (brief.md, design-spec.md, spec.feature, code-review/, test-report.md, etc.), excludes all volatile runtime files (run-state.json, run.lock, run-log.jsonl, logs/, gates/archive/, etc.), generates `"pipeline: stages NN–NN PASS"` (or `"pipeline(repair): ..."` for repair runs), and prompts `y/n/e` before committing with a `Co-Authored-By: Stagecraft` trailer. `--all` ignores cursor; `--dry-run` prints without committing; `--message` overrides; `--json` emits machine-readable output. Calling it twice is a no-op (second call prints "nothing to commit"). `run-state.json` gains `stages_advanced` (stage IDs in pipeline order) and `last_committed_stage_index` (commit cursor, null until first commit); old run-states are migrated on read. `RUN_SCHEMA_VERSION` bumped to 1.2. Stage artifact registry in `core/pipeline/artifacts.js` covers all 19 stage IDs. Tests: 27 new tests in `tests/commit.test.js` (file selection, cursor mechanics, repair-mode diagnosis.md substitution, schema migration, volatile exclusion, WARN gate inclusion, directory and glob artifact expansion, CLI registration, and driver state writing). Honest scope note: in-place pipeline mode only (changeId=null); bounded-workspace support is Phase 12.3+. Suite: 1757 pass, lint clean, consistency 319 checks green.

- **Track provenance: `pipeline/track.json` + confirmation guard — Phase 11.3 (ADR-006). Phase 11 complete.** `devteam assess` (default) now writes `pipeline/track.json` — a per-run track inference record with `{track, source, confidence, reasons, assessed_at, assessed_by}` — so every autonomous run has a traceable provenance record. `--confirm` sets `source: "human"`; `--apply` still writes `pipeline.custom_stages` to `.devteam/config.yml` (no breaking change). `resolveTrack` in `core/driver.js` now returns `{track, source, confidence}` and reads `pipeline/track.json` in precedence order: `--track > pipeline/track.json > custom_stages > default_track > "full"`. New `run-start` event in `run-log.jsonl` carries `track_source` and `track_confidence` for audit provenance; `track-confidence-check` event logged on every guard invocation. New `autonomy.require_confirmed_track` config flag (default `false`): when on, an inferred `pipeline/track.json` at medium or low confidence halts with `unconfirmed-track` requiring `--track` or `--force`; high confidence proceeds. The flag is **not** keyed on `CI=true` (which is already overloaded by validator strict-mode and the verify runner). Docs: `docs/tracks.md` "Track record" section; `docs/runbooks/autonomous-run.md` pre-run checklist + `unconfirmed-track` halt row; `docs/ci.md` assess step + `require_confirmed_track` section. Tests: 9 new tests covering `resolveTrack` precedence, confidence guard (flag off warn-only, flag on medium/low halt, flag on high proceeds, human source no halt, `--force` bypass, run-start event fields), and CLI assess behavior. Suite: 1718 pass, lint clean, consistency green.

- **Advisory sweep on completion + `--fail-on-advisory` — Phase 11.2 (ADR-008).** After `pipeline-complete`, the driver now runs an in-process advisory sweep (reusing `core/advise.js` classification: `QA_BLOCKER` / `PEER_REVIEW_RISK` / `A11Y_FIX`) and adds `advisory_blockers_count` and `advisory_breakdown` (per-class counts) to the `--json` summary (schema version bumped to `1.1`). When any blocker-class items remain, the driver prints a loud line to stderr: `pipeline complete — N advisory blocker(s) remain; run \`devteam advise\` to review`. **The default exit code is unchanged** — `pipeline-complete` still exits 0 so external `if devteam run; then merge` consumers are unaffected (ADR-008 revision: A-default). New opt-in `--fail-on-advisory` flag exits **3** (not 1 — preserves the failed-vs-advisory distinction) when unaddressed blocker-class items remain; default threshold: `QA_BLOCKER` + `A11Y_FIX`; `--fail-on-advisory=all` adds `PEER_REVIEW_RISK`. Flag parser extended to support `--flag=value` form and a new `"toggle"` type (bare → `true`, `=value` → value string). Docs: exit-code table updated (0/1/2/3) in `docs/runbooks/autonomous-run.md` and the CLI reference; `docs/ci.md` lenient-vs-strict advisory gate examples added. Tests: 7 new tests (2 driver-level, 5 CLI-subprocess) in `tests/run.test.js`. Suite: 1709 pass, lint clean, consistency green (318 checks).

- **Liveness heartbeat + observe-only stall detector — Phase 11.1 (ADR-007 Tier 1).** The driver now emits a `heartbeat` event to `run-log.jsonl` (and via `onEvent`) at the **start of every loop iteration**, before `next()`, so the last-event age is always bounded. Alongside each `run-stage`/`continue-stage` dispatch an **observe-only stall probe** runs fire-and-forget: it wakes every 60 s and emits `stall-detected` (with `stall_class: "observed"`) if neither the workstream log (under `pipeline/logs/`) grew ≥ 512 bytes nor any gate updated within 5 minutes. The dispatch is **never killed, no `Promise.race` fires** (Tier-1 observe-only; the probe self-cancels via a `cancelled` flag when the dispatch settles, preventing stale events). Config: optional `autonomy.stall_threshold_ms` (default 300000) and `autonomy.stall_min_growth_bytes` (default 512) in `.devteam/config.yml`. The probe detects silent hangs only — loop-spew (repetitive output that resets the clock) rides with ADR-007 Tier 2. New read-only **`devteam status`** command reads `run-state.json` + tail of `run-log.jsonl` and reports `status / current_stage / last_action / iterations / cost_usd / last_heartbeat_age_ms / last_event_age_ms / stall_detected`. Docs: "No heartbeat" removed from `docs/runbooks/autonomous-run.md` Honest Limitations; replaced with a full liveness section (heartbeat, stall probe, `devteam status` fields, observe-first note); `devteam status` added to help text. Tests: 4 new tests in `tests/run.test.js` (heartbeat every iteration, stall-detected on flat log+gate with injected clock, no stale event after dispatch settles, no kill on stall) and 1 new `tests/status.test.js` file (ages from fixture log). Suite: 1702 pass, lint clean, consistency green (318 checks).

- **Repair-mode vocabulary map, runbook, and deferred metrics surface — Phase 10.4 (ADR-009 §Decision.8 + §Decision.7).** Ships the residual "teaching" cost named in ADR-009 §Consequences plus the advisory metrics surface. (1) **Vocabulary map** (`docs/conventions.md` § Repair-mode vocabulary): authoritative table distinguishing `--repair` (intent), `hotfix` (depth), `fix-and-retry` / `fix_steps` (internal driver machinery), and PATCH MODE (mechanism). Explains why the internal terms were not renamed and why a `--repair` run coexisting with `fix-retry` events is expected, not a bug. (2) **Repair-flow runbook** (`docs/runbooks/repair-flow.md`): covers all three operator decision points — (a) diagnosis gate approval: what to read, interactive vs autonomous approval, `--repair-at` escape hatch, and the knowledge-gate honest limitation; (b) scope-gate FAIL recovery: why it fires, how to amend the diagnosis scope and re-run, and when the gate is inert; (c) tri-state reproduction: what `reproduced: true / false / "unverifiable: <reason>"` each means, accepted skip reasons, and why repair-on-hotfix now includes stage-03b. Indexed in `docs/runbooks/README.md` (3 symptom rows + listing) and `docs/README.md`. (3) **Advisory metrics surface** (`scripts/dashboard.js` / `routing-suggest.js` / `budget.js`): `dashboard.js` accepts `--by intent` as a new grouping slice for both pass-rate and cost views; exports `computeScopeAdherence(gates)` (headline repair metric: did the build stay within the diagnosed files, from gates with `scope_adhered` field) and `computeCostInversionEstimate(...)` (savings estimate with exposed inputs — `savings ≈ diagnosisRejectionRate × avgFullBuildCost − diagnosisCost` — never a measured figure); `routing-suggest.js` adds `--intent repair|feature` filter backed by `filterByIntent(gates, intent)` so routing suggestions can be computed per-intent; `budget.js` adds `--intent` on `init`, writes an optional `Intent:` line in `pipeline/budget.md`, and preserves it through `update` calls. All three changes are advisory-only and non-blocking. `npm run docs:generate` confirmed idempotent; `--repair` flag was already in `docs/reference/cli.md` from 10.1. (4) `examples/sms-opt-in` remains the feature-intent canonical example; no separate repair example was added (none requested).

  Tests (15 new in `tests/repair-metrics.test.js`): intent slice in `aggregate()` and `aggregateCost()` (groups repair/feature gates, fallback "(no intent)"); `computeScopeAdherence` (rate computation, null when no data, feature gates excluded); `computeCostInversionEstimate` (positive savings, negative savings, missing inputs → null); `routing-suggest.filterByIntent` (repair-only, feature-only, null passthrough, exclusion of intent-less gates). Suite: 1691 pass (was 1676), 0 fail, lint clean, consistency 318 checks passed.

  **Phase 10 complete.** All four items shipped: 10.1 PATCH-MODE intent flag (PR #140); 10.2 diagnosis stage + scope gate (PR #141); 10.3 failing-first reproduction (PR #146); 10.4 vocabulary + runbook + metrics (PR #147).

- **Failing-first reproduction via stage-03b + stamp, tri-state honest skip — Phase 10.3 (ADR-009 Phase 3).** The mitigation for 10.2's knowledge-gate limit: repair runs now route through stage-03b (executable-spec) even on hotfix depth (which normally skips it), adding failing-first reproduction discipline to every repair. Concretely: (1) **Stage order injection** — for `intent === "repair"`, the driver's stage order always injects `"executable-spec"` immediately before `"build"`, regardless of the base track; hotfix repair runs gain `[requirements, executable-spec, build, ...]` instead of `[requirements, build, ...]`. (2) **`repairOverride` for stage-03b** — `core/pipeline/stages.js` adds a `repairOverride` to the `"executable-spec"` stage (same pattern as the stage-01 diagnosis override from Phase 2): in repair mode `buildDescriptor` swaps the objective to failing-first framing ("write a Gherkin Scenario that is RED before the fix and GREEN after") and adds `reproduced: false` to the gate shape so the PM model knows to set it. (3) **Tri-state `reproduced` field** — `core/gates/schemas/stage-03b.schema.json` gains an optional `reproduced` property (not in `required`; omitted for feature runs): `true` = bug reproduced and fix verified green; `false` = could not reproduce; `"unverifiable: <reason>"` = automated test impossible (external API / nondeterminism / data dependency). (4) **`stampStage03b` handles the tri-state**: `"unverifiable: ..."` → WARN loudly to `gate.warnings`, no blocker (run proceeds, but manual verification is flagged); `true|false` → runs the project's test command to capture the pre-build (pre-fix) baseline in `_orchestrator_stamped.runs.reproduction_pre_build`, marks the field as `orchestrator_deferred` pending stage-04a. (5) **`stampStage04a` finalizes `reproduced`**: after running the post-build test command, reads the stage-03b gate (if present) and writes `reproduced: true` when tests pass (green after fix confirmed), `reproduced: false` when tests fail (fix didn't work); unverifiable bugs are not touched; the `reproduction_verification` audit record (`red_before_confirmed`, `green_after_confirmed`, `post_build_tests_passed`, `pre_build_tests_passed`) is appended to `_orchestrator_stamped.runs`. Feature runs (no `reproduced` in stage-03b gate) are silently skipped. (6) The `--repair-at` escape hatch also includes stage-03b — reproduction discipline applies even when diagnosis is bypassed.

  Tests (15 new): `tests/repair-mode.test.js` section 8 — hotfix baseline confirms executable-spec absent from hotfix track; repair intent on hotfix includes executable-spec in captured order array; executable-spec placed immediately before build; full-track repair no double-inject; `--repair-at` still includes executable-spec; `buildDescriptor` repair objective mentions failing-first; feature mode gate has no `reproduced`. `tests/verify-stamp.test.js` — unverifiable adds loud WARN, no blocker; `reproduced:true` records pre-build red; `reproduced:false` records pre-build green; feature run no reproduction_pre_build; red-before/green-after stamps `reproduced:true` from stage-04a; post-fix fail stamps `reproduced:false`; unverifiable not changed by stage-04a; feature run (no stage-03b gate) skips gracefully. Suite: 1676 pass (was 1661), 0 fail, lint clean, consistency 317 checks passed.

  Honest scope note: The "red before" phase captures pre-build test state at stage-03b time; since the regression test code is written by the build agent (not the PM), the pre-build run records whatever tests already exist rather than a regression-specific test. The "green after" phase is orchestrator-verified at stage-04a via the actual test command exit code. The combination — stamp records both phases, final `reproduced` is set by the orchestrator (not the agent alone) — satisfies the "not asserted by the agent" requirement.

- **Diagnosis as fix-aware stage-01 and `--repair-at` escape hatch — Phase 10.2 (ADR-009 Phase 2).** When `intent === "repair"`, stage-01 (requirements) produces a **DIAGNOSIS** document instead of a feature brief — same stage id, same gate file path, fix-aware artifact, no new stages. Concretely: (1) `repairOverride` field added to the `requirements` stage definition; `buildDescriptor` in the orchestrator applies it when `intent === "repair"`, swapping objective, artifact (`pipeline/diagnosis.md`), template (`templates/diagnosis-template.md`), `allowedWrites`, and gate schema. (2) The diagnosis gate is always **ESCALATE-shaped** — a judgment gate with `escalation_reason` and `decision_needed` fields, requiring human approval or `--auto-rule diagnosis-approved` before the build proceeds. `diagnosis-approved` is the new ruling class slug; grant it with `--auto-rule diagnosis-approved`. (3) Driver: `repairNeedsDiagnosis = intent === "repair" && !repairAt` prepends `"requirements"` to the effective stage order so `next()` routes through diagnosis before build; the diagnosis gate's `affected_files` list is read before each build dispatch and populates `state.affectedFiles`, **activating 10.1's structural scope gate** (previously inert — no diagnosis stage existed to supply the list); `repairPatchItems` upgrades from the raw symptom string to structured per-file entries from the diagnosis. (4) **`--repair-at <file>:<line>` escape hatch** — when the caller already knows the defect location, comma-separated `file:line` locations seed `state.affectedFiles` directly, write a synthetic PASS stage-01 gate, and skip the LLM diagnosis dispatch entirely; a `repair-at-seeded` event is logged. (5) `intent` propagated through `ctx` in `runStage()` so adapters render repair-mode prompts. Tests (6 new in `tests/repair-mode.test.js`, section 7): `buildDescriptor` repair shape (unit); `buildDescriptor` feature shape unchanged (unit); scope gate activates from diagnosis gate `affected_files` without `opts.affectedFiles` (this test failed on main before 10.2); diagnosis ESCALATE halts without `--auto-rule`; `--auto-rule diagnosis-approved` proceeds; `--repair-at` escape hatch seeds, writes synthetic gate, skips dispatch. Suite: 1661 pass (was 1655), lint clean, consistency 317 checks passed.

- **`--repair "<symptom>"` intent flag — Phase 10.1 (ADR-009 Phase 1).** Adds `--repair` to `devteam run` as an intent flag orthogonal to `--track`, implemented as fix-aware wiring on existing stages — zero new stages, zero parallel pipeline. Concretely: (1) `--repair` and `--feature` are mutually exclusive (enforced in both the CLI command and the driver); (2) `--repair` defaults to `hotfix` depth; `--repair --track full` overrides; auth/payments/migration symptoms are upgraded to `full` via the same stoplist patterns (`checkStoplist`) regardless of the default — the existing lighter-track stoplist bypass does not apply here; (3) `intent: "repair" | "feature"` is written to `run-state.json` and every run-log event base object from day one (ADR-009 §Decision.7 perishable baseline — without this, repair vs feature runs are indistinguishable in history); `repair: <symptom>` string is also persisted in run-state; (4) on `--resume`, a `prior_run_id` correlation field is written linking the re-run to its predecessor's `started_at`; (5) `changeIdFromSymptom` exported from `core/config.js` (same slug algorithm as `changeIdFromFeature`) so bounded-isolation paths can derive the changeId from a symptom string (ADR-009 §Consequences); (6) repair builds dispatch `runStageHeadless` with `patchItems` set to the symptom string, activating `renderPatchBlock`'s `## ⚠️  PATCH MODE — targeted fix only` block in the build prompt — no new prompt authored (ADR-009 §Decision.2, PATCH MODE is the existing mechanism); (7) structural scope gate wired behind `state.affectedFiles` / `opts.affectedFiles`: a post-build `checkScopeGate` call (injectable for tests; default: `git diff --name-only HEAD`) fails the run with `halt_action: "scope-gate"` when files outside the list were touched. The list is supplied by 10.2's diagnosis stage (same release). CLI reference regenerated (`npm run docs:generate`). Tests (14 new in `tests/repair-mode.test.js`): mutual exclusion (both CLI and driver-level); hotfix default; `--track full` override; auth-symptom stoplist upgrade with event emission and run-log verification; intent tag in run-state and run-log; feature run intent tag; resume prior_run_id correlation; repair build patchItems dispatch; feature build lacks patchItems; `renderPatchBlock` unit check with symptom text; scope gate FAIL with synthetic affected-files list; scope gate PASS within scope; scope gate inert without affectedFiles. Suite: 1655 pass (was 1641), lint clean, consistency 317 checks passed.

- Require Phase 1 and Phase 2 audit findings to include `verified_by` evidence before they can be promoted above LOW confidence.

- Stream headless stage transcripts directly to disk so long-running host output stays observable and no longer grows Stagecraft's memory with transcript size.

- Reconcile current documentation and maintenance guidance with shipped Windows support, canonical role-tool ownership, performance-gate vocabulary, bounded autonomy, and supported embedding providers.

- Demote unused `adapterPath` and verify runner timeout exports to private module details.

---
type: feat
---

- Add `cloud-run` deploy adapter (`core/deploy/cloud-run.md`): builds a Docker image, pushes to GCP Artifact Registry, deploys a Cloud Run revision, smoke-tests the live URL, and writes a compliant stage-08 gate with `deploy_completed`, `smoke_tests_passed`, and `rollback_executed` fields.

Added a Stage 8 deploy cost gate that blocks 10x-or-greater recurring cost increases unless an explicit human override is recorded.

---
type: feat
---

- Add `gizmos` deploy adapter (`core/deploy/gizmos.md`): pushes source to the Gizmos platform (Cloudflare Workers, gizmos.run) via `gizmos push`, smoke-tests the live URL, and writes a compliant stage-08 gate with `deploy_completed`, `smoke_tests_passed`, and `rollback_executed` fields.

- **docs(analysis):** D5 adaptive routing evidence review (`plans/adaptive-routing-evidence.md`). Runs `devteam routing:suggest` against all accumulated pipeline gate data; finds zero real-run telemetry — only the hand-authored `examples/sms-opt-in` fixture (max 4 dispatches per role, no cost data). The tool's MIN_DISPATCHES guard fires for all 6 roles; no recommendations are produced; human conclusion matches tool output. Verdict: continuous adaptive routing stays gated pending ≥5 dispatches per (role, host) pair across ≥2 real projects, cost telemetry, and ADR-007 implementation. Honest scope note: ADR-007 precondition not yet met.

- **docs(adr):** Draft ADR-007 — Liveness/heartbeat (`docs/adr/007-liveness-heartbeat.md`, Status: Proposed). Defines *stall* (host process alive, output flowing, no gate progress) as distinct from the wall-clock `timeoutMs` timeout; specifies a per-iteration `heartbeat` event in `run-log.jsonl` and a dispatch-progress probe (log-file growth vs gate mtime) running as `Promise.race` alongside each dispatch; specifies operator surface (`devteam status` reporting `last_heartbeat_age_ms` and `stall_detected`, and a `devteam run --watch` rendering flag); stall response reuses the existing `transient`/`structural` vocabulary from `classifyDispatch`. Ends with 7 open questions for human ruling. Updates `docs/adr/README.md` to move ADR-007 from Deferred to the main Proposed index.

- **docs(adr):** Draft ADR-008 — Exit semantics (`docs/adr/008-exit-semantics.md`, Status: Proposed). Confirms [verify-first]: `devteam run` exits 0 on `pipeline-complete` with pending advise blockers — the design-doc step 9 ("run a final advise sweep and exit") was never implemented. ADR frames four options (status quo, exit 1, exit 3, opt-in flag), with exit 3 as the recommended candidate for evaluation; ends with 4 open questions for human ruling including severity threshold and CI contract documentation. Updates `docs/adr/README.md` to move ADR-008 from Deferred to the main Proposed index.

- **Docs: FAQ entry on preserving implementation constraints through the PM interpretation layer.** The PM agent rewrites `--feature` as product intent, which can normalise away specific env var names, API endpoints, or explicit exclusions. The new entry covers: (1) phrasing constraints as observable behaviours so the PM captures them as ACs, (2) seeding `pipeline/context.md` with a binding constraints block before running, and (3) how to open a build-gate blocker and re-run after the build has already produced the wrong implementation.

## `docs/git-workflow.md` restructure + repair-mode commit guidance (Phase 12.4)

**`docs/git-workflow.md`** restructured into a 7-section outline covering both operator
modes: §1 Overview (interactive vs. autonomous; what lives in git), §2 What to commit vs.
ignore (reference `devteam init` gitignore block; include/exclude table), §3 Interactive
mode (`devteam commit` as primary interface; per-stage-group commit cadence; Stage 04
worktrees), §4 Autonomous mode (new: `halt_action` table identifying `ceiling`/`until`/
`budget` as clean commit signals; `devteam commit` after a halt; `--auto-commit` opt-in
semantics), §5 Repair mode (new: three natural commit points; note that source file staging
is the operator's responsibility), §6 PR timing, §7 CI integration.

**`docs/runbooks/repair-flow.md`** — added "When to commit in repair mode" section: three
commit points (after diagnosis gate approval, after failing-first test, after build + scope
gate PASS). Notes that `devteam commit` handles gate files automatically; application source
files require explicit `git add` by the operator.

**Phase 12 complete.** All four items shipped: managed gitignore (PR #154), `devteam commit`
(PR #155), `--auto-commit` (PR #156), docs restructure (PR #157).

---
type: fix
---

- Document gizmos secrets limitation in `core/deploy/gizmos.md`: `gizmos push` has no flag for env vars or secrets; add them via the Gizmos hub UI after the first deploy. First-request failure is expected, not a broken deploy.

- **Plan: Phase 12 — Git workflow automation (ADR-010).** Documents the design and implementation plan for removing the two structural git friction points in Stagecraft: volatile file management (`devteam init` writes a managed `.gitignore` block) and autonomous-mode commit timing (`devteam commit` command + `devteam run --auto-commit` on clean halts). ADR-010 proposes five binding decisions; items 12.1–12.4 are blocked until ADR-010 is accepted.

- **Plan: Phase 14 — Dogfooding support.** Adds `devteam init --profile dogfood` (infrastructure guard pre-commit hook, supplemental gitignore block for pipeline document artifacts, `.git/info/exclude` entry for deploy spec, `profile: dogfood` config marker), `devteam doctor` dogfood-mode checks (6 checks: hook presence/executability, gitignore block, exclude entry, no publish script, budget reminder), a preflight gate that blocks staged pipeline artifacts from reaching peer-review, a budget-cap warning when `devteam run` starts without `--budget-usd`, and `docs/guides/dogfooding.md`. Tracking: issue #130.

- **Plan: Phase 15 — Adapter-aware stage context.** Pre-work (`devteam init --adapter`, PR #173) and 15.1 (gizmos auth fix, PR #176) complete. 15.2 adds `core/deploy/<adapter>.conventions.md` files (Gizmos and Cloud Run) and a `seedDeployContext()` function that writes adapter platform constraints into `pipeline/context.md` before stages 01–03 dispatch — so `--feature` strings can express pure intent without repeating stack details already implied by `deploy.adapter` config.

- **Docs: adoption guide now covers project context seeding as a first-run step.** A new Step 4 in the Week 1 pilot sequence explains what to write into `pipeline/context.md` before the first pipeline run — architecture, platform, locked-in technology choices, compliance constraints, integration points, and team conventions. Includes a safe-zone rule (content must go above `<!-- devteam: -->` markers to survive pipeline runs), a concrete example for a payments service, and a cross-reference between the adoption guide and the existing FAQ entry on preserving per-run binding constraints through the PM layer.

- **Repair-mode vocabulary map (ADR-009 §Decision.8).** `docs/conventions.md` now carries the authoritative vocabulary table distinguishing `--repair` (intent), `hotfix` (depth), `fix-and-retry` / `fix_steps` (internal driver machinery), and PATCH MODE (the mechanism `--repair` reuses). Explains why renaming the internal terms was rejected and why a `--repair` run will still emit `fix-retry` events in its `run-log.jsonl` — coexistence is expected, not a bug.
- **Repair-mode runbook (`docs/runbooks/repair-flow.md`).** Covers all three operator decision points: (1) the diagnosis gate — what to read, how to approve interactively and autonomously, the `--repair-at` escape hatch, and the knowledge-gate limit; (2) scope-gate FAIL recovery — why it fires, how to amend the diagnosis scope and re-run, and why the gate is inert without a diagnosis; (3) tri-state reproduction — what `reproduced: true / false / "unverifiable: <reason>"` each means, accepted skip reasons, and why repair-on-hotfix now includes stage-03b. `docs/runbooks/README.md` gains three index rows. Pointer added to `docs/conventions.md` § See also.
- **Metrics surface — intent slice (ADR-009 §Decision.7, advisory only).** `scripts/dashboard.js` accepts `--by intent` as a new grouping dimension (alongside existing stage / host / role / status). Both pass-rate and cost views support the slice. Exports `computeScopeAdherence(gates)` (scope adherence: did the repair build stay within the diagnosed affected-files set — the headline repair metric, ADR-009 §Decision.3) and `computeCostInversionEstimate({ diagnosisRejectionRate, avgFullBuildCost, diagnosisCost })` (savings estimate with exposed inputs — never a measured figure). `scripts/routing-suggest.js` exports and wires `filterByIntent(gates, intent)` behind a `--intent repair|feature` CLI flag so routing recommendations can be computed separately for each intent. `scripts/budget.js` accepts `--intent repair|feature` on `init` and records an optional `Intent:` line in `pipeline/budget.md`, preserved across `update` calls. Tests: 14 new in `tests/repair-metrics.test.js` covering intent slice (aggregate + cost), scope adherence, cost inversion estimate, and routing-suggest filterByIntent.

- Clarify the per-stage rule-file coverage shape so stages 3 and 03b are documented as intentional `pipeline-core.md` guidance rather than missing rule files.

- **`devteam doctor` now shows a "Dogfood mode" section when `profile: dogfood` is set (Phase 14.2).** Six checks are shown: pre-commit infrastructure guard present, hook executable, `# BEGIN stagecraft-dogfood` block in `.gitignore`, `pipeline/stages/deploy.md` in `.git/info/exclude`, no `npm publish` script (warn), and a budget-usd reminder (info). The section is entirely absent when the profile is not set.

## Unreleased

- Enforced the Stage 7 documentation gate with schema fields, validator checks, and auto-fold changed-file evidence.

- **Docs: dogfooding guide.** Adds `docs/guides/dogfooding.md` — one-time setup with `devteam init --profile dogfood`, per-feature workflow, recommended budget table, infrastructure guard explanation, failure modes, and expected `devteam doctor` output. Cross-referenced from `docs/user-guide.md`.

- **Extract autonomous-driver dispatch decisions** (audit P2-2, roadmap PR 3.2b).
  Moves consequence, `--until`, and budget guards; host-result normalization;
  transient/structural classification; targeted-fix convergence; and repair scope
  decisions into pure handlers returning the common transition result. `run()`
  retains host invocation, stall probes, persistence, retry delay, stub cleanup,
  and loop ownership. Existing characterization traces remain unchanged. *Honest
  scope note:* fix, ruling, and merge handlers remain the sequential PR 3.2c.

- Taught autonomous fix retries to use the Stage 2 `file_ownership` map when routing blocker-named files back to a single owning build workstream.

- **Complete autonomous-driver transition extraction** (audit P2-2, roadmap PR
  3.2c). Moves fix/retry and convergence outcomes, Principal-ruling boundaries, and
  merge results into pure handlers returning the common transition result. The
  effectful coordinator retains archive and gate writes, Principal and host dispatch,
  state persistence, locking, loop control, and final cleanup. Current backlog,
  design, and comparative guidance now record the completed three-PR decomposition.
  *Honest scope note:* this is a behavior-preserving structural change and adds no
  autonomous capability or gate/event vocabulary.

- **Characterize the autonomous-driver transition contract** (audit P2-2, roadmap
  PR 3.2a). Adds a common `continue` / `halt` / `complete` transition result for
  summary and run-state patches plus ordered run-log/progress events, and routes
  representative terminal paths through its centralized applicator. New
  characterization tests pin persisted state and event traces for successful and
  transient dispatch, non-code fixes, rulings, and merge failure before handler
  extraction begins. *Honest scope note:* this slice introduces and proves the
  contract; dispatch/transient and fix/ruling/merge handler extraction remain the
  sequential follow-up PRs.

- Add consented, aggregate-only evidence export with a rotatable pseudonymous project identity, strict schema and digest validation, sparse-cell suppression, and explicit multi-bundle portfolio readiness analysis.

- **Propose a privacy-safe evidence acquisition contract** (audit P3-1). Defines the
  raw-data threat model, aggregate-only export allowlist, pseudonymous and rotatable
  project identity, explicit consent boundary, sparse-cell suppression, strict bundle
  schema direction, and the sequenced local-status/export implementation plan. This
  proposal changes no runtime behavior and does not open evidence-gated capabilities.

- **Add read-only evidence readiness** (audit P3-1, Phase 16.2). `devteam evidence
  status` uses bounded, symlink-rejecting readers to aggregate local run logs, current
  gates, and gate archives for #142–#145. It separates local progress from
  cross-project conditions, reports degraded inputs, excludes free-form content, and
  explicitly marks durable-routing and accepted-resolution signals that current
  records cannot prove.

- Feat: adapter conventions auto-injected into pipeline/context.md.
  When deploy.adapter is set, devteam run and devteam stage (requirements/design/build)
  write a deploy-target context block into pipeline/context.md before the first agent
  dispatches. The block is idempotent and adapter-specific (gizmos, cloud-run have
  full conventions files). --feature strings no longer need to repeat stack details
  implied by the deploy adapter.

- **Advisory sweep on completion + `--fail-on-advisory` — Phase 11.2 (ADR-008).** After `pipeline-complete`, the driver now runs an in-process advisory sweep (reusing `core/advise.js` classification: `QA_BLOCKER` / `PEER_REVIEW_RISK` / `A11Y_FIX`) and adds `advisory_blockers_count` and `advisory_breakdown` (per-class counts) to the `--json` summary (schema version bumped to `1.1`). When any blocker-class items remain, the driver prints a loud line to stderr: `pipeline complete — N advisory blocker(s) remain; run \`devteam advise\` to review`. **The default exit code is unchanged** — `pipeline-complete` still exits 0 so external `if devteam run; then merge` consumers are unaffected (ADR-008 revision: A-default). New opt-in `--fail-on-advisory` flag exits **3** (not 1 — preserves the failed-vs-advisory distinction) when unaddressed blocker-class items remain; default threshold: `QA_BLOCKER` + `A11Y_FIX`; `--fail-on-advisory=all` adds `PEER_REVIEW_RISK`. Flag parser extended to support `--flag=value` form and a new `"toggle"` type (bare → `true`, `=value` → value string). Docs: exit-code table updated (0/1/2/3) in `docs/runbooks/autonomous-run.md` and the CLI reference; `docs/ci.md` lenient-vs-strict advisory gate examples added. Tests: 7 new tests (2 driver-level, 5 CLI-subprocess) in `tests/run.test.js`. Suite: 1709 pass, lint clean, consistency green (318 checks).

---
type: feat
---

- `devteam advise` now renders follow-up items grouped by risk tier (QA BLOCKER → PEER-REVIEW RISK → QA NOISE → INFO) with item counts; tiers with zero items are omitted.
- ADDRESSED items collapse to a single summary line (`✓ N addressed: id1, id2, ...`) instead of printing a full block per item.
- Scaffold follow-up commands are surfaced inline in read mode, not only after `--apply`.
- `runAdvise` result and `--json` output now include a `by_tier` object pre-grouping items by classification for machine consumers.

## `devteam commit` command (Phase 12.2)

**New command:** `devteam commit [options]`

Stages exactly the right pipeline artifacts for each completed stage and
generates a meaningful commit message — without any `git add` decisions from
the operator. Uses an idempotency cursor (`last_committed_stage_index`) so
calling it repeatedly is safe.

**Flags:**
- `--all` — stage all gate-bearing stages regardless of the cursor
- `--dry-run` — print what would be staged without committing
- `--message <msg>` — override the generated commit message
- `--json` — machine-readable output

**Stage artifact registry** (`core/pipeline/artifacts.js`): maps every stage ID
to its named output files. Gate files are added automatically for PASS/WARN
stages. Volatile runtime files (from the `devteam init` gitignore block) are
excluded unconditionally.

**Schema bump:** `run-state.json` now carries `stages_advanced` (list of stage
IDs in pipeline order) and `last_committed_stage_index` (commit cursor, `null`
if nothing has been committed). Both fields are migrated on read from pre-12.2
run states. `RUN_SCHEMA_VERSION` bumped to 1.2.

**Honest scope note:** Phase 12.2 supports in-place pipeline mode (changeId
null). Bounded-workspace (B9) support for `devteam commit` is a follow-on item.

- **New: `devteam compact`** (`core/cli/commands/compact.js`). Strips all devteam-managed marker sections (`<!-- devteam:*:begin/end -->`) from `pipeline/context.md` in one shot. These sections (run-blockers, red-team-blockers, deploy-target, advise, etc.) are regenerated by devteam on the next run when still needed, so removing them is always safe. Supports `--dry-run` to preview what would be removed and `--json` for scripted use. Designed for projects with long-lived in-place pipelines where `context.md` has accumulated blocker history across multiple escalation/ruling cycles, and as a pre-migration cleanup step before switching to bounded isolation.

- Added `--feature-file <path>` for `devteam stage` and `devteam run` so longer feature briefs can be read from disk.

- **Feat: `devteam init --adapter <name>` sets the stage-08 deploy target.** Pass `--adapter gizmos`, `--adapter cloud-run`, `--adapter docker-compose`, `--adapter kubernetes`, `--adapter terraform`, or `--adapter custom` at init time to write the `deploy:` block into `.devteam/config.yml` automatically — no hand-editing required. Adapter-specific config hints (gizmos app name, cloud-run project/region/service) are included as comments. Unknown adapter names are rejected at init time with a clear error listing valid choices.

- **`devteam init` writes managed `.gitignore` block (Phase 12.1).** Running `devteam init --host <x>` now writes (or updates) a `# BEGIN stagecraft` / `# END stagecraft` block in the project's `.gitignore`, covering all volatile pipeline files (`run.lock`, `run-state.json`, `run-log.jsonl`, `logs/`, `gates/archive/`, `gates/replay/`, `dispatches/`, `memory/`, and their `pipeline/changes/*/` counterparts). The block is the canonical list from ADR-010; subsequent runs are idempotent (skipped if identical, updated if outdated). Operators on existing projects can run `devteam init --host <x>` without `--force` to migrate. Honest scope note: the block covers Stagecraft-owned volatile files; application source files and other project-specific ignores remain the operator's responsibility.

- **Liveness heartbeat + observe-only stall detector — Phase 11.1 (ADR-007 Tier 1).** The driver now emits a `heartbeat` event to `run-log.jsonl` (and via `onEvent`) at the **start of every loop iteration**, before `next()`, so the last-event age is always bounded. Alongside each `run-stage`/`continue-stage` dispatch an **observe-only stall probe** runs fire-and-forget: it wakes every 60 s and emits `stall-detected` (with `stall_class: "observed"`) if neither the workstream log (under `pipeline/logs/`) grew ≥ 512 bytes nor any gate updated within 5 minutes. The dispatch is **never killed, no `Promise.race` fires** (Tier-1 observe-only; the probe self-cancels via a `cancelled` flag when the dispatch settles, preventing stale events). Config: optional `autonomy.stall_threshold_ms` (default 300000) and `autonomy.stall_min_growth_bytes` (default 512) in `.devteam/config.yml`. The probe detects silent hangs only — loop-spew (repetitive output that resets the clock) rides with ADR-007 Tier 2. New read-only **`devteam status`** command reads `run-state.json` + tail of `run-log.jsonl` and reports `status / current_stage / last_action / iterations / cost_usd / last_heartbeat_age_ms / last_event_age_ms / stall_detected`. Docs: "No heartbeat" removed from `docs/runbooks/autonomous-run.md` Honest Limitations; replaced with a full liveness section (heartbeat, stall probe, `devteam status` fields, observe-first note); `devteam status` added to help text. Tests: 4 new tests in `tests/run.test.js` (heartbeat every iteration, stall-detected on flat log+gate with injected clock, no stale event after dispatch settles, no kill on stall) and 1 new `tests/status.test.js` file (ages from fixture log). Suite: 1702 pass, lint clean, consistency green (318 checks).

- **New: `npm` deploy adapter** (`core/deploy/npm.md`). Stage 8 can now publish Node.js packages to an npm registry. The adapter runs `npm pack --dry-run`, verifies artifact scope (accepts both `"files"` whitelist and `.npmignore`), checks for **actual populated credentials** by reading file contents rather than pattern-matching on filenames, bumps version-conflict detection, and smoke-tests the published tarball with `npm install --dry-run`. Fixes the false-positive credential blocker (B2) that caused the commit-gen deploy to escalate. Fixes #231.

- **`--repair` diagnosis stage — Phase 10.2 (ADR-009 Phase 2).** When `intent === "repair"`, stage-01 (requirements) produces a **DIAGNOSIS** document instead of a feature brief — same stage id, same gate file path, fix-aware artifact. Zero new stages, zero parallel pipeline. Concretely: (1) `repairOverride` field added to the `requirements` stage definition in `core/pipeline/stages.js`; when `intent === "repair"`, `buildDescriptor` (orchestrator) merges the override on top of the base definition — swapping objective, artifact (`pipeline/diagnosis.md`), template (`diagnosis-template.md`), `allowedWrites`, and gate schema. (2) The diagnosis gate is always ESCALATE-shaped (`escalation_reason` + `decision_needed`) — a judgment gate requiring human approval or `--auto-rule diagnosis-approved` before the build proceeds. (3) `intent` is propagated through `ctx` in `runStage()` so adapters render repair-mode prompts correctly. (4) Driver (`core/driver.js`): `repairNeedsDiagnosis = intent === "repair" && !repairAtRaw` prepends `"requirements"` to the effective stage order so `next()` routes through it before build; the diagnosis gate is read before each build dispatch and its `affected_files` list activates 10.1's structural scope gate (previously inert) by populating `state.affectedFiles`; `repairPatchItems` upgrades from the raw symptom string to structured per-file entries from the diagnosis. (5) **`--repair-at <file>:<line>` escape hatch**: comma-separated `file:line` locations seed `state.affectedFiles` directly, write a synthetic PASS stage-01 gate, and skip the LLM diagnosis dispatch entirely — for cases where the caller already knows the defect location. (6) `diagnosis-approved` is the new ruling class slug; granted via `--auto-rule diagnosis-approved`. (7) `templates/diagnosis-template.md` added. CLI reference regenerated. Tests (6 new in `tests/repair-mode.test.js`, section 7): `buildDescriptor` repair shape (unit); `buildDescriptor` feature shape unchanged (unit); scope gate activates from diagnosis gate `affected_files` without `opts.affectedFiles` (this test fails on main without 10.2 — the activation boundary); diagnosis ESCALATE halts without `--auto-rule`; `--auto-rule diagnosis-approved` proceeds; `--repair-at` escape hatch seeds, writes synthetic gate, skips dispatch. Suite: 1661 pass, lint clean, consistency 317 checks passed.

- **`--repair "<symptom>"` intent flag — Phase 10.1 (ADR-009 Phase 1).** Adds `--repair` to `devteam run` as an intent flag orthogonal to `--track`, implemented as fix-aware wiring on existing stages — zero new stages, zero parallel pipeline. Concretely: (1) `--repair` and `--feature` are mutually exclusive (enforced in both the CLI command and the driver); (2) `--repair` defaults to `hotfix` depth; `--repair --track full` overrides; auth/payments/migration symptoms are upgraded to `full` via the same stoplist patterns (`checkStoplist`) regardless of the default — the existing lighter-track stoplist bypass does not apply here; (3) `intent: "repair" | "feature"` is written to `run-state.json` and every run-log event base object from day one (ADR-009 §Decision.7 perishable baseline — without this, repair vs feature runs are indistinguishable in history); `repair: <symptom>` string is also persisted in run-state; (4) on `--resume`, a `prior_run_id` correlation field is written linking the re-run to its predecessor's `started_at`; (5) `changeIdFromSymptom` exported from `core/config.js` (same slug algorithm as `changeIdFromFeature`) so bounded-isolation paths can derive the changeId from a symptom string (ADR-009 §Consequences); (6) repair builds dispatch `runStageHeadless` with `patchItems` set to the symptom string, activating `renderPatchBlock`'s `## ⚠️  PATCH MODE — targeted fix only` block in the build prompt — no new prompt authored (ADR-009 §Decision.2, PATCH MODE is the existing mechanism); (7) structural scope gate wired behind `opts.affectedFiles`: if present, a post-build `checkScopeGate` call (injectable for tests; default: `git diff --name-only HEAD`) fails the run with `halt_action: "scope-gate"` when files outside the list were touched — inert in 10.1 (no diagnosis yet), activated by 10.2's affected-files contract; peer-review criteria gain "could this be smaller?" as a judgment on top of the mechanical boundary. CLI reference regenerated (`npm run docs:generate`). Tests (14 new in `tests/repair-mode.test.js`): mutual exclusion (both CLI and driver-level); hotfix default; `--track full` override; auth-symptom stoplist upgrade with event emission and run-log verification; intent tag in run-state and run-log; feature run intent tag; resume prior_run_id correlation; repair build patchItems dispatch; feature build lacks patchItems; `renderPatchBlock` unit check with symptom text; scope gate FAIL with synthetic affected-files list; scope gate PASS within scope; scope gate inert without affectedFiles. Suite: 1655 pass (was 1641), lint clean, consistency 317 checks passed.

  Honest scope note: The structural scope gate is mechanically inert in 10.1 — no affected-files list is supplied because 10.2's diagnosis stage (which produces it) has not shipped yet. The ADR-009 Phase 1 must-not-ship-without-Phase-2 rule (`plans/phase-10-repair-mode.md §10.1`) applies: 10.1 should be merged together with 10.2 so the scope gate has an actual contract to enforce.

- **`--repair` reproduction stage — Phase 10.3 (ADR-009 Phase 3).** When `intent === "repair"`, stage-03b (executable-spec) is injected immediately before `build` in the effective stage order — even on hotfix depth, which previously skipped it entirely. The stage author writes a failing-first Gherkin Scenario that exercises the defect so the regression test is RED before the fix and GREEN after. Concretely: (1) `repairOverride` added to the `executable-spec` stage definition in `core/pipeline/stages.js` — swaps objective to failing-first bug reproduction, swaps `readFirst` to include `pipeline/diagnosis.md`, and adds a tri-state `reproduced` gate field (`true` / `false` / `"unverifiable: <reason>"`). (2) Driver (`core/driver.js`): for repair intent, filters `executable-spec` out of the base track list and re-injects it at the position immediately before `build`; `--repair-at` escape hatch still includes the reproduction stage (skips diagnosis only); full-track runs are filtered before re-inject to prevent double-injection. (3) `stampStage03b` in `core/verify/stamp.js`: if `gate.reproduced` is unverifiable, emits a loud `WARN reproduction-unverifiable` into `gate.warnings` and records `{ unverifiable: true, reason }` in `stamp.runs.reproduction_pre_build` — no blocker; if `true` or `false`, runs the configured test command and captures the pre-build baseline (`reproduction_pre_build`). (4) `stampStage04a` in `core/verify/stamp.js`: reads `stage-03b.json`, compares pre-build vs post-build test results, writes `reproduction_verification` (`red_before_confirmed`, `green_after_confirmed`, `finalized_at`) and finalizes `reproduced` on the stage-03b gate file on disk — verification is orchestrator-observed, not agent-asserted. (5) `core/gates/schemas/stage-03b.schema.json`: optional `reproduced` property added (tri-state `oneOf`), not in `required` so feature runs continue to satisfy the schema skeleton test. Tests: 7 new in `tests/repair-mode.test.js` (section 8 — stage order injection, adjacency, double-inject safety, escape-hatch inclusion, `buildDescriptor` repair/feature modes) and 8 new in `tests/verify-stamp.test.js` (stampStage03b tri-state, stampStage04a red→green finalization). Suite: 1676 pass, lint clean, consistency 317 checks passed.

- `devteam restart requirements [--cascade]` now also deletes `pipeline/brief.md` so a follow-on `devteam run --feature "..."` or `devteam stage requirements --feature "..."` starts completely fresh without manual cleanup.

## `devteam run --auto-commit` (Phase 12.3)

**New flag:** `--auto-commit` on `devteam run`

When passed, the driver automatically commits pipeline artifacts after a clean
halt — using the same algorithm as `devteam commit`, with no interactive
confirmation prompt.

**"Clean halt"** is defined as `halt_action` in `{"ceiling", "until", "budget"}`:
the halts where the driver stopped by design, not because something broke.
Non-clean halts (`fix-and-retry`, `resolve-escalation`, `structural-input`,
etc.) do **not** trigger auto-commit.

**Behaviour:**
- Calls `runCommit(cwd)` (the programmatic export of `devteam commit`) after
  the driver returns. Prints the list of committed files to stderr.
- If there is nothing to commit (cursor already current), logs
  `{"event":"auto-commit-skipped","reason":"nothing-to-commit"}` and moves on.
- On commit success, logs `{"event":"auto-commit","staged_files":[…],"commit_hash":"…"}`.
- On commit failure, logs `{"event":"auto-commit-failed","reason":"…"}` and
  emits a loud stderr warning. The run's exit code is **not** changed — a git
  failure does not retroactively change the pipeline halt semantics.

**New export:** `runCommit(cwd)` from `core/cli/commands/commit.js` — the
programmatic interface for unattended commits (no prompt, returns a result
object rather than calling `process.exit`).

**Honest scope note:** auto-commit operates in in-place mode (changeId null),
consistent with Phase 12.2. Bounded-workspace support is a follow-on item.

## feat(track-provenance): pipeline/track.json + confidence guard (ADR-006, Phase 11.3)

**`devteam assess` writes `pipeline/track.json`** (per-run inference record) by default.
`--confirm` sets `source:"human"`. `--apply` continues to write `custom_stages` to
`.devteam/config.yml` (no breaking change).

**`resolveTrack`** now reads `pipeline/track.json` in precedence:
```
--track  >  pipeline/track.json  >  custom_stages  >  default_track  >  "full"
```
Returns `{track, source, confidence}` so the confidence guard below can apply.

**`autonomy.require_confirmed_track`** (new config flag, default `false`): when on,
an inferred `pipeline/track.json` at medium or low confidence produces an
`unconfirmed-track` halt requiring `--track` or `--force`. High confidence proceeds.
When off (default), an inferred track emits a warn-once line to stderr, never blocks.
The flag is NOT keyed on `CI=true` (which is already overloaded by the validator and
verify runner) — CI pipelines opt in explicitly.

**`run-log.jsonl`** gains a `run-start` event at the top of every run, carrying
`track_source` and `track_confidence` for provenance auditing. A
`track-confidence-check` event is logged whenever the guard runs.

Honest scope note: the guard covers `pipeline/track.json`-based provenance. A run
with no `track.json` falls through to `custom_stages` / `default_track` (source:
`"config"`) — those are explicit project-wide choices and not subject to the
confidence guard.

---
type: fix
---

- `AC_SECTION_RE` in `extractAcsFromBrief` now accepts any single-token section prefix before "Acceptance Criteria" (`§3`, `3.`, `3`, etc.), not just the `§N` style. Briefs using `## 3. Acceptance Criteria` no longer fall through to a whole-document scan that misidentifies cross-section AC references as duplicate definitions.
- The drift blocker message now includes `duplicate_criteria` count and ids when duplicates are the cause, making the failure self-explanatory without requiring a read of the gate file.

- **Fix: `devteam advise --apply` now correctly handles item IDs containing commas.** The parser previously split the entire `--apply` value on every comma, fragmenting long item IDs that contain commas and emitting "Unknown item id" errors for each fragment. It now accumulates fragments until it finds a complete `id=letter` selection boundary, making comma-containing IDs work as expected.

- **Fix: `devteam advise` no longer duplicates item text or prints an unparseable Apply hint.** When a `noted_for_followup` entry was a plain string without a short `ID:` prefix, the item label printed the full text twice (separated by ` — `) and the `Apply:` hint was missing shell quoting, making it impossible to run. Both are now corrected in `core/cli/commands/advise.js`.

- **Fix: `devteam advise` option descriptions now show the correct `--apply` option letter and quote long item IDs.** The ticket hint in `generateOptions` hardcoded `=B:PROJ-XYZ` for all classifications, but `PEER_REVIEW_RISK` items have `defer` as option A — the hint now uses the correct letter per call site. Item IDs containing spaces or shell-unsafe characters are also now single-quoted in the hint.

---
type: fix
---

- `extractAcsFromBrief` now parses AC definitions written in bold markdown format (`**AC-1** — description`) in addition to the existing bare and bullet-prefixed forms.
- Extraction is scoped to the `## [§N ]Acceptance Criteria` section when a heading is present, preventing AC references in other sections (e.g. Observability notes) from being counted as duplicate definitions. Falls back to whole-document scan for headerless briefs.

- **Fix: three bugs that forced manual `run-state.json` edits after `convergence-exhausted`.** (1) `detectNoSourceChange` in `core/gates/convergence.js` now early-returns `false` when any blocker-referenced file is unreadable, instead of hashing its content as `""` — the SHA-256 of `""` (`e3b0c44…`) made two consecutive missing-file iterations look identical and tripped the no-source-change halt prematurely. (2) `core/driver.js` now rewrites the failing gate to `status: "ESCALATE"` with `escalation_reason` and `decision_needed` when convergence-exhausted fires, so the state is visible in the gate file rather than only in `run-state.json` and `run-log.jsonl`. (3) `devteam restart <stage>` now clears `fixRetries[stageName]` from `run-state.json` so re-running after a convergence-exhausted restart doesn't immediately re-halt. Fixes issue #195.

- **Three ephemeral pipeline txt files added to the canonical `.gitignore` block.** `devteam init` now writes `pipeline/lint-output.txt`, `pipeline/pre-review-output.txt`, and `pipeline/changed-files.txt` (plus their `pipeline/changes/*/` bounded-mode counterparts) to the managed Stagecraft block. Projects on the old block pick up the new entries automatically on the next `devteam init` run (no `--force` needed). These files were previously listed as "optional" in `docs/git-workflow.md`; they are now correctly marked as ephemeral and excluded from git.
- **`docs/git-workflow.md` commit-coverage corrections.** Two entries in the "Recommended commit points" table incorrectly claimed `devteam commit` stages `pipeline/context.md` (Stage 1) and `pipeline/adr/` (Stage 2). Neither path is in the stage-artifact registry — both must be staged manually. The table now reflects this, and a `devteam compact` reminder is added for `context.md`. The prose note below the table is updated to name both exceptions explicitly.

- **Fix: `gizmos whoami` replaced with `GIZMOS_API_KEY` env check in `core/deploy/gizmos.md`.** `gizmos whoami` is not a real CLI command. Authentication is via the `GIZMOS_API_KEY` environment variable — a missing or empty value causes `gizmos push` to fail with a 401. Both the `## Assumptions` line and Precondition step 1f now reflect the correct auth mechanism.

- **Fix: `devteam help` now lists all current commands.** `devteam commit`, `devteam hook`, and `devteam advise` (shipped in Phases 11–12) were missing from the help output entirely. The `devteam run` synopsis was also missing `--auto-commit`. All four gaps are now documented in `core/cli/commands/help.js`.

- **Fix marker-section replacement when an end marker is missing.** Stagecraft now uses the shared marker helper for `context.md` blocker/advisory upserts and preserves surrounding content when a managed section has an orphaned begin marker instead of silently slicing the file at the wrong offset.

- `devteam next` now reads the active track from `pipeline/run-state.json` (written by `devteam run`) so it sequences against the correct track instead of always falling back to the full track. A new `--track` flag allows manual override. Fixes #220.

- **Fix: red-team (stage-04c) now writes a stub gate before the adversarial walk, preventing structural-input halts on context-exhausting runs.** On thorough runs (10 surfaces walked, many carried findings), the report narrative could exhaust the context window before the gate write, leaving no `pipeline/gates/stage-04c.json` and causing the orchestrator to halt. The role now lists the gate before the report in `## Writes`, adds a Step 0a that writes a minimal valid stub immediately after surface scoping, and makes the report explicitly last. Fixes #181.

- **Fix: red-team (stage-04c) context-exhaustion halt now retries instead of halting with structural-input.** The driver pre-seeds a `_stub: true` gate before dispatch; `headless.js` detects whether the LLM overwrote it; if not (context exhausted before the gate write), `classifyDispatch` treats the outcome as transient rather than structural-input, giving one retry. Fixes the regression introduced when PR #182's prompt-only Step 0a instruction was silently skipped by the LLM. Fixes #181.

---
type: fix
---
- `devteam restart --cascade` now deletes downstream artifact files (e.g. `brief.md`, `spec.feature`, `test-report.md`) in addition to gate files. Previously, stale artifacts from a prior feature run would cause false drift on the next run.

- **Fix spec-drift false-positive when brief prose references an AC from a prior build.** Stage-03b was escalating with `orphan_criteria=[AC-N]` when a brief mentioned an acceptance criterion number in a cross-reference (e.g. "all existing AC-1 through AC-12 continue to apply") and word-wrap happened to place that identifier at the start of a line. Two root causes fixed:
  - `core/spec/verify.js` `AC_LINE_RE`: the separator character (`—`, `:`, `.`) after the AC number was optional (`[.:\-—]?`), so `AC-12 from the initial build...` matched as a definition. Separator is now required — prose cross-references never have one immediately following the number, while every defined AC always does.
  - `core/verify/stamp.js` `extractAcsFromBrief`: used an independent global-scan regex `/(?:^|\s|\*|`)AC-(\d+)\b/g` that matched `AC-N` anywhere in the document regardless of line position. Replaced with a delegation to `core/spec/verify.js`'s section-scoped, line-anchored implementation so both the orchestrator and the CLI display use the same extraction logic.
- Regression tests added to `tests/spec-g2.test.js` and `tests/verify-stamp.test.js` covering the word-wrap false-positive scenario.

---
type: fix
---
- `stampStage03b` no longer runs the test-report alignment check (that belongs to stage-06). A stale `pipeline/test-report.md` from a prior feature run no longer causes `drift: true` in the spec-authoring gate.
- `stamp.runs.spec_verify` now records `orphan_in_tests_count` and `unknown_in_tests_count` so drift is never opaque.

- Targeted autonomous fix retries at the owning build workstream when a failed gate names exactly one build workstream and blocker context.

- Harden the pipeline dashboard against model-authored HTML injection, add a restrictive content security policy, and clean up heartbeat timers when UI servers close.

- **`devteam init --profile dogfood` writes four dogfooding safeguards (Phase 14.1).** Running `devteam init --host <x> --profile dogfood` now writes a supplemental `# BEGIN stagecraft-dogfood` gitignore block covering generated pipeline documents (`brief.md`, `context.md`, `spec.feature`, `runbook.md`, `test-report.md`, `code-review/`, and their `pipeline/changes/*/` counterparts), installs a pre-commit hook that blocks accidental commits to `core/`, `bin/devteam`, `pipeline/stages/`, `roles/`, or `rules/`, adds `pipeline/stages/deploy.md` to `.git/info/exclude`, and writes a `profile: dogfood` marker to `.devteam/config.yml`. All writes are idempotent — re-running the command skips already-correct state.

## Improvements

- Lazy-load CLI command modules in `bin/devteam` so command startup only requires the selected command handler.

## Unreleased

- Marked live streaming headless output as shipped in the backlog.

- Prevent out-of-scope build and review workstreams, detect additional structural defects before peer review, and halt when an escalation applicator fails to dispatch the ruled build workstream.

Added pluggable host adapter discovery for installed `@devteam/host-*` packages.

- **`devteam preflight` now blocks PRs that contain staged pipeline artifacts (Phase 14.3).** A new check in `core/preflight.js` runs `git diff --cached --name-only` and emits a BLOCKER if any file matching the artifact prefix list (`pipeline/brief.md`, `pipeline/gates/`, `pipeline/code-review/`, etc.) appears in the git index. Applies to all projects, not just dogfood mode. Run `git restore --staged <files>` to clear the blocker.

## Fixes

- Implemented the advertised `devteam replay --restore-backup` recovery mode so leftover replay backups can be restored without manually copying files.

- **feat(driver):** emit a two-line stderr warning when `devteam run` starts without `--budget-usd`, so operators know the run will not halt on spend (Phase 14.4).

- Extend consistency checks to prevent drift in schema field vocabulary, Node and platform support claims, and volatile test totals in current maintainer documentation.

- Added a machine-readable `file_ownership` map to the Stage 2 design gate so later auto-fix routing can identify the Stage 4 workstream that owns a blocker-named file.

- Enforce targeted build fix dispatches by halting when the named blocker files
  are unchanged despite a successful retry.

## Unreleased

- Fixed headless command parsing so quoted arguments and executable or script paths containing spaces survive dispatch, escalation, a11y remediation, and doctor diagnostics.

## Unreleased

- Replaced POSIX-only gate clear commands in fix-step guidance with portable Node commands.

- Add native Windows CI coverage for command parsing, executable discovery, timeout termination, initialization, diagnostics, and CLI startup.

## Unreleased

- Made `devteam doctor` find Windows executables via semicolon-delimited PATH entries and PATHEXT candidates.

## Unreleased

- Made timeout termination use Windows-friendly process killing while preserving POSIX SIGTERM/SIGKILL escalation.

---

## [0.7.0] — 2026-06-14

### Fixed

- **PM role can't follow its own brief — Phase 6.2** (closes the pm/shell contradiction). `roles/pm.md`'s stage-03b procedure previously instructed the pm to run `devteam spec generate` and `devteam spec verify`, but pm's declared tool budget is `Read, Write, Glob` — no Bash. Under claude-code's native enforcement the pm subagent cannot execute its own brief. Solution: (1) `core/verify/stamp.js` gains `stampStage03b()` — the orchestrator now runs spec generation (if `spec.feature` is absent) and drift verification via `core/spec/verify.js`, stamping all spec-related gate fields (`criteria_count`, `scenarios_count`, `criteria_to_scenario_mapping`, `all_criteria_mapped`, `orphan_scenarios`, `orphan_criteria`, `drift`) with model-said vs observed in the same pattern as stage-04a/06. `stage-03b` is added to `STAMPABLE_STAGES`; (2) `roles/pm.md` stage-03b procedure rewritten — pm now authors ACs and fills in Given/When/Then directly via Write; the orchestrator handles generation and verification; no shell commands in the procedure. Rejected alternative (grant pm Bash): verification belongs to the orchestrator, not to the agent self-certifying; (3) `scripts/consistency.js` gains a new check class `role-budget-brief`: any `Run \`devteam <subcommand>\`` instruction in a role brief whose tool budget lacks Bash is flagged as a violation, catching the next budget/brief contradiction mechanically. Check applies to `roles/*.md`; informational references (no leading "Run") are not flagged. Tests (13 new): `tests/verify-stamp.test.js` — stampStage03b happy path with all gate fields verified, status flip to FAIL on drift with model_said vs orchestrator recorded, scaffold generation when spec.feature absent, graceful skip when brief.md absent, model_said capture on count mismatch, stamp() dispatch round-trip; `tests/consistency-meta.test.js` — checker fires on pm fixture with "Run `devteam` " instruction, passes on qa fixture with Bash, passes on pm fixture with informational reference (no "Run"), real roles/ regression guard after pm.md rewrite. Suite: 1562 pass (was 1552), lint clean, `npm run consistency` 313 checks passed.

  Honest scope note: `stampStage03b` reads `pipeline/brief.md` and `pipeline/spec.feature` from the standard (non-bounded) pipeline path; bounded-mode support follows the same B9 exemption pattern as `stampStage04a`. The checker targets `Run \`devteam` patterns only — other shell invocation verbs ("Execute", "Invoke") would require a separate pattern addition.

- **DAG-derived gate invalidation — Phase 5.1** (closes the #109 class generalized). Fix recipes previously hand-listed `clear_gates` entries per stage; when the stage-06d recipe cleared stage-04 workstream gates and re-dispatched build, stage-05 (peer-review) and stage-06 (QA) PASS gates were left standing — rewritten code re-entered verification without passing peer-review or QA again. Solution: a new `core/pipeline/invalidation.js` helper, `derivedClearGates({ rootStageId, failingStageId, stageList, gatesDir, changeId })`, computes which downstream attestation gates must be cleared by walking the ordered stage list between the cleared root and the failing stage and checking which gate files actually exist on disk. Recipes now declare only the root stage(s) they clear; `derivedClearGates` adds every intermediate gate automatically. The helper is changeId-aware (`prefixPipelineRelative`) for bounded-mode compatibility (Phase 5.4). `core/orchestrator.js` passes `stageList` and `changeId` from `_nextImpl` into every `diagnose()` call. Affected recipes: stage-04a, stage-04c, stage-05 (code-changes path), stage-06, stage-06b (path 2 only), stage-06d. The hand-listed `"pipeline/gates/stage-04a.json"` entry is removed from `buildGatePaths` and derived automatically. Chain re-stamping invariant: cleared downstream gates are re-stamped by `runStageHeadless` and `mergeWorkstreamGates` when each stage re-runs; the driver guarantees re-execution before `next()` advances past the cleared stage. Tests (17 new): `tests/invalidation.test.js` — `derivedClearGates` unit tests (empty-stageList, empty-gatesDir, same-stage, existing-only, workstream regex correctness, changeId prefix, full-range); integration tests verifying the primary fix (stage-06d clear_gates now includes stage-05 — this test failed on main before Phase 5.1); after-clearing test confirming next() re-demands pre-review; registry meta-test asserting no recipe hand-lists an intermediate gate without stageList.

  Honest scope note: `derivedClearGates` returns `[]` when `stageList` is absent (e.g., direct recipe unit tests without the new ctx fields) — safe for old callers. The driver always receives `stageList` via `_nextImpl`, so production behavior is complete.

### Added

- **Model-facing token budget program** (D5 of documentation-plan.md). Implements a measured, auditable token budget for the framework prose loaded at every agent dispatch. Four deliverables: (1) `scripts/prompt-budget.js` — computes per-stage max-dispatch bytes from `readFirst` framework files (`AGENTS.md`, `rules/*` mapped from `.devteam/rules/`, and the role brief for each dispatched role; `pipeline/*` project artifacts excluded) and writes `docs/reference/prompt-budget.md` (fenced with `<!-- generated: do not hand-edit -->` markers, machine-readable `<!-- budget-data -->` block for CI advisory comparisons). At 22 dispatched stage-role combinations: framework bytes are consistently 11,785 B across all stages; heaviest dispatch is platform/build/pre-review/sign-off/deploy at 27,402 B (~6,851 tokens); (2) CI advisory in `scripts/consistency.js` (`checkPromptBudgetSync`) — two non-blocking advisories: staleness (committed file ≠ fresh generator output, distinct from the blocking fail used for stages-ref/hosts-ref/cli-ref because the budget file is informational, not a correctness guarantee) and budget-growth (any stage's fresh max-dispatch bytes grew >10% above the numbers stored in the committed file — fires when rules/ or roles/ grow between `docs:generate` runs); (3) per-file ceiling advisories in `scripts/consistency.js` (`checkFileSizeCeilings`) — non-blocking: role brief ≤ 16 KB (no current violations), stage rule file ≤ 8 KB (`rules/stage-05.md` at 9,985 B exceeds ceiling — advisory fires, file not edited), `AGENTS.md` ≤ 10 KB (4,145 B, comfortable headroom); (4) `scripts/prompt-budget.js` also added to `scripts/docs-generate.js` so `npm run docs:generate` regenerates all four reference files atomically. Tests: `tests/prompt-budget.test.js` (16 tests) — generator importable without side-effects, computeStageStats completeness and correctness, generateBlock idempotency and structural markers, parseCommittedBudget round-trip, advisory fires on synthetic >10% growth (meta-test), advisory absent when numbers match, stage-05.md ceiling violation fires in full-repo run, role-brief ceiling regression guard, committed file matches generator. Suite: 1469 pass (was 1453), lint clean, `npm run consistency` 312 checks passed with 1 known advisory.

  Honest scope note: The budget is computed from framework files only (rules/ + roles/ + AGENTS.md); it does not include skill files (skills/\*.md) loaded on-demand by some stages, nor the stage-specific rule files (rules/stage-NN.md) that are currently not in any `readFirst` array (they serve as human reference for the gate schemas). The budget-growth advisory compares fresh numbers against the numbers in the committed file from the last `docs:generate` run — it fires when content grew and regeneration hasn't happened yet. The ceiling for stage rule files (8 KB) is advisory only; `rules/stage-05.md` at 9,985 B already exceeds it.

- **Audience-based documentation map** (D2 of documentation-plan.md). Replaced the flat 30-doc list in README's "Documentation map" with four reader-path tables (Evaluator / Operator / Contributor / Model), each with an ordered 3–5 doc core trail and a one-line purpose per doc. Every previously-mapped doc is assigned to exactly one path; 8 docs not previously in the map (BACKLOG.md, TESTING.md, adr/README.md, autonomous-execution-design.md, brief-template.md, design-spec-template.md, GAP-ANALYSIS.md, runbook-template.md) are now included. Created `docs/README.md` with the same four paths restricted to files under `docs/`. Created `docs/runbooks/README.md`: a 24-row troubleshooting index mapping symptom → runbook section (with deep-link anchors) sourced from all five runbooks. Extended `scripts/consistency.js` with check 7 (`docs-index`): every `.md` file under `docs/` (excluding `historical/`, `audit-archive/`, `reference/`, and `audit/`) must be linked from `docs/README.md` — directly or via a parent directory's `README.md` — so orphan docs fail CI. Added 8 meta-tests for the new check in `tests/consistency-meta.test.js`.

  Honest scope note: `docs/audit/` is excluded from the orphan check (generated output); `docs/adr/*.md` individual files are covered by the `adr/README.md` directory-index link rather than individually linked entries. The "~30 lines" target for `docs/README.md` was not achievable while covering all 40 docs — the file is ~55 lines.

- **docs(adr):** Sync `docs/adr/README.md`: add ADR-006 (track inference under autonomy, Proposed); correct ADR-004 status from Proposed to Accepted (the ADR file itself already said Accepted); add a "Deferred" subsection documenting that ADR-005 (standing grants), ADR-007 (heartbeat/liveness), and ADR-008 (exit semantics) are identified in `plans/phase-4-capability-roadmap.md §4.4` as intentionally deferred — the gap in numbering is deliberate and now recorded in the index.

- **docs(runbook):** Add stale-archive symptom to `autonomous-run.md`: the no-progress breaker compares archive files from `pipeline/gates/archive/`; archives surviving from a prior run (pre-Phase-5.2 or a run that ended without `devteam restart`) can cause a false-positive convergence-exhausted escalation on the very first retry of a new run. Documents the `rm -rf pipeline/gates/archive/` recovery step for operators upgrading from older versions.

- **docs(runbook):** Rewrite `escalation.md` §4c to the archive-based convergence-exhaustion reality: the driver derives exhaustion from `pipeline/gates/archive/` diffs (not from an agent-falsifiable `retry_number` field), the default ceiling is 2 retries, and `no_progress_evidence` in `run-log.jsonl` carries the operator-readable evidence. Fix two dead TOC and §0 anchors that still pointed to the pre-drift-sweep `#4b` heading.

- **docs(runbook):** Sync `fix-and-retry.md` to shipped behavior: (a) update `convergence-exhausted` framing from pure retry-budget to budget-or-no-progress (archive-diff breaker); (b) rewrite Case 7 accessibility to the three-path recipe shipped in Phase 6.4 (`fix-recipes.js`): Path 1 prior-stage advise IDs, Path 2 gate-blocker rebuild, Path 3 no-blocker advise panel — removes the "always frontend" claim; (c) new Case 12 for license-gate FAIL (`license_check_passed: false`) documenting the replace-dependency vs allowlist-policy split (neither is `--patch`); (d) new Case 13 for tool-budget denial covering native claude-code refusal vs advisory non-compliance on prompt-only hosts; (e) add #109 stage-04a note to Cases 4 and 5 manual-recovery paths (must clear `stage-04a.json` when hand-clearing build gates). Index rows added to `runbooks/README.md`.

- **docs(rules):** Rename example ADR IDs in `rules/stage-02.md` gate JSON from `ADR-007`/`ADR-012` to `PADR-1`/`PADR-2` (project ADR namespace) to avoid collision with the Stagecraft framework's own ADR namespace (`docs/adr/`). Add a clarifying half-sentence explaining the PADR-N convention.

- **docs(tracks):** Add `devteam assess` sentence and link to `docs/tracks.md §Choosing a track` — the doc that explains how to pick a track never mentioned the command that automates the choice. Links to `ADR-006` for the `pipeline/track.json` track-record design.

- **docs(adr):** Draft ADR 004 — Role tool budgets (G10). Proposes formalising the existing `tools:` field in `ROLE_FRONTMATTER` as the per-role tool-budget declaration, adding `enforces.tool_budget: "native" | "prompt-only"` to each host's `capabilities.json` following the C1 pattern, recording `dispatched_tool_budget` on workstream gates, and deferring an MCP mediation server in favour of host-native tool pinning ("ship the seam, not the server"). Status: Proposed — awaiting reviewer sign-off on three open questions (warn vs block for prompt-only hosts, cross-host tool-name translation, canonical budget location). (plans/phase-4-capability-roadmap.md §4.1)

- **docs(adr):** Draft ADR 006 — Track inference under autonomy (plans/phase-4-capability-roadmap.md §4.4). Proposes `pipeline/track.json` as an explicit per-run track record written by `devteam assess --apply`, consumed by `devteam run` between `--track` and the `custom_stages` config fallback. Key rules: the driver MUST NOT call `assess` internally (inference must be operator-visible); inferred tracks at medium/low confidence halt in CI (`CI=true`) with `halt_action: "unconfirmed-track"`; `"human"` source is always silent. Stoplist (Phase 1.1) remains the floor; this ADR is the ceiling. Status: Proposed — five open questions for reviewer ruling (assess --apply migration path, interactive-pause vs always-halt at low confidence, gitignore policy, confirm-track command surface, standing-grant interaction with ADR-005).

- **D3.2 — Generated CLI reference (documentation-plan.md D3 sub-item 2).** Added `scripts/generate-cli-ref.js`, which emits `docs/reference/cli.md` — a full `devteam` command reference generated from the per-command flag schemas in `core/cli/commands/`. For each of the 31 commands (in registry order matching `bin/devteam`), the output contains: a synopsis line, a one-line description, and a flag table derived from the schema (flag name, type, description). Output is fenced with `<!-- generated: do not hand-edit -->` markers, consistent with D3.1/D3.3.

  Extended `scripts/docs-generate.js` to include the CLI ref as the fourth generator target; `npm run docs:generate` now writes all four outputs (tracks matrix, stages ref, hosts ref, CLI ref) in one pass. Extended `scripts/consistency.js` with a new `checkCliRefSync()` check (`cli-ref`) that fails CI when the committed file diverges from regenerated output — same pattern as the `stages-ref` and `hosts-ref` checks. Added 4 tests to `tests/consistency-meta.test.js`: committed-file sync (real-repo), import-without-side-effects, simulated-hand-edit proof, and the task-required sampled-command test (both `devteam run` and `devteam next` flag schemas: every flag name from the schema appears in the generated doc — agreement by construction).

  **Duplication sweep (step 2):** Grepped `devteam ` code blocks across all non-excluded `docs/` files and runbooks. Finding: no flag or command enumeration tables exist outside the generated file. Every `devteam --flag` reference in the corpus is a procedure example (code block teaching a workflow) or a feature description — both stay under the judgment rule (procedure beats reference). No content was converted to links.

  Honest scope note: Synopsis strings and command descriptions live in the generator itself (`COMMANDS` array in `generate-cli-ref.js`), not in the command modules — the flag schemas in `core/cli/commands/` remain the authoritative source for flag metadata. If a new command is added without an entry in the generator's `COMMANDS` array, the CLI reference will silently omit it; a future check could enforce that every file in `core/cli/commands/` has a matching entry. (closes BACKLOG D3 sub-item 2)

- **D3 — Generated reference docs (stages + hosts, D3.1/D3.3/D3.4 of documentation-plan.md).** Added two documentation generators and their consistency checks, completing the "generate, don't transcribe" principle for the two biggest sources of prose drift.

  New generators: `scripts/generate-stages-ref.js` emits `docs/reference/stages.md` — a full stage table (ID, name, roles, conditionalOn, gate files, artifact, template) derived from `STAGES`/`ORDERED_STAGE_NAMES` in `core/pipeline/stages.js`, grouped by phase. `scripts/generate-hosts-ref.js` emits `docs/reference/hosts.md` — a capability/enforcement matrix derived from `hosts/*/capabilities.json`, covering all four host adapters. `scripts/docs-generate.js` orchestrates all three generators (tracks matrix, stages ref, hosts ref); `npm run docs:generate` is the single entry point. Outputs are fenced with `<!-- generated: do not hand-edit -->` markers.

  Extended `scripts/consistency.js` with two new checks (`stages-ref`, `hosts-ref`) that verify the committed files equal regenerated output — drift from a hand-edit or a stages.js change fails CI. Added 6 meta-tests in `tests/consistency-meta.test.js` covering: committed-file sync (real-repo), import-without-side-effects, and a simulated-hand-edit proof for each new generator.

  Replaced hand-maintained equivalents with links + ≤2-line summaries. Replacements: (1) `docs/FEATURES.md §Supported hosts` — four-host prose block replaced with one-paragraph summary + link to `docs/reference/hosts.md`; (2) `docs/FEATURES.md §A structured SDLC / Tracks` — the 19-row stage+role table and the 6-row track+stages table replaced with 2-line summaries + links to `docs/reference/stages.md` and `docs/tracks.md`; (3) `docs/concepts.md §Tracks at a glance` — the 6-row track table (which also contained a stale "All 17" stage count) replaced with a 2-line summary + links; (4) `docs/user-guide.md §Conditional stages` — 2-row conditional-stages table replaced with 1-sentence summary + link to `docs/reference/stages.md §Phase 2`.

  Idempotency: a second `npm run docs:generate` produces no diff.

  Honest scope note: `docs/reference/cli.md` (D3.2) is a separate later prompt — deferred until Phase 3.1a flag schemas land. (closes BACKLOG D3 sub-items 1, 3, 4)

- **D4 — Dedup and lifecycle (BACKLOG · README · CONTRIBUTING · AGENTS).** BACKLOG slimming: all struck-through table rows compressed to one-liner format (`ID · ~~Title~~ · vX.Y.Z · CHANGELOG link`); G-section innovation bets collapsed to sub-heading stubs; priority queue pruned to the two surviving open items (D5, H3). Eight items that had no CHANGELOG.md entry (B2, B9, B10, C1, C3, C5, E7, G6) each gained a `changelog.d/` fragment before slimming so no implementation detail was lost. README diet: flat 30-doc "Documentation map" replaced with the four D2 audience-path tables (Evaluator / Operator / Contributor / Model); "What this gives you" slimmed from 12 bullets to 5 headline bullets with a `docs/FEATURES.md` link for the full catalogue. CONTRIBUTING additions: new "Documentation principles" section (the five §2 rules from the documentation plan), "Doc-update checklist" X→Y table (stages.js / new flag / new feature / new decision / landed BACKLOG item), and "Archive policy" paragraph formalizing the `docs/historical/` convention. AGENTS.md refit: rewritten from 112 lines to ~65 lines; load-bearing contracts section condensed to two paragraphs that link to `ARCHITECTURE.md`, `gate.schema.json`, and `host-adapter.md` rather than restating their content; "Adding things" table now links to CONTRIBUTING recipes; test commands section added (`npm test`, `npm run consistency`, `npx eslint .`, `CI=true DEVTEAM_HEADLESS_COMMAND=cat npm test`). (closes BACKLOG D4)

---
type: changed
pr: ~
---

**Execute D5 step 3 — role-brief token trim (8.3)**

Move stage-conditional task sections from `roles/platform.md` (15,617 B →
2,400 B, −85%) and `roles/qa.md` (12,878 B → 2,718 B, −79%) into dedicated
per-stage skill files, leaving role identity + handoff + gate rules in the
briefs.

- **New skills (platform):** `skills/platform-build/SKILL.md`,
  `skills/platform-pre-review/SKILL.md`, `skills/platform-deploy/SKILL.md`.
  Extended: `skills/review-rubric/SKILL.md` (Platform Reviewer Focus section),
  `skills/observability-verification/SKILL.md` (Platform gate detail section).
- **New skills (qa):** `skills/qa-augmentation/SKILL.md`,
  `skills/qa-test-authoring/SKILL.md`, `skills/qa-test-execution/SKILL.md`.
  Extended: `skills/review-rubric/SKILL.md` (QA Reviewer Focus section).
- **`rules/stage-05.md`** trimmed from 9,985 B to 8,177 B (under the 8 KB
  advisory ceiling). The approval-derivation hook contract detail (blockers[]
  schema, gate merge strategy, affected_workstreams derivation) moved to
  `docs/conventions.md §Stage 5 approval-derivation hook contract`.
- **`docs/reference/prompt-budget.md`** regenerated. Platform dispatch:
  27,402 B → 14,185 B (−48%); QA dispatch: 24,663 B → 14,503 B (−41%).
- `npm run consistency` — 314 checks passed, zero advisories (was 1).

Honest scope note: the skill files are loaded on-demand by the model (directed
by the Task Skills table in each role brief), not automatically injected by the
orchestrator per stage identity. Orchestrator-level automatic injection remains
a future architectural improvement; the token reduction is real because the
brief is what the orchestrator includes in every dispatch, and skills are read
only for the current task.

- **D6 — Onboarding flow upkeep (documentation-plan.md D6).** Three sub-items:

  **D6.1 — EXAMPLE.md freshness stamp.** Added a "captured at v0.5.0" stamp near the top of `EXAMPLE.md` (last substantive content update: commits `21a7995`/`b001e9b`, released in v0.5.0). Extended `scripts/consistency.js` with a new `checkExampleMdFreshnessStamp()` advisory that warns when the stamp is more than one minor behind `package.json` — fires at the next minor release, not before. Extended `scripts/release.js` `check()` with an EXAMPLE.md re-capture reminder (warning, not failure) that surfaces on every `node scripts/release.js check` run.

  **D6.2 — First-30-minutes CI smoke.** Extended `.github/workflows/test.yml` with a "First-30-minutes onboarding smoke" step (after the existing doctor step). The step executes the README's actual onboarding sequence in a temp dir: `devteam init` → `devteam doctor` → `DEVTEAM_HEADLESS_COMMAND=cat devteam stage requirements --feature "smoke test feature" --headless` → `devteam next --json` (asserts the action is one of the six valid pipeline actions). `DEVTEAM_HEADLESS_COMMAND=cat` renders the prompt to stdout without invoking a model — fully offline-safe; no divergence from the README sequence.

  **D6.3 — FAQ policy note + entry cleanup.** Added a three-line "How this FAQ is maintained" policy note to the top of `docs/faq.md`. Applied the policy once to existing entries (cross-check against FEATURES.md): deleted "When will this hit 1.0?" (future-state claim with a stale time bound — not an operational question); trimmed "What's planned next?" to a bare link to BACKLOG.md (the item list cited `devteam run` as planned but it shipped in v0.3.0).

- **docs:** Mark Phase 4 complete in plans/prompts/ALL-PROMPTS.md (PRs #90–#97); update BACKLOG.md to mark G3, G10, and H2 progress-based convergence as landed with accurate implementation descriptions; add progress-based convergence bullet to FEATURES.md autonomous execution section.

- **docs(platform):** Declared Stagecraft as macOS/Linux-only (POSIX-only); Windows native is not supported. README prerequisites and `docs/faq.md` now state this explicitly with a WSL2 recommendation. `devteam doctor` and `devteam init` print a clear warning (not a hard exit) when `process.platform === "win32"`. `docs/BACKLOG.md` gains item A6 (Windows port, impact 2 / effort 4) with the three known breakage points: PATH probe, headless command splitter, and POSIX `rm` in fix steps. Cheap correctness wins: `devteam doctor`'s `which` subprocess replaced by a pure-Node PATH probe (`findOnPath`); the headless command splitter in `core/adapters/headless.js` and `core/escalation.js` now throws a clear error on quote characters rather than silently mis-splitting. 13 new tests in `tests/posix-only.test.js`. (plans/phase-3-structural-debt.md §3.5)

- **C3 Phase 6.3 — License gate runner: verify, don't trust.** `core/verify/license-runner.js` adds an orchestrator-side offline license compliance check for Node projects. `stampStage04a()` now walks `node_modules/*/package.json` (including scoped `@scope/pkg` packages) and evaluates each declared SPDX license against the C3 policy table (MIT/Apache-2.0/BSD-*/ISC/CC0/Unlicense → allowed; UNLICENSED/SSPL/BUSL → warned; GPL-*/AGPL-*/LGPL-* → denied). The orchestrator's result overwrites the model's `license_check_passed` claim with model-said vs observed recorded in `_orchestrator_stamped`. Non-Node projects (no `package.json`) and Node projects where `node_modules/` is not installed are stamped `"unverified-by-orchestrator"` (new tri-state value) with a `warnings[]` entry — the model's assertion stands but is explicitly labeled unverified. Schema (`stage-04a.schema.json`) and `rules/stage-04a.md` updated for the tri-state. Project-level license exceptions via `.devteam/config.yml` `license.extra_allowed[]` are respected. `dependency_review_passed` is relabeled model-asserted by design in both schema and rules: vulnerability scanning (npm audit, pip-audit) requires network access to the advisory database and cannot be verified offline by the orchestrator. (closes C3 doctrine exception, Phase 6.3)

- **feat(stage-07):** Add documentation gate to PM sign-off. The PM must now classify whether the change touches a user-visible surface (CLI flag, config key, API endpoint, or behaviour change) and confirm that the appropriate doc update was made. `docs_updated: false` with `docs_surface_affected: true` is a gate blocker. Internal-only changes require only a one-line skip reason. Auto-fold from Stage 6 is blocked when a surface is detected but doc completion cannot be confirmed from the artifacts.

- **feat(G10): role tool budgets — per-role tool-surface restriction with cross-host degradation.** Formalises the existing `tools:` field in `ROLE_FRONTMATTER` (hosts/claude-code/adapter.js) as the per-role tool-budget declaration. `hosts/claude-code/adapter.js` exports `toolBudgetFor(role)` → `string[] | null`. Orchestrator resolves `descriptor.toolBudget` at dispatch time, warns (not blocks) when a budget-carrying role routes to a prompt-only host (`enforces.tool_budget: "native" | "prompt-only"` added to all four `capabilities.json` files). Prompt-only hosts (codex, gemini-cli, generic) inject an intent-plus-names advisory section via `toolBudgetSection()` in `core/adapters/render-helpers.js`. Claude-code enforces natively (subagent `tools:` line); no prompt injection needed. `dispatched_tool_budget` field added to `gate.schema.json`; stamped orchestrator-side for headless runs (mtime-guarded to preserve replay flow), auto-injected by the gate validator for user-driven gates. 12 new tests in tests/adapter-contract.test.js. docs/FEATURES.md and docs/concepts.md updated.
- **fix(6.1): prompt-only path made real.** Role→tools table moved from `hosts/claude-code/adapter.js` to `core/roles.js` (`toolBudgetFor` export); orchestrator and gate validator now resolve the budget host-neutrally so codex, gemini-cli, and generic dispatches receive `descriptor.toolBudget`, render the advisory section, fire the degradation warning, and stamp `dispatched_tool_budget`. 9 new tests added; gate-validator and adapter-contract tests updated to exercise the real resolution path.

- **feat(G3): production feedback seam — close the brief→production SLO loop (effort-1).** Operator-curated `pipeline/production-feedback.md` (template + conventions entry) provides the integration seam between the pipeline and production signals without automated ingestion. Template (`templates/production-feedback-template.md`) has sections keyed by the brief's metric/SLO names plus an incidents list; registered in `templates/README.md`. Stage-09 `readFirst` gains an optional entry rendered as "(if present)" via a new `{ path, optional: true }` object form handled in `buildDescriptor` (orchestrator.js) — smallest code change, bounded workspace-safe. Stage-09 gate adds an optional `production_feedback_reviewed: true|false|"absent"` field (schema + rules/stage-09.md + gate skeleton). `rules/stage-09.md` gains a "Production deltas vs. brief SLOs" section directing the principal to read the file, write a `## Production Deltas` retro section, and stamp the gate field. `devteam next` on `pipeline-complete` emits one suggestion line when the file is absent — not a blocker, not a nag. Docs: `docs/conventions.md` catalogue entry, `docs/FEATURES.md` row, `docs/runbooks/open-followups.md` cross-link. Tests: contract test extended (template registered), gate schema validates all three `production_feedback_reviewed` values, pipeline-complete CLI output correct when file present/absent. *Honest scope note:* No automated ingestion — the file is the integration seam; Jira/Datadog automation can write it later without framework changes (BACKLOG F2/F3/F5 deprioritized, honored).

- **feat(driver):** Add `detectNoSourceChange` convergence check — when a blocker names specific files and those files' content is identical across consecutive auto-fix attempts, the driver halts as `convergence-exhausted` after just one wasted build dispatch instead of two. Catches config-level defects (e.g. Dockerfile base image) that are invisible to the build agent's lint/test goal condition.

- **feat(convergence):** Progress-based convergence breaker implemented on both the interactive (`devteam next`) and autonomous (`devteam run`) paths (Phase 4.2 / ADR-003). The breaker now trips on **no progress** — identical blocker sets across the last two archived attempts — rather than solely on attempt count. When it trips, `halt_reason` and a new `no_progress_evidence` field state what didn't change (e.g. `"blocker 'unit tests failing' identical across attempts 1,2"`) for operator inspection and escalation context. `run-log.jsonl` also carries the evidence.
- **feat(convergence):** Interactive path (`devteam next` / `core/orchestrator.js`) now derives attempt count from archived gate files (`countArchivedAttempts`) instead of the model-written `gate.retry_number`, removing an agent-falsifiable input from the convergence decision. The count-based ceiling (`autonomy.max_retries`, default 2) is retained as the backstop for the first retry, before two archives exist to compare.
- **feat(convergence):** New module `core/gates/convergence.js` exports `detectNoProgress`, `countArchivedAttempts`, and `noProgressEvidence`. Reads from `pipeline/gates/archive/` (the per-attempt archive layer landed in commit `3d0b16f`); never writes; best-effort (unreadable archives leave the count-based ceiling in control).
- **docs:** `docs/autonomous-execution-design.md` §2.5 updated from "grounding correction — not implemented" to the implemented state. §4.1 step 4 updated. `docs/runbooks/autonomous-run.md` limitation updated from "count-based" to progress-based with honest scope note.

  **Honest scope note:** the progress comparison is blocker-set text (model-written), normalized and sorted. Stable blocker IDs are not yet assigned; two semantically identical blockers with different wording will not be detected as stuck. Targeted fanout retry remains deferred per the spec.

- **Phase 5.2 — Archive lifecycle owner.** Closes the bug class where per-attempt gate archives (`pipeline/gates/archive/`) could outlive the failure sequence they describe, producing false `convergence-exhausted` halts on re-entry and stale-archive false no-progress halts on fresh runs. Three-part fix: (1) **Prune-on-recovery**: new `pruneArchives(gatesDir, stageId)` in `core/gates/archive.js`; called at both finalization sites — `mergeWorkstreamGates` (multi-role merge path) and `runStageHeadless` (single-role stamp path) — whenever the stage gate reaches PASS. (2) **Prune-on-re-entry**: the driver's `fix-and-retry` path calls `pruneArchives` for every stage whose gate is cleared by a recipe, generalizing the `#106` restart-only fix; `restart.js` already used the shared `archive.js` `listArchives` path. (3) **Defense-in-depth guard** in `core/gates/convergence.js`: `_currentSequenceArchives()` filters archives from previous failure sequences by comparing mtime to the current attempt-1 archive, so stale archives that survived a missed prune cannot trigger false `detectNoProgress` or `countArchivedAttempts` results. Two regression tests (both failed on main before this fix): stage that failed twice, recovered, and was re-entered via a downstream recipe no longer hits instant `convergence-exhausted`; fresh run with stale attempt-2/3 archives from a previous run no longer produces a false no-progress halt. Existing `#106` restart archive-cleanup tests continue to pass via the shared path.

- **Phase 5.3 — Interactive convergence ceiling.** Closes the gap where a purely interactive `devteam next` / `devteam stage` loop had no convergence ceiling: archives were only created by the autonomous driver, so an interactive loop that failed the same stage repeatedly accumulated zero archive files and `countArchivedAttempts()` never returned a non-zero count. Fix: new shared helper `archiveGateIfFail(gatesDir, stageId)` in `core/gates/archive.js` — checks whether the current gate has status FAIL, derives the attempt number from existing archives on disk (`listArchives().length + 1`), and calls `archiveGate`. This function is called at two sites: (1) `runStageHeadless` (in `core/orchestrator.js`) archives the stage gate before dispatch — covers the interactive path; (2) the driver's fix-and-retry branch (in `core/driver.js`) now calls `archiveGateIfFail` instead of the bare `archiveGate` call — consolidates both paths to the same helper. No double-archiving: the driver clears the gate before `runStageHeadless` runs, so the shared-path call in the orchestrator is a no-op on the autonomous path (gate absent → `archiveGateIfFail` returns null). Convergence module header updated to document the archive-before-overwrite coverage boundary (interactive and driver paths covered; manual hook-driven gate overwrites are out of scope). Two new regression tests (`tests/convergence-ceiling-interactive.test.js`): both failed on main before this fix — `runStageHeadless` archives a pre-existing FAIL gate before dispatch (verified by archive count after each dispatch), and interactive loop of `maxRetries+1` identical-blocker failures → `next()` returns `convergence-exhausted` with `no_progress_evidence` populated.

- **Phase 5.4 (commit 1) — Bounded isolation fence.** Closes the silent-wrong state where `isolation: bounded` in `.devteam/config.yml` allowed the CLI read-side commands (`next`, `restart`, `log`, `advise`, `replay`, `derive-approvals`, `spec`) to proceed without changeId awareness, silently reading and writing the global `pipeline/` directory instead of the per-change subtree. Fix: new `checkBoundedFence(config, commandName)` function in `core/config.js` (exported alongside `BOUNDED_UNWIRED_COMMANDS`). Each of the seven unwired commands calls the fence at entry — if `isolation: bounded` is active and `isolation_acknowledge_partial: true` is not set, the command exits with an error that names the full unwired list. The fence is honest: it neither silently proceeds (data corruption risk) nor refuses the driver path (which is fully wired). Escape hatch: set `isolation_acknowledge_partial: true` in `.devteam/config.yml` to use only the driver path while the CLI layer catches up. `loadConfig` now parses `isolation_acknowledge_partial`. Tests: `tests/bounded-fence.test.js` — fence throws for each unwired command; escape hatch bypasses the fence; in-place config is always a no-op; `loadConfig` parses the new field; meta-test greps `core/cli/commands/` for `resolveChangeId` and verifies `BOUNDED_UNWIRED_COMMANDS` matches the derived unwired set (prevents fence message from going stale as commands are wired in commit 2).

  Honest scope note: the CLI read-side commands are still not changeId-aware after this commit; commit 2 wires each command, shrinks `BOUNDED_UNWIRED_COMMANDS`, and the meta-test enforces parity automatically.

## fix(b9-cli-layer): wire all seven CLI read-side commands for bounded isolation — Phase 5.4 commit 2

**Scope**: Phase 5.4, commit 2 — B9 bounded workspace isolation, CLI read-side wiring.

### What was broken

In `isolation: bounded` mode, the seven CLI read-side commands (`next`, `restart`,
`log`, `advise`, `replay`, `derive-approvals`, `spec`) silently read from and wrote
to the global `pipeline/` directory instead of the per-change
`pipeline/changes/<changeId>/` subtree. The autonomous driver's auto-fix path
additionally looked for `clear_gates` entries at in-place paths, finding nothing
and halting with _"fix steps contain no gate clears"_.

### What changed

#### New: `core/cli/resolve-change-id.js`
Shared helper `resolveChangeId(flags, config)` returns `changeIdFromFeature(flags.feature)`
in bounded mode or `null` in in-place mode. The presence of this import token is what
the meta-test in `tests/bounded-fence.test.js` greps for to determine a command is "wired".

#### CLI commands — `--feature` flag and bounded path routing
All seven commands now accept `--feature <name>` and call `resolveChangeId` at entry.
Each routes artifact reads and writes through the bounded path helpers:

| Command | Bounded path used |
|---------|-------------------|
| `next` | `pipelineRoot(cwd, changeId)` for production-feedback check |
| `restart` | `gatesDir(cwd, changeId)`, `pipelineRoot(cwd, changeId)` for context.md |
| `log` | `buildEvents(cwd, changeId)` scans bounded pipelineRoot |
| `advise` | `gatesDir(cwd, changeId)`, `pipelineRoot(cwd, changeId)/context.md` |
| `replay` | `gatesDir(cwd, changeId)` for gate lookup and archive |
| `derive-approvals` | `pipelineRoot(cwd, changeId)/code-review`; passes `DEVTEAM_REVIEW_DIR` and `DEVTEAM_GATES_DIR` env vars to the hook subprocess |
| `spec` | `pipelineRoot(cwd, changeId)` as `pipelineDir` for brief/spec/test-report |

#### `core/driver.js` — `prefixPipelineRelative` for recipe `clear_gates`
Recipes emit gate paths in the in-place format (`"pipeline/gates/stage-NN.json"`).
The driver now rewrites each path through `prefixPipelineRelative(rel, changeId)` before
calling `clearGates()`, so bounded runs clear the correct `pipeline/changes/<id>/gates/`
file instead of a non-existent in-place file that caused the "no gate clears" false halt.

#### `core/log/journal.js` — `buildEvents` accepts `changeId`
`buildEvents(cwd, changeId)` now uses `pipelineRoot(cwd, changeId)` as the scan root.
`walkArtifacts` receives `relBase = pipelineRoot` instead of `cwd`, and computes
`"pipeline/" + path.relative(relBase, full)` so ARTIFACT_PATTERNS (which all start
with `"pipeline/"`) match in both in-place and bounded mode.

#### `core/hooks/approval-derivation.js` — env-var path overrides
`DEVTEAM_REVIEW_DIR` and `DEVTEAM_GATES_DIR` environment variables override the
hook's hardcoded in-place paths, allowing `devteam derive-approvals` to pass the
bounded paths to the hook subprocess without changing its argument interface.

#### `core/spec/verify.js` — `opts.pipelineDir` parameter
`verify(cwd, opts)` now accepts `opts.pipelineDir` to override the default
`cwd/pipeline` root, used by `devteam spec` in bounded mode.

#### `core/config.js` — `BOUNDED_UNWIRED_COMMANDS` emptied
Now `[]` — all seven commands are wired. The bounded isolation fence is fully
transparent for all CLI commands and no longer requires `isolation_acknowledge_partial: true`.

### Tests added

`tests/bounded-mode-wiring.test.js` (16 tests):
- Driver auto-fix regression: recipe clears the PREFIXED bounded gate and the run completes.
- Per-command bounded path coverage for all seven wired commands (next, restart, log, advise, replay, derive-approvals, spec): each test verifies the command reads/writes from `pipeline/changes/<id>/` when `--feature` is supplied and from `pipeline/` without it.

## fix(6.2): orchestrator stamps stage-03b — pm brief no longer needs Bash

**Scope**: Phase 6.2 — Promise Integrity: PM role/shell contradiction.

### What was broken

`roles/pm.md` stage-03b procedure instructed the pm to run `devteam spec generate`
and `devteam spec verify` (shell commands), but pm's declared tool budget is
`Read, Write, Glob` — no Bash. Under claude-code's native tool-budget enforcement
the pm subagent cannot execute its own brief: the instructions are unreachable.

Additionally, no mechanical check existed to catch future budget/brief contradictions
of the same kind.

### What changed

#### `core/verify/stamp.js` — `stampStage03b()`

New stamping function added to the orchestrator layer. After the pm agent writes
`pipeline/gates/stage-03b.json`, the orchestrator now:

1. Generates `pipeline/spec.feature` via `generateScaffold()` (from `core/spec/verify.js`)
   if the file is absent — one scaffold scenario per AC in `brief.md`.
2. Runs `verify()` (pure Node.js, same function `devteam spec verify` uses) to detect
   drift between `brief.md` acceptance criteria and `spec.feature` scenarios.
3. Stamps all seven spec-related gate fields with model-said vs orchestrator-observed:

| Field | Stamped value |
|-------|---------------|
| `criteria_count` | AC count from `brief.md` |
| `scenarios_count` | scenario count from `spec.feature` |
| `criteria_to_scenario_mapping` | per-criterion scenario names |
| `all_criteria_mapped` | true iff no orphan criteria or duplicates |
| `orphan_scenarios` | scenario names with no matching AC |
| `orphan_criteria` | AC IDs with no matching scenario |
| `drift` | true iff any orphan or duplicate found |

If `drift` is true or `all_criteria_mapped` is false, a blocker is appended and
the gate status flips to FAIL — same `finalizeStamp` pattern as stage-04a/06.

`"stage-03b"` added to `STAMPABLE_STAGES`.

#### `roles/pm.md` — stage-03b procedure rewritten

The pm's stage-03b procedure now:
- Reads `brief.md` for acceptance criteria (source of truth).
- Reads or writes `spec.feature` directly via the Write tool — one scenario per AC,
  each tagged `@AC-N`, with concrete Given/When/Then steps.
- Writes `pipeline/gates/stage-03b.json` with its self-assessment.
- No shell commands appear anywhere in the procedure.

A note clarifies that `devteam spec generate` and `devteam spec verify` are pipeline
shell commands the orchestrator runs on the pm's behalf after dispatch.

Rejected alternative — grant pm Bash: verification belongs to the orchestrator, not
to an agent self-certifying what the orchestrator should verify.

#### `scripts/consistency.js` — new check class `role-budget-brief`

`checkRoleBriefToolBudgetCompatibility()` scans `roles/*.md`. For each role whose
`toolBudgetFor()` result does not include Bash, any line matching
`` Run `devteam <subcommand>` `` is flagged as a violation. The check distinguishes
imperative instructions ("Run `devteam …`") from informational references
(`` `devteam …` `` without the leading "Run"), so descriptions of what the pipeline
does are not penalised. The real `roles/` tree produces zero violations after the
`pm.md` rewrite.

### Tests added

**`tests/verify-stamp.test.js`** — 6 new tests for `stampStage03b`:
- Happy path: all 7 gate fields stamped correctly, `drift=false`, status PASS.
- Drift detected: status flips to FAIL, `model_said` recorded, blocker appended.
- Scaffold generated when `spec.feature` is absent.
- Graceful skip when `brief.md` is absent (track without requirements stage).
- `model_said` vs orchestrator captured on count mismatch.
- `stamp()` dispatch round-trip for `"stage-03b"`.

**`tests/consistency-meta.test.js`** — 4 new tests for `role-budget-brief`:
- `"Run \`devteam spec generate\`"` in a no-Bash role → violation detected (exit 1).
- Same command in a role with Bash (e.g. qa) → no violation (exit 0).
- Informational reference `` `devteam spec generate` `` without "Run" → no violation.
- Real `roles/` regression guard → 0 violations after `pm.md` rewrite (exit 0).

- **Fix (6.4): de-overfit fix recipes — provenance-based blocker routing replaces regex heuristics.**
  Three overfit sources removed:

  1. **`_wsFromText` regex demoted to last-resort fallback.** Recipe routing now reads workstream attribution from blocker fields (`assigned_to`, `workstream`) directly — provenance first, regex only when no structured attribution exists (emits a WARN). A new `_wsFromProvenance()` helper encodes this priority.

  2. **`mergeWorkstreamGates` preserves workstream on object blockers.** The merge previously flattened all workstream gate blockers into a single array without recording their source. Object blockers now carry `workstream: role` when merged, enabling provenance-based routing downstream.

  3. **stage-06b recipe: backend hardcoding and demo-project comment removed.** The old recipe unconditionally routed A11Y blockers to the backend workstream (based on a demo-project CSS filename). The updated recipe routes to whichever workstream `assigned_to`/`workstream` fields identify; falls back to regex then to all build roles when blockers carry no structured attribution.

  4. **Hardcoded `["backend","frontend","platform","qa"]` fallback arrays → `_buildRoles()`.** Two last-resort fallbacks in stage-04c and stage-06d that listed build roles explicitly now derive them from the build stage definition (`getStage("build").roles`), so they stay correct if the build stage's role list changes.

  **Tests added:** frontend-owned A11Y blocker (assigned_to: frontend) routes to frontend, not backend; multi-workstream A11Y blockers clear all attributed gates; soc2 scenario (string blockers) uses general build dispatch; recipe-hygiene meta-test ensures no recipe source quotes a filename that exists only under `examples/`.

  Honest scope note: string blockers without `assigned_to` still fall back to regex then to clearing all build workstream gates — these are safe but may over-clear. Adding `assigned_to` to A11Y blockers in the gate schema is the long-term fix.

- **fix(7.1):** Git-aware consistency enumeration and meta-test isolation. `scripts/consistency.js` now uses `git ls-files -z` when `.git` is present so untracked files never block a blocking check — they emit an advisory instead. Added `--only <check-class>` flag so meta-tests run only their own check class, eliminating five-test fan-out from a single stray file. Added `PROMPT_BUDGET_FILE` env override (mirrors `CONSISTENCY_BASELINE_FILE`) so prompt-budget meta-tests write to a tempdir instead of rewriting the real file in place. The stage-05.md "known exceedance" test is now fixture-based via `--root` + `--only file-size-ceiling`, so trimming that file in Phase 8 won't break the suite. CI workflow permanently creates `docs/SCRATCH-ci-probe.md` before `npm test` as a regression guard; this step was red on the pre-fix main and is green after. (plans/phase-7-test-harness.md §7.1)

## fix/ci-signal (Phase 7.2) — CI signal quality

### 7.2.1 — Tighten onboarding smoke assertion
- The CI onboarding smoke step now captures `devteam stage` stdout+stderr and
  asserts the requirements-role header (`Stage stage-01`) appears in the
  output. A crash inside `devteam stage` now fails the step instead of
  silently succeeding behind `|| true`.
- Pinned `devteam next` action check to `run-stage|continue-stage` (the two
  actions reachable from a headless run that wrote no gate), replacing the
  previous six-action whitelist that included `pipeline-complete` and
  `resolve-escalation` (neither reachable from a fresh `init`).

### 7.2.2 — Coverage signal surfacing
- Coverage step now emits a summary block to `$GITHUB_STEP_SUMMARY` — numbers
  are visible from the PR checks list without opening the raw log.
- New `upload-artifact` step saves `coverage-report.txt` for 14 days per node
  version (non-blocking, `if-no-files-found: ignore`).
- Moved the recorded baseline from a YAML comment into
  `.github/coverage-baseline.json` so updating it produces a visible diff.

### 7.2.3 — a11y-fixer success-path tests
- Added three tests covering `fixA11yBlockers`'s dispatch → re-validation path
  (the reason the module exists), which was untested at 69.7% line coverage:
  - PASS gate: returns `{ status: "PASS", exitCode: 0 }`.
  - FAIL gate with remaining blockers: returns `{ status: "FAIL", exitCode: 1,
    remainingBlockers: [...] }`.
  - No gate written by re-run: returns `{ status: "MISSING", exitCode: 1 }`.

### 7.2.4 — Fix preflight git-hygiene dead code
- Fixed `core/preflight.js`: added `-c` (`--cached`) flag to `git ls-files
  --ignored --exclude-standard`. Without it the command exits 128 on git ≥
  2.27, making the blocker path permanently unreachable on modern git (macOS
  Apple Git ≥ 2.28, Ubuntu default git ≥ 2.27).
- Replaced the two documenting tests (which recorded the broken behavior) with
  three behavioral tests: clean repo passes, committed-then-ignored file fires
  a blocker with a `git rm --cached` suggestion.

- **Fix: `--allow-stage` now accepts comma-separated values.** Previously, `--allow-stage sign-off,deploy` was treated as a single literal stage name and failed to grant the consequence ceiling for either stage. Adding `split: true` to the flag definition makes both `--allow-stage sign-off,deploy` and `--allow-stage sign-off --allow-stage deploy` produce the same result.

- **Fix: build retry recipes now clear `stage-04a` (pre-review lint gate).** `buildGatePaths()` — the shared helper used by six fix recipes to generate clear_gates lists — was omitting `pipeline/gates/stage-04a.json`. When any recipe re-dispatched the build workstream, the driver saw stage-04a still PASS and skipped the pre-review lint check entirely. Lint errors introduced by the build agent during the re-dispatch reached deploy time undetected. Adding `stage-04a.json` to `buildGatePaths()` closes the gap for all callers at once. Resolves #108.

- **Fix: DAG-derived gate invalidation — Phase 5.1 (closes the #109 class generalized).** Fix recipes hand-listed `clear_gates` per stage; when stage-06d cleared stage-04 build gates, stage-05 (peer-review) and stage-06 (QA) PASS gates were left standing — rewritten code re-entered verification without passing peer-review or QA again. New `core/pipeline/invalidation.js` helper `derivedClearGates()` computes which downstream attestation gates to clear by walking the ordered stage list between the cleared root and the failing stage, returning only paths for gate files that actually exist on disk. Recipes now declare only root stage(s); derived clearing adds every intermediate gate automatically. The hand-listed `stage-04a.json` entry removed from `buildGatePaths`. Updated recipes: stage-04a, stage-04c, stage-05 (code-changes path), stage-06, stage-06b (path 2), stage-06d. `_nextImpl` now passes `stageList` and `changeId` to every `diagnose()` call; the helper is changeId-aware for bounded-mode runs (Phase 5.4). 17 new tests in `tests/invalidation.test.js`, including the regression test that failed on `main` before this fix.

- **Fix: `devteam log` no longer shows artifacts from prior pipeline runs.** When a second feature was started with `devteam restart design --cascade`, gate files were cleared but artifact files (ADRs, design-spec, build-plan, etc.) remained on disk with their original timestamps. The journal sorted all pipeline artifacts by mtime, so first-feature artifacts appeared at the head of `devteam log --follow` output alongside the new feature's events — making the timeline confusing and hard to follow. Fixed by anchoring the artifact timeline to `pipeline/brief.md` mtime: artifacts written before the current brief are treated as prior-run artifacts and suppressed. Gates are unaffected (they are always cleared and re-created). When no brief exists yet, no filtering is applied.

- **fix(write-audit):** `snapshotWritables` now uses `git status --porcelain -z` (NUL-delimited) instead of the newline-based format. Git quotes paths that contain spaces or high-byte characters in the newline format; the old `slice(3).trim()` captured the quote characters verbatim, causing false-positive `allowedWrites` violations that flipped PASS gates to FAIL. The `-z` format never quotes paths. Rename/copy entries (two NUL-separated records) are handled with a `skipNext` flag that discards the origin path, consistent with the previous `" -> "` handling. (plans/phase-3-structural-debt.md §3.7.1)
- **fix(orchestrator):** `mergeWorkstreamGates` now falls back to the locally-resolved `track` variable (derived from `opts.track` / `custom_stages` / `default_track`) when `wsGates[0].gate.track` is `undefined`. Previously a workstream gate that omitted the `track` field caused the merged gate to ship `track: undefined`, which the validator flagged as an unrecognised track — a gate the orchestrator itself wrote was self-flagged. (plans/phase-3-structural-debt.md §3.7.2)
- **fix(tracks):** `core/gates/validator.js` and the `devteam doctor` track check in `bin/devteam` now derive their valid-track sets from the canonical `TRACKS` export in `core/pipeline/stages.js` rather than maintaining independent inline literals. Any track added to `stages.js` automatically propagates to both without a separate manual edit. `VALID_TRACKS` is now exported from `validator.js` for testability. (plans/phase-3-structural-debt.md §3.7.5)

- **fix(config):** `assess --apply` now calls `clearConfigCache()` after writing `.devteam/config.yml`. Previously, any `loadConfig()` call in the same process (e.g. a chained command) would return the stale pre-write value from the in-process cache. Also adds a comment in `core/driver.js` documenting the intentional per-run config pinning: the driver loads config once at run start because track, isolation, and changeId are derived from it and baked into `run-state.json`; re-reading mid-loop could silently corrupt an in-progress run. (plans/phase-3-structural-debt.md §3.7.3)
- **fix(orchestrator):** The `--workstream` filter is now applied inside `runStage` before prompt rendering, rather than in separate post-render implementations in `runStageHeadless` and `cmdStage`. Both headless and non-headless modes now share a single filter path. The matching rule is documented as "role-prefix match": filter values are bare role names; for fanout stages, all fanout instances of a role (e.g. `stage-05.backend.claude-code` and `stage-05.backend.codex`) are selected together by a single `--workstream backend` value. `roles[]` in the returned object now reflects the filtered set. (plans/phase-3-structural-debt.md §3.7.6)
- **fix(pricing):** `mergeWorkstreamGates` now adds a `warnings[]` entry (`"unpriced model X — budget enforcement incomplete"`) when a workstream gate reports token usage for a model not in the pricing table. Previously, budget sums silently treated unpriced models as zero cost. The pricing table remains hand-maintained; this change makes staleness visible without auto-updating it. (plans/phase-3-structural-debt.md §3.7.7)

- **6.5.1 — Unpriced-model WARN on single-role stamp path.** `patchGateForUnpricedModel()` added to `core/orchestrator.js` and called in `runStageHeadless` after a single-role gate is written. Single-role stages (e.g. requirements, executable-spec, qa) now emit the same D7 budget-enforcement warning that `mergeWorkstreamGates` has emitted for multi-role stages since v0.6.0. Function exported for direct unit testing; four cases in `tests/orchestrator.test.js`.
- **6.5.2 — `hosts/generic/capabilities.json` declares `goalLoop: false` explicitly.** Closes the v0.6.0 "explicit false, never ambiguous" gap (same principle applied to gemini-cli in Phase 4). `tests/goal-loop.test.js` strengthened: generic assertion is now `strictEqual(false)` instead of the weaker `ok(!caps.goalLoop)`, so a missing key is caught. `docs/reference/hosts.md` regenerated.
- **6.5.3 — codex/gemini-cli adapter dedup.** The two adapters were ~95% identical (165/166 LOC). Shared `installRoles`, `install`, `uninstall`, `status`, and `renderStagePrompt` logic extracted into `core/adapters/markdown-host.js` as `makeMarkdownHostAdapter(capabilities)`. Both adapters delegate to the base; each retains only its own `invoke()`. Deletes the in-file NOTE comments that flagged this dedup as pending since Phase 3. `tests/audit.test.js` updated: the "uses `core/roles.listRoles()`" invariant now checks the shared base. Adapter-contract and install-roundtrip tests confirm byte-identical rendered output.

- **Fix: `devteam init` hook commands are now portable across machines.** The claude-code adapter previously baked absolute paths to Stagecraft core scripts into `.claude/settings.local.json` at init time (e.g. `node "/abs/path/core/gates/validator.js"`), making the file machine-specific and requiring `devteam init` to be re-run after every fresh clone to a different machine or path. Hook commands now use `devteam hook validate`, `devteam hook secret-scan`, and `devteam hook approval-derivation` — resolved at execution time via the installed `devteam` binary. A new `devteam hook <name>` subcommand dispatches to the same underlying scripts with full stdio and exit-code fidelity. `settings.local.json` is now safe to commit or omit from `.gitignore` without consequence; existing projects can regenerate with `devteam init --host claude-code --force`.

- **Fix: `devteam restart <stage>` now also clears archive files for the restarted stage.** Previously, only the live gate JSON files were deleted; archive files under `pipeline/gates/archive/<stage>.attempt-N.json` were left on disk. This caused `detectNoProgress` to compare stale archives from a prior run against a new attempt, firing a false `convergence-exhausted` halt before the driver could apply the fix recipe and clear gates. The restart command now deletes all archive files for every stage it restarts (including cascade targets), making re-runs after a manual restart start with a clean convergence slate.

- **Fix: stage-06b (accessibility-audit) fix recipe now routes correctly.** The previous recipe scanned `noted_for_followup` items across all gate files — including `stage-06b.json` itself — and, when cosmetic advisory IDs (disclosure triangle, `aria-hidden`) matched the A11Y regex, generated a `devteam advise --apply` command with `clear_gates: []`. Applying cosmetic advisories did not resolve the actual color-contrast blockers, so the stage failed again and `detectNoProgress` fired on the second attempt. The updated recipe (1) excludes stage-06b's own gate from the `noted_for_followup` search, (2) adds an explicit path for stages where A11Y blockers name specific source files — clearing and re-dispatching the backend build + audit gates so the agent can actually edit the CSS.

- **Fix: stage-06d fix steps now include `--patch` on targeted workstream build dispatch.** When a build workstream was identifiable from blocker text (e.g. `Fix: src/backend/server.js:10`), the recipe generated `devteam stage build --workstream backend --headless` — without `--patch`. Without patch mode the build agent verifies existing code rather than implementing the fix, so an operator following the fix steps verbatim would see the same verification blockers again. Added `--patch --from verification-beyond-tests` to match the existing else-branch (unidentifiable workstream) behaviour. Note: the autonomous driver still dispatches build without patch context (`runStageHeadless` does not yet accept `patchFrom`); this fixes the human-visible fix steps only.

- **Fix: stage-06d auto-fix now dispatches build before re-running verification.** When `_wsFromText` could not map a verification blocker to a known workstream (e.g. the blocker contained `"Fix: if (value instanceof Date)…"` — a code snippet, not a file path — and files like `hasher.js` didn't match `src/backend/` patterns), `computeFixSteps` fell back to a no-op descriptive step with empty `commands`. `clearGatesFromFixSteps` found only `rm pipeline/gates/stage-06d.json`, so the driver cleared the gate and re-ran the verifier on unchanged code — burning both retry slots without any patch attempt. Fix: replace the no-op else branch with a global build dispatch (`devteam stage build --patch --from verification-beyond-tests`) plus `rm` commands for all four per-area gates and `stage-04.json`, so `next()` routes through build before re-running verification. Tests added for the unidentifiable-workstream and code-snippet Fix: clause cases.

- **refactor(cli):** `bin/devteam` is now a 91-line pure registry dispatcher. All 31 commands (read-only, pipeline, tooling) are extracted into `core/cli/commands/<command>.js` modules, each exporting `{ name, flags, run(positional, flags) }`. The monolith that was ~2,900 lines is gone; every command is independently loadable, testable, and auditable. `core/cli/get-orchestrator.js` provides a shared lazy-loader so commands that need the orchestrator don't incur its ~60 ms cold-load unless invoked. (plans/phase-3-structural-debt.md §3.1 PR 2)

- **refactor(cli):** Introduce `core/cli/flags.js` — a schema-driven flag parser (`parseFlags(argv, schema)`) that replaces the flat shared `parseFlags` in `bin/devteam`. Each command now declares its own `FLAGS` schema (`{ flagName: { type, key?, split?, description } }`), and unknown flags are rejected per-command rather than via a global catch-all. `generateHelp(commandLine, schema)` produces per-command usage text from the same schema, replacing hand-maintained `Usage:` strings. The Phase-1.4 `--apply` peek-ahead hack dissolves: `assess` declares `apply` as `boolean`, `advise` declares it as `string` — the parser enforces the correct contract for each. `bin/devteam` stays monolithic in this PR; commands move in PR 2. (plans/phase-3-structural-debt.md §3.1 PR 1)

- **refactor(gates):** extracted gate snapshot/restore logic from the replay command module into `core/gates/replay-backup.js`. The new module provides `snapshotGate`, `restoreFromBackup`, `deleteBackup`, `findLeftoverBackups`, `archiveReplayGate`, and `clearOriginalGate`. Command modules now contain argument handling and output formatting only — all gate file operations are delegated to core. (plans/phase-3-structural-debt.md §3.1 PR 3)
- **fix(replay):** eliminated the clobber-and-restore race in `devteam replay`. Previously, the headless run overwrote the original workstream gate with only an in-memory restore; a crash between dispatch and restore left the original silently replaced. Fix: the original gate is now snapshotted to `pipeline/gates/.replay-backup/<name>.json` *before* dispatch; restored from disk afterwards; backup deleted on clean success. On next `devteam replay` invocation, leftover backups from a prior crash are detected and reported before any new dispatch begins. (plans/phase-3-structural-debt.md §3.7.4)

- **refactor(recipes):** replaced the 440-line `computeFixSteps` if-ladder in `core/orchestrator.js` with a per-stage recipe registry in `core/pipeline/fix-recipes.js`. Each stage registers a `diagnose(gate, ctx)` function that returns `{ clear_gates, steps }` directly as data; a single `formatGateClear` formatter derives the human-readable `rm` command strings — no other code generates them. `clearGatesFromFixSteps` (the reverse parse of rm strings back into paths) is deleted; `_nextImpl` calls `getRecipe().diagnose()` directly and the structured `clear_gates` array is attached to every `fix-and-retry` action without post-hoc parsing. `driver.js` updated to consume `clear_gates` exclusively (the `fix_steps` fallback path is removed). orchestrator.js shrank by 521 lines (1481 → 960). (plans/phase-3-structural-debt.md §3.2)

- **refactor(markers):** Extracted `upsertSection` and `stripSection` into a new `core/markers.js` module, eliminating three copies of begin/end-marker section logic. The two strip implementations (core/gates/validator.js and bin/devteam) were byte-for-byte identical; no behavioral divergence. The upsert implementation in core/driver.js had a verified bug: inverted markers (end before begin) or a missing end marker caused a duplicate section to be appended. The new `upsertSection` treats corrupt input explicitly — replaces from the begin-marker to EOF and emits a warning — instead of appending. Both functions operate on text strings; callers own file I/O. (plans/phase-3-structural-debt.md §3.3)

- **refactor(deps):** Moved `@huggingface/transformers` from `dependencies` to `optionalDependencies`. The package is only needed for `devteam memory` with the default local embedding provider; it is never loaded by other commands. `core/memory/embed.js` already lazily `require`d the package — the change adds MODULE_NOT_FOUND detection and a clear actionable error message naming the install command. `devteam doctor` now reports embedding availability as informational (`ℹ`) instead of omitting it or treating absence as a failure. Honest scope note: `npm install` (with no flags) still installs optional dependencies by default, so most users see no change; only `npm install --omit=optional` skips the ~447 MB download. (plans/phase-3-structural-debt.md §3.4)

- **test(coverage):** Added behavioral test suites for the two previously-untested core modules: `tests/preflight.test.js` (19 tests covering `runGitHygieneCheck`, `runImportPathCheck`, `runDeferredItemsRisk`, and `runPreflight` — gate I/O, track propagation, FAIL/PASS status, skipWrite) and `tests/a11y-fixer.test.js` (21 tests covering `parseBlocker` including malformed-input cases, `buildA11yFixPrompt` across empty/single/multiple/null blockers, and `fixA11yBlockers` error paths — no blockers, missing headless capability, missing headlessCommand, non-zero agent exit). Added a non-blocking `Coverage report (informational)` step to `.github/workflows/test.yml` using `node --test --experimental-test-coverage`; baseline at 3.6 merge: 85.43% lines / 76.02% branches / 82.42% functions. No threshold set. Honest scope note: `runGitHygieneCheck`'s blocker path (committed-but-ignored files) is unreachable on git 2.27+ because `git ls-files --ignored --exclude-standard` now requires `-c` or `-o`; the function always produces a warning instead of a blocker on modern git. (plans/phase-3-structural-debt.md §3.6)

---

## [0.6.0] — 2026-06-11

### Added

- **Split `rules/gates.md` per stage to cut per-invocation token cost** (Phase 2 item 2.3). `rules/gates.md` (~21.5 KB, in every stage's `readFirst`) was the single largest driver of prompt overhead: every agent invocation loaded the full gate reference including 11 stage-specific schemas the agent would never write. The file is now split three ways: (1) `rules/gates-core.md` (~5.5 KB) — the universal contract every agent needs: required fields JSON, status lattice (PASS/WARN/FAIL/ESCALATE), workstream vs. stage gates, `affected_workstreams[]` and `noted_for_followup[]` schemas, retry protocol, tamper-evident chain, track field, validator summary, and failure classification; (2) per-stage `## Gate` sections added to all 14 existing `rules/stage-NN.md` files plus 3 new thin stage files created (`rules/stage-01.md`, `rules/stage-02.md`, `rules/stage-09.md`) — each gate section contains a complete JSON example with all fields matching the `gate:` skeleton in `stages.js`; (3) `rules/gates.md` converted to a one-paragraph tombstone pointing at `gates-core.md` and each per-stage file (retained for one release; external docs may link to it). All 16 `readFirst` arrays in `core/pipeline/stages.js` updated: `.devteam/rules/gates.md` → `.devteam/rules/gates-core.md`. **Token reduction for stage-04:** framework readFirst bytes 32 633 B → 13 039 B (−19 594 B = −19.1 KB). Reference audit: `core/gates/validator.js`, `core/gates/schemas/gate.schema.json`, `rules/pipeline.md`, `rules/pipeline-build.md`, `rules/orchestrator.md`, all `roles/*.md`, and `docs/*.md` updated to cite `gates-core.md` or the per-stage file; CHANGELOG history entries left unchanged. Tests: `tests/contract.test.js` extended with two new suites — (a) every stage `readFirst` contains `gates-core.md` and not the old `gates.md`; (b) every `rules/stage-NN.md` that exists contains a `## Gate` section whose field names match the `gate:` skeleton in `stages.js`. `scripts/consistency.js` `checkRequiredRulesPresent` extended to require both `gates.md` (tombstone) and `gates-core.md`. Suite: 1236 pass (was 1234), lint clean, `npm run consistency` 237 checks pass. *Honest scope note:* The per-stage gate docs are now in stage files that are not yet in any stage's `readFirst`; they serve as human reference and hold the gate examples that tests pin. A follow-on item could add the specific `rules/stage-NN.md` to that stage's `readFirst` if agents need the field-level prose, at the cost of ~1–3 KB per stage.

- **Consistency drift sweep (phase 2.2).** Eliminated all 88 prose-vs-code violations identified by the 2.1 checker, burned the baseline to empty, and deleted `scripts/consistency-baseline.json` so `npm run consistency` runs fully un-baselined. Changes: (1) gate-filename fixes — corrected every dash-form workstream gate reference (`stage-04-backend.json` → `stage-04.backend.json`, `stage-05-{area}.json` → `stage-05.{area}.json`) in roles/backend.md, roles/frontend.md, roles/platform.md, roles/reviewer.md, roles/qa.md, roles/security.md, rules/stage-04.md, rules/stage-04a.md, rules/stage-04b.md, rules/stage-05.md, and rules/gates.md; (2) ghost command surface — replaced all slash-command and `bootstrap.sh` / `npm run review:derive` references in rules/ and roles/ with real `devteam` CLI invocations; (3) missing stage rule files — added rules/stage-04c.md (red-team), rules/stage-04d.md (migration-safety), rules/stage-06d.md (verification-beyond-tests), rules/stage-06e.md (performance-budget); updated rules/pipeline-build.md index to list all 14 build-phase stages; (4) stage/track count fixes — updated 17→18 stage count and 4→6 track count across docs/concepts.md, docs/faq.md, docs/ci.md, docs/TESTING.md, docs/comparative-analysis.md, two walkthroughs, three audit docs, skills/audit/SKILL.md, and rules/gates.md; (5) tracks matrix generator — `scripts/generate-tracks-matrix.js` derives the "What each track runs" matrix in docs/tracks.md from `STAGES_BY_TRACK`; a new `checkTracksMatrixSync` check in consistency.js fails if the committed block is stale; 2 meta-tests added; (6) secondary docs refresh — AGENTS.md (300+→1200+ tests, 11→12 locked decisions, stale backlog blurb replaced), CONTRIBUTING.md (remove "until test suite lands" placeholders), README.md (11→12 locked decisions), docs/TESTING.md (remove stale count, add autonomous-execution suites to inventory), docs/faq.md (3→4 adapters, remove stale test count, fix /goal paragraph), docs/runbooks/autonomous-run.md (rewrite "Honest limitations"), docs/runbooks/escalation.md (renumber duplicate §4b to §4c), rules/compaction.md (renumber duplicate items 8/8/9 to 8/9/10), docs/BACKLOG.md (strike E1 devteam summary, E5 devteam doctor as landed); (7) template referers — rules/gates.md, rules/stage-08.md, core/deploy/README.md, core/deploy/docker-compose.md, and core/gates/schemas/stage-01.schema.json updated to point at `templates/` canonical blank forms instead of `docs/` annotation guides; remaining 27 stage-id and 5 ref-existence violations fixed (un-padded stage IDs in runbook headings/anchors, stale `core/skills/` path references, target-project-path clarifications). Suite: 1231 pass, 3 skipped, lint clean.

- **Prose-vs-code consistency checker — six new check classes** (Phase 2 item 2.1, closes plan `phase-2-consistency-and-docs.md`). `scripts/consistency.js` now detects six classes of drift between the prose artifacts (rules/, roles/, docs/, skills/) and the live code (`STAGES`, `TRACKS`, `ORDERED_STAGE_NAMES`, `approval-derivation.js`): (1) **gate-filename** — dash-separated workstream gate names (`stage-04-backend.json`) where the canonical form is dot-separated (`stage-04.backend.json`, per `approval-derivation.js:217`); also catches dash-form template placeholders (`stage-05-{area}.json`); (2) **stage-id** — non-canonical stage IDs (un-padded: `stage-4`, `stage-5`) and IDs not present in `STAGES`; (3) **stage-count** — "N-stage" prose claims that disagree with `ORDERED_STAGE_NAMES.length` (18); (4) **track-list** — "N tracks" count claims that disagree with `TRACKS.length` (6), and enumerated "Valid values:" lists that name some tracks but omit others; (5) **ref-existence** — backtick-path and markdown-link references to `rules/`, `roles/`, `core/`, `skills/`, `docs/`, `.devteam/rules/` that point to files not present in the repo; (6) **stage-rule-file** — stages in STAGES build range (04–08) or indexed in `rules/pipeline-build.md` with no corresponding `rules/stage-NN[x].md`. **Baseline mode** (`scripts/consistency-baseline.json`, 86 entries): pre-existing violations are suppressed (reported but not failing) so CI can enforce the checker immediately; item 2.2 burns the baseline down. Baseline keys are stable (`checkClass:file:identifier`, no line numbers), so unrelated edits don't churn the file. Flags: `--no-baseline` (show raw violations), `--root <path>` (fixture-tree mode, prose checks only), `--json` (machine output). Supports `CONSISTENCY_BASELINE_FILE` env var to inject a fixture baseline in tests. `module.exports = { main }` for programmatic invocation. `tests/consistency-meta.test.js` extended with 23 fixture-tree tests — one violation-detected + clean fixture per check class, plus baseline suppression (exit 0 + "baselined" note) and non-baselined failure (exit 1). Suite: 1227 pass, lint clean, `npm run consistency` exits 0.

- **`next()` is now a pure read — Stage 7 auto-fold write extracted** (closes phase-1-trust-consolidation item 1.2). `core/orchestrator.js` documents `next()` as "Pure read; never mutates state" but `tryAutoFoldSignOff` was writing `pipeline/gates/stage-07.json` as a side effect of asking "what's next?". The auto-fold *feature* is preserved — the **write** is moved to callers. `tryAutoFoldSignOff` is now a pure function returning the folded gate object (or `{ok:false}`) with no `fs.writeFileSync`. `_nextImpl` returns a new `"fold-sign-off"` action carrying `gate_path`, `gate_content`, and `acCount` in the payload. **`cmdNext`** handles `fold-sign-off`: writes the gate, emits a stderr notice, re-runs `next()`, and shows the subsequent action — single-command UX preserved. **`devteam run` (driver)** handles `fold-sign-off`: writes the gate and appends `{"event":"auto-fold-sign-off","derived_from":"brief AC mapping"}` to `run-log.jsonl` — making the fold visible in the audit log (previously invisible). `--allow-stage` is not required for the fold (it is orchestrator-derived from verified AC mapping, not model-asserted). `NEXT_SCHEMA_VERSION` bumped `1.0 → 1.1` (fold-sign-off is a new action a programmatic consumer must handle). Tests: `tests/auto-fold.test.js` updated (3 old tests) — now assert `next()` leaves `pipeline/gates/` byte-identical, that the payload validates against stage-07 schema required fields, and that callers write via `gate_content`. 4 new tests added: (a) byte-identity gate snapshot, (b) schema field validation, (c) driver writes gate + `run-log.jsonl` event + `onEvent` fires, (d) `cmdNext` writes stage-07.json on fold-sign-off. `tests/pipeline-e2e.test.js` `walkPipeline` updated to handle `fold-sign-off`. `tests/next.test.js` schema_version assertion updated. Total: 1172 pass, lint clean. *Honest scope note:* `cmdNext --json` returns the `fold-sign-off` action shape to programmatic callers; callers that previously received the subsequent action in JSON mode must handle the new action value.

- **Per-attempt gate archiving in the autonomous driver.** When `devteam run` auto-fixes a `code-defect` and is about to clear/overwrite the failed stage gate, it first snapshots it to `pipeline/gates/archive/<stage>.attempt-N.json`. The progression of failed attempts now survives — diff `attempt-1` vs `attempt-2` to see whether blockers were shrinking or stuck. New `core/gates/archive.js` (`archiveGate`, `listArchives`); the driver archives before clearing and records the path on the `fix-retry` run-log event. This is the audit/debug record on its own, and the data a future *progress-based* convergence check would read — but convergence stays **count-based** for now (this layer only archives; no behavior change to retry/escalate). Best-effort (never breaks a run). Tests: `tests/archive.test.js` (snapshot + content preservation + sorted `listArchives`) and a driver test that a retry archives `attempt-1` before clearing; full suite 1153 pass, lint clean. Docs: `docs/runbooks/autonomous-run.md`.

- **Structured `clear_gates` on the `fix-and-retry` action.** `devteam next` now attaches `clear_gates` — the repo-relative gate files (e.g. `pipeline/gates/stage-04.backend.json`) a fix recipe wants cleared before re-running, derived once via a shared `clearGatesFromFixSteps` helper in `core/orchestrator.js`. The autonomous driver consumes this structured field directly instead of regex-parsing the recipe's `rm …` command strings (the parse is gone from `core/driver.js` — `extractGateClears` now delegates to the shared helper, kept as a fallback for older action shapes). `clear_gates` also appears in `devteam next --json`, so any programmatic consumer sees the gate-clear intent as data. No behavior change to the recipes themselves; purely makes the intent first-class. Tests: `clearGatesFromFixSteps` unit + `next()` attaches it on a recipe-bearing FAIL (`tests/next.test.js`); driver honors the structured field with no `fix_steps` present (`tests/run.test.js`). Docs: `rules/gates.md`, `README.md`.

- **CI enforces the tamper-evident gate chain** (BACKLOG **F4** + **C6**). The GitHub Actions PR-checks template (`templates/ci/github-actions/stagecraft-pr-checks.yml`, dropped by `devteam ci install`) gains a `devteam verify-chain` step between gate validation and check-run posting. It recomputes the C6 chain on the PR's gates and **fails the build on a break** (a stamped gate whose predecessor changed after chaining — tampering, or an un-re-stamped earlier-stage re-run). Blocking by design — a tamper-evident audit trail is only meaningful if a break fails CI; the step documents how to soften it to advisory (`continue-on-error: true`) for projects that haven't adopted gate chaining. Unstamped/absent chains are reported, not fatal, so adoption is incremental. Tests: `tests/ci.test.js` asserts the step is present; full suite green, lint clean. Docs: `docs/ci.md`.

- **Autonomous-decision authority bound into the tamper-evident chain** (BACKLOG **C6**, PR-D2 — completes C6). When `devteam run --auto-rule` autonomously resolves an escalation, the driver now writes the authority record **onto the escalating gate** as `resolved_by: { authority: "auto-rule:<class>", grant_class, ruling, ts }` — not only to `run-log.jsonl`. Because the gate is hashed by the next downstream stamp, the provenance inherits C6's tamper-evidence: altering "who/what authorized this autonomous decision" after the fact breaks the chain. `devteam verify-chain` (and `--json`) now surfaces a `resolved` list of `{stage, authority, ruling, …}` so an auditor sees, per stage, which autonomous grant resolved it. Optional `resolved_by` object added to `gate.schema.json` (additive). Best-effort: if the applicator cleared the gate to re-run rather than fixing it in place, `run-log.jsonl` still carries the record. Tests: driver writes `resolved_by` onto a real escalating gate (`tests/run.test.js`); `verifyChain` surfaces it (`tests/chain.test.js`); full suite 1148 pass, lint clean. Docs: `rules/gates.md`, design doc (§3.2 — authority-on-gate now landed), `docs/BACKLOG.md` (C6 follow-up closed).

- **Tamper-evident gate chain** (closes BACKLOG **C6**, PR-D1). Recording *what* decided a stage (C4 reproducibility) is only half the audit story — the record must also be tamper-evident. Each **stage-level** gate now carries a `chain` field: `{ prev_stage, prev_hash, algo }`, where `prev_hash` is a **canonical-JSON SHA-256** of the predecessor stage gate's *full* content (including its own `chain` field, so the chain is transitive). Mutating any earlier gate changes its hash, so every gate downstream no longer matches what it recorded — **`devteam verify-chain`** recomputes the chain, locates the break, and exits non-zero (CI-usable); it also flags unstamped stage gates rather than silently passing. New pure module `core/gates/chain.js` (`stampChain`, `verifyChain`, `stampAll`, `canonicalGateHash`). Stamped automatically by the orchestrator: `mergeWorkstreamGates` for multi-role stages, and `runStageHeadless` for single-role stages — **only when the dispatch actually wrote the gate** (pre/post mtime guard, so `devteam replay` against a no-write host stays distinguishable). New **`devteam stamp-chain`** (re)stamps every stage gate in order — used after a deliberate earlier-stage re-run, which legitimately invalidates the chain until re-stamped (documented, not a false alarm). Canonical hashing means key order / whitespace never false-positive; any content change does. Schema: optional `chain` object added to `gate.schema.json` (additive). Makes C4 provenance and the autonomous-run authority records (`--auto-rule`) tamper-evident — the EU AI Act / SOC 2 "who decided this, and was the record altered?" guarantee. Tests: new `tests/chain.test.js` (6 — stamp/genesis, canonical hashing, intact verify, tamper-detect-and-locate, unstamped flagging, re-stamp restore); full suite 1146 pass, lint clean. **PR-D2 follow-up:** bind the `--auto-rule` authority record (`auto-rule:<class>`) onto the chained gate (`resolved_by`) so it inherits the tamper-evidence. Docs alongside: `rules/gates.md`, `README.md`, `docs/FEATURES.md`, design doc, `docs/BACKLOG.md` (C6 ✅).

- **`devteam run --auto-rule` — bounded autonomous escalation resolution** (BACKLOG **H2** / Phase 2 **PR-C2** of [ADR-003](docs/adr/003-bounded-autonomous-execution.md) / [autonomous-execution-design.md](docs/autonomous-execution-design.md)). Closes the autonomous loop for *pre-authorized* decision types — with the safety model from the original design intact. **Default behavior is unchanged**: the driver halts on every escalation and doesn't even dispatch the Principal. Opt in per-run with an allowlist of bounded ruling classes — `devteam run --auto-rule formatting-only,doc-only` (**CLI-only**, no config persistence; **allowlist-only**, no wildcard). On an escalation the driver dispatches the Principal (invoking the existing, tested `devteam ruling` / `devteam fix-escalation` commands as subprocesses — injectable for tests), reads the Principal's *newest* output via a new ordered `loadPrincipalOutputs()` in `core/escalation.js`, and: applies a `PRINCIPAL-RULING` whose `[class:]` ∈ the grant (`fix-escalation`) then resumes; **halts** on a `PRINCIPAL-CANNOT-DECIDE` (surfacing `cannot_decide.{reason_class, question}` in the run summary), an ungranted/`unclassified` class, or no output. **Hard stops `--auto-rule` can never cross** (halt even with a matching grant): the consequence ceiling (`sign-off`/`deploy`) and `convergence-exhausted`; and a given escalation is auto-ruled **at most once** (re-escalation → halt). Authority provenance — `grant_class`, the `ruling`, and `authority: auto-rule:<class>` — is recorded to `pipeline/run-log.jsonl` (C6 tamper-evident chaining is a follow-up). New `--auto-rule` flag + `auto-ruled` / `auto-rule-dispatch` / `cannot-decide` progress events. Tests: auto-rule paths in `tests/run.test.js` (granted-apply / cannot-decide / ungranted / ceiling-never / once-only / no-grant-no-dispatch) with injected runners; full suite 1138 pass, lint clean. Honest scope note: the driver invokes the CLI commands rather than calling extracted in-process functions — a clean `core/escalation.js` extraction is a noted follow-up. Docs alongside: `docs/runbooks/autonomous-run.md`, `README.md`, `ARCHITECTURE.md` #12, design doc (Phase 2 PR-C2 landed).

- **Typed escalation contract** (BACKLOG **H2** / Phase 2 **PR-C1** of [ADR-003](docs/adr/003-bounded-autonomous-execution.md) / [autonomous-execution-design.md](docs/autonomous-execution-design.md)). Makes the Principal's escalation output *typed*, the prerequisite for any bounded autonomous escalation resolution — and an immediate improvement to the human-driven flow. The Principal now writes ONE of two lines into `pipeline/context.md`: `PRINCIPAL-RULING: <topic> → <decision> [class: <slug>]`, where the optional `[class:]` tags the *kind* of decision (e.g. `formatting-only`, `doc-only`, `known-safe-dependency-bump`) — the category an operator will pre-authorize via `devteam run --auto-rule` (PR-C2); or `PRINCIPAL-CANNOT-DECIDE: <authority|information|value> → <question>` when the decision is underdetermined (commits an ungranted resource, needs a fact outside every artifact, or an unranked value tradeoff — ADR-003 §3.1). A precise cannot-decide is a *correct* outcome that routes the decision to the human who holds the missing authority/information/ranking; it is never auto-resolved. New pure parser module `core/escalation.js` (`parseRulingLine`, `parseCannotDecideLine`, `loadRulings`, `loadCannotDecide`); the ruling prompt (`renderPrincipalRulingPrompt`), `roles/principal.md`, and `rules/escalation.md` carry the contract and the "cannot decide" boundary (rule only what's *derivable*; never inflate a class to fit a grant). `devteam next` now surfaces a `PRINCIPAL-CANNOT-DECIDE` question directly so the operator sees exactly what's needed. **Backward-compatible**: legacy untyped rulings parse as `class: unclassified` and are never auto-applied; no schema migration. **No autonomy change** — escalations still halt for a human (the driver acting on grants is PR-C2). Tests: new `tests/escalation.test.js` (9). Docs alongside: `roles/principal.md`, `rules/escalation.md`, `docs/runbooks/escalation.md`, design doc (Phase 2 PR-C1 landed; PR-C2 scoped).

- **`devteam run` — autonomous fix-and-retry** (BACKLOG **H2**, Phase 1 **PR-B** of [ADR-003](docs/adr/003-bounded-autonomous-execution.md) / [autonomous-execution-design.md](docs/autonomous-execution-design.md)). The driver now **acts** on the machine-fixable cases instead of halting. On a `code-defect` FAIL it clears the failing `pipeline/gates/*` paths the recipe names — extracted in-process from `computeFixSteps`' `rm` steps; the recipe's `devteam stage`/`merge` strings are ignored since the driver's own loop re-dispatches and re-merges — writes the blockers into `pipeline/context.md` under an upserted `<!-- devteam:run-blockers -->` section (cross-stage context so the re-dispatched agent sees *why*), and loops. Bounded by a **driver-side** retry ceiling (`autonomy.max_retries`, default 2) — the authoritative backstop, since `next()`'s `convergence-exhausted` relies on the agent bumping `retry_number`, which the driver doesn't control; on exhaustion it escalates (`resolve-escalation` / `convergence-exhausted`). Adds **`classifyDispatch`** (the H1-deferred dispatch-time classifier, in `core/gates/classify.js`), replacing PR-A's no-progress guard: a dispatch that writes no gate is `transient` (backoff `--retry-delay-ms`, default 30s, then re-dispatch) up to `maxTransientRetries` (default 1), then `structural-input` → halt; a clean exit (code 0) with no gate is structural immediately. Escalations still halt for a human (Phase 2 adds the Principal). New progress events `fix-retry` / `transient-retry` in the log + stderr. Tests: `classifyDispatch` units + fix-retry / transient-recovery / convergence-ceiling / structural / `extractGateClears` cases in `tests/run.test.js`; full suite 1123 pass, lint clean. Honest follow-ups documented: a structured `clear_gates` field on the fix recipe (retire `rm` string-parsing) and gate archiving for progress-based convergence. Docs updated alongside: `docs/runbooks/autonomous-run.md`, `README.md`, design doc (Phase 1 PR-B landed), `ARCHITECTURE.md` #12.

- **`devteam run` — bounded autonomous driver, skeleton + happy path** (BACKLOG **H2**, Phase 1 PR-A of [ADR-003](docs/adr/003-bounded-autonomous-execution.md) / [autonomous-execution-design.md](docs/autonomous-execution-design.md)). A deterministic code loop (`core/driver.js`) that advances the pipeline unattended — `next → dispatch → merge` until `pipeline-complete` — and **halts cleanly the moment a human is needed**. The only LLMs in the loop are the workstream agents it dispatches (in-process via `runStageHeadless`, so it gets the structured `{exitCode, gatePath, timedOut}` a later transient/structural classifier needs). Halts on any `fix-and-retry`/`resolve-escalation` (surfacing the H1 `failure_class`), at the **consequence ceiling** — never advances into `sign-off` (stage-07) or `deploy` (stage-08) without an explicit `--allow-stage` grant — on a `--budget-usd` cap (pre-dispatch, summed from merged stage gates to avoid double-counting), at a `--until` boundary, or on a no-gate dispatch (the interim no-progress guard that closes the infinite-loop hole until PR-B's `classifyDispatch` lands). Introduces run-scoped state the otherwise-stateless-within-a-run model avoids: `pipeline/run.lock` (exclusive, with a stale-pid check + `--force`), `pipeline/run-state.json` (resumable via `--resume`), and `pipeline/run-log.jsonl` (one line per transition — the audit + debug trail). Flags: `--track`, `--until`, `--max-iterations` (default 100), `--budget-usd`, `--timeout-ms`, `--allow-stage` (repeatable), `--resume`, `--force`, `--json`. Exit codes: 0 = complete or a clean configured stop (`--until` / ceiling), 1 = needs attention (FAIL / escalation / no-progress / merge-failed / budget / max-iterations), 2 = lock held. **Scoped — does NOT auto-fix or auto-rule yet** (that is PR-B for `code-defect` and Phase 2 for escalations). `run()` accepts injectable `next`/`runStageHeadless`/`mergeWorkstreamGates` so the loop is unit-testable without spawning hosts. Tests: new `tests/run.test.js` (13 — real-`next()` halt paths + injected-dep dispatch loop); full suite 1113 pass, lint clean. Docs alongside: new [docs/runbooks/autonomous-run.md](docs/runbooks/autonomous-run.md), `README.md` CLI table, design doc (Phase 1 PR-A marked landed; PR-B scoped), and `ARCHITECTURE.md` locked-decision #12 (dispatch-time vs gate-time class split clarified).

- **Typed failure classification on `devteam next`** (BACKLOG **H1**, Phase 0 of [ADR-003](docs/adr/003-bounded-autonomous-execution.md) / [autonomous-execution-design.md](docs/autonomous-execution-design.md)). `next()` historically collapsed every non-pass, non-escalate gate into one `fix-and-retry` action — a corrupt gate file and a failing test got identical handling, and a structural failure that writes no gate could be re-dispatched forever (no `next()`-level circuit breaker). Each non-pass action now carries a **`failure_class`** so the reader (human stage manager today; the autonomous driver later) responds correctly: `code-defect` (change code, re-run), `state-corruption` (gate unreadable — repair it, **don't** re-run), `external-blocked` (a human/external action is required), `judgment-gate` (`status: ESCALATE` — make a ruling), and `convergence-exhausted` (retry budget spent → `next` returns `resolve-escalation` instead of another fix-and-retry). New pure-function module `core/gates/classify.js` (`classifyGate`); the convergence ceiling is a count-based check on the gate's `retry_number` against `autonomy.max_retries` in `.devteam/config.yml` (default 2) — the orchestrator-side backstop for the agent-side self-escalation rule in `rules/gates.md` § Retry Protocol. **Additive and backward-compatible**: the action vocabulary is unchanged (the `halt`/`block` actions and the dispatch-time `transient`/`structural-input` classifier are deferred to the driver in H2, where they have a consumer), and there is **no gate-schema migration** — `failure_class` is derived from existing gate state. `devteam next --json` gains a `schema_version` field (`"1.0"`) for programmatic callers; the human output shows the class as a `[tag]`. Honest limitation documented: true *progress-based* convergence detection (escalate when blocker counts stop decreasing) needs gate archiving and remains a follow-up; today's ceiling is count-based. Tests: new `tests/classify.test.js` (10) + failure-classification / convergence / `--json` cases in `tests/next.test.js`; full suite 1100+ pass, lint clean. Docs updated alongside the code: `rules/gates.md`, `docs/user-guide.md`, `docs/runbooks/fix-and-retry.md`, `docs/runbooks/escalation.md`, `README.md`, and the design doc (§2.5/§2.6 corrected against the as-grounded code; Phase 0 PR-1 marked landed).

- **`devteam consistency analyze` — cross-artifact drift check across the full pipeline chain** (closes BACKLOG **B8** / `cmp-E-1`). Generalizes `devteam spec verify` (which checks brief.md ↔ spec.feature ↔ test-report.md drift) to **every** intermediate artifact + the gate-vs-reality dimension. Five drift classes covered: (1) AC ↔ scenario in spec [delegates to existing G2 logic]; (2) AC ↔ test-report rows [delegates to G2]; (3) **NEW** — AC in brief without a `## Verify` bullet in any `pr-{area}.md`, OR a Verify bullet for an AC not in the brief; (4) **NEW** — red-team `must_address_before_peer_review[]` items that haven't been resolved by stage-05 reaching PASS; (5) **NEW** — gate field claims that drift from the artifact they describe (e.g. `stage-01.acceptance_criteria_count` ≠ actual AC count in brief.md; `stage-06.tests_total` ≠ actual row count in test-report.md). The gate-vs-reality dimension is uniquely possible because Stagecraft has machine-readable gate JSON — no other framework in the 2026 comparative landscape (Spec Kit, BMAD, AI-DLC, OpenSpec, Agent OS, Kiro) can do this check because none has Stagecraft's gate-as-executable-state-seam. New module `core/spec/analyze.js` (~250 lines) with pure-function and file-path wrappers. New `bin/devteam consistency analyze [--strict] [--json]` subcommand renders the report as readable markdown or structured JSON; exits non-zero on any drift. 25 new tests in `tests/cross-artifact-analyze.test.js` (810/810 suite total). README CLI table updated. From the 2026-06-03 comparative analysis (Spec Kit's `/speckit.analyze` was the inspiration).

- **`eslint-plugin-security` enabled** (closes BACKLOG **C7** / `hist-a`). Targeted subset of rules focused on the shell-injection-shape class CodeQL has caught post-merge three times since v0.5.0 (PRs #31, #34, #38). Pre-push catch is the goal. Rules enabled: `detect-child-process`, `detect-eval-with-expression`, `detect-pseudoRandomBytes`, `detect-new-buffer`, `detect-bidi-characters`. Rules deliberately disabled with reasoning preserved in `eslint.config.js`: `detect-unsafe-regex` (flagged 7 bounded line-by-line parsers under operator control — DDL keywords, Gherkin grammar, AC identifiers, YAML config); `detect-non-literal-fs-filename` (Stagecraft legitimately reads dynamic paths); `detect-non-literal-regexp`, `detect-non-literal-require`, `detect-object-injection`, `detect-possible-timing-attacks` (all high false-positive rates in this codebase, none catching a real bug class). The empirical case for adding the plugin was strong (3 CodeQL alerts / week); the empirical case for the disabled rules was weak. Lint suite still 0 violations; test suite still 785/785.

- **`docs/BACKLOG.md` re-prioritized post comparative analysis.** Six new items folded into existing buckets: **B8** cross-artifact consistency analyze (from Spec Kit's `/speckit.analyze`), **B9** bounded workspace deltas (from OpenSpec), **B10** Discover Standards preprocessing (from Agent OS), **C7** `eslint-plugin-security` (from between-cycle observations after 3 CodeQL alerts in one week), **C8** CHANGELOG-per-PR fragments (from recurring `[Unreleased]` merge conflicts), **C9** verify-before-promoting structural enforcement (from the C-1 retraction failure mode), **E9** conversational stage mode (from BMAD's Party Mode). Cross-reference added: G6 (stage shopping) confirmed as the same direction as `cmp-E-3` (adaptive pathways from AI-DLC + BMAD). The stale Top-10 priority queue (all 10 items landed) was replaced with a fresh three-tier queue — top-tier (~30 days, 5 items), mid-tier (~quarter, 5 items), strategic bets (~year, 3 items) — plus 5 consciously-deprioritized items (VS Code extension, more host adapters, documentation gate, ticket/chat integrations, self-modifying pipeline) with reasoning. Item-source tags (`[cmp-E-N]`, `[hist-N]`) make the provenance auditable.

- **`docs/comparative-analysis.md` — Stagecraft vs the AI-dev tooling landscape (2026).** A 300-line positioning document comparing Stagecraft against six adjacent public frameworks: BMAD-METHOD, GitHub Spec Kit, Agent OS, OpenSpec, AWS Kiro, AI-DLC. Synthesized from three independently-written analyses (one generated in Claude Code, two contributed by the operator from external sessions) and verified against current web sources. Includes: (a) a four-school taxonomy of the 2026 AI-dev-framework space, with a complementary 5-layer functional-stack lens; (b) a 10-dimension comparison matrix; (c) per-framework deep-dives; (d) three claims Stagecraft can defend (gate JSON as executable state seam, heterogeneous multi-model dispatch, downstream-of-build coverage); (e) three honest cases where Stagecraft is *not* the best fit; (f) seven evolution opportunities ranked by leverage with effort estimates and a "what Stagecraft should NOT absorb" section; (g) a four-layer composability stack diagram. Linked from README under Reference / extension. Doc-only; no code changes.

- **Between-cycle observations channel in `docs/audit-archive/HISTORY.md`.** Three observations surfaced between audit #2 (2026-06-03) and the next audit, but had nowhere durable to live — they'd be lost from the conversation that produced them. New `## Between-cycle observations` section in HISTORY.md captures them; `skills/audit/SKILL.md` § Phase 3.1 updated to read the section and fold each observation into the new backlog (promoted to a finding with full ratings, or closed-out with a citation). Convention is "observations live with the audit they informed" — at archive time, processed observations move from HISTORY.md into the archived audit's `09-backlog.md` § Project-Specific. First three captured: (a) `eslint-plugin-security` as a P3 candidate — three CodeQL alerts in one week since v0.5.0 suggests the PR 2.1 defer should be revisited; (b) CHANGELOG-per-PR fragments as a P3 — `[Unreleased]` merge conflicts hit 4+ times across Batch 1/2; (c) "verify before promoting" discipline didn't hold even after codification — the C-1 retraction in PR #32 was the same failure mode as the 2026-05-28 audit's S5, suggesting an enforceable mechanism is needed, not just textual guidance.

- *(entry backfilled post-release)* **B2 — Performance budget stage (stage-06e).** New `stage-06e`, role `qa`, between observability-gate and sign-off. Checks Lighthouse Web Vitals (LCP/CLS/FID against the brief's targets), bundle size delta (vs. merge-base), and k6/autocannon load-test throughput against configured budgets (`.devteam/config.yml` `performance.budget.*` or fallback `performance.budget.json`). `budget_exceeded: true` → gate FAIL; `skipped_reason` for non-performance-relevant changes (backend-only, config-only, dep-update). `requiredCapabilities: { shell: true }`. Included in `full`, `quick`, `hotfix` tracks; excluded from `nano`, `config-only`, `dep-update`. `skills/performance-budget/SKILL.md` walks seven steps from tool selection through gate writing. `templates/performance-report-template.md`. Stage journal entries embed budget status, checks run, and Lighthouse score. 25 tests in `tests/performance-budget.test.js`. *Honest scope note:* the stage depends on the project having a Lighthouse-compatible frontend and a load-testing entrypoint; non-applicable projects use `skipped_reason` rather than failing. (closes BACKLOG B2)

- *(entry backfilled post-release)* **B9 — Bounded workspace deltas.** Opt-in isolation mode: when `.devteam/config.yml` sets `pipeline.isolation: bounded`, every in-flight feature's artifacts (prompts, gates, logs) land under `pipeline/changes/<changeId>/` instead of the global `pipeline/`. `changeId` is derived by slugifying `opts.feature`. New `core/paths.js` exports `pipelineRoot`, `gatesDir`, `logsDir`, `prefixPipelineRelative`. `changeIdFromFeature` added to `core/config.js`. `orchestrator.js` computes `ctx.changeId`, threads it into `buildDescriptor` (prefixes `readFirst`/`allowedWrites`/`artifact`), and uses path helpers in `runStageHeadless`/`mergeWorkstreamGates`. `headless.js` routes gate + log files to the bounded directory. `render-helpers.js` writes the bounded gate path into the agent prompt. `validator.js` reads `DEVTEAM_CHANGE_ID` env var to validate gates in the bounded directory. Default `in-place` mode is unchanged — zero impact for existing setups. 35 new tests in `tests/bounded-workspace.test.js`. (closes BACKLOG B9 / cmp-E-2)

- *(entry backfilled post-release)* **B10 — Discover Standards preprocessing.** New `devteam standards discover [--cwd <dir>] [--json] [--dry-run] [--force]` — pure static analysis that scans a project codebase and writes `docs/project-conventions.md`. Detects: tech stack (JS/TS/Python/Go/Rust via manifest files), module system (ESM/CJS/mixed from `package.json type` + source sampling), file layout (top-level dirs + source subdirs), naming style (kebab/PascalCase/camelCase/snake_case plurality), tooling (TypeScript/ESLint/Prettier/Biome/Husky/EditorConfig), test config (framework, co-location, pattern), and most-used imports (regex-based tally, skips builtins). `--dry-run` prints without writing; `--json` emits the structured discovery result; `--force` overwrites an existing file. `core/standards/discover.js` exports `discover()`, `formatReport()`, and individual detectors for unit testing. 67 tests in `tests/standards-discover.test.js`. Pair with `readFirst` lists and AGENTS.md to inject discovered conventions into agent prompts. (closes BACKLOG B10 / cmp-E-5)

- *(entry backfilled post-release)* **C1 — Filesystem-level `allowedWrites` enforcement.** Post-hoc write-audit via git-status diff for adapters that lack hook infrastructure (codex, gemini-cli). New `core/guards/write-audit.js` exports `snapshotWritables` (git status before spawn), `auditWrites` (diff before/after, checked against `allowedWrites` patterns), `isAllowed` (exact-file + directory-prefix matching). `runHeadless` snapshots dirty state before the host process starts and diffs after close; unauthorized writes are logged immediately and returned as `writeViolations[]`. Orchestrator patches the gate to `FAIL` and appends violation messages to `blockers[]` when violations are found. `codex` and `gemini-cli` capabilities updated from `prompt-only` to `post-hoc-audit`; `claude-code` keeps `tool-call-time` (hooks already block writes at dispatch time). `render-helpers.js` caption updated to reflect actual enforcement level. 33 tests in `tests/write-audit.test.js`. (closes BACKLOG C1)

- *(entry backfilled post-release)* **C3 — License compatibility gate.** `stage-04a.schema.json` now requires `license_check_passed` (boolean) and `license_findings[]` (per-package `{ package, license, policy: allowed|warned|denied, note? }`). Default policy table: MIT/Apache-2.0/BSD-*/ISC/CC0-1.0/Unlicense → `allowed`; UNLICENSED/SSPL/BUSL → `warned`; GPL-*/AGPL-*/LGPL-* → `denied`. `roles/platform.md` step 4 replaced with a concrete procedure: license-checker (Node), pip-licenses (Python), cargo-license (Rust) + SPDX classification; fallback advice for missing tools; `.devteam/config.yml license.extra_allowed[]` override for intentional exceptions. `rules/gates-core.md` and `templates/pre-review-template.md` updated with the per-license policy table. Gate skeleton in `stages.js` carries the new fields. (closes BACKLOG C3)

- *(entry backfilled post-release)* **C5 — Capability-required permissions.** All four adapter `capabilities.json` files now declare `enforces.shell` and `enforces.network` (true for claude-code/codex/gemini-cli; false for generic). Four stages that need shell access to do their work declare `requiredCapabilities: { shell: true }` in `stages.js` (pre-review, qa, verification-beyond-tests, deploy). `assertCapabilities()` in `orchestrator.js` is called at dispatch time for every workstream — headless or interactive — and throws a named `CapabilityError` if the routed host lacks a required capability; the error surfaces as an `ESCALATE` gate with a "host does not enforce shell" message. 31 new tests in `tests/capabilities.test.js`. (closes BACKLOG C5)

- *(entry backfilled post-release)* **E7 — `/goal` integration for convergence-shaped stages.** `claude-code` and `codex` now declare `capabilities.goalLoop: true`. `build` (stage-04) and `qa` (stage-06) carry a `goalCondition` template in `stages.js` with a `{workstreamId}` placeholder that `buildDescriptor` resolves at dispatch time. `runStageHeadless` prepends `/goal "<condition>"` to the prompt for any workstream whose adapter has `goalLoop: true` and whose stage has a `goalCondition` — instructing the host to loop until the gate passes rather than exiting after one pass. Non-goal stages and non-goal-loop hosts (gemini-cli, generic) are unaffected. `hosts/gemini-cli/capabilities.json` explicitly declares `"goalLoop": false` so absence is never ambiguous. 30 new tests in `tests/goal-loop.test.js`. (closes BACKLOG E7)

- *(entry backfilled post-release)* **G6 — Stage shopping (AI-inferred tracks).** `devteam assess [--description "..."] [--json] [--apply] [files...]` runs rule-based track analysis: description keyword patterns + path/content heuristics (via `security-heuristic.js` and `migration-heuristic.js`) recommend a track with rationale. Priority order: hotfix keywords → dep-update → config-only → nano → quick → full (default). Heuristic overrides: migration-safety-required bumps lighter tracks to full; security-required bumps nano to quick. `--apply` writes `pipeline.custom_stages` to `.devteam/config.yml`; `custom_stages` is consumed by `next()`, `summary()`, and `runStage()` transparently, overriding `default_track`. `orderedStageNamesForTrack` and `isStageInTrack` now accept custom stage arrays. `trackLabel()` serializes array tracks for OTel span attributes. New `core/stage-shopping/assess.js`. 38 new tests in `tests/stage-shopping.test.js`. *Cross-confirmed by comparative analysis:* AI-DLC dynamic pathway selection and BMAD scale-adaptive depth both validate this direction (cmp-E-3). (closes BACKLOG G6)

### Changed

- **Escalation rendering + dispatch consolidated into `core/escalation.js` (in-process).** Pure refactor closing the PR-C2 follow-up. The Principal-ruling and escalation-applicator prompt renderers, the headless dispatch, the raw-ruling-line loader, and topic derivation moved from `bin/devteam` into `core/escalation.js` (`renderPrincipalRulingPrompt`, `renderEscalationApplicatorPrompt`, `dispatchToPrincipal`, `runRuling`, `runFixEscalation`, `loadPrincipalRulingLines`, `deriveTopicFromGate`). `bin/devteam`'s `cmdRuling` / `cmdFixEscalation` now delegate to these (CLI behavior, messages, and exit codes unchanged — `tests/ruling.test.js` stays green). The autonomous driver (`devteam run --auto-rule`) now renders + dispatches the Principal **in-process** instead of spawning `devteam ruling` / `devteam fix-escalation` as subprocesses — one fewer Node process per escalation, and the driver shares the exact code path the CLI exercises. No behavior change, no new flags; full suite 1148 pass, lint clean.

### Fixed

- **PATCH MODE rendering on all four host adapters** (Phase 1 item 1.5). `--patch --from <stage>` is the centerpiece of the fix-and-retry runbook, but the scoping constraint was silently dropped for workstreams dispatched to `codex` or `gemini-cli`: `hosts/codex/adapter.js` and `hosts/gemini-cli/adapter.js` never read `ctx.patchItems`, so a patched workstream routed to either host received no "fix ONLY these items" instruction. **Fix:** extracted the PATCH MODE block rendering from `hosts/claude-code/adapter.js` and `hosts/generic/adapter.js` into `core/adapters/render-helpers.js` as `renderPatchBlock(ctx, lines)` (claude-code wording canonical), and wired all four adapters to call it. Output for `claude-code` and `generic` is byte-identical to before the refactor (verified by SHA-256 hash of the no-patch path). A comment in `codex` and `gemini-cli` notes the ~95% adapter duplication and points to `plans/phase-3-structural-debt.md` for the deferred base-class refactor. **`[verify-first]` goalLoop on gemini-cli:** `hosts/gemini-cli/capabilities.json` was missing the `goalLoop` key. Investigation confirmed the `/goal` directive is a Claude Code session-level feature with no Gemini CLI equivalent; the absence was intentional. Added `"goalLoop": false` explicitly so absence is never ambiguous (the existing goal-loop test already asserted `!caps.goalLoop`; updated the test description and assertion to `strictEqual(caps.goalLoop, false)`). Tests: 9 new cases in `tests/adapter-contract.test.js` — for every host, descriptor WITH `patchItems` renders the PATCH MODE block; descriptor WITHOUT does not; `absent vs empty patchItems` produces identical output for `claude-code` and `generic`. Full suite 1188 pass (was 1179), lint clean.

- **Stoplist enforced on the autonomous path** (Phase 1 item 1.1 — highest severity). The safety stoplist (auth / credentials / PII / payments / migrations / …) was previously checked only in the interactive path (`devteam stage`), leaving `devteam run` able to silently dispatch lighter tracks on sensitive changes unattended — exactly the path where the guard matters most. Two check-points added to `core/driver.js`: (1) **run-start** — before the first loop iteration, after track resolution; (2) **pre-build** — immediately before dispatching `stage-04 (build)`, catching briefs written by the requirements agent after run-start. On a match the driver halts with `halt_action: "stoplist"`, writes a `stoplist-halt` event to `run-log.jsonl`, and surfaces `explainMatches()` output. `full` and `hotfix` tracks bypass by design (unchanged). `--force` opts out (consistent with the interactive path). `STOPLIST_TRACKS` moved from a local constant in `bin/devteam` into `core/guards/stoplist.js` (exported), so both paths share a single source of truth; `gatherCandidates` now also reads `pipeline/brief.md` so the pre-build check can catch content written mid-run. Tests: 3 new cases in `tests/run.test.js` (quick+match→halt, full+match→no-halt, mid-run brief→pre-build halt); full suite 1171 pass, lint clean. Docs: `docs/runbooks/autonomous-run.md` halt-action table. Honest scope note: `--force` bypasses the autonomous stoplist check as it does the interactive one — it is an explicit, auditable operator override.
- **Gate validator: fail closed where it matters** (Phase 1 item 1.3). Three related hardening changes to `core/gates/validator.js`, which underpins the tamper-evident gate chain and CI blocking:
  1. **`--strict` mode** (also activated by `CI=true` env var): the unknown-internal-error path in `runMain()` — previously "treating as PASS" and exiting 0 — now **exits 1** in strict mode, so a validator bug cannot silently green-light the gate chain in CI. Hook-mode (default) **keeps** warn-and-pass (rationale: don't kill an interactive session on a validator defect — that remains correct and intentional), but now **appends a timestamped entry to `pipeline/validator-errors.log`** so unknown errors are discoverable instead of vanishing. The existing ENOENT (exit 0) and HALT_FS_CODES (exit 1) branches are unchanged.
  2. **CI template and `devteam ci install`** now pass `--strict` to the validator invocation in `templates/ci/github-actions/stagecraft-pr-checks.yml`. Deployed CI pipelines re-generated with `devteam ci install --force` pick up this change.
  3. **Escalation sweep ordering replaced**: `listGates()` previously sorted gate files by **filesystem mtime**, which `git checkout`, `touch`, or any CI workspace copy can change without altering gate content — allowing mtime manipulation to flip the "bypassed escalation" verdict. Ordering is now content-derived: **gate `timestamp` field** (written by the orchestrator at gate-write time) is the primary key, with **stage order from `core/pipeline/stages.js`** as a deterministic fallback for equal or absent timestamps. A comment explains why mtime was wrong. *Honest scope note: hook-mode fail-open is preserved by design — this item only makes the CI/strict path fail closed and the hook-mode failures discoverable.*
  Tests: 7 new cases in `tests/gate-validator.test.js` covering hook-mode exit 0 + log write, `--strict` exit 1, `CI=true` exit 1, and an `fs.utimesSync` mtime-manipulation test asserting the bypass verdict no longer changes. Full suite 1175 pass, lint clean, consistency 235 checks passed.

- **`parseFlags` flag-parsing bugs** (Phase 1 item 1.4). Three documented flags were absent from the shared `parseFlags` vocabulary and exited 2 "Unknown flag" whenever used: `--skip-write` (referenced in `cmdPreflight`), `--skip-preflight` (referenced in `cmdStage`), and `--skip-advise` (referenced in `cmdNext`). All three are now registered as booleans with keys exactly matching the existing checks. Additionally, `--apply` was unconditionally value-consuming — `devteam assess --apply --json` swallowed `--json` as the apply-value (losing JSON output) and `--apply` as the final argument set `flags.apply = undefined` (silently skipping the apply). `--apply` is now peek-ahead boolean-or-value: when the next token is absent or starts with `--`, `flags.apply = true` (boolean, no token consumed); otherwise the value string is consumed as before (preserving `devteam advise --apply AC-11=A`). `cmdAdvise` now errors with a clear message when `flags.apply === true` since it requires a selection string. Orphan audit found no further missing flags beyond these four. Tests: 7 new cases in `tests/cli.test.js`; full suite 1168 pass, lint clean.

- **Bounded isolation (B9) read-side wiring complete** (Phase 1 item 1.6). `core/paths.js` cleanly mapped `changeId → pipeline/changes/<id>/…` and dispatch honored it, but the read side hardcoded `path.join(cwd, "pipeline", …)`: `next()` in `core/orchestrator.js` always looked in `pipeline/gates/`; `summary()` did the same; `tryAutoFoldSignOff` resolved `brief.md`/`test-report.md`/`runbook.md` from the global `pipeline/`; and the driver's lock/run-state/run-log/gates/context paths in `core/driver.js` were always global. In bounded mode, dispatch wrote gates under `pipeline/changes/<id>/gates/` while `next()` checked `pipeline/gates/` — so the pipeline appeared permanently "not started". Changes: (1) `next()` now accepts `changeId` (or derives it from `opts.feature` + config isolation), calls `getGatesDir(cwd, changeId)`, and threads `cwd`/`changeId` through to `_nextImpl` and `tryAutoFoldSignOff`; (2) `summary()` same; (3) `tryAutoFoldSignOff` uses `pipelineRoot(cwd, changeId)` for artifact paths; (4) driver path helpers (`lockPath`, `runStatePath`, `runLogPath`, `gatesDir`, `writeRunBlockers`) all accept `changeId`; (5) `run()` derives `changeId` from `opts.feature` + config isolation (same mechanism as `runStageHeadless`), threads it through every helper, and passes `feature` to `_runStageHeadless` so dispatch and read are in the same bounded subtree; (6) `cmdRun` passes `flags.feature` to `run()`; (7) `_merge` call in the driver now passes `changeId`. All other `path.join(cwd, "pipeline"` hits in `core/` carry a `// B9 exemption:` comment explaining why they are changeId-exempt. Tests: 6 new end-to-end tests in `tests/bounded-workspace.test.js` — `next()` advances past a bounded-path gate; `summary()` reports PASS from bounded gates; in-place mode is unaffected by bounded-path gate files; driver writes run-log/run-state under the change root and not under global `pipeline/`; driver with real `next()` completes when all bounded gates are seeded PASS. Full suite 1185 pass (1188 total, 3 skipped for DEVTEAM_HEADLESS_COMMAND), lint clean. *Honest scope note:* The stoplist brief scan in `runStoplistCheck` still reads `pipeline/brief.md` (global path); in bounded mode the brief lives at `pipeline/changes/<id>/brief.md`. This is noted with a `// B9 exemption:` comment; wiring changeId into `checkStoplist` is a small follow-up.

- **Small hardening basket** (Phase 1 item 1.7 — three fixes in one PR). See `plans/phase-1-trust-consolidation.md` item 1.7.
  1. **`summary()` crash on status-less gate** (`core/orchestrator.js`). A valid-JSON gate file missing the `status` field caused `gate.status.toLowerCase()` to throw `TypeError`, crashing `devteam summary` and the UI `/api/state` endpoint. Applied the `(x || "unknown").toLowerCase()` pattern to both the merged-gate path and the `workstreams[]` mapping so status-less entries render as `"unknown"` instead of exploding. Regression tests: gate `{}` and a workstream entry without `status` both yield `state: "unknown"` without throwing.
  2. **Secret-scan bypass scope narrowed from whole-file to per-line** (`core/hooks/secret-scan.js`). The `devteam-allow-secret:` magic comment previously disabled the *entire* scan for any file containing it — including LLM-written content where one comment could silence all findings across hundreds of lines. New behavior: the comment suppresses findings only on its own line and the immediately following line (comment-above-code style). Every suppressed finding is appended as a JSON record `{file, line, reason, ts}` to `pipeline/secret-allowlist.log` for audit. The stderr help text is updated to describe the narrower scope. Regression tests: comment on line 1 + secret on line 30 → fail; comment adjacent to secret → pass + log entry written.
  3. **Budget-cap blind spot closed** (`core/driver.js`). `totalCostUsd()` previously summed only merged stage gates (`stage-NN.json`), leaving per-workstream gate costs (`stage-NN.<role>.json`) invisible to the budget cap until `mergeWorkstreamGates` ran. The fix includes workstream gate costs when no merged gate exists yet for that stage, and uses only the merged gate once it exists — avoiding double-counting (`mergeWorkstreamGates` already rolls workstream costs up into the merged gate's `cost_usd`). Regression tests: workstream gates totalling > cap with no merged gate → budget halt fires; merged gate + workstream gates → no double-count, no spurious halt.
  Full suite 1195 pass, lint clean. *Honest scope note: `appendAllowlistLog` in the secret-scan hook writes relative to `process.cwd()`. In practice the hook is invoked from the project root (standard Claude Code hook contract), so `pipeline/secret-allowlist.log` lands in the right place; a hook invoked from a non-root directory would write to a different location.*

- **Two GitHub code-scanning alerts** that surfaced after the v0.5.0 push.
  - **HIGH (alert #2): `js/incomplete-sanitization` in `tests/audit.test.js:152`.** The test built a regex via `new RegExp(f.replace(/\./g, "\\."))` to confirm the audit skill references each of the 11 phase output files. The escape only handled dots — not backslashes or other regex metacharacters. The filenames are hardcoded literals so the risk was structural rather than active, but the cleanest fix is to drop the regex entirely: `text.includes(f)` does the same check without any escape concerns. Removes the alert class for that call site.
  - **MEDIUM (alert #1): `actions/missing-workflow-permissions` in `.github/workflows/test.yml`.** Added a top-level `permissions: { contents: read }` block. The default `GITHUB_TOKEN` has overly-broad write scope; the test workflow only reads source (lint, tests, consistency check, devteam-doctor smoke test — no issue / PR / package / release writes), so minimal `contents: read` is correct.

- **CHANGELOG fragments — per-PR fragment files replace [Unreleased] direct edits** (closes BACKLOG C8). The `[Unreleased]` section caused 4+ merge conflicts across earlier PRs; per-PR fragment files under `changelog.d/` end the conflict class — each PR owns one file, nothing collides. `scripts/release.js` gains an `assemble <version>` step that reads all `changelog.d/*.md` files (stable alphabetical order) plus any existing `[Unreleased]` content, folds both into the new version section, and deletes the fragment files. A CI guard (`scripts/changelog-guard.js`, wired into `.github/workflows/test.yml`) fails PR builds that touch `core/`, `bin/`, `hosts/`, `rules/`, `roles/`, or `skills/` without a corresponding `changelog.d/` entry; opt-out via `[skip-changelog]` in the PR title or any commit message. `CONTRIBUTING.md` updated with the fragment recipe (Recipe 5). Tests: four assemble scenarios in `tests/release.test.js`; four guard-logic cases in `tests/changelog-guard.test.js`. *Honest scope note:* the BACKLOG entry proposed `CHANGELOG.next/<slug>.md`; the implemented path is `changelog.d/<slug>.md`, which is the more widely-used convention.

---

## [0.5.0] — 2026-06-03

Post-0.4.0 work, accumulated since `v0.4.0` (2026-05-28). Four themes:
(1) **tightening the build loop** so adversarial findings feed back into
the same stage that produced them (red-team blocker auto-injection +
`--patch`, QA-within-build, orchestrator-stamped verification for
stage-04a/06); (2) **operational ergonomics** for unattended and
recovery runs (parallel workstream dispatch, `--dangerously-skip-permissions`,
configurable stage skips, headless timeout doc, `devteam ruling` /
`derive-approvals` / `restart` / `log` subcommands, `--patch --from`
flow for scoped re-runs, fix-and-retry runbook); (3) **sustained
documentation work** (methodology.md, SOC 2 walkthrough, FEATURES.md,
conventions.md, four-mode audit framing, escalation + fix-and-retry
runbooks, audit-archive convention with skill Step 0.0); (4)
**pre-1.0 hygiene** (ESLint + .editorconfig, secret-scan size cap,
`tryOpen` exec→spawn, security-heuristic magic comment, lazy-require
in `bin/devteam`, cross-host render equivalence test, second self-audit
cycle with 100 % carry-forward from the first).

All additive; no breaking changes to gate JSON, the adapter contract,
or `.devteam/config.yml`. Tracks suite growth: 378 (v0.4.0) → 783 (v0.5.0),
a 107 % increase that tracked feature additions in lockstep. Lint
tooling and the audit-archive convention land as load-bearing
infrastructure for v1.0.

### Added

- **Test coverage completion: cross-host gate-footer equivalence + verify-stamp middle-path** (audit Batch 2 PR 2.4, addresses P2-6 / T-2 and P2-7 / T-3). Two small additions, both pinning behavior that wasn't being explicitly verified.
  - **Cross-host gate-footer equivalence** in `tests/adapter-contract.test.js`: for a fixed descriptor, claude-code / codex / gemini-cli must render *structurally identical* gate-footer content (normalizing the legitimately host-specific `"host":` literal and the `system_prompt_hash`, since the latter is computed over the full prompt including per-host headers). Pins the `renderStagePrompt` de-duplication (commit 38ce2a0, `core/adapters/render-helpers.js`); silent drift in any one adapter's footer would have caused `devteam reproduce` / `devteam replay` to report hash mismatch across hosts without an obvious culprit. Second test confirms each adapter stamps its own host name. Generic is exempt (different render path).
  - **Verify-stamp middle-path fall-through** in `tests/verify-stamp.test.js`: the command-resolution chain is `.devteam/config.yml pipeline.verify.* → package.json scripts.{lint,test} → skip`. The happy path (config provides) and the skip path (neither provides) were tested; the middle path (no config, package.json scripts present) was unit-tested in `verify-runner.test.js` but not exercised through the full stamping flow. New test: `makeTargetProject` (no verify config) + `package.json` with `scripts.lint: "true"` + `scripts.test: "true"` → both commands resolve, run, and stamp exit_code 0; neither shows up as skipped. Catches any future wiring break between `resolveCommands` and the stamp logic.
  - 783/783 suite (was 780; +3 new tests). 0 lint violations.

- **`docs/user-guide.md` gains an "Ad-hoc Principal rulings" subsection** (audit Batch 2 PR 2.3, addresses D-3 / P2-3). `devteam ruling` was in the README CLI table and the escalation runbook but absent from the user-guide ("daily-use reference" per the README doc map). New subsection right after "`devteam next` says `resolve-escalation`" in "When things go wrong": three concrete "when to reach for it" examples (reviewer `ESCALATE-to-Principal:` marker, ADR-vs-implementation drift, reproducibility-hash drift), the "no gate is written; the ruling is an artifact" framing, all four flags with a real-shape example, routing precedence (`routing.roles.principal` → `routing.default_host`), pointer to the runbook for the full playbook. Doc-only.

- **Operational hygiene cluster: `tryOpen` exec→spawn, `devteam-no-security-review:` magic comment, lazy-require for orchestrator** (audit Batch 2 PR 2.2; addresses P2-2 / S-2, P2-4 / Q-4, P2-5 / P-1).
  - **`core/ui/server.js:tryOpen`** switched from `exec(shellStringWithUrl)` to `spawn(cmd, args, {detached, stdio:"ignore"})`. URL is bound by `server.address()` today (safe), but the `exec(string)` shape is exactly the pattern CodeQL's `js/shell-command-injection-from-environment` rule flags — defense in depth against future URL-source changes. Same fix shape as PR #31's test-plumbing fix.
  - **`core/guards/security-heuristic.js`** gains a `devteam-no-security-review: <reason>` magic-comment override (parity with `secret-scan`'s `devteam-allow-secret:` escape hatch). Content scan returns `[]` when the marker is present, suppressing spurious `stage-04b` triggers on doc/example files that legitimately mention security primitives without using them. 2 new tests in `tests/security-heuristic.test.js`.
  - **`bin/devteam` lazy-loads the orchestrator** via a `getOrchestrator()` helper. The orchestrator is the heaviest module to require (~60 ms cold — transitively pulls in the validator, every gate schema, the spawn helper, and every host adapter via the router). Lightweight subcommands (`help`, `stages`, `hosts`, `doctor`, `init`, `validate`, plus the `memory` / `architecture` / `ci` / `spec` subcommands) no longer pay the cost. Cold-start measured: 40-60 ms → 30-40 ms (~25% on the not-orchestrator path). Hot-path commands (`stage`, `next`, `merge`, `summary`) destructure from `getOrchestrator()` at function entry and pay the load cost only when actually invoked. The lazy pattern is also the right ergonomic shape if the CLI surface grows past 25 subcommands.

- **Lint tooling: `.editorconfig` + ESLint flat config + CI step** (audit Batch 2, P2-1, finding Q-2). Style consistency was being held by author convention through ~9k LOC and 99 commits across 8 days — genuinely consistent, but unenforced. Audit's highest-leverage P2 because the cost of retrofit grows with codebase size. New `.editorconfig` (2-space, LF, UTF-8, final newline, trim trailing whitespace except in Markdown). New `eslint.config.js` (flat config, modern ESLint v9): `eslint:recommended` + `no-unused-vars` (with `^_` ignore pattern for caught errors and intentional args) + `eqeqeq` (strict equality, `null: "ignore"` to allow `== null` for null/undefined checks). Browser globals scoped to `core/ui/static/`; tests/scripts share the Node config. `npm run lint` added; CI runs lint *before* tests (`.github/workflows/test.yml`) so style violations fail fast on Node 20/22/24. Cleanup landed inline: 30 unused-vars violations across `core/`, `bin/`, `hosts/`, `scripts/`, `tests/` (mostly leftover imports from refactors); 3 empty `catch {}` blocks annotated with `/* test cleanup; ignore */`; 1 useless escape in a regex char class. No semantic changes — every fix was deletion of dead code or a small annotation. Added `@eslint/js` + `eslint` as `devDependencies`. Test suite still 780/780 + lint 0 violations. Doesn't introduce `eslint-plugin-security` for now — CodeQL is already catching the shell-injection-shape class on PR scans (caught my own bad test code in PR #31 yesterday). If we want local pre-push enforcement for that class, add the plugin in a future P3 follow-up.

- **`secret-scan` hook gains a 1 MB content size cap** (audit Batch 1, P1-1). `core/hooks/secret-scan.js` previously had no size limit on `tool_input.content`, while sibling components (`core/guards/security-heuristic.js`, `core/hooks/approval-derivation.js`, `core/gates/validator.js`) all cap at 1 MB. Risk was fail-OPEN under load: a model writing a very large file could cause the PreToolUse hook to take long enough that Claude Code times it out, and timed-out hooks are non-blocking — so the secret scan would silently be skipped without any signal. New `MAX_SCAN_BYTES = 1_000_000` matches the sibling cap; oversize content exits 0 with a `[secret-scan] ⚠️ content for <file> is N bytes (cap 1000000); skipping scan and allowing.` warning to stderr. Real source files are well under 1 MB; the cap only fires on pathological cases. 2 new tests in `tests/secret-scan.test.js`: oversize content fails-soft with the warning and the buried-AWS-key is NOT detected (proving the scan was skipped); under-cap content still scans normally. The oversize test uses shell-redirected stdin from a temp file because `spawnSync`'s `input` option EPIPEs on ≳500KB stdin — real Claude Code uses streamed pipes that don't hit this artifact. Closes audit finding S-1.

- **Audit-archive convention + skill step 0.0.** Past audits are now preserved under `docs/audit-archive/<date>-<version>-<context>/` rather than overwritten when a new audit runs. New `skills/audit/SKILL.md` § Phase 0 step 0.0 codifies the archive procedure: check whether `docs/audit/status.json` reports a completed prior audit; if so, `git mv` the prior files into a date-stamped archive directory and append a row to `docs/audit-archive/HISTORY.md`. Skips on `--resume`. Both `/audit` and `/audit-quick` slash commands updated to invoke step 0.0 at startup. New Phase 3.1 wording instructs the auditor to read the most recent archived `09-backlog.md` and `10-roadmap.md` and carry forward any items still open — the mechanism that keeps audits cumulative rather than re-discovering the same gaps each cycle. The existing 2026-05-28 self-audit was moved into the archive (`docs/audit-archive/2026-05-28-v0.4.0-initial-dogfood/`) as the first historical entry; HISTORY.md captures its headline (0 P0 · 5 P1 quick wins · 5 P2 targeted · 1 P3 strategic). New `docs/audit/README.md` doubles as the placeholder that keeps the empty current-audit directory tracked and as discovery for the archive convention.

- **`devteam ruling --topic "..." [--headless]` — ad-hoc Principal subagent dispatch.** Tier-4 closes the "no clean headless path for ad-hoc Principal rulings" gap from the user-report follow-up. Use when an escalation needs a Principal judgment (e.g. a reviewer's `ESCALATE to Principal:`) but you don't want to re-run an entire stage. Dispatches the Principal subagent via the configured host's headless command, with a focused prompt that instructs the Principal to read the cited context (`--context paths` + `--target-gate <gate>`), weigh the question, and write a `PRINCIPAL-RULING:` line into `pipeline/context.md` under a `## Principal Rulings` section. Notably: the ruling is an artifact, not a status change — the user still uses `devteam restart <stage>` (must-fix) or hand-edits the escalating gate (defer) to act on it, so the rule that gates are written by their stage's own dispatch is preserved. Routes via `routing.roles.principal` if set, else `routing.default_host`; refuses cleanly when the host doesn't support `--headless`. User-driven mode (no `--headless`) prints the prompt for paste-into-host. 12 new tests across argument handling, user-driven and headless modes, routing precedence, and host-loading errors.

- **Auto-inject red-team blockers into build context + `--patch` for scoped re-runs.** When stage-04c (red-team) writes `must_address_before_peer_review[]`, the validator now auto-injects each blocker into `pipeline/context.md` so the next build invocation sees the findings without manual copy-paste. New `--patch --from <gate>` flag on `devteam stage build` renders a scoped prompt addressing only the cited blockers, rather than a full re-build. Closes the only place in the pipeline where adversarial feedback was previously broken (red-team would find an issue and the implementer would have to manually port it into context). `core/hooks/approval-derivation.js` writes the injection idempotently. See `tests/red-team.test.js` for the round-trip.

- **QA-within-build fix workflow.** When stage-06 (QA) fails on a fix-the-tests-not-the-implementation case, the orchestrator can now dispatch a scoped build re-run that addresses the QA findings without re-running the entire build stage. Reduces wall-clock on the common "test added late, implementation needs a 3-line tweak" loop.

- **`pipeline.skip_stages` config.** Teams that intentionally skip a stage (e.g., `observability-gate` on a docs-only repo) can now declare that in `.devteam/config.yml` and have `devteam next` walk past the stage cleanly, rather than escalating. Pairs with `core/pipeline/stages.js` so skips are visible at orchestrator level, not buried in role briefs.

- **`nano` track gains scoped peer-review.** Audit Tier-2 policy decision: nano was previously `["build", "qa"]`, which skipped the entire review methodology — "even trivial changes deserve a second pair of eyes." Nano is now `["build", "peer-review", "qa"]` with peer-review configured for one reviewer (the backend slot) and `required_approvals: 1`. New `PEER_REVIEW_SIZING` table in `core/pipeline/stages.js` keys per-track sizing; new exports `rolesForStage(stageDef, track)` and `requiredApprovalsFor(stageDef, track)` that the orchestrator's `computeDispatchPlan` and the `approval-derivation` hook consult. Approval-derivation now reads the project's track from config and stamps the right `required_approvals` (1 for nano, 2 for everything else) and `review_shape` (`single` for nano, `matrix` otherwise) on gate creation. Lighter tracks keep their wall-clock advantage; the marquee review property is preserved across every track. Three new tests across `tests/tracks.test.js`, `tests/next.test.js`, `tests/approval-derivation.test.js`.

- **Stage 7 auto-fold actually implemented.** Audit Tier-2 policy decision: EXAMPLE.md and `docs/concepts.md` documented auto-fold as a shipped feature, but `grep -rn auto.fold core/ bin/` returned zero hits — the orchestrator wasn't writing stage-07.json from stage-06 in any code path. Now it is. When the orchestrator's walk reaches sign-off, it checks: stage-06 is PASS, stage-06's `criterion_to_test_mapping_is_one_to_one` is true, `pipeline/brief.md` has at least one AC-N entry, every AC-N is mentioned in `pipeline/test-report.md`, and no stage-07 workstreams have already started. When all conditions hold, the orchestrator writes `pipeline/gates/stage-07.json` with `auto_from_stage_06: true`, `pm_signoff: true`, `deploy_requested: true`, `runbook_referenced` populated from actual file existence, plus an `auto_fold` audit block listing the criteria it found and stamped. The check is *verified*, not trusted: the orchestrator re-derives the AC list from brief.md and the test mapping from test-report.md itself rather than rubber-stamping the QA agent's claim. 9 new tests in `tests/auto-fold.test.js` covering both fold and refuse paths.

- **Orchestrator-stamped verification gates for stage-04a and stage-06.** Audit Tier-2 finding #1 (CRITICAL): every Stage 04a gate field (`lint_passed`, `tests_passed`) and Stage 06 field (`all_acceptance_criteria_met`) was self-reported by the model that did the work — the validator only enforced shape, not truth. The orchestrator now runs the configured commands itself and stamps what it actually observed. New `devteam verify <stage-id>` command does this on demand; `--headless` mode runs it automatically after the stage completes. When the orchestrator's truth disagrees with the model's claim (e.g., model wrote `lint_passed: true` but the lint command exits 1), the gate's status flips to FAIL and a structured `_orchestrator_stamped` block records the override (commands run, exit codes, model claim, orchestrator observation). For stage-06, the orchestrator also cross-references `pipeline/brief.md` AC-N entries against the `AC | Test` mapping in `pipeline/test-report.md` and overrides `all_acceptance_criteria_met` based on its own count. New `pipeline.verify.{lint,test}_command` config keys; falls back to `package.json` scripts; falls back to skip. Two new modules (`core/verify/runner.js`, `core/verify/stamp.js`) and 27 new tests. Role briefs for `platform` (stage-04a) and `qa` (stage-06) now document the stamping behavior so the model knows its claims will be cross-checked.

- **SOC 2 evidence collector walkthrough.** A non-trivial 17-stage trace at `docs/walkthroughs/soc2-evidence-collector.md` — building a SOC 2 evidence collector CLI end to end, with conditional security/migration stages firing for real, adversarial peer review, and property-based verification. Replaces EXAMPLE.md as the canonical full-feature showcase for evaluators who want to see what the full track actually produces. Linked from user-guide and adoption-guide.

- **`docs/FEATURES.md`** — every shipped feature organized by area. Single source of truth for "what does Stagecraft do?", separate from the methodology doc ("why does it do it that way?") and concepts ("what are the primitives?"). Front-of-line for skeptical evaluators.

- **`docs/methodology.md`** — the development methodology Stagecraft enforces: ATDD loop, phase-gate progression, the adversarial red-team layer, multi-role peer review, and the four coding principles. Pulls together what was previously scattered across coding-principles.md, role briefs, and the rules docs into one referenceable explanation of *why* the pipeline is shaped this way.

- **Red-team failure recovery Q&A in FAQ + unattended-pipeline guidance in user-guide.** Two operational gaps users hit in pilot.

- **Forcing function in dev role briefs: `## Verify` section required before PASS.** Audit Tier-2: dev role briefs (backend, frontend, platform) ended with "Write the gate with `status: PASS`" — no forcing function preventing a careless model from rubber-stamping without doing the work. Each brief now requires the implementing dev to write a `## Verify` section in their `pipeline/pr-{area}.md` listing one bullet per acceptance criterion, each carrying (a) the exact command/action and (b) the observed output. Examples per role: backend bullets show `curl` invocations + actual HTTP responses; frontend bullets show user actions + DOM/screenshot evidence; platform bullets show `docker compose` output + health-check status. The gate-writing step is now explicit that PASS without a populated `## Verify` is invalid and will be flagged at peer review. Pairs with the orchestrator-stamped verification PR's stage-06 AC-mapping cross-check — the model is now both forced to claim verification (in writing) and cross-examined by the orchestrator after the fact.

- **Security heuristic gains content scanning.** Audit Tier-3: the prior heuristic was 12 path regexes — fired on every `package.json` change but missed `src/users/login.ts`, `src/handlers/identity.ts`, and code that imports `bcrypt`/`jsonwebtoken`/`crypto.createCipheriv` without a security-flavored filename. The heuristic now scans both paths and file contents: 10 content patterns covering password hashing (`bcrypt`/`argon2`/`scrypt`/`pbkdf2`), JWT operations, OAuth libraries, Node `crypto` primitives, algorithm constants (`AES-256`, `RSA-2048`, `SHA-512`), session/cookie signing, CSRF, authorization function calls (`hasPermission()`, `requireAuth()` etc.), hard-coded credential literals, SQL string concatenation, and security-context `Math.random` use. New path patterns for `login`/`logout`/`signup`/`oauth`/`identity`/`permission`/`session` directories. New structured `analyze(paths, opts)` API returns findings tagged by kind (path vs content) and pattern label so reviewers see *why* each file flagged. 1 MB size cap on content scanning matches `secret-scan`/`gate-validator`. Back-compat preserved: `needsSecurityReview(paths)` and the CLI exit-code contract unchanged. 16 new tests; the heuristic suite goes from 8 → 24.

- **`adapter-contract.test.js` upgraded from existence checks to behavioural assertions.** Audit Tier-3: the prior contract test was 24 assertions of the shape `typeof adapter[m] === "function"`. A method could `return undefined` and still pass; a regression in install/status/uninstall would slip through to user-install time. Now every adapter is exercised against the contract: `renderStagePrompt` must return a non-empty string containing the workstreamId; `install` must return `{written, skipped}` with the documented shape; `status` must return `{ok, missing}` and report `ok:false` on a clean dir; install+status round-trips to `ok:true`; `uninstall` actually deletes the payload from disk (not just unreported by status); install is idempotent. Plus an `enforces.{allowed_writes,stoplist}` enum check. 32 new assertions across 4 adapters (claude-code, codex, gemini-cli, generic); contract suite goes 24 → 56 tests.

- **Concrete examples inlined into `code-conventions`, `security-checklist`, `api-conventions` skills.** Audit Tier-3: these three skills shipped as bullet-list aphorisms ("Don't use `any`", "No SQL string concatenation", "Use ISO 8601 timestamps") with no examples. Aphorisms are forgettable; a model that's never seen what `any → unknown` looks like in a real diff can't recognise the violation in a review. Each rule now has a paired example showing what BAD and GOOD look like — TypeScript `any` vs `unknown`, parameterised SQL, JWT verify vs decode, 404 vs 403 to avoid existence leaks, timing-safe equality, etc. Rules also gain stable `#rule-name` anchors (e.g. `code-conventions#no-stack-leak`) so reviewers can cite the specific failure mode in `REVIEW: CHANGES REQUESTED` comments rather than restating the rule. Skills go from 55/49/59 lines to 143/144/165; the doubling pays for itself the first time a reviewer can write `BLOCKER: code-conventions#no-any` instead of re-explaining it.

- **De-duplicated `renderStagePrompt` across the three host adapters.** Audit Tier-3: claude-code, codex, and gemini-cli each carried ~30 lines of identical text — gate JSON skeleton, orchestrator/host attribution line, cost-telemetry hint, C4 system-prompt-hash computation + line. Three forks meant every prompt-format change had to be made three times and stay byte-aligned across them or replay hashes would drift. New `core/adapters/render-helpers.js` exports `appendGateFooter(lines, descriptor, ctx, hostName)` and `allowedWritesCaption(enforcementLevel, hostDisplayName)`. Adapters now push their host-specific header (claude-code's subagent + patch-mode block, codex/gemini's role-prompt-path line), the objective/readFirst/artifact sections, then delegate the footer. Net adapter LoC: 780 → 714 (-66 lines of duplication); 69 lines in the helper plus a 10-test unit-test file pinning the hash-determinism contract. Adding a fourth adapter is now a ~5-line footer integration instead of a ~30-line copy-paste.

- **`devteam derive-approvals [<file>]` + Stage-5 quorum-miss documentation.** Two coupled gaps surfaced from a real operator run: (a) Stage 5 can FAIL in two distinct shapes — reviewer objections (existing Case 4 in `fix-and-retry.md`, BLOCKER content present) or a quorum miss (no objections but a per-area gate's `approvals.length < required_approvals`); the runbook only covered the first. (b) The fix we initially documented — append `## Review of <area>` with `REVIEW: APPROVED` to a reviewer file — assumed the `approval-derivation` hook fires on the save, but it's registered as a Claude Code `PostToolUse Write|Edit` hook and only fires on agent-driven writes inside an active host session; shell or editor saves bypass it entirely. New `devteam derive-approvals [<file>]` subcommand exposes the hook to operators with a friendly interface: invokes the same `core/hooks/approval-derivation.js` with a synthetic PostToolUse payload (same code, same gate shape, same lock + atomic-write semantics), defaults to processing every `by-*.md` under `pipeline/code-review/` when no argument is given, validates the file lives under `pipeline/code-review/` and matches `by-<reviewer>.md`. 9 new tests covering end-to-end gate updates (single file, no-arg fanout, quorum flip to PASS), JSON output, and error paths. Docs: `fix-and-retry.md` gains Case 5 (~140 lines) with the worked example and an explicit "Why step 2 is needed: the host-lifecycle constraint" subsection; `concepts.md` gains a 4-row Stage-4-vs-Stage-5 vocabulary callout (`workstreams[]` means implementers at Stage 4 but areas-of-code at Stage 5) and updates the Approval-derivation entry; FAQ entry points at both. The hand-edit gotcha is extended to cover the Stage-5 exception.

- **Per-stage rules files split out of `pipeline-build.md`.** Audit Tier-3: `pipeline-build.md` was 358 lines describing nine stages (4 / 4a / 4b / 5 / 6 / 6b / 6c / 7 / 8). The orchestrator agent loaded the whole file at startup regardless of which stages a given run would actually visit. Each stage's procedural rules now live in its own `rules/stage-NN.md` file (9 new files, 14–144 lines each — stage-05 is the largest because peer review has the most procedure). `pipeline-build.md` becomes a 30-line index that lists every stage with a one-line summary and links to its file. `rules/orchestrator.md` startup instructions updated: read the index, load each `stage-NN.md` on demand as the stage dispatches. `pipeline.md`, `pipeline-core.md`, `pipeline-tracks.md`, and `CONTRIBUTING.md` cross-references updated. Install adds 8 new files (40 → 48 in a fresh `devteam init`). No content changes — the split is purely structural; gate schemas in `gates.md` are unchanged because they're consulted by reference rather than read eagerly.

### Changed

- **Parallel workstream dispatch.** Stage 04 and stage 05 (the two multi-role stages) now dispatch their workstreams in parallel rather than sequentially. On a `full` track with 4 build workstreams, this typically cuts wall-clock by 40–60% depending on host responsiveness. Removed an internal `Promise.all`-shaped redundancy that was already serializing work that didn't need to be serialized.

- **Reduced prompt token usage in claude-code adapter.** Trimmed boilerplate and de-duplicated context-loading instructions in the rendered stage prompt; typical reduction is 15–25% input tokens per dispatch with no observable change in output quality. Direct cost reduction for users on per-token-priced model tiers.

- **`devteam init` and the SOC 2 walkthrough sweep.** Comprehensive doc audit pass over README, user-guide, FAQ, presentation-notes — primarily updating stale stage counts (8→12 roles, 6→13 skills) and aligning the 17-stage table across every reference point. Audit-tier-1 fixes from the 2026-06-02 self-audit completed this sweep (examples, walkthrough, api-conventions DELETE claim, FEATURES.md track counts).

- **Stage 5 renamed from "adversarial peer review" to "peer review" / "multi-model peer review".** The audit flagged that all four area reviewers in Stage 5 use the same `reviewer.md` rubric on the same inputs — a fanout across hosts gives execution-diversity (different training data) but not method-diversity. Calling this "adversarial" overclaimed: the adversarial label belongs to stage-04c red-team (a separate role with a separate method: the 10-surfaces walkthrough). Renamed the term across README, methodology, concepts, FEATURES, user-guide, adoption-guide, presentation-notes, faq, BACKLOG, and EXAMPLE. Stage 4c remains "adversarial review" everywhere — that label is accurate and load-bearing.

- **End-to-end orchestrator state-machine test.** Audit Tier-2: every test in the suite seeded gates directly; no test walked `init → next → stage → write gate → next → ...` against a real tempdir, so a regression in `next()`'s stage-transition logic would be invisible to the existing unit suite. New `tests/pipeline-e2e.test.js` walks both the smallest track (nano: build → peer-review → qa) and the full track (all 17 stages, including the multi-role merge for build/peer-review and the conditional-stage skips for security-review/migration-safety). The full-track walk also exercises Stage 7 auto-fold when that feature is present on the branch. Plus one CLI-subprocess smoke test confirming `devteam init` lays down the expected files and `devteam next` reports the first stage. 4 new tests.

### Fixed

- **Validator auto-injects `orchestrator` and `host` fields.** Gates written by adapters without these fields are completed at validation time using the calling adapter's identity, rather than failing the schema. Catches the most common shape error agents make (forgetting one of the two identity fields) without forcing every adapter prompt to re-state them. `tests/gate-validator.test.js` updated.

- **`--dangerously-skip-permissions` in claude-code headless mode.** Without this flag, headless `claude --print` would hang on the first tool that asked for permission, breaking unattended runs. Set on the headless path in `hosts/claude-code/capabilities.json`; documented as a deliberate trust-the-prompt-discipline tradeoff for the headless mode only.

- **Missing YAML frontmatter on 6 skill files.** Claude Code's skill loader skips skills without frontmatter; six SKILL.md files that shipped during 0.4.0 had been silently invisible. Added the standard `name:` + `description:` block.

- **Malformed ISO timestamps in `examples/sms-opt-in/pipeline/gates/stage-04.*.json`.** Four workstream gates carried `T15:020:00Z` / `T15:010:00Z` (extra digit in minutes); fixed to `T15:20:00Z` / `T15:10:00Z`. The example users copy to seed their own runs is now valid.

- **`docs/walkthroughs/stage-04-split-host.md` rewrite.** The walkthrough was a pre-0.1 design exercise dressed up as a current trace — referenced commands and paths that no longer exist (`devteam status --advance`, `/devteam:stage`, a non-existent pm skill) and proposed a contract that has since shipped. Rewritten as a post-implementation trace using today's CLI, today's `capabilities.json`, and real gate JSON from `examples/sms-opt-in/`.

- **`skills/api-conventions/SKILL.md` DELETE 204 claim.** The skill stated "DELETE returns 204, not 404" as a flat rule contradicting its own 404 entry; now explicit that this is a deliberate project convention (idempotent DELETEs, retry-friendly) rather than a universal HTTP rule, with reviewer guidance about not blocker-ing standards-conformant third-party code.

- **`docs/FEATURES.md` track counts.** Quick=9 (not 7), nano=2 (not 3); rules install to `.devteam/rules/` (not `.claude/rules/`).

- **Stale role/skill/template counts across README, EXAMPLE.md, user-guide, presentation-notes.** Numbers had drifted as the repo grew: 8→12 roles, 6→13 skills, 12→15 templates, 3→4 hosts (gemini-cli added). README repo-layout block updated to include `core/memory`, `core/spec`, `core/ui`, and `hosts/gemini-cli/`. Hooks list updated to include secret-scan on `PreToolUse`.

---

## [0.4.0] — 2026-05-28

Eight commits since `v0.3.0`. This release closes out the audit's top-11 recommendations (11/11 done, plus E6 as a bonus) and adds two more pipeline stages, taking the total to 17. The arc: record what AI runs (C4) → replay and diff them (E6) → publish gate state to CI (F4) → catch unsafe migrations (B5) → close the AC→spec→test loop (G2) → verify beyond example tests (G7). All additive — no breaking changes to gate JSON shape, host adapter contract, or `.devteam/config.yml` schema. The pipeline is now what an SOC 2 / EU AI Act reviewer asks for: every gate captures *what* configuration produced it, the runtime can replay any past gate and surface drift, CI surfaces gates as check runs, and three new safety stages (migration / executable-spec / verification-beyond-tests) raise the verification ceiling beyond "tests pass."

| Audit theme | What ships it |
|---|---|
| **Reproducibility + audit trail** | **C4 (gate captures model_version / temperature / seed / system_prompt_hash / tools_hash)** + **E6 (devteam replay <stage>)** |
| **CI integration** | **F4 (`devteam ci install` drops a GitHub Actions workflow that validates + publishes gates as check runs — does NOT run the LLM pipeline in CI by design)** |
| **Verification beyond example tests** | **G7 (verification-beyond-tests stage with the verifier role: property-based / mutation / formal)** |
| **Specification rigour** | **G2 (executable-spec stage: AC-N in brief.md ↔ Scenario @AC-N in spec.feature ↔ test row in test-report.md; drift caught structurally by `devteam spec verify`)** |
| **Data-layer safety** | **B5 (migration-safety stage with veto power: empty rollback / untested rollback on breaking change / missing backfill strategy each auto-veto)** |

Public surfaces unchanged from 0.3.0. New CLI subcommands (`devteam reproduce`, `devteam replay`, `devteam ci`, `devteam spec`) are purely additive. New stages all default to `full` track (except B5 which also runs on `hotfix` + `config-only`); lighter tracks are unaffected.

### Added

- **G7 — Verification beyond tests (stage-06d).** New stage between observability-gate (06c) and sign-off (07) that applies systematic verification methods AFTER stage-06 (qa) PASS. New `verifier` role (read-only on production code, writes property tests under `src/tests/property/` and formal specs under `pipeline/formal/`) inventories candidates from the diff and picks the right method per code shape: property-based testing (fast-check / hypothesis / proptest) for pure functions / parsers / transforms; mutation testing (stryker / mutmut / mull) for critical business logic with existing test coverage; formal verification (TLA+ / Alloy / Lean) for concurrent state machines / consistency invariants / safety properties. Skip with reason for glue/UI/CRUD. Gate (`core/gates/schemas/stage-06d.schema.json`) records `methods_attempted[]` (enum constrains to property/mutation/formal plus `attempted_but_blocked:<method>` variants for honest reporting when tooling isn't installed), `methods_skipped[{method, reason}]` (reason required minLength: 1 — schema enforces that "didn't have time" isn't a legitimate skip), `candidates_inventoried`, per-method stats objects (`property_based`: properties_asserted/cases_tried/counterexamples_found/tool; `mutation`: mutants_generated/killed/survived/timed_out/score/threshold/tool/target — the pre-declared `threshold` is audit-grade, prevents goal-post moving; `formal`: property_modeled/spec_path/tool/depth_explored/counterexample_found), `findings_count`, `blocking_findings[]` (each requires method + summary), `non_blocking_findings[]`. A surviving mutant on a critical path, a property counterexample to a stated invariant, or a formal counterexample to a safety property populates `blocking_findings[]` → stage FAIL → implementer addresses → re-run (analogous to red-team's `must_address_before_peer_review[]`). New `skills/verification-beyond-tests/SKILL.md` walks five phases (inventory → pick → apply → triage → report) with a code-shape → method selection table, the full property-shape vocabulary (round-trip / idempotence / commutativity / associativity / monotonicity / invariant preservation / reference-implementation / oracle), concrete example invocations per method, and a documented set of failure modes (properties that just re-state the implementation; 100% mutation scores that signal tautological tests; formal proofs of trivialities; counterexample dismissal). New `templates/verification-report-template.md` carries sections per method + candidate inventory + skipped methods + triage + recommendations + the four-shape approval line. Role brief (`roles/verifier.md`) is explicit about distinct-from boundaries (qa = floor, red-team = pre-build adversarial, verifier = post-tests systematic ceiling), the not-faking-runs contract (tool missing → `attempted_but_blocked` with install hint), and escalation triggers (counterexample to spec rather than implementation; 100% mutation score; formal violation suggesting design assumption was wrong). Track inclusion: `full` only — the heavy stuff lives on the track that explicitly opted into rigour-over-speed; other tracks rely on stage-06 example tests as their floor. ROLE_FRONTMATTER entry on claude-code (opus model, full Read/Glob/Grep/Bash/Write surface); codex / gemini-cli / generic auto-discover via `core/roles.listRoles()`. 13 new tests in `tests/verification-beyond-tests.test.js` (stage shape, ordering, track inclusion, schema required fields + enum + minLength constraints + blocking_findings shape, role brief shape, skill structure with selection vocabulary, template sections, claude-code adapter, install roundtrip for both claude-code and codex, stage prompt rendering). 2 new `tests/tracks.test.js` cases. Auto-picked-up contract assertions in `tests/contract.test.js` covered the new stage→schema mapping, role brief presence, and ordered-vs-keys correspondence without modification. Strategic value: stage-06 verifies the cases the author thought of; stage-06d verifies the cases nobody thought of. The shape of the gate makes it impossible to claim verification was done without saying which methods, what was found, and what was skipped + why — drift between "we have tests" and "we have evidence" gets caught structurally.

- **G2 — Closed-loop AC → exec spec → tests (stage-03b).** New stage between clarification (stage-03) and build (stage-04) that translates each numbered acceptance criterion (`AC-N` in `pipeline/brief.md`) into one Gherkin Scenario in `pipeline/spec.feature`, tagged `@AC-N`. The .feature file becomes the canonical contract that QA's tests must map to. Drift across the chain — brief.md ↔ spec.feature ↔ test-report.md — is caught structurally rather than by hope. New `core/spec/gherkin.js` parses Feature: / Scenario: / Scenario Outline: / Given|When|Then|And|But / tags (including inline `@AC-N` in scenario names as a fallback). New `core/spec/verify.js` extracts AC-Ns from brief.md (tolerant of bullet markers, optional colon/dash, indentation), AC refs from test-report.md, and computes a drift report with five distinct error classes: `orphan_criteria` (AC in brief, no scenario), `orphan_scenarios` (scenario in spec, no AC tag or AC not in brief), `duplicate_criteria` (same AC-N twice), `orphan_in_tests` (AC in brief, no test reference), `unknown_in_tests` (test references AC not in brief); plus informational `multi_mapped_criteria` (one AC, many scenarios) which `--strict` mode promotes to drift. New `devteam spec verify [--strict] [--json]` CLI runs the drift detector and exits non-zero on any drift; `devteam spec generate [--feature "..."] [--force]` scaffolds the .feature file from brief.md with one tagged `Scenario:` per AC and TODO Given/When/Then placeholders. Gate (`core/gates/schemas/stage-03b.schema.json`) carries `criteria_count`, `scenarios_count`, the full `criteria_to_scenario_mapping` array, `all_criteria_mapped`, `orphan_scenarios`, `orphan_criteria`, `drift`. QA's stage-06 schema extended with `scenarios_total`, `scenarios_covered`, `all_scenarios_have_tests` so the spec-to-test side of the chain is also enforceable. PM role brief gets a new "On an Executable-Spec Request" section walking the procedure; QA role brief instructed to read spec.feature as the canonical behaviour list. New `skills/spec-authoring/SKILL.md` walks five phases (load context → scaffold → fill in Given/When/Then → verify drift → write gate) with a drift-cause table and Given/When/Then guidance. New `templates/spec-template.feature` carries the Feature/Scenario scaffold; `templates/brief-template.md` updated to use numbered AC-N entries (the load-bearing contract); `templates/test-report-template.md` updated to a 4-column `AC | Scenario | Test | Result` mapping table. Tracks: `full` + `quick` (the tracks with a requirements stage to derive ACs from); skipped on `hotfix`/`nano`/`config-only`/`dep-update`. No new role added — the PM that authored ACs is the right brain to translate them; same brain = no translation drift. Auto-picked-up adapter contract assertions in `tests/contract.test.js` covered the new stage + schema + role updates without modification. 36 new tests in `tests/spec-g2.test.js` (Gherkin parser edge cases, AC extraction, drift detection across every error class, generateScaffold, verify(cwd) file-based, stage shape + ordering + track inclusion, schema fields, template/skill/role shape, CLI verify exit codes + JSON output, generate scaffold + --force, install roundtrip, stage prompt rendering). 4 new `tests/tracks.test.js` cases. 4 existing `tests/next.test.js` cases updated to seed the new `stage-03b` gate alongside `stage-03`. Strategic value: the brief is in prose, tests are in code, and the gap between them is where regression hides. Gherkin is the contract that keeps both sides honest — and the verifier is what makes the contract enforceable rather than wishful.

- **B5 — Migration safety stage (stage-04d).** New conditional safety stage between red-team (4c) and peer-review (5). Fires when `stage-04a`'s pre-review heuristic flags data-layer changes — schema files, migration directories, ORM migrations, or files containing DDL fragments (`ALTER/CREATE/DROP TABLE`, `ADD/DROP COLUMN`, `RENAME`, index DDL). The heuristic (`core/guards/migration-heuristic.js`) does path-pattern matching plus optional content scanning for DDL inside non-obvious paths. New `migrations` role brief (read-only on code), new `skills/migration-safety/SKILL.md` walking six questions per migration: what does it do? is it breaking? does it need a backfill? a dual-write window? what's the rollback plan? was it tested? Gate schema (`core/gates/schemas/stage-04d.schema.json`) enforces non-empty `rollback_plan`. **Has veto power** like stage-04b security: empty rollback plan, untested rollback on a breaking change, or missing backfill strategy when backfill is required each auto-veto. Peer-review approvals CANNOT override a veto — the migrations role must personally re-review. Included in `full` + `hotfix` + `config-only` tracks (the tracks where schema changes can plausibly land); skipped on `quick` / `nano` / `dep-update`. Template `templates/migration-safety-template.md` mirrors the six-question structure. ROLE_FRONTMATTER entry on claude-code; codex / gemini-cli / generic auto-discover via `core/roles.listRoles()`. 20 new tests in `tests/migration-safety.test.js` (heuristic patterns + DDL content scan + stage definition + ordering + schema + role brief + skill + template + adapter integration + install roundtrip + render check) plus 4 new `tests/tracks.test.js` cases. Strategic value: data-layer changes are the bug class that bites hardest in production; this stage forces the backfill + rollback plan to exist + be tested BEFORE peer review, with veto teeth.

- **F4 — CI runner integration (GitHub Actions).** New reusable workflow template at `templates/ci/github-actions/stagecraft-pr-checks.yml` that validates `pipeline/gates/*.json` with Stagecraft's validator and posts each gate as a GitHub check run on the PR head via `scripts/pr-publish.js`. Includes an advisory `devteam reproduce` drift check (continue-on-error). Skips cleanly when the PR doesn't touch `pipeline/`. New CLI: `devteam ci install [--ci github-actions] [--out <dir>] [--force]` drops the template into the target project's `.github/workflows/`; `devteam ci show` previews. The deliberate shape: the workflow does NOT run the LLM pipeline itself in CI (cost prohibitive, defeats the human-in-the-loop design). It surfaces gates that local runs produced — reviewers see "10/12 stages passing" in the PR status bar with click-through. Required GitHub permissions are scoped to the workflow run (`checks: write` for posting, no PAT needed). 12 tests in `tests/ci.test.js` covering template shape, action version pinning, install, --force overwrite, --out redirect, --ci unknown error path, `ci show`, usage. GitLab / Buildkite / CircleCI templates are BACKLOG follow-ups — the Stagecraft side is CI-agnostic; only template files needed. See `docs/ci.md` for the full rationale.

- **E6 — `devteam replay <stage-id>`.** Re-runs a recorded stage against the CURRENT configuration, writes the new gate to `pipeline/gates/replay/<stage-id>.<timestamp>.json` (subdirectory, deliberately outside what the validator scans), and diffs the original vs the replay across status / blockers / cost / tokens / duration / reproducibility fields. `--dry-run` prints the plan + prompt-hash drift check without invoking the host. `--json` for tooling. Detects "host exited 0 but wrote nothing" by capturing the original gate's mtime before invoking and requiring it to advance — a real bug caught during testing. Pairs with C4: C4 records what ran, E6 re-runs and surfaces drift. The drift surface is the audit-grade output (six months later, "would replay match?" is a one-command question). Per-invocation param overrides at the host CLI level (pinning model_version / temperature / seed during replay) remain a C4 follow-up — replay uses current config and makes the drift visible rather than pretending to recreate the original environment. 7 tests in `tests/replay.test.js` covering usage, missing gates, dry-run (drift + match), JSON shape, no-gate-written detection, and end-to-end replay with a synthetic host. See `docs/reproducibility.md` § Replay.

- **C4 — Reproducible runs (recording half).** Every gate can now carry an audit-complete record of how an AI decision was made: optional fields `model_version`, `temperature`, `seed`, `max_tokens`, `system_prompt_hash`, `tools_hash`. `core/reproducibility.js` ships `sha256`, `hashSystemPrompt` (trailing-whitespace-normalized so the same logical prompt hashes the same across line-ending platforms), `hashTools` (sorted + deduped so tool order doesn't change the hash), `reproducibilityFingerprint`, `compareFingerprints`, and `replayReadiness` (classifies a gate as `full` / `partial` / `incomplete`). All three host adapters compute the system-prompt-hash inline during `renderStagePrompt` and embed it in the gate skeleton hint, so the agent stamps it verbatim instead of re-computing. New `devteam reproduce <stage-id>` subcommand reads a gate, prints recorded fields + readiness classification, and (when possible) re-renders the current prompt to surface hash drift — the answer to "would the same prompt render today?". **Config-side pinning** (`.devteam/config.yml reproducibility.model_pins`) and **actual replay** (E6) are deferred to follow-up commits; this lands the recording layer that both will read from. Strategic value: the gate JSON is now what SOC 2 / EU AI Act compliance reviews ask for — a complete record of what configuration produced each artifact. 24 new tests in `tests/reproducibility.test.js` covering hash determinism + normalization, fingerprint extraction, drift detection, readiness classification, CLI surface, and schema declarations. See `docs/reproducibility.md` for the honest framing of what "reproducible LLM run" actually means (recording vs. determinism).

---

## [0.3.0] — 2026-05-29

Twenty commits since `v0.2.0`. All four "differentiating bets" from `docs/BACKLOG.md` are now operational — this release marks the line between "structured AI dev pipeline" and "structured AI dev pipeline that learns, remembers, and includes an adversary."

| Bet | What ships it (✓ across all four) |
|---|---|
| **Diversity beats monoculture** | G1 (peer-review fanout, v0.2.0) + **G4 (red team, this release)** + **D4/D5 (adaptive routing, this release)** |
| **Evals are the rate-limit** | D1 (OTel, v0.2.0) + D2 (dashboards, v0.2.0) + **D6 (cost telemetry, this release)** |
| **Memory + persistence** | D7 (per-project, v0.2.0) + **D3 (cross-project) + G8 (architecture continuity, this release)** |
| **The unit is the team, not the model** | **G4 sharpens it (this release)** + the whole architecture |

The arc of this release: measure what each model costs (D6) → score which model is best at which role (D4) → recommend config swaps (D5) → add an adversary that breaks what was just built (G4) → share architectural decisions across projects (D3) → make the architect remember (G8). No new breaks to gate JSON shape, host adapter contract, or `.devteam/config.yml` schema — additive throughout. Public surfaces unchanged from 0.2.0.

### Added

- **D3 + G8 — Cross-project memory + architecture continuity.** Two BACKLOG items shipped together because G8 reads from the foundation D3 lays.
  - **D3 — Org-shared memory.** New store rooted at `~/.stagecraft/memory/` (overridable via `STAGECRAFT_ORG_MEMORY_DIR`). New `core/memory/index.js` exports `promote`, `queryOrg`, `statsOrg`, `clearOrg`. CLI: `devteam memory promote [<kinds...>]` (default `adr` + `lessons-learned`); `--org` flag on `query`, `stats`, `clear` targets the shared pool. Org records carry `project_cwd` attribution so query results name their source project. Idempotent promote, embedder-mismatch guard, explicit opt-in (nothing flows automatically). The per-project store from D7 is unchanged; sharing is additive and deliberate.
  - **G8 — Architecture continuity.** Principal role brief now instructs querying org memory for prior ADRs before drafting a new design — prior ADRs are binding commitments unless explicitly superseded via a new ADR with a `Supersedes:` field + rationale. ADR template gains `Supersedes:` + a "Prior commitments considered" section. design stage's gate optionally records `adrs_consulted` + `adrs_superseded` arrays (audit trail). New `devteam architecture lookup "<topic>"` subcommand — friendlier wrapper around `memory query --org --kind adr` that the role brief points at. Strategic outcome: the "architect always remembers" bet from BACKLOG is operational; architecture doesn't drift because every new design opens with org-memory consultation. 14 new tests across `tests/memory.test.js` (D3 promote/query/stats/clear) and `tests/architecture-continuity.test.js` (G8 role brief, ADR template, gate fields, subcommand, end-to-end cross-project lookup).

- **G4 — Red team role (stage-04c).** New adversarial-by-design role and stage between security-review (4b) and peer-review (5). Always-on for `full` + `hotfix` tracks; skipped on lighter tracks. Walks 10 attack surfaces — input boundaries, state, sequence, integrations, auth edges, resource exhaustion, failure modes mid-operation, abuse cases, downstream effects, observability gaps — and produces **concrete reproducers** (not vibes). Findings are triaged by severity × likelihood × scope; the `must_address_before_peer_review` array blocks Stage 5 until the implementer addresses each item by re-running build. New `roles/red-team.md` (read-only on code, like `reviewer`); new `skills/red-team/SKILL.md` with the methodology and a "diversity matters — route to a different host than the build agents" recommendation; new stage entry in `core/pipeline/stages.js`; new `core/gates/schemas/stage-04c.schema.json`; new `templates/red-team-report-template.md`. claude-code adapter gets a ROLE_FRONTMATTER entry for `red-team`; codex / gemini-cli / generic pick it up automatically via `core/roles.listRoles()`. 10 new tests in `tests/red-team.test.js` + 3 new `tests/tracks.test.js` cases for track inclusion. Distinct from stage-04b security review (narrower remit, conditional, has veto) and stage-05 peer review (general code review).

- **The "routing-learns-itself" arc — D6 + D4 + D5.** Three commits realize the BACKLOG's "diversity beats monoculture" bet: the system measures which (role, host) combinations work best and recommends config changes.
  - **D6 — Cost telemetry.** New optional gate fields (`tokens_in`, `tokens_out`, `cost_usd`, `model`, `duration_ms`). New `core/pricing.js` with $/Mtok pricing tables for Claude / GPT / Gemini families. New `--view cost` flag on `scripts/dashboard.js` (`npm run dashboard:cost`) rolling up tokens / dollars / duration per host / role / stage. `mergeWorkstreamGates` sums per-workstream cost into stage totals. Adapters' renderStagePrompt asks agents to fill in cost fields when measurable. See `docs/cost.md`.
  - **D4 — Per-role per-model performance scores.** New `scripts/performance.js` (`npm run performance`). For each `(role, host)` pair: dispatches, first-try pass rate, mean retries, mean cost, **cost per pass** (unit-cost of a successful dispatch), mean duration, distinct models seen. Headlines pairwise comparisons. Multi-project rollup. The data layer feeding D5.
  - **D5 — Adaptive routing.** New `scripts/routing-suggest.js` (`npm run routing:suggest`). Reads the same gate history, compares against the current `.devteam/config.yml`, proposes role-level routing swaps. Minimum-dispatch threshold (5 default) + minimum pass-rate delta (10pp default) prevent noisy recommendations. YAML-diff output by default; `--apply` rewrites the config after a confirmation prompt (or `--apply --yes` for CI). Honest about insufficient-data cases. End-to-end demo: synthetic history of backend on codex (100% first-try @ $0.24) vs backend on claude-code (33% @ $1.71) produces a clean `backend: codex # was: claude-code` patch.
- **Self-audit dogfood** — full audit run of Stagecraft using the new `/audit` feature, committed at `docs/audit/00-project-context.md` through `10-roadmap.md` + `status.json`. Acts as a reference artifact (users see what audit output actually looks like) and surfaced the follow-up work below. Notable finding: Phase 2.1 promoted a UI path-traversal concern (S5) based on signature reasoning, then RETRACTED it after a live curl exploit attempt returned HTTP 404 — codified as a "verify before promoting" discipline in `skills/audit/SKILL.md`. Referenced from `docs/user-guide.md` § Auditing a codebase as a concrete example of the output.

### Changed (audit follow-up work)

- **Validator `node:` import prefix** (`core/gates/validator.js`). Was the only file using bare `require("fs")` / `require("path")` instead of the `node:` form. Consistency fix.
- **`docs/TESTING.md` test-count freshness.** Rewrote the summary line to stop quoting a specific number (the count drifts every commit); now says "~380 tests across 25+ files (exact counts in `npm test` output)."
- **`tests/consistency-meta.test.js`** — meta-test that spawns `node scripts/consistency.js` and asserts exit 0. Ensures `npm test` alone catches contract drift, not just CI.
- **`AGENTS.md` — documented two unstated conventions:** `node:` prefix on built-in imports, and stdout/stderr separation (stdout for primary output, stderr for warnings + framing + logs). The framing-on-stderr norm is load-bearing — `devteam stage ... > prompt.md` works correctly because of it.
- **`skills/audit/SKILL.md` § Process discipline.** New section codifying "verify before promoting": any finding past LOW confidence must be backed by direct evidence (live exploit attempt, code path trace, test run, git log) — not signature-only reasoning. References the actual S5 retraction in the self-audit as a worked example.
- **`tests/visualize.test.js`** (4 tests) — `scripts/visualize.js` had no direct coverage. Tests default rendering, `--track nano` produces smaller graph, `--tracks` renders multiple, unknown track is handled.
- **`tests/pr-pack.test.js`** (8 tests) — `scripts/pr-pack.js`'s `buildPRBody` helper now has unit tests: empty pipeline placeholder, brief H1 → PR title, brief §Problem → Summary, per-role pr-*.md sections, merged stage-04 workstreams table, stage-06 test results, design-spec mention, determinism modulo timestamp.
- **`devteam stage --headless --timeout-ms N`** — caps each workstream's wall-clock (default 600000ms / 10 min; pass 0 to disable). SIGTERM with a 5s grace window, then SIGKILL. Result reports "TIMEOUT after Nms" vs "exit N, Nms". Closes the "hung host CLI hangs CI indefinitely" risk. 2 new tests in `tests/headless.test.js`.
- **Asymmetric template-doc coverage documented** in `docs/concepts.md`. Per-template annotation guides (`docs/<artifact>-template.md`) exist for brief / design-spec / runbook because humans read them end-to-end; the other 9 templates are agent-facing and don't need separate annotation. Made explicit instead of inferred.
- **Inline comments** on `workstreamId()` (`core/orchestrator.js`) and `KNOWN_HOSTS` (`core/hooks/approval-derivation.js`) — small clarity improvements in hot files. `KNOWN_HOSTS` comment now spells out the sync requirement (adding a host adapter requires adding to the set, otherwise fanout review gates collide across hosts).
- **Adapter de-duplication — single source of truth for the role list.** New `core/roles.js` exports `listRoles()` which scans `roles/*.md`. The codex and gemini-cli adapters now derive their `ROLES` array from there; claude-code keeps `ROLE_FRONTMATTER` (per-role model / tools / permissionMode metadata) but warns at install if a brief exists without a corresponding entry. Adding a new role brief is now a single edit — every host picks it up automatically.
- **Adapter de-duplication — shared install helpers.** New `core/adapters/base-install.js` exports `installRules` / `installSkills` / `uninstallRules` / `uninstallSkills` — the install logic that was character-identical across all three adapters. Per-host work (claude-code's `installCommands` + `installSettings`, each adapter's `installRoles`) stays in the adapter. LOC reduction: claude-code 404→369 (-35), codex 233→172 (-61, -26%), gemini-cli 234→173 (-61, -26%). Net 871→823 LOC of pure duplication eliminated. The next adapter add (BACKLOG A2) should be ~150 lines instead of ~250.

### Added

- **Codebase audit feature** (`docs/BACKLOG.md` E8). Read-only end-to-end analysis pass with prioritized roadmap output — separate from the 13-stage pipeline (which builds features; the audit analyzes existing code). New `skills/audit/SKILL.md` defines 4 phases (Bootstrap → Health Assessment → Deep Analysis → Roadmap) producing 11 output files in `docs/audit/00-project-context.md` through `docs/audit/10-roadmap.md`. New `roles/auditor.md` (read-only by design — never writes source). New `/audit` and `/audit-quick` slash commands installed by the claude-code host adapter; the audit skill + auditor role brief also install for codex and gemini-cli hosts (no slash commands there, but the skill is invocable). 11 phase output templates in `templates/audit/` as framework-side reference. Resume capability via `docs/audit/status.json`. Monorepo-aware. Extensible via `docs/audit-extensions.md` for project-specific checks (compliance frameworks, custom security policies, team conventions). 9 new tests in `tests/audit.test.js`; 15 new consistency checks in `scripts/consistency.js`. Fixes the dangling `scripts/audit.js` reference in `ARCHITECTURE.md` that's been wrong since v0.1.0.

- **Documentation uplift across three tiers.** Major rewrite of seven docs to bring Stagecraft to parity with claude-dev-team's documentation quality. New: `docs/presentation-notes.md` (13-slide deck + speaker notes, ~22KB, with timing references and Q&A primers), `docs/brief-template.md`, `docs/design-spec-template.md`, `docs/runbook-template.md` (section-by-section "what to write, why, what to skip" guides for the three load-bearing artifacts). Rewritten: `docs/concepts.md` (restructured around a 6-primitives table), `docs/user-guide.md` (14KB → 26KB, adds "shape of one run" diagram + "Your three moments of control" framing + sections on UI / memory / OTel / fanout), `docs/adoption-guide.md` (10KB → 16KB, deeper Q&A answers + 12-month success milestones), `docs/faq.md` (10KB → 22KB, +25 questions across 6 new topic groups), `EXAMPLE.md` (adds a hotfix-track walkthrough as a second worked example), `README.md` (problem-first hook + "First 30 minutes" checklist + documentation map). New BACKLOG entry E7 for `/goal` integration.

- **`devteam stage` onboarding framing.** In user-driven mode (the default), the rendered stage prompt is now wrapped with a preamble that names the stage, explains that `devteam` does not call a model, and lists the three ways to feed the prompt to a host (Claude Code paste, `/devteam stage <name>` slash command, or `--headless` to drive `claude --print` automatically). A postamble points at the next concrete action (`devteam next` after the gate is written). Framing is suppressed under `--headless` (the prompt is piped to the host CLI) and reserved-suppressed under `--json`. Closes the #1 first-run footgun where new users ran `devteam stage` and got a raw prompt block with no context. 3 new tests in `tests/cli.test.js`.
- **Un-initialised target warning.** `devteam stage` now stderr-warns when the target directory has no `.devteam/config.yml`, with the exact `devteam init --host claude-code --cwd "..."` command to fix it. The warning fires before the prompt renders, so users see the fix path before they see a prompt that references files that don't exist. 1 new test in `tests/cli.test.js`.
- **Quickstart section in `devteam help`.** Five numbered steps from `init` through the first `devteam next`, plus a one-line statement of the model-agnostic invariant ("devteam never calls a model itself").
- `tests/headless.test.js` (8 tests) — covers `core/adapters/headless.js`: command resolution, env override, missing-command rejection, exit-code propagation, spawn-ENOENT error, gatePath detection, EPIPE swallowing, whitespace splitting.
- `tests/release.test.js` (7 tests) — covers `scripts/release.js notes`: `[Unreleased]` default, middle section, last-section (no trailing header to anchor to — the regression that bit v0.1.0's tag), missing-version error, blank-line preservation, trailing `---` stripping.
- `tests/ui.test.js`: 4 new tests for the non-loopback bind guard — accepts loopback (`127.0.0.1`, `localhost`) without opt-in, rejects non-loopback bind with `EREMOTEBIND` unless `STAGECRAFT_UI_ALLOW_REMOTE=1` is set, allows non-loopback with a stderr warning when opt-in is given.

### Changed

- `core/gates/validator.js`: lifted `GATES_DIR` / `LESSONS_FILE` from module-load constants to `gatesDir()` / `lessonsFile()` functions. The validator is normally spawned as a subprocess (each invocation has a fresh cwd), so behavior is unchanged in production; the lazy resolution makes the module require()-able from tests and other callers that chdir().
- `scripts/release.js notes`: strips the trailing `---` separator from extracted sections. CHANGELOG uses `---` between sections structurally, but it was bleeding into annotated tag messages. Annotated tags built from `release:notes <version>` now end cleanly at the section body.
- `docs/TESTING.md`: rewritten to reflect current reality (362 tests / 24 files / 81 suites / ~1.5s, tiers 1+2 shipped) instead of the original strategy-doc framing where tiers 1 and 2 were aspirational.
- `docs/GAP-ANALYSIS.md`: rewritten as a historical-then-current doc. Migration is complete; most listed gaps are closed. The load-bearing section now is the feature inventory of what Stagecraft has that the forks didn't (contracts A/B/C/F, conditionalOn, stage-04b/06b/06c, OTel, memory, fanout, dashboards, PR integration, web UI, secret scanning, consistency lint). For active gap tracking, see `docs/BACKLOG.md`.
- Schema `$id` URLs: switched from the placeholder `https://example.local/ai-dev-team/<name>.schema.json` to `urn:stagecraft:schema:<name>`. Internal identifiers; the URN form avoids claiming a DNS namespace we don't own. `tests/schemas.test.js` and `scripts/consistency.js` updated to assert the new form.
- `core/ui/server.js`: refuses to bind to non-loopback hosts unless `STAGECRAFT_UI_ALLOW_REMOTE=1` is set. The UI has no auth, no rate limits, and exposes full pipeline state — making a remote bind a conscious opt-in instead of a typo-distance default. Loopback bind (`127.0.0.1`, `::1`, `localhost`) is unaffected. When opt-in is given, a loud stderr warning prints at startup.
- OpenTelemetry dependency pins: `^x.y.z` → `~x.y.z` for all `@opentelemetry/*` packages. Pre-1.0 OTel SDK packages have historically shipped breaks in minor releases; tilde restricts to patch-only updates.

### Security

- **GHSA-q7rr-3cgh-j5r3 resolved by removing the vulnerable package.** `@opentelemetry/sdk-node` was a convenience wrapper that we only used to wire `OTLPTraceExporter` + `Resource` onto a tracer provider — work that `NodeTracerProvider` (from `@opentelemetry/sdk-trace-node`, already in our deps as stable 1.x) does directly. `core/observability.js` now uses `NodeTracerProvider` + `BatchSpanProcessor` explicitly, and `@opentelemetry/sdk-node` is removed from `package.json`. `npm install` drops 51 transitive packages (including the vulnerable Prometheus exporter). `npm audit` reports `found 0 vulnerabilities` post-change. Production tracing behavior is unchanged: same span shape, same OTLP/HTTP transport, same shutdown flush on `beforeExit` / `SIGINT` / `SIGTERM`.

---

## [0.2.0] — 2026-05-27

Ten priority BACKLOG items shipped in a row, plus the rename from `ai-dev-team` to **Stagecraft**. The CLI binary remains `devteam`; only the project identity changed. Public surfaces unchanged from 0.1.0: gate JSON shape, host adapter contract, `.devteam/config.yml` schema. Additive features only — no breaking changes.

### Added

- **OpenTelemetry tracing** (`docs/BACKLOG.md` D1). Every pipeline operation emits spans: `pipeline.stage`, `pipeline.workstream`, `pipeline.stage.headless`, `pipeline.merge`, `pipeline.next`, `adapter.renderStagePrompt`, `adapter.invoke`. Opt-in via the standard `OTEL_EXPORTER_OTLP_ENDPOINT` env var; no-op tracer when unset (zero overhead). Ships spans via OTLP/HTTP to Jaeger, Tempo, Honeycomb, Datadog Agent, etc.
- `core/observability.js` — tracer bootstrap + `withSpan` helper.
- `docs/observability.md` — setup cookbooks for Jaeger / Honeycomb / Datadog.
- `tests/observability.test.js` — 9 tests asserting expected spans + attributes using `InMemorySpanExporter`.
- **Secret scanning PreToolUse hook** (`docs/BACKLOG.md` C2). Blocks `Write` / `Edit` operations that introduce AWS keys, GitHub / Anthropic / OpenAI / Google / Slack / Stripe credentials, private keys, JWTs, or postgres URLs with embedded passwords. Built-in regex patterns; no external scanner required. Path allowlist (`.env.example`, `docs/`, `examples/`, tests, snapshots). Magic-comment override `devteam-allow-secret:` for verified false positives. Findings are redacted before being echoed back. `DEVTEAM_SECRET_SCAN_ALLOW` env var accepts additional path-regex allowlist entries.
- `core/hooks/secret-scan.js` — hook script + exported `scanContent()`.
- `tests/secret-scan.test.js` — 32 tests across pattern detection, false-positive guards, magic-comment override, path allowlist, end-to-end PreToolUse stdin parsing, and snippet redaction.
- **Gemini CLI host adapter** (`docs/BACKLOG.md` A1). Third real host alongside claude-code and codex. Symmetric to codex (no hooks, no slash commands, headless via `gemini`). Installs roles → `.gemini/prompts/roles/<role>.md`, rules → `.devteam/rules/` (shared), skills → `.gemini/skills/<name>/`. Tri-host install (`devteam init --host claude-code,codex,gemini-cli`) lays down all three side-by-side with shared rules deduped automatically.
- **Accessibility audit stage** (`docs/BACKLOG.md` B1). New `stage-06b` between QA and sign-off, role: `qa`. Gate carries `audit_method` (axe-core / pa11y / lighthouse / manual), `wcag_level` (A / AA / AAA), `violations` (critical / serious / moderate / minor counts), `components_audited`, and an `audit_skipped_reason` escape for backend-only changes. PASS requires zero critical AND zero serious; moderate/minor flow through as WARN. Included in `full`, `quick`, `hotfix` tracks (skipped on `nano`, `config-only`, `dep-update`). `skills/accessibility-audit/SKILL.md` walks through tool choice, procedure, triage, gate writing, and gotchas (Storybook-passes-route-fails, color-contrast in real browsers, manual audit for hover/focus/error states).
- **Observability gate** (`docs/BACKLOG.md` B4). New `stage-06c` between accessibility-audit and sign-off, role: `platform`. Verifies that every metric / log / trace the brief's §9 "Observability requirements" promised is actually emitted by the shipped code. Gate carries `metrics`, `logs`, `traces` each with `{required[], verified[], gap[]}` plus a `verification_method` enum (`code-grep` → `runtime-probe`). PASS requires every gap empty; weak verification methods PASS with WARN ("recommend runtime-probe post-deploy"). Non-empty gap → FAIL with missing signals as blockers. Included in `full` + `hotfix` tracks (the tracks where brief §9 is mandatory). `skills/observability-verification/SKILL.md` walks through extraction, naming conventions to match (`_` ↔ `.` ↔ `-`), grep patterns per signal type, and the decision matrix.
- **Gate-pass-rate dashboards** (`docs/BACKLOG.md` D2). `scripts/dashboard.js` aggregates `pipeline/gates/` across one or more projects and produces a per-stage / per-host / per-role / per-status pass-rate report. Default: Markdown with ASCII stacked-bar charts (`▰` PASS, `▱` WARN, `▨` FAIL, `▩` ESCALATE); `--json` for tooling integration. `--from p1,p2,...` for multi-project rollups, `--since YYYY-MM-DD` for time-windowed views. Expands merged stage gates into their constituent workstreams so per-host / per-role attribution is correct (e.g. a stage-04 merged gate counts as 4 rows in the host breakdown, one per workstream). `npm run dashboard` exposes it. Foundation for the not-yet-built D4 (per-role per-model performance scores) and D5 (adaptive routing).
- `scripts/dashboard.js` + `tests/dashboard.test.js` (14 tests).
- **GitHub PR integration** (`docs/BACKLOG.md` F1). `scripts/pr-publish.js` uses the `gh` CLI to publish pipeline state to a PR. Two modes: `body` (replace PR description with pr-pack output — idempotent; re-run after each pipeline change to keep the PR in sync) and `checks` (post each gate as a GitHub check run on the PR head commit — PASS→success, WARN→neutral, FAIL/ESCALATE→failure, with blockers + warnings + workstreams in the check run's summary text). Auto-detects repo from git remote and PR from current branch; `--dry-run` previews what would happen (works without `gh` configured when `--pr` and `--repo` are supplied). `npm run pr-publish` exposes it. Auth via `gh` — we never handle tokens directly.
- `scripts/pr-publish.js` + `tests/pr-publish.test.js` (12 tests — gate-to-check-run translation, including PASS/WARN/FAIL/ESCALATE conclusion mapping, workstream gate naming, blockers/warnings/workstreams in output text, edge cases).
- **Web UI for pipeline runs** (`docs/BACKLOG.md` E2). `devteam ui` starts a local HTTP server (default http://127.0.0.1:3737/). Single-page UI shows the active track + pipeline state (one row per stage, expandable workstreams for multi-role stages, status icons + colors), gate detail on click (status, identity fields, blockers, warnings, workstreams table, raw JSON), and live updates via Server-Sent Events backed by `fs.watch` on `pipeline/gates/`. Zero build step (vanilla HTML / CSS / JS); zero new dependencies. `--open` launches the default browser; `--port N` overrides; loopback-only by default. Path-traversal-safe static serving.
- `core/ui/server.js` + `core/ui/static/{index.html, app.js, styles.css}` + `tests/ui.test.js` (14 tests covering pure helpers, route correctness, security, and SSE plumbing).
- **Multi-model adversarial peer review** (`docs/BACKLOG.md` G1). New `routing.review_fanout: [host, host, ...]` config field. When set, stage-05 (peer-review) workstreams duplicate across all listed hosts — 4 areas × 3 hosts = 12 parallel reviews. Each host produces its own review file (`pipeline/code-review/by-<host>.md`); the approval-derivation hook recognizes host-based filenames and writes gates to a new 3-segment path (`pipeline/gates/stage-05.<area>.<host>.json`). `mergeWorkstreamGates` reads all expected fanout gates and aggregates pessimistically (any FAIL anywhere → merged FAIL). Adapter contract, host install payload, and gate JSON schema unchanged — fanout is pure composition of existing infrastructure. Default `review_fanout: []` (off); opt-in via config.
- `core/orchestrator.js`: new `computeDispatchPlan(stageDef, config)` helper that computes the full set of `(role, hostName, workstreamId, gateFile)` entries the orchestrator should dispatch — one per role normally, N×M when fanout is active.
- `core/hooks/approval-derivation.js`: new `hostFromPath()` helper + `KNOWN_HOSTS` export; `applyVerdict` accepts an optional `host` param that flips gate naming to 3-segment.
- `tests/fanout.test.js` (16 tests covering dispatch plan correctness for fanout / non-fanout / non-peer-review stages, end-to-end runStage producing N×M workstream prompts, mergeWorkstreamGates aggregation across all 12 gates, missing-gate detection, hostFromPath recognition, and approval-derivation end-to-end with host-based review files).
- **Persistent project memory** (`docs/BACKLOG.md` D7, v1). Per-project semantic memory under `.devteam/memory/`. `devteam memory ingest` indexes briefs / design specs / ADRs / clarification logs / runbooks / test reports / accessibility / observability / security reviews / retrospectives / lessons-learned by splitting at level-2 markdown headings and embedding each chunk. `devteam memory query "text"` returns top-K matches by cosine similarity, ranked, with source path + section heading + snippet + similarity score. Local-default embedder (`Xenova/bge-small-en-v1.5` via `@huggingface/transformers`, ~33MB model lazy-downloaded to `~/.cache/huggingface/`, fully offline thereafter). JSON-backed storage (git-friendly); `MemoryStore` interface ready for the sqlite-vec backend planned for v0.3. Opt-out per artifact via the `stagecraft-no-memory` marker. Re-ingest replaces existing chunks (no duplicate rows). Cross-project import is deferred per D7 decision 3.
- `core/memory/{embed,chunker,store,index}.js` + `tests/memory.test.js` (22 tests using `DEVTEAM_EMBEDDING_PROVIDER=stub` to keep CI fast and offline; live BGE smoke-tested separately against the example project).
- Dependency: `@huggingface/transformers ^3.x` (the v3 successor to `@xenova/transformers`).
- `tests/budget.test.js` (7 tests covering `parseBudgetMd` round-trip, config parsing, init/update/check round-trip, and the contract-F gate emitted on escalation).

### Changed

- **Project rename** `ai-dev-team` → **Stagecraft** (marketing / identity surface only). The CLI binary, config dir (`.devteam/`), gate-file paths, and ORCHESTRATOR_ID prefix (`devteam@<version>`) are all unchanged. README, ARCHITECTURE, AGENTS, CONTRIBUTING, and docs/* reflect the new name and tagline.
- **Budget tracking relocated** from `core/guards/budget.js` → `scripts/budget.js`. It was never wired into the orchestrator as a runtime guard — it's an out-of-band tracker fed by external telemetry. New `npm run budget` exposes it. Fixed a latent contract-F violation: the gate it writes on escalation now carries `orchestrator: "devteam@<version>"` instead of the legacy `agent:` field. The exported `root()` is now lazy so the script's pure-logic exports can be called from tests after `chdir()`.

---

## [0.1.0] — 2026-05-26

First tagged release. This is the unification of `claude-dev-team` and `codex-dev-team` into a single model-agnostic core with per-host adapters. The 0.x signals that the public surface — gate JSON shape, host adapter contract, CLI subcommands, `.devteam/config.yml` schema — may break before 1.0. 1.0.0 is reserved for a substantial future release (see `docs/BACKLOG.md`).

### Added

#### Core architecture
- **Model-agnostic core (`core/`)** that never invokes a model — emits stage prompts and validates gate JSON.
- **Host adapter contract** (`core/adapters/host-adapter.md`) — minimum surface a host must implement: `capabilities`, `install`, `renderStagePrompt`, `status`, `uninstall`, optional `invoke`.
- **Router** (`core/router.js`) — adapter discovery + per-(stage, role) resolution with precedence `routing.stages > routing.roles > routing.default_host`.
- **Orchestrator** (`core/orchestrator.js`) — `runStage`, `runStageHeadless`, `mergeWorkstreamGates`, `next`, `summary`. Decomposes multi-role stages into per-workstream dispatches.
- **Config** (`core/config.js`) — loads `.devteam/config.yml` (js-yaml), resolves host per workstream, generates default config for `devteam init`.
- **Stage definitions** (`core/pipeline/stages.js`) — 11 stages, 6 tracks, role-keyed gate skeletons, per-role allowedWrites overrides, conditional dispatch.

#### Pipeline stages
- Stage 1–9 with sub-stages 4a (pre-review) and **new 4b (security review, conditional)**.
- Conditional dispatch via `conditionalOn: { stage, field, equals }` — generic mechanism, currently used by security-review.
- Per-workstream gates (`pipeline/gates/<stage>.<workstream>.json`) for multi-role stages, merged into stage gate (`pipeline/gates/<stage>.json`) by the orchestrator with aggregate status `ESCALATE > FAIL > WARN > PASS`.

#### Host adapters
- `hosts/claude-code/` — full capabilities (hooks, subagents, slashCommands, worktrees, headless). Installs subagents to `.claude/agents/<name>.md` with YAML frontmatter, rules to `.devteam/rules/`, skills to `.claude/skills/<name>/`, slash command to `.claude/commands/devteam.md`, hooks (Stop/SubagentStop/PostToolUse) to `.claude/settings.local.json`.
- `hosts/codex/` — moderate capabilities (no hooks, no subagents, headless via `codex exec`). Installs roles to `.codex/prompts/roles/<role>.md`, rules to `.devteam/rules/`, skills to `.codex/skills/<name>/`.
- `hosts/generic/` — zero in-host integration. Proves the contract is genuinely host-neutral; install is a no-op.

#### CLI (`bin/devteam`)
- `init --host <list> [--force]` — install one or more adapters into a target project; write `.devteam/config.yml`; create `pipeline/gates/`.
- `stage <name> [--feature "..."] [--headless] [--force]` — render prompts (or drive headlessly); stoplist-guarded on lighter tracks unless `--force`.
- `next [--json]` — read pipeline state, decide what to do next (run/continue/merge/fix/escalate/complete).
- `merge <stage>` — aggregate per-workstream gates into stage gate.
- `validate` — run the gate validator against `pipeline/gates/`. Exit codes propagate (0 PASS/WARN, 1 malformed, 2 FAIL, 3 ESCALATE).
- `summary [--json]` — one-screen pipeline-state report.
- `doctor` — pre-flight check: framework install, target project layout, config validity, per-adapter status, host CLIs on PATH.
- `stages`, `hosts`, `help`.

#### Guards
- `core/guards/stoplist.js` — phrase-based safety guard; wired into `devteam stage` for STOPLIST_GUARDED_TRACKS (`quick`, `nano`, `config-only`, `dep-update`).
- `core/guards/budget.js` — token + wall-clock budget tracking (lifted, not yet wired into the CLI).
- `core/guards/security-heuristic.js` — file-path patterns that trigger Stage 4b security review.

#### Hooks
- `core/gates/validator.js` — gate validator; wired into Claude Code's Stop + SubagentStop events.
- `core/hooks/approval-derivation.js` — Stage 5 PostToolUse hook that parses per-area `REVIEW:` markers in `pipeline/code-review/by-<reviewer>.md` files and upserts the per-area workstream gates.
- `core/adapters/headless.js` — shared helper for adapter `invoke()` implementations.

#### Schemas
- `core/gates/schemas/gate.schema.json` — base schema with **contract F** identity fields: `stage`, `status`, `orchestrator`, `track`, `timestamp`, `blockers`, `warnings`, plus `workstream` and `host` (workstream gates only) and `workstreams[]` (merged stage gates only). **Legacy `agent` field is removed.**
- Per-stage schemas `stage-01` through `stage-09`, plus `stage-04a` (pre-review) and `stage-04b` (security review).

#### Single-source content
- `roles/` — 8 host-neutral role briefs (pm, principal, backend, frontend, platform, qa, reviewer, security).
- `rules/` — 10 pipeline rules docs (gates, pipeline, escalation, retrospective, orchestrator, coding-principles, compaction, pipeline-build, pipeline-core, pipeline-tracks).
- `skills/` — 6 task-oriented helpers (api-conventions, code-conventions, implement, pre-pr-review, review-rubric, security-checklist).
- `templates/` — 12 artifact templates (brief, design-spec, build, clarification, pr-summary, pre-review, review, runbook, test-report, retrospective, adr).
- `core/deploy/` — 4 deploy adapter docs (docker-compose, kubernetes, terraform, custom) + README.

#### Documentation
- `README.md` — concise entry point.
- `ARCHITECTURE.md` — design model + 11 locked decisions.
- `AGENTS.md` — host-neutral context for LLMs working on this repo.
- `CONTRIBUTING.md` — recipes to add a host adapter, stage, role, or skill.
- `EXAMPLE.md` — end-to-end walkthrough of one pipeline run with real CLI captures.
- `docs/concepts.md` — one-sentence definitions of every primitive.
- `docs/GAP-ANALYSIS.md` — comparison vs claude-dev-team / codex-dev-team.
- `docs/TESTING.md` — testing strategy.
- `docs/BACKLOG.md` — bucketed roadmap with impact/effort scores + innovation bets.
- `docs/walkthroughs/stage-04-split-host.md` — stress-test trace that locked the multi-workstream contract.

#### Tests
- 113 tests across 8 files: contract, config, router, adapter-contract, gate-validator, orchestrator, next, install-roundtrip, approval-derivation. `npm test` passes in ~500ms.

### Locked design decisions

11 decisions in `ARCHITECTURE.md` — most consequential:

1. The core never spawns a model. Emits prompts and validates JSON.
2. Gate JSON is the stable seam. Identity fields `stage`, `status`, `orchestrator`, `host`, `workstream` (no more `agent`).
3. Role briefs have one source (`roles/*.md`); adapters render into host-expected paths at install time.
4. **Per-workstream host selection.** A single pipeline can route different roles to different hosts; merged via the gate seam.
5. Multi-host install is the default code path. Single-host is a list of length 1.
6. Capability negotiation per adapter — declares `hooks`, `subagents`, `slashCommands`, `worktrees`, `headless`, plus an `enforces` map.

### Differences from claude-dev-team and codex-dev-team

- No fork to maintain — one core, three host adapters.
- Contract F applied everywhere: `agent` field replaced with `orchestrator` + `host` + `workstream`.
- WARN status added (PASS-with-warnings, non-blocking).
- Generic `conditionalOn` mechanism for conditional stages.
- Per-role `roleWrites` map narrows allowed writes per workstream in multi-role stages (backend's prompt no longer lists `src/frontend/`).
- `stage.subagent` override lets multi-workstream stages dispatch all workstreams to a single named subagent (used by peer-review).
- Multi-host install (`devteam init --host claude-code,codex`) is first-class.

### Migration history

Land in 5 logical commits then iterate (see `git log`):

1. `scaffold` — architecture, host-adapter contract, stress-test walkthrough.
2. `core` — templates, schemas, validator, guards, stages.js (contracts A/F applied).
3. `roles + rules` — single source of truth, host-neutral paths.
4. `orchestrator + CLI + generic adapter + init command` (contract B merge).
5. `claude-code adapter` (agents + slash command + rules install).

Then iteratively: codex adapter, `next`, hooks wiring, headless `invoke()`, track filtering, per-role allowedWrites, peer-review structural fix, conditional security review, skills, version-note cleanup, role-brief refinements, README/LICENSE/gap-analysis/testing, tier-1 doc + test + CLI set.