baldart 4.33.2 → 4.34.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [4.34.1] - 2026-06-12
+
+**`reference-integrity` CI gate: recognize the plumbing carve-out.** v4.33.2 introduced a legitimate `subagent_type: general-purpose` dispatch for the mechanical file-revert agent (the REGISTRY.md plumbing carve-out — mechanical git/file ops, never code authoring), but the CI `reference-integrity` gate's R11 anti-fallback rule banned `general-purpose` **unconditionally**, so `main` went red on the v4.33.2 / v4.34.0 tags (the npm publish workflow is independent and succeeded — both versions are live). The gate now allows `subagent_type: general-purpose` **only** on a dispatch line explicitly marked `plumbing carve-out`; every other `general-purpose` dispatch stays banned (R11 intact, intentionally narrow so it can't be abused as a generic fallback). **PATCH** (CI gate fix; no behavior change to `/new`).
+
+### Changed
+
+- **`scripts/check-reference-integrity.js`** — Check A allows `subagent_type: general-purpose` when the dispatch line carries the literal `plumbing carve-out` marker; otherwise the R11 ban stands (with an error message pointing to the marker + REGISTRY.md).
+
+## [4.34.0] - 2026-06-12
+
+**`/new` per-card review cluster extracted into the `new-card-review` dynamic workflow — kills the dominant context-cost driver on long epics.** On a long epic (10-12 cards) `/new` accumulated context monotonically: every card ran the full review fan-out (Simplify ×3 + Codex/code-review + qa + the verify/FP pass) *inside the orchestrator*, and each step re-paid the whole growing prefix (cumulative `cache_read`). The driver is **turn-count × prefix**, not subagent output volume. Following the validated `new-final-review` pattern (read-only fan-out hosted in a workflow whose context is discarded), the review cluster now runs OUTSIDE the orchestrator and returns only a compact result.
+
+A **single workflow parametrized on the number of cards** covers both modes: sequential delegates `cards:[1]`; team-mode delegates `cards:[the whole wave]`, so it runs **once per wave, not once per card** — the key win, since the team-mode per-card Codex (D.4b) + Simplify (D.3b) loops were the chattiest sub-steps. The workflow fans out the finders per card (Simplify + cross-model Codex with `code-reviewer` fallback + qa-sentinel at group-max tier + security-reviewer on high-risk only), each specialist FP-checking its own findings; then **one `coder` applies all VERIFIED code/perf/security/simplify findings in a single pass** (files disjoint by ownership) and re-verifies lint/tsc/build. Only `{perCard:{fixesApplied,residual}, gateTable, summary}` re-enters the orchestrator — the minority `residual` (doc, needs-manual, scope-expanding, unconverged) is resolved by the skill with the right specialist or a user gate.
+
+**Boundaries (by design):** E2E (Phase 2.6 / D.3c — human-gated + nests a skill) and doc-review (Phase 3 / D.2+D.4a — write-mode, must see final code) stay in the skill; doc runs **after E2E on final code** in the delegated path. `/codexreview` (Phase 3.7 / D.4b — a skill that nests sub-agents) cannot run inside a workflow, so the workflow launches the Codex **binary** directly via an agent (haiku preflight + background poll), exactly like `new-final-review`; the **Final FULL gate** remains the cross-card depth net. api-perf stays deferred to the Final. **Opt-in + additive**: delegates only when the `Workflow` tool is available AND the script is linked, else the inline prose (SSOT) runs unchanged — Codex/cross-tool consumers are unaffected. **MINOR** (new capability, fallback inline, no breaking change; no `baldart.config.yml` key ⇒ schema-propagation rule N/A). Validation deferred to telemetry on the first real run (per `/new` convention).
+
+### Added
+
+- **`framework/.claude/workflows/new-card-review.js`** — the per-wave review+fix workflow (1..N cards). Modeled on `new-final-review.js` (shared schemas, deterministic Codex preflight haiku + background poll, specialist-owned FP-check) + Simplify/security finders + the single-coder batch-fix pass.
+
+### Changed
+
+- **`framework/.claude/skills/new/references/review-cycle.md`** — new "Phase 2.5x — Review-cluster workflow delegation gate" (replica of final-review.md F.1.5): delegates Phase 2.55+3.5+3.7 to `new-card-review` (`cards:[this card]`), consumes the typed `residual`, then proceeds E2E→Doc→Commit; else inline SSOT. `IS_TRIVIAL` never delegates.
+- **`framework/.claude/skills/new/references/team-mode.md`** — new "D.1.6 — Review-cluster workflow delegation gate": delegates the group's D.3b+D.4+D.4b in ONE call per wave (`cards:[the wave]`), runs D.3a (AC-closure) before it and D.3c (E2E) + post-E2E doc + D.5/D.6 after; else inline.
+- **`framework/.claude/skills/new/references/codex-gate.md`** — Phase 3.7 carve-out: SKIP when the cluster was delegated (the workflow already ran the Codex pass).
+- **`framework/.claude/skills/new/SKILL.md`** — routing table notes the `new-card-review` delegation for the 2.55+3.5+3.7 cluster (parity with the final-review row).
+- **`framework/docs/WORKFLOWS.md`** — documents the `new-card-review` workflow.
+
 ## [4.33.2] - 2026-06-12
 
 **`/new` runs its two purely-mechanical spawns on haiku instead of opus.** Audit of every agent `/new` spawns (not `new2`) found that the spawns inherit each agent's frontmatter default and none ever override `model:` — correct for the reasoning agents (`coder`/`ui-expert` = opus; the review/analysis agents = sonnet), but the **background worktree-setup subagent** that runs `/nw` is a `general-purpose` agent with no `model:`, so it inherited the **session model (opus)** to do pure git plumbing (create worktree, install deps, allocate port, write registry). Same shape for the **file-scoped revert agent** (was spawned as `coder`/opus to do a mechanical revert). Both now run on **haiku** — cheaper and faster on the background barrier, with no quality loss because neither does any reasoning or code authoring. `qa-sentinel` deliberately stays on sonnet (failure interpretation + test-tier selection). `/mw` is invoked inline by the orchestrator (not a subagent) so it is unaffected. No `baldart.config.yml` key involved (model selection is native) ⇒ schema-change propagation rule does not apply. **PATCH** (cost/perf, no new capability, no breaking change).

package/VERSION

@@ -1 +1 @@
-4.33.2
+4.34.1

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

@@ -271,8 +271,8 @@ mappa di navigazione.
 | 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) |
+| 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. **Il cluster discovery+fix 2.55+3.5+3.7 delega al workflow `new-card-review` se il tool `Workflow` è disponibile (review-cycle.md § Phase 2.5x — poi E2E→Doc→Commit); altrimenti inline. E2E (2.6) e Doc (3) restano sempre nella skill.** |
+| 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). **Coperta dal workflow `new-card-review` quando il cluster è delegato (codex-gate.md carve-out).** |
 | 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). **F.2–F.4 delegate al workflow `new-final-review` se il tool `Workflow` è disponibile (Step F.1.5); altrimenti inline.** F.5/F.6 sempre nella skill. |
 | 6 / 6b / 6c — Merge & cleanup | dopo Final | [`references/merge-cleanup.md`](references/merge-cleanup.md) | mai (BLOCKING) |

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

