baldart 4.12.0 → 4.13.0

package/framework/.claude/skills/new/SKILL.md

@@ -114,7 +114,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
 ### Update rules
 
-- **Before starting a card**: move it to `## Current Card` with phase info.
+- **Before starting a card**: move it to `## Current Card` with phase info, and record `phase_module_loaded: <modulo>` as you Read each phase module (per § "Routing" HARD RULE) so context recovery can re-load it.
 - **After each phase**: update the current card's phase status in the tracker.
 - **After completing a card**: move it from `Current Card` to `## Completed Cards` with:
   - Commit hash
@@ -237,239 +237,127 @@ baselines. Keep that bulk on disk and pass **paths**, not bodies.
 
 ---
 
-## Phase 0 — Workspace Hygiene Pre-flight (BLOCKING — non-skippable)
 
-**Why this exists**: FEAT-0006 incident left the main repo with an unpushed orphan commit (`c9d41f9`) and `develop` diverged from `origin/develop` because `/new` started work on a dirty/diverged repo without surfacing the situation. This phase reconciles the main repo state BEFORE any worktree is created, and snapshots any in-progress user work so Phase 6c can restore it after the batch.
+## Routing — il per-card pipeline e i moduli on-demand
+
+`/new` è uno **orchestrator long-lived**: il suo corpo skill sta nel prefisso di
+sistema, ri-letto a OGNI turno. Per non pagare 60k+ token di istruzioni di fase a
+ogni turno, il dettaglio passo-passo di ogni fase vive in un **modulo `references/<x>.md`**
+caricato on-demand. Questo file (il core) tiene solo gli invarianti cross-fase
+(Context Tracking, Progress Visibility, § "Context economy", Agent Routing, QA
+Profile, Trivial fast-lane, Risk-signal detector, Fix Application Log) + questa
+mappa di navigazione.
+
+> **HARD RULE — leggi il modulo PRIMA di eseguire la fase.** Quando entri in una
+> fase, **Read** il suo modulo `references/<x>.md` e poi eseguilo. Eseguire una
+> fase "a memoria" (senza aver caricato il modulo in questo run, o dopo una
+> compaction che l'ha evacuato) è una violazione di protocollo: ricaricalo. Registra
+> nel tracker, sotto `## Current Card`, il campo `phase_module_loaded: <modulo>` al
+> caricamento, così la § "Context recovery protocol" sa cosa ri-leggere dopo una
+> compaction. I `§ "..."` citati dai moduli (Context economy, Context Tracking,
+> Trivial-card fast-lane, Risk-signal detector, Fix Application Log) puntano a sezioni
+> che vivono **qui nel core** → risolvono sempre.
+
+**Sequenza (per ogni card, in ordine — i moduli per-card sono caricati per traversata):**
+
+| Fase | Quando | Modulo | Skip se (ragione enumerata) |
+|------|--------|--------|------------------------------|
+| 0 — Workspace Hygiene + Pre-flight | a inizio batch (una volta) | [`references/setup.md`](references/setup.md) | mai (BLOCKING) |
+| 1-2 — Claim & Context + Implement | per card | [`references/implement.md`](references/implement.md) | — |
+| 2.5 / 2.5b — Completeness + AC-Closure | dopo l'impl | [`references/completeness.md`](references/completeness.md) | — (2.5b è BLOCKING, mai skip) |
+| 2.55 / 2.6 / 3 / 3.5 — Simplify + E2E + Doc + QA | dopo AC-Closure | [`references/review-cycle.md`](references/review-cycle.md) | `IS_TRIVIAL`→skip 2.55+3.5; `has_e2e_review:false`/backend-only→skip 2.6; `light`+no-doc-diff→Doc a Final; `balanced`→QA a Final |
+| 3.7 — Pre-Merge Codex Review Gate | pre-commit | [`references/codex-gate.md`](references/codex-gate.md) | solo `IS_TRIVIAL` (altrimenti unconditional; `light`/`full` è DEPTH, non skip) |
+| 4-5 — Commit + Context Clean | fine card | [`references/commit.md`](references/commit.md) | — |
+| Final review F.1-F.6 | dopo l'ultima card | [`references/final-review.md`](references/final-review.md) | mai (FULL gate unconditional) |
+| 6 / 6b / 6c — Merge & cleanup | dopo Final | [`references/merge-cleanup.md`](references/merge-cleanup.md) | mai (BLOCKING) |
+| 7 — Production Readiness | dopo il merge | [`references/production-readiness.md`](references/production-readiness.md) | — |
+| 8 — Metrics Log | ultimo | [`references/metrics.md`](references/metrics.md) | mai (non-blocking, best-effort) |
+
+**Team Mode** (batch complessi, deciso in Pre-flight per § "Parallelism rules"): il
+per-card pipeline sopra è rimpiazzato dall'esecuzione per-gruppo parallela —
+[`references/team-mode.md`](references/team-mode.md). Le stesse fasi/gate sono propagate
+per-card nei sub-step D.x (mai aggregate). Caricalo quando Pre-flight seleziona team mode.
 
-**Auto Mode does NOT override this phase.** Every `AskUserQuestion` below is non-bypassable — the model has no authority to pick an option on the user's behalf.
+---
 
-**Steps:**
+## Parallelism rules
 
-0. **Feature gate + config resolution (BLOCKING)** — before anything else:
-   - Read `features.has_backlog` from `baldart.config.yml`. If it is `false` (or the key is absent and the user confirms there is no backlog), this skill REFUSES to run: print "`/new` operates on backlog cards and requires `features.has_backlog: true` — run `npx baldart configure` to enable." and HALT. Do NOT proceed to step 1.
-   - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml`. **When the key is absent** (consumer updated to ≥4.0.0 without re-running `configure`), do NOT hard-assume `develop` — autodetect the repo's real default branch exactly as worktree-manager does, so `/new` and `nw` agree on the base: `git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD` (strip `refs/remotes/origin/`), else the first existing local branch among `develop` / `main` / `master`. A `main`-trunk repo defaulted to `develop` here would diverge from the worktree base `nw` picks and break every `git diff "$TRUNK...HEAD"` gate. Only HALT ("Trunk branch unresolved — run `npx baldart configure`") if nothing resolves. Persist the resolved value as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from the tracker".
-   - Resolve `$METRICS` = `paths.metrics` from `baldart.config.yml` (default `docs/metrics`). This is the framework-owned telemetry directory written by Phase 8 (tracker archive, `skill-runs.jsonl`, `sessions/`). The dirty-tree gate (step 3) reads `$METRICS` to recognise — and never surface — its own telemetry output. Persist it as `Metrics dir:` in the tracker `## Worktree` section.
+### Sequential mode (default for small batches)
 
-1. **Resolve `$MAIN`** — the absolute path of the main repo (not a worktree). If `/new` was invoked from inside a worktree, walk up to the parent repo via `git rev-parse --show-superproject-working-tree` or `git worktree list` until you find the non-worktree root. Persist as `Main repo:` in the tracker `## Worktree` section. **Write `$MAIN` to the tracker the moment it is computed** — every later consumer (Phase 6c, Phase 6b) MUST re-read it from the tracker and HALT with "`$MAIN` absent from tracker" if the field is missing or empty, never silently use an undefined `$MAIN` (it does not survive context compaction).
+- Cards execute one at a time through the full per-card pipeline (Phases 1-5).
+- Code review and doc review for the same card run as **parallel read-only audits**, then fixes are applied by domain owner: **doc findings → `doc-reviewer` (write mode)**, code/security/migration findings → `coder`. (Sequential Phase 3 is even simpler — doc-reviewer runs alone, so it audits AND applies in one invocation.)
+- This mode is unchanged from the original behavior.
 
-2. **Fetch remote state**:
-   ```bash
-   git -C "$MAIN" fetch origin --quiet
-   ```
+### Team mode (for complex batches)
 
-3. **Dirty-tree gate (BLOCKING — framework telemetry is auto-ignored, never surfaced)** — capture the working tree state of the main repo, then **partition it** so the gate fires only on genuine in-progress user work:
-   ```bash
-   PORCELAIN="$(git -C "$MAIN" status --porcelain)"
-   # Drop framework-owned telemetry THIS skill writes in Phase 8 (tracker archive,
-   # skill-runs.jsonl, sessions/) and never commits. Porcelain lines are "XY path";
-   # paths with special chars are quoted. $METRICS resolved in step 0 (e.g. docs/metrics).
-   USER_DIRTY="$(printf '%s\n' "$PORCELAIN" \
-     | grep -vE "^.{3}\"?${METRICS}/" \
-     | grep -vE "^.{3}\"?${METRICS}\"?$" \
-     | grep -v '^[[:space:]]*$')"
-   ```
-   **Why**: Phase 8 copies the batch tracker into `$METRICS/archive/` and appends to `$METRICS/skill-runs.jsonl` *after* the merge, and never commits them. If those untracked telemetry files tripped this gate, **every batch would block on the previous batch's metrics** — a self-inflicted loop. They are not user work and the user is never asked about them.
-   - If `$PORCELAIN` is non-empty but `$USER_DIRTY` is **empty** (only telemetry under `$METRICS` is dirty) → do **NOT** gate. Write `Dirty: framework-telemetry-only (auto-ignored)` to the tracker and proceed to step 4. No `AskUserQuestion`.
-   - If `$USER_DIRTY` is **non-empty** (genuine uncommitted user work) → invoke `AskUserQuestion`:
-   - Question: `"Main repo ($MAIN) ha modifiche non committate prima di partire con la batch. Come procedo?"`
-   - Options (max 4):
-     1. **"Stash automatico (restore in Phase 6c)"** — `$MAIN` is the main checkout (NOT a worktree), so a stash here is safe. Run `git -C "$MAIN" stash push -u -m "baldart-new-phase0-<FIRST-CARD-ID>-<timestamp>"` and write the **stash MESSAGE label** (`baldart-new-phase0-<FIRST-CARD-ID>-<timestamp>`) to the tracker under `## Workspace Snapshot: <message-label> (created <timestamp>)`. Phase 6c resolves the stash by this message — NEVER by a positional `stash@{N}`, because other stashes pushed during the batch (on the main checkout) would shift the index. Do NOT record `stash@{0}`.
-     2. **"Committa adesso (apri editor)"** — halt the batch with a clear message asking the user to commit in their terminal and re-invoke `/new`. Do NOT proceed to step 4.
-     3. **"Procedi senza stash (lavoro mio, lo gestisco io)"** — explicit user override. Log in tracker: `## Workspace Snapshot: dirty-tree override @ <timestamp> — user accepted responsibility`. Phase 6c will still check post-merge state but will NOT attempt restore.
-     4. **"Abort batch"** — halt the batch, leave the tracker file in place, exit.
-
-   Do NOT silently proceed. Do NOT auto-stash without the user picking option 1.
-
-4. **Divergence gate (BLOCKING — framework-management commits do NOT count as orphan commits)** — compare local `$TRUNK` against `origin/$TRUNK` (the trunk resolved in step 0):
-   ```bash
-   read BEHIND AHEAD <<< "$(git -C "$MAIN" rev-list --left-right --count "origin/$TRUNK...$TRUNK")"
-   ```
-   `$BEHIND` / `$AHEAD` are the raw counts. Before branching, **reclassify the ahead commits**: commits produced by `baldart update`/`baldart add` (subtree merges into `.framework/`, the `[CHORE] baldart update …` commit, and the regenerated overlay files they carry) are *expected* divergence, not the FEAT-0006 orphan-commit pattern. Count only **genuine** unpushed commits:
-   ```bash
-   GENUINE_AHEAD=0; GENUINE_LIST=""; FW_SKIPPED=0
-   for sha in $(git -C "$MAIN" rev-list "origin/$TRUNK..$TRUNK"); do
-     subj="$(git -C "$MAIN" log -1 --format=%s "$sha")"
-     # subtree merge (e.g. "Merge commit '…' as '.framework'") or baldart update/add chore
-     if printf '%s' "$subj" | grep -qE "as '\.framework'" || printf '%s' "$subj" | grep -qiE "baldart (update|add)"; then
-       FW_SKIPPED=$((FW_SKIPPED+1)); continue
-     fi
-     # touches ONLY files under .framework/ ? (empty file list = merge commit, handled above)
-     files="$(git -C "$MAIN" show --pretty=format: --name-only "$sha" | grep -v '^$')"
-     if [ -n "$files" ] && ! printf '%s\n' "$files" | grep -qvE '^\.framework/'; then
-       FW_SKIPPED=$((FW_SKIPPED+1)); continue
-     fi
-     GENUINE_AHEAD=$((GENUINE_AHEAD+1)); GENUINE_LIST="$GENUINE_LIST $sha"
-   done
-   ```
-   `$FW_SKIPPED` framework-management commits are auto-ignored (log them — see below). Branch on `$BEHIND` and the **genuine** ahead count `$GENUINE_AHEAD` (NOT the raw `$AHEAD`):
-
-   - **`BEHIND=0` and `GENUINE_AHEAD=0`** — synchronized for `/new`'s purposes. If `$FW_SKIPPED > 0`, write `Divergence: $FW_SKIPPED framework-management commits ahead (auto-ignored — baldart update/subtree)` to the tracker. **No `AskUserQuestion`.** Proceed to step 5.
-   - **`BEHIND>0` and `GENUINE_AHEAD=0`** (only behind) — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è behind origin/$TRUNK di $BEHIND commit. Come procedo?"`
-     - Options: `[Fast-forward pull adesso]` / `[Procedi senza pull]` / `[Abort]`.
-     - On `Fast-forward pull adesso`: if `$MAIN` HEAD == `$TRUNK`, run `git -C "$MAIN" pull --ff-only origin "$TRUNK"`; otherwise log "main HEAD is `<branch>` — fetch already updated `refs/remotes/origin/$TRUNK`, local `$TRUNK` ref will be reconciled in Phase 6c".
-   - **`BEHIND=0` and `GENUINE_AHEAD>0`** (genuine UNPUSHED LOCAL COMMITS, this is the FEAT-0006 pattern) — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è ahead di origin/$TRUNK di $GENUINE_AHEAD commit locali non pushati (esclusi $FW_SKIPPED commit di gestione framework). Cosa faccio?"`
-     - Show **only the genuine** commits inline: `git -C "$MAIN" show -s --oneline $GENUINE_LIST`.
-     - Options: `[Push adesso (git push origin $TRUNK)]` / `[Cherry-pick a parte e continua]` / `[Lascia così e procedi (lo gestisco io)]` / `[Abort]`.
-   - **`BEHIND>0` and `GENUINE_AHEAD>0`** (diverged both ways) — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è diverged da origin/$TRUNK: $BEHIND behind, $GENUINE_AHEAD genuine ahead. Servono entrambe le riconciliazioni. Come procedo?"`
-     - Options: `[Rebase local $TRUNK su origin/$TRUNK]` / `[Mostrami i commit e fammi decidere]` / `[Abort]`.
-
-5. **Log and proceed** — write to the tracker:
-   ```
-   ## Phase 0 — Workspace Hygiene Pre-flight
-   Status: PASS
-   Main repo: $MAIN
-   Trunk branch: $TRUNK
-   Dirty: <none | framework-telemetry-only (auto-ignored) | stashed: <message-label> | user-override>
-   Divergence (local…origin/$TRUNK): <0\t0 | framework-mgmt-only (auto-ignored: $FW_SKIPPED) | resolved: ff-pull | resolved: pushed | user-deferred>
-   Completed: <timestamp>
-   ```
-   If any step ended in HALT, set `Status: HALT` and stop — do NOT continue to `## Pre-flight (once)`.
+- Cards within the same `execution_strategy.groups` level (same `level`) run in parallel via isolated coder agents.
+- Groups execute sequentially (group 0 → group 1 → group 2...).
+- Review + QA run ONCE per group (combined), not per card.
+- The orchestrator holds ONLY coordination state, never implementation details.
+- File ownership map is enforced per-agent via MAY EDIT / FORBIDDEN lists.
+- See "Team Mode" section below for full workflow.
+
+### Common rules (both modes)
 
-6. **Anti-bypass guard** — before exiting Phase 0, re-read the tracker section you just wrote. If `## Phase 0` is missing or shows `Status: HALT`, refuse to proceed. There is no `--skip-phase-0` flag; if you find yourself reaching for one, treat it as a self-correction trigger and stop.
+- The file-ownership map is the authoritative source for which files each agent may edit.
+- When running parallel agents, expect "file modified since read" errors on shared files (like the backlog yml) — handle gracefully.
+- When running in parallel, each parallel branch updates the tracker with its own card — use card ID as prefix to avoid conflicts.
 
 ---
 
-## Pre-flight (once)
-
-1. Read each backlog card from `${paths.backlog_dir}/*.yml` to understand scope and dependencies. Also read the project's canonical-docs registry — typically `${paths.references_dir}/ssot-registry.md` plus any linking-protocol guide — to understand which canonical docs exist for the feature area being implemented. Exact filenames are listed in `.baldart/overlays/new.md`; skip when absent.
-1b. **Validate card fields (pre-flight gate)** — for each card, verify it has the minimum required fields before queuing it:
-   - `requirements` — must be a non-empty list (>=1 item)
-   - `acceptance_criteria` — must be a non-empty list (>=1 item)
-   - `files_likely_touched` — must be a non-empty list (>=1 file)
-   If any card fails: log the specific missing fields in `## Issues & Flags`, ask the user to fill them in before proceeding with that card, and continue pre-flight for any remaining valid cards.
-
-1c. **Field Registry Validation (pre-flight gate)** — for each card with a `data_fields` block, run the project's field-validation tool if available (path listed in `.baldart/overlays/new.md`; typically `python3 tools/validate-card-fields.py <card-yaml-path>`).
-   - If exit 1: display the field errors in `## Issues & Flags` and HALT — ask the user to fix the card before proceeding. Do not start implementation until the card passes validation.
-   - If the card has DB-index signals (`db_indexes` — or legacy `firestore_indexes` — or `data.collections`/`data.tables`) but NO `data_fields` block: log WARNING in `## Issues & Flags` — "Card `<ID>` touches the persistence layer but has no `data_fields` block. Field/column names are unvalidated."
-   - Cards with no `data_fields` and no storage signals: skip silently.
-   - If the project does not ship a field-validation tool: skip this step.
-2. Check `${paths.references_dir}/project-status.md` for current state (skip when absent).
-3. Determine which cards can run in **parallel** (no shared files/components) vs which must be **sequential** (dependencies or overlapping paths). Use `group.sequence` to determine execution order within a group.
-3b. **Build a file-ownership map** — for each card, enumerate every source file it is expected to touch (from `claimed_paths`, `paths`, and the implementation plan). Assign each file to **exactly one agent**. If two cards claim the same file, force those cards sequential on a single agent — do NOT spawn them in parallel. Record this map in the tracker under `## File Ownership Map`. This map is the authoritative source for all agent file permissions in Phase 2.
-3c. **Complexity assessment — team mode decision**
-
-   Determine whether to use **team mode** (parallel coder agents with isolated contexts) or keep **sequential mode** (current behavior).
-
-   **Decision logic:**
-
-   1. Read `execution_strategy.recommended_mode` from the epic parent card (if it exists). If present, use it as the default. The `execution_strategy` block is authored by `prd-card-writer` with the canonical shape `groups:` (a list, each entry has `level:` (int) + `cards:` (list)) — consume that shape, not a flat `parallel_group` field.
-   2. If no `execution_strategy` exists, compute:
-      - Count total cards in batch
-      - Count max cards in any single group (from `execution_strategy.groups[].cards`, i.e. cards sharing the same `level`)
-      - If no `execution_strategy.groups` exist, compute the levels on-the-fly: build dependency graph from `depends_on`/`blocks`, add conflict edges for cards sharing `(MODIFY)` files, compute topological layers via BFS — each topological layer becomes one group `level`.
-   3. Apply threshold:
-      - **Sequential mode** if ANY of: total cards <= 3 — OR all cards are in different groups (max group size = 1, nothing to parallelize) — OR all cards form a linear dependency chain.
-      - **Team mode** if: total cards > 3 AND at least one group has 2+ cards.
-   4. Log decision in tracker:
-      ```
-      ## Execution Mode
-      Mode: team | sequential
-      Reason: [e.g., "6 cards, 3 parallel groups, max 3 cards in group 1"]
-      ```
-   5. Inform the user:
-      ```
-      Batch: N cards, M file unici
-      Gruppi paralleli: K livelli, max P card in parallelo
-      Modalita: **team mode** / **sequential mode** — [reason]
-      ```
-      Proceed without asking (the PRD already approved the strategy).
-
-   When `mode == sequential`, the per-card pipeline below runs exactly as documented. The `execution_strategy.groups` levels are simply ignored. When `mode == team`, skip the per-card pipeline and follow the **Team Mode** section at the end of this document.
-
-   **→ Create the Task spine now.** The execution mode and (in team mode) the wave layout are resolved — create the native Task spine per § "Progress Visibility" A: `Pre-flight` (→ `in_progress`) + one task per card (wave-labelled in team mode) + `Final review` + `Merge & cleanup`. Emit the first Progress Bar with this batch's table. Mark `Pre-flight` → `completed` once worktree setup (step 5) finishes.
-
-3d. **Codex batch cross-card grounding check** (runs in background during worktree setup)
-
-   > **Why**: a non-Anthropic frontier model (Codex, via `codex-companion.mjs`) reviews the full card batch for cross-card conflicts that per-card plan-auditor checks cannot detect (each plan-auditor sees only one card).
-
-   **Skip decision (provenance-aware — since v4.3.0).** The `/prd` Step 6.6 holistic audit (4-agent team + Codex adversarial pass) ALREADY ran this exact cross-card analysis over the cards when they were authored — its Codex prompt covers `files_likely_touched` conflicts, dependency shadows, implicit ordering, and shared-state mutation across the whole audited set. Re-running here is only worth the Codex call when **something changed between that audit and now**. Compute the skip before launching:
-
-   1. **Always skip** if the batch has only 1 card (no cross-card conflicts possible).
-   2. Otherwise, read `metadata.holistic_audit` from every card in the batch and evaluate the four SKIP conditions — **all must hold**:
-      - **S1 — provenance present**: every batch card has `metadata.holistic_audit` with non-empty `audited_at`, `audited_commit`, and `audited_set`. (Missing/partial on any card ⇒ condition fails.)
-      - **S2 — jointly audited**: all batch cards carry the **same** `audited_set` value (they were reviewed together, not stitched from separate PRD runs).
-      - **S3 — batch ⊆ audited set**: every batch card ID is present in that shared `audited_set`.
-      - **S4 — no drift on the claimed paths**: no commit touched any path the batch claims, between the audit baseline and the trunk this run grounds on. Using the shared `audited_commit` (`$AC`) and the batch's union of claimed/touched paths from the file-ownership map (step 3b, `$BATCH_PATHS`):
-        ```bash
-        # empty AC, or AC not in history → treat as drift (do NOT skip)
-        DRIFT="$(git -C "$MAIN" log --oneline "$AC".."$TRUNK" -- $BATCH_PATHS 2>/dev/null || echo "DRIFT")"
-        ```
-        S4 holds **iff** `$AC` is non-empty AND the command succeeds AND `$DRIFT` is empty.
-   3. **If S1–S4 all hold → SKIP the Codex cross-card check.** Log in the tracker under `## Cross-Card Conflicts (Codex)`:
-      `SKIPPED (provenance) — batch ⊆ holistic_audit set <audited_set>, no drift since <AC short sha> (audited <audited_at>)`. Then proceed to step 4 with the file-ownership map unchanged. Do NOT present anything to the user — this is a non-decision.
-   4. **Otherwise → RUN the check** (launch below). Record WHY in the same tracker section so the choice is auditable: `RUN — <reason>` where reason is one of `no/partial provenance` (S1) · `batch spans multiple audit sets` (S2) · `batch not a subset of audited set` (S3) · `drift on <first drifted path>` (S4).
-
-   `$MAIN` and `$TRUNK` are the same variables resolved in Phase 0. This gate degrades safely in every direction: any missing signal, ambiguity, or git error falls through to RUN — never to a silent skip.
-
-   Launch via `Bash` with `run_in_background: true` and `timeout: 300000`:
 
-   ```bash
-   AUDIT_FILE="/tmp/codex-crosscard-<FIRST-CARD-ID>-<SESSION-ID>.md" && \
-   CODEX_SCRIPT="$(ls -d ~/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)" && \
-   [ -z "$CODEX_SCRIPT" ] && echo "CODEX_NOT_FOUND" > "$AUDIT_FILE" && exit 1; \
-   node "$CODEX_SCRIPT" task --wait "
-   Cross-card grounding check for a batch of backlog cards about to be implemented together.
-   Your job is to find conflicts BETWEEN cards that per-card reviewers would miss.
-
-   Cards to check (read each file):
-   ${CARD_PATHS}
-
-   File-ownership map:
-   ${FILE_OWNERSHIP_MAP}
-
-   Check:
-   1. FILE CONFLICTS: Do two cards modify the same file in incompatible ways?
-      (e.g., Card A adds field X to interface Foo, Card B restructures Foo entirely)
-   2. IMPLICIT DEPENDENCIES: Does Card A change a type/function that Card B's
-      requirements assume stays unchanged? Flag missing depends_on.
-   3. EXECUTION ORDER RISKS: Given the execution_strategy group/level assignments, will parallel
-      execution cause merge conflicts or type errors?
-   4. SHARED STATE MUTATIONS: Do multiple cards write to the same persistence
-      {entity} ({collection|table|item} per `stack.database`) in ways that could
-      conflict at runtime?
-
-   For each finding return:
-   - **Cards involved**: CARD-A + CARD-B
-   - **Conflict type**: FILE_CONFLICT | IMPLICIT_DEP | ORDER_RISK | STATE_MUTATION
-   - **Evidence**: exact field/file from each card
-   - **Fix**: concrete recommendation (add depends_on, force sequential, etc.)
-
-   If no cross-card conflicts: return PASS.
-   " > "$AUDIT_FILE" 2>&1
-   ```
+## Context recovery protocol
+
+If at ANY point you are unsure where you are in the batch:
+1. Read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`)
+2. Check `## Current Card` — if populated, resume that card at the listed phase.
+3. **Re-Read the phase module** named in `## Current Card`'s `phase_module_loaded:` field (a compaction may have evacuated it from context — see § "Routing" HARD RULE). If the field is absent, map the listed phase to its module via the § "Routing" table and Read that.
+4. Check `## Card Queue` — find the next unchecked card.
+5. Check `## Completed Cards` — know what's already done (don't redo).
+6. Continue the pipeline from where you left off.
+
+---
+
+
+## Agent Routing (Phase 2 dispatcher)
+
+Phase 2 reads the card's `owner_agent` field and dispatches to the matching
+specialist. The enum's single source of truth is the **`owner_agent enum` block in
+`framework/.claude/agents/REGISTRY.md`** (applied by `prd-card-writer.md § Agent
+Specialization Rules`) and validated by the PRD validation phase
+(`framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0).
+
+| `owner_agent` | Dispatcher action in Phase 2 step 7 | Briefing variant |
+|---|---|---|
+| `coder` | Spawn `coder` | Standard coder briefing (default body below) |
+| `ui-expert` | Spawn `ui-expert` | UI briefing — adds BLOCKING registry-first cascade + Post-Intervention Coherence Check (see step 7 § UI branch) |
+| `plan` | Fallback to `coder` + WARN | Standard coder briefing + log `"[ROUTER] plan-only briefing not yet implemented — using coder"` |
+| `visual-designer` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
+| `motion-expert` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
+| missing / `""` / `claude` (legacy placeholders only) | Fallback to `coder` + WARN | Standard coder briefing + log `"[ROUTER] card <ID> has no valid owner_agent (got '<raw>'); defaulting to coder"` |
+| any other unrecognized value (typo, unregistered agent) | **HALT + ask the user** | No briefing — the router stops and surfaces the literal value (see pseudocode step 6b) |
+
+The three `plan` / `visual-designer` / `motion-expert` stubs exist so the
+router never blocks a card; specialized briefings are tracked as a follow-up.
+**Only the empty/missing/`claude` legacy placeholders fall back to `coder`** — a
+genuinely unrecognized value (e.g. a typo `coder-agent`, or an agent not in the
+enum) HALTs so a mis-routed card is never silently downgraded. The table and the
+step-6b pseudocode are the same contract stated twice; keep them in lockstep.
+
+The valid values come from ONE place — `REGISTRY.md`'s `owner_agent enum` block. Do not
+re-list them here or maintain parallel copies; if the roster changes, edit the enum in
+`REGISTRY.md` and these consumers read it:
+
+- `framework/.claude/skills/prd/assets/card-template.yml` (the placeholder cites the REGISTRY enum),
+- `framework/.claude/agents/prd-card-writer.md § Agent Specialization Rules`,
+- `framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0a,
+- `framework/.claude/agents/REGISTRY.md` decision-tree.
 
-   **Variable interpolation**:
-   - `${CARD_PATHS}`: newline-separated list of all `- ${paths.backlog_dir}/FEAT-XXXX-*.yml` paths in the batch
-   - `${FILE_OWNERSHIP_MAP}`: the file-ownership map built in step 3b
-
-   > `<SESSION-ID>` is the current session id (e.g. `$CLAUDE_CODE_SESSION_ID`, or a run UUID if unset). The task-scoped unique name prevents two concurrent `/new` sessions on the same day from clobbering each other's findings (a date-only name silently collides). Record the exact `$AUDIT_FILE` path in the tracker under `## Cross-Card Conflicts (Codex)` so the result-handling step reads the SAME path — never re-derive it by wildcard/timestamp.
-
-   **Result handling** (read before Phase 1 of first card):
-   - **Background completion barrier (BLOCKING):** record the background task id when you launch it; do NOT read `$AUDIT_FILE` until that task has completed. Because this gate's verdict steers Phase-1 card ordering, the first card MUST NOT start while the check is in flight.
-   - **TIMED_OUT branch:** the launch sets `timeout: 300000` (5 min). If the background task hits the timeout without producing a terminal result (the tail of `$AUDIT_FILE` shows no `PASS` / conflict block / `CODEX_NOT_FOUND`), treat it as **TIMED_OUT** — do NOT leave the task "in-progress" and silently proceed. Log `cross-card-check: TIMED_OUT` in `## Cross-Card Conflicts (Codex)` and take the SAME fallback as `CODEX_NOT_FOUND`: spawn `code-reviewer` over the batch with the four conflict questions. Never start the batch with cross-card review in an unresolved/in-flight state.
-   - Read the exact `$AUDIT_FILE` path recorded in the tracker after the background command completes.
-   - If the file contains **`CODEX_NOT_FOUND`** (Codex unavailable): do NOT silently proceed — **fallback**: spawn the `code-reviewer` agent over the full batch's card YAMLs + file-ownership map with the same cross-card conflict questions (FILE_CONFLICT / IMPLICIT_DEP / ORDER_RISK / STATE_MUTATION). If `code-reviewer` is also unavailable, surface `CAPABILITY_UNAVAILABLE: cross-card-review` to the user and ask whether to proceed without cross-card detection or halt. Never run a multi-card batch with cross-card review silently skipped.
-   - If **PASS** or file empty: proceed normally.
-   - If **conflicts found**: log in tracker under `## Cross-Card Conflicts (Codex)` and present to user. For each conflict:
-     - `FILE_CONFLICT` / `ORDER_RISK` → force the conflicting cards sequential (update file-ownership map).
-     - `IMPLICIT_DEP` → add `depends_on` entry to tracker notes (do NOT modify backlog YAML).
-     - `STATE_MUTATION` → add warning to both cards' Phase 2 briefings.
-
-4. **Worktree setup** — delegate to the **worktree-manager** skill (`/nw` in programmatic mode):
-   a. **Resolve the `slug`** (required by the `/nw` programmatic API — `{ cards, groupParent, slug, branch? }`). Derive it deterministically: if the parent card (or the lead card) has `git_strategy.branch` set, parse the slug from it (`feat/<PARENT-ID>-<slug>` → `<slug>`); otherwise slugify the parent/lead card `title` (lowercase, non-alphanumerics → `-`, collapse repeats, trim, cap ~40 chars). Persist the resolved `slug` in the tracker `## Worktree` section so the path/branch are reproducible across compaction. Do NOT let `/nw` invent its own slug — pass it explicitly.
-   b. Pass all card IDs, their `group.parent` fields, AND the resolved `slug` to the skill's grouping logic.
-   c. The skill handles: grouping cards by `group.parent`, deriving branch names from `git_strategy.branch` (falling back to `feat/<PARENT-ID>-<slug>` using the slug you passed), creating the worktree in `.worktrees/`, installing dependencies, copying env files, assigning a free port, and verifying the build.
-   d. The skill updates `.worktrees/registry.json` with the worktree entry (including all card IDs in the `cards` field).
-   e. If build fails → the skill STOPs and reports. Do NOT continue.
-   f. Record the worktree path, branch, slug, and port from the skill's output in the tracker.
-5. **Tracker already exists** — the `/tmp/batch-tracker-<FIRST-CARD-ID>.md` file was created at batch start (before Phase 0, see "Context Tracking"). Here, backfill the `## Worktree` section with the worktree path, branch, slug, and port resolved in step 4, AND write `Created: <ISO-8601 now>` (`date -u +%Y-%m-%dT%H:%M:%SZ`) — this is the strategy-independent start anchor Phase 8's `cycle_time_mins` reads. Do NOT re-create the file (Phase 0 has already written to it).
-6. Create a task list to track progress across all cards.
+Keep them in lockstep — drift between any two layers silently mis-routes cards.
 
 ---
 
+
 ## QA Profile Selector
 
 Before Phase 3.5, determine the review profile for each card. **`/new` is a CONSUMER of `review_profile`, not the place where the decision criteria live.**
@@ -495,6 +383,7 @@ disagree.
 
 ---
 
+
 ## Trivial-card fast-lane (since v4.6.0 — SSOT; phases below CITE this, never redefine it)
 
 Some cards are genuinely too small to justify the review machine: a `docs`/`chore`/`config`
@@ -552,678 +441,65 @@ diff + 0 triggers` — a deterministic, card-authored gate reason. Never `time b
 
 ---
 
-## Agent Routing (Phase 2 dispatcher)
-
-Phase 2 reads the card's `owner_agent` field and dispatches to the matching
-specialist. The enum's single source of truth is the **`owner_agent enum` block in
-`framework/.claude/agents/REGISTRY.md`** (applied by `prd-card-writer.md § Agent
-Specialization Rules`) and validated by the PRD validation phase
-(`framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0).
-
-| `owner_agent` | Dispatcher action in Phase 2 step 7 | Briefing variant |
-|---|---|---|
-| `coder` | Spawn `coder` | Standard coder briefing (default body below) |
-| `ui-expert` | Spawn `ui-expert` | UI briefing — adds BLOCKING registry-first cascade + Post-Intervention Coherence Check (see step 7 § UI branch) |
-| `plan` | Fallback to `coder` + WARN | Standard coder briefing + log `"[ROUTER] plan-only briefing not yet implemented — using coder"` |
-| `visual-designer` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
-| `motion-expert` | Fallback to `coder` + WARN | Standard coder briefing + same WARN format |
-| missing / `""` / `claude` (legacy placeholders only) | Fallback to `coder` + WARN | Standard coder briefing + log `"[ROUTER] card <ID> has no valid owner_agent (got '<raw>'); defaulting to coder"` |
-| any other unrecognized value (typo, unregistered agent) | **HALT + ask the user** | No briefing — the router stops and surfaces the literal value (see pseudocode step 6b) |
-
-The three `plan` / `visual-designer` / `motion-expert` stubs exist so the
-router never blocks a card; specialized briefings are tracked as a follow-up.
-**Only the empty/missing/`claude` legacy placeholders fall back to `coder`** — a
-genuinely unrecognized value (e.g. a typo `coder-agent`, or an agent not in the
-enum) HALTs so a mis-routed card is never silently downgraded. The table and the
-step-6b pseudocode are the same contract stated twice; keep them in lockstep.
-
-The valid values come from ONE place — `REGISTRY.md`'s `owner_agent enum` block. Do not
-re-list them here or maintain parallel copies; if the roster changes, edit the enum in
-`REGISTRY.md` and these consumers read it:
-
-- `framework/.claude/skills/prd/assets/card-template.yml` (the placeholder cites the REGISTRY enum),
-- `framework/.claude/agents/prd-card-writer.md § Agent Specialization Rules`,
-- `framework/.claude/skills/prd/references/validation-phase.md` Step 6 → 0a,
-- `framework/.claude/agents/REGISTRY.md` decision-tree.
-
-Keep them in lockstep — drift between any two layers silently mis-routes cards.
-
----
-
-## Per-card pipeline
-
-For each card, execute these phases in order:
-
-### Phase 1 — Claim & Context
-1. **Update tracker**: set current card, phase = "1-claim".
-2. **`depends_on` gate (BEFORE claiming)** — read the card's `depends_on` field. For each listed card ID:
-   - Read that card's backlog YAML and check its `status` field.
-   - If NOT `DONE` → HALT: log in `## Issues & Flags` and ask the user: "Card <CARD-ID> depends on <DEP-ID> which is `<status>`. Proceed anyway, or wait?" Do not start implementation until the user responds explicitly. **The card status is NOT written until this gate passes** — so a HALT leaves the card untouched (no stale `IN_PROGRESS` for the next run to mis-read).
-   - If `DONE` (or the user chose "proceed anyway") → continue.
-2b. **Claim** — only now set the card status to `IN_PROGRESS` and assign yourself. **→ Visibility**: TaskUpdate this card's spine task → `in_progress`, and emit a Progress Bar (card change) per § "Progress Visibility".
-2c. **Trivial-card classification (BLOCKING gate for steps 3–4)** — evaluate `IS_TRIVIAL(card)` per § "Trivial-card fast-lane". Note: condition 3 (non-source diff) cannot be fully evaluated until the coder has produced the diff, so at this point compute the **provisional** trivial flag from conditions 1+2 only (`review_profile == skip` AND no Step-A trigger sourced from the card YAML text + `files_likely_touched` extensions — if EVERY path in `files_likely_touched` is non-source, condition 3 is provisionally satisfied). If provisionally trivial → **SKIP steps 3, 3a, and 4** (architecture grounding); log `trivial: architecture grounding skipped (review_profile=skip + non-source files_likely_touched + 0 triggers)` and jump to Phase 2. Re-confirm `IS_TRIVIAL` on the ACTUAL committed diff at the review gates (Phase 2.55/3.5/3.7); if the coder unexpectedly touched a source file, the guard flips the card back onto the normal review path there. If NOT provisionally trivial → run steps 3, 3a, 4 as normal.
-3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. The orchestrator does NOT propagate the flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.)
-3a. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project) — do this AFTER the codebase-architect run (step 3) so the "Active Code Context" reflects the architect's findings (which files are actually in scope), not just the card YAML's `files_likely_touched`. Writing it before the architect run would persist pre-analysis claims that downstream agents (e.g. a parallel card) would then read as truth.
-4. **Plan-auditor grounding check** — but first, a **provenance skip (since v4.7.0 — mirror of Step 3d)**: the `/prd` Step 6.6 holistic audit already ran a per-card grounding pass when the card was authored. Re-grounding here is only worth a plan-auditor spawn if something changed since. Skip the plan-auditor when **BOTH** hold:
-   - **P1 — provenance present**: the card has `metadata.holistic_audit` with non-empty `audited_at`, `audited_commit`, `audited_set`.
-   - **P2 — no drift on this card's claimed paths** since the audit baseline. With `$AC` = `metadata.holistic_audit.audited_commit`, `$MAIN`/`$TRUNK` from the tracker, and this card's `files_likely_touched`/claimed paths (`$CARD_PATHS`):
-     ```bash
-     # empty AC, AC not in history, or any git error → treat as drift (do NOT skip)
-     DRIFT="$(git -C "$MAIN" log --oneline "$AC".."$TRUNK" -- $CARD_PATHS 2>/dev/null || echo "DRIFT")"
-     ```
-     P2 holds **iff** `$AC` is non-empty AND the command succeeds AND `$DRIFT` is empty.
-
-   (No S2/S3 cross-card conditions — grounding is per-card, and the holistic audit grounded each card individually.) If **P1 ∧ P2 → SKIP** the plan-auditor: log `plan-auditor grounding: SKIPPED (holistic_audit provenance, no drift on claimed paths since <AC short sha>)`, carry the card requirements unchanged into Phase 2, and proceed to step 5. **Fail-safe**: missing/partial provenance, any drift, or any git error → fall through to RUN the plan-auditor as written below (never a silent skip). Independent of the trivial fast-lane (a trivial card already skipped steps 3–4 at step 2c). Otherwise — invoke the **plan-auditor** agent in **QUICK mode** (pass `mode: QUICK`; its contract runs only the grounding checks, and because the codebase-architect findings are passed in below it does NOT re-spawn codebase-architect for this narrow check):
-   ```
-   mode: QUICK
-   Grounding check only (NOT a full audit — do not run the full AUDIT CHECKLIST A-H, and do not
-   re-invoke codebase-architect; the findings are pasted below). Verify this backlog card's
-   requirements are grounded in the actual codebase.
-
-   Check:
-   1. Do all paths in files_likely_touched actually exist?
-   2. Are all type/field references in requirements correct per the codebase findings below?
-   3. Are any [ASSUMED] items answerable by reading the listed files (i.e., should be verified facts)?
-   4. Do any requirements conflict with known anti-patterns from your memory?
-
-   Card YAML:
-   [paste full card YAML]
-
-   Codebase-architect findings:
-   [paste key findings from step 3]
-
-   Return: PASS | FIXES NEEDED (list exact corrections). No full audit report needed.
-   ```
-   - If **FIXES NEEDED**: apply corrections to the tracker notes for this card (do NOT modify the backlog YAML). Carry the corrected requirements into the Phase 2 briefing.
-   - If **PASS**: proceed.
-5. **Update tracker**: phase = "1-claim DONE", log codebase-architect key findings (1-2 lines) and plan-auditor result (PASS or corrections applied).
-5b. **Persist the architecture baseline for reuse (since v3.35.0)** — write the **untruncated codebase-architect task result verbatim** (the full Task-tool output: file paths, type signatures, patterns, high-risk paths) to `/tmp/arch-baseline-<CARD-ID>.md`. This is NOT the 1-2-line tracker summary from step 5 — serialize the agent's complete output to disk BEFORE you summarize it for the tracker, so Phase 3.7's per-card `/codexreview` (lean mode, reuses this file instead of re-spawning `codebase-architect`) gets enough detail to ground a reviewer. If you summarize first and write the summary, the lean contract is defeated.
-
-### Phase 2 — Implement (self-healing, up to 3 retries)
-6. **Update tracker**: phase = "2-implement".
-6b. **Agent dispatch (router)** — read `owner_agent` from the card YAML and resolve the spawn target per the table in § Agent Routing above:
-
-   ```
-   Let raw = card.owner_agent (string, may be missing).
-   # Epic guard FIRST — an epic is a tracker, not implementable work.
-   If card is an epic (id ends "-00" OR filename ends "-epic.yml" OR review_profile == "skip"
-       with no requirements): SKIP — do NOT dispatch to any agent. Log
-       "[ROUTER] card <ID> is an epic (tracker) — skipped, not implemented" and move to the next card.
-   Switch on raw:
-     - "coder"           → spawn = "coder",       briefing = "coder"
-     - "ui-expert"       → spawn = "ui-expert",   briefing = "ui-expert"
-     - "plan"            → spawn = "coder",       briefing = "coder"
-                           + log: "[ROUTER] plan-only briefing not yet implemented — using coder"
-     - "visual-designer" → spawn = "coder",       briefing = "coder"
-                           + log: "[ROUTER] visual-designer briefing not yet implemented — using coder"
-     - "motion-expert"   → spawn = "coder",       briefing = "coder"
-                           + log: "[ROUTER] motion-expert briefing not yet implemented — using coder"
-     - "" | missing | "claude"
-                         → spawn = "coder",       briefing = "coder"
-                           + log: "[ROUTER] card <ID> has no valid owner_agent (got '<raw>'); defaulting to coder"
-     - anything else     → HALT. Log: "[ROUTER] card <ID> has unknown owner_agent '<raw>' — not in {coder, ui-expert, plan, visual-designer, motion-expert}. Ask the user how to proceed."
-   ```
-
-   Log the resolved `spawn` and `briefing` in the tracker (1 line: `"router: owner_agent=<raw> → spawn=<agent>, briefing=<variant>"`). This is the audit trail for which specialist actually handled the card.
-
-7. Spawn the **resolved agent** (from step 6b) using this **standardized mission briefing** — fill in each section from the card YAML, tracker, and codebase-architect findings. When `briefing = "ui-expert"`, ALSO include the additional UI sections marked **[UI-ONLY]** below:
-
-   ```
-   ## MISSION BRIEFING — <CARD-ID>
-
-   ### Card Specification (verbatim — do not paraphrase)
-   Requirements:
-   [copy full requirements list from card YAML, including any corrections from the plan-auditor grounding check (step 4)]
-
-   Acceptance Criteria:
-   [copy full acceptance_criteria list from card YAML]
-
-   ### Unknowns & Conditional Requirements (MANDATORY — resolve before coding)
-   [If card has `unknowns` field: copy verbatim. If empty or absent: "None."]
-
-   Each unknown that says "verify X; if missing → do Y" is a BINARY-OUTCOME ITEM.
-   You MUST actively verify and produce one of the two outcomes (implementation OR TODO comment).
-   See `coder.md § Conditional Requirements — Binary-Outcome Items`.
-
-   ### Business Context (WHY this feature exists)
-   [paste business_rationale field from card YAML]
-   [if field is empty/missing, read PRD Section 1b from card's links.prd path]
-
-   ### Codebase Context
-   [paste codebase-architect key findings: file paths, exact line numbers, type signatures, existing patterns to follow]
-   [include any corrections or anti-patterns flagged by plan-auditor grounding check]
-
-   ### Design Reference (UI cards only — include if card has links.design)
-   Design file: [path from card's links.design field]
-   Read the design.html file and use it as the visual reference for your implementation.
-   The design was approved by the user — your implementation MUST match it.
-
-   ### [UI-ONLY] Registry-first BLOCKING pre-work (include ONLY when briefing = "ui-expert")
-   You are spawned as `ui-expert`. Before writing any UI code, you MUST complete
-   the registry-first cascade defined in
-   `framework/.claude/agents/ui-expert.md` § "Authoritative Style Reference —
-   Registry-First Protocol" (the SSOT lives in
-   `framework/agents/design-system-protocol.md`). Reproduce its 5 steps
-   verbatim, do NOT paraphrase or skip:
-
-   1. Read `${paths.design_system}/INDEX.md` (component index + Canonical
-      Authority Matrix).
-   2. Read `${paths.ui_guidelines}` (visual language, typography,
-      accessibility, brand voice).
-   3. Read `${paths.design_system}/tokens-reference.md` (token contract —
-      SSOT for every color / spacing / shadow / radius / motion value).
-   4. For EACH primitive in scope on this card, read
-      `${paths.design_system}/components/<Name>.md`. "In scope" = any
-      component named in the mockup, the requirements, or `files_likely_touched`.
-   5. For EACH pattern in scope, read the relevant
-      `${paths.design_system}/patterns/<topic>.md`.
-
-   State, in your first response, which Authority Matrix rows govern this
-   card, which component specs you read (step 4), and which patterns you
-   read (step 5). Skipping this declaration = the orchestrator will reject
-   the implementation and re-spawn.
-
-   The `features.has_design_system: true` flag in `baldart.config.yml` is
-   the precondition for the full cascade. When `features.has_design_system:
-   false`, only step 2 applies — log the gap, recommend `/design-system-init`
-   if drift is visible, and proceed with coder-level diligence (no cascade
-   enforced).
-
-   ### [UI-ONLY] Implementation-only constraint (include ONLY when briefing = "ui-expert")
-   This `/new` invocation gives you the role of IMPLEMENTER, not designer:
-
-   - DO NOT redesign the mockup. The mockup at `links.design` is the
-     user-approved visual contract for this card.
-   - DO NOT silently adapt a mockup detail that conflicts with the registry
-     (e.g. a custom shadow not in `tokens-reference.md`, a font size off the
-     type scale, a color outside the palette). If you find such a conflict:
-     STOP, log it in the tracker as `[DS-DRIFT] mockup-vs-registry`, and ask
-     the user which side to honor.
-   - DO NOT extend scope into business logic, API calls, state management, or
-     validation rules. Those belong to a sibling `coder` card (see
-     `backlog-phase.md § Rule B`). If a requirement appears to need logic,
-     STOP and ask — do not implement it.
-
-   ### [UI-ONLY] Post-Intervention Coherence Check (include ONLY when briefing = "ui-expert")
-   Before declaring the card done, you MUST reconcile the three design-system
-   sources in the SAME commit as your UI change, per
-   `framework/agents/design-system-protocol.md § Post-Intervention Coherence Check`:
-
-   - `${paths.design_system}/INDEX.md` — add / update entries for any primitive
-     introduced or modified. Drift code: `DS_INDEX_DRIFT`.
-   - `${paths.design_system}/components/<Name>.md` — ship the per-component
-     spec for any new primitive; update the spec when a primitive's API or
-     visual changes. Drift code: `DS_COMPONENT_STALE`.
-   - `${paths.design_system}/tokens-reference.md` — add / update token entries
-     when introducing new semantic tokens. Drift code: `DS_TOKENS_DRIFT`.
-
-   The four conditions defined in `design-system-protocol.md` are the SSOT —
-   reproduce them in your completion report under a `design_system_coherence:`
-   block listing which conditions applied and which artifacts you updated.
-   Omitting the block = the orchestrator treats the card as not done.
-
-   ### File Permissions (ENFORCED — no exceptions)
-   MAY EDIT — your files for this card:
-   [list from ownership map for this card]
-
-   MUST READ ONLY — shared dependencies:
-   [list from ownership map: files owned by other cards that this card reads]
-
-   FORBIDDEN:
-   - Do NOT edit any file outside the MAY EDIT list above
-   - Do NOT refactor unrelated code
-   - Do NOT add unrequested features or extra error handling beyond what's specified
-   - Do NOT modify test files unless the card explicitly requires it
-
-   ### Database Indexes (if card has `db_indexes` — or legacy `firestore_indexes` — field)
-   This card requires the following indexes shipped in the SAME commit as the query
-   code. Missing indexes degrade performance or break production (variant per
-   `stack.database` — see `framework/.claude/agents/coder.md § Database Index Invariant`).
-
-   [paste db_indexes entries from card YAML, formatted as:]
-   | Entity | Dialect | Fields | Kind | Query Location | PRD Ref |
-   |--------|---------|--------|------|----------------|---------|
-   | [entity] | [stack.database] | [field1 ASC, field2 DESC] | [composite/covering/GIN/GSI] | [file path] | [IDX-N] |
-
-   **Where to ship the index — pick the artifact matching `stack.database`:**
-
-   - `firestore` → append to `firestore.indexes.json` under `indexes[]`:
-     ```json
-     {
-       "collectionGroup": "<entity>",
-       "queryScope": "COLLECTION",
-       "fields": [
-         { "fieldPath": "<field1>", "order": "ASCENDING" },
-         { "fieldPath": "<field2>", "order": "DESCENDING" }
-       ]
-     }
-     ```
-     Stage `firestore.indexes.json` together with the query code.
-   - `postgres` / `supabase` / `mysql` / `sqlite` → add a migration file under the
-     project's migrations dir (`migrations/`, `db/migrate/`, `supabase/migrations/`,
-     `prisma/migrations/` per project convention) with `CREATE INDEX ...` or the
-     Prisma `@@index([...])` directive. For Supabase, RLS policies live in the same
-     migration when relevant.
-   - `mongodb` → add `db.<entity>.createIndex(...)` to the project's index-bootstrap
-     script (path declared in `.baldart/overlays/new.md § Schema Bootstrap`), or run
-     it as part of the migration command.
-   - `dynamodb` → update the table definition in the project's IaC (CDK / Terraform /
-     SAM / SST) with the matching GSI/LSI.
-   - Stack `none` or unset → if you still see `db_indexes` on the card, ask the user
-     to confirm the persistence target before staging anything.
-
-   Stage the index artifact alongside the query code in the SAME commit. Verification
-   (post-deploy index propagation) is handled in the Production Readiness Checklist
-   section below, branched by `stack.deployment`.
-
-   ### Expected Output Locations
-   [pre-fill from codebase-architect: for each requirement, the file:line where the change should go]
-
-   ### Project Anti-Patterns & NFRs (ENFORCED)
-   Violating these is a BLOCKER in code review.
-
-   Deprecated patterns — the orchestrator MUST fill this from the project's own AGENTS.md / MEMORY.md / coding-standards.md before sending the briefing. If the project documents none, write "None documented." Do NOT pass placeholder example text to the coder (it wastes tokens and confuses the agent):
-   [resolved list of this project's deprecated/anti-patterns, or "None documented."]
-
-   Performance MUST rules (adapt to your stack):
-   - Bounded reads on every database query (`.limit()` / equivalent)
-   - Cursor-based pagination, not offset
-   - No per-row fetches in loops — batch instead
-   - Database indexes declared in schema config (same commit as the query that needs them)
-
-   Security MUST rules:
-   - No stack traces in HTTP responses — generic messages + error codes only
-   - No PII in console.log or error tracking
-   - No hardcoded secrets — env vars only
-   - ALL non-public routes MUST use the project's auth middleware
-
-   Coding standards (agents/coding-standards.md):
-   - Use the project's canonical terminology (document it in coding-standards.md)
-   - Honor the design-system theming contract (e.g. text/background pairing rules)
-   - Honor the project's image-format and asset-pipeline rules
-
-   Design System SSOT (MANDATORY for UI cards):
-   - Master reference: `${paths.design_system}/INDEX.md` (component index + Canonical Authority
-     Matrix + Quick rules MUST). Read this BEFORE touching any UI file.
-   - For each UI component you modify or create, read `${paths.design_system}/components/<Name>.md`.
-   - Merchant-themed surfaces MUST follow the pairing rule in
-     `the project's theming pattern doc (listed in `.baldart/overlays/ui-design.md`)`.
-   - Motion MUST follow `the project's motion pattern doc (listed in `.baldart/overlays/ui-design.md`)` (reduced-motion variants
-     required). The coder agent's own hardening (see `.claude/agents/coder.md`) already enforces
-     this — this briefing is an explicit reminder for UI-touching cards.
-   - No hardcoded hex/shadow/border values in component styling — canonical tokens only.
-
-   ### Batch Lessons (from prior cards in this batch)
-   [If tracker `## Lessons Learned` has entries, paste them here.
-    If empty or first card: "First card — no lessons yet."]
-
-   ### MANDATORY: Numbered Requirements Checklist (anti-skip measure)
-   Before you start coding, print this checklist to confirm you see ALL requirements:
-   ```
-   REQUIREMENTS TO IMPLEMENT:
-   [x] R1: [requirement text]
-   [x] R2: [requirement text]
-   ...
-   ACCEPTANCE CRITERIA TO SATISFY:
-   [x] AC1: [criterion text]
-   [x] AC2: [criterion text]
-   ...
-   CONDITIONAL / BINARY-OUTCOME ITEMS (from unknowns + requirements with "verify if / if missing"):
-   [ ] C1: [item text] → Branch to take: A (found+implement) | B (missing+TODO)
-   [ ] C2: [item text] → Branch to take: A (found+implement) | B (missing+TODO)
-   ...
-   Total: N requirements + M acceptance criteria + K conditional items = X items
-   ```
-   You MUST implement ALL items. Skipping even one is a failure.
-   For each conditional item: verify actively, then produce the correct branch artifact.
-
-   ### MANDATORY: Completion Report
-   When implementation is done, output this block in EXACTLY this format.
-   This report is NOT optional — if you omit it, the orchestrator will flag
-   your implementation as incomplete and spawn a fix agent.
-
-   ```completion-report
-   card: <CARD-ID>
-   requirements:
-     - id: 1
-       text: "[verbatim requirement text]"
-       status: done | not_implemented
-       evidence: "src/path/to/file.ts:LINE_NUMBER"
-       notes: "[if not_implemented: explain why]"
-     - id: 2
-       [repeat for each requirement]
-   acceptance_criteria:
-     - id: 1
-       text: "[verbatim criterion text]"
-       status: done | not_implemented
-       evidence: "src/path/to/file.ts:LINE_NUMBER"
-   items_total: [N]
-   items_done: [M]
-   items_skipped: [list of skipped item IDs, or "none"]
-   conditional_items:
-     - item: "[verbatim text of conditional requirement]"
-       branch_taken: "A-found" | "B-missing"
-       evidence: "src/path/to/file.ts:LINE_NUMBER"
-       notes: "[if B-missing: exact TODO location and text left; otherwise omit]"
-   ```
-
-   Per-requirement / per-AC `status` is BINARY: `done` or `not_implemented` (the legacy
-   `partial`/`blocked` values are removed — see `coder.md`). The orchestrator re-derives the
-   finer Done/Partial/Missing classification itself in Phase 2.5 by reading the code; the coder
-   report is a starting signal, not ground truth.
-   If `items_skipped` is not "none", you MUST explain why each was skipped.
-   The orchestrator treats any `not_implemented` or skipped item as a gap requiring a fix agent.
-   `conditional_items` MUST list every binary-outcome item from the card. If the card has no
-   conditional requirements, omit the field. `branch_taken: B-missing` MUST have a `notes`
-   field with the exact file path and line where the TODO comment was written.
-   ```
-
-8. **Run the verification gates and CAPTURE their output to disk** (so step 9 can pass it to a fix agent) — **redirect, never `tee`/stream inline** (per § "Context economy" → Gate-output discipline). Each is its own gate:
-   ```bash
-   cd <worktree-path>
-   npm run lint        > /tmp/lint-<CARD-ID>.txt  2>&1; echo "lint:$?"
-   # tsc is its OWN blocking gate — run it ONLY when stack.language includes "typescript"
-   # (do NOT assume `npm run build` covers tsc — Next.js dev builds and many setups skip it):
-   npx tsc --noEmit    > /tmp/tsc-<CARD-ID>.txt   2>&1; echo "tsc:$?"   # guard: when stack.language includes "typescript"
-   npm test            > /tmp/test-<CARD-ID>.txt  2>&1; echo "test:$?"  # if tests exist
-   npm run build       > /tmp/build-<CARD-ID>.txt 2>&1; echo "build:$?"
-   ```
-   The `echo "<gate>:$?"` lines surface only the **exit code** inline — the full log stays on disk. When `stack.language` does NOT include `typescript`, skip the `tsc` line (no equivalent gate). Capturing to `/tmp/*-<CARD-ID>.txt` guarantees the failing output is available for step 9. On a non-zero exit, read a **bounded** extract only (`tail -n 30 /tmp/<gate>-<CARD-ID>.txt`), never the whole log — do NOT run the gates without redirect-to-file capture.
-9. **If any check fails**: categorize the error (`lint | TypeScript | test | build`), log it in the tracker as `retry-cause: <category>`.
-   **Code-recovery check (MUST do before rewriting)**: before spawning a fix agent or rewriting code, check whether lint-staged or a pre-commit hook removed code that is actually needed (e.g. a field "unused" at commit time but consumed by later code). Inspect the captured diff and `git diff`/`git log -p` for the worktree branch and restore the needed code by an explicit file write. **Do NOT `git stash pop` inside the worktree** — `refs/stash` is globally shared across worktrees (`$GIT_COMMON_DIR`), so a stash created or popped in a worktree can corrupt another worktree's state (see Phase 4 WORKTREE COMMIT RULE). If you need to set work aside in a worktree, make a clearly-labelled WIP commit and record its hash in the tracker for later squash, never a stash.
-   When spawning a fix agent: scope it exclusively to this card's Edit-allowed files (from `## File Ownership Map`) — it MUST NOT touch files owned by other cards. Pass the fix agent: the **path** to the captured gate log (`/tmp/<gate>-<CARD-ID>.txt` — it Reads the log itself; do NOT inline-paste the full log into its prompt), the error category, and the explicit list of files it may edit. Do NOT ask the user — just fix and re-run. Fix the code, not the tests (unless the test itself is wrong). Repeat up to **3 times**. **Stuck-loop guard**: compare the failing error's fingerprint (file:line + message) between retries; if the SAME error reproduces on 2 consecutive retries, the fix is not converging (often a constraint outside the card's ownership map) — stop early, log `[STUCK-LOOP] <error>` in `## Issues & Flags`, and escalate to the user rather than burning the 3rd retry on an identical failure.
-10. If still failing after 3 retries (or on a stuck loop), log the failure in `## Issues & Flags` and ask the user before continuing.
-11. **Update tracker**: phase = "2-implement DONE", log files changed (short list), retry count, retry causes (e.g., `"2 retries: TypeScript x1, lint x1"`), and test results (new + existing test count, pass/fail).
-11b. **File diff gate** — verify the coder only touched its allowed files. The coder commits its work (per `coder.md`), so a bare `git diff --name-only HEAD` is vacuous (clean tree). Detect what the card's commits actually changed against the trunk, with an uncommitted-fallback:
-   ```bash
-   cd <worktree-path>
-   git diff --name-only "$TRUNK...HEAD" 2>/dev/null || git diff --name-only HEAD~1..HEAD
-   ```
-   (`$TRUNK` is the trunk branch resolved in Phase 0; if the worktree branched from a different base, the `HEAD~1..HEAD` fallback covers the last commit.)
-   Compare against this card's allowed files in `## File Ownership Map`.
-   - **All within allowed set** → proceed to Phase 2.5.
-   - **Any file outside allowed set** → log the violation in `## Issues & Flags` (`"unauthorized file: <path>"`), then spawn a **targeted revert coder agent** with instruction: "Revert ONLY these files to their pre-commit state. Do not touch any other file: [list unauthorized files]". Re-run build + lint to confirm clean state after revert. Update tracker with revert outcome, then proceed to Phase 2.5.
-
-### Phase 2.5 — Implementation Completeness Check (MANDATORY)
-
-Before triggering any review, you MUST verify that the coder agent implemented **every requirement and acceptance criterion** in the backlog card. This is a blocking gate — do NOT proceed to Phase 3 with unimplemented items.
-
-**Step-by-step**:
-
-0. **Conditional requirements pre-scan** (BLOCKING — before building the main checklist):
-
-   Scan the card's `requirements`, `acceptance_criteria`, `unknowns`, and `notes` fields for
-   conditional language patterns: "verify if / verify whether", "if missing / if not present /
-   if not found / if not already", "if already exists / if already included", "leave TODO /
-   add TODO / leave a note", "add if needed / create if missing", "add support if missing".
-
-   For each match, classify as a **binary-outcome item** and verify:
-   a. Positive branch: grep changed files for the implementation.
-   b. Negative branch (B-missing): grep codebase for `// TODO [CARD-ID]:` at the relevant location.
-
-   If NEITHER branch artifact exists → classify as `Missing` (not Partial) and trigger the
-   gap-resolution fix agent sub-loop immediately for these items (before continuing the checklist).
-   **Loop-counter scope**: the max-2 gap-resolution cap is tracked PER ITEM, not per phase. The
-   step-0 pre-scan and the step-5 main loop share the same per-item budget — an item that consumed
-   both retries here is NOT given two fresh retries at step 5; an item never touched here keeps its
-   full budget at step 5. This prevents both over-fixing (4 spawns) and starvation (0 retries left).
 
-   Also check: if the card has conditional requirements but the completion report has no
-   `conditional_items` section → flag as `Missing` (the coder must document the branch taken).
+## Risk-signal detector (Phase 3.7 Step A — signal-logging only, NEVER gates the next step)
 
-1. **Update tracker**: phase = "2.5-completeness".
-2. Re-read the backlog card (`requirements`, `acceptance_criteria`, `unknowns`, and `definition_of_done` fields).
-3. Build a checklist — one row per item:
+> Questo detector vive nel core perché due consumatori lo usano in momenti diversi:
+> la § "Trivial-card fast-lane" (a Phase 1, per classificare la card) e il modulo
+> `references/codex-gate.md` (a Phase 3.7, Step B/C). È deterministico (grep + path
+> match), non LLM-discrezionale, e **non gate mai** il passo successivo.
 
-   ```
-   ## Completeness Check — <CARD-ID>
-   | # | Requirement / Criterion | Status | Evidence |
-   |---|------------------------|--------|----------|
-   | 1 | [requirement text]     | Done / Missing / Partial | [file:line or "not found"] |
-   | 2 | [acceptance criterion] | Done / Missing / Partial | [file:line or "not found"] |
-   ```
-
-4. For each item, verify by **reading the actual implementation code** — but read **narrowly** (per
-   § "Context economy" → Targeted Reads): use the coder completion report's `evidence: file:line` as
-   the index, then `Grep` (or `Read` with a tight `offset`/`limit` around that line) for the specific
-   symbol/route/field — do NOT Read whole files into context to confirm one item. The report is your
-   index of WHERE to look; you still verify independently (do NOT trust its `status` alone), just
-   without pulling entire files inline.
-
-   **Verification depth per requirement type:**
-   - **"Create endpoint/route"** → verify: route file exists, handler has correct HTTP method,
-     request validation present, response shape matches requirement, auth middleware applied.
-   - **"Add UI component/page"** → verify: component file exists, renders the required elements,
-     handles loading/error/empty states if specified, is wired into the page/layout.
-   - **"Add field/collection"** → verify: type definition updated, field used in read AND write
-     paths, validation present if specified.
-   - **"Integrate with X"** → verify: import exists, function is called with correct parameters,
-     error handling present.
-   - **Data fields completeness** → if card has `data_fields` block:
-     - For each `status: existing` field: grep the changed files to confirm the field name is
-       referenced in the implementation. A declared-but-unused field is a red flag (wrong name
-       or dead code). Log in checklist as Partial if not found.
-     - For each `status: new` field: verify the field is BOTH written (setter/creator path)
-       AND read (getter/reader path) in the changed files.
-     - For each `status: modified` field: verify old-name references are removed and
-       new-name references exist.
-   - **DB compound query** → verify: if the card has a `db_indexes` (or legacy
-     `firestore_indexes`) field, check that EVERY listed index has been shipped to
-     the artifact matching `stack.database`:
-     - `firestore` → entries exist in `firestore.indexes.json` (match collection +
-       fields + order); also grep the query code to confirm `where()` + `orderBy()`
-       field names match the index definition exactly. Missing index = CRITICAL
-       (runtime 500 FAILED_PRECONDITION).
-     - `postgres`/`supabase`/`mysql`/`sqlite` → a migration file exists declaring
-       the index (or `prisma/schema.prisma` `@@index([...])`); grep the query to
-       confirm the column names match. Missing migration = CRITICAL (silent
-       Seq Scan in production on hot path).
-     - `mongodb` → `createIndex` call exists in the bootstrap script (or migration);
-       compound field order in the call matches equality → range → sort in the query.
-       Missing = HIGH (no immediate error, but slow aggregation under load).
-     - `dynamodb` → the GSI/LSI is declared in the IaC table definition AND the
-       query uses the GSI name via `IndexName`. Missing = CRITICAL (throttle on
-       hot partition).
-
-   If the completion report has `items_skipped` that is not "none", immediately flag those
-   items as Missing regardless of the agent's justification.
-
-   - **[UI-ONLY] Design-system conformance** → run ONLY when `briefing = "ui-expert"` from step 6b
-     AND `features.has_design_system: true` in `baldart.config.yml`:
-     - Grep the changed files for hardcoded design values that bypass the registry:
-       hex colors (`#[0-9a-fA-F]{3,8}`), `rgb(`/`rgba(`, `box-shadow:` with inline
-       offsets/blurs, `border-radius:` with px/rem literals, `font-size:` with raw
-       px/rem (outside the type scale), `padding`/`margin` with raw px (outside the
-       spacing scale). Each hit on a NEW or MODIFIED line = Partial — the value
-       should come from a token, not a literal.
-     - Verify the completion report includes the `design_system_coherence:` block
-       required by the UI-ONLY briefing. Missing block = Missing (orchestrator
-       cannot confirm Post-Intervention Coherence Check ran).
-     - For each new primitive declared by the report (or detected via Grep for new
-       components in `${paths.components_primitives}`), verify the matching
-       `${paths.design_system}/components/<Name>.md` spec was created in the same
-       commit. Missing spec = Partial — fix by re-spawning `ui-expert` with the
-       narrow instruction "ship the component spec for <Name> per
-       design-system-protocol.md".
-     - For each token change declared by the report, verify the entry exists in
-       `${paths.design_system}/tokens-reference.md`. Missing entry = Partial.
-     - If `features.has_design_system: false`, log "DS conformance skipped — flag is false" and continue.
-
-5. Classify each item:
-   - **Done** — code exists AND satisfies the FULL scope of the requirement (not just partial).
-   - **Partial** — some code exists but the criterion is not fully satisfied (e.g., UI renders but no error state, endpoint exists but wrong response shape).
-   - **Missing** — no evidence found in the codebase, OR the coder agent explicitly skipped it.
-
-**Gap resolution** (for Partial and Missing items):
-
-- Spawn a **targeted fix coder agent** with:
-  - The exact list of unimplemented items (copy the checklist rows)
-  - The file-ownership restrictions from `## File Ownership Map`
-  - The instruction: "Implement ONLY these missing items. Do not refactor or expand scope."
-- After the fix agent completes, re-run the static gates the fix could have broken — `npm run lint`, `npx tsc --noEmit` (when `stack.language` includes typescript), and `npm test` — not just build + lint (a gap-fix can introduce a type error or break a test that the earlier Phase 2 gate had passed). Redirect each to `/tmp/<gate>-<CARD-ID>.txt` per § "Context economy" (never inline).
-- Re-verify each fixed item against the code — do NOT trust the agent's self-report.
-- Repeat this sub-loop up to **2 times** (per-item budget, shared with step 0 — see "Loop-counter scope"). After 2 loops, if items remain Partial or Missing:
-  - Log in `## Issues & Flags`: list each unimplemented requirement.
-  - Ask the user whether to proceed to review despite the gap or stop.
-  - **Handoff to Phase 2.5b**: any AC that is still `Partial` or `Missing` at this point (whether the user said "proceed" or not) MUST be seeded into the Phase 2.5b AC Closure Ledger as a `deferred` row with `User-approved? pending` — the user's "proceed to review" answer here does NOT auto-approve the deferral; Phase 2.5b Step 4 still asks per-AC. Do NOT let "proceed" silently mark these ACs `implemented`.
-
-5b. **API contract check**:
-    - From `git diff --name-only "$TRUNK...HEAD"`, identify `route.ts` files that existed before this card (MODIFIED) vs newly added (NEW).
-    - **NEW routes** are exempt from the breaking-change comparison (no prior contract to violate) BUT must still be checked for a **path collision**: read `${paths.references_dir}/api/index.md` and confirm the new route's URL path is not already documented under a different module. A collision → `[API-CONTRACT] PATH-COLLISION` in `## Issues & Flags` (BLOCKER — a second handler for a documented path).
-    - For each MODIFIED route:
-      a. Derive the API module from path (e.g., `src/app/api/v1/booking/[id]/route.ts` → `booking`).
-      b. Read `${paths.references_dir}/api/<module>.md` (or subdirectory match).
-      c. Read the modified route, extract response shape from `NextResponse.json()` calls.
-      d. Compare against documented schema.
-      e. Flag: removed fields or changed types → `[API-CONTRACT] BREAKING` in `## Issues & Flags` (BLOCKER).
-         Added fields only → `[API-CONTRACT] ADDITIVE` (informational).
-         No doc found → `[API-CONTRACT] NO-DOC` (informational).
-
-5c. **Reference-aliasing mutation check** (MANDATORY — deterministic detector, reference-aliasing mutation prevention).
-
-Detect call sites that pair a helper invocation with in-place mutation of an input array
-without an identity guard. Anti-pattern (the reference-aliasing mutation family):
-
-```ts
-const result = filterHelper(input, ...);
-input.length = 0;          // ← wipes both input AND result when result === input
-input.push(...result);     // ← pushes zero elements (result was just emptied)
-```
 
-This detector targets TypeScript/JavaScript array-mutation patterns. **Guard: run it only when `stack.language` includes `typescript` or `javascript`.** For other languages it does not apply — log `[ALIAS-MUTATION] skipped — stack.language not ts/js` and continue (do NOT report a non-TS diff as "clean", which would imply the check ran).
+Run this exact bash block in the worktree. It is deterministic (grep + path match), not LLM-discretionary.
 
-Run this exact bash block in the worktree (`$TRUNK` = the trunk branch resolved in Phase 0):
+`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, autodetected when the key is absent — see Phase 0 step 0). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.** `BACKLOG_DIR` is the value of `paths.backlog_dir` from `baldart.config.yml` (fallback `backlog` when the key is absent — emit it resolved, never the literal `${paths.backlog_dir}` token, which is not valid bash). The card lookup uses `-iname` (case-insensitive) on purpose: card filenames carry uppercase prefixes (`FEAT-`/`BUG-`/`CHORE-`) but `CARD_ID` may arrive lowercased (e.g. `/new feat-0019`), and a case-sensitive `-name` would return empty silently → the card would be treated as non-existent.
 
 ```bash
 cd <worktree-path>
-CHANGED_TS="$(git diff --name-only "$TRUNK...HEAD" -- '*.ts' '*.tsx' '*.js' '*.jsx' 2>/dev/null \
-              || git diff --name-only HEAD~1..HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx')"
-
-ALIAS_HITS=()
-for f in $CHANGED_TS; do
-  [ -f "$f" ] || continue
-  # Heuristic: find lines matching `arr.length = 0` followed within 3 lines by `arr.push(...result)`.
-  # Capture the variable name; flag for human/agent review.
-  python3 - "$f" <<'PY'
-import re, sys
-src = open(sys.argv[1]).read().splitlines()
-for i, line in enumerate(src):
-    m = re.search(r'(\w+)\.length\s*=\s*0', line)
-    if not m: continue
-    var = m.group(1)
-    # Look back 5 lines for a const/let assignment from a function call returning to a different name,
-    # then forward 3 lines for `var.push(...other)`.
-    back = "\n".join(src[max(0,i-5):i])
-    fwd  = "\n".join(src[i+1:i+4])
-    assign = re.search(rf'const\s+(\w+)\s*=\s*\w+\([^)]*\b{re.escape(var)}\b', back)
-    push   = re.search(rf'{re.escape(var)}\.push\(\.\.\.(\w+)\)', fwd)
-    if assign and push and assign.group(1) == push.group(1):
-        print(f"{sys.argv[1]}:{i+1}: ALIAS-MUTATION candidate — '{var}.length = 0' followed by '{var}.push(...{push.group(1)})' where {push.group(1)} comes from a call that received {var}")
-PY
-done
-```
-
-For each hit, classify by reading 10 lines of context around the match:
-
-- **Guarded** — an `if (<assignedName> !== <var>)` check wraps the reset+push block. SAFE. Log `[ALIAS-MUTATION] guarded` (informational, no action).
-- **Defensively cloned** — the helper was called with `[...var]` or `var.slice()` instead of `var`. SAFE. Log `[ALIAS-MUTATION] cloned` (informational).
-- **Helper always returns new array** — read every `return` in the helper. If ALL paths return `[...candidates]` / `candidates.filter(...)` / a new array literal, identity collision is impossible. SAFE. Log `[ALIAS-MUTATION] helper-immutable` (informational).
-- **Un-guarded** — none of the above. Flag `[ALIAS-MUTATION] BLOCKER` in `## Issues & Flags` with file:line and the captured pattern.
-
-For each `[ALIAS-MUTATION] BLOCKER`:
-
-- Spawn a targeted fix `coder` agent with the exact file:line and instruction: "Add identity guard `if (result !== input) { ... }` around the in-place reset, OR clone the input with `[...input]` before passing it to the helper. Add a regression test on the caller pattern, co-located with the helper's existing tests following this project's test convention (e.g. a `*-reference` negative-control test next to the helper's test file). Read `agents/coding-standards.md § Reference-Aliasing Mutation Patterns` before implementing."
-- Re-run the detector after the fix. The hit MUST classify as Guarded, Cloned, or helper-immutable. Repeat **max 2 times**.
-- If still un-guarded after 2 loops → log in `## Issues & Flags` and ask the user.
-
-Rationale (reference-aliasing incident class): a helper that returns its same input reference on some code paths, combined with a call site that did `arr.length = 0; arr.push(...result)` without an identity guard, silently wiped the result. The helper passed unit tests in isolation; the bug only manifested end-to-end. This detector closes that detection gap. Full policy: `agents/coding-standards.md § Reference-Aliasing Mutation Patterns`.
-
-5d. **Caller-pattern test coverage check** (MANDATORY — when card introduces or modifies an exported helper consumed by 1+ caller with in-place mutation).
-
-If the card's diff includes BOTH (a) an `export function` / `export const` declaration in a shared-library file (under `${paths.lib}` if defined, else the project's lib/util dir) AND (b) at least one call site in another file that mutates an input array in place (detected via the bash block in 5c), verify that a test file exists that exercises the **caller pattern** — not only the helper in isolation.
-
-Required test characteristics:
-
-- At least one case asserts the post-call state of the input array (e.g. `assert.strictEqual(arr.length, N)` after the helper invocation).
-- At least one **negative-control case** documents the failure mode that would occur if the identity guard / defensive clone were removed.
-
-If the test is missing:
-
-- Spawn a targeted fix `coder` agent to write the test. The test MUST live in a file co-located with similar helpers, following this project's test convention (do NOT invent a directory — mirror where the helper's existing tests live).
-- This is BLOCKING for Phase 4 commit when the helper is on a high-risk path (a path listed in `paths.high_risk_modules` in `baldart.config.yml`, e.g. auth / payments / a shared scoring-or-ranking primitive). On non-high-risk paths it's a HIGH-severity flag but the orchestrator may proceed and defer to `/codexreview`.
-
-Rationale: in the originating incident, the helper's caller pattern was never tested (tests were deferred to a later E2E card); the helper passed in isolation while the caller-side aliasing bug shipped. A caller-pattern test at the helper-card level catches this class earlier.
-
-6. **Update tracker**: phase = "2.5-completeness DONE", log result (PASS / GAPS REMAIN + count).
-
-### Phase 2.5b — AC-Closure Gate (BLOCKING — Scope Closure Discipline)
-
-This gate enforces `framework/agents/workflows.md § Scope Closure Discipline` at the per-card level. It runs after Phase 2.5's gap-resolution loops have settled and BEFORE Phase 2.55 (Simplify). It is non-skippable.
-
-**Why this exists**: Phase 2.5's fix loops handle items an agent can implement autonomously. They do NOT handle the case where the implementer (or you, the orchestrator) decides — under context pressure or perceived complexity — that an AC is "good enough as is" or "already covered by an existing component". Burying that decision in the card YAML's `implementation_notes`, in a commit message, or in a final recap is a silent scope reduction. The decision belongs to the user.
-
-**Step-by-step**:
-
-1. **Update tracker**: phase = "2.5b-ac-closure".
-
-2. **Build the AC Closure Ledger** — one row per `acceptance_criteria` entry from the card YAML (NOT requirements — only the AC list, because ACs are the user-facing contract):
-
-   ```
-   ## AC Closure Ledger — <CARD-ID>
-   | AC# | Text (verbatim) | Status | Evidence (file:line) | User-approved? |
-   |-----|-----------------|--------|----------------------|----------------|
-   | AC-1 | [text] | implemented | src/x.ts:42 | n/a |
-   | AC-2 | [text] | deferred | n/a | pending |
-   ```
-
-   Status enum: `implemented` | `deferred`. The Phase 2.5 categories map as follows: `Done` → `implemented`; `Partial` or `Missing` (after gap-resolution exhausted retries) → `deferred`. There is no third option — an AC is either in the diff or it is being deferred.
-
-3. **Rationalization scan (BLOCKING for every `deferred` row)** — read the coder's completion report and the card's `implementation_notes`. If the justification for a `deferred` AC matches any of the patterns below, classify the row as `RATIONALIZATION_NEEDS_PROOF`:
-
-   - "covered by <X>" / "already covers" / "existing <X> handles" / "<X> already does"
-   - "implicit in <X>" / "no longer needed" / "redundant with <X>"
-   - "out of scope of this card" (when the AC is clearly listed in the card YAML)
-
-   For each `RATIONALIZATION_NEEDS_PROOF` row, the orchestrator MUST verify by reading `<X>` and producing a line-for-line scope mapping between the AC text and the alleged coverage. The mapping goes in the tracker under `## Rationalization Verification`. If the mapping does not hold (or cannot be produced confidently), the row stays `deferred` and proceeds to Step 4 — the rationalization does NOT auto-approve the deferral.
-
-4. **User gate (BLOCKING `AskUserQuestion` — one per `deferred` AC that is not pre-approved)**:
-
-   For each `deferred` row whose `User-approved?` is `pending`, invoke `AskUserQuestion` with:
-   - Question: `"AC-<N> of <CARD-ID> non implementata. Testo verbatim: '<AC text>'. Motivazione dell'implementer: '<reason or 'nessuna — silent skip'>'. Come procedo?"`
-   - Options (max 4):
-     1. **"Implementa adesso"** — spawn a targeted fix `coder` agent scoped to this card's MAY EDIT files (from `## File Ownership Map`) with the instruction "Implement ONLY AC-<N>: '<AC text>'. Do not refactor or expand scope." Re-run Phase 2.5 verification on the resulting diff — **including the mandatory sub-steps 5b (API contract), 5c (alias-mutation), 5d (caller-pattern test)** if the fix touched a route, an exported helper, or a call site (a single-AC fix can still introduce these). **Hard cap: 2 attempts on the same AC.** On the 2nd failure, do NOT re-offer "Implementa adesso" — re-invoke `AskUserQuestion` with only options 2/3/4 (approve deferral / follow-up card / stop), so the loop cannot recur unbounded.
-     2. **"Approva il deferral"** — record `[USER-APPROVED DEFERRAL] <today>: <user-supplied reason>` on its own line in the card's `implementation_notes`. Mark the row `User-approved? yes`.
-     3. **"Sposta su follow-up card"** — create a backlog stub at `${paths.backlog_dir}/<CARD-ID>-followup-AC<N>.yml` with `status: TODO` AND the minimum fields the Pre-flight gate (step 1b) requires, so a future `/new` run can pick it up without halting: a non-empty `requirements` (≥1, derived from the AC), a non-empty `acceptance_criteria` (≥1, the verbatim AC text), and a non-empty `files_likely_touched` (≥1, carried from the parent card's ownership map for this AC). Mark the row `User-approved? yes (follow-up: <new-card-id>)`. Do NOT proceed to Phase 2.55 until the follow-up file exists on disk and passes the step-1b field check.
-     4. **"Ferma il batch"** — halt the orchestrator, leave the worktree intact, log the reason in `## Issues & Flags`. Do NOT commit.
-
-   Do NOT batch the question across multiple ACs — one `AskUserQuestion` per AC, so the user sees each AC's text in isolation. Issue the questions sequentially.
-
-5. **`implementation_notes` deferral audit (cheap text grep — also BLOCKING)** — before exiting the phase, scan the card YAML's `implementation_notes` field (post-edits, including any text added during this phase) for any of these phrases:
-
-   - `deferred` / `deferral` / `defer to`
-   - `out of scope` / `scope cut`
-   - `covered by` / `already handles` / `redundant`
-   - `skipped` / `dropped`
-
-   When scanning a line, FIRST check for the `[USER-APPROVED DEFERRAL]` prefix; if present AND the corresponding AC row has `User-approved? yes`, the line is RESOLVED — do NOT re-match the rationalization keywords inside the user-supplied reason text (otherwise a freeform reason like "approve deferral: existing component already handles this" would re-flag an already-approved AC). Only lines WITHOUT the prefix (or whose AC row is not `yes`) are silent deferrals that escaped Step 4 — for those, trigger the Step 4 `AskUserQuestion` for the AC referenced (or for "the unspecified AC implied by this note" if no AC is named, asking the user to clarify which AC the note refers to). **If Step 5 triggers any new Step 4 question, fully resolve it (loop back into Step 4) BEFORE running Step 6** — do NOT write `2.5b-ac-closure DONE` while a triggered question is still open.
+CARD_ID="<CARD-ID>"
+BACKLOG_DIR="<value of paths.backlog_dir, or 'backlog' if the key is absent>"
+CARD_FILE="$(find "$BACKLOG_DIR" -iname "${CARD_ID}*.yml" 2>/dev/null | head -1)"
+# Detect what THIS card's commits changed against the trunk (post-commit), with an uncommitted fallback:
+CHANGED="$(git diff --name-only "$TRUNK...HEAD" 2>/dev/null || git diff --name-only HEAD~1..HEAD)"
+# High-risk path alternation from config (empty when paths.high_risk_modules is unset):
+HIGH_RISK_RE="<alternation of paths.high_risk_modules entries, or empty>"
 
-6. **Update tracker** (only after Steps 3–5 have fully settled, including any Step-5-triggered Step-4 question): phase = "2.5b-ac-closure DONE". Persist the AC Closure Ledger AND the Rationalization Verification (if any) in the tracker. Log counts on one line:
+TRIGGERS=()
 
-   ```
-   ac-closure: implemented=N | user-approved deferrals=M | follow-up cards created=K | rationalization-verifications passed=L
-   ```
+# Trigger #1 — High-risk module (auth / permission / payment / shared scoring-or-ranking primitive)
+# Sourced from paths.high_risk_modules — NOT a hardcoded project path.
+if [ -n "$HIGH_RISK_RE" ]; then
+  echo "$CHANGED" | grep -qE "$HIGH_RISK_RE" \
+    && TRIGGERS+=("#1: high-risk module (paths.high_risk_modules)")
+else
+  echo "[DETECTOR] paths.high_risk_modules absent — path-based high-risk trigger skipped" >&2
+fi
 
-The gate exits PASS only when every ledger row is either `implemented` or `deferred` with `User-approved? yes`. Phase 2.55 (Simplify) MUST NOT start until this gate exits PASS.
+# Trigger #2 — Dead-code resurrection (card text + commit messages)
+{ cat "$CARD_FILE" 2>/dev/null; git log --format=%B "$TRUNK...HEAD" 2>/dev/null; } \
+  | grep -qiE 'dead code|unreachable|resurrect' \
+  && TRIGGERS+=("#2: Dead-code resurrection")
 
-#### Context-pressure exception (still BLOCKING — no escape)
+# Trigger #3 — Reference-aliasing mutation pattern (in-place array reset + push)
+# Card introduces or modifies an exported helper AND a call site in the diff mutates an input
+# array in place via `length = 0` + `push(...result)`. Even with a local identity guard, the
+# high-risk gate runs adversarial review to confirm the contract is robust against future callers.
+# Iterate file-by-file safely (no unquoted xargs filename expansion):
+RESET=""; PUSH=""
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  C="$(git show "HEAD:$f" 2>/dev/null)" || continue
+  printf '%s' "$C" | grep -qE '\.length\s*=\s*0' && RESET=1
+  printf '%s' "$C" | grep -qE '\.push\(\s*\.\.\.' && PUSH=1
+done <<< "$CHANGED"
+[ -n "$RESET" ] && [ -n "$PUSH" ] \
+  && TRIGGERS+=("#3: Reference-aliasing mutation pattern")
 
-If at any point in Phases 2 / 2.5 / 2.5b you detect context-window pressure (your context is being summarized, you have ≥ 1 forced compaction, you are racing through verification, you are tempted to "just mark this AC as covered"), do NOT compensate by skipping ACs. The correct response is:
+printf '%s\n' "${TRIGGERS[@]}"
+```
 
-1. Stop the current card's pipeline.
-2. Write the current state to the tracker under `## Issues & Flags` with the prefix `[CONTEXT-PRESSURE]` (which Phase 2 finished, which ACs are open, which files are dirty).
-3. Invoke `AskUserQuestion` with options: (a) finish remaining ACs in a fresh `/new` session that resumes from the tracker, (b) commit the complete ACs and route the rest through this gate's Step 4, (c) hand off the worktree intact to the user.
 
-Auto Mode does NOT override this rule. "Bias toward proceeding" applies to routine decisions ("should I rerun this check?", "should I confirm this safe rename?"), NEVER to scope reduction.
+---
 
 ### Fix Application Log Schema (telemetry)
 
@@ -1265,1484 +541,3 @@ Enumerated exhaustively:
 **Edge case explicit** — a mechanical append-a-row update to `CHANGELOG.md` or `ssot-registry.md` is still classified `doc` and still goes through `doc-reviewer`, never inline and never `coder`. The uniformity of the rule matters more than the cost of the individual spawn.
 
 Domains NOT listed here remain governed by the per-phase rules of the corresponding phase (e.g. `simplify-*` follows Phase 2.55 inline rule).
-
-### Phase 2.55 — Simplify (code cleanup before review)
-
-> **Trivial fast-lane gate**: re-confirm `IS_TRIVIAL` on the ACTUAL committed diff (§ "Trivial-card fast-lane" — all 3 conditions, now including the real non-source diff check). If trivial → **SKIP this phase** AND Phase 3.5 QA + Phase 3.7 Codex; instead run the **inline mechanical gates** (`markdownlint` on changed `.md`, `lint` on lintable changed files, `build` as a sanity check — no qa-sentinel, no test suite), then proceed to Phase 3 (doc review, which DOES run) and Phase 4 (commit). Log `simplify/qa/codex: SKIPPED (trivial — non-source diff)`. If the actual diff turned out to contain a source file → NOT trivial → run this phase and the normal review path. AC-Closure (Phase 2.5b) already ran and is never skipped.
-
-After completeness is verified, clean up the implementation before it reaches reviewers and E2E tests. This phase launches three parallel agents on the card's diff, then applies fixes directly.
-
-**Step-by-step**:
-
-1. **Update tracker**: phase = "2.55-simplify".
-2. Capture the current card's changes to disk — `git diff > /tmp/diff-<CARD-ID>.txt` in the worktree (**redirect, not inline** — per § "Context economy" → Diffs to disk).
-3. Launch **three agents in parallel** (single message). Each receives the **path** `/tmp/diff-<CARD-ID>.txt` and Reads the diff itself — do NOT paste the full diff into the prompts:
-
-   - **Reuse agent** — search the codebase for existing utilities/helpers that could replace newly written code. Flag duplicated functionality, inline logic that could use existing utils.
-   - **Quality agent** — flag redundant state, parameter sprawl, copy-paste with slight variation, leaky abstractions, stringly-typed code where constants/enums exist, unnecessary JSX nesting, unnecessary comments (WHAT comments, narration, task references).
-   - **Efficiency agent** — flag unnecessary work (redundant computations, duplicate API calls, N+1), missed concurrency, hot-path bloat, recurring no-op updates without change-detection guards, TOCTOU existence checks, memory issues (unbounded structures, missing cleanup), overly broad operations.
-
-4. Aggregate findings from all three agents. For each finding:
-   - **Valid AND in a Domain-Override domain** (the finding's target file matches the `doc`, `security`, or `migration` match rule in "Domain-Override Domains") → do NOT apply inline. Delegate to the domain owner: `doc` → `doc-reviewer` (write mode), `security`/`migration` → `coder`. Even a one-line efficiency fix in `paths.high_risk_modules` or a migration file goes to the owning agent — the orchestrator lacks that domain's invariant contract.
-   - **Valid AND not in a Domain-Override domain** → fix directly (apply edits inline).
-   - **False positive / not worth addressing** → skip, BUT record it (see telemetry). If the skip rests on a "covered by X" / "redundant" / "not needed" rationalization (the same family the AC-Closure Gate guards against), do NOT discard silently — verify the rationale by reading `X`, and if it does not hold, treat the finding as valid.
-
-   **Telemetry (Fix Application Log)** — for EVERY finding (valid OR skipped) append one row to the tracker's `## Fix Application Log` section per the schema above. Use `domain=simplify-{reuse|quality|efficiency}` matching the originating agent. Include the `severity` trailing key. Inline: `decision=inline | applied_by=orchestrator | est_lines=<n> | severity=<HIGH|MEDIUM> | finding=<1-line>`. Delegated (domain-override): `decision=<coder|doc-reviewer> | applied_by=<coder|doc-reviewer> | est_lines=<n> | severity=<...> | finding=<1-line>`. Skipped: `decision=skipped | applied_by=- | est_lines=0 | reason=<false-positive|not-worth-addressing>`.
-
-5. After all fixes, run `npm run lint` and `npx tsc --noEmit` to confirm nothing broke (redirect to disk per § "Context economy"; surface only exit code + a bounded extract on failure).
-   If either fails, fix the regression (up to **2 retries**). **If it still fails after 2 retries**: do NOT silently continue to Phase 2.6 with a broken tree — log the failure in `## Issues & Flags` as `[SIMPLIFY-REGRESSION]` and invoke `AskUserQuestion` (revert the simplify fixes / keep and have me fix manually / stop the card), mirroring the Phase 3.5 escalation.
-
-6. **Update tracker**: phase = "2.55-simplify DONE", log count of fixes applied (or "clean — 0 fixes").
-   If any valid finding revealed a reusable pattern or common mistake, append 1-line to `## Lessons Learned`:
-   `SIMPLIFY: <pattern> — <file>`
-
-### Phase 2.6 — End-to-End Review (BLOCKING, since v3.18.0)
-
-This phase delegates to the `/e2e-review` skill — a deterministic, BLOCKING
-orchestrator that combines functional E2E (Playwright spec written by `coder`,
-executed via `playwright-skill`) with visual fidelity diff
-(`visual-fidelity-verifier` multimodal agent), aggregates findings under a
-strict severity gate, runs a bounded self-heal loop, and either passes /
-blocks / accepts an explicit user override.
-
-The skill replaces the previous advisory pair (legacy Phase 2.6 E2E testing
-and Phase 2.7 visual design review). It runs by default on every UI card,
-auto-skips on backend-only cards, and BLOCKS the commit on gating findings.
-
-#### Gate (skip the whole phase when any of the below is true)
-
-| Condition | Action |
-|-----------|--------|
-| `features.has_e2e_review: false` in `baldart.config.yml` | **SKIP** — log `"e2e-review: SKIP (feature disabled — run `npx baldart configure` to enable)"`. Preserves backwards compatibility for pre-3.18 consumers. |
-| Card has no `links.design` AND the card's diff (`git diff --name-only "$TRUNK...HEAD"` for this card's committed files, falling back to `HEAD~1..HEAD`) shows no file under `${paths.app_dir}` AND no file under `${paths.components_primitives}` AND no `*.tsx` / `*.css` / `*.scss` / `*.svelte` / `*.vue` anywhere | **SKIP** — log `"e2e-review: SKIP (backend-only card)"`. (Diff against the trunk, NOT a bare `HEAD` — the coder already committed, so a working-tree diff is empty and would false-skip.) |
-| Card type is `backend`, `api`, `db`, `infra`, `docs`, `chore`, or `config` | **SKIP** — same log. (This list mirrors `/e2e-review`'s OWN Pre-flight skip set so `/new` does not invoke the skill only to have it immediately return `skipped`. A card with no `type` field falls through to the diff-based backend-only check above — do NOT assume a missing type means skip.) |
-
-#### Invocation contract
-
-When the gate above passes, the orchestrator invokes `/e2e-review` in
-**programmatic mode**:
-
-1. **Update tracker**: phase = "2.6-e2e-review".
-2. Spawn the skill with the payload:
-
-   ```json
-   {
-     "card_id": "<CARD-ID>",
-     "worktree_path": "<absolute worktree path>",
-     "mode": "programmatic"
-   }
-   ```
-
-   Do NOT pass `tolerance` / `max_self_heal_iterations` in the payload — `/e2e-review` reads those from `features.e2e_review.*` in `baldart.config.yml` itself (they are NOT parsed from the invocation payload). Passing them here would be dead keys that silently diverge from the config the skill actually uses.
-
-   The skill is responsible for: reading the card YAML + `test_plan`, deriving
-   routes from the diff, walking the 4-level mockup cascade (Figma MCP →
-   local image → compliance-only → skip), generating the Playwright spec via
-   `coder`, executing it headless, invoking `visual-fidelity-verifier` per
-   route, and returning a single JSON object.
-
-3. Parse the returned JSON. The contract is:
-
-   ```json
-   {
-     "status": "passed" | "blocked" | "overridden" | "skipped" | "error",
-     "iterations": 0,
-     "findings": [ ... ],
-     "ds_drift_codes": [ "DS_TOKENS_DRIFT" | "DS_COMPONENT_STALE" | "DS_INDEX_DRIFT" ],
-     "gaps": [ ... ],
-     "transcript_paths": [ ... ]
-   }
-   ```
-
-#### Gating logic (BLOCKING)
-
-| `status` from `/e2e-review` | Orchestrator action |
-|----|----|
-| `"passed"` | Log result in tracker. Proceed to Phase 3 (doc review + code review). |
-| `"skipped"` | Log skip reason. Proceed to Phase 3. |
-| `"overridden"` | Log override + reason in `## Issues & Flags` as `[E2E-OVERRIDE] <reason>`. Proceed to Phase 3. |
-| `"blocked"` | **STOP the card**. Log findings in tracker + `## Issues & Flags` as `[E2E-BLOCKED] <count> gating findings (<categories>)`. Ask the user whether to (a) override with reason, (b) escalate (open follow-up card), or (c) abandon this card and continue the batch. Do NOT proceed to Phase 3 silently. |
-| `"error"` | Log error in `## Issues & Flags`. Ask the user whether to retry, skip, or abandon. Do NOT proceed silently. **Retry re-entry (defined path, capped):** on "retry", re-enter at step 1 of this Invocation contract — reset the `.baldart/e2e-review/<CARD-ID>/` state dir, re-spawn `/e2e-review` with the SAME payload, and re-parse. **Cap: 2 error-retries per card** (central repair cap, consistent with the other loops). On the 2nd `error`, do NOT re-offer "retry" — re-invoke `AskUserQuestion` with only skip/abandon, so the loop cannot recur unbounded. |
-
-#### Re-run trigger (after Phase 3.7 `/codexreview`)
-
-If the mandatory `/codexreview` gate in Phase 3.7 modifies any file under
-`${paths.app_dir}`, `${paths.components_primitives}`, or any `*.css` /
-`*.scss`, the orchestrator MUST re-invoke `/e2e-review` BEFORE the Phase 4
-commit. This protects against code-review changes that silently reintroduce
-visual / functional drift. The re-run reuses the same
-`.baldart/e2e-review/<CARD-ID>/` state directory and starts from Phase 3
-of the skill (skipping plan extraction and mockup cascade).
-
-#### Tracker output
-
-Append to `## Current Card` and (on completion) carry into `## Completed Cards`:
-
-```
-e2e-review: <status> | iterations: <N> | findings: <X critical, Y major, Z minor> | drift: [<codes>] | tolerance: <strict|balanced|lenient>
-```
-
-#### Out of scope for this phase
-
-- Mockup re-design (the skill never modifies the mockup — only the
-  implementation).
-- Code review or doc review (those remain Phase 3 / 3.7 responsibilities).
-- Unit-test execution (that is `qa-sentinel`).
-- Visual polish beyond gating findings (advisory Minor findings under
-  balanced/lenient tolerance are logged but not actioned).
-
-#### Legacy cards
-
-Cards written before v3.18.0 (without a `test_plan` block) still work — the
-skill's Phase 1 falls back to deriving Gherkin scenarios from
-`acceptance_criteria` directly. The mockup cascade gracefully degrades when
-`links.design` is missing.
-
----
-
-### Phase 3 — Doc Review & Sync (code review handled by mandatory Phase 3.7 gate)
-
-> **Note**: Code review is NOT performed in this phase — it is handled by the **mandatory unconditional `/codexreview` gate in Phase 3.7**, which runs per-card BEFORE the Phase 4 commit. The post-batch `/codexreview` in the Final review remains as a final FULL-diff sweep over the entire batch (since v3.37.0 — the guaranteed full-depth merge gate). This Phase 3 focuses exclusively on documentation sync, which must happen per-card (tied to the specific commit).
-
-> **Deferral gate (since v4.7.0 — enumerated, `review_profile`-driven)**: SKIP per-card doc-review and defer it to the **Final Review F.3 doc-reviewer** (which runs over the entire batch) when the card is **`review_profile == light` AND its committed diff touches NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). These are small code changes with no doc surface of their own; their only doc concern is drift, which the batch-wide Final doc-reviewer catches. Log `doc-review: DEFERRED to Final FULL gate (light, no doc files in diff)` and proceed to Phase 3.5. **KEEP per-card doc-review** for: `balanced`/`deep` cards, ANY card whose diff touches a doc file (the change IS doc-relevant), and trivial cards (doc-review is their primary gate — § "Trivial-card fast-lane", unchanged). Never defer "for time" — the only enumerated reason is `light + non-doc diff`.
-
-12. **Update tracker**: phase = "3-doc-review".
-13. Build a **Doc Sync Context** block. The coder committed in Phase 2, so detect the card's changed files against the trunk (a bare `HEAD` diff would be empty post-commit):
-    ```bash
-    git diff --name-only "$TRUNK...HEAD" 2>/dev/null || git diff --name-only HEAD~1..HEAD
-    ```
-    Use the output to build this block:
-    ```
-    ## Doc Sync Context
-
-    ### Changed code files (for freshness mapping):
-    [list all code files changed — src/, scripts/, etc.]
-
-    ### Invariant checklist (Linking Protocol — docs/guides/linking-protocol-rollout-v1.md):
-    - [ ] New route.ts added? → ${paths.references_dir}/api/<module>.md + api/index.md count
-    - [ ] New page.tsx added? → ${paths.references_dir}/ui/<domain>.md + ui/index.md Route Summary
-    - [ ] New persistence-layer {entity} ({collection|table|item} per `stack.database`)? → ${paths.references_dir}/data-model.md + the entity's reference doc per project convention (`collections/<domain>.md`, `tables/<domain>.md`, etc.)
-    - [ ] Compound query needing a multi-attribute index? → the matching index artifact MUST be staged in the same commit, per `stack.database`: `firestore.indexes.json` (firestore), migration file or Prisma `@@index` (SQL), `createIndex` script (mongo), GSI/LSI in IaC (dynamodb)
-    - [ ] Backlog card set to DONE? → ${paths.references_dir}/ssot-registry.md entry
-    - [ ] New external dependency? → agents/architecture.md External Dependencies list
-    - [ ] Card has `documentation_impact` field? → verify each listed doc is updated
-    - [ ] New `process.env.VAR` added? → entry in `${paths.references_dir}/env-vars.md` (name, scope, required, feature/card, default)
-    - [ ] Last usage of `process.env.VAR` removed? → mark `status: deprecated` in `${paths.references_dir}/env-vars.md` with the date
-    - [ ] Default value changed in the project's env module (e.g. `src/lib/env.ts`)? → update the Default column in `${paths.references_dir}/env-vars.md`
-    - [ ] Card has an `env_vars` field populated? → verify each entry is tracked in `${paths.references_dir}/env-vars.md`
-
-    ### Related docs to check (per convention map):
-    - [derive from FRESHNESS_MAP: src/app/api/** → ${paths.references_dir}/api/; src/lib/booking/** → booking.md etc.]
-    ```
-
-    Invoke the **doc-reviewer** agent in **audit-and-apply mode** (single invocation — it both finds the gaps AND fixes them, per `doc-reviewer.md` § Constraints), passing the Doc Sync Context:
-    ```
-    Doc Sync Context:
-    [paste the Doc Sync Context block built above]
-
-    Instructions for doc-reviewer:
-    - You OWN the `doc` domain end-to-end: audit AND apply the fixes in THIS invocation.
-      Do NOT defer doc writes to another agent — you are the agent with the doc-invariant
-      contract and the full context. Write the missing/stale docs directly.
-    - Set freshness_status: fresh and last_verified_from_code: <today's date> on any doc you touch
-    - Check each invariant in the checklist above and fix any that are unmet
-    - Update any doc in "Related docs to check" that should be marked stale/fresh
-    - Run your standard doc audit on all changed files and apply the corrections
-    - **Spec/docs-drift → bug lens (MANDATORY since v3.35.0)**: flag any place where the
-      implementation contradicts a documented contract/spec in a way that can cause incorrect
-      behavior (response shape diverging from `api/<module>.md`, field semantics diverging from
-      `data-model.md`, etc.). This lens was previously exclusive to `/codexreview` agent #4; the
-      per-card Phase 3.7 gate now skips that duplicate (lean mode), so THIS pass MUST carry it.
-      A doc-drift→bug finding whose root cause is in CODE (not the doc) is the ONE thing
-      doc-reviewer does NOT fix itself — report it with the conflicting code location + the doc
-      it violates, and the orchestrator routes it to the `security`/code fix path as appropriate.
-    ```
-    Doc-reviewer applies all doc-domain fixes itself. The orchestrator does NOT spawn a coder for doc fixes (since v3.40.0 — `doc` is owned by `doc-reviewer`, see "Domain-Override Domains"). The only doc-reviewer output that leaves this phase unfixed is a **doc-drift→bug finding rooted in CODE** (the implementation contradicts a documented contract). Route it explicitly: if the conflicting code file matches the `security` Domain-Override match rule (`paths.high_risk_modules`) → spawn `coder` with the finding now, in this phase (a security-class code fix is not deferrable to a `light` Phase 3.7); otherwise carry the finding into the Phase 3.7 `/codexreview` input as a known code-drift bug and let the Phase 3.7 fix sub-loop apply it. Either way, append a Fix Application Log row with `domain=codex-correctness` (NOT `doc`) so telemetry attributes it as a code fix. Do NOT leave it accumulating in the tracker with no fix owner.
-14. **Knowledge-corpus sync (OPTIONAL — only if the project ships a corpus-sync agent)**: There is NO shipped `obsidian-sync` agent — do NOT dispatch one (a hard dispatch to a non-existent subagent fails silently). Only when the project provides its own knowledge-corpus sync agent (declared in `.baldart/overlays/new.md`) AND doc-reviewer's findings indicate a corpus impact, invoke that agent with the listed paths after the doc fixes are applied. Otherwise skip with a one-line notice (`knowledge-corpus sync: skipped (no corpus-sync agent configured)`). Non-blocking either way.
-15. **Telemetry** — after doc-reviewer returns, append one row per doc finding to `## Fix Application Log`: `3 | doc | est_lines=<n> | decision=doc-reviewer | applied_by=doc-reviewer | finding=<1-line>`. If 0 findings, append one row: `3 | doc | est_lines=0 | decision=skipped | applied_by=- | reason=no-findings`. **Phase-8 producer (named counter)** — ALSO record the per-card doc-gap counts as a structured line in `## Current Card` (carried into `## Completed Cards` at Phase 5): `doc_gaps: found=<N> fixed=<M>` where `N` = total doc findings doc-reviewer raised and `M` = those it applied. This is the single named producer for Phase 8's `doc_gaps_found` / `doc_gaps_fixed` fields — without it those fields have no upstream write and Phase 8 would hard-code zeros. (D.4a is the team-mode producer of the same counter — see Phase 7 § D.4a.)
-16. Run `npm run lint` and `npx tsc --noEmit` (when `stack.language` includes typescript) to verify nothing broke (redirect to disk per § "Context economy"). If doc-reviewer touched any source-adjacent file (a `.ts`/`.tsx` helper, a co-located doc export), also run `npm run build`. If any check fails, apply the self-healing retry loop (up to 3 times, no user prompt). **If still failing after 3 retries**: do NOT fall through silently to Phase 3.5 — log `[DOC-PHASE-REGRESSION]` in `## Issues & Flags` and invoke `AskUserQuestion` (revert the doc-phase edits that broke the build / keep and fix manually / stop the card).
-17. **Telemetry for the step-16 self-heal** — if the retry loop spawned any fix (a code edit to recover from a doc-phase regression), append a Fix Application Log row for it AFTER the loop settles (the step-15 doc telemetry row was written before this loop ran, so it does not capture step-16 fixes). Then update tracker: phase = "3-doc-review DONE", log doc findings count, fixes applied.
-    If doc-reviewer found a recurring gap, append 1-line to `## Lessons Learned`:
-    `DOC: <pattern>`
-
-### Phase 3.5 — QA Validation
-
-18. **Update tracker**: phase = "3.5-qa".
-19. **Select QA profile**: READ the card's `review_profile` field (use verbatim); only compute via the QA Profile Selector above (whose criteria SSOT is `prd-card-writer.md § Rule C`) when the field is absent (legacy card). Log the chosen profile and its source (`from card` | `computed`) in the tracker (1 line).
-20. **If profile is SKIP**: log "QA skipped — [reason]" in the tracker. Proceed to Phase 4.
-21. **If profile is LIGHT**: SKIP qa-sentinel. Phase 2 step 8 ran lint/tsc/test/build, AND the two code-mutating phases that follow it (Phase 2.55 Simplify, Phase 3 doc-reviewer) each re-run lint + tsc on their post-mutation output (so the static checks cover the committed code, not just the pre-mutation code). Log "QA LIGHT skipped — lint/tsc/test/build passed in Phase 2 and lint/tsc re-ran post-mutation in 2.55/3" in the tracker. Proceed to Phase 4.
-21b. **If profile is BALANCED (since v4.7.0 — deferral to Final, enumerated `review_profile`-driven)**: SKIP per-card qa-sentinel and **defer the test suite to the Final Review F.3 qa-sentinel** (which runs the FULL suite + build + audit over the entire batch — the unconditional merge gate). Phase 2 step 8 already ran lint/tsc/test/build on this card's diff. **Exception — risk escalation runs FULL per-card anyway**: if the Phase 3.7 Step A detector matched any high-risk trigger on this card's diff (auth/permission/payment/schema/migration/API-contract), do NOT defer — run qa-sentinel at FULL here for fail-fast. Log `QA balanced deferred to Final FULL gate (no risk escalation)` or `QA balanced escalated to FULL (risk drift: <trigger>)`. ⚠️ Most `feature`/`enhancement` cards are `balanced` (Rule C), so a balanced-only batch first runs the suite at the Final gate; the merge gate stays safe (Final = full suite over the whole batch). Proceed to Phase 4 when deferred.
-22. **If profile is DEEP (or BALANCED escalated by risk drift — see 21b)**: invoke the **`qa-sentinel`** agent (subagent_type: `qa-sentinel`) via Task tool with the following context:
-
-    ```
-    Run QA gates on card <CARD-ID> at the tier dictated by the QA profile below (do NOT default to FULL).
-    You are a MECHANICAL GATE-RUNNER: run the gates, return a PASS/FAIL gate table + confidence.
-    Do NOT read source files to analyze logic, do NOT emit a BLOCKER/MAJOR/MINOR severity taxonomy,
-    do NOT do collateral-impact analysis, and do NOT write tests.
-
-    Context:
-    - Worktree path: <worktree-path> — `cd` into it before running any gate
-    - Branch: <branch-name>
-    - Changed files: <list from implementation phase>
-    - QA profile: [deep | balanced-escalated]
-
-    Tier contract: deep → FULL suite. A BALANCED card only reaches this step when risk drift
-    escalated it (step 21b) — run it at FULL too (the escalation reason is the fail-fast signal).
-    A non-escalated balanced card never reaches here (its suite is deferred to the Final FULL gate
-    per step 21b). File count never escalates.
-
-    E2E is NOT your job (run by the /e2e-review skill in Phase 2.6) — do NOT run Playwright.
-    Run the gates: lint, tsc (when stack.language includes typescript), test (per tier), build, markdownlint.
-    Do NOT verify acceptance criteria (Phase 2.5 already did this).
-    Do NOT analyze code for bugs/patterns (the per-card /codexreview gate in Phase 3.7 does this).
-
-    Write the gate results + verdict to: /qa/<CARD-ID>.md
-    Report should be under 40 lines.
-    Return verdict: PASS or FAIL (+ the per-gate table).
-    ```
-
-23. **Read qa-sentinel's output.** Verify the findings file was written to `/qa/<CARD-ID>.md`. **If the file is absent** (qa-sentinel returned a verdict but did not write it): re-invoke qa-sentinel once asking it to (re-)write the file; if still absent, treat the verdict from the return message as authoritative, log `[QA] findings file missing — used return verdict` in `## Issues & Flags`, and pass the captured gate output (not a missing path) to any fix coder.
-24. **If QA verdict is FAIL** (one or more gates failed):
-    - Spawn the **coder** agent to fix the FAILING GATES (pass it the findings file path + the failing-gate output — NOT a severity-ranked finding list; qa-sentinel does not emit one). Do NOT ask the user.
-    - After coder fixes, re-invoke `qa-sentinel` in the same mode to re-validate. Repeat up to **2 times**.
-    - If still FAIL after 2 retries: log in `## Issues & Flags` and **ask the user** whether to proceed or stop.
-    - The commit in Phase 4 MUST NOT happen until QA verdict is PASS (or user explicitly overrides).
-    - **Telemetry** — after each coder spawn, append one row per failing-gate fix to `## Fix Application Log`: `3.5 | qa-blocker | est_lines=<n> | decision=coder | applied_by=coder | retry=<0|1|2>`. After PASS without any spawn (initial verdict PASS), append one row: `3.5 | qa-none | est_lines=0 | decision=skipped | applied_by=- | reason=qa-pass`.
-25. **Update tracker**: phase = "3.5-qa DONE", log: profile used, tier run (SCOPED/FULL) + any risk-drift escalation, verdict (PASS/FAIL/SKIP), confidence %, failing gates (which of lint/tsc/test/build/markdownlint), findings file path. (qa-sentinel returns a per-gate PASS/FAIL table, not a blockers/majors/minors split — do not invent one.) **Phase-8 producer (named flag)** — ALSO record `qa_first_attempt: <pass|fail>` on the card's `## Completed Cards` QA line: `pass` ⟺ the FIRST qa-sentinel invocation (step 22, retry=0) returned PASS with no step-24 coder spawn; `fail` ⟺ a retry was needed (or the profile reached PASS only after a fix). For `SKIP`/`LIGHT` cards (qa-sentinel not run) record `qa_first_attempt: n/a`. This is the single named producer for Phase 8's `qa_pass_first_attempt_rate` — the tracker otherwise logs only the final verdict, so the first-attempt signal must be tagged here at the source.
-
-### Phase 3.7 — Pre-Merge Codex Review Gate (MANDATORY — UNCONDITIONAL)
-
-**This gate runs for EVERY card with code to review before the Phase 4 commit.** A per-card `/codexreview` MUST run BEFORE the Phase 4 commit, regardless of file paths or perceived risk. The historical conditional High-Risk Path detector is preserved below — but only as a **signal-logging step** to record *which* triggers matched in the tracker. It NEVER suppresses the `/codexreview` invocation. Even if zero triggers match, `/codexreview` runs.
-
-> **Single carve-out — `IS_TRIVIAL` fast-lane (since v4.6.0)**: a card that is `IS_TRIVIAL` on its ACTUAL committed diff (`review_profile=skip` + non-source diff + 0 Step-A triggers — § "Trivial-card fast-lane") **skips this gate**, because there is no code for Codex to review. Its adversarial coverage is carried by the SAME unconditional **Final-review FULL gate** the `light` path already relies on (it runs Codex over the entire batch diff, including every trivial card's files, before merge). This is NOT a `time budget` skip — it is the deterministic `IS_TRIVIAL` gate reason, and the guard means a single source file in the diff flips the card back onto this gate. Log `codex-review: SKIPPED (trivial — non-source diff; covered by Final FULL gate)`.
-
-**Rationale**: leaving the gate conditional caused it to be silently skipped on the majority of cards, defeating the AGENTS.md "MUST run BEFORE merge" requirement. The gate itself is unconditional — what varies is its DEPTH (`light` vs `full`). The protection against a missed blocker on a "low-risk" path (BUG-0530-class regressions) is carried by two mechanisms, not by an always-on per-card Codex pass: (1) the Step A detector escalates any risky diff to `full` per-card, and (2) the unconditional **Final-review FULL gate** runs Codex adversarial over the entire batch diff before merge. So `light` can safely run `code-reviewer` + FP-gate only (since v3.38.0) without weakening the merge gate.
-
-#### Step A — Detect (signal-logging only, NEVER gates the next step)
-
-Run this exact bash block in the worktree. It is deterministic (grep + path match), not LLM-discretionary.
-
-`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, autodetected when the key is absent — see Phase 0 step 0). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.** `BACKLOG_DIR` is the value of `paths.backlog_dir` from `baldart.config.yml` (fallback `backlog` when the key is absent — emit it resolved, never the literal `${paths.backlog_dir}` token, which is not valid bash). The card lookup uses `-iname` (case-insensitive) on purpose: card filenames carry uppercase prefixes (`FEAT-`/`BUG-`/`CHORE-`) but `CARD_ID` may arrive lowercased (e.g. `/new feat-0019`), and a case-sensitive `-name` would return empty silently → the card would be treated as non-existent.
-
-```bash
-cd <worktree-path>
-CARD_ID="<CARD-ID>"
-BACKLOG_DIR="<value of paths.backlog_dir, or 'backlog' if the key is absent>"
-CARD_FILE="$(find "$BACKLOG_DIR" -iname "${CARD_ID}*.yml" 2>/dev/null | head -1)"
-# Detect what THIS card's commits changed against the trunk (post-commit), with an uncommitted fallback:
-CHANGED="$(git diff --name-only "$TRUNK...HEAD" 2>/dev/null || git diff --name-only HEAD~1..HEAD)"
-# High-risk path alternation from config (empty when paths.high_risk_modules is unset):
-HIGH_RISK_RE="<alternation of paths.high_risk_modules entries, or empty>"
-
-TRIGGERS=()
-
-# Trigger #1 — High-risk module (auth / permission / payment / shared scoring-or-ranking primitive)
-# Sourced from paths.high_risk_modules — NOT a hardcoded project path.
-if [ -n "$HIGH_RISK_RE" ]; then
-  echo "$CHANGED" | grep -qE "$HIGH_RISK_RE" \
-    && TRIGGERS+=("#1: high-risk module (paths.high_risk_modules)")
-else
-  echo "[DETECTOR] paths.high_risk_modules absent — path-based high-risk trigger skipped" >&2
-fi
-
-# Trigger #2 — Dead-code resurrection (card text + commit messages)
-{ cat "$CARD_FILE" 2>/dev/null; git log --format=%B "$TRUNK...HEAD" 2>/dev/null; } \
-  | grep -qiE 'dead code|unreachable|resurrect' \
-  && TRIGGERS+=("#2: Dead-code resurrection")
-
-# Trigger #3 — Reference-aliasing mutation pattern (in-place array reset + push)
-# Card introduces or modifies an exported helper AND a call site in the diff mutates an input
-# array in place via `length = 0` + `push(...result)`. Even with a local identity guard, the
-# high-risk gate runs adversarial review to confirm the contract is robust against future callers.
-# Iterate file-by-file safely (no unquoted xargs filename expansion):
-RESET=""; PUSH=""
-while IFS= read -r f; do
-  [ -n "$f" ] || continue
-  C="$(git show "HEAD:$f" 2>/dev/null)" || continue
-  printf '%s' "$C" | grep -qE '\.length\s*=\s*0' && RESET=1
-  printf '%s' "$C" | grep -qE '\.push\(\s*\.\.\.' && PUSH=1
-done <<< "$CHANGED"
-[ -n "$RESET" ] && [ -n "$PUSH" ] \
-  && TRIGGERS+=("#3: Reference-aliasing mutation pattern")
-
-printf '%s\n' "${TRIGGERS[@]}"
-```
-
-#### Step B — Log detector result (never skips)
-
-Log the detector output in the tracker for traceability. **This step never short-circuits Step C — `/codexreview` runs unconditionally regardless of whether `TRIGGERS` is empty or populated.**
-
-- If `TRIGGERS` is empty: log `## Pre-Merge Codex Review: no high-risk triggers matched (gate still runs unconditionally)` and proceed to Step C.
-- If `TRIGGERS` is non-empty: log the matched triggers (see Step C step 1) and proceed to Step C.
-
-#### Step C — Invoke per-card `/codexreview` (ALWAYS)
-
-For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH varies):
-
-0. **Select the Codex review profile (deterministic — Review Profile Selector)** by mapping the
-   card's review profile (read from the card's `review_profile` field per the QA Profile Selector
-   above — since v3.38.0; fallback-computed only for legacy cards) and the Step A detector:
-   - **`light`** ⟺ the card's profile ∈ {`skip`, `light`} **AND** Step A matched **zero**
-     high-risk triggers.
-   - **`full`** ⟺ otherwise — i.e. the card's profile ∈ {`balanced`, `deep`}, **OR** any Step A
-     trigger matched.
-
-   **Escalation-only invariant (since v3.38.0)**: the Step A detector runs on the ACTUAL diff and
-   can only ever **escalate** `light` → `full` (a high-risk path surfaced at implementation time
-   that the card's authored profile didn't anticipate). It can NEVER downgrade `full` → `light`.
-   The card's `review_profile` is the deterministic floor; the diff detector is the safety net on
-   top of it.
-
-   `light` is **NOT** a skip: `/codexreview` still runs `code-reviewer` + the Step 3 false-positive
-   gate. **Since v3.38.0 the per-card Codex adversarial pass is NO LONGER run at `light`** — it is the
-   prerogative of `full` and of the final cross-check. `light` drops the Codex adversarial pass AND the
-   breadth agents (qa-sentinel, api-perf-cost-auditor, doc-reviewer) AND Step 3.5 CoVe — leaving exactly
-   `code-reviewer` + FP-gate, the cheap per-card pass that yields the early feedback worth having on a
-   0-trigger, QA-light diff. `full` is unchanged (Codex adversarial + the full agent set, minus the
-   duplicate doc-reviewer).
-   **Where the BUG-0530 invariant now lives.** Pre-v3.38.0 the per-card Codex adversarial was the
-   "never miss a blocker on a low-risk path" guard. Two mechanisms now carry that guarantee instead,
-   so dropping it from `light` is safe:
-   1. **Escalation-only (Step A)** — any high-risk trigger on the ACTUAL diff promotes `light` → `full`,
-      so genuinely risky paths (auth/payment/permission/schema/…) STILL get per-card Codex adversarial.
-      Only a 0-trigger, authored-`light` card defers it.
-   2. **Final-review FULL gate (since v3.37.0)** — the **Final review ALWAYS runs a single FULL
-      `/codexreview` over the entire batch diff before merge** (no N=1 skip, no scope reduction — see
-      "Final review → Final-review FULL gate"), and FULL includes Codex adversarial. So every line of
-      every `light` card receives Codex adversarial at least once before merge.
-   Net effect: `light` per-card = early `code-reviewer` feedback; the Codex adversarial review is paid
-   once, at the final batch gate (or per-card the moment a risk trigger fires). To put per-card Codex
-   back on `light`, re-add agent #5 to the `light` branch of `/codexreview` Step -0.5.
-
-   Then dump the card diff (reviewer grounding) and write the lean contract `/codexreview` consumes:
-   ```bash
-   cd <worktree-path>
-   # $TRUNK = the trunk branch resolved in Phase 0 (git.trunk_branch)
-   git diff "$TRUNK...HEAD" -- <card files from ownership map> > /tmp/diff-<CARD-ID>.txt 2>/dev/null \
-     || git diff HEAD~1..HEAD > /tmp/diff-<CARD-ID>.txt
-   ```
-   Write `/tmp/codexreview-lean-<CARD-ID>.json`:
-   ```json
-   { "profile": "light|full", "arch_baseline_path": "/tmp/arch-baseline-<CARD-ID>.md",
-     "diff_summary_path": "/tmp/diff-<CARD-ID>.txt", "skip_doc_reviewer": true,
-     "skip_api_perf_auditor": true }
-   ```
-   `skip_doc_reviewer` is ALWAYS true: Phase 3 already ran `doc-reviewer` on this diff (with the
-   spec/docs-drift→bug lens since v3.35.0), so `/codexreview` agent #3 would be a duplicate.
-   `skip_api_perf_auditor` is ALWAYS true (since v4.7.0): the per-card api-perf/cost pass is deferred
-   to the **Final Review F.3 api-perf-cost-auditor** (batch-wide), so `/codexreview` agent #2 would be
-   a duplicate of the final sweep. (At `full` `/codexreview` would otherwise spawn it; at `light` it is
-   already dropped.)
-
-1. **Log gate invocation** in the tracker under `## Pre-Merge Codex Review`:
-
-   ```
-   ## Pre-Merge Codex Review
-   - Triggered: unconditional (mandatory pre-merge gate)
-   - Profile: light | full — reason: <review_profile=<skip|light|balanced|deep> (from card | computed); triggers=0 | trigger #N matched (escalated light→full)>
-   - Matched high-risk triggers: <list from detector, or "none">
-   - Action: invoking /codexreview <CARD-ID> (per-card, pre-merge gate; lean contract written)
-   ```
-
-2. **Invoke `/codexreview`** for the single card via the Skill tool:
-
-   ```
-   Skill: codexreview
-   args: <CARD-ID>
-   ```
-
-   `/codexreview` Step -0.5 consumes `/tmp/codexreview-lean-<CARD-ID>.json`: reuses the Phase-1
-   architecture baseline (no re-spawn), drops the duplicate doc-reviewer, and for `profile: light`
-   also drops qa-sentinel + api-perf-cost-auditor + **the Codex adversarial pass** + Step 3.5 CoVe
-   (since v3.38.0). `code-reviewer` + Step 3 FP-gate + Step 4 report ALWAYS run. (`full` = standard
-   pipeline incl. Codex adversarial, minus the duplicate doc-reviewer.)
-
-3. **Read the consolidated report**. `/codexreview` writes it to `/tmp/codexreview-report-<TIMESTAMP>.md` and RETURNS that exact path in its Skill-tool result — use the returned path, do NOT guess the timestamp. If the return value did not surface the path, locate the newest report whose body names this `<CARD-ID>` (`grep -l "<CARD-ID>" /tmp/codexreview-report-*.md | xargs ls -t | head -1`), never just the newest file by mtime (a parallel card's report could be newer). Extract:
-   - Verified BLOCKER count
-   - Verified HIGH count
-   - List of `[ripple-expanded]` findings (Step 3.5 widened scope). At `light` profile Step 3.5 CoVe does not run, so this list is structurally empty — log `ripple-expanded: 0 (CoVe not run at light)` rather than a bare `0`, so audits can tell "not attempted" apart from "attempted, none found".
-
-4. **Apply fix sub-loop** (mirror of Phase 3.5 retry pattern):
-   - If 0 BLOCKER and 0 HIGH → log `verdict: PASS — proceeding to Phase 4` in tracker. Done. (MEDIUM/LOW findings are advisory at this per-card gate; they are not silently lost — the post-batch **Final-review FULL gate** applies every VERIFIED finding ≥ MEDIUM. Log the MEDIUM count in the tracker so it is visible.)
-   - If 1+ BLOCKER OR 1+ HIGH → spawn `coder` agent with the report path + list of VERIFIED bugs. **At `full` profile** the report contains Codex-suggested inline patches: pass them and have the coder **apply the suggested patches** with the right system prompt (project conventions, naming, testing patterns) — it does NOT re-do the analysis or re-grep (since v3.28.3), BUT it MUST first confirm each patch still applies against the current file state (prior fix-loop iterations may have shifted line offsets); if a patch no longer applies cleanly, the coder re-locates the target by content and applies the equivalent edit rather than a stale-offset verbatim paste. **At `light` profile** no Codex adversarial patches exist (the pass was dropped) — the findings come from `code-reviewer`; brief the coder accordingly (apply the `code-reviewer` fix direction; there are no Codex patches to paste). After coder fixes, **re-write the lean contract `/tmp/codexreview-lean-<CARD-ID>.json` (it is consumed-once and deleted by `/codexreview`)** and re-invoke `/codexreview` via the Skill tool with `args: <CARD-ID>` (NOT a bare prose mention — the card ID MUST be passed so the retry reviews THIS card, not an inferred one). Repeat **max 2 times**.
-   - If still BLOCKER/HIGH after 2 retries → log in `## Issues & Flags` and **ask the user** whether to proceed, escalate, or stop. The Phase 4 commit MUST NOT happen until the Pre-Merge Codex Review verdict is PASS or user explicitly overrides.
-   - **Telemetry** — for EVERY codex finding processed (verified BLOCKER, verified HIGH, or false-positive-filtered), append one row to `## Fix Application Log`: `3.7 | codex-<security|correctness|other> | est_lines=<n> | decision=<coder|skipped> | applied_by=<coder|-> | severity=<BLOCKER|HIGH|FALSE-POSITIVE> | retry=<n>`. Classify domain: `security` for findings touching RLS / auth / permissions / payments; `correctness` for logic / data integrity / race conditions; `other` for everything else.
-
-5. **Update tracker**: phase = `3.7-codexgate DONE` (the gate runs unconditionally for every card — the legacy `3.7-highrisk` name implied it only fired on high-risk cards, which is no longer true), log final verdict, retry count, list of fixed findings, and the report path.
-
-6. **E2E re-run obligation check (enforces the Phase 2.6 re-run trigger HERE)** — if this Phase 3.7 fix sub-loop modified any file under `${paths.app_dir}`, `${paths.components_primitives}`, or any `*.css` / `*.scss`, you MUST re-invoke `/e2e-review` (programmatic mode, same `.baldart/e2e-review/<CARD-ID>/` state dir) BEFORE the Phase 4 commit and resolve its verdict per the Phase 2.6 gating-logic table. Log `e2e-rerun: triggered` or `e2e-rerun: not-needed (no UI files touched in 3.7)` in the tracker so Phase 4 can assert it. Do NOT defer this to "it's documented in Phase 2.6" — the check fires here, where the fixes happen.
-
-#### Why deterministic detector + agent pipeline
-
-The detector (Step A) is bash + grep — guaranteed to run, no LLM skip. The downstream pipeline (Step C) is the existing `/codexreview` skill — fully tested, includes Codex adversarial review and Step 3.5 cross-agent CoVe. This combination ensures the AGENTS.md "MUST run BEFORE merge" rule is enforced reliably.
-
-**Crash handling**: if `/codexreview` (or its fix-loop `coder`) crashes mid-phase, apply the "Sub-agent failure protocol" (below). Treat this gate as a **mandatory gate, NOT a non-domain-override fallback** — `/codexreview` covers the `security` domain (auth/payment/permission findings), so a crash that cannot be recovered by one retry STOPS the pipeline and routes to `AskUserQuestion`; do NOT rationalize it as "non-domain-override" and inline-bypass the merge gate.
-
-### Phase 4 — Commit (in worktree, NO merge yet)
-
-> Sequential-mode global step numbering resumes here at 26 (Phase 3.5 ended at 25; Phase 3.7 used its own local C.0–C.6 counter). The tracker phase-string `4-commit` therefore maps to step 26, NOT a second step 25.
-
-26. **Update tracker**: phase = "4-commit". **Entry assertion** — before committing, verify the Phase 3.7 e2e re-run obligation was honored: read the tracker for `e2e-rerun: triggered` / `e2e-rerun: not-needed`. If Phase 3.7 touched UI files but no `e2e-rerun` entry exists, do NOT commit yet — go run the re-run per Phase 3.7 step 6 first. Also confirm Phase 3.5/3.7 fixes did not leave lint/tsc broken: if the Phase 3.7 fix sub-loop applied any patch, run `npm run lint` + `npx tsc --noEmit` (when typescript) once before committing (redirect to disk per § "Context economy").
-27. Stage and commit **all changes together** in the worktree using format `[CARD-ID] Brief description` (MUST per AGENTS.md). Include all relevant files — implementation, review fixes, QA-driven fixes, and doc updates in a single commit. Do NOT merge or push yet — that happens post-batch.
-    - **IMPORTANT — explicit staging**: NEVER use `git add -A` or `git add .`. Always stage files by explicit name:
-      ```bash
-      cd <worktree-path>
-      # List changed files
-      git diff --name-only
-      git ls-files --others --exclude-standard
-      # Stage only the files this card touched (explicit names)
-      git add src/path/to/file1.ts src/path/to/file2.ts ...
-      # Commit directly — NO stash in worktrees
-      git commit -m "[CARD-ID] Brief description"
-      ```
-    - **WORKTREE COMMIT RULE — NEVER use `git stash` in worktrees.** Stashes are globally shared across all worktrees (`refs/stash` via `git.commondir`). A stash created in one worktree can be popped by another, causing conflicts, data loss, and cascading merge failures. The file ownership map ensures no overlap between cards — explicit staging is sufficient isolation. The stash pattern in AGENTS.md applies ONLY to the main repo working tree.
-    - **If commit fails**:
-      0. **"Nothing to commit" is NOT a failure** — if the error is `nothing to commit, working tree clean`, all changes were already committed by a prior step (e.g. doc-reviewer committed its own docs, or a Phase 3.7 fix was already committed). Treat the card commit as already done, record the existing HEAD hash, and proceed to step 28 (Mark card DONE) — do NOT enter the COMMIT_LOCK / re-stage loop.
-      1. **Check for stale COMMIT_LOCK first** — parallel agents and crashed processes leave stale lock files. Always clear before retry:
-         ```bash
-         rm -f <main-repo>/.git/worktrees/<worktree-name>/COMMIT_LOCK 2>/dev/null
-         ```
-      2. Re-stage the same files explicitly and retry. Never run `git commit` alone after a failure — the staging area may have been altered by lint-staged auto-fixes. If lint-staged removed an "unused" variable that IS used by code in a later card, check `git diff` to see what changed, restore the needed code (explicit file write — **never `git stash pop` in a worktree**), re-stage, and retry.
-      3. **Retry cap + escalation** — retry the commit at most **2 times**. If it still fails (e.g. a pre-commit / doc-freshness rule that cannot be satisfied without human input), log the failure in `## Issues & Flags` as `[COMMIT-BLOCKED] <error>` and invoke `AskUserQuestion`: (a) fix the blocking condition manually and let me retry, (b) hand off the worktree intact, (c) abandon this card and continue the batch. Do NOT loop indefinitely and do NOT silently proceed to step 28 with an uncommitted card.
-    - The Claude Code pre-commit hook automatically skips for worktree commits (Husky handles checks natively in the worktree).
-28. **Mark card DONE (MANDATORY — do NOT skip)**:
-    a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`.
-    b. Add implementation notes summarizing what was built.
-    c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `${paths.backlog_dir}/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
-    d. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry the edit.
-    e. Stage BOTH the updated YAML AND ssot-registry.md, then commit (or as an immediate follow-up commit if the Phase 4 implementation commit already happened). When this produces a SECOND commit for the card, record BOTH hashes in the tracker (`commit: <impl-hash> + <done-hash>`) so traceability/bisect is unambiguous.
-29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`**. **→ Visibility**: TaskUpdate this card's spine task → `completed` (strip any live phase suffix) and emit a Progress Bar (card change) per § "Progress Visibility".
-
-### Sub-agent failure protocol (since v3.28.3)
-
-If any sub-agent **crashes or errors** during any phase, follow this 4-step protocol. The pre-v3.28.3 wording ("attempt the work yourself directly") was being used as a shortcut to bypass delegation rules even when no agent had crashed — that escape valve is closed.
-
-1. **Log the failure** in the tracker with the full error trace (under `## Issues & Flags`, prefix `[AGENT-CRASH]`).
-2. **Retry the same agent once**. Transient errors (network, rate-limit, race) are common; a single retry resolves most.
-3. **If retry fails AND the fix is in a domain-override domain** (`doc`, `security`, `migration` — see "Domain-Override Domains" sub-section): **STOP the pipeline**, log in `## Issues & Flags`, and invoke `AskUserQuestion` with options (a) skip the finding, (b) hand off to user, (c) escalate to a different agent type. **NEVER** fall through to inline orchestrator apply for these domains. The whole point of delegation here is that the orchestrator does not have the right system prompt — bypassing on crash defeats the rule.
-4. **If retry fails AND the fix is non-domain-override**: orchestrator MAY apply inline, but MUST log a Fix Application Log row with `applied_by=orchestrator-fallback` + `reason=<agent>-crash-retry-failed` so the telemetry surfaces frequency. If this happens often for the same agent, that agent's reliability is the problem, not the protocol.
-
-Never block the pipeline indefinitely — recover and continue per the rules above. AskUserQuestion in step 3 is bounded by normal user response time.
-
-### Phase 5 — Context Clean & Continue
-30. Archive the card from Active Code Context in `${paths.references_dir}/project-status.md`.
-31. **CONTEXT HYGIENE**: After updating the tracker, stop referencing this card's details. From this point forward do NOT pull this card's code, file contents, or review findings back into your messages — the tracker summary is the only carry-over; if you need a detail, Read the tracker (or the on-disk findings/gate file) at the point you need it. NOTE: this is a *reference-hygiene* instruction, not token reclamation — a prompt cannot make the model "forget" (see § "Context economy"). The real lever is upstream: because the § "Context economy" rules kept this card's bulk (gate logs, diffs, whole files, baselines) OUT of your inline context in the first place, there is little to carry over. If the harness auto-compacts at a card boundary, recover via the tracker per § "Context Tracking".
-32. **Update tracker**: clear `## Current Card`, move to next pending card.
-33. **Move to the next card** — restart the per-card pipeline at **Phase 1 (Claim & Context)** for the next pending card in `## Card Queue`. Do NOT re-run Phase 0 (workspace hygiene runs once per batch) and do NOT re-run Pre-flight worktree setup (the worktree already exists). When all cards in the queue are done, proceed to **Final review**.
-
----
-
-## Final review (after all cards)
-
-> **Primary code reviewer: Codex (a non-Anthropic frontier model, via `codex-companion.mjs`)** — cross-model validation with built-in FP filtering.
-> Claude `code-reviewer` is the automatic fallback if Codex is unavailable.
-> The `/codexreview` command remains available for standalone reviews on demand.
-
-Once ALL cards are committed in the worktree:
-
-> **Final-review FULL gate (since v3.37.0 — supersedes the v3.35.0 scope-reduction)** — because
-> Phase 3.7 may now run a card at `light` depth, the per-card pass can NO LONGER be assumed to have
-> full-reviewed every card. The final review is therefore the **unconditional safety gate that makes
-> the Phase 3.7 `light` profile safe**: it ALWAYS runs a single FULL `/codexreview` (full agent set)
-> over the **ENTIRE batch diff** before merge — **no N=1 skip, no cross-card scope reduction**. Every
-> line of every card — including any reviewed at `light` in Phase 3.7 — receives a full-depth Codex
-> review at least once before merge.
->
-> - Run Steps F.1–F.5 for **EVERY batch, including N=1**. Nothing here is skipped.
-> - `review_scope_files` = the **FULL union** of all touched files across all cards (F.1 step 4 —
->   NEVER reduced to the cross-card subset).
-> - F.3 invokes the full reviewer set (Codex + doc-reviewer + api-perf-cost-auditor + qa-sentinel)
->   over that union; F.5 runs the final build.
->
-> Rationale: this re-introduces the post-batch full pass that v3.35.0 de-duplicated away. That
-> de-dup assumed Phase 3.7 had already full-reviewed every card — an assumption broken the moment
-> `light` became selectable. The cost of one full batch-diff review is the deliberate price of the
-> per-card `light` speed-up (explicit maintainer decision, v3.37.0).
-
-### Step F.1 — Resolve scope
-
-**→ Visibility (batch transition)**: all cards are committed. TaskUpdate `Final review` → `in_progress` and emit a Progress Bar per § "Progress Visibility". Mark `Final review` → `completed` when F.5 finishes (fixes applied, build green).
-
-1. **Read the tracker file** to get the full picture: card IDs, files changed, commit hashes.
-2. Gather git evidence in the worktree:
-   ```bash
-   cd <worktree-path>
-   git diff --name-only <base-branch>...HEAD
-   ```
-3. Read each card's backlog YAML to collect `acceptance_criteria`, `files_likely_touched`.
-4. Build `review_scope_files` as the **FULL union** of card-indicated files + git-touched files
-   across ALL cards in the batch. **Since v3.37.0 this union is NEVER reduced** (the v3.35.0
-   cross-card scope-reduction is removed) — the final review is a full-depth pass over the entire
-   batch diff, so cards reviewed at `light` in Phase 3.7 still get a guaranteed full review before
-   merge. Record the union in the tracker; downstream F.3 reviews it in full.
-
-### Step F.2 — Architecture baseline
-
-5. **Reuse per-card baselines before re-spawning (dedup).** Phase 1 step 5b already persisted one
-   `/tmp/arch-baseline-<CARD-ID>.md` per card. Before spawning `codebase-architect` for the batch
-   scope, check whether every card in the batch already has a readable baseline file:
-   ```bash
-   MISSING=()
-   for c in <ALL-CARD-IDS>; do [ -s "/tmp/arch-baseline-$c.md" ] || MISSING+=("$c"); done
-   printf '%s\n' "${MISSING[@]}"
-   ```
-   - **All present** → do NOT re-spawn the architect for the full batch. Set `${ARCH_BASELINE_PATHS}`
-     to the newline-separated **list of `/tmp/arch-baseline-<CARD-ID>.md` paths** (they already cover
-     every touched file across the batch) — do NOT read or concatenate their contents inline (per
-     § "Context economy" → pass paths, not concatenations; Codex Reads them on demand). Proceed to F.3.
-     Log `f.2-arch: reused N per-card baselines (no re-spawn)` in the tracker. This avoids the N+1
-     architect invocations the per-card persistence was designed to prevent.
-   - **Any missing** (a card was added late, or a baseline was purged) → invoke **codebase-architect**
-     ONCE over the batch scope to map existing architecture, critical patterns, and high-risk code
-     paths for regression. Persist its output to `/tmp/arch-baseline-batch-<FIRST-CARD-ID>.md` and set
-     `${ARCH_BASELINE_PATHS}` to that single path. Log `f.2-arch: re-spawned (missing baselines: <list>)`. Do NOT spawn
-     the architect more than once for the batch — it is the single grounding context for all
-     downstream review agents.
-
-### Step F.3 — Codex deep code review (primary) + Claude agents (support)
-
-> **Primary reviewer: Codex (a non-Anthropic frontier model, via `codex-companion.mjs`)** — cross-model validation. This is a SINGLE-MODEL Codex pass over the batch diff (scope + review + self-FP-check in one task) — it is NOT the full multi-agent `/codexreview` command pipeline (no sub-agent spawning, no Step 3.5 CoVe). The full per-card `/codexreview` already ran in Phase 3.7; this final pass is the cross-model batch-wide sweep. Claude agents (doc-reviewer, api-perf-cost-auditor) provide doc review and supplementary checks; qa-sentinel runs gates only.
-
-6. **Launch Codex code review** via `Bash` with `run_in_background: true` and `timeout: 600000` (10 min). **The companion script is invoked WITHOUT `--wait`** so the Bash call returns immediately and the orchestrator can fire the parallel Claude agents in step 7; poll `$REVIEW_FILE` for completion in F.4 (it is redirected to the file with `> "$REVIEW_FILE" 2>&1`, so it fills as Codex runs and is complete when the background task finishes — no inline `tee` copy, per § "Context economy"). Combining `run_in_background: true` with `--wait` would block the shell and defeat the parallelism — do NOT pass `--wait` here.
-
-   ```bash
-   REVIEW_FILE="/tmp/codexreview-batch-<FIRST-CARD-ID>-<SESSION-ID>.md" && \
-   CODEX_SCRIPT="$(ls -d ~/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)" && \
-   [ -z "$CODEX_SCRIPT" ] && echo "CODEX_NOT_FOUND" > "$REVIEW_FILE" && exit 1; \
-   node "$CODEX_SCRIPT" task "
-   Run a deep multi-agent code review for these backlog cards. This is a post-implementation
-   review — the code is already written and committed. Your job is to find bugs, regressions,
-   security issues, and quality problems.
-
-   Cards to review (read each file):
-   ${CARD_PATHS}
-
-   Files changed (review ALL of these):
-   ${REVIEW_SCOPE_FILES}
-
-   Architecture baseline files (read each — they hold file paths, type signatures, patterns, high-risk paths):
-   ${ARCH_BASELINE_PATHS}
-
-   Follow the /codexreview protocol:
-   1. For each card, read its backlog YAML for acceptance_criteria and entrypoints.
-   2. Read every changed file in full.
-   3. Check for: functional bugs, logic flaws, regressions, cross-card inconsistencies,
-      security issues (auth gaps, input validation, multi-tenant isolation),
-      performance issues (unbounded reads, N+1, missing pagination),
-      missing error handling on external boundaries.
-   4. For each finding, return:
-      - finding_id: <CARD-ID>-F###
-      - title: short description
-      - severity: BLOCKER | HIGH | MEDIUM | LOW
-      - confidence: 0-100
-      - evidence: exact file:line + code quote
-      - minimal_fix_direction: what to change
-   5. Run mandatory false-positive check: for each finding, ask 'What is the strongest
-      argument this is a false positive?' Suppress if the FP argument is convincing.
-   6. Classify surviving findings as VERIFIED, FALSE_POSITIVE, or NEEDS_MANUAL_CONFIRMATION.
-
-   Return ONLY verified findings. If zero verified bugs: state 'No verified bugs found.'
-   " > "$REVIEW_FILE" 2>&1
-   ```
-
-   **Variable interpolation** (build the command string before execution):
-   - `${CARD_PATHS}`: newline-separated list of backlog YAML paths
-   - `${REVIEW_SCOPE_FILES}`: newline-separated list from Step F.1
-   - `${ARCH_BASELINE_PATHS}`: newline-separated list of per-card baseline file paths from Step F.2 (Codex Reads them on demand — do NOT inline their contents)
-
-7. **In parallel with Codex**, launch Claude support agents (single message):
-
-   | Agent | `subagent_type` | Focus | Output |
-   |-------|-----------------|-------|--------|
-   | **doc-reviewer** | `doc-reviewer` | Cross-card doc consistency, ssot-registry completeness, invariants | Findings: `finding_id`, `title`, `severity`, `confidence`, `evidence`, `minimal_fix_direction` |
-   | **api-perf-cost-auditor** | `api-perf-cost-auditor` | API/data/performance/cost defects (skip if no API/data files in scope) | Same findings schema |
-   | **qa-sentinel** | `qa-sentinel` | **Mechanical gates ONLY** over the batch scope (lint, tsc, full test suite, build, `npm audit`, markdownlint) | A PASS/FAIL gate table — NOT a findings list. qa-sentinel does not read source files, does not emit severities, and does not do edge-case/reproducibility analysis (its system prompt forbids it). A gate FAILURE feeds the fix-loop the same way a VERIFIED finding does. |
-
-   The two code-aware agents (doc-reviewer, api-perf-cost-auditor) receive: card IDs, YAML, `review_scope_files`, codebase-architect baseline, and a Budget Block per the `/codexreview` Step 2 contract (`framework/.claude/commands/codexreview.md`). qa-sentinel receives only the worktree path + the changed-file list and runs gates. Code-correctness/edge-case analysis is Codex's job (and the per-card `/codexreview` already ran) — do NOT ask qa-sentinel to produce code findings.
-
-   **Fan-out completion barrier (BLOCKING before F.4).** The three Claude agents write to a shared
-   findings pool that F.4 step 9 fans in. Before F.4 reads ANY finding, you MUST have collected the
-   return value of ALL THREE Task invocations from step 7 (doc-reviewer, api-perf-cost-auditor,
-   qa-sentinel) — never start the merge while a Task is still in flight. Because step 7 launches all
-   three in a single message, the harness returns when all three complete; do NOT proceed to step 9
-   on a partial set. (The Codex background task has its OWN barrier — step 8 below polls `$REVIEW_FILE`
-   for completion. The two barriers are independent: wait for BOTH the three Claude Tasks AND the
-   Codex background task before merging.)
-
-### Step F.4 — Collect & merge findings
-
-8. **Read Codex findings** from `$REVIEW_FILE` after the background command completes (the background
-   task was launched with `timeout: 600000` in step 6 — that 10-min window is the max wait).
-   - If file exists and contains findings → use as **primary code review source**.
-   - If file is empty, missing, or contains `CODEX_NOT_FOUND` → **fallback**: spawn `code-reviewer`
-     agent (subagent_type: `code-reviewer`) with the same scope and instructions. Log fallback
-     reason in tracker: `"Codex unavailable — fallback to Claude code-reviewer"`.
-   - **TIMED_OUT branch:** if the 10-min window elapses and `$REVIEW_FILE` still has no terminal
-     output (no findings block and no `CODEX_NOT_FOUND`), treat the Codex pass as **TIMED_OUT** — do
-     NOT block the merge gate waiting indefinitely and do NOT leave the task silently "in-progress".
-     Log `f.3-codex: TIMED_OUT` in `## Issues & Flags` and take the SAME `code-reviewer` fallback as
-     the unavailable case, so the final merge gate still gets a full code review.
-
-9. **Merge all findings** (Codex + Claude agents) into a consolidated list.
-   - Codex findings are already FP-validated (Step F.3 protocol includes it).
-   - Claude agent findings with `confidence < 80` → cross-validate by spawning **`code-reviewer`** as the static validator over the cited file:line; on disagreement between the originating agent and `code-reviewer`, classify the finding `NEEDS_MANUAL_CONFIRMATION` (do NOT silently drop it). (Naming the validator avoids the inconsistent "some second agent" interpretation.)
-   - Classify: `VERIFIED` | `FALSE_POSITIVE` | `NEEDS_MANUAL_CONFIRMATION`.
-   - `VERIFIED` findings proceed to fixes. **`NEEDS_MANUAL_CONFIRMATION` findings are NOT discarded** — list them in `## Issues & Flags` and surface them to the user via `AskUserQuestion` (treat as VERIFIED, treat as FALSE_POSITIVE, or hand off) before merge. Only `FALSE_POSITIVE` are dropped.
-
-### Step F.5 — Apply fixes and final build
-
-10. **Persist verified findings** to `/tmp/batch-final-review-<FIRST-CARD-ID>.md`.
-11. **Merge-blocking gate (mirrors the per-card Phase 3.7 gate this final pass backstops):** if any VERIFIED **BLOCKER or HIGH** finding exists, it MUST be resolved before Phase 6 merge. Apply fixes by **domain owner** (since v3.40.0 — same Domain-Override routing as the per-card phases), then re-verify; if a BLOCKER/HIGH cannot be resolved in a single apply + one retry, log it in `## Issues & Flags` and invoke `AskUserQuestion` (override with reason / escalate to a follow-up card / halt) — do NOT proceed to Phase 6 with an unresolved BLOCKER or HIGH. VERIFIED findings of severity MEDIUM are also applied (advisory below that). Partition the verified findings by the **Domain-Override match rules** ("Domain-Override Domains"):
-    - **`doc`-domain findings** (file path matching the `doc` match rule — `*.md` under `${paths.references_dir}`/`${paths.prd_dir}`, `CHANGELOG.md`, `ssot-registry.md`) → invoke the **doc-reviewer** agent once in write mode to apply them. NEVER route doc fixes to coder.
-    - **`security`-domain findings** (path in `paths.high_risk_modules`, or RLS-policy SQL) and **`migration`-domain findings** (SQL under the migrations dir) → route to **coder**, but apply the Sub-agent failure protocol's STOP-on-crash rule for these domains (never inline-fallback on a security/migration fix). These are NOT collapsed into a generic "everything else" bucket.
-    - **All remaining findings** (other code, perf, test) → invoke the **coder** agent once to apply them in a single pass.
-    Run in the order doc-reviewer → coder (or skip either if its partition is empty). Pass only the verified findings, not false positives.
-12. Run final build: `npm run lint && npx tsc --noEmit && npm run build` (redirect each to `/tmp/final-<gate>.txt` per § "Context economy"; surface only exit code + bounded extract on failure).
-    If any check fails, apply self-healing retry loop (up to 3 times).
-13. **Update tracker** with final review results:
-    - Review engine: Codex (a non-Anthropic frontier model, resolved at runtime by `codex-companion.mjs`) (primary) | Claude code-reviewer (fallback)
-    - Total findings raised / verified / false positives / needs-manual
-    - Fixes applied count
-    - Build status (pass/fail + retry count)
-    - Highest severity found
-    - **Phase-8 producer (named counters)** — ALSO write the structured line `review_findings: total=<R> verified=<V> blockers=<B>` to the tracker `## Final Review` section, where `R` = all findings raised (Codex + Claude agents, pre-FP), `V` = VERIFIED count, `B` = VERIFIED-BLOCKER count. These are the single named producers for Phase 8's batch-level `findings_total` / `findings_verified` / `blockers_count` — Phase 8 reads THESE keys, never re-parses prose. (Per-card Phase 3.7 codex counts stay in `## Pre-Merge Codex Review`; Phase 8 uses the batch-level `review_findings` line here as the canonical total so the QA-findings and codex-findings counts are not conflated.)
-
-### Step F.6 — Post-review wrap-up (SSOT summary, sync, hand-off to Phase 6)
-
-> This is a distinct sub-section from F.1–F.5 (its own list); the numbering below restarts and does NOT continue the F.5 counter.
-
-1. **SSOT & Documentation Activity** (MANDATORY — run BEFORE merge):
-
-   Summarize all documentation and SSOT updates performed during the batch:
-
-   ```
-   ## Aggiornamenti SSOT & Documentazione
-
-   ### Documenti aggiornati
-   - `${paths.references_dir}/api/<module>.md` — N nuovi endpoint aggiunti
-   - `${paths.references_dir}/ui/<domain>.md` — N nuove route aggiunte
-   - `${paths.references_dir}/data-model.md` — N nuove collection
-   - `${paths.references_dir}/ssot-registry.md` — N entry aggiornate/create
-   - `${paths.references_dir}/project-status.md` — contesto aggiornato
-
-   ### ADR creati
-   - `${paths.adrs_dir}/ADR-YYYYMMDD-<slug>.md` — [titolo] (o "Nessun ADR creato")
-   ```
-
-2. **Knowledge Base Sync** (OPTIONAL — only if the project has an external knowledge corpus, e.g. an Obsidian vault, Confluence space, or Notion workspace):
-
-   If the project ships a `knowledge-sync` corpus agent (declared in `.baldart/overlays/new.md`), invoke it after doc updates so the external corpus stays aligned. If no such agent exists, skip this step with a one-line notice (do NOT dispatch a non-existent agent).
-
-3. **Proceed to Phase 6** (post-batch merge & cleanup).
-4. Present a **single summary report** to the user per card (and a batch summary at the end):
-   - **Files changed** (short list per card)
-   - **Test results** (new tests + existing tests count, pass rate at each iteration)
-   - **Build/lint status** (pass + retry count if any)
-   - **Fix cycles** (total number of self-healing retries across phases)
-   - **Final review** (findings: N raised / M verified / K false positives | fixes applied: N | highest severity)
-   - **UX testing** (PASS/FAIL/SKIP | test file path if written)
-   - **QA result** (profile: skip/light/balanced/deep | verdict: PASS/FAIL/SKIP | confidence % | failing gates: which of lint/tsc/test/build/markdownlint, or "none" | findings file path). E2E is reported separately (Phase 2.6 e2e-review), not by qa-sentinel.
-   - **Issues needing user attention** (anything unresolved, partially wired, or flagged)
-   - **Commit hashes** (from tracker)
-   - **Merge commit hash** (from Phase 6)
-   - **Card status reconciliation** (Phase 6b: N cards verified DONE, K force-updated)
-   - **Worktree cleanup status** (success/failed)
-   - **Knowledge-corpus sync status** (from Step F.6 item 2 "Knowledge Base Sync" — COMPLETED/FAILED/PARTIAL, or SKIPPED if no corpus-sync agent is configured)
-   - Overall implementation status
-
-4b. **Next Steps & Launch Command** (MANDATORY section — always present):
-
-   Check for remaining not-yet-DONE cards in the same epic group (match "not DONE",
-   not a hard-coded status value — see the `status enum` SSOT in REGISTRY.md):
-
-   ```bash
-   # Find parent epic's cards that are NOT yet DONE (TODO | READY | IN_PROGRESS | BLOCKED)
-   grep -l "parent: <EPIC-ID>" ${paths.backlog_dir}/*.yml \
-     | xargs grep -L "status: DONE"
-   ```
-
-   Present the section:
-
-   ```
-   ## Prossimi Passi
-
-   ### Lancio implementazione (copia e incolla)
-   ```
-   /new FEAT-XXXX-05 FEAT-XXXX-06 FEAT-XXXX-07
-   ```
-
-   ### Card rimanenti nell'epic
-   | Card | Titolo | Status | Gruppo parallelo |
-   |------|--------|--------|-----------------|
-   | FEAT-XXXX-05 | [title] | TODO | 2 |
-   | FEAT-XXXX-06 | [title] | TODO | 2 |
-
-   ### Card completate in questa sessione
-   | Card | Titolo | Commit |
-   |------|--------|--------|
-   | FEAT-XXXX-01 | [title] | abc1234 |
-   | FEAT-XXXX-02 | [title] | def5678 |
-   ```
-
-   If ALL cards in the epic are DONE:
-   ```
-   ## Prossimi Passi
-
-   Tutte le card dell'epic **FEAT-XXXX** sono state completate.
-   Pronto per il deploy: `/deploy` o `git push origin <trunk branch>` (il `git.trunk_branch` configurato)
-   ```
-
-5. **Proceed to Phase 7** (production readiness checklist).
-
----
-
-## Phase 6 — Post-batch merge & cleanup (delegated to worktree-manager skill)
-
-**→ Visibility (batch transition)**: TaskUpdate `Merge & cleanup` → `in_progress` and emit a Progress Bar per § "Progress Visibility". Mark it → `completed` at the end of Phase 6c (merge done, worktree removed, workspace reconciled).
-
-After the final review passes AND all cards are committed in the worktree, delegate the entire merge and cleanup to the **worktree-manager** skill (`/mw` in programmatic mode):
-
-1. **BEFORE invoking /mw** — verify no uncommitted files remain in the worktree:
-   ```bash
-   cd <worktree-path>
-   git status --porcelain
-   ```
-   If ANY uncommitted files exist (staged, unstaged, or untracked), commit them NOW with `[safety] Auto-commit remaining files before merge`. Do NOT proceed to `/mw` with a dirty worktree — files WILL be lost during rebase.
-2. Invoke `/mw` with:
-   - The worktree path and branch from the tracker
-   - `checksAlreadyPassed: true` (final review + QA already validated the build)
-   - All card IDs for the commit message
-3. The skill handles: safety commit of any remaining uncommitted files (step 3), rebasing onto the latest trunk (`$TRUNK` = `git.trunk_branch`) (step 4b — auto-resolves doc conflicts, stops on code conflicts), merging into the trunk via the configured `git.merge_strategy` (step 4c — `pr` uses `gh pr merge`, `local-push` does a direct FF push to `origin/$TRUNK`; NEITHER runs `git checkout` of the trunk on the main repo, respecting the absolute terminal-isolation rule), post-merge verification, worktree removal, registry cleanup, and remote branch deletion.
-4. **If code merge conflicts** → the skill STOPs and reports. Doc-only conflicts (ssot-registry.md, project-status.md, etc.) are auto-resolved by keeping both sides.
-5. **If post-merge build fails** → the skill STOPs and keeps the worktree intact for investigation.
-6. Record the merge commit hash and result in the tracker. **Also record the merge timestamp** under `## Worktree Merges` (`merge_ts: <ISO-8601>`): for `local-push` use the local merge-commit time (`git log --format=%ci <hash>`); for `pr` (`gh pr merge`) use the PR merge completion time, or note `merge_ts: pending` if GitHub has not yet finalized the merge. Phase 8's `cycle_time_mins` reads THIS field as the strategy-independent end anchor (never a raw hash that may be the PR HEAD).
-
-### Phase 6b — Backlog Card Status Reconciliation (MANDATORY — ZERO TOLERANCE)
-
-**This gate runs IMMEDIATELY after Phase 6 merge completes, BEFORE presenting any summary to the user. It is NON-SKIPPABLE.**
-
-The most common failure mode is leaving cards IN_PROGRESS after merge. This creates SSOT drift and confuses downstream agents (codebase-architect, doc-reviewer). This gate prevents that.
-
-**Steps:**
-
-1. **Read the tracker file** to get the full list of card IDs in the batch.
-2. **For EACH card in the batch**, read its backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`) and check the `status` field:
-   - If `status: DONE` → OK, skip.
-   - If `status` is anything else (`IN_PROGRESS`, `READY`, `TODO`, etc.) → **FORCE UPDATE to DONE immediately**.
-3. **Early exit — all cards already DONE**: if step 2 found ALL cards are already `status: DONE`, skip steps 4-5 entirely. Log in the tracker:
-   ```
-   ## Phase 6b — Status Reconciliation
-   Cards checked: N
-   Already DONE: N (all cards marked DONE by coder agents)
-   Force-updated to DONE: 0
-   Reconciliation commit: not needed
-   ```
-   Proceed directly to step 6.
-4. **Force update procedure** for non-DONE cards:
-   ```bash
-   # In the MAIN repo (not worktree — worktree is already cleaned up)
-   cd <main-repo-path>
-   ```
-   Edit the backlog YAML: set `status: DONE`, add `completed_date: <today>`, add implementation note: `"Marked DONE by post-merge reconciliation gate (Phase 6b)"`.
-5. **If ANY card was force-updated**: commit in the main repo with these precautions:
-   a. **Clear stale COMMIT_LOCK** (common when coder agents crash or timeout):
-      ```bash
-      # Remove any stale COMMIT_LOCK from main repo or worktrees
-      rm -f <main-repo-path>/.git/COMMIT_LOCK 2>/dev/null
-      find <main-repo-path>/.git/worktrees -name COMMIT_LOCK -delete 2>/dev/null || true
-      ```
-   b. **Stage backlog YAMLs AND related docs** (pre-commit hook requires doc updates):
-      ```bash
-      # Stage only the force-updated backlog YAMLs
-      git add ${paths.backlog_dir}/CARD-001.yml ${paths.backlog_dir}/CARD-002.yml
-      # If ssot-registry.md was modified during the batch, stage it too
-      # (doc-freshness hook blocks commits that touch ${paths.backlog_dir}/ without ssot-registry.md)
-      git diff --name-only ${paths.references_dir}/ssot-registry.md && git add ${paths.references_dir}/ssot-registry.md || true
-      ```
-   c. **Commit with explicit file list**:
-      ```bash
-      git commit -m "[BATCH] Mark cards DONE — post-merge reconciliation"
-      ```
-   d. **If commit fails due to pre-commit hook** (lint-staged, doc-freshness): check the error.
-      - If "no staged files" → all changes were already committed. Log as "not needed".
-      - If doc-freshness requires ssot-registry.md → update its `last_verified_from_code` date, stage it, and retry.
-      - If COMMIT_LOCK → re-run step 5a and retry.
-      - Do NOT retry more than 2 times. Log the failure and move on.
-6. **Update tracker** with reconciliation results:
-   ```
-   ## Phase 6b — Status Reconciliation
-   Cards checked: N
-   Already DONE: M
-   Force-updated to DONE: K [list card IDs]
-   Reconciliation commit: <hash> (or "not needed")
-   ```
-7. **HALT condition**: if a card cannot be updated (e.g., file read error, YAML parse error), log it in `## Issues & Flags` and continue with the remaining cards. Report the failure in the final summary.
-
-**Why this exists**: Agents frequently skip the DONE marking in Phase 4 (step 27) due to context compaction, commit failures that interrupt the flow, or team mode where Step D.6 gets lost. This gate is the safety net that catches ALL of these cases.
-
-### Phase 6c — Workspace Hygiene Post-merge (BLOCKING — non-skippable)
-
-**Why this exists**: FEAT-0006 incident closed the batch leaving the main repo with an unpushed orphan commit (`c9d41f9`) and local `develop` diverged from `origin/develop` for a manual fix. This phase closes the loop opened by Phase 0: it verifies the main repo is clean and synchronized, parses the `[SYNC-DEFERRED]` marker emitted by `/mw` when HEAD ≠ `$TRUNK`, and restores any stash saved in Phase 0.
-
-**Auto Mode does NOT override this phase.** Every `AskUserQuestion` below is non-bypassable.
-
-**Steps:**
-
-1. **Fetch remote state**:
-   ```bash
-   git -C "$MAIN" fetch origin --quiet
-   ```
-
-2. **Parse `mw-docs` sync markers** — scan the captured stdout from every `/mw` invocation in this batch (kept in the tracker under `## Worktree Merges`):
-   - **`[SYNC-DEFERRED] main repo HEAD=<branch>`** (main repo HEAD ≠ `$TRUNK`) — surface via `AskUserQuestion`:
-     - Question: `"Una o più merge worktree hanno deferito la sincronizzazione di local $TRUNK (main repo HEAD non era $TRUNK). Come riconcilio adesso?"`
-     - Options: `[Ora HEAD è $TRUNK → ff-pull adesso]` / `[Lascia deferred (riconcilio io manualmente)]` / `[Mostra dettagli e fammi decidere]`.
-   - **`[SYNC-NEEDS-DECISION] …`** (HEAD was `$TRUNK` but the ff was blocked by a **foreign** uncommitted file, or by a divergence/rebase conflict `/mw` would not auto-commit) — this is NEVER a passive note. Surface via `AskUserQuestion`:
-     - Question: `"Il $TRUNK locale non si è sincronizzato: <dettaglio dal marker>. Come chiudo?"`
-     - Options: `[Committa tu adesso (descrivi cosa)]` / `[Lo gestisco io — chiudi senza sync locale]` / `[Mostrami il diff e decidiamo]`.
-   - **No marker** — `/mw` fast-forwarded (or auto-reconciled the framework telemetry log); nothing to parse.
-
-3. **Clean-tree assertion (BLOCKING)**:
-   ```bash
-   git -C "$MAIN" status --porcelain
-   ```
-   If non-empty AND no Phase 0 stash is pending → invoke `AskUserQuestion`:
-   - Question: `"Main repo ha modifiche non committate dopo il batch (non c'era stash di Phase 0). Cosa faccio?"`
-   - Options: `[Mostrami il diff e fammi decidere]` / `[Stash adesso con label baldart-post-batch-<timestamp>]` / `[Lascia così (lo gestisco io)]` / `[Halt]`.
-
-4. **Divergence assertion (BLOCKING — this catches the FEAT-0006 orphan-commit pattern)**. `$MAIN` and `$TRUNK` are read from the tracker (`## Worktree` section); HALT if either is absent/empty.
-   ```bash
-   read BEHIND AHEAD <<< "$(git -C "$MAIN" rev-list --left-right --count "origin/$TRUNK...$TRUNK")"
-   ```
-   Compute `$GENUINE_AHEAD` / `$GENUINE_LIST` / `$FW_SKIPPED` with the **exact same reclassification loop as Phase 0 step 4** (framework-management commits — subtree merges into `.framework/`, `baldart update`/`add` chores, `.framework/`-only commits — are auto-ignored, NOT orphan commits). Then branch on `$BEHIND` and `$GENUINE_AHEAD`:
-   - **`BEHIND=0` and `GENUINE_AHEAD=0`** — synchronized. If `$FW_SKIPPED > 0`, log `Divergence: $FW_SKIPPED framework-management commits ahead (auto-ignored)` and proceed. No `AskUserQuestion`.
-   - **Ahead only (`GENUINE_AHEAD > 0`, genuine unpushed commits)** — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK ha $GENUINE_AHEAD commit genuini non pushati su origin/$TRUNK al termine del batch (esclusi $FW_SKIPPED di gestione framework). Lista: <git show -s --oneline $GENUINE_LIST>. Cosa faccio?"`
-     - Options: `[Push adesso (git push origin $TRUNK)]` / `[Cherry-pick selettivo su origin/$TRUNK]` / `[Reset --hard origin/$TRUNK (richiede conferma esplicita, DISTRUTTIVO)]` / `[Halt con stato preservato]`.
-     - On `Reset --hard origin/$TRUNK` re-ask `AskUserQuestion` to confirm: `"Confermi reset --hard? I commit <list> verranno persi se non pushati altrove."` Solo dopo conferma esplicita esegui il reset.
-   - **Behind only (`BEHIND > 0`, `GENUINE_AHEAD=0`)** — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è behind origin/$TRUNK di $BEHIND commit (qualcuno ha pushato durante il batch). Faccio ff-pull adesso?"`
-     - Options: `[Fast-forward pull]` / `[Lascia behind (lo gestisco io)]`.
-   - **Diverged both ways (`BEHIND > 0` and `GENUINE_AHEAD > 0`)** — invoke `AskUserQuestion`:
-     - Question: `"Local $TRUNK è diverged ($BEHIND behind, $GENUINE_AHEAD genuine ahead). Servono entrambe le riconciliazioni. Come procedo?"`
-     - Options: `[Rebase local $TRUNK su origin/$TRUNK]` / `[Mostrami i commit locali e decidiamo]` / `[Halt]`.
-
-5. **Restore Phase 0 stash (if any)** — read the tracker for `## Workspace Snapshot: <message-label>`:
-   - If the snapshot is `dirty-tree override` → skip restore, log "user retained dirty-tree responsibility".
-   - If it is a stash MESSAGE label (e.g. `baldart-new-phase0-<FIRST-CARD-ID>-<timestamp>`) — resolve the stash by its message, NEVER by positional `stash@{N}` (other stashes may have shifted the index since Phase 0). This runs on `$MAIN` (the main checkout, not a worktree), so a stash op here is safe:
-     ```bash
-     REF="$(git -C "$MAIN" stash list | grep -F "<message-label>" | head -1 | cut -d: -f1)"
-     [ -n "$REF" ] && git -C "$MAIN" stash pop "$REF" \
-       || echo "stash '<message-label>' not found — was it already restored?"
-     ```
-     On conflict, do NOT silent-drop — invoke `AskUserQuestion`:
-     - Question: `"Restore dello stash di Phase 0 ha generato conflitti. Lo stash è ancora presente (NON eliminato). Come procedo?"`
-     - Options: `[Lascia lo stash + apri istruzioni per merge manuale]` / `[Mostrami il conflitto inline]` / `[Halt]`.
-
-6. **Log and exit**:
-   ```
-   ## Phase 6c — Workspace Hygiene Post-merge
-   Status: PASS
-   Clean-tree: <yes | resolved: stashed | user-retained>
-   Divergence (local…origin/$TRUNK): <0\t0 | resolved: pushed/cherry-picked/ff-pulled/rebased>
-   Sync-deferred markers: <none | reconciled | user-retained>
-   Phase 0 snapshot restore: <n/a | popped clean | conflict-deferred-to-user>
-   Completed: <timestamp>
-   ```
-   If any step ended in HALT, set `Status: HALT` and report — Phase 7 must NOT start with an unclean main repo unless the user explicitly chose `[Lascia così]`.
-
-7. **Anti-bypass guard** — like Phase 0, before exiting Phase 6c re-read the tracker section you just wrote. Missing `## Phase 6c` → refuse to proceed to Phase 7. There is no `--skip-phase-6c` flag; treat any urge to skip as a self-correction trigger.
-
-### Fail-safe rules (enforced by worktree-manager skill)
-- **Never `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo** from inside this orchestrator. The main repo is shared across parallel terminals. Use the configured `git.merge_strategy` for trunk merges and `git -C <main> pull --ff-only` (only when `HEAD = $TRUNK` already) for sync. See `/mw` step 4c.
-- Never merge into a release/production branch — only into the integration trunk (`$TRUNK` = `git.trunk_branch`), via the configured `git.merge_strategy` (NOT local checkout).
-- Never force push to the trunk. `--force-with-lease` on feature branches after rebase is allowed.
-- Never delete a branch before successful merge verification.
-- Never remove a worktree before confirming the trunk is stable post-merge.
-- Stop execution immediately if any command fails.
-
----
-
-## Phase 7 — Production Readiness Checklist
-
-After Phase 6 completes (or after the final summary report if Phase 6 is deferred), present a **Production Readiness Checklist** — a clear list of all manual or infrastructure actions required to launch the implemented changes in production.
-
-### How to detect items
-
-Scan ALL files changed across the batch (use the tracker's completed cards + `git diff` against the base branch) and check for the items below.
-
-**The "Action to report" column shows the command for the deployment target
-matching `stack.deployment` in `baldart.config.yml`.** When `stack.deployment`
-is empty, infer from `stack.database` + presence of config files
-(`vercel.json`, `firebase.json`, `wrangler.toml`, `fly.toml`) and fall back to
-asking the user.
-
-| Category | Detection signal | Action to report (per `stack.deployment`) |
-|----------|-----------------|-------------------------------------------|
-| **Database indexes** | New/modified index config file (`firestore.indexes.json`, SQL migration with `CREATE INDEX`, `prisma migrate` artifact, `db.createIndex` call, CDK/Terraform GSI) | firebase: `firebase deploy --only firestore:indexes`; vercel+postgres: run migrations during deploy; aws+dynamodb: apply CDK/Terraform; generic: run the project's migration command |
-| **Persistence-layer access rules** | New/modified `firestore.rules`, Supabase RLS migration, Mongo validator, DynamoDB IAM policy | firebase: `firebase deploy --only firestore:rules`; supabase: `supabase db push`; aws+dynamodb: apply IAM via CDK/Terraform |
-| **Storage access rules** | New/modified `storage.rules` or equivalent bucket policy | firebase: `firebase deploy --only storage:rules`; aws: apply S3 bucket policy; gcp: apply GCS IAM |
-| **Environment variables** | New `process.env.*` references not in the base branch, new entries in `.env.example` or `.env.local` | 1. Add to the deployment platform (Vercel/Firebase/Cloudflare/AWS Param Store) — list each var + target environments 2. Update `${paths.references_dir}/env-vars.md` Change Log |
-| **Feature-flag / remote config** | New flag keys in code, new `remoteConfig` calls, growthbook/launchdarkly keys | Add keys in the project's flag system (Firebase Remote Config / Growthbook / LaunchDarkly / Unleash) |
-| **Auth provider configuration** | New auth provider initialization or scope change | Configure in the auth provider console matching `stack.auth_provider` (Firebase Console / Supabase dashboard / Clerk dashboard / Auth0 / Cognito) |
-| **Scheduled functions / cron** | New or modified cron/scheduled jobs | firebase: `firebase deploy --only functions`; vercel: deploy includes cron from `vercel.json`; aws: deploy EventBridge rule + Lambda |
-| **Database migrations** | New {entities}, field renames, data backfills referenced in code or ADRs | Run the project's migration command — varies by stack (firebase admin script / `supabase db push` / `prisma migrate deploy` / Mongo migration tool / SQL migrator) |
-| **New API endpoints** | New route files (`src/app/api/` Next.js, `app/routes/api.*` Remix, `src/routes/api/+server.ts` SvelteKit, etc.) | Verify CORS/auth config; update API docs if public |
-| **Third-party services** | New API keys, webhook URLs, or external service integrations | Configure in provider dashboard + add secrets to the deployment platform |
-| **DNS / domain changes** | Hosting or redirect config changes | Update DNS records on registrar; update domain settings on the deployment platform |
-| **Package upgrades with breaking changes** | Major version bumps in `package.json` / `pyproject.toml` / `Gemfile` | Verify compatibility; check migration guides |
-
-### Output format
-
-Present the checklist as a clearly formatted section in the final report.
-The example below assumes `stack.deployment: firebase` + `stack.database: firestore`;
-adapt commands and tags to the project's resolved stack.
-
-```
-## Production Readiness Checklist
-
-### Required before deploy
-1. **[DB Indexes — firestore]** Deploy composite indexes
-   - Command: `firebase deploy --only firestore:indexes`
-   - Reason: New compound query on `<entity>` (`<field1>` + `<field2>` + `<field3>`)
-
-2. **[Environment Variable]** Add `<VAR_NAME>` to the deployment platform
-   - Go to: <Vercel/Firebase/Cloudflare/AWS> > Project Settings > Environment Variables
-   - Required for: Production, Preview
-   - Value: (obtain from <provider> dashboard)
-
-3. **[DB Access Rules — firestore]** Deploy updated security rules
-   - Command: `firebase deploy --only firestore:rules`
-   - Reason: New {entity} `<name>` access rules added
-
-# Equivalent commands for other stacks:
-#   stack.database: supabase   → `supabase db push` (RLS migration)
-#   stack.database: postgres   → `prisma migrate deploy` (or project migration tool)
-#   stack.database: mongodb    → run the index/validator bootstrap script
-#   stack.database: dynamodb   → `cdk deploy` / `terraform apply` for the table+GSI
-
-### No action needed
-- No new scheduled functions
-- No database migrations
-- No DNS changes
-
-### Notes
-- DB index propagation can take time (firestore 5-10 min, postgres CONCURRENTLY minutes-to-hours on large tables, dynamodb GSI minutes); deploy BEFORE releasing the code
-- Environment variables must be set on the deployment platform BEFORE the deploy triggers
-```
-
-### Auto-execution of agent-doable tasks
-
-Before presenting the checklist, **auto-execute** all items that can be performed by the agent
-without manual intervention. Do NOT ask the user for approval — just run them.
-
-**Auto-executable items** (run via Bash tool, no confirmation needed). Pick the
-command matching `stack.deployment` + `stack.database`. If the inferred command
-is wrong for the project, ask the user — never auto-execute a guess.
-
-| Category | Command per `stack.deployment` | Auto-execute? |
-|----------|-------------------------------|--------------|
-| Database indexes | firebase → `firebase deploy --only firestore:indexes --project <id>`; supabase → `supabase db push`; vercel+postgres → `prisma migrate deploy` (or project-specific) | YES (when stack-matched) |
-| Persistence access rules | firebase → `firebase deploy --only firestore:rules --project <id>`; supabase → `supabase db push` (RLS migration); aws → CDK / Terraform apply | YES (when stack-matched) |
-| Storage access rules | firebase → `firebase deploy --only storage:rules --project <id>`; aws → S3 bucket policy apply via IaC | YES (when stack-matched) |
-| Scheduled functions | firebase → `firebase deploy --only functions --project <id>`; vercel → deploy step already includes cron from `vercel.json`; aws → CDK / Terraform apply | YES (when stack-matched) |
-
-**Manual-only items** (report to user, do NOT auto-execute):
-
-| Category | Why manual |
-|----------|-----------|
-| Environment variables | Requires deployment-platform dashboard access or secret values |
-| Feature-flag / remote config | Requires flag-system console (Firebase Remote Config / GrowthBook / LaunchDarkly / Unleash) |
-| Auth provider configuration | Requires console UI of the provider matching `stack.auth_provider` |
-| Database migrations / backfills | Risk of data loss — needs human judgment |
-| Third-party service config | Requires external dashboards and secrets |
-| DNS / domain changes | Risk of downtime — needs human judgment |
-
-**Auto-execution procedure:**
-
-1. For each auto-executable item detected, run the command immediately.
-2. Log the result (success/failure) in the tracker under `## Production Readiness`.
-3. In the final checklist output, mark auto-executed items with their result:
-   ```
-   1. **[DB Indexes — <stack.database>]** Deploy indexes
-      - Command: <stack-matched command from the Auto-executable table>
-      - Result: DEPLOYED (took 45s) | FAILED (error: ...)
-   ```
-4. If an auto-execution FAILS: log the error, mark it as `MANUAL FALLBACK NEEDED`,
-   and include it in the "Required before deploy" section for the user to handle.
-
-### DB Index Verification (MUST — after deploy)
-
-After the deploy command succeeds, verify the indexes are actually live before
-reporting success. The deploy command typically returns before index propagation
-completes (Firestore: 5–10 minutes; Postgres `CREATE INDEX CONCURRENTLY` on a
-large table: minutes to hours; DynamoDB GSI: minutes; Mongo background index:
-minutes to hours).
-
-**Skip this section entirely when:**
-- the card has no `db_indexes` / `firestore_indexes` block, OR
-- `stack.database` is unset / `none`, OR
-- the card's index artifact is a SQL migration on a small table (the migration
-  itself is synchronous and self-verifying — the deploy step already failed if
-  the index didn't build).
-
-**Verification procedure — pick the variant matching `stack.database`:**
-
-#### Variant — Firestore (`stack.database: firestore`)
-
-After `firebase deploy --only firestore:indexes` succeeds:
-
-1. **Extract expected collection groups** from the local `firestore.indexes.json`:
-   ```bash
-   cat firestore.indexes.json | python3 -c "
-   import sys, json
-   data = json.load(sys.stdin)
-   groups = sorted(set(i['collectionGroup'] for i in data.get('indexes', [])))
-   print('\n'.join(groups))
-   "
-   ```
-
-2. **Check index states** via Firestore REST API for each collection group:
-   ```bash
-   TOKEN=$(gcloud auth print-access-token) && \
-   for CG in <collection_groups>; do
-     curl -s "https://firestore.googleapis.com/v1/projects/<your-firebase-project>/databases/(default)/collectionGroups/$CG/indexes" \
-       -H "Authorization: Bearer $TOKEN" 2>/dev/null
-   done | python3 -c "
-   import sys, json, re
-   raw = sys.stdin.read()
-   creating = []
-   for match in re.finditer(r'\{[^{}]*\"indexes\"[^}]*\}', raw, re.DOTALL):
-       try:
-           data = json.loads(match.group())
-           for idx in data.get('indexes', []):
-               state = idx.get('state', 'UNKNOWN')
-               if state != 'READY':
-                   fields = ' + '.join(f.get('fieldPath','?') for f in idx.get('fields',[]))
-                   cg = idx.get('name','').split('/collectionGroups/')[1].split('/')[0] if '/collectionGroups/' in idx.get('name','') else '?'
-                   creating.append(f'{state}: {cg} ({fields})')
-       except: pass
-   if creating:
-       print(f'NOT_READY ({len(creating)} indexes still building):')
-       for c in creating: print(f'  - {c}')
-   else:
-       print('ALL_READY')
-   "
-   ```
-
-3. **Poll if NOT_READY** — re-check every 30 seconds, up to 10 retries (5 minutes max).
-
-4. **Final status**:
-   - All `READY` → `VERIFIED READY`.
-   - Still `CREATING` after 10 retries → `DEPLOYED BUT BUILDING` (warning).
-   - Any `NEEDS_REPAIR` / `ERROR` → `INDEX ERROR — manual intervention required`.
-
-#### Variant — Postgres / Supabase (`stack.database` ∈ {postgres, supabase})
-
-After the migration / `supabase db push` succeeds:
-
-```bash
-# For each index named in the migration:
-psql "$DATABASE_URL" -c "SELECT indexname, indexdef FROM pg_indexes WHERE indexname = '<index_name>';"
-# If the migration used CREATE INDEX CONCURRENTLY on a large table, also check:
-psql "$DATABASE_URL" -c "SELECT pid, phase, blocks_total, blocks_done FROM pg_stat_progress_create_index;"
-```
-
-If `pg_stat_progress_create_index` returns rows → index still building, poll every
-30s. If `pg_indexes` returns 0 rows for an expected name → CRITICAL (migration
-silently skipped or rolled back).
-
-#### Variant — MongoDB (`stack.database: mongodb`)
-
-After the bootstrap script / migration runs:
-
-```bash
-mongosh "$MONGO_URL" --eval "db.<entity>.getIndexes()"
-```
-
-Confirm every expected `name`/`key` is present. For background-built indexes, watch
-`db.currentOp({'$or':[{op:'command','command.createIndexes':{$exists:true}}]})` until empty.
-
-#### Variant — DynamoDB (`stack.database: dynamodb`)
-
-After `cdk deploy` / `terraform apply`:
-
-```bash
-aws dynamodb describe-table --table-name <table> \
-  --query 'Table.GlobalSecondaryIndexes[].{Name:IndexName,Status:IndexStatus}'
-```
-
-All GSIs must show `ACTIVE`. `CREATING` → poll; `DELETING` / `UPDATING` → manual review.
-
-**Checklist output format with verification:**
-```
-1. **[DB Indexes — <stack.database>]** Deploy indexes
-   - Command: <stack-matched command>
-   - Deploy: SUCCESS (took 45s)
-   - Verification: ALL READY (5/5) | BUILDING (2 still creating after 5min) | ERROR (details)
-```
-
-### Rules
-
-- **Always present this section**, even if the checklist is empty (in that case, state "No infrastructure changes required — deploy is code-only").
-- Order items by **deployment sequence** (items that must happen first go first — e.g., indexes before code deploy, env vars before code deploy).
-- For each item, include the **reason** (which card/feature requires it) and the **exact command or UI path**.
-- If an item is **uncertain** (e.g., you suspect a new index might be needed but aren't sure), mark it with `VERIFY` and explain what to check.
-- **Update the tracker** with the full checklist under a new `## Production Readiness` section.
-
----
-
-## Context recovery protocol
-
-If at ANY point you are unsure where you are in the batch:
-1. Read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`)
-2. Check `## Current Card` — if populated, resume that card at the listed phase.
-3. Check `## Card Queue` — find the next unchecked card.
-4. Check `## Completed Cards` — know what's already done (don't redo).
-5. Continue the pipeline from where you left off.
-
----
-
-## Parallelism rules
-
-### Sequential mode (default for small batches)
-
-- Cards execute one at a time through the full per-card pipeline (Phases 1-5).
-- Code review and doc review for the same card run as **parallel read-only audits**, then fixes are applied by domain owner: **doc findings → `doc-reviewer` (write mode)**, code/security/migration findings → `coder`. (Sequential Phase 3 is even simpler — doc-reviewer runs alone, so it audits AND applies in one invocation.)
-- This mode is unchanged from the original behavior.
-
-### Team mode (for complex batches)
-
-- Cards within the same `execution_strategy.groups` level (same `level`) run in parallel via isolated coder agents.
-- Groups execute sequentially (group 0 → group 1 → group 2...).
-- Review + QA run ONCE per group (combined), not per card.
-- The orchestrator holds ONLY coordination state, never implementation details.
-- File ownership map is enforced per-agent via MAY EDIT / FORBIDDEN lists.
-- See "Team Mode" section below for full workflow.
-
-### Common rules (both modes)
-
-- The file-ownership map is the authoritative source for which files each agent may edit.
-- When running parallel agents, expect "file modified since read" errors on shared files (like the backlog yml) — handle gracefully.
-- When running in parallel, each parallel branch updates the tracker with its own card — use card ID as prefix to avoid conflicts.
-
----
-
-## Team Mode (parallel coder agents with isolated contexts)
-
-When the complexity assessment (step 3c) selects team mode, the orchestrator changes role: instead of executing each card's pipeline sequentially, it coordinates parallel coder agents — each with its OWN isolated context window.
-
-**Key principle**: the orchestrator stays LEAN. It holds only:
-- The tracker file path
-- Parallel group status (pending/active/done)
-- Completion verdicts per card (pass/fail + files changed)
-
-It does NOT accumulate implementation details, codebase-architect findings, or review outputs — those live and die in each agent's isolated context.
-
-### Team Mode Pre-flight
-
-After the standard pre-flight (steps 1-7), add:
-
-1. Read the `execution_strategy.groups` (each with `level` + `cards`) and sort into execution layers by `level`. For legacy cards lacking the block, fall back to the on-the-fly topological-layer computation from step 3c.
-2. Update tracker with team mode section:
-   ```
-   ## Team Mode
-   Status: active
-
-   ## Parallel Groups
-   | Group | Cards | Status |
-   |-------|-------|--------|
-   | 0 | FEAT-01 | pending |
-   | 1 | FEAT-02, FEAT-03 | pending |
-   | 2 | FEAT-04, FEAT-05 | pending |
-   ```
-
-### Per-Group Execution
-
-Process groups in order (0, 1, 2, ...). Within each group, spawn coder agents IN PARALLEL — one per card.
-
-#### Step A: Pre-compute shared context (ONCE per group)
-
-Before spawning coders, the orchestrator runs **codebase-architect** ONCE for the entire group (not per card). This single call covers all cards in the group.
-
-Prompt:
-```
-Explore the codebase for context relevant to these cards:
-[list card IDs + their scope.summary, one line each]
-
-Focus on: [combined files_likely_touched from all cards in group]
-Return: file paths, type signatures, existing patterns. Max 30 lines.
-```
-
-This is the ONLY context the orchestrator accumulates per group. After passing it to the coders, it can be purged.
-
-**Persist for review reuse (since v3.35.0)** — also write these findings to
-`/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`. D.4b's per-card `/codexreview` lean contract points
-its `arch_baseline_path` at this file, so the review reuses the group baseline instead of re-spawning
-`codebase-architect`.
-
-#### Step B: Spawn parallel coder agents
-
-**→ Visibility (wave change)**: this is a new wave starting. TaskUpdate ALL of this group's card spine tasks → `in_progress`, and emit a Progress Bar with the new `Wave <X>/<Y>` header per § "Progress Visibility".
-
-For each card in the current group, spawn a coder agent using the Agent tool. ALL agents for the group MUST be spawned in a **SINGLE message** (multiple Agent tool calls) to run truly in parallel.
-
-Each coder agent receives a **SELF-CONTAINED** mission briefing that includes EVERYTHING it needs — it will NOT call codebase-architect or plan-auditor itself:
-
-```
-Agent tool call:
-  subagent_type: "coder"
-  mode: "bypassPermissions"
-  run_in_background: true
-  name: "coder-<CARD-ID>"
-  prompt: |
-    ## AUTONOMOUS CARD IMPLEMENTATION — <CARD-ID>
-
-    You are implementing this card AUTONOMOUSLY. Complete ALL phases below
-    without external coordination. You have your own isolated context.
-
-    ### 1. Card Specification (verbatim)
-    Requirements:
-    [copy from card YAML]
-
-    Acceptance Criteria:
-    [copy from card YAML]
-
-    ### 2. Codebase Context (pre-computed)
-    [paste codebase-architect findings from Step A]
-
-    ### 3. Working Directory
-    All work MUST happen in the worktree: <worktree-path>
-    cd to this directory before any file operations.
-
-    ### 4. File Permissions (ENFORCED)
-    MAY EDIT:
-    [files from ownership map for THIS card only]
-
-    FORBIDDEN:
-    - ALL files not in the MAY EDIT list
-    - Do NOT create files outside the designated paths
-
-    ### 5. Design Reference (if UI card)
-    [path to design.html if exists]
-
-    ### 6. Your Pipeline
-    Execute these steps in order:
-    a) Print the numbered requirements checklist (anti-skip measure)
-    b) Implement ALL requirements
-    c) Run: npx tsc --noEmit && npx eslint --max-warnings=0 <your-files>
-    d) Self-heal up to 3 times if checks fail
-    e) Verify completeness: for each requirement, confirm code exists (read it)
-    f) If any requirement is missing after implementation, implement it now
-    g) Output the completion report (MANDATORY format below)
-
-    ### 7. Completion Report (MANDATORY)
-    ```completion-report
-    card: <CARD-ID>
-    status: done | partial | blocked   # card-level — matches coder.md four-state (coder never self-emits deferred-approved; the orchestrator sets that after the AC-Closure Gate)
-    requirements:
-      - id: 1
-        text: "[text]"
-        status: done | not_implemented   # per-requirement is BINARY (legacy row-level partial/blocked were silent-deferral channels — removed)
-        evidence: "file:line"
-    files_changed:
-      - path/to/file.ts
-    build_status: pass | fail
-    lint_status: pass | fail
-    tsc_status: pass | fail | n/a        # n/a when stack.language excludes typescript
-    retry_count: N
-    ```
-```
-
-#### Step C: Wait for group completion
-
-The orchestrator waits for ALL background agents in the group to complete. It will be notified automatically as each finishes (`run_in_background`).
-
-> **Do NOT poll with `sleep N; echo "waiting..."` loops.** Background agents (and background `Bash` commands) re-invoke the orchestrator automatically when they finish — issuing `sleep`/`echo` "waiting" turns burns orchestrator turns and tokens for zero progress. Simply end your turn after spawning the background work; you will be woken on completion. This applies to EVERY barrier in Step D (D.1 build, D.2 reviewers, D.3/D.3b agents, D.4 qa-sentinel, D.4a doc-reviewer, D.4b `/codexreview`), not just Step C.
-
-For each completed agent:
-1. Read the completion report from the agent's output.
-2. Log to tracker: card ID, status, files changed, build/lint status.
-3. Do NOT read or store implementation details — only the verdict.
-
-**If an agent fails** (status: failed after 3 retries — the central repair cap):
-- Log failure in tracker `## Issues & Flags`.
-- Other agents in the group continue unaffected.
-- After group completes, ask user: retry failed card or skip?
-- **Retry re-entry (defined path):** on "retry", re-run the failed card from **Step B** (re-spawn the autonomous coder with a fresh briefing) — NOT from Step A, because the Step A arch context for the group is already in hand and is reused. The retried card then rejoins the group's Step D pipeline and MUST pass the SAME mandatory per-card sub-steps as its peers (D.3a AC-Closure → D.3b Simplify → D.3c E2E → D.4 QA → D.4a doc → D.4b codex → D.5 commit → D.6 backlog); there is no shortcut. The Step D coverage assertion will block Step E until the retried card has all mandatory tracker entries — so a retried card cannot silently skip a gate. **Cap: one Step-B re-entry per card** (consistent with the central cap discipline); on a second failure, re-ask with only skip/abandon so the loop cannot recur unbounded.
-
-#### Step D: Post-group review + QA (ALL sub-steps MANDATORY)
-
-> **The sub-steps below are ALL MANDATORY.** The previous lean Step D (build → combined review → qa → codex → commit) was an incident-causing shortcut (FEAT-0006: 10 sub-cards committed with 0 invocations of Phase 2.5b / 2.55 / 2.6 / 3 / 3.5 / 3.7) and is now FORBIDDEN. Every card in the group MUST complete every per-card sub-step (D.3a, D.3b, D.3c, D.4a) before the group reaches D.5 commit. Skipping any sub-step "to save time", "to save tokens", "because the diff is small", or for any model-invented reason is a protocol violation. Auto Mode does NOT override this.
-
-After ALL agents in the group complete successfully:
-
-1. **D.1 — Build verification (group)** — Run `npm run build` in the worktree to verify combined changes compile (redirect to `/tmp/build-group.txt` per § "Context economy"; surface only exit code + bounded extract on failure). If build fails, identify which card's changes broke it (from `git diff --name-only` per card), spawn a targeted fix-coder for those files only.
-
-1.5. **D.1.5 — Effective per-card review profile (compute ONCE; drives D.2 + D.4b)** — For EACH card in the group, compute its **effective codex profile** with the SAME deterministic rule the sequential Phase 3.7 Step C uses, so the two paths never disagree:
-   - **Floor**: read the card's `review_profile` field (`skip`/`light`/`balanced`/`deep`) per the QA Profile Selector (fallback-computed only for legacy cards lacking the field).
-   - **Escalation-only (Step A detector)**: run the Phase 3.7 **Step A** high-risk detector (bash + grep) on THIS card's committed diff (`git diff "$TRUNK...HEAD" -- <card files from ownership map>`). A matched trigger promotes `light`→`full`; it can NEVER downgrade `full`→`light`. The card's `review_profile` is the floor; the detector is the safety net on top.
-   - **Partition** the group into two lists and log them in the tracker under `## Team Mode`:
-     - `LIGHT_CARDS` = cards whose effective profile is `light` or `skip` **AND** zero Step-A triggers.
-     - `FULL_CARDS` = all others (effective profile `balanced`/`deep`, OR any Step-A trigger).
-   - **Sub-classify `TRIVIAL_CARDS` ⊆ `LIGHT_CARDS`** = cards that are `IS_TRIVIAL` on the committed diff (§ "Trivial-card fast-lane": `review_profile == skip` AND 0 Step-A triggers AND **non-source diff**). These are the LIGHT cards that have nothing for `code-reviewer` to review. (A `skip` card whose diff DID touch a source file is in `LIGHT_CARDS` but NOT `TRIVIAL_CARDS` — the guard keeps it on the code-review path.)
-   - **Sub-classify `DOC_DEFER_CARDS`** (since v4.7.0, for #2 doc deferral) = cards with `review_profile == light` whose committed diff touches **NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). Their per-card doc-review is deferred to the Final F.3 doc-reviewer. (Trivial cards, and any card whose diff touches a doc file, are NOT in this set — doc-review stays relevant for them.)
-   - Log: `## D.1.5 Effective Profiles\n<CARD-ID>: profile=<floor> triggers=<n> diff=<source|non-source> → effective=<light|full> (<LIGHT_CARDS|FULL_CARDS>)<, TRIVIAL / DOC_DEFER if applicable>` per card. This single computation is the SSOT for D.2 (code-reviewer + doc-reviewer scoping), D.3b/D.3c (already skipped for trivial), and D.4b (inclusion) — do NOT recompute it downstream.
-
-2. **D.2 — Combined static review (group)** — Two reviewers, **scoped by the D.1.5 partition** so each card gets exactly ONE per-card/group code review proportional to its risk (the other is the Final FULL gate):
-   - **doc-reviewer — over the group MINUS `DOC_DEFER_CARDS`** (since v4.7.0). It runs **read-only here** (it cannot write while code-reviewer reads in parallel — parallel-safety), MUST **attribute every doc finding to a specific card** (by file → ownership map), and applies the full Phase 3 mandate INCLUDING the spec/docs-drift→bug lens (since v3.35.0). The `DOC_DEFER_CARDS` (light, no-doc diff per D.1.5) are excluded — their doc-review is deferred to the Final F.3 doc-reviewer (batch-wide). **If the group is entirely `DOC_DEFER_CARDS` → skip the D.2 doc-reviewer** and log `D.2 doc-reviewer: DEFERRED to Final FULL gate (all cards light + no-doc diff)`. D.4a consumes the per-card findings (for the non-deferred cards) and dispatches the doc-reviewer (now alone, in write mode) to apply them — no second AUDIT spawn, but the FIXES are still owned by doc-reviewer.
-   - **code-reviewer — scoped to the diff-union of `LIGHT_CARDS` MINUS `TRIVIAL_CARDS`** (run it in parallel with the doc-reviewer over those files). These light non-trivial cards skip D.4b, so D.2 is their single per-card code review (the cross-batch Codex pass at Final covers them adversarially). **`TRIVIAL_CARDS` are excluded from the code-reviewer scope** — their diff is non-source, so there is nothing to code-review (doc-reviewer still covers them via the whole-group pass above; the Final FULL gate covers them adversarially). **If `LIGHT_CARDS \ TRIVIAL_CARDS` is empty → do NOT spawn code-reviewer at D.2** (every remaining card is either `FULL_CARDS` — deeper review at D.4b — or `TRIVIAL_CARDS` — nothing to review). Log the deterministic gate reason: `D.2 code-reviewer: scope=[<ids>] | excluded-trivial=[<ids>] | SKIPPED (no code-bearing light cards)`.
-   - **Tradeoff (documented, accepted — see top-of-file `REVIEW DEPTH SCALES` clause)**: for `FULL_CARDS`, cross-card detection moves from the per-group D.2 pass to the per-batch **Final-review FULL gate** (Codex over the entire batch diff, plus code-reviewer fallback) — same merge-gate safety, feedback arrives at batch-end rather than per-group. This is the intended de-duplication: `FULL_CARDS` are NOT re-reviewed by a group-level code-reviewer on top of their D.4b `/codexreview`.
-
-3. **D.3 — Apply fixes (group)** — If D.2 findings exist, spawn ONE fix-coder to apply all fixes in a single pass. Run build + lint after.
-
-3a. **D.3a — Phase 2.5b AC-Closure Gate (per-card, BLOCKING — non-skippable)** — For EACH card in the group, **sequentially**, invoke the full Phase 2.5b gate as documented in `### Phase 2.5b — AC-Closure Gate (BLOCKING — Scope Closure Discipline)`. This includes: build the AC Closure Ledger from the card YAML, run the rationalization scan, invoke `AskUserQuestion` one-per-deferred-AC, run the `implementation_notes` deferral audit, and persist the ledger in the tracker. Until EVERY card in the group exits PASS, do NOT proceed to D.3b. Cards exiting with `not_implemented` ACs that the user routes to "Implementa adesso" must finish their fix-coder loop and re-pass the gate before D.3b starts for the next card. Log under `## AC Closure Ledger — <CARD-ID>` per card.
-
-3b. **D.3b — Phase 2.55 Simplify (per-card, FANNED OUT across the group)** — The Simplify agents are **read-only analysis on file-disjoint per-card diffs** (the orchestrator applies the fixes afterward), so there is NO reason to run them one card at a time. **Spawn the per-card Simplify analysis for ALL eligible cards in PARALLEL** — in a SINGLE message, fire each card's Phase 2.55 trio (Reuse / Quality / Efficiency) against that card's diff captured to `/tmp/diff-<CARD-ID>.txt` (per Phase 2.55 step 2 — pass each trio the **path**, scoped to the card's File Ownership Map; never inline the diff). Per-card (not group-aggregate) so findings stay attributable. When all analyses return, **apply fixes per card** (file-disjoint → no write conflict), then re-run `npm run lint` and `npx tsc --noEmit` on the worktree ONCE for the whole group (redirect to disk per § "Context economy"). (Concurrency is capped by the platform; passing N cards is safe — excess agents queue.)
-   - **Gate (enumerated, `review_profile`-driven)**: SKIP D.3b for a card whose `review_profile == skip` (trivial / non-implementable card — Simplify is quality-only, so there is no merge-gate coverage to lose, and there is no substantive diff to simplify). Log `simplify: SKIPPED (review_profile=skip)`. For `light`/`balanced`/`deep` cards D.3b runs unchanged. This is the ONLY enumerated skip — never skip D.3b "for time" on a `light`+ card. (Skipped cards are simply omitted from the parallel fan-out.)
-
-3c. **D.3c — Phase 2.6 E2E-Review (per-card)** — First, evaluate the existing Gate table for EVERY card at once (skip when `features.has_e2e_review: false`, backend-only diff per the diff predicate documented in Phase 2.6, or card type in the Phase 2.6 skip set — `backend`/`api`/`db`/`infra`/`docs`/`chore`/`config`). In practice most cards in a group skip this gate (backend/db/api), so the eligible set is usually 0–1. For the cards that PASS the gate, invoke `/e2e-review` in programmatic mode with that card's payload. Each `/e2e-review` keeps its own isolated state dir (`.baldart/e2e-review/<CARD-ID>/`), so multiple runs do not clobber each other's artifacts.
-   - **Parallel-when-safe**: if **two or more** cards pass the gate, you MAY fan them out in parallel ONLY when they hit **disjoint routes/pages** — the genuinely shared resource is the worktree's single dev-server port, and concurrent Playwright sessions against one server are fine for disjoint routes. If the eligible cards touch overlapping routes (or `/e2e-review` spins its own server and a port clash is possible), run those **sequentially** to avoid a flaky cross-test. Default to parallel for the common disjoint case; fall back to sequential on any contention.
-   - BLOCKING per-card: if `/e2e-review` returns `"blocked"` or `"error"`, surface to the user via the same `AskUserQuestion` documented in Phase 2.6 — do NOT proceed to D.4 with an unresolved card. Skips are logged with the documented gate reason, never with `"time budget"` or similar.
-
-4. **D.4 — QA gate (group; since v4.7.0 — runs only for `deep` / risk-escalation, else deferred to Final)** — Read each card's `review_profile` field and the D.1.5 Step-A trigger result. **Run the group qa-sentinel (once, at FULL) iff** the group's MAX profile is `deep` **OR** any card in the group had a Step-A risk escalation. **Otherwise (max profile ≤ `balanced`, no escalation) → DEFER the group QA to the Final Review F.3 qa-sentinel** (FULL suite + build + audit over the entire batch — the unconditional merge gate); log `D.4 QA: DEFERRED to Final FULL gate (group max=balanced, no risk escalation)`. This mirrors sequential step 21b. When it DOES run, invoke qa-sentinel at FULL (the combined group diff must be validated together) using the same prompt contract as Phase 3.5 step 22. ⚠️ A balanced-only group runs its first suite at the Final gate; merge safety is preserved because Final is FULL over the whole batch.
-
-4a. **D.4a — Per-card doc gate (consumes D.2, since v3.35.0; doc-reviewer-applied since v3.40.0)** — Do NOT re-run the doc AUDIT (D.2 already produced per-card-attributed findings). If any card in the group has doc findings, invoke the **doc-reviewer once in write mode** over the group, passing the per-card-attributed findings from D.2, to APPLY all doc fixes in a single pass (it is now alone — code-reviewer is done — so the D.2 parallel-safety constraint no longer applies). Do **NOT** spawn a fix-coder for doc findings: `doc` is owned by `doc-reviewer` (see "Domain-Override Domains"); a code-oriented coder lacks the doc-invariant contract. The only exception is a doc-drift→bug finding rooted in CODE — that follows the D.4b code fix path. (Previously D.4a spawned a fix-coder per card; the audit was already collapsed to a single attributed D.2 pass. D.4b's per-card `/codexreview` also skips its doc-reviewer via the lean contract, so the doc AUDIT runs once per group while the doc FIXES run once per group via doc-reviewer.) **Telemetry** — append one row per applied doc finding to `## Fix Application Log`: `D.4a | doc | est_lines=<n> | decision=doc-reviewer | applied_by=doc-reviewer | card=<ID> | finding=<1-line>`. **Phase-8 producer (named counter)** — ALSO record per card the `doc_gaps: found=<N> fixed=<M>` line in that card's `## Completed Cards` entry (same named counter as sequential Phase 3 step 15), so Phase 8 reads `doc_gaps_found`/`doc_gaps_fixed` from a structured field, not a free-form row.
-
-4b. **D.4b — Pre-Merge Codex Review Gate (per-card, profile-gated via D.1.5)** — Invoke `/codexreview` for **EACH card in `FULL_CARDS`** (the partition computed at D.1.5), one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path.
-   - **`LIGHT_CARDS` → SKIP D.4b** (enumerated `review_profile`-driven gate reason, NOT a time skip). A `light`/`skip` 0-trigger card already received its single per-card code review at the **D.2 group pass**, and its Codex-adversarial review is **guaranteed by the unconditional Final-review FULL gate** (Codex over the entire batch diff, post-batch). Running `/codexreview` here at `light` would only re-run `code-reviewer` + FP-gate (Codex is dropped at `light` since v3.38.0) — a pure duplicate of D.2. Log per card: `codex-review: SKIPPED (light, 0 triggers — D.2 group code-review covered + Codex adversarial guaranteed by Final FULL gate)`.
-   - **`FULL_CARDS` → run `/codexreview` as today** (the per-card Codex adversarial + CoVe + FP-gate pass is exactly where the per-card code review for these cards lives — D.2 deliberately did NOT re-review them). The profile passed is always `full` (D.1.5 already resolved it; do NOT recompute). Keep the sequential one-at-a-time loop (avoid N concurrent `/codexreview`, each of which fans out multiple sub-agents → rate-limit risk).
-   Apply the same fix sub-loop as sequential Phase 3.7 Step C.4: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and — **re-writing the consumed-once lean contract first** — re-invoke `/codexreview` via the Skill tool with `args: <CARD-ID>` (max 2 retries per card; a bare prose mention or a missing card-ID would let the retry review the wrong card). If still BLOCKER/HIGH after retries, ask the user before proceeding to D.5. The D.5 commits MUST NOT happen until every card in the group has a PASS verdict (or explicit user override via `AskUserQuestion`). Log results in the tracker under `## Pre-Merge Codex Review` per card. **Lean + profile (since v3.35.0)**: before each card's `/codexreview`, apply the same Review Profile Selector and write the same `/tmp/codexreview-lean-<CARD-ID>.json` contract as sequential Phase 3.7 Step C — `arch_baseline_path` pointing at `/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`, `skip_doc_reviewer: true`, `skip_api_perf_auditor: true` (since v4.7.0 — api-perf deferred to the Final F.3 batch-wide auditor), and `profile: full` (every card that reaches D.4b is in `FULL_CARDS` per D.1.5 — `light`/`skip` 0-trigger cards were already partitioned out and skip D.4b entirely; do NOT recompute the profile here). `full` runs the standard pipeline (Codex adversarial + CoVe + FP-gate, minus the duplicate doc-reviewer). The merge-gate safety for the skipped `LIGHT_CARDS` is the post-batch **Final-review FULL gate** (a single FULL `/codexreview` over the entire batch diff, which team mode reaches via "Post-batch — same as sequential mode"). To make D.4b run for every card again (pre-v4.5.0 behavior), drop the D.1.5 partition and iterate over all group cards here at their per-card profile; the final full gate stays regardless.
-
-5. **D.5 — Commit** — One commit per card using explicit staging from the ownership map. **NO stash in worktrees** (stashes are globally shared via `refs/stash` — see Phase 4 WORKTREE COMMIT RULE):
-   ```bash
-   cd <worktree-path>
-   # For each card in the group:
-   git add <card's-files-only>
-   # Disambiguate "nothing to commit" from a hook rejection BEFORE committing:
-   if [ -z "$(git status --porcelain)" ]; then
-     echo "D.5 <CARD-ID>: nothing staged — already committed upstream; record HEAD and skip"
-   else
-     git commit -m "[CARD-ID] Brief description"
-   fi
-   ```
-   If `git commit` itself fails with a non-empty staging area (a pre-commit / lint-staged hook rejected it), apply the SAME bounded handler as sequential Phase 4 step 27: clear a stale `COMMIT_LOCK`, re-stage explicitly, retry at most **2 times**, then log `[COMMIT-BLOCKED]` and escalate via `AskUserQuestion` — never loop unbounded and never silently leave a card uncommitted.
-
-6. **D.6 — Update backlog (MANDATORY — do NOT skip)** — For EACH card in the group:
-   a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`, add implementation notes (NEVER include `[USER-APPROVED DEFERRAL]` lines that didn't actually pass through D.3a's gate).
-   b. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry.
-   c. Stage the updated YAML and include it in the card's commit (or as an immediate follow-up commit).
-   d. Log in tracker: `card_status: DONE (verified)` for each card.
-   e. **→ Visibility**: TaskUpdate each card's spine task → `completed` (strip any live phase suffix) as it reaches DONE here.
-   Note: Phase 6b (Status Reconciliation) will catch any card missed here, but aim for zero misses.
-
-#### Step D coverage assertion (MANDATORY end-of-group check)
-
-Before moving to Step E, the orchestrator MUST verify the tracker contains, for EACH card in the group, ALL of the following entries (or an explicit gate-skip log with the documented reason):
-
-- `## AC Closure Ledger — <CARD-ID>` with `ac-closure: implemented=N | user-approved deferrals=M | follow-up cards created=K` (NEVER skipped — applies to trivial cards too)
-- `simplify: <N fixes | clean — 0 fixes | SKIPPED (review_profile=skip)>` (per-card from D.3b)
-- `e2e-review: <status>` (with documented gate-skip reason if SKIP)
-- `doc-review: <status | DEFERRED to Final FULL gate (DOC_DEFER_CARDS: light + no-doc diff)>` (from D.4a — runs for trivial cards too; the DEFERRED form is valid ONLY for `DOC_DEFER_CARDS` per D.1.5)
-- `qa: <profile=... | verdict=... | mechanical-only (trivial) | DEFERRED to Final FULL gate (group max=balanced, no risk escalation)>` (group-level from D.4; the DEFERRED form is valid when the group max profile ≤ balanced with no Step-A escalation)
-- `api-perf: <covered at D.4b | DEFERRED to Final FULL gate (skip_api_perf_auditor)>` (per-card — `skip_api_perf_auditor` defers it to F.3 batch-wide; DEFERRED is the normal v4.7.0 value)
-- `code-review: <covered at D.2 | covered at D.4b | SKIPPED (trivial — non-source diff)>` (per-card — the trivial SKIP is valid ONLY for `TRIVIAL_CARDS` per the D.1.5 partition)
-- `codex-review: <verdict | SKIPPED (light, 0 triggers — D.2 group code-review covered + Final FULL gate) | SKIPPED (trivial — non-source diff; covered by Final FULL gate)>` (per-card from D.4b — the SKIPPED forms are valid ONLY for `LIGHT_CARDS` / `TRIVIAL_CARDS` respectively)
-
-A missing entry means a sub-step was skipped. An entry whose value is a **`review_profile`-driven SKIP/DEFER**, an **`IS_TRIVIAL` SKIP**, or a **`/prd`-provenance SKIP** with a documented enumerated reason above (D.3b `skip` profile; D.4b `LIGHT_CARDS`; code/codex `TRIVIAL_CARDS`; doc-review `DOC_DEFER_CARDS`; QA `group max=balanced, no escalation`; api-perf `skip_api_perf_auditor`; plan-auditor `holistic_audit provenance`) is a VALID, present entry — not a violation; all defer to the unconditional Final FULL gate. What remains forbidden: a missing entry, or a skip whose reason is `time budget` / `to save tokens` / any model-invented constraint. If any entry is genuinely missing, do NOT proceed to Step E — return to the missing sub-step and execute it. Documenting "skipped per time budget" or similar is a protocol violation per the top-of-file rigidity clause.
-
-#### Step E: Context purge + next group
-
-After committing all cards in the group:
-1. Update tracker: move group to done, log all results per card.
-2. **PURGE**: forget all implementation details, review findings, architect context.
-3. **→ Visibility**: emit a Progress Bar reflecting the wave boundary (this wave done; next `Wave <X+1>/<Y>` pending) per § "Progress Visibility".
-4. Move to the next pending group (Step A again).
-
-### Sequential fallback within team mode
-
-If two cards in the same parallel group are discovered at runtime to have a file conflict (e.g., one coder created an unexpected file that overlaps):
-1. Detect via file-diff gate after Step C.
-2. Revert the later card's conflicting files.
-3. Re-run that card as a standalone sequential step after the group.
-
-### Dependency gates between groups
-
-Before starting group N, verify ALL cards in groups 0..N-1 are status: done. If any card in a previous group failed and was skipped:
-- If cards in group N `depends_on` it: skip those dependent cards too, log in `## Issues & Flags`.
-- If no dependency: proceed normally.
-
-### Post-batch (same as sequential mode)
-
-After all groups are complete, run the same Final Review, Phase 6 (merge), and Phase 7 (production readiness) as documented above. Since v3.37.0 the Final Review runs a **single FULL `/codexreview` over the entire batch diff** (per the Final-review FULL gate) — no scope reduction — so every team-mode card, including any reviewed at `light` in D.4b, receives a guaranteed full review before merge.
-
----
-
-## Phase 8 — Metrics Log (MONITORING SIGNAL — non-blocking — runs after Phase 7)
-
-After the Production Readiness Checklist is complete, log this batch run to the skill
-effectiveness registry. This enables tracking of first-attempt success rate, actionability,
-and QA quality over time. This is a telemetry write, NOT a gate — it never blocks the batch (see
-the fail-safe note at the end of the phase). It was previously labelled "MANDATORY", but since it
-has no blocking consequence the honest label is "monitoring signal".
-
-**Steps:**
-
-1. Read the batch tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`) to extract — every field below has a NAMED upstream producer; read the structured key, do NOT re-parse prose:
-   - Start timestamp (from `Started:` field)
-   - Worktree-creation timestamp (from `## Worktree` — the time Phase 0/Pre-flight created the worktree; the strategy-independent cycle-time anchor, see step 2)
-   - Card list and total count
-   - For each completed card:
-     - `fix_cycles` (from the per-phase retry counts logged in `## Completed Cards`)
-     - `qa_profile`, `qa_verdict` (Phase 3.5 step 25 / D.4 QA line)
-     - `qa_first_attempt` (Phase 3.5 step 25 named flag — `pass`/`fail`/`n/a`)
-     - `doc_gaps: found=<N> fixed=<M>` (Phase 3 step 15 / D.4a named counter)
-   - Batch-level `review_findings: total / verified / blockers` (Final Review F.5 step 13 named counters — the canonical source for `findings_total` / `findings_verified` / `blockers_count`)
-   - Merge commit hash (and, when `git.merge_strategy: pr`, the PR merge timestamp recorded by Phase 6 — see step 2)
-
-   If any named field is absent (e.g. a legacy tracker), record `0`/`n/a` for that field and append `metrics_gaps: <field>` to the JSONL row's notes — do NOT invent a value by re-parsing free-form prose.
-
-2. Compute aggregate metrics:
-   - `first_attempt_success_rate`: cards with fix_cycles == 0 / total_cards
-   - `mean_fix_cycles`: mean of per-card fix cycle counts
-   - `qa_profiles`: count of {skip, light, balanced, deep}
-   - `qa_pass_first_attempt_rate`: cards with `qa_first_attempt == pass` / cards where qa ran (exclude `n/a` SKIP/LIGHT cards from the denominator) — read the named flag from step 1, do NOT re-infer from `## Fix Application Log` rows
-   - `findings_total` / `findings_verified`: from the batch-level `review_findings` named counter (Final Review), NOT a per-card re-sum (which would conflate QA gate counts with codex review findings)
-   - `actionability_rate`: findings_verified / findings_total (conservative proxy — a lower-bound on reviewer precision, since some VERIFIED findings end as NEEDS_MANUAL_CONFIRMATION and never produce a fix; 0 if no findings)
-   - `severity_p0_pct`: blockers_count / findings_total (0 if no findings)
-   - `cycle_time_mins`: minutes from the **strategy-independent anchor** to batch completion. Use the **worktree-creation timestamp** (Phase 0/Pre-flight) as the start, NOT `Started:` (which precedes workspace hygiene) and NOT a merge-commit hash (which varies by `git.merge_strategy` — under `pr` the merge commit is created asynchronously by GitHub CI and may not exist locally at Phase 8 time). End anchor: read the `merge_ts` field Phase 6 step 6 recorded under `## Worktree Merges` (it is already strategy-resolved there — local merge-commit time for `local-push`, PR merge completion time for `pr`). If `merge_ts: pending` (a `pr` merge GitHub has not yet finalized), fall back to "now" (`date -u`). Never recompute from a raw merge-commit hash that may be the PR HEAD rather than the actual merge commit.
-
-   > `$METRICS` = `paths.metrics` from `baldart.config.yml` (default `docs/metrics`). All paths below resolve under `$METRICS` — never a hardcoded `docs/metrics`.
-
-3. **Assemble the full JSONL record in memory** (single atomic append — JSONL is append-only, so the row must be COMPLETE before it touches the file). If `STATS=true` (step 6), the `"cost"` key is part of THIS record — do NOT write a baseline row now and rewrite it later (a mid-file rewrite corrupts the JSONL; there is no `sed -i`/`jq` rewrite step in this skill). When `STATS=true`, defer the single append to step 6 after the cost object is computed; when `STATS=false`, append now. The record shape:
-
-   ```json
-   {"ts":"<ISO-8601-UTC>","skill":"new","run_id":"batch-<FIRST-CARD-ID>","cards":["FEAT-XXX"],"total_cards":N,"first_attempt_success_rate":0.0,"mean_fix_cycles":0.0,"qa_profiles":{"skip":0,"light":0,"balanced":0,"deep":0},"qa_pass_first_attempt_rate":0.0,"findings_total":0,"findings_verified":0,"actionability_rate":0.0,"severity_p0_pct":0.0,"doc_gaps_found":0,"doc_gaps_fixed":0,"cycle_time_mins":0,"worktree_branch":"","merge_commit":""}
-   ```
-
-   Use `date -u +%Y-%m-%dT%H:%M:%SZ` for the timestamp. Append the assembled line ONCE with `echo '<full-record>' >> "$METRICS/skill-runs.jsonl"` via Bash — never append a partial row then mutate it.
-
-4. Copy the batch tracker to archive:
-
-   ```bash
-   cp /tmp/batch-tracker-<FIRST-CARD-ID>.md "$METRICS/archive/"
-   ```
-
-5. Note in tracker: `## Metrics Log: WRITTEN (run_id: batch-<FIRST-CARD-ID>)`
-
-6. **Session token telemetry (ONLY when `STATS=true`)** — if the run was invoked with `-stats` / `--stats`:
-
-   Measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
-
-   ```bash
-   node .framework/framework/scripts/analyze-session-tokens.js \
-     --skill new --run-id "batch-<FIRST-CARD-ID>" --out-dir "$METRICS"
-   ```
-
-   The script reads `$CLAUDE_CODE_SESSION_ID` from the environment and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — those are test-only overrides). It writes a human-readable breakdown to `$METRICS/sessions/batch-<FIRST-CARD-ID>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line.
-
-   Parse the `TELEMETRY_JSON=` line and add a `"cost"` key (holding that JSON object: `by_role` + `totals` + `run_wall_ms`) to the in-memory record from step 3, then **append the complete record ONCE** to `$METRICS/skill-runs.jsonl` (this is the deferred single atomic append from step 3 — there is NO already-written row to rewrite, so JSONL semantics stay intact: exactly one line per `run_id`). If the script printed `stats: SKIPPED (...)` instead, set `"cost":{"skipped":"<reason>"}` and append the single record. Echo the script's summary to the user so they see the per-role breakdown.
-
-**If `$METRICS/skill-runs.jsonl` does not exist**: create it first with `mkdir -p "$METRICS" && touch "$METRICS/skill-runs.jsonl"`.
-**If batch tracker is missing or unreadable**: log "Metrics Log: SKIPPED (tracker not found)" and proceed without blocking.
-**This phase is NON-BLOCKING** — if it fails for any reason, do not abort the run. The `-stats` step in particular is best-effort: the script is fail-safe (always exits 0), so never let it block the commit.