baldart 4.99.0 → 5.0.1

package/framework/.claude/commands/codexreview.md

@@ -48,11 +48,19 @@ For the (single) card in scope, check for `/tmp/codexreview-lean-<CARD-ID>.json`
     "profile": "light" | "full",
     "arch_baseline_path": "/tmp/arch-baseline-<CARD-ID>.md",
     "diff_summary_path": "<completion-report or git-diff path>",
+    "review_bundle_path": "/tmp/review-bundle-<CARD-ID>.json",
     "skip_doc_reviewer": true,
-    "skip_api_perf_auditor": true
+    "skip_api_perf_auditor": true,
+    "specialist_dispatch": {
+      "suppress": ["doc-reviewer", "plan-auditor", "api-perf-cost-auditor", "security-reviewer"],
+      "owner": "/new phases 3 / 3.5 / 3.7 + Final F.3"
+    }
   }
   ```
 
+  (`review_bundle_path` and `specialist_dispatch` since v5.0.1 — producer: `codex-gate.md` § lean
+  contract. Both OPTIONAL: absent on pre-5.0 contracts; unknown keys are ignored.)
+
   Apply:
   - `arch_baseline_path` readable → **skip Step 1** (do NOT re-spawn `codebase-architect`); load the
     baseline from that file and ALSO attach the `diff_summary_path` contents to every review agent so
@@ -77,6 +85,17 @@ For the (single) card in scope, check for `/tmp/codexreview-lean-<CARD-ID>.json`
     its own findings as before. Any high-risk diff trigger escalates the card to `full` (both finders)
     per the Review Profile Selector; the Final-review FULL gate re-runs Codex batch-wide regardless. *(B1)*
   - `profile: "full"` (or missing) → full agent set incl. Codex adversarial, minus #3 if `skip_doc_reviewer`.
+  - `review_bundle_path` present AND readable (since v5.0.1) → append to EVERY Step-2 reviewer prompt
+    the binding anti-re-read phrase: *"Review bundle: `<review_bundle_path>` — Read it FIRST. It lists
+    the diff, the changed files, the arch baseline and the completion report. Do NOT re-Read source
+    files to rebuild context you can get from those paths; for any file in `hot_files`, Read ONLY the
+    symbol ranges listed."* Absent/unreadable → no phrase (reviewers derive scope as before). *(A4)*
+  - `specialist_dispatch` present (since v5.0.1) → append its verbatim JSON to EVERY Step-2 reviewer
+    prompt, prefixed: *"ORCHESTRATED run — do NOT spawn any of the suppressed specialists yourself
+    (owner: `<owner>`); record what you would have routed as findings tagged
+    `dispatch_deferred: <agent>`."* (SSOT semantics: `agents/review-protocol.md § SECTION:
+    specialist-spawn`; the block WINS over the legacy `skip_*` flags where both are present.)
+    Absent → the reviewers' own spawn matrices apply (standalone behavior, unchanged). *(A5)*
 
 **Invariant**: lean mode NEVER suppresses the run itself — at minimum a **finder + the Step 3 FP-gate**
 execute on every card. At `light` the finder is **Codex** (or `code-reviewer` on the Codex-unavailable
@@ -85,8 +104,9 @@ malformed/unreadable, fall back to **full mode** and note it. **Consume-once**:
 `/tmp/codexreview-lean-<CARD-ID>.json` immediately after parsing it, so a later standalone
 `/codexreview <CARD-ID>` on the same card never inherits a stale lean contract from a prior `/new` run.
 Record the resolved mode in the Step 4 report `Method` section, e.g.
-`lean: profile=light, architect=reused, doc-reviewer=skipped(Phase 3), codex=finder(light), code-reviewer=fp-gate, cove=skipped`
-(or `codex=unavailable→code-reviewer finder(light)` when the fallback fired).
+`lean: profile=light, architect=reused, doc-reviewer=skipped(Phase 3), codex=finder(light), code-reviewer=fp-gate, cove=skipped, bundle=forwarded, dispatch=suppressed`
+(or `codex=unavailable→code-reviewer finder(light)` when the fallback fired; `bundle=absent` /
+`dispatch=none` on pre-5.0 contracts).
 
 ---
 
@@ -175,7 +195,9 @@ Launch these agents in parallel for each card:
 > the finder instead (the Step 3 FP-gate validates its findings). At `full` with `skip_api_perf_auditor`,
 > launch #1 + #4 (Codex) (+ #3 unless `skip_doc_reviewer`). At `full` with no skips (and in full mode
 > with no contract file), launch all four. The standalone `/codexreview <CARD-ID>` invocation (no
-> contract) is always full with the complete set.
+> contract) is always full with the complete set. When the contract carried `review_bundle_path` /
+> `specialist_dispatch` (Step -0.5 A4/A5), every prompt built here carries the anti-re-read phrase
+> and the suppression block respectively.
 
 **Codex invocation rules (agent #4):**
 

package/framework/.claude/hooks/agent-discovery-gate.js

@@ -25,7 +25,7 @@
  *
  * Source of truth for the list of BALDART agents: the filesystem
  * directory next to this file (`.framework/framework/.claude/agents/`).
- * Every `<name>.md` (except `REGISTRY.md`) is a BALDART agent. No
+ * Every `<name>.md` (except `REGISTRY.md` and `CHANGELOG.md`) is a BALDART agent. No
  * separate manifest is shipped — the directory IS the manifest.
  *
  * Fail-safe contract: this hook MUST NOT block legitimate work. If
@@ -68,7 +68,7 @@ function loadBaldartAgents() {
   try {
     if (!fs.existsSync(agentsDir)) return null;
     const names = fs.readdirSync(agentsDir)
-      .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md')
+      .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md' && f !== 'CHANGELOG.md')
       .map((f) => f.replace(/\.md$/, ''));
     return new Set(names);
   } catch (_) {

package/framework/.claude/hooks/agent-discovery-info.sh

@@ -99,6 +99,7 @@ while IFS= read -r f; do
   [ -z "$f" ] && continue
   name="$(basename "$f" .md)"
   [ "$name" = "REGISTRY" ] && continue
+  [ "$name" = "CHANGELOG" ] && continue
   target="$CONSUMER_AGENTS_DIR/${name}.${CONSUMER_AGENT_EXT}"
   # `test -e` returns false for broken symlinks too — exactly what we want.
   if [ ! -e "$target" ]; then

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

@@ -2,6 +2,45 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.0.1 — 2026-07-03
+
+Adversarial-verification fixes on the v5.0.0 pipeline wave (framework v5.0.1):
+
+- **implement.md 11b→11c (HIGH)**: the clean branch of the file-diff gate now proceeds to 11c
+  (review bundle + doc-invariants) — previously it jumped straight to Phase 2.5, leaving the
+  bundle/PASS-fast machinery inert on the happy path. 11c now ends with an explicit "proceed
+  to Phase 2.5".
+- **implement.md 7d**: explicit branch for `[CAP-HANDOFF]` marker present but checkpoint file
+  missing (rebuild `items_remaining` from the completion report, else `[CAP-EXHAUSTED]`); the
+  continuation briefing cites the review bundle only "when it already exists".
+- **implement.md 6a**: delegated `/ui-implement` cards explicitly still run steps 7c–11c
+  (i18n fill, gates, ownership gate, bundle) — the delegation replaces only the build + 2.6.
+- **review-cycle.md**: Phase 2.55 pre-5.0 diff fallback is now `git diff "$TRUNK...HEAD"`
+  (a bare `git diff` post-commit is vacuous); the 2.5x delegation passes `reviewBundlePath`
+  to `new-card-review.js`; the deferral KEEP list re-includes `balanced`; the PASS-fast
+  Own-Doc Closure claim corrected (modified-primitive obligations ride the serializer gate +
+  Final F.3, R1/R3 fire on new files only); the QA briefing marks bundle `gate_logs` as
+  CONTEXT ONLY (own-tier gates always re-run).
+- **scripts/build-review-bundle.mjs**: the diff/files_changed are now SCOPED to `--may-edit`
+  when passed — in a sequential multi-card batch the unscoped `trunk...HEAD` accumulated
+  prior cards' commits into card N's bundle/docinv.
+- **scripts/doc-invariants.mjs**: `card_declares_docs` evaluates `documentation_impact` and
+  `canonical_docs` independently (a populated `canonical_docs` with `documentation_impact: []`
+  no longer PASS-fasts).
+- Companion consumer fix (command, not this skill): `/codexreview` Step -0.5 now parses +
+  forwards `review_bundle_path` and `specialist_dispatch` from the lean contract.
+
+## 2.0.0 — 2026-07-03
+
+- **BALDART 5.0 pipeline wave (framework v5.0.0).** Six additive mechanisms, all with pre-5.0 graceful degradation:
+  - **Review bundle (implement.md step 11c)**: `scripts/build-review-bundle.mjs` materializes the deterministic per-card handoff (`/tmp/review-bundle-<ID>.json` — diff, files_changed, arch-baseline pointer + parsed Hot-File Map, completion report, ownership, gate logs). Every reviewer briefing carries the binding anti-re-read phrase; the coder also persists its completion report to `/tmp/completion-<ID>.md`. The Phase 2.55 / 3.7 diff dumps become consumers, not producers.
+  - **doc-invariants PASS-fast (Phase 3)**: `scripts/doc-invariants.mjs` classifies the diff against the doc-reviewer invariant table (9 rules, advisory rows excluded); `pass_fast_eligible` + non-`deep` profile → per-card doc-reviewer spawn skipped (measured 84/127 PASS runs), Final F.3 backstop unchanged.
+  - **Cap-and-handoff (step 7 briefing + step 7d)**: soft ~80 / hard 100 tool calls, checkpoint JSON + `[CAP-HANDOFF]` marker, fresh continuation respawn (max 2), then unmet items flow through the normal gap path.
+  - **Explicit i18n fill pass (step 7c)**: the buried step-9 sub-bullet promoted to a numbered step — deterministic new-key detection, `i18n-translator` spawned BY NAME (closes the general-purpose leakage), parity failures never retry the coder.
+  - **Specialist dispatch suppression (codex-gate lean contract)**: new `specialist_dispatch` block (suppress list + owner) — reviewers consume it instead of nested-spawning duplicates; legacy `skip_*` flags kept for back-compat. SSOT: `agents/review-protocol.md § specialist-spawn`.
+  - **Fix-pass model routing A/B (steps 9 / 3.5 / 3.7)**: fix-pass `coder` spawns get `model: sonnet` best-effort (initial builds untouched, specialists untouched); overlay kill-switch `## [OVERRIDE] Fix-pass model`; `model=` recorded in Fix Application Log rows for recurrence telemetry.
+  - Codex parity: scripts portable (.mjs), prose additive, bundle/docinv degrade to the pre-5.0 inline behaviour when the scripts are absent. All six policies guarded by `scripts/check-new-parity.mjs`.
+
 ## 1.5.0 — 2026-07-03
 
 - **Epic-closure gate (framework v4.99.0)**: `commit.md` step 28 gains sub-step **c-bis** — when the card being marked DONE declares a `parent:` epic, a deterministic count of non-DONE siblings decides whether the PARENT epic's ssot-registry entry (and its own YAML, if present) is flipped to DONE in the same commit. Closes the recurring consumer gap where epics stayed `IN_PROGRESS` after their last child closed (3 occurrences across two audit windows, caught only by the nightly). Mirrored in `new2.js`'s mechanical commit prompt (step 4b).

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 1.5.0
+version: 2.0.1
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
   end-to-end inside a dedicated worktree, with code review, doc review, QA, and

