baldart 4.24.3 → 4.26.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).
 
+## [4.26.0] - 2026-06-11
+
+**`new2`: Phase 1 decomposed into specialist agents — the owner implements, it no longer explores.** The old per-card pipeline gave the owner agent one mega-prompt ("you ARE claim + architect + plan-auditor + owner"), so the owner absorbed the whole codebase exploration into its own context and reached the actual coding with a degraded window. Phase 1 now runs as dedicated specialists with file handoff (`/tmp`), per the "ognuno fa una cosa" principle. Verified premise: nested subagent spawning does NOT exist in Claude Code (official docs: "Subagents cannot spawn other subagents" + 2 empirical probes), so the decomposition lives at the WORKFLOW level — the JS is the orchestrator, exactly what dynamic workflows are for. **MINOR** (pipeline capability on the EXPERIMENTAL `new2` surface only; no config key, no change to `/new`).
+
+### Changed
+
+- **`framework/.claude/workflows/new2.js` — per-card `codebase-architect` specialist (B7).** Context retrieval is now a dedicated `codebase-architect` spawn that writes the COMPLETE untruncated baseline to `/tmp/arch-baseline-<CARD>.md` (the owner and reviewers Read the file; the structured return stays minimal). Bonus over the old pre-flight snapshot: the per-card architect sees prior in-batch commits — card N's baseline reflects what cards 1..N-1 changed. The pre-flight no longer writes baselines (generalist relieved of specialist work; `archBaselinePaths` removed from its contract). **Fail-safe**: architect crash/not-ok degrades to the old inline behavior (the owner explores itself) — never blocks the card; transient outage re-queues it.
+- **`new2.js` — `plan-auditor` demoted to a deterministic DRIFT gate.** `/prd` already validates every card at creation time, so an unconditional re-audit per card was duplicate work. plan-auditor now runs ONLY when execution-time drift is plausible: (a) a prior in-batch commit touched the card's declared surface (`filesLikelyTouched` ∩ prior `filesChanged`, computed in JS), (b) the architect found declared paths missing (stale card — factual `missingPaths` check, no judgement), or (c) `review_profile: deep` (Rule C escalation). Its corrections amend the implementation BRIEFING (never the backlog YAML). A fresh single-card batch with no drift evidence skips it at zero cost. Crash → non-blocking skip, ledgered.
+- **`new2.js` — epic guard moved to JS (zero spawns for trackers).** The pre-flight returns `cardGraph[].isEpic` (implement.md §6b rule); an epic card now short-circuits in JS before ANY spawn — the old path burned a full owner-agent spawn just to learn the card was a tracker. The impl agent's own epic flag stays as backstop.
+- **`new2.js` telemetry — `per_card[].phase1`** records `{architect: done|inline-fallback, audit: pass|fixes|skipped-no-drift|skipped-error|skipped-no-baseline}` plus `phase1-architect`/`phase1-audit` ledger rows, so the A/B accounting can price the decomposition.
+
+## [4.25.0] - 2026-06-11
+
+**`new2`: deterministic per-card review matrix — `balanced` no longer spawns every specialist on every card.** The old fan-out ran code-reviewer + doc-reviewer + qa-sentinel + api-perf-cost-auditor (+ security-reviewer) unconditionally at `balanced`: an api-perf pass on a doc-only card, a doc pass on a pure-code card — 1–3 wasted spawns per card. Each specialist now runs IFF its domain is evidenced by the card's actual surface (`scopeFiles ∪ MAY-EDIT`), computed deterministically in JS (no agent judgement) and audited via a `review-matrix` ledger row per card. **MINOR** (review-behavior capability on the EXPERIMENTAL `new2` surface only; no config key, no change to `/new` — its interactive profiles are untouched; the schema-change propagation rule does not apply).
+
+### Changed
+
+- **`framework/.claude/workflows/new2.js` — relevance-gated `balanced` fan-out.** `touchesCode` → code-reviewer + qa-sentinel; `touchesDocs` (`.md`/`.mdx` or under `paths.docs_dir|references_dir|wiki_dir|prd_dir|design_system`) → doc-reviewer (on a doc-ONLY card it IS the core finder — code-reviewer and qa-sentinel are skipped); `touchesApiData` (superset of the final review's `hasApiDataFiles` regex) → api-perf-cost-auditor; the v4.24.2 `securityRelevant` gate → security-reviewer. Surface = `scopeFiles ∪ MAY-EDIT`, so a DoD-mandated doc the implementer FORGOT to edit still triggers doc-reviewer (it's in MAY-EDIT). **Fail-safes**: `deep` keeps the unconditional full fan-out (Rule C escalation is respected); an empty surface (no evidence) falls back to the full fan-out — absence of evidence is not evidence of absence. `light`/`skip` unchanged.
+- **`new2.js` Phase Final — the F-041 `singleCard`/slim skip is now coverage-gated.** The final review's doc pass is skipped for a single-card batch ONLY when doc-reviewer ACTUALLY ran per-card (`reviewersRun`); otherwise it runs as the missing-doc-update safety net — so gating a per-card specialist off never leaves its domain unreviewed at batch level. This also closes a **latent F-041 hole**: under `light`, doc-reviewer never ran per-card, yet the slim skip still suppressed the final doc pass for single-card batches.
+- **`new2.js` telemetry — `per_card[].reviewers`** records the gated matrix per card, so the A/B spawn accounting can measure exactly what the gating saves.
+
 ## [4.24.3] - 2026-06-10
 
 **`new2`: two follow-ups from the v4.24.2 logic review — epic closure no longer misses deferred cards, and the owner-gated classification reaches the final review.** Both are "parallel location" gaps of earlier fixes (the v4.17.2 meta-lesson): v4.22.1's epic-closure and v4.24.1's owner-gated deferral each missed one site. **PATCH** (bug-fix to the EXPERIMENTAL `new2` surface only; no config key, no change to `/new`).