@@ -4,6 +4,16 @@
 
 ### Phase 3.7 — Pre-Merge Codex Review Gate (MANDATORY — UNCONDITIONAL)
 
+> **Workflow-delegation carve-out (v4.34.0)**: if the review cluster was delegated to the
+> `new-card-review` workflow (see `references/review-cycle.md` § "Phase 2.5x — Review-cluster workflow
+> delegation gate"), this Phase 3.7 is **already covered** — the workflow ran the cross-model Codex pass
+> (agent-launched binary, `code-reviewer` fallback) at the card's profile depth as part of the cluster,
+> and the FP-validated findings were already fix-applied. **SKIP this gate**; log
+> `codex-review: covered by new-card-review workflow`. This carve-out applies ONLY when the delegation
+> branch was taken; on the inline fallback (no `Workflow` tool) this gate runs in full as written below.
+> The unconditional **Final-review FULL gate** (Codex over the whole batch) remains the cross-card net
+> in both paths.
+
 **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)`.

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

@@ -2,6 +2,81 @@
 
 > **Modulo `/new`** — eseguilo, poi torna al core § "Routing" per la fase successiva. I `§ "..."` (Context economy, Context Tracking, Trivial-card fast-lane, Risk-signal detector, Fix Application Log) vivono nel **core SKILL.md**.
 
+### Phase 2.5x — Review-cluster workflow delegation gate (v4.34.0 — opt-in, additive)
+
+The per-card review cluster — **Phase 2.55 Simplify + Phase 3.5 QA + Phase 3.7 Codex** (the
+*discovery* fan-out: Simplify trio, cross-model Codex/code-reviewer, qa-sentinel gates, security
+review) plus the **fix application** — is a self-contained read-then-fix pass that touches no git
+state outside the worktree and asks the user nothing on the happy path. That makes it a clean fit for a
+**dynamic workflow** that runs the whole cluster OUTSIDE this orchestrator's context window (the single
+biggest source of prefix growth on long epics). E2E (Phase 2.6, human-gated + nests a skill) and the
+doc-review (Phase 3, write-mode, must see the FINAL code) stay in the skill.
+
+**Branch (decide once, here — at the top of the review cluster, AFTER Phase 2.5b AC-Closure):**
+
+- **IF `IS_TRIVIAL`** (§ "Trivial-card fast-lane", re-confirmed on the committed diff) → do NOT delegate.
+  Follow the trivial fast-lane in Phase 2.55 below (inline mechanical gates → Phase 3 doc → commit).
+
+- **ELSE IF** the `Workflow` tool is available **AND** `.claude/workflows/new-card-review.js` is present
+  (linked by the framework on Claude-enabled installs) → **delegate the cluster** to it. First build the
+  inputs (reusing the existing deterministic logic — do NOT re-implement it):
+  - `qaTier` ← the **Phase 3.5 profile selection** (step 19-21b below: `review_profile` floor →
+    `skip`/`light` ⇒ `qaTier:"light"` (qa-sentinel deferred to Final), `deep` **or any Phase 3.7 Step-A
+    high-risk trigger on this card's diff** ⇒ `qaTier:"full"`). Compute the **Step-A detector**
+    (`references/codex-gate.md` Step A) once here — it also tells the workflow's Codex pass the depth.
+  - `scopeFiles` ← this card's committed diff (`git diff --name-only "$TRUNK...HEAD"`, fallback `HEAD~1..HEAD`).
+  - `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).
+  - `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 }],
+    worktreePath, baseBranch, config            // from Phase 0 / tracker
+  }})
+  ```
+
+  The workflow runs Simplify + Codex (agent-launched, code-reviewer fallback) + qa-sentinel + security,
+  FP-checks each specialist's own findings, then **one coder applies all VERIFIED
+  code/perf/security/simplify findings in a single pass** and re-verifies lint/tsc/build. It returns
+  `{ codexEngine, perCard: { <CARD-ID>: { fixesApplied, residual } }, gateTable, summary }`.
+  **Skip the inline Phase 2.55 + Phase 3.5 below AND the Phase 3.7 gate in `codex-gate.md`** (all three
+  are now done), then handle the workflow output HERE in the skill. **Process each `residual` finding by
+  CLASSIFICATION FIRST, then domain** (so a needs-manual doc finding reaches the human gate, not the
+  automated doc re-review):
+  - `classification == NEEDS_MANUAL_CONFIRMATION` (any domain) → `AskUserQuestion` — the human gate the
+    workflow cannot run. (`summary.needsManual` counts these, doc included.)
+  - else `domain == doc` residual → carry into **Phase 3** (the doc-reviewer runs there, post-E2E, on final code).
+  - else `code`/`perf`/`security`/`migration` residual (a fix the coder could not converge in its 2 retries)
+    → spawn a targeted `coder` now over this card's `editableFiles`.
+  - **QA gate (BLOCKING — mirror of inline Phase 3.5 step 24)**: if `gateTable` has any `status:"FAIL"`
+    **OR** `summary.checksFailed` is true, the merge gate is NOT satisfied. Spawn a `coder` on the
+    failing gates / post-fix regressions (≤2 retries, re-run via the workflow or inline qa-sentinel),
+    then if still failing → `AskUserQuestion` (proceed/stop). **Do NOT proceed to Phase 4 commit until
+    `gateTable` is all PASS/SKIP and `checksFailed` is false** — a delegated QA FAIL must block exactly
+    as the inline path does. (`gateTable` is **wave-scoped**, not per-card — qa-sentinel runs once over
+    the worktree; a FAIL applies to the whole wave's commit.)
+  - **Telemetry**: append the workflow's `fixesApplied` + `residual` to `## Fix Application Log`
+    (`decision=workflow`). Derive the Phase-8 producers from the return: `qa_first_attempt` ←
+    `summary.qaRan ? (summary.failingGates.length === 0 && !summary.checksFailed ? "pass" : "fail") : "n/a"`
+    (n/a when qa was deferred to the Final); `doc_gaps` is produced by **Phase 3** (which still runs below).
+
+  Then proceed to **Phase 2.6 (E2E)** → **Phase 3 (doc review, relevance-gated)** → **Phase 4 (commit)**.
+  Log `review-cluster: delegated to new-card-review (engine: <codexEngine>, fixes: <n>, residual: <n>, qa: <pass|fail|deferred>)`.
+
+- **ELSE** (no `Workflow` tool — older Claude Code, `disableWorkflows`, or a Codex install where
+  workflows have no equivalent) → run the **inline Phase 2.55 → 2.6 → 3 → 3.5 → 3.7 exactly as written
+  below**. This prose is the SSOT and the always-available fallback; the workflow only mirrors it.
+
+> **Drift note (maintainers):** `new-card-review.js` encodes only the *orchestration shape* of the
+> review cluster; its agent briefs cite THIS module for the review *semantics*, so the SSOT for what each
+> finder checks stays here. When you change the Simplify lenses, the qa contract, the Codex/Step-A
+> profile rule, or the FP-check/routing, update the workflow's phase/agent wiring to match. The
+> delegated path runs the doc-review (Phase 3) on the FINAL post-fix/post-E2E code; the inline path runs
+> it at its current position — both are doc-relevance-gated and both are backstopped by the Final FULL
+> doc-reviewer.
+
 ### 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.

package/framework/.claude/skills/new/references/team-mode.md

@@ -163,6 +163,63 @@ After ALL agents in the group complete successfully:
    - **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 (doc-reviewer scoping), D.3b/D.3c (already skipped for trivial), and D.4b (inclusion + per-card Codex profile: `light` cards → `/codexreview` `light`, `full` cards → `full`) — do NOT recompute it downstream.
 
+1.6. **D.1.6 — Review-cluster workflow delegation gate (v4.34.0 — opt-in, additive)** — The group's
+   code-review cluster — **D.3b Simplify + D.4 QA + D.4b Codex** (per-card discovery) **and their fix
+   application** — runs ONCE per wave OUTSIDE this orchestrator's context when delegated to a dynamic
+   workflow. This is the single biggest context-economy win in team mode (the D.4b per-card Codex loop +
+   the D.3b per-card Simplify fan-out are the chattiest sub-steps).
+
+   - **IF** the `Workflow` tool is available **AND** `.claude/workflows/new-card-review.js` is present →
+     **delegate the cluster for the whole group in ONE call.** First run **D.3a (AC-Closure Gate)** for
+     every card (it is a human gate and must precede the review — keep it here, before the workflow).
+     Then build one `cards[]` entry per **non-trivial** card in the group (skip `TRIVIAL_CARDS`):
+     `cardId`, `cardPath`, `scopeFiles` (the card's committed diff), `editableFiles` (its File Ownership
+     Map slice), `qaTier` (`full` iff the GROUP max is `deep`/risk-escalated per D.1.5 — mirrors D.4's
+     group predicate; else `light`), `hasSecurityFiles` (scope ∩ `paths.high_risk_modules`),
+     `runSimplify:true`, `archBaselinePath` (`/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`).
+     ```
+     Workflow({ name: 'new-card-review', args: {
+       cards: [ …one entry per non-trivial card in the wave… ],
+       worktreePath, baseBranch, config
+     }})
+     ```
+     The workflow fans out the finders per card, runs ONE Codex pass + ONE qa-sentinel (group max tier)
+     over the union, and **one coder applies all VERIFIED code/perf/security/simplify fixes for the
+     whole group in a single pass** (files disjoint by ownership → no conflict, same as D.3). It returns
+     `{ codexEngine, perCard, gateTable, summary }`. **Skip the inline D.2 (code portion), D.3, D.3b,
+     D.4, D.4b** below. Then per card handle `perCard[<id>].residual` exactly as the sequential gate does
+     (`references/review-cycle.md` § Phase 2.5x — **by classification first**: `NEEDS_MANUAL_CONFIRMATION`
+     any-domain → `AskUserQuestion`; else doc residual → the post-E2E doc step; else unconverged
+     code/perf/security residual → targeted `coder`). Apply the **same BLOCKING QA-gate consumption**:
+     `gateTable` with any `status:"FAIL"` OR `summary.checksFailed` → coder fix (≤2 retries) then
+     `AskUserQuestion`; **D.5 commit MUST NOT happen until `gateTable` is PASS/SKIP and `checksFailed` is
+     false** (a delegated QA FAIL blocks exactly as inline D.4 / Phase 3.5 would — `gateTable` is
+     wave-scoped). Append the workflow `fixesApplied`/`residual` to `## Fix Application Log`
+     (`decision=workflow`, with `card=<ID>`).
+     - **Coverage-assertion reconciliation (BLOCKING — closes the FEAT-0006 hole on the delegated path)**:
+       the Step D coverage assertion (below) requires per-card `simplify:` / `code-review:` /
+       `codex-review:` / `qa:` rows whose inline producers (D.3b/D.4/D.4b) were just skipped. **Synthesize
+       them truthfully from the workflow return**, per non-trivial card: `simplify:` ← `<n> fixes via
+       workflow | decision=workflow` (or `clean`); `code-review:`/`codex-review:` ← `decision=workflow,
+       engine=<codexEngine>`; `qa:` ← `summary.qaRan ? (gateTable all PASS ? "PASS" : "FAIL→fixed/asked")
+       : "DEFERRED to Final FULL gate (group max ≤ balanced)"`; `qa_first_attempt` ← `summary.qaRan ?
+       (summary.failingGates.length===0 && !summary.checksFailed ? "pass" : "fail") : "n/a"`. `TRIVIAL_CARDS`
+       (excluded from `cards[]`) still get their `SKIPPED (trivial)` rows as in the inline path. A
+       `decision=workflow` row is a **truthful** producer — never write a placeholder for work that did
+       not run. `doc_gaps` is produced by the post-E2E doc step (D.4a logic, below).
+     Then proceed: **D.3c (E2E)** → **doc-review (audit+apply, group, relevance-gated — run it HERE,
+     after E2E, on the final code; this is the D.2-audit + D.4a-apply pair collapsed into one post-E2E
+     pass, excluding `DOC_DEFER_CARDS`)** → **D.5 (commit)** → **D.6 (backlog)**.
+     Log `D.1.6: review-cluster delegated to new-card-review (wave, <N> cards, engine: <codexEngine>, qa: <pass|fail|deferred>)`.
+
+   - **ELSE** (no `Workflow` tool / Codex install) → run the **inline D.2 → D.6 exactly as written
+     below** (SSOT fallback; unchanged order). 
+
+   > **Drift note (maintainers):** when delegating, the doc-review (D.2 audit + D.4a apply) runs as a
+   > single post-E2E pass on final code; on the inline fallback it stays split at D.2/D.4a. Both exclude
+   > `DOC_DEFER_CARDS` and are backstopped by the Final FULL doc-reviewer. Keep the workflow's finder
+   > set / FP-check / profile rule in sync with `references/review-cycle.md` (the cluster SSOT).
+
 2. **D.2 — Combined static review (group)** — **doc-reviewer only** (since v4.18.0 — the code-reviewer pass moved to D.4b; see below):
    - **doc-reviewer — over the group MINUS `DOC_DEFER_CARDS`** (since v4.7.0). It runs **read-only here**, 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 (in write mode) to apply them — no second AUDIT spawn, but the FIXES are still owned by doc-reviewer.
    - **No D.2 code-reviewer (since v4.18.0).** Previously `code-reviewer` ran here over `LIGHT_CARDS \ TRIVIAL_CARDS` as their single per-card code review (to keep Codex off light). Now that `light` runs Codex per-card (Codex finder + FP-gate at D.4b — `code-reviewer` validates there), the light cards' code review lives at **D.4b** alongside the full cards. D.2 no longer spawns a code-reviewer; log `D.2 code-reviewer: N/A (light cards code-reviewed at D.4b via Codex-light since v4.18.0)`.
@@ -224,7 +281,7 @@ Before moving to Step E, the orchestrator MUST verify the tracker contains, for
 - `code-review: <covered at D.4b (Codex-light FP-gate or Codex-full) | SKIPPED (trivial — non-source diff)>` (per-card — since v4.18.0 light cards are code-reviewed at D.4b, not D.2; the trivial SKIP is valid ONLY for `TRIVIAL_CARDS` per the D.1.5 partition)
 - `codex-review: <verdict (light — Codex finder + FP-gate) | verdict (full) | SKIPPED (trivial — non-source diff; covered by Final FULL gate)>` (per-card from D.4b — since v4.18.0 `LIGHT_CARDS` produce a Codex verdict, NOT a skip; the SKIPPED form is valid ONLY for `TRIVIAL_CARDS`)
 
-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/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.
+A missing entry means a sub-step was skipped. An entry whose value is a **`review_profile`-driven SKIP/DEFER**, an **`IS_TRIVIAL` SKIP**, a **`/prd`-provenance SKIP**, or a **`decision=workflow` provenance** (the D.1.6 delegated path — the `new-card-review` workflow IS the producer of `simplify`/`code-review`/`codex-review`/`qa` for that card, synthesized truthfully from its return, never a placeholder) with a documented enumerated reason above (D.3b `skip` profile; D.4b/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`; **D.1.6 `decision=workflow`**) 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
 

package/framework/.claude/workflows/new-card-review.js

@@ -0,0 +1,416 @@
+export const meta = {
+  name: 'new-card-review',
+  description:
+    "Per-wave review+fix cluster for /new. Takes 1..N co-located cards (1 = sequential per-card; N = a team-mode group/wave) and runs the whole review fan-out OUTSIDE the orchestrator context: Simplify + cross-model Codex (agent-launched, code-reviewer fallback) + qa-sentinel gates + security-reviewer (high-risk only), each specialist FP-checking its OWN findings; then ONE coder applies all VERIFIED code/perf/security/simplify findings in a single pass (files disjoint by ownership) and re-verifies lint/tsc/build. Doc-review and api-perf are deliberately OUT (doc runs post-E2E in the skill; api-perf is deferred to the Final FULL gate). Returns a compact {perCard:{fixesApplied,residual}, gateTable, summary} — the only object that re-enters the orchestrator prefix. Maps to references/review-cycle.md (Phase 2.55+3.5+3.7) and references/team-mode.md (Step D.2-D.4b). NOT new2: no human gates (returned as residual), no AC-closure, no E2E, no merge/commit/backlog.",
+  phases: [
+    { title: 'Baseline', detail: 'architecture grounding for the wave scope' },
+    { title: 'Discovery', detail: 'parallel finders per card (simplify / codex / qa / security)' },
+    { title: 'Verify', detail: 'specialist-owned FP validation; residual routed to domain specialist' },
+    { title: 'Fix', detail: 'one coder applies all verified code/perf/security/simplify findings + re-verify' },
+  ],
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// args contract — supplied by the /new skill (it owns git + tracker + human gates):
+//   cards         [{ cardId, cardPath, scopeFiles[], editableFiles[], qaTier,
+//                    hasSecurityFiles, runSimplify, archBaselinePath }]
+//                 sequential → length 1; team-mode → the whole group/wave.
+//                   scopeFiles    files the card's committed diff touched (review surface)
+//                   editableFiles ownership-map files the coder MAY write (fix scope)
+//                   qaTier        'light' | 'full'  (qa-sentinel runs only at 'full'; else deferred to Final)
+//                   archBaselinePath  /tmp/arch-baseline-<id>.md  (or null)
+//   worktreePath  string   the batch worktree (agents cd into it)
+//   baseBranch    string   trunk the diff is taken against
+//   config        object   resolved baldart.config.yml (paths.* … )
+//
+// Return value (consumed by the skill):
+//   { codexEngine, perCard: { <cardId>: { fixesApplied:[…1-line], residual:[…finding] } },
+//     gateTable, summary }
+// ───────────────────────────────────────────────────────────────────────────
+
+const a = args || {}
+const cards = (Array.isArray(a.cards) ? a.cards : []).filter((c) => c && c.cardId)
+const cfg = a.config || {}
+const highRisk = (cfg.paths && cfg.paths.high_risk_modules) || [] // security-domain hint
+const protocolRef = '.claude/skills/new/references/review-cycle.md'
+
+// Per-card result accumulator — built up-front (so the early-return guards can return it) and
+// populated with fixesApplied/residual in the Fix phase.
+const perCard = {}
+for (const c of cards) perCard[c.cardId] = { fixesApplied: [], residual: [] }
+
+if (!cards.length) {
+  log('new-card-review: no cards supplied — nothing to review.')
+  return { codexEngine: 'none', perCard, gateTable: [], summary: makeSummary({}) }
+}
+
+// Union scope across the wave (Codex + qa run once over the union; per-card attribution by file).
+const unionScope = dedupe(cards.flatMap((c) => asArr(c.scopeFiles)))
+const unionEditable = dedupe(cards.flatMap((c) => asArr(c.editableFiles)))
+const maxQaTier = cards.some((c) => String(c.qaTier).toLowerCase() === 'full') ? 'full' : 'light'
+
+if (!unionScope.length) {
+  log('new-card-review: empty review scope across all cards — nothing to review.')
+  return { codexEngine: 'none', perCard, gateTable: [], summary: makeSummary({}) }
+}
+
+// ---- Schemas (parity with new-final-review.js) ------------------------------
+const FINDING = {
+  type: 'object',
+  required: ['finding_id', 'title', 'severity', 'confidence', 'evidence', 'minimal_fix_direction', 'domain'],
+  additionalProperties: false,
+  properties: {
+    finding_id: { type: 'string', description: '<CARD-ID>-F### or <agent>-F###' },
+    title: { type: 'string' },
+    severity: { enum: ['BLOCKER', 'HIGH', 'MEDIUM', 'LOW'] },
+    confidence: { type: 'number', description: '0-100' },
+    evidence: { type: 'string', description: 'exact file:line + code quote' },
+    minimal_fix_direction: { type: 'string' },
+    domain: { enum: ['doc', 'security', 'migration', 'code', 'perf', 'test'], description: 'Domain-Override routing bucket' },
+  },
+}
+const FINDINGS_SCHEMA = {
+  type: 'object', required: ['findings'], additionalProperties: false,
+  properties: { findings: { type: 'array', items: FINDING }, note: { type: 'string' } },
+}
+const CODEX_SCHEMA = {
+  type: 'object', required: ['codexAvailable', 'findings'], additionalProperties: false,
+  properties: {
+    codexAvailable: { type: 'boolean', description: 'false if CODEX_NOT_FOUND / TIMED_OUT' },
+    findings: { type: 'array', items: FINDING },
+    note: { type: 'string' },
+  },
+}
+const GATES_SCHEMA = {
+  type: 'object', required: ['gates'], additionalProperties: false,
+  properties: {
+    gates: {
+      type: 'array',
+      items: {
+        type: 'object', required: ['gate', 'status'], additionalProperties: false,
+        properties: { gate: { type: 'string' }, status: { enum: ['PASS', 'FAIL', 'SKIP'] }, detail: { type: 'string' } },
+      },
+    },
+  },
+}
+const VERDICT_SCHEMA = {
+  type: 'object', required: ['classification'], additionalProperties: false,
+  properties: {
+    classification: { enum: ['VERIFIED', 'FALSE_POSITIVE', 'NEEDS_MANUAL_CONFIRMATION'] },
+    rationale: { type: 'string' },
+  },
+}
+const FIX_SCHEMA = {
+  type: 'object', required: ['applied', 'unresolved', 'checks'], additionalProperties: false,
+  properties: {
+    applied: {
+      type: 'array',
+      items: {
+        type: 'object', required: ['finding_id'], additionalProperties: false,
+        properties: { finding_id: { type: 'string' }, note: { type: 'string' } },
+      },
+    },
+    unresolved: { type: 'array', items: { type: 'string', description: 'finding_id left unfixed' } },
+    checks: {
+      type: 'object', required: ['lint', 'tsc', 'build'], additionalProperties: false,
+      properties: { lint: { enum: ['PASS', 'FAIL', 'SKIP'] }, tsc: { enum: ['PASS', 'FAIL', 'SKIP'] }, build: { enum: ['PASS', 'FAIL', 'SKIP'] } },
+    },
+    note: { type: 'string' },
+  },
+}
+
+// ---- Shared brief fragments -------------------------------------------------
+const waveBrief = [
+  `Worktree: ${a.worktreePath || '(cwd)'}`,
+  `Base branch for the diff: ${a.baseBranch || '(trunk)'}`,
+  `Cards under review (Read each YAML for acceptance_criteria + entrypoints):\n${cards.map((c) => `${c.cardId} — ${c.cardPath || '(no path)'}`).join('\n')}`,
+  `ALL changed files in this wave (review every one):\n${unionScope.join('\n')}`,
+].join('\n\n')
+
+function cardScopeBrief(c) {
+  return `Card ${c.cardId} — files changed (review surface):\n${asArr(c.scopeFiles).join('\n') || '(none)'}`
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Baseline — reuse per-card baselines when present, else architect ×1
+// ───────────────────────────────────────────────────────────────────────────
+phase('Baseline')
+const baselinePaths = dedupe(cards.map((c) => c.archBaselinePath).filter(Boolean))
+let baselineBrief
+if (baselinePaths.length) {
+  baselineBrief = `Architecture baseline files (Read each — file paths, type signatures, patterns, high-risk paths):\n${baselinePaths.join('\n')}`
+  log(`Baseline: reusing ${baselinePaths.length} per-card baseline file(s).`)
+} else {
+  const arch = await agent(
+    `You are grounding a post-implementation code review. Map the EXISTING architecture, critical patterns, and high-risk code paths relevant to this wave's changed files, so downstream reviewers can spot regressions.\n\n${waveBrief}\n\nReturn a concise baseline (key modules, their contracts, the regression-prone seams touched by this diff). Do not review the changes yet.`,
+    { label: 'arch-baseline', phase: 'Baseline', agentType: 'codebase-architect',
+      schema: { type: 'object', required: ['baseline'], additionalProperties: false, properties: { baseline: { type: 'string' } } } }
+  )
+  baselineBrief = `Architecture baseline (from codebase-architect):\n${(arch && arch.baseline) || '(unavailable)'}`
+  log('Baseline: spawned codebase-architect (no per-card baselines supplied).')
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Discovery — per-card Simplify/security finders + wave-wide Codex + qa
+// ───────────────────────────────────────────────────────────────────────────
+phase('Discovery')
+
+// Deterministic Codex pre-flight (parity with new-final-review.js F-040): a minimal Haiku agent runs
+// ONLY the resolution glob and returns the path, so the existence decision is taken out of the review
+// agent's hands. Found → Codex runs in the BACKGROUND with file-poll. Not found → code-reviewer fallback.
+const PREFLIGHT_SCHEMA = {
+  type: 'object', required: ['codexScriptPath'], additionalProperties: false,
+  properties: { codexScriptPath: { type: 'string', description: 'absolute path to codex-companion.mjs, or "" if none' } },
+}
+let codexScriptPath = ''
+try {
+  const pf = await agent(
+    `Resolve the Codex companion script path. Run EXACTLY this one Bash command and nothing else:\n` +
+      "  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\n" +
+      `Return codexScriptPath = the trimmed stdout (a single absolute path), or "" if the command printed nothing. Do NOT run Codex, do NOT read any other file, do NOT reason about availability — just report the command's stdout.`,
+    { label: 'codex-preflight', phase: 'Discovery', model: 'haiku', schema: PREFLIGHT_SCHEMA }
+  )
+  codexScriptPath = (pf && typeof pf.codexScriptPath === 'string') ? pf.codexScriptPath.trim() : ''
+} catch (_) { codexScriptPath = '' }
+const codexResolved = /codex-companion\.mjs$/.test(codexScriptPath)
+log(codexResolved
+  ? `Codex companion resolved deterministically: ${codexScriptPath}`
+  : 'Codex companion NOT found (deterministic pre-flight) — primary code review via code-reviewer fallback.')
+
+const codexPrompt =
+  `Run a deep, cross-model code review over this wave's diff, following the review protocol summarized in ${protocolRef} (Phase 3.7). The code is already written and committed — find bugs, regressions, security issues, and quality problems.\n\n` +
+  `The Codex companion script is ALREADY CONFIRMED PRESENT at:\n  ${codexScriptPath}\n` +
+  `Launch it in the BACKGROUND and poll for completion — do NOT run it synchronously (a sync run would hit the Bash tool timeout):\n` +
+  `  • REVIEW_FILE=a unique /tmp file (e.g. /tmp/codexreview-wave-${cards[0].cardId}-$$.md)\n` +
+  `  • node "${codexScriptPath}" task "<your review instructions>" > "$REVIEW_FILE" 2>&1   — run this with run_in_background:true (the launching call returns immediately).\n` +
+  `  • Then POLL $REVIEW_FILE (BashOutput / repeated reads) until it holds a terminal result, up to a full 10-minute window.\n` +
+  `Return codexAvailable:false ONLY if $REVIEW_FILE ends up containing "CODEX_NOT_FOUND" or stays empty after the FULL 10-minute window — NEVER because a single Bash call returned slowly.\n\n` +
+  `${waveBrief}\n\n${baselineBrief}\n\n` +
+  `For each finding return: finding_id, title, severity (BLOCKER|HIGH|MEDIUM|LOW), confidence (0-100), evidence (exact file:line + code quote), minimal_fix_direction, and domain (doc|security|migration|code|perf|test). ` +
+  `Run the mandatory false-positive check on every finding and suppress the unconvincing ones (your findings are treated as already FP-validated). Set codexAvailable:true when the review ran.`
+
+const qaPrompt =
+  `Run MECHANICAL GATES ONLY over the wave scope, per ${protocolRef} (Phase 3.5 qa-sentinel contract): lint, type-check (when stack uses typescript), the full test suite, build, dependency audit, and markdownlint as applicable. You are a GATE RUNNER: do NOT read source for code findings, do NOT emit severities — return only a PASS/FAIL/SKIP gate table.\n\nWorktree: ${a.worktreePath || '(cwd)'} — cd into it first.\nChanged files:\n${unionScope.join('\n')}`
+
+function simplifyPrompt(c) {
+  return `Simplify analysis (read-only — you do NOT edit, the workflow applies fixes afterward) over ONE card's committed diff, per ${protocolRef} (Phase 2.55). Cover all THREE lenses and return findings:\n` +
+    `  • Reuse — newly written code that duplicates an existing util/helper; inline logic that could use existing code.\n` +
+    `  • Quality — redundant state, parameter sprawl, copy-paste with slight variation, leaky abstractions, stringly-typed code where enums exist, unnecessary JSX nesting, WHAT-comments / narration.\n` +
+    `  • Efficiency — redundant computation, duplicate API calls, N+1, missed concurrency, hot-path bloat, missing change-detection guards, unbounded structures.\n\n` +
+    `${cardScopeBrief(c)}\n\n${baselineBrief}\n\n` +
+    `Run a false-positive check on every finding and SUPPRESS the unconvincing ones (your surviving findings are treated as validated). Return findings with domain in {code, perf}. Flag only a finding you genuinely cannot resolve as confidence < 80.`
+}
+
+function securityPrompt(c) {
+  return `AppSec review (read-only) over ONE card's committed diff — auth, permissions, secrets, webhooks, file upload, infra, multi-tenant isolation, injection. Security-sensitive paths: ${highRisk.join(', ') || '(none configured)'}.\n\n${cardScopeBrief(c)}\n\n${baselineBrief}\n\n` +
+    `You OWN the security domain end-to-end: run the mandatory false-positive check on every finding yourself and SUPPRESS the unconvincing ones — your surviving findings are treated as validated and are NOT re-judged by another agent. Flag only a finding you genuinely cannot resolve as confidence < 80. Return findings with domain in {security, migration}.`
+}
+
+// Build the finder fan-out. Per-card: simplify (if runSimplify), security (if hasSecurityFiles).
+// Wave-wide: ONE Codex pass over the union, ONE qa-sentinel pass at full tier (else skipped → deferred).
+const findThunks = []
+for (const c of cards) {
+  if (c.runSimplify !== false) {
+    findThunks.push(() => agent(simplifyPrompt(c), { label: `simplify:${c.cardId}`, phase: 'Discovery', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'simplify', card: c, r })))
+  }
+  if (c.hasSecurityFiles === true) {
+    findThunks.push(() => agent(securityPrompt(c), { label: `security:${c.cardId}`, phase: 'Discovery', agentType: 'security-reviewer', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'security', card: c, r })))
+  }
+}
+if (codexResolved) {
+  findThunks.push(() => agent(codexPrompt, { label: 'codex', phase: 'Discovery', schema: CODEX_SCHEMA }).then((r) => ({ kind: 'codex', card: null, r })))
+}
+if (maxQaTier === 'full') {
+  findThunks.push(() => agent(qaPrompt, { label: 'qa-sentinel', phase: 'Discovery', agentType: 'qa-sentinel', schema: GATES_SCHEMA }).then((r) => ({ kind: 'qa', card: null, r })))
+} else {
+  log('Discovery: qa-sentinel SKIPPED (wave max tier ≤ light — full suite deferred to the Final FULL gate).')
+}
+
+const findResults = (await parallel(findThunks)).filter(Boolean)
+
+// ---- Fan-in: collect findings + Codex fallback branch -----------------------
+let raw = []
+let gateTable = []
+let codexEngine = codexResolved ? 'codex' : 'code-reviewer (fallback)'
+let codexRan = false
+for (const item of findResults) {
+  if (item.kind === 'codex') {
+    if (item.r && item.r.codexAvailable && Array.isArray(item.r.findings)) {
+      codexRan = true
+      raw.push(...item.r.findings.map((f) => ({ ...f, source: 'codex', preValidated: true })))
+    } else {
+      log('Discovery: Codex companion resolved but its review did not complete — falling back to code-reviewer.')
+    }
+  } else if (item.kind === 'qa') {
+    gateTable = (item.r && item.r.gates) || []
+  } else if (item.r && Array.isArray(item.r.findings)) {
+    // simplify / security own their lane and FP-check their OWN findings → already validated.
+    raw.push(...item.r.findings.map((f) => ({ ...f, source: item.kind, preValidated: true })))
+  }
+}
+
+// ONE deterministic fallback: pre-flight found no companion, or it ran but did not complete.
+if (!codexRan) {
+  codexEngine = 'code-reviewer (fallback)'
+  const fb = await agent(
+    `Codex was unavailable for this wave's code review. Run the FULL code review yourself over the wave diff, per ${protocolRef} (Phase 3.7).\n\n${waveBrief}\n\n${baselineBrief}\n\nReturn findings using the schema fields, with a self false-positive check applied (your findings are treated as validated).`,
+    { label: 'code-reviewer (fallback)', phase: 'Discovery', agentType: 'code-reviewer', schema: FINDINGS_SCHEMA }
+  )
+  if (fb && Array.isArray(fb.findings)) raw.push(...fb.findings.map((f) => ({ ...f, source: 'code-reviewer', preValidated: true })))
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Verify — specialist-owned validation (parity with new-final-review.js F.4)
+// ───────────────────────────────────────────────────────────────────────────
+phase('Verify')
+const classified = (await parallel(raw.map((f) => () => verifyFinding(f)))).filter(Boolean)
+
+function domainVerifier(domain) {
+  const d = String(domain || 'code').toLowerCase()
+  if (/doc|wiki|ssot|readme/.test(d)) return 'doc-reviewer'
+  if (/sec|auth|secret|rls|migrat|schema|ddl|\bsql\b/.test(d)) return 'security-reviewer'
+  if (/perf|cost|\bapi\b|data|latency|throughput|n\+1/.test(d)) return 'api-perf-cost-auditor'
+  if (/\btest|qa\b|spec|coverage/.test(d)) return 'qa-sentinel'
+  return 'code-reviewer'
+}
+
+async function verifyFinding(f) {
+  if (f.preValidated || (typeof f.confidence === 'number' && f.confidence >= 80)) {
+    return { ...f, classification: 'VERIFIED' }
+  }
+  const verifier = domainVerifier(f.domain)
+  if (verifier === f.source) {
+    // domain specialist IS the finder and already had its pass — a second instance adds no diversity.
+    return { ...f, classification: 'NEEDS_MANUAL_CONFIRMATION' }
+  }
+  const v = await agent(
+    `Adversarially validate this ${f.domain || 'code'} finding as the DOMAIN specialist over the cited file:line. Default to FALSE_POSITIVE if the evidence does not hold; use NEEDS_MANUAL_CONFIRMATION only when you genuinely cannot decide from the code.\n\n` +
+      `finding_id: ${f.finding_id}\nseverity: ${f.severity}\ntitle: ${f.title}\nevidence: ${f.evidence}\ndomain: ${f.domain}\nsecurity-sensitive paths: ${highRisk.join(', ') || '(none configured)'}`,
+    { label: `verify:${f.finding_id}`, phase: 'Verify', agentType: verifier, schema: VERDICT_SCHEMA }
+  )
+  return { ...f, classification: (v && v.classification) || 'NEEDS_MANUAL_CONFIRMATION' }
+}
+
+// Drop FALSE_POSITIVE; attribute each surviving finding to its card by file → card map.
+const fileToCard = buildFileToCard(cards)
+const surviving = classified
+  .filter((f) => f.classification !== 'FALSE_POSITIVE')
+  .map((f) => ({ ...f, card: attributeCard(f, fileToCard, cards) }))
+
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Fix — ONE coder applies all VERIFIED code/perf/security/simplify findings.
+//   doc findings → residual (the skill runs doc-reviewer post-E2E on final code).
+//   NEEDS_MANUAL_CONFIRMATION → residual (human gate, owned by the skill).
+// ───────────────────────────────────────────────────────────────────────────
+phase('Fix')
+const isDoc = (f) => /doc|wiki|ssot|readme/.test(String(f.domain).toLowerCase())
+const isManual = (f) => f.classification === 'NEEDS_MANUAL_CONFIRMATION'
+// Partition `surviving` (= VERIFIED + NEEDS_MANUAL; FALSE_POSITIVE already dropped) with NO overlap:
+//   actionable    = VERIFIED non-doc  → the coder fixes these.
+//   docResidual   = VERIFIED doc      → the skill runs doc-reviewer post-E2E on final code.
+//   manualResidual= NEEDS_MANUAL any  → human gate, owned by the skill (a doc-manual must NOT be
+//                   silently auto-re-reviewed: it carries its needs-manual classification out).
+const actionable = surviving.filter((f) => f.classification === 'VERIFIED' && !isDoc(f))
+const docResidual = surviving.filter((f) => f.classification === 'VERIFIED' && isDoc(f))
+const manualResidual = surviving.filter(isManual)
+
+const SKIP_CHECKS = { lint: 'SKIP', tsc: 'SKIP', build: 'SKIP' }
+let fixResult = { applied: [], unresolved: [], checks: { ...SKIP_CHECKS } }
+if (actionable.length && unionEditable.length) {
+  const fixBrief =
+    `Apply ALL of the verified review findings below to the worktree, then verify the build. You are the SINGLE fix pass for this wave.\n\n` +
+    `Worktree: ${a.worktreePath || '(cwd)'} — cd into it.\n` +
+    `You MAY edit ONLY these files (ownership map — touching anything else is a violation):\n${unionEditable.join('\n')}\n\n` +
+    `Findings to fix (grouped — fix the code, not the tests unless a test itself is wrong; do NOT expand scope beyond the finding):\n` +
+    actionable.map((f) => `- [${f.finding_id}] (${f.card || '?'} / ${f.domain} / ${f.severity}) ${f.title}\n    evidence: ${f.evidence}\n    direction: ${f.minimal_fix_direction}`).join('\n') +
+    `\n\nAfter applying: run \`npm run lint\` and (when the project uses typescript) \`npx tsc --noEmit\` and \`npm run build\` in the worktree. If a check fails because of an edit you made, fix the regression — at most 2 retries — staying within the allowed files. ` +
+    `Do NOT commit. Do NOT git stash (refs/stash is shared across worktrees). ` +
+    `Return: applied (finding_ids you fixed), unresolved (finding_ids you could NOT fix within the allowed files / 2 retries), and checks (PASS/FAIL/SKIP for lint, tsc, build).`
+  const r = await agent(fixBrief, { label: 'fix-coder', phase: 'Fix', agentType: 'coder', schema: FIX_SCHEMA })
+  // Normalize: the coder may die (null) or return a truthy object missing fields.
+  fixResult = (r && typeof r === 'object') ? r : { applied: [], unresolved: actionable.map((f) => f.finding_id), checks: { ...SKIP_CHECKS } }
+  if (!Array.isArray(fixResult.applied)) fixResult.applied = []
+  if (!Array.isArray(fixResult.unresolved)) fixResult.unresolved = []
+  if (!fixResult.checks || typeof fixResult.checks !== 'object') fixResult.checks = { ...SKIP_CHECKS }
+  log(`Fix: coder applied ${fixResult.applied.length}/${actionable.length} finding(s); checks lint=${fixResult.checks.lint} tsc=${fixResult.checks.tsc} build=${fixResult.checks.build}.`)
+} else if (actionable.length) {
+  // Actionable findings exist but NO editable files are mapped → cannot fix; return all as residual
+  // (no wasted coder spawn — the skill will route them to a targeted coder with a proper ownership scope).
+  fixResult = { applied: [], unresolved: actionable.map((f) => f.finding_id), checks: { ...SKIP_CHECKS } }
+  log(`Fix: ${actionable.length} actionable finding(s) but no editable files in scope — returned as residual (coder skipped).`)
+} else {
+  log('Fix: no actionable code/perf/security/simplify findings — coder skipped.')
+}
+
+// Unfixed actionable findings become residual (human/coder follow-up owned by the skill).
+const appliedIds = new Set((fixResult.applied || []).map((x) => x.finding_id))
+const unresolvedIds = new Set(fixResult.unresolved || [])
+const codeResidual = actionable.filter((f) => !appliedIds.has(f.finding_id) || unresolvedIds.has(f.finding_id))
+const checksFailed = ['lint', 'tsc', 'build'].some((k) => fixResult.checks && fixResult.checks[k] === 'FAIL')
+
+// ---- Assemble per-card result ----------------------------------------------
+function bucket(cardId) { return perCard[cardId] || (perCard[cardId] = { fixesApplied: [], residual: [] }) }
+for (const f of actionable) {
+  if (appliedIds.has(f.finding_id) && !unresolvedIds.has(f.finding_id)) {
+    bucket(f.card || cards[0].cardId).fixesApplied.push(`[${f.finding_id}] ${f.title}`)
+  }
+}
+for (const f of [...codeResidual, ...docResidual, ...manualResidual]) {
+  bucket(f.card || cards[0].cardId).residual.push(slimFinding(f))
+}
+
+const summary = makeSummary({
+  cards: cards.length,
+  totalFindings: raw.length,
+  verified: surviving.filter((f) => f.classification === 'VERIFIED').length,
+  falsePositive: classified.filter((f) => f.classification === 'FALSE_POSITIVE').length,
+  needsManual: manualResidual.length,
+  fixesApplied: appliedIds.size,
+  docResidual: docResidual.length,
+  codeResidual: codeResidual.length,
+  qaRan: maxQaTier === 'full',          // false ⇒ qa-sentinel deferred to the Final FULL gate (qa_first_attempt = n/a)
+  checksFailed,                          // post-fix lint/tsc/build (coder); distinct from the qa-sentinel gateTable
+  failingGates: gateTable.filter((g) => g.status === 'FAIL').map((g) => g.gate), // qa-sentinel FAIL gates (test/build/audit/markdownlint)
+  blockers: surviving.filter((f) => f.classification === 'VERIFIED' && f.severity === 'BLOCKER').length,
+  highs: surviving.filter((f) => f.classification === 'VERIFIED' && f.severity === 'HIGH').length,
+})
+log(`Wave review done: ${summary.fixesApplied} fixed, ${summary.codeResidual} code-residual, ${summary.docResidual} doc-residual, ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s)${checksFailed ? ', post-fix checks FAILED' : ''}. Engine: ${codexEngine}.`)
+
+return { codexEngine, perCard, gateTable, summary }
+
+// ---- helpers ----------------------------------------------------------------
+function asArr(x) { return Array.isArray(x) ? x.filter(Boolean) : [] }
+function dedupe(xs) { return Array.from(new Set(asArr(xs))) }
+function makeSummary(o) {
+  return Object.assign({ cards: 0, totalFindings: 0, verified: 0, falsePositive: 0, needsManual: 0, fixesApplied: 0, docResidual: 0, codeResidual: 0, qaRan: false, checksFailed: false, failingGates: [], blockers: 0, highs: 0 }, o || {})
+}
+function slimFinding(f) {
+  return { finding_id: f.finding_id, title: f.title, severity: f.severity, domain: f.domain, evidence: f.evidence, minimal_fix_direction: f.minimal_fix_direction, classification: f.classification, card: f.card }
+}
+function buildFileToCard(cs) {
+  const m = new Map()
+  for (const c of cs) for (const file of dedupe([...asArr(c.scopeFiles), ...asArr(c.editableFiles)])) if (!m.has(file)) m.set(file, c.cardId)
+  return m
+}
+function attributeCard(f, map, cs) {
+  const ev = String(f.evidence || '') + ' ' + String(f.minimal_fix_direction || '')
+  // longest known path that appears in the evidence AT A PATH BOUNDARY wins (most specific match).
+  // Boundary match avoids `components/Button` mis-matching inside `components/ButtonGroup.tsx`.
+  let best = null
+  for (const [file, cardId] of map.entries()) {
+    if (pathInText(file, ev) && (!best || file.length > best.len)) best = { cardId, len: file.length }
+  }
+  return best ? best.cardId : cs[0].cardId
+}
+function pathInText(file, text) {
+  if (!file) return false
+  const cont = /[A-Za-z0-9._/-]/ // a path-continuation char on either side ⇒ not a real boundary match
+  let i = text.indexOf(file)
+  while (i !== -1) {
+    const before = i === 0 ? '' : text[i - 1]
+    const after = i + file.length >= text.length ? '' : text[i + file.length]
+    if (!cont.test(before) && !cont.test(after)) return true
+    i = text.indexOf(file, i + 1)
+  }
+  return false
+}

package/framework/docs/WORKFLOWS.md

@@ -14,6 +14,7 @@ workflows are unavailable behaves exactly as before.
 | Workflow | Used by | What it does |
 | :--- | :--- | :--- |
 | `new-final-review` | `/new` Final Review (Step F.1.5) | Runs the read-only cross-batch review fan-out — architecture baseline + Codex ‖ doc-reviewer ‖ api-perf-cost-auditor ‖ qa-sentinel — then adversarially verifies low-confidence findings and returns them classified. Applies no fixes (the skill owns fix application + user gates). **v4.17.1+:** Codex availability is resolved by a **deterministic pre-flight glob + background poll** (no false negatives from a synchronous-run timeout); a **single-card batch** skips the duplicate doc/api reviewers (already run per-card), keeping only the cross-model Codex pass + qa gates. |
+| `new-card-review` (v4.34.0) | `/new` per-card review cluster — sequential (`review-cycle.md` § Phase 2.5x) **and** team-mode (`team-mode.md` D.1.6) | Hosts the **per-wave** review-cluster OUTSIDE the orchestrator context — the biggest prefix-growth source on long epics. Takes **1..N co-located cards** (1 = sequential per-card; N = a team-mode group, so it runs **once per wave, not per card**) and fans out the finders per card: Simplify + cross-model Codex (agent-launched binary, `code-reviewer` fallback) + qa-sentinel (group max tier) + security-reviewer (high-risk only), each specialist FP-checking its own findings. Then **ONE `coder` applies all VERIFIED code/perf/security/simplify findings in a single pass** (files disjoint by ownership) and re-verifies lint/tsc/build. Returns a compact `{perCard:{fixesApplied,residual}, gateTable, summary}` — the minority `residual` (doc, needs-manual, scope, unconverged) the skill resolves with the right specialist / user gate. **Doc-review and E2E stay in the skill** (doc is write-mode + must see final code; E2E is human-gated + nests a skill); **api-perf is deferred to the Final FULL gate**. Maps to `review-cycle.md` Phase 2.55+3.5+3.7. |
 | `new2` (v4.17.2) | `/new2` skill (the whole batch) | **EXPERIMENTAL A/B variant of `/new`.** Hosts the ENTIRE batch in the background runtime so subagent output never enters the main context. A **dependency-gated DAG scheduler** runs a card only when all in-batch deps are *committed* (and blocks transitive dependents of a failed dep instead of routing them to resolve); each card uses its **owner_agent** + a **specialized review fan-out** (not general-purpose); the worktree is kept **atomic per card** (rollback-to-HEAD on failure); transient API errors are retried and a sustained **outage degrades cleanly** (`degraded` return + durable resume via the skill); a **run ledger** dedups resolves and records accepted deferrals (no re-routing loop); the **merge is integrity-gated** (never force-DONE, never `git add` unreviewed code, never merge an incomplete/degraded batch); the commit step runs on **Haiku** while **follow-up cards are written by `prd-card-writer`**; telemetry carries real **cost** (`total_tokens` via `budget.spent()`, `agent_count`, skill-stamped `wall_clock_s`) + `degraded`. **v4.17.2:** the pre-flight **G3 cross-card Codex check is deterministic** (glob-first + background poll, skipped on single-card batches; `codex_resolved` in telemetry); a non-transient card crash is terminal-with-residual (no orphaned self-healing). Agents Read `/new`'s reference modules for semantics. |
 | `new2-resolve` (v4.17.2) | `new2` (self-healing) | Resolution pass for any gate that would otherwise need a human (`ac-unmet · blocker · qa-fail · e2e-blocked · merge-blocker · scope-expansion`). A **terminal short-circuit** skips the costly multi-attempt when the problem is impossible-by-definition (`out-of-ownership` verified in JS; other terminal reasons ratified by a judge); a **MANDATORY adversarial judge** cross-checks every `verified` claim — the judge independently greps the files and the workflow verifies **at least one** falls inside MAY-EDIT (`.some()`, so listing adjacent changed files is not mistaken for fabrication); accepts a **batched `findings` list** (one resolve per fix-area). **The domain is normalized** (freeform `documentation`→`doc`, …) before routing the **fixer** (doc→doc-reviewer, ui→ui-expert, security→security-reviewer, else coder) and judge, and a **doc finding gets doc-tree MAY-EDIT** (not the card's code scope); the 3-angle Tier-2 fan-out is reserved for code domains (single retry for doc/test). Follow-ups are written by **`prd-card-writer`**, offline-safe (deferred to the skill if no agent can write). |
 

package/package.json

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