baldart 4.31.1 → 4.32.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.32.0] - 2026-06-11
+
+**`new2`: `deep` is now relevance-gated too — it no longer fires all 5 reviewers on every card regardless of content.** Diagnosing a real batch (the FEAT-0023 supplier-associated-users epic — permissions/RLS/migrations, so 7 of 11 cards are legitimately `review_profile: deep` per `prd-card-writer` Rule C) exposed an **asymmetry**, not a misclassification: the per-card review matrix relevance-gated `balanced` (a specialist runs only if its domain is evidenced by `scopeFiles ∪ MAY-EDIT`) but left `deep` on an **unconditional 5-way fan-out** (`FULL_FANOUT` = code-reviewer + doc-reviewer + qa-sentinel + api-perf-cost-auditor + security-reviewer). So a `deep` card with no doc surface still paid for a doc-reviewer, and one with no API/data surface still paid for api-perf-cost-auditor — every time. This is exactly the "every card gets a full review regardless of what's inside" symptom.
+
+The fix unifies the review MODEL: **the profile controls review DEPTH, the surface controls review BREADTH.**
+- `deep` and `balanced` now share the same relevance-gated reviewer SET (extracted into `relevanceGated()`): `touchesCode` → code-reviewer + qa-sentinel; `touchesDocs` → doc-reviewer (the core finder on a doc-only card); `touchesApiData` → api-perf-cost-auditor; `securityRelevant` → security-reviewer.
+- `deep`'s extra DEPTH is unchanged and is carried downstream, NOT by the fan-out set: the full QA suite + Codex-full posture reach each spawned reviewer via `cardBrief`'s "Review profile" line, and the Phase-1 architect audit still keys on `reviewProfile === 'deep'` (`needAudit`). So the reviewers that DO run review at full depth — only the ones whose domain the card never touches are dropped.
+- **Fail-safe preserved**: `noEvidence` (empty `scopeFiles ∪ MAY-EDIT`) still falls back to `FULL_FANOUT` for BOTH balanced and deep — absence of evidence ≠ evidence of absence. `light`/`skip` unchanged. Batch-level coverage is unchanged: the Final Review's batch-wide doc + api/perf passes remain the safety nets, and `securityRelevant` (which a `deep` card almost always trips) keeps security-reviewer on genuinely sensitive cards.
+
+Not touched: `prd-card-writer` Rule C (it classifies correctly — `deep` for migration/RLS/permission/schema/HIGH-integration cards, `light` for pure-UI, `skip` for epic/doc — verified against the FEAT-0023 cards) and `/new`'s interactive prose path (which already scales per-card by profile + relevance — api-perf is deferred to the Final Review F.3, qa deferred at balanced, doc deferred at light-no-doc — so the unconditional-deep fan-out was unique to `new2.js`). **MINOR** (review-behavior change on the EXPERIMENTAL `new2` surface only; no config key — the schema-change propagation rule does not apply; no change to `/new`).
+
+### Changed
+
+- **`framework/.claude/workflows/new2.js`** — per-card review matrix (B7): the relevance gate now applies to `deep` as well as `balanced` via a shared `relevanceGated()` helper; the `reviewProfile === 'deep'` arm of the `FULL_FANOUT` branch is removed, leaving only `noEvidence` as the conservative full-fan-out fail-safe. The `review-matrix` ledger row's `→conservative-full` annotation now fires for any `noEvidence` profile (was `balanced`-only). Comment block updated to document the depth-vs-breadth model.
+
 ## [4.31.1] - 2026-06-11
 
 **`new2`: fix v4.31.0's dedup coverage + drop empty residuals + honest A/B cost — verified against the real FEAT-0022 telemetry/report (not the narrative).** Reading the actual run's `skill-runs.jsonl` + workflow report (instead of the prior turn's recollection) exposed three things v4.31.0 missed:

package/VERSION

@@ -1 +1 @@
-4.31.1
+4.32.0

package/framework/.claude/workflows/new2.js

@@ -578,15 +578,22 @@ async function runCard(cardId, cardPath) {
   // block routes through resolve(), whose mandatory adversarial judge (new2-resolve F-015, code domain
   // → code-reviewer) cross-checks the Codex finding before a fix/followup.
   const codexAvail = !!sharedCtx.codexResolved && !!sharedCtx.codexScriptPath
-  // B6 (v4.25.0) — deterministic per-card review matrix. `balanced` no longer means "every
-  // specialist on every card": each one runs IFF its domain is evidenced by the card's actual
-  // surface (scopeFiles ∪ MAY-EDIT), computed deterministically HERE in JS and audited via a
-  // `review-matrix` ledger row. `deep` keeps the unconditional full fan-out (Rule C assigns it
-  // to high-risk cards — respect the escalation). Coverage holds at batch level: the final
-  // review's doc pass stays the missing-doc-update safety net (its singleCard/slim skip is now
-  // gated on doc-reviewer having ACTUALLY run per-card — see Phase Final), and its api-perf
-  // pass keys on hasApiDataFiles with a regex this matrix supersets — so gating OFF a per-card
-  // specialist never leaves its domain unreviewed.
+  // B6 (v4.25.0) / B7 (v4.32.0) — deterministic per-card review matrix. A specialist runs IFF its
+  // domain is evidenced by the card's actual surface (scopeFiles ∪ MAY-EDIT), computed
+  // deterministically HERE in JS and audited via a `review-matrix` ledger row. Since v4.32.0 this
+  // relevance gate applies to `deep` TOO — `deep` no longer means an unconditional 5-way fan-out.
+  // The asymmetry it removed: `balanced` was surface-gated while `deep` paid for doc-reviewer on a
+  // card with no doc surface and api-perf-cost-auditor on a card with no API/data surface, every
+  // time. The REVIEW MODEL is now: the **profile controls review DEPTH** (deep → full QA suite +
+  // Codex full + the Phase-1 audit gate — all keyed on `reviewProfile` downstream and carried to
+  // each spawned reviewer via `cardBrief`'s "Review profile" line, so the depth of the reviewers
+  // that DO run is unchanged), and the **surface controls review BREADTH**. `noEvidence` (empty
+  // surface) stays the conservative full-fan-out fail-safe for BOTH balanced and deep — absence of
+  // evidence ≠ evidence of absence. Coverage holds at batch level: the final review's doc pass
+  // stays the missing-doc-update safety net (its singleCard/slim skip is gated on doc-reviewer
+  // having ACTUALLY run per-card — see Phase Final), and its api-perf pass keys on hasApiDataFiles
+  // with a regex this matrix supersets — so gating OFF a per-card specialist never leaves its
+  // domain unreviewed.
   const surface = dedupe((scopeFiles || []).concat(mayEdit || []))
   const docDirs = [paths.docs_dir, paths.references_dir, paths.wiki_dir, paths.prd_dir, paths.design_system].filter(Boolean)
   const isDocFile = (f) => /\.(md|mdx)$/i.test(String(f)) || docDirs.some((d) => String(f).includes(String(d)))
@@ -597,19 +604,23 @@ async function runCard(cardId, cardPath) {
   const touchesApiData = surface.some((f) => /api\/|data-model|\.sql$|migrations?\/|server|route|edge|middleware|cron|queue|worker|prisma|drizzle|supabase|schema/i.test(String(f)))
   const noEvidence = surface.length === 0 // fail-safe: absence of evidence ≠ evidence of absence
   const FULL_FANOUT = ['code-reviewer', 'doc-reviewer', 'qa-sentinel', 'api-perf-cost-auditor'].concat(securityRelevant ? ['security-reviewer'] : [])
+  // Relevance-gated BREADTH — shared by `balanced` AND `deep` (profile-gated DEPTH is carried
+  // downstream via cardBrief + needAudit, not by which specialists spawn).
+  const relevanceGated = () => {
+    const rs = []
+    if (touchesCode) rs.push('code-reviewer')
+    if (touchesDocs) rs.push('doc-reviewer') // doc-ONLY card: doc-reviewer IS the core finder
+    if (touchesCode) rs.push('qa-sentinel')  // skip for doc-only cards — no behavior to QA
+    if (touchesApiData) rs.push('api-perf-cost-auditor')
+    if (securityRelevant) rs.push('security-reviewer')
+    return rs
+  }
   let reviewers
   if (reviewProfile === 'skip') reviewers = []
   else if (reviewProfile === 'light') reviewers = codexAvail ? ['codex'] : ['code-reviewer']
-  else if (reviewProfile === 'deep' || noEvidence) reviewers = FULL_FANOUT
-  else { // balanced — relevance-gated
-    reviewers = []
-    if (touchesCode) reviewers.push('code-reviewer')
-    if (touchesDocs) reviewers.push('doc-reviewer') // doc-ONLY card: doc-reviewer IS the core finder
-    if (touchesCode) reviewers.push('qa-sentinel')  // skip for doc-only cards — no behavior to QA
-    if (touchesApiData) reviewers.push('api-perf-cost-auditor')
-    if (securityRelevant) reviewers.push('security-reviewer')
-  }
-  if (reviewProfile !== 'skip') g('review-matrix', 'PLANNED', `[${reviewProfile}${noEvidence && reviewProfile === 'balanced' ? '→conservative-full (no surface evidence)' : ''}] ${reviewers.join('+') || '(none)'} · docs:${touchesDocs} code:${touchesCode} api/data:${touchesApiData} sec:${securityRelevant}`)
+  else if (noEvidence) reviewers = FULL_FANOUT // balanced/deep, no surface evidence → conservative full
+  else reviewers = relevanceGated() // balanced AND deep — surface-gated breadth
+  if (reviewProfile !== 'skip') g('review-matrix', 'PLANNED', `[${reviewProfile}${noEvidence ? '→conservative-full (no surface evidence)' : ''}] ${reviewers.join('+') || '(none)'} · docs:${touchesDocs} code:${touchesCode} api/data:${touchesApiData} sec:${securityRelevant}`)
   const reviewSchema = { type: 'object', required: ['blocks', 'scopeExpansion'], additionalProperties: true,
     properties: { blocks: { type: 'array', items: { type: 'object', additionalProperties: true } }, scopeExpansion: { type: 'array', items: { type: 'object', additionalProperties: true } }, note: { type: 'string' } } }
   let reviewResults = []

package/package.json

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