package/VERSION

@@ -1 +1 @@
-4.24.3
+4.26.0

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

@@ -148,6 +148,10 @@ const PREFLIGHT_SCHEMA = {
           // spawn per card in runCard (always false on a fresh run).
           alreadyCommitted: { type: 'boolean', description: 'commit referencing the card exists in trunk..HEAD of the worktree AND validation re-runs green AND no open follow-up' },
           alreadyCommittedSha: { type: 'string' },
+          // B7 (v4.26.0) — epic guard moved to JS (an epic never reaches any spawn) + the
+          // card's declared surface, used by the deterministic plan-audit drift gate.
+          isEpic: { type: 'boolean', description: "epic/tracker card per implement.md §6b: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements" },
+          filesLikelyTouched: { type: 'array', items: { type: 'string' }, description: "the card's files_likely_touched, verbatim" },
           // F-016 — ACs whose only implementation file is outside the card MAY-EDIT,
           // pre-classified deferred-by-policy (never routed to resolve).
           policyDeferredACs: { type: 'array', items: { type: 'object', additionalProperties: true } },
@@ -156,6 +160,9 @@ const PREFLIGHT_SCHEMA = {
     },
     excluded: { type: 'array', items: { type: 'object', additionalProperties: true } },
     ownershipMapPath: { type: 'string' },
+    // B7 — archBaselinePaths removed: the per-card baseline is now written by the
+    // codebase-architect SPECIALIST in runCard (it also sees prior in-batch commits,
+    // which a pre-flight snapshot cannot), not by this generalist agent.
     crossCard: { type: 'string' },
     // G2 — deterministic Codex availability (glob-resolved, NOT a self-reported judgement),
     // so a false negative on the cross-card check is visible in telemetry. true=companion found.
@@ -164,7 +171,6 @@ const PREFLIGHT_SCHEMA = {
     // `light` card can run Codex as its finder. Empty string when codexResolved is false.
     codexScriptPath: { type: 'string' },
     workspaceNote: { type: 'string' },
-    archBaselinePaths: { type: 'array', items: { type: 'string' } },
   },
 }
 