package/framework/.claude/skills/new/references/codex-gate.md

@@ -99,25 +99,39 @@ For EVERY other card (no conditional skip — the gate ALWAYS runs; only its DEP
    the Codex-unavailable fallback). To revert per-card Codex off `light`, restore the v3.38.0 `light`
    branch of `/codexreview` Step -0.5 (`code-reviewer` finder only).
 
-   Then dump the card diff (reviewer grounding) and write the lean contract `/codexreview` consumes:
+   Then ensure the card diff is on disk (implement.md step 11c's review bundle already dumped
+   `/tmp/diff-<CARD-ID>.txt` — this gate is a CONSUMER; only on a pre-5.0 install without the
+   bundle script, dump it now) 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 \
+   [ -s /tmp/diff-<CARD-ID>.txt ] || 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 }
+     "diff_summary_path": "/tmp/diff-<CARD-ID>.txt",
+     "review_bundle_path": "/tmp/review-bundle-<CARD-ID>.json",
+     "skip_doc_reviewer": true, "skip_api_perf_auditor": true,
+     "specialist_dispatch": {
+       "suppress": ["doc-reviewer", "plan-auditor", "api-perf-cost-auditor", "security-reviewer"],
+       "owner": "/new phases 3 / 3.5 / 3.7 + Final F.3" } }
    ```
-   `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.)
+   **`specialist_dispatch` (v5.0.0 — the generalized suppression block, SSOT semantics in
+   `agents/review-protocol.md § SECTION: specialist-spawn`)**: in an orchestrated run the
+   ORCHESTRATOR owns specialist routing — `/new` runs doc-review (Phase 3), qa (3.5), security
+   fixes (3.7 writer partition) and the batch-wide api-perf pass (Final F.3) itself, so a reviewer
+   that nested-spawned any of the suppressed agents would duplicate a review, untracked and
+   invisible to the tracker. Reviewers record what they would have routed as findings tagged
+   `dispatch_deferred: <agent>`. The legacy `skip_doc_reviewer`/`skip_api_perf_auditor` flags stay
+   for back-compat (pre-5.0 readers); the block WINS where both are present. `review_bundle_path`
+   points the reviewer at the deterministic scope handoff (Read it FIRST; never re-derive; honor
+   `hot_files` ranges). Standalone `/codexreview` invocations (no lean contract) carry no block —
+   the reviewers' own spawn matrices apply as before.
+   `skip_doc_reviewer` rationale: Phase 3 already ran `doc-reviewer` on this diff (spec/docs-drift→bug
+   lens since v3.35.0). `skip_api_perf_auditor` rationale (since v4.7.0): the per-card api-perf pass is
+   deferred to the Final Review F.3 batch-wide sweep.
 
 1. **Log gate invocation** in the tracker under `## Pre-Merge Codex Review`:
 
@@ -151,7 +165,7 @@ For EVERY other card (no conditional skip — the gate ALWAYS runs; only its DEP
 
 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 the **domain writer** with the report path + list of VERIFIED bugs (canonical writer map v4.26.1 — see SKILL.md § "Domain-Override Domains"): **`security`-domain findings** (touching `paths.high_risk_modules` or RLS-policy SQL — the same `security` match rule) → **`security-reviewer`** in write mode (it owns the security-invariant contract a coder lacks; never route a security fix to `coder`); **all other findings** (`correctness`/code/perf/`other`) → **`coder`**. Run security-reviewer first, then coder (skip either if its partition is empty). **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** (since v4.18.0) the findings come from **Codex** (the sole finder) — the report carries Codex's `minimal_fix_direction`; brief the coder to apply it (treat it like the `full`-profile Codex fix direction). **On the Codex-unavailable fallback** the `light` findings come from `code-reviewer` instead — brief the coder to apply the `code-reviewer` fix direction (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 1+ BLOCKER OR 1+ HIGH → spawn the **domain writer** with the report path + list of VERIFIED bugs (canonical writer map v4.26.1 — see SKILL.md § "Domain-Override Domains"): **`security`-domain findings** (touching `paths.high_risk_modules` or RLS-policy SQL — the same `security` match rule) → **`security-reviewer`** in write mode (it owns the security-invariant contract a coder lacks; never route a security fix to `coder`); **all other findings** (`correctness`/code/perf/`other`) → **`coder`** — **fix-pass model routing (v5.0.0 A/B, best-effort): spawn the fix-pass coder with `model: sonnet`** when the runtime supports it (overlay `## [OVERRIDE] Fix-pass model` wins; the security-reviewer partition is NOT downgraded); append `model=<sonnet|opus>` to the Fix Application Log rows. Run security-reviewer first, then coder (skip either if its partition is empty). **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** (since v4.18.0) the findings come from **Codex** (the sole finder) — the report carries Codex's `minimal_fix_direction`; brief the coder to apply it (treat it like the `full`-profile Codex fix direction). **On the Codex-unavailable fallback** the `light` findings come from `code-reviewer` instead — brief the coder to apply the `code-reviewer` fix direction (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. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=route the residual BLOCKER/HIGH to the writer (security-reviewer/coder) and re-verify; if still unresolved → follow-up card (NEVER force the verdict to PASS / force-commit).**
    - **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=<security-reviewer|coder|skipped> | applied_by=<security-reviewer|coder|-> | severity=<BLOCKER|HIGH|FALSE-POSITIVE> | retry=<n>`. (`security`-domain fixes are applied by `security-reviewer`, all others by `coder`.) Classify domain: `security` for findings touching RLS / auth / permissions / payments; `correctness` for logic / data integrity / race conditions; `other` for everything else.
 

package/framework/.claude/skills/new/references/implement.md

@@ -62,7 +62,10 @@
            in programmatic mode (contract: ui-implement/references/integration.md).
            Consume its COMPACT JSON (status mirrors /e2e-review — review-cycle.md Phase 2.6
            gating table). SKIP step 6b (owner_agent router), the step-7 coarse briefing,
-           AND Phase 2.6 (the skill already ran /e2e-review). Then resume the per-card
+           AND Phase 2.6 (the skill already ran /e2e-review). Steps 7c–11c still run HERE
+           for the delegated card (i18n fill, gates 8–9, file diff gate 11b, review bundle
+           11c) — the delegation replaces ONLY the build steps and Phase 2.6, never the
+           gates or the bundle. Then resume the per-card
            review cluster (Phase 2.55 Simplify → Phase 3 doc → 3.5 QA → 3.7 Codex) per the
            card's review_profile — for a MIXED UI+logic card /new KEEPS that cluster
            (integration.md § "What /new KEEPS"); it is fidelity-only that the skill owns.
@@ -409,6 +412,20 @@
      this — this briefing is an explicit reminder for UI-touching cards.
    - No hardcoded hex/shadow/border values in component styling — canonical tokens only.
 
+   ### Tool-call budget & checkpoint (cap-and-handoff, v5.0.0)
+   Call budget for this card: soft ~80 tool calls, hard 100. The measured failure mode
+   this prevents: runs that ballooned to 200–440 calls on a degrading context (a single
+   such run cost 93M tokens — more than 30 median cards). When you cross the SOFT cap —
+   or notice you are re-reading the same files — do NOT push through:
+   (1) commit the WIP (`[<CARD-ID>] WIP checkpoint` — never a stash),
+   (2) write `/tmp/checkpoint-<CARD-ID>.json` per `coder.md § Tool-Call Budget & Checkpoint`
+       ({ card, wip_commit, items_done, items_remaining[{id,text,next_step}],
+          files_in_progress, gates_last_status, decisions, warnings }),
+   (3) return a `partial` completion report with the checkpoint path and the marker
+       `[CAP-HANDOFF n=<attempt>]` in your final message.
+   At the HARD cap stop even mid-task. A fresh continuation spawn finishes the card on a
+   clean context — cheaper and safer than 100 more calls on a bloated one.
+
    ### 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."]
@@ -437,6 +454,9 @@
    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.
+   **ALSO write the identical block to `/tmp/completion-<CARD-ID>.md` before returning**
+   (v5.0.0 — downstream reviewers read it from disk via the review bundle; the
+   orchestrator persists it from your return as a backstop if the file is missing).
 
    ```completion-report
    card: <CARD-ID>
@@ -479,6 +499,20 @@
    - **Grounding (cheap `grep`, like the Phase-1 plan-auditor grounding):** every cited source symbol/class MUST appear in `mockups/_src/` (`grep -rF "<symbol>" <prd_dir>/<slug>/mockups/_src/`), and every cited registry primitive MUST exist in the registry (`grep` `${paths.design_system}/INDEX.md` / `components/`). A symbol that is not in the source, or a primitive that is not in the registry, means a fabricated declaration → reject + re-spawn (do NOT pass it to the gates). Log `design-source: grounded` or `design-source: rejected (<reason>)` in the tracker.
    - This does NOT re-verify pixels — that stays with `visual-fidelity-verifier` (Phase 2.6). It only proves the source was read and the reuse-mapping targets are real. When the card has no design source, skip this step entirely.
 
+7c. **i18n fill pass (explicit, deterministic — v5.0.0, promoted from the step-9 sub-bullet).** When `features.has_i18n: true` AND this card's diff added new source-locale keys — detect deterministically, never by intuition:
+   ```bash
+   cd <worktree-path>
+   # $SRC_LOCALE = the source-language locale file path (from i18n config / the project's locales root)
+   git diff "$TRUNK...HEAD" -- "$SRC_LOCALE" 2>/dev/null | grep -c '^+.*:' || echo 0
+   ```
+   If > 0 new keys → spawn **`i18n-translator`** BY NAME (never `general-purpose`, never a generic agent — the context-aware fill is its exclusive domain per `agents/i18n-protocol.md`), passing: the registry path (`${paths.i18n_registry}`), the diff path, and the instruction "fill the missing target locales for the new source keys — source stays untouched". This runs AFTER the coder commit and BEFORE the step-8 gates, so locale-parity holds first-try (the fail-then-fix round-trip measured ~2M tokens on FEAT-0042). Log `i18n-fill: RAN (<n> keys)` or `i18n-fill: SKIP (no new source keys)` in the tracker. A locale-parity failure later in step 8/9 despite this pass → route back to `i18n-translator`, NEVER retry the coder on it (the coder is source-only by design).
+
+7d. **Cap-and-handoff continuation loop (v5.0.0).** If the implementer returned `partial` with a `[CAP-HANDOFF]` marker and `/tmp/checkpoint-<CARD-ID>.json` exists:
+   - Respawn a FRESH instance of the SAME owner agent with a minimal continuation briefing: the arch-baseline path (+ the review-bundle path only when it already exists — it is normally built later, at 11c) + the checkpoint path + "continue from `items_remaining`; the checkpoint + baseline are your context — do NOT re-explore, do NOT re-read files already listed as done". Same card, same worktree, same ownership map.
+   - **Max 2 continuations.** Still `partial` after the 2nd → do NOT keep respawning: log `[CAP-EXHAUSTED]` in `## Issues & Flags`, treat the unfinished items as `not_implemented` rows, and route through the normal gap path (AC-Closure Gate / follow-up card — the card is NOT auto-DONE). Log each continuation in the tracker: `cap-handoff: CONTINUED n=<i> (items_remaining=<k>)`.
+   - `[CAP-HANDOFF]` marker present but the checkpoint file MISSING → do NOT respawn blind: rebuild `items_remaining` from the completion report's `not_implemented` rows and persist it to `/tmp/checkpoint-<CARD-ID>.json` yourself, then run the continuation as above (it counts toward the max-2). If the completion report is also missing, treat as `[CAP-EXHAUSTED]` directly (gap path) — never guess what remains.
+   - No `[CAP-HANDOFF]` marker → this step is a no-op.
+
 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:
    When `features.has_toolchain: true`, substitute each command below with `toolchain.commands.{lint,typecheck,test,build}` run verbatim (§ "Toolchain gates"; defaults shown are the fallback when a key is unset).
    ```bash
@@ -514,9 +548,9 @@
    ```
    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 | i18n | ds-gate`), log it in the tracker as `retry-cause: <category>`. An `i18n` failure means a hardcoded user-facing string — the fix is to externalize it via `t()` + register the key (coder STEP 9), never to weaken the gate. A `ds-gate` failure (`DS_CLOSED_SET_VIOLATION`) means this card introduced a NEW canonical component in a CLOSED role family — the fix is to **reuse the family's canonical member** (named in the gate message), never to weaken the gate or add the duplicate; if the requirement genuinely needs a new member, that is a governance decision (escalate as a blocking finding for a `/prd` reconciliation + ADR, do not self-approve). Because the gate is **diff-scoped to this card's changed files**, an `i18n` failure is unambiguously a string **this card** introduced — it is never pre-existing baseline debt in an untouched file (so do NOT spend a retry triaging "is this mine?"; it is). The Final review re-runs the gate over the whole batch diff as the merge backstop.
-   - **i18n locale-PARITY ≠ anti-hardcoded (do NOT retry the coder on it).** The `i18n` category above is the *anti-hardcoded* gate. A separate **locale-parity** failure — the project's OWN parity test/build complaining that a new key exists in the source locale but not in the others — surfaces under `test`/`build`, and is **NOT a `coder` retry**: the `coder` writes the source locale only **by design** (`coder.md` STEP 9.6), so retrying it just loops. Route it to **`i18n-translator`** (fills the missing target locales context-aware from the registry), then re-run the gate. **Proactively — to avoid the fail-then-fix round-trip (a measured ~2M tokens, FEAT-0042): when `features.has_i18n` AND this card's diff added new source-locale keys, spawn the `i18n-translator` fill pass right after the coder commits and BEFORE these gates**, so parity holds first-try. This is the planned per-card i18n cascade step (`agents/i18n-protocol.md`); the coder still never translates.
+   - **i18n locale-PARITY ≠ anti-hardcoded (do NOT retry the coder on it).** The `i18n` category above is the *anti-hardcoded* gate. A separate **locale-parity** failure — the project's OWN parity test/build complaining that a new key exists in the source locale but not in the others — surfaces under `test`/`build`, and is **NOT a `coder` retry**: the `coder` writes the source locale only **by design** (`coder.md` STEP 9.5), so retrying it just loops. Route it to **`i18n-translator`** (by name), then re-run the gate. The proactive fill already ran at **step 7c** — a parity failure here means 7c was skipped or missed keys; fix via 7c's spawn, never via the coder.
    **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.
+   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. **Fix-pass model routing (v5.0.0 A/B, best-effort)**: spawn the fix-pass `coder` with `model: sonnet` when the runtime supports a model param (the initial build stays on the agent's default opus; a fix-pass applies a scoped, well-specified correction). Consumer kill-switch: an overlay section `## [OVERRIDE] Fix-pass model` in `.baldart/overlays/new.md` naming `fix_pass_model: opus` wins. Append `model=<sonnet|opus>` to the finding's `## Fix Application Log` row so the telemetry can compare recurrence per model. 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:
@@ -526,7 +560,7 @@
    ```
    (`$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.
+   - **All within allowed set** → proceed to 11c (the bundle build runs on EVERY card, not only after a violation).
    - **Any file outside allowed set** → log the violation in `## Issues & Flags` (`"unauthorized file: <path>"`), then run the **deterministic file-scoped revert SCRIPT** (a file-scoped revert is mechanical git plumbing, not code authoring — a script cannot fabricate or over-reach, and it runs IDENTICALLY on Claude and Codex with no dependency on a `model` param or a `general-purpose` agent Codex lacks). Resolve + run it (opt-in-with-fallback):
      ```bash
      REVERT_SH="$(ls .framework/framework/.claude/skills/new/scripts/revert-files.sh .claude/skills/new/scripts/revert-files.sh 2>/dev/null | head -1)"
@@ -537,4 +571,14 @@
        for f in <unauthorized-files...>; do git cat-file -e "$TRUNK:$f" 2>/dev/null && git checkout "$TRUNK" -- "$f" || git rm -f --quiet "$f"; done
      fi
      ```
-     Re-run build + lint to confirm clean state after revert. Update tracker with the revert outcome (from the script's JSON: `reverted`/`removed`/`refused`), then proceed to Phase 2.5.
+     Re-run build + lint to confirm clean state after revert. Update tracker with the revert outcome (from the script's JSON: `reverted`/`removed`/`refused`), then proceed to 11c.
+11c. **Build the review bundle (v5.0.0 — the anti-re-read handoff for the whole review chain).** With the diff now FINAL (post 11b), materialize the deterministic per-card bundle every downstream reviewer reads FIRST:
+   ```bash
+   BUNDLE_MJS="$(ls .framework/framework/.claude/skills/new/scripts/build-review-bundle.mjs .claude/skills/new/scripts/build-review-bundle.mjs 2>/dev/null | head -1)"
+   [ -n "$BUNDLE_MJS" ] && node "$BUNDLE_MJS" --card <CARD-ID> --worktree <worktree-path> --trunk "$TRUNK" \
+       --card-yaml <card yaml path> --may-edit "<comma-separated allowed files from ## File Ownership Map>"
+   # Also classify the doc invariants NOW (consumed by Phase 3's PASS-fast gate):
+   DOCINV_MJS="$(ls .framework/framework/.claude/skills/new/scripts/doc-invariants.mjs .claude/skills/new/scripts/doc-invariants.mjs 2>/dev/null | head -1)"
+   [ -n "$DOCINV_MJS" ] && node "$DOCINV_MJS" --diff /tmp/diff-<CARD-ID>.txt --card <card yaml path> --config baldart.config.yml
+   ```
+   The bundle (`/tmp/review-bundle-<CARD-ID>.json`) unifies the diff dump (it writes `/tmp/diff-<CARD-ID>.txt` if missing — Phase 2.55 step 2 and the Phase 3.7 dump become consumers, not producers), the arch-baseline pointer + parsed Hot-File Map, the completion report path (backstop: if the implementer did not write `/tmp/completion-<CARD-ID>.md`, persist its returned `completion-report` block there YOURSELF before running the script), the ownership map, and the gate-log paths. **Every reviewer briefing from here on carries the binding phrase**: *"Review bundle: `/tmp/review-bundle-<CARD-ID>.json` — Read it FIRST. It lists the diff, the changed files, the arch baseline and the completion report. Do NOT re-Read source files to rebuild context you can get from those paths; for any file in `hot_files`, Read ONLY the symbol ranges listed."* Scripts missing (pre-5.0 install) → skip both, log `review-bundle: unavailable (pre-5.0 scripts)` — the reviewers derive scope themselves as before (graceful degradation, Codex-portable either way). Then proceed to Phase 2.5.

package/framework/.claude/skills/new/references/review-cycle.md

@@ -47,12 +47,13 @@ so it surfaces in telemetry.
   - `scopeFiles` ← this card's committed diff (`git diff --name-only "$TRUNK...HEAD"`, fallback `HEAD~1..HEAD`). **Diffs to disk (context economy, v4.43.0):** write the card's full diff to `/tmp/diff-<CARD-ID>.txt` once and derive BOTH the Step-A grep (above) and this `--name-only` list from it — never read the raw diff inline (mirrors the team-mode D.1.5 batching discipline, so the two paths stay symmetric).
   - `editableFiles` ← this card's **File Ownership Map** entries (the coder's write scope; `setup.md` step 3b).
   - `archBaselinePath` ← `/tmp/arch-baseline-<CARD-ID>.md` (persisted at `implement.md` step 5b).
+  - `reviewBundlePath` ← `/tmp/review-bundle-<CARD-ID>.json` when it exists (implement.md step 11c), else omit — the workflow threads it into every agent brief as the anti-re-read phrase (v5.0.1; absent → briefs unchanged, pre-5.0 behavior).
   - `hasSecurityFiles` ← any `scopeFiles` path matches `paths.high_risk_modules`.
   - `runSimplify` ← `true` (a non-trivial card always simplifies).
 
   ```
   Workflow({ name: 'new-card-review', args: {
-    cards: [{ cardId, cardPath, scopeFiles, editableFiles, qaTier, hasSecurityFiles, runSimplify, archBaselinePath }],
+    cards: [{ cardId, cardPath, scopeFiles, editableFiles, qaTier, hasSecurityFiles, runSimplify, archBaselinePath, reviewBundlePath }],
     worktreePath, baseBranch, config, codexScriptPath   // from Phase 0 / tracker
   }})
   ```
@@ -135,8 +136,8 @@ After completeness is verified, clean up the implementation before it reaches re
 **Step-by-step**:
 
 1. **Enter Phase 2.55 (simplify)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `2.55-simplify DONE` at step 6, co-emitted). Proceed directly to step 2.
-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:
+2. Ensure the card diff is on disk — implement.md step 11c's review bundle already wrote `/tmp/diff-<CARD-ID>.txt` (this phase is a CONSUMER, not a producer). Only if the bundle step did not run (pre-5.0 install): `git diff "$TRUNK...HEAD" > /tmp/diff-<CARD-ID>.txt 2>/dev/null || git diff HEAD~1..HEAD > /tmp/diff-<CARD-ID>.txt` in the worktree — the coder already committed, so a bare `git diff` would be vacuous (**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. When `/tmp/review-bundle-<CARD-ID>.json` exists, each briefing ALSO carries the binding anti-re-read phrase (implement.md step 11c): *"Review bundle: `/tmp/review-bundle-<CARD-ID>.json` — Read it FIRST; do NOT re-Read source files to rebuild context you can get from its paths; for `hot_files`, Read ONLY the listed symbol ranges."*
 
    - **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).
@@ -304,7 +305,9 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 > **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`.
+> **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: `deep` cards, `balanced` cards (they may still PASS-fast via the deterministic gate below — that gate, not this deferral, is their only skip lane), 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 reasons are `light + non-doc diff` and the deterministic PASS-fast below.
+>
+> **Deterministic PASS-fast (v5.0.0 — measured: 84/127 per-card doc reviews returned PASS)**: when implement.md step 11c produced `/tmp/docinv-<CARD-ID>.json` AND it says `pass_fast_eligible: true` (zero non-advisory invariant rows triggered + no doc file in the diff + the card declares no `documentation_impact`/`canonical_docs`) AND the card is NOT `deep` → log `doc-review: PASS-fast (doc-invariants: 0 blocking rows) — Final doc-reviewer backstop stands` and **skip the per-card spawn** (proceed to Phase 3.5). No gate is removed: the batch-Final F.3 doc-reviewer still sees this card's diff. Own-Doc Closure: NEW-file obligations are definitionally empty (no invariant row fired, no docs declared); obligations on MODIFIED primitives/routes are covered by the automatic spec resync (`DS_COMPONENT_STALE` serializer gate, v4.70.0) plus the Final F.3 backstop — the invariant table's R1/R3 fire on new files only, by design. `deep` cards always spawn. Missing docinv JSON → no PASS-fast (fall through to the normal path).
 
 12. **Enter Phase 3 (doc-review)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `3-doc-review DONE` at step 17, co-emitted). Proceed directly to the next step.
 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):
@@ -340,6 +343,14 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
     Doc Sync Context:
     [paste the Doc Sync Context block built above]
 
+    Deterministic invariant classification (v5.0.0 — when /tmp/docinv-<CARD-ID>.json exists):
+    Read /tmp/docinv-<CARD-ID>.json FIRST — its `triggered` rows ARE the drift check:
+    Read ONLY the `target_doc` of each triggered row (manual pattern-matching over the
+    checklist above applies ONLY when the JSON is missing).
+    Review bundle: /tmp/review-bundle-<CARD-ID>.json — Read it FIRST. Do NOT re-Read source
+    files to rebuild context you can get from its paths; for `hot_files`, Read ONLY the
+    listed symbol ranges.
+
     Instructions for doc-reviewer:
     - **WORKTREE ISOLATION (per AGENTS.md § Worktree isolation):** every doc you Edit/Write MUST be UNDER the worktree root <ABSOLUTE_WORKTREE_PATH>. NEVER write a path under the main repo <ABSOLUTE_MAIN_REPO> — it is checked out live by other sessions; `cd` alone does not stop an absolute main-repo path. Edit the worktree-rooted copy of every doc.
     - You OWN the `doc` domain end-to-end: audit AND apply the fixes in THIS invocation.
@@ -385,6 +396,10 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
     - Worktree path: <worktree-path> — `cd` into it before running any gate
     - Branch: <branch-name>
     - Changed files: <list from implementation phase>
+    - Review bundle: /tmp/review-bundle-<CARD-ID>.json (when present) — its `files_changed`
+      is authoritative for scope (do not re-derive); its `gate_logs` are CONTEXT ONLY
+      (Phase-2 logs, possibly stale after Simplify/doc mutations) — the gates your tier
+      owns you execute yourself, never cite a bundle log as your own run
     - QA profile: [deep | balanced-escalated]
 
     Tier contract: deep → FULL suite. A BALANCED card only reaches this step when risk drift
@@ -404,7 +419,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 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.
+    - 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. **Fix-pass model routing (v5.0.0 A/B, best-effort)**: spawn it with `model: sonnet` when the runtime supports it (overlay `## [OVERRIDE] Fix-pass model` wins — see implement.md step 9); append `model=<sonnet|opus>` to the Fix Application Log rows.
     - 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. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=none safe (a failing QA gate is a merge blocker) → materialize a follow-up card and stop this card's commit (NEVER force-proceed past a FAIL verdict).**
     - The commit in Phase 4 MUST NOT happen until QA verdict is PASS (or user explicitly overrides).

package/framework/.claude/skills/new/scripts/build-review-bundle.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * build-review-bundle.mjs — deterministic per-card review bundle (v5.0.0).
+ *
+ * Materializes ONE JSON file every downstream reviewer reads FIRST, so the
+ * chain stops re-deriving scope the orchestrator already has (measured: the
+ * same hot files re-read at every link — data.ts 363× coder / 111× reviewer).
+ * Pure derivation from git + files already on disk — NEVER an LLM summary
+ * (a summarized code artifact would be a second SSOT that drifts).
+ *
+ * Usage (run from anywhere; --worktree is the card's worktree):
+ *   node build-review-bundle.mjs --card FEAT-0001-02 --worktree <path> --trunk main \
+ *        [--card-yaml backlog/FEAT-0001-02.yml] [--may-edit "src/a.ts,src/b.ts"] [--out /tmp/review-bundle-<ID>.json]
+ *
+ * Output: /tmp/review-bundle-<CARD-ID>.json + a one-line summary on stdout.
+ * Exit 0 always (fail-open: missing pieces are null — a reviewer treats a null
+ * as "derive this one yourself", never as a hard failure).
+ */
+
+import fs from 'fs';
+import { execFileSync } from 'child_process';
+
+const args = {};
+for (let i = 2; i < process.argv.length; i++) {
+  const k = process.argv[i];
+  if (k.startsWith('--')) args[k.slice(2)] = process.argv[i + 1], i++;
+}
+const card = args.card;
+const worktree = args.worktree || process.cwd();
+const trunk = args.trunk || 'main';
+if (!card) { console.error('usage: build-review-bundle.mjs --card <CARD-ID> --worktree <path> --trunk <branch>'); process.exit(0); }
+
+const out = args.out || `/tmp/review-bundle-${card}.json`;
+const exists = (p) => { try { fs.accessSync(p); return true; } catch { return false; } };
+const git = (argv) => {
+  try { return execFileSync('git', ['-C', worktree, ...argv], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }
+  catch { return null; }
+};
+
+// Ownership scope (v5.0.1): in a sequential multi-card batch the worktree's
+// `trunk...HEAD` accumulates PRIOR cards' commits — an unscoped diff would make
+// card N's bundle/docinv classify other cards' files. When --may-edit is passed
+// (implement.md step 11c always passes it), scope the diff to this card's
+// allowed files; standalone invocations without it keep the full diff.
+const mayEdit = args['may-edit'] ? args['may-edit'].split(',').map((s) => s.trim()).filter(Boolean) : null;
+const scopeArgs = mayEdit && mayEdit.length ? ['--', ...mayEdit] : [];
+
+// diff: reuse the per-card dump when present, else write it now (same command
+// as implement.md step 8 / codex-gate — this script UNIFIES the dumps).
+const diffPath = `/tmp/diff-${card}.txt`;
+if (!exists(diffPath)) {
+  const diff = git(['diff', `${trunk}...HEAD`, ...scopeArgs]) ?? git(['diff', 'HEAD~1..HEAD', ...scopeArgs]);
+  if (diff != null) fs.writeFileSync(diffPath, diff + '\n');
+}
+
+// files changed (trunk-relative, uncommitted fallback; card-scoped when possible)
+const filesChanged = (git(['diff', '--name-only', `${trunk}...HEAD`, ...scopeArgs]) ?? git(['diff', '--name-only', 'HEAD~1..HEAD', ...scopeArgs]) ?? '')
+  .split('\n').filter(Boolean);
+
+// arch baseline + Hot-File Map (deterministic parse of the architect's block:
+//   `path (N lines): symbol — L<start>–L<end>`)
+const baselinePath = `/tmp/arch-baseline-${card}.md`;
+let hotFiles = [];
+if (exists(baselinePath)) {
+  const base = fs.readFileSync(baselinePath, 'utf8');
+  const section = base.split(/^##\s*Hot-File Map\s*$/m)[1];
+  if (section) {
+    const body = section.split(/^##\s/m)[0];
+    // \s* BEFORE the bullet: a match anchored at string start would otherwise
+    // eat the leading newline via the later \s* and swallow the bullet into
+    // the filename capture.
+    const rowRe = /^\s*[-*]?\s*(.+?)\s*\((\d+)\s*lines?\):\s*(.+?)\s*[—-]\s*L(\d+)\s*[–-]\s*L?(\d+)\s*$/gm;
+    const byFile = new Map();
+    let m;
+    while ((m = rowRe.exec(body))) {
+      const [, file, lines, symbol, start, end] = m;
+      if (!byFile.has(file)) byFile.set(file, { file, lines: Number(lines), symbols: [] });
+      byFile.get(file).symbols.push({ name: symbol.trim(), range: [Number(start), Number(end)] });
+    }
+    hotFiles = [...byFile.values()];
+  }
+}
+
+// gate logs written by implement.md step 8 (paths only — reviewers Read on demand)
+const gateLogs = {};
+for (const gate of ['lint', 'tsc', 'test', 'build', 'i18n', 'dsgate']) {
+  const p = `/tmp/${gate}-${card}.txt`;
+  if (exists(p)) gateLogs[gate] = p;
+}
+
+const completionPath = `/tmp/completion-${card}.md`;
+const docinvPath = `/tmp/docinv-${card}.json`;
+
+const bundle = {
+  card,
+  trunk,
+  worktree,
+  generated_at_commit: git(['rev-parse', '--short', 'HEAD']),
+  card_yaml_path: args['card-yaml'] || null,
+  diff_path: exists(diffPath) ? diffPath : null,
+  files_changed: filesChanged,
+  arch_baseline_path: exists(baselinePath) ? baselinePath : null,
+  hot_files: hotFiles,
+  completion_report_path: exists(completionPath) ? completionPath : null,
+  doc_invariants_path: exists(docinvPath) ? docinvPath : null,
+  ownership_may_edit: mayEdit,
+  gate_logs: gateLogs,
+  generated_by: 'build-review-bundle.mjs v5.0.1',
+};
+
+fs.writeFileSync(out, JSON.stringify(bundle, null, 2) + '\n');
+console.log(`review-bundle: ${out} (files=${filesChanged.length} hot=${hotFiles.length} baseline=${bundle.arch_baseline_path ? 'yes' : 'MISSING'} completion=${bundle.completion_report_path ? 'yes' : 'missing'})`);