baldart 3.36.0 → 3.37.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.37.0] - 2026-05-30
+
+**Two-tier review for `/new`: fast `light` per-card during the loop, one guaranteed FULL pass over the whole batch before merge.** This activates the dormant v3.35.0 Review Profile Selector AND re-introduces an unconditional final full review — together they cut tokens/wall-clock on low-risk cards *without* weakening the merge gate. **No new `baldart.config.yml` keys** — both are changes inside the skill, so the schema-propagation rule does not apply.
+
+> **The design.** `light` (per-card Phase 3.7) is now an **early-feedback optimization**, not the safety gate. The safety gate is the **Final review**, which since this release 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. So every line of every card, including any reviewed at `light`, gets a full-depth Codex review at least once before merge. This is what makes activating `light` safe: it shifts the breadth passes (qa-sentinel, api-perf-cost-auditor, doc-reviewer) + CoVe from the per-card loop to the single final pass, rather than dropping them from the merge gate. (The v3.35.0 data gate — which had kept the selector hard-coded to `full` pending consumer telemetry — is lifted by explicit maintainer decision; an adversarial review showed that gate's intended post-hoc telemetry could never have validated it anyway, since the Fix Application Log is blind by construction to blockers `light` *misses*. The final full gate makes that validation question moot.)
+
+### Changed — Review Profile Selector live (per-card early feedback)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)**: Phase 3.7 Step C (sequential) and Team Mode D.4b no longer hard-code `profile = full`. The selector runs as designed — `light` ⟺ Step A matched **0** high-risk triggers **AND** the card's QA profile ∈ {`skip`, `light`}; `full` otherwise. **BUG-0530 invariant preserved**: `light` ≠ skip — Codex adversarial + `code-reviewer` + false-positive gate ALWAYS run per-card; `light` drops only the breadth passes + CoVe.
+
+### Changed — Final review is now an unconditional FULL batch-diff gate (supersedes v3.35.0 scope-reduction)
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** (Final review / Step F.1): the v3.35.0 final-review scope gate (N=1 → skip F.1–F.4; N>1 → reduce to the cross-card surface) is **removed**. The final review now runs Steps F.1–F.5 for **every batch including N=1**, with `review_scope_files` = the **full union** of all touched files, never reduced. F.3 reviews the entire batch diff at full depth (Codex + doc-reviewer + api-perf-cost-auditor + qa-sentinel); F.5 runs the final build. Team mode reaches the same gate via "Post-batch — same as sequential mode" (its prior "cross-card-only scope" note is updated accordingly).
+- **Rationale**: v3.35.0 de-duplicated the final full pass on the assumption that Phase 3.7 had already full-reviewed every card. Selecting `light` breaks that assumption, so the post-batch full pass is re-introduced as the guaranteed merge gate.
+
+### Cost & trade-offs (documented)
+
+- **Net cost**: one full `/codexreview` per batch is re-introduced (the deliberate price of the per-card `light` speed-up). The saving comes from cheaper per-card reviews during the loop; the final pass is paid once per batch, not per card.
+- **Later feedback on `light` cards**: a defect on a `light`-reviewed card may now surface at the final pass rather than at the per-card step — possibly a later fix-cycle. Acceptable: it is still caught before merge.
+- **Revert**: to make Phase 3.7 always-full again, restore `profile = full` (no config kill-switch by design). The final full gate is independent and stays regardless.
+
 ## [3.36.0] - 2026-05-30
 
 Adds **opt-in session telemetry** to `/new` and `/prd`: append `-stats` (or `--stats`) to a run and, at the end, the skill writes a per-**agent-role** breakdown of REAL token consumption and wall-clock time. This finally answers "what took the most time and tokens in a `/new` run" — and feeds the v3.35.0 Review Profile Selector **data gate** (still pending precisely because `docs/metrics/` carried no per-role cost data). **No new `baldart.config.yml` keys** — the opt-in is a flag, not a config feature, so the schema-propagation rule does not apply.

package/VERSION

@@ -1 +1 @@
-3.36.0
+3.37.0

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

@@ -1113,7 +1113,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 ### 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 Phase 7 remains as a final cross-card sweep. This Phase 3 focuses exclusively on documentation sync, which must happen per-card (tied to the specific commit).
+> **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).
 
 12. **Update tracker**: phase = "3-doc-review".
 13. Build a **Doc Sync Context** block:
@@ -1287,10 +1287,15 @@ For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH var
    doc-reviewer) and Step 3.5 CoVe — exactly the passes that yield ~nothing on a 0-trigger, QA-light
    diff. The BUG-0530 invariant ("never miss a blocker on a low-risk path") holds because the Codex
    adversarial pass — the one that catches those — always runs.