@@ -220,11 +226,11 @@ try {
       g3Bullet +
       `• G4 card-field validation (setup.md 1b/1c): card missing requirements/acceptance_criteria/files_likely_touched → EXCLUDE (excluded[] + reason). Never HALT for one bad card.\n` +
       `• G5 depends-on: a card whose depends_on names a non-DONE card NOT in this batch → EXCLUDE it AND every in-batch card that transitively depends on it.\n` +
-      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha }.\n` +
+      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
       `• B1/F-026 idempotency (per card, AFTER the worktree exists): set alreadyCommitted:true (+ alreadyCommittedSha) IFF ALL hold: (a) a commit referencing the card id exists in ${TRUNK}..HEAD of the worktree; (b) the card's validation_commands re-run GREEN right now; (c) NO open follow-up card for it exists in ${paths.backlog_dir || 'backlog'}. On a FRESH worktree ${TRUNK}..HEAD is empty → all false, zero extra work.\n` +
       `• F-016 AC↔ownership consistency: for each acceptance_criterion, derive the file(s) it requires editing. If those files are NOT a subset of the card's MAY-EDIT/files_likely_touched → add the AC to policyDeferredACs:[{n,text,owningCard|owningFile,reason}] (it will become ONE follow-up, never a resolve). Do the same for any AC whose remedy is an owner-gated infra action (remote db push / deploy / secret / DNS).\n` +
       `• Ownership (setup.md 3c): build the file-ownership map → /tmp; return ownershipMapPath. F-040: each card's MAY-EDIT = files_likely_touched ∪ every path NAMED EXPLICITLY in that card's acceptance_criteria/definition_of_done (an ADR the DoD says to update, the data-model / ER doc for a schema-change, etc.) — so editing a DoD-mandated doc is NOT a file-diff violation. Do NOT add another card's files this way.\n` +
-      `• Persist per-card architecture baselines to /tmp/arch-baseline-<CARD>.md; return archBaselinePaths.\n\n` +
+      `• Do NOT write architecture baselines — the per-card codebase-architect specialist does that during the card pipeline (B7).\n\n` +
       `Return the structured PREFLIGHT object. ok:false ONLY if the workspace is unworkable.`,
     { label: 'preflight', phase: 'Pre-flight', agentType: 'general-purpose', schema: PREFLIGHT_SCHEMA }
   )
@@ -267,7 +273,6 @@ const sharedCtx = {
   worktreePath: preflight.worktreePath,
   branch: preflight.branch,
   ownershipMapPath: preflight.ownershipMapPath,
-  archBaselinePaths: preflight.archBaselinePaths || [],
   // v4.18.0 — per-card Codex-light finder needs the resolved companion path in runCard scope.
   codexResolved: !!preflight.codexResolved,
   codexScriptPath: preflight.codexScriptPath || '',
@@ -390,6 +395,11 @@ async function runCard(cardId, cardPath) {
   const deferredClasses = new Set(deferredOpen ? ['policy-deferred-ac'] : [])
   function g(name, decision, detail) { gates.push({ gate: name, decision, detail: detail || '' }); ledger(cardId, name, decision, detail) }
 
+  // B7 — epic guard in JS (pre-flight reads the YAML): an epic is a tracker, not implementable
+  // work — skip it BEFORE any spawn (the old path burned a full owner-agent spawn to learn it).
+  // The impl agent's own epic flag stays as backstop for a pre-flight false negative.
+  if (node.isEpic) { g('router', 'EPIC-SKIPPED', 'epic card (pre-flight, zero spawns)'); return { card: cardId, status: 'epic-skipped', gates, commit: '-' } }
+
   // F-026/B1 — skip-completed from the PRE-FLIGHT's git-authoritative probe (cardGraph[].
   // alreadyCommitted), not a per-card agent spawn: on a fresh run the old Haiku probe was N
   // guaranteed-false spawns, and on resume the journal cache already covers it. Keyed on the
@@ -399,14 +409,70 @@ async function runCard(cardId, cardPath) {
     return { card: cardId, status: 'committed', commit: node.alreadyCommittedSha || '-', filesChanged: [], scopeFiles: [], archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, gates }
   }
 
-  const cardBrief = `${projectBrief}\n\nCard: ${cardId}\nCard YAML: ${cardPath}\nOwner agent: ${ownerAgent} · Review profile: ${reviewProfile}\nWorktree: ${sharedCtx.worktreePath} (cd into it)\nFile-ownership map: ${sharedCtx.ownershipMapPath}\nArch baseline (write to /tmp/arch-baseline-${cardId}.md): reuse if present.\nNOTE: ACs already pre-classified as policy-deferred MUST NOT be implemented or routed — they are tracked as follow-ups.`
+  const cardBrief = `${projectBrief}\n\nCard: ${cardId}\nCard YAML: ${cardPath}\nOwner agent: ${ownerAgent} · Review profile: ${reviewProfile}\nWorktree: ${sharedCtx.worktreePath} (cd into it)\nFile-ownership map: ${sharedCtx.ownershipMapPath}\nNOTE: ACs already pre-classified as policy-deferred MUST NOT be implemented or routed — they are tracked as follow-ups.`
 
-  // --- Phase 1+2: dispatch the card's OWNER_AGENT (F-024), not general-purpose. ---
+  // --- Phase 1 (B7, v4.26.0) — SPECIALIST decomposition: each Phase-1 duty runs as its own
+  // agent ("ognuno fa una cosa"), with handoff via /tmp files so the owner's context stays
+  // clean of exploration noise. The old single mega-prompt ("you ARE claim+architect+
+  // plan-auditor+owner") made the owner absorb the whole exploration into its context.
+  const baselinePath = `/tmp/arch-baseline-${cardId}.md`
+  const phase1 = { architect: 'inline-fallback', audit: 'skipped-no-drift' }
+  let arch = null
+  try {
+    arch = await agentSafe(
+      `You are the Phase-1 context retriever for card ${cardId} (per ${REF}/implement.md Phase 1 step 3 / 5b). cd into the worktree ${sharedCtx.worktreePath}.\n\n${cardBrief}\n\n` +
+        `Explore the codebase exactly as your system prompt mandates for this card's scope (requirements + files_likely_touched: ${JSON.stringify(node.filesLikelyTouched || [])}). Write your COMPLETE untruncated findings (file paths, type signatures, patterns, high-risk paths) to ${baselinePath} — refresh it if a stale copy exists. The owner agent and the per-card reviewers will Read that file; keep your structured return MINIMAL.\n\n` +
+        `Also report missingPaths: every path in files_likely_touched that does NOT exist in the worktree (factual ls/test check — no judgement). Return: { ok, missingPaths:[...], note }`,
+      { label: `architect:${cardId}`, phase: 'Implement', agentType: 'codebase-architect',
+        schema: { type: 'object', required: ['ok'], additionalProperties: true, properties: { ok: { type: 'boolean' }, missingPaths: { type: 'array', items: { type: 'string' } }, note: { type: 'string' } } } }
+    )
+    if (arch && arch.ok) { phase1.architect = 'done'; g('phase1-architect', 'DONE', `baseline → ${baselinePath}${(arch.missingPaths || []).length ? ' · missing: ' + arch.missingPaths.join(', ') : ''}`) }
+    else g('phase1-architect', 'FALLBACK-INLINE', (arch && arch.note) || 'architect returned not-ok — owner explores inline')
+  } catch (e) {
+    if (e && e.transientExhausted) { noteDegraded('outage'); return { card: cardId, status: 'pending', gates } }
+    g('phase1-architect', 'FALLBACK-INLINE', `architect crashed (${String(e && e.message)}) — owner explores inline`)
+  }
+  const architectOk = phase1.architect === 'done'
+
+  // B7 — plan-auditor as a DETERMINISTIC DRIFT GATE, not an unconditional duplicate of the
+  // validation /prd already ran at card-creation time. It runs ONLY when execution-time drift
+  // is plausible: (a) a prior in-batch commit touched this card's declared surface (the
+  // strongest signal — the codebase moved under the card), (b) the architect found declared
+  // paths missing (stale card), or (c) review_profile 'deep' (Rule C escalation). Fresh
+  // single-card batches with no drift evidence skip it — /prd's validation stands.
+  const flt = (node.filesLikelyTouched || []).map(String)
+  const priorTouched = perCardResults.filter((r) => r.status === 'committed').flatMap((r) => r.filesChanged || [])
+  const inBatchOverlap = flt.length && priorTouched.some((f) => flt.some((c) => String(f).includes(c) || c.includes(String(f))))
+  const needAudit = reviewProfile === 'deep' || inBatchOverlap || (architectOk && (arch.missingPaths || []).length > 0)
+  let auditCorrections = []
+  if (needAudit && architectOk) {
+    try {
+      const audit = await agentSafe(
+        `Audit card ${cardId} for EXECUTION-TIME DRIFT per ${REF}/implement.md Phase 1 step 4 (you are plan-auditor; the card was already validated by /prd at creation time — your job is what changed SINCE). cd into ${sharedCtx.worktreePath}.\n\n${cardBrief}\nArchitecture baseline (Read it): ${baselinePath}\nDrift signals: ${inBatchOverlap ? 'prior in-batch commits touched this card surface; ' : ''}${(arch.missingPaths || []).length ? 'missing declared paths: ' + arch.missingPaths.join(', ') : ''}\n\n` +
+          `Check ONLY: (1) paths in files_likely_touched still exist; (2) type/field references in the requirements still correct per the baseline; (3) [ASSUMED] items now answerable from the code. Return PASS or the exact corrections — corrections amend the IMPLEMENTATION BRIEFING, never the backlog YAML.\n\nReturn: { verdict, corrections:[strings] }`,
+        { label: `plan-audit:${cardId}`, phase: 'Implement', agentType: 'plan-auditor',
+          schema: { type: 'object', required: ['verdict'], additionalProperties: true, properties: { verdict: { enum: ['PASS', 'FIXES_NEEDED'] }, corrections: { type: 'array', items: { type: 'string' } } } } }
+      )
+      auditCorrections = (audit && audit.corrections) || []
+      phase1.audit = audit && audit.verdict === 'FIXES_NEEDED' ? 'fixes' : 'pass'
+      g('phase1-audit', phase1.audit === 'fixes' ? 'FIXES-APPLIED-TO-BRIEF' : 'PASS', `drift gate (${reviewProfile === 'deep' ? 'deep' : inBatchOverlap ? 'in-batch overlap' : 'missing paths'})${auditCorrections.length ? ' · ' + auditCorrections.length + ' corrections' : ''}`)
+    } catch (e) {
+      if (e && e.transientExhausted) { noteDegraded('outage'); return { card: cardId, status: 'pending', gates } }
+      phase1.audit = 'skipped-error'
+      g('phase1-audit', 'SKIPPED', `auditor crashed (${String(e && e.message)}) — proceeding without audit (non-blocking)`)
+    }
+  } else if (needAudit && !architectOk) { phase1.audit = 'skipped-no-baseline'; g('phase1-audit', 'SKIPPED', 'drift signaled but no baseline — owner re-derives context inline') }
+  else g('phase1-audit', 'SKIPPED', 'no drift evidence — /prd creation-time validation stands')
+
+  // --- Phase 2: dispatch the card's OWNER_AGENT (F-024), not general-purpose. ---
+  const phase1Brief = architectOk
+    ? `Phase 1 already ran as specialist agents. READ the architecture baseline at ${baselinePath} BEFORE writing any code — it is your codebase context; do NOT redo the exploration.${auditCorrections.length ? `\nPlan-audit corrections (apply them as amendments to this briefing — do NOT modify the backlog YAML):\n${auditCorrections.map((c, i) => `  ${i + 1}. ${c}`).join('\n')}` : ''}`
+    : `Phase 1 fallback: the architect specialist was unavailable — do the Phase 1 claim+architect exploration yourself per ${REF}/implement.md and persist the baseline to ${baselinePath} before coding.`
   let impl
   try {
     impl = await agentSafe(
-      `Implement card ${cardId} per ${REF}/implement.md (Phase 1 claim+architect+plan-auditor, Phase 2 you ARE the owner_agent '${ownerAgent}') and ${REF}/completeness.md (Phase 2.5 + 2.5b AC-closure ledger). Run all gates/bash yourself.\n\n${cardBrief}\n\n` +
-        `POLICIES: G26 Phase-2 lint/tsc/test/build failing after the module's retry cap → buildBlocked:true + blockedGate. Build the AC Closure Ledger (one row per AC: implemented|unmet|policy-deferred). DO NOT silently defer; report unmet rows (excluding policy-deferred). Persist arch baseline to /tmp/arch-baseline-${cardId}.md and the diff to /tmp/diff-${cardId}.txt.\n\n` +
+      `Implement card ${cardId} per ${REF}/implement.md Phase 2 — you ARE the owner_agent '${ownerAgent}' — and ${REF}/completeness.md (Phase 2.5 + 2.5b AC-closure ledger). Run all gates/bash yourself.\n\n${phase1Brief}\n\n${cardBrief}\n\n` +
+        `POLICIES: G26 Phase-2 lint/tsc/test/build failing after the module's retry cap → buildBlocked:true + blockedGate. Build the AC Closure Ledger (one row per AC: implemented|unmet|policy-deferred). DO NOT silently defer; report unmet rows (excluding policy-deferred). Persist the diff to /tmp/diff-${cardId}.txt.\n\n` +
         `E4 OWNERSHIP RECONCILE (implement.md §11b — do this BEFORE returning): the card's MAY-EDIT includes files_likely_touched ∪ paths NAMED EXPLICITLY in this card's acceptance_criteria/definition_of_done (e.g. an ADR the DoD says to update, the data-model / ER doc for a schema change). Editing THOSE is in-scope. For any OTHER dirty file outside MAY-EDIT (another card's file, or unrelated): \`git checkout -- <file>\` to revert it (NEVER leave it orphaned), list it in revertedOutOfOwnership. Set fileDiffViolation:true ONLY if such an edit genuinely could not be reverted (then say why in note) — it is no longer a silent label.\n\n` +
         `Return: { epic, buildBlocked, blockedGate, unmetACs:[{n,text}], scopeFiles, mayEditPaths, revertedOutOfOwnership:[paths], fileDiffViolation, note }`,
       { label: `implement:${cardId}`, phase: 'Implement', agentType: ownerAgent,
@@ -460,12 +526,40 @@ async function runCard(cardId, cardPath) {
   // v4.18.0 — at `light`, Codex is the SOLE finder (cost-shift off Claude); `code-reviewer` is the
   // fallback when the companion is unavailable. The FP-gate equivalent is preserved downstream: any
   // 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. `balanced`/`deep` unchanged.
+  // → code-reviewer) cross-checks the Codex finding before a fix/followup.
   const codexAvail = !!sharedCtx.codexResolved && !!sharedCtx.codexScriptPath
-  const reviewers = reviewProfile === 'skip' ? []
-    : reviewProfile === 'light' ? (codexAvail ? ['codex'] : ['code-reviewer'])
-    : ['code-reviewer', 'doc-reviewer', 'qa-sentinel', 'api-perf-cost-auditor'].concat(
-        securityRelevant ? ['security-reviewer'] : [])
+  // 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.
+  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)))
+  const touchesDocs = surface.some(isDocFile)
+  const touchesCode = surface.some((f) => !isDocFile(f))
+  // superset of new-final-review's hasApiDataFiles regex — per-card coverage may exceed the
+  // final pass, never lag it.
+  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'] : [])
+  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}`)
   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 = []
@@ -535,7 +629,7 @@ async function runCard(cardId, cardPath) {
     for (const sx of grp) g('scope-expansion', s === 'resolved' ? 'INTEGRATED' : 'FOLLOWUP', sx.evidence || '')
   }
 
-  if (cardBlocked) { await rollbackCard(cardId, mayEdit); return { card: cardId, status: 'followup', gates, commit: '-', scopeFiles, archBaselinePath: `/tmp/arch-baseline-${cardId}.md` } }
+  if (cardBlocked) { await rollbackCard(cardId, mayEdit); return { card: cardId, status: 'followup', gates, commit: '-', scopeFiles, reviewersRun: reviewers, archBaselinePath: `/tmp/arch-baseline-${cardId}.md` } }
 
   // --- Phase 4 — commit (F-023: Haiku + git-status reconcile, never git add -A). ---
   // F-040/H — DONE policy. A card with an OPEN owner-gated/policy-deferred AC commits its code but
@@ -578,6 +672,11 @@ async function runCard(cardId, cardPath) {
     // (A3): an 'unresolved' class means the DoD is genuinely unmet → the card stays IN_PROGRESS.
     deferred: deferredOpen,
     deferredClasses: Array.from(deferredClasses),
+    // B6 — which reviewers ACTUALLY ran (the gated matrix); Phase Final keys its slim/skip
+    // decision on this, and per_card telemetry records it for the A/B spawn accounting.
+    reviewersRun: reviewers,
+    // B7 — Phase-1 specialist record (architect: done|inline-fallback; audit: pass|fixes|skipped-*).
+    phase1,
     scopeFiles, archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, gates,
   }
 }
@@ -675,9 +774,15 @@ if (committed.length && !degraded) {
       firstCardId: firstCard, worktreePath: sharedCtx.worktreePath, baseBranch: TRUNK,
       cardPaths: committed.map((r) => pathById[r.card]).filter(Boolean),
       reviewScopeFiles, archBaselinePaths: allArch, hasApiDataFiles, config: cfg,
-      // F-041 — single-card batch: doc-reviewer + api-perf already ran per-card and there is
-      // NO cross-card conflict to find. Keep only the cross-model Codex pass + qa gates.
-      singleCard: committed.length === 1,
+      // F-041 + B6 — slim the final pass (skip its doc-reviewer) ONLY when doc-reviewer
+      // ACTUALLY ran per-card for this single card. The old unconditional `length === 1` was
+      // built on the premise "doc + api-perf already ran per-card" — false under the gated
+      // review matrix (and it was ALREADY false under `light`, a latent F-041 coverage hole
+      // this closes). When per-card doc review was gated off, the final doc pass is the
+      // missing-doc-update safety net and must run even for a single card. api-perf at the
+      // final pass is independently gated by hasApiDataFiles (regex the per-card matrix
+      // supersets), so its coverage is consistent either way.
+      singleCard: committed.length === 1 && ((committed[0].reviewersRun || []).includes('doc-reviewer')),
     })
   } catch (e) { if (e && isTransient(e)) noteDegraded('outage'); final = null }
 
@@ -840,7 +945,7 @@ function buildTelemetry() {
     // cost — total_tokens via budget.spent() delta; agent_count via counter; wall_clock_s stamped by the SKILL.
     total_tokens: totalTokens,
     agent_count: agentCount,
-    per_card: perCardResults.map((r) => ({ card: r.card, status: r.status, deferred: !!r.deferred, deferredClasses: r.deferredClasses || [], gates: (r.gates || []).length })),
+    per_card: perCardResults.map((r) => ({ card: r.card, status: r.status, deferred: !!r.deferred, deferredClasses: r.deferredClasses || [], reviewers: r.reviewersRun || [], phase1: r.phase1 || null, gates: (r.gates || []).length })),
     stats_requested: !!FLAGS.stats,
   }
 }

package/package.json

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