-   **DATA GATE (BLOCKING for `light`)**: until the consumer's telemetry (`docs/metrics/` Fix
-   Application Log) confirms that `light`-eligible cards have NOT historically produced verified
-   BLOCKER/HIGH at FULL depth, hard-code `profile = full` here. Flip to the selector only after the
-   data passes (no config key — change the line).
+   **ACTIVE since v3.37.0**: the selector above runs as written. Here `light` is an **early-feedback
+   optimization** for the per-card loop — NOT the merge-gate. Safety is guaranteed downstream: 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"). So every card
+   reviewed at `light` here still receives a full-depth review before merge; `light` shifts the breadth
+   passes (qa-sentinel, api-perf-cost-auditor, doc-reviewer) + CoVe from the per-card loop to that single
+   final full pass, it does not drop them from the merge gate. The BUG-0530 invariant still holds per-card
+   (Codex adversarial + `code-reviewer` + FP-gate always run in `light`). To make Phase 3.7 always-full
+   again: restore `profile = full` here (the final full gate is independent and stays regardless).
 
    Then dump the card diff (reviewer grounding) and write the lean contract `/codexreview` consumes:
    ```bash
@@ -1402,20 +1407,24 @@ Never block the pipeline indefinitely — recover and continue per the rules abo
 
 Once ALL cards are committed in the worktree:
 
-> **Final-review scope gate (deterministic, since v3.35.0)** — the per-card Phase 3.7 `/codexreview`
-> gate has ALREADY reviewed every card individually before its commit. The final review exists to
-> catch what a per-card pass structurally cannot: **cross-card interactions**. Branch on batch size:
+> **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.
 >
-> - **Single card (N=1)**: SKIP Steps F.1–F.4 (the lone card is byte-identical to what Phase 3.7
->   already passed — re-review adds nothing). Log:
->   `"Final review (F.1–F.4) skipped — single card already passed /codexreview at Phase 3.7 (PASS), code unchanged since commit"`.
->   Then jump to **Step F.5 and RUN the final build** (`npm run lint && npx tsc --noEmit && npm run build`)
->   — that gate is NOT skipped.
-> - **Multiple cards (N>1)**: run F.1–F.5 but **scope the review to the cross-card surface only**
->   (computed, not discretionary) — see F.1 step 4. If that surface is empty, log
->   `"cross-card review: no shared surface (intersection=∅, depends_on=∅) — F.3 limited to integration sanity"`
->   and run a minimal integration pass (build + type-check across the union) instead of a full
->   per-line re-review. This is a computed scope reduction, NEVER a model-decided skip.
+> - 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
 
@@ -1426,11 +1435,11 @@ Once ALL cards are committed in the worktree:
    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 union of card-indicated files + git-touched files. **For N>1 (per
-   the Final-review scope gate above), then REDUCE `review_scope_files` to the cross-card subset**:
-   files appearing in ≥2 cards' File Ownership Map entries ∪ files of any `depends_on`-linked card
-   pair. Record both the full union and the reduced set in the tracker; downstream F.3 reviews the
-   reduced set.
+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
 
@@ -2193,7 +2202,7 @@ After ALL agents in the group complete successfully:
 
 4a. **D.4a — Per-card doc gate (consumes D.2, since v3.35.0)** — Do NOT re-spawn `doc-reviewer`. For EACH card in the group, take that card's doc findings from D.2's per-card-attributed output; if any exist, spawn a targeted fix-coder for that card only. (Previously D.4a re-ran doc-reviewer per card — a duplicate of D.2; collapsed to a single attributed D.2 pass. D.4b's per-card `/codexreview` also skips its doc-reviewer via the lean contract, so doc-review now runs once per group instead of ~3× per card.)
 
-4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per 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`, and `profile: light|full` from (0 triggers + QA ∈ {skip,light}). LIGHT still runs Codex adversarial + code-reviewer + FP-gate (subject to the same DATA GATE: keep `full` until telemetry confirms).
+4b. **D.4b — Pre-Merge Codex Review Gate (per-card, MANDATORY — UNCONDITIONAL)** — Invoke `/codexreview` for EACH card in the group, one at a time, BEFORE any commit. This mirrors Phase 3.7 of the sequential path and is non-skippable regardless of file paths or perceived risk. Apply the same fix sub-loop: if the consolidated report shows verified BLOCKER/HIGH findings, spawn a fix-coder and re-run `/codexreview <CARD-ID>` (max 2 retries per 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`, and `profile: light|full` from (0 triggers + QA ∈ {skip,light}). LIGHT still runs Codex adversarial + code-reviewer + FP-gate. The Review Profile Selector is **ACTIVE since v3.37.0** — same status as sequential Phase 3.7 Step C above: `light` is per-card early feedback, and the merge-gate safety 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 per-card always-full again, restore `profile = full`; 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
@@ -2245,7 +2254,7 @@ Before starting group N, verify ALL cards in groups 0..N-1 are status: done. If
 
 ### 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. Team mode is always N>1, so the Final Review applies its deterministic **cross-card-only scope** (per the Final-review scope gate) — not a full per-line re-review.
+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.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.36.0",
+  "version": "3.37.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"