baldart 4.17.0 → 4.17.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.17.1] - 2026-06-08
+
+**`new2` post-refactor: tre falle di routing/detection emerse al secondo run reale (card FEAT-0019-followup).** Dopo l'hardening v4.17.0, gli agent principali sono correttamente specializzati, ma il *resolve* e il *final review* mostravano tre errori di instradamento. **PATCH** (bugfix di orchestrazione nei workflow `new2-resolve`/`new-final-review`; nessuna nuova capability, nessun cambio layout, **nessuna chiave `baldart.config.yml`** → schema-propagation N/A).
+
+> **Why.** Tutti e tre i bug condividono la stessa radice: una decisione che dovrebbe essere **deterministica** (quale agent per quale dominio / esiste Codex) era affidata o a una mappa incompleta o al self-report soft di un subagent. Il dominio freeform `documentation` non matchava la chiave `doc`, il companion Codex (installato e funzionante) veniva dichiarato assente per un timeout di una Bash-call sincrona, e le follow-up card nascevano da un Haiku general-purpose anziché dal loro owner.
+
+### Fixed
+
+- **`framework/.claude/workflows/new2-resolve.js` — routing per dominio robusto (F-038/F-024).** Le review agent emettono `domain` come **stringa libera** (`documentation`, `frontend`, …); la mappa fixer keyava solo su `doc`/`ui`, così `documentation` cadeva sul costoso `coder` (Opus) per un finding di pura documentazione. Aggiunto `normDomain()` che normalizza ai bucket di routing (`doc|ui|security|migration|perf|test|code`) **prima** di scegliere fixer e judge, e mappa fixer estesa (`doc→doc-reviewer`, `ui→ui-expert`, `security→security-reviewer`, resto→`coder`) — reviewer-owns-its-domain anche in fase di *apply*, non solo di *judge*.
+- **`framework/.claude/workflows/new2-resolve.js` — follow-up card via `prd-card-writer` (F-039).** La materializzazione della follow-up usava `general-purpose` + Haiku scrivendo uno stub YAML minimale; ora delega all'agent **`prd-card-writer`** (owner del `card-template`, Rule C per `review_profile`, `owner_agent`, traceability) — le card di follow-up rispettano le stesse regole SSOT di quelle native.
+- **`framework/.claude/workflows/new-final-review.js` — detection Codex deterministica + background (F-040).** Codex risultava "non disponibile" pur essendo installato e funzionante: il workflow delegava l'intera invocazione a un subagent generico che la eseguiva **in modo sincrono** dentro una Bash-call e auto-dichiarava `codexAvailable` — un run reale di Codex (minuti) superava il timeout della call → falso negativo → fallback a `code-reviewer`. Ora un **pre-flight deterministico** (un Haiku risolve SOLO il glob del companion e ritorna il path: la decisione di esistenza è tolta al review agent), poi Codex gira in **background con poll su file** e finestra 10 min (allineato a `references/final-review.md` F.3/F.4); `codexAvailable:false` è ammesso solo per `CODEX_NOT_FOUND` reale o file vuoto a fine timeout. Un **unico** fallback deterministico a `code-reviewer` copre sia "companion assente" sia "run non completato".
+- **`new2.js` + `new-final-review.js` — final review snella per batch mono-card (F-041).** Un batch da 1 sola card eseguiva la batch final review **per intero** (`doc-reviewer` + `api-perf-cost-auditor` + `qa-sentinel`), **duplicando** la review per-card (Phase 3) che aveva già girato gli stessi agent sugli stessi file — e senza alcun conflitto cross-card da trovare (~300k token ripetuti su un run reale da 1,28M). Ora `new2.js` passa `singleCard: committed.length === 1`; con quel flag la final review tiene **solo** il passaggio cross-model Codex (valore unico: modello diverso → bug diversi) + i gate `qa-sentinel` (letti dall'integrity gate di merge), e salta i duplicati Claude. Batch multi-card invariati.
+- **`new2.js` + `new2-resolve.js` — fan-out Tier-2 inutile su finding doc (F-038/F-033/F-036).** Un singolo merge-blocker doc-domain già **risolto al Tier-1 e confermato dal judge** (`best:1`) faceva comunque partire **3 `doc-reviewer` paralleli (~150k token)** — con rischio di follow-up spuria per un problema già chiuso. Tre cause composte, tutte corrette: **(A)** la resolve riceveva come MAY-EDIT i file di **codice** della card (`reviewScopeFiles`), così il fixer doc editava `docs/` "fuori ownership" — ora `domainMayEdit()` dà ai finding doc la loro territory reale (`docs_dir`/`references_dir`/`wiki_dir`/`prd_dir`); **(B)** la guardia anti-fabbricazione del judge usava `.every()` (rigetto se *anche un solo* file confermato cade fuori MAY-EDIT) — ma il judge lista naturalmente i file adiacenti (il codice che una doc descrive); ora `someInScope()` (`.some()`) rigetta solo un verdetto che non conferma **nessun** file di proprietà (phantom puro); **(C)** il fan-out a 3 angoli (`root-cause`/`call-site`/`reuse-utility`) è code-bug-shaped → per domini deterministici non-code (doc/test) ora un **singolo** retry mirato invece di 3.
+
 ## [4.17.0] - 2026-06-07
 
 **`new2` hardening single-wave: 36 finding dal primo run reale risolti in un colpo.** Il primo run reale di `new2` (batch FEAT-0021, 9 card) sotto un outage 529 prolungato è costato **7.4M token / 100 agent / 5h08m producendo solo 6/9 card reali**, con 2 stati `DONE` falsi nel backlog, codice security RLS-bypass non revisionato finito su `develop` via un "safety commit", e 1 follow-up persa. Una raccolta diagnostica end-to-end (36 finding verificati su codice + telemetria reale) ha isolato cause **strutturali**; questo rilascio le risolve tutte in un'unica wave, riportando il costo atteso a ~1.5-2.5M e — prioritario — azzerando le violazioni di integrità/sicurezza sotto degradazione. **MINOR** (cambio sostanziale di capacità del workflow esperimentale `new2`; nessuna rimozione/cambio layout d'install; **nessuna nuova chiave `baldart.config.yml`** → schema-propagation N/A).

package/VERSION

@@ -1 +1 @@
-4.17.0
+4.17.1

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

@@ -116,11 +116,40 @@ if (baselinePaths.length) {
 // ───────────────────────────────────────────────────────────────────────────
 phase('Review')
 
+// F-040 — DETERMINISTIC Codex pre-flight (fixes the false-negative where Codex is
+// installed+working but the review subagent reported codexAvailable:false because a
+// synchronous inline run hit its Bash timeout). The workflow sandbox has no Bash, so a
+// minimal Haiku agent runs ONLY the resolution glob and returns the path — the existence
+// decision is thus taken OUT of the review agent's hands. Found → Codex runs in the
+// BACKGROUND with file-poll (canonical final-review.md F.3/F.4). Not found → straight to
+// the code-reviewer fallback, no wasted Codex agent.
+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: 'Review', 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 review via code-reviewer fallback.')
+
 const codexPrompt =
   `Run a deep, cross-model code review over this batch diff, following the /codexreview protocol summarized in ${protocolRef} (Step F.3). The code is already written and committed — find bugs, regressions, security issues, and quality problems.\n\n` +
-  `Resolve and invoke the Codex companion (a non-Anthropic frontier model) via Bash:\n` +
-  "  CODEX_SCRIPT=\"$(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" +
-  `If no companion script is found, OR the review does not complete, return { "codexAvailable": false, "findings": [] } — do NOT fabricate findings.\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 and is the exact bug this design fixes):\n` +
+  `  • REVIEW_FILE=a unique /tmp file (e.g. /tmp/codexreview-batch-${a.firstCardId || 'batch'}-$$.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. The script's existence is already verified, so a premature false here is a bug, not a capability gap.\n\n` +
   `${scopeBrief}\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.`
@@ -134,16 +163,29 @@ const apiPrompt =
 const qaPrompt =
   `Run MECHANICAL GATES ONLY over the batch scope, per ${protocolRef} Step F.3 (qa-sentinel row): lint, type-check, the full test suite, build, dependency audit, and markdownlint as applicable to this project. Do NOT read source for code findings, do NOT emit severities — return only a PASS/FAIL/SKIP gate table.\n\nWorktree: ${a.worktreePath || '(cwd)'}\nChanged files:\n${scope.join('\n')}`
 
+// F-041 — single-card batch: the per-card review (Phase 3) already ran doc-reviewer +
+// api-perf-cost-auditor over these exact files, and a 1-card batch has NO cross-card
+// conflict to surface. Keep ONLY the cross-model Codex pass (its unique value — a different
+// model finds different bugs) + qa-sentinel gates; skip the Claude-agent duplicates.
+const slim = a.singleCard === true
+// qa-sentinel always runs — the merge integrity gate reads its PASS/FAIL table.
 const reviewThunks = [
-  () => agent(codexPrompt, { label: 'codex', phase: 'Review', schema: CODEX_SCHEMA }).then((r) => ({ kind: 'codex', r })),
-  () => agent(docPrompt, { label: 'doc-reviewer', phase: 'Review', agentType: 'doc-reviewer', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'doc', r })),
   () => agent(qaPrompt, { label: 'qa-sentinel', phase: 'Review', agentType: 'qa-sentinel', schema: GATES_SCHEMA }).then((r) => ({ kind: 'qa', r })),
 ]
-// api-perf-cost-auditor is skipped when the batch touches no API/data files (F.3 note).
-if (a.hasApiDataFiles !== false) {
+if (!slim) {
+  reviewThunks.unshift(() => agent(docPrompt, { label: 'doc-reviewer', phase: 'Review', agentType: 'doc-reviewer', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'doc', r })))
+}
+// Codex thunk runs ONLY when the pre-flight resolved the companion (else: no wasted agent).
+if (codexResolved) {
+  reviewThunks.unshift(() => agent(codexPrompt, { label: 'codex', phase: 'Review', schema: CODEX_SCHEMA }).then((r) => ({ kind: 'codex', r })))
+}
+// api-perf-cost-auditor: skipped when no API/data files OR on a slim single-card pass.
+if (!slim && a.hasApiDataFiles !== false) {
   reviewThunks.push(() => agent(apiPrompt, { label: 'api-perf-cost-auditor', phase: 'Review', agentType: 'api-perf-cost-auditor', schema: FINDINGS_SCHEMA }).then((r) => ({ kind: 'api', r })))
 } else {
-  log('Review: api-perf-cost-auditor skipped (no API/data files in scope).')
+  log(slim
+    ? 'Review: single-card batch — doc-reviewer + api-perf skipped (already run per-card); kept cross-model Codex + qa gates.'
+    : 'Review: api-perf-cost-auditor skipped (no API/data files in scope).')
 }
 
 const reviewResults = (await parallel(reviewThunks)).filter(Boolean)
@@ -151,20 +193,16 @@ const reviewResults = (await parallel(reviewThunks)).filter(Boolean)
 // ---- Fan-in (F.4 step 9): collect findings + Codex fallback branch ----------
 let raw = []
 let gateTable = []
-let codexEngine = 'codex'
+let codexEngine = codexResolved ? 'codex' : 'code-reviewer (fallback)'
+let codexRan = false
 for (const item of reviewResults) {
   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 {
-      // CODEX_NOT_FOUND / TIMED_OUT → Claude code-reviewer fallback (F.4 step 8).
-      codexEngine = 'code-reviewer (fallback)'
-      log('Review: Codex unavailable — falling back to code-reviewer for the primary code review.')
-      const fb = await agent(
-        `Codex was unavailable for the batch final review. Run the FULL code review yourself over the batch diff, per ${protocolRef} Step F.3.\n\n${scopeBrief}\n\n${baselineBrief}\n\nReturn findings using the schema fields, with a self false-positive check applied.`,
-        { label: 'code-reviewer (fallback)', phase: 'Review', agentType: 'code-reviewer', schema: FINDINGS_SCHEMA }
-      )
-      if (fb && Array.isArray(fb.findings)) raw.push(...fb.findings.map((f) => ({ ...f, source: 'code-reviewer', preValidated: false })))
+      // Resolved but the run itself failed (CODEX_NOT_FOUND written / empty after timeout).
+      log('Review: 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) || []
@@ -173,6 +211,17 @@ for (const item of reviewResults) {
   }
 }
 
+// F-040 — ONE deterministic fallback: either the pre-flight found no companion, or it ran
+// but did not complete. Either way the primary code review must still happen (F.4 step 8).
+if (!codexRan) {
+  codexEngine = 'code-reviewer (fallback)'
+  const fb = await agent(
+    `Codex was unavailable for the batch final review. Run the FULL code review yourself over the batch diff, per ${protocolRef} Step F.3.\n\n${scopeBrief}\n\n${baselineBrief}\n\nReturn findings using the schema fields, with a self false-positive check applied.`,
+    { label: 'code-reviewer (fallback)', phase: 'Review', agentType: 'code-reviewer', schema: FINDINGS_SCHEMA }
+  )
+  if (fb && Array.isArray(fb.findings)) raw.push(...fb.findings.map((f) => ({ ...f, source: 'code-reviewer', preValidated: false })))
+}
+
 // ───────────────────────────────────────────────────────────────────────────
 // Phase Verify (F.4) — adversarial validation of low-confidence findings
 //   Codex findings are pre-FP-validated → VERIFIED. Claude-agent findings with

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

@@ -25,7 +25,20 @@ const evidence = a.evidence || ''
 const worktree = a.worktreePath || '(cwd)'
 const mayEdit = Array.isArray(a.mayEditPaths) ? a.mayEditPaths : []
 const scopeFiles = Array.isArray(a.scopeFiles) ? a.scopeFiles : []
-const domain = a.domain || 'code'
+// F-038 — review agents emit FREEFORM domain strings (e.g. 'documentation', 'frontend').
+// Normalize to the routing buckets the fixer/judge maps key on, so a doc finding never
+// falls through to the costly `coder` (the v4.17.0 'documentation'→coder regression).
+function normDomain(d) {
+  const s = String(d || 'code').toLowerCase()
+  if (/doc|wiki|ssot|readme/.test(s)) return 'doc'
+  if (/ui|frontend|front-end|design|css|visual|component/.test(s)) return 'ui'
+  if (/sec|auth|secret|rls|tenant|xss|csrf|injection/.test(s)) return 'security'
+  if (/migrat|schema|ddl|\bsql\b/.test(s)) return 'migration'
+  if (/perf|cost|n\+1|latency|throughput/.test(s)) return 'perf'
+  if (/\btest|qa\b|spec|coverage/.test(s)) return 'test'
+  return 'code'
+}
+const domain = normDomain(a.domain || 'code')
 const findings = Array.isArray(a.findings) && a.findings.length ? a.findings : [{ kind, evidence, domain }]
 const REF = (a.refModulesBase || '.claude/skills/new/references').replace(/\/$/, '')
 const cfg = a.config || {}
@@ -81,8 +94,9 @@ const FOLLOWUP_SCHEMA = {
   properties: { created: { type: 'boolean' }, followupCard: { type: 'string' }, note: { type: 'string' } },
 }
 
-// F-024 — domain-specialized fixer + judge (full map, not just doc|coder).
-const fixerAgent = ({ doc: 'doc-reviewer', ui: 'ui-expert' })[domain] || 'coder'
+// F-024 — domain-specialized fixer + judge (full map; reviewer-owns-its-domain — a doc
+// finding is fixed by doc-reviewer, a security finding by security-reviewer, never coder).
+const fixerAgent = ({ doc: 'doc-reviewer', ui: 'ui-expert', security: 'security-reviewer' })[domain] || 'coder'
 const judgeAgent = (domain === 'security' || domain === 'migration') ? 'security-reviewer' : domain === 'perf' ? 'api-perf-cost-auditor' : 'code-reviewer'
 
 const findingsBlock = findings.map((f, i) => `  ${i + 1}. [${f.kind || kind}/${f.domain || domain}] ${f.evidence}`).join('\n')
@@ -105,6 +119,15 @@ function filesInScope(files) {
   if (!mayEdit.length) return false
   return files.every((f) => mayEdit.some((m) => String(f).includes(m) || m.includes(String(f))))
 }
+// F-033 — fabrication guard for the judge cross-check: a REAL fix touched AT LEAST ONE
+// owned file. The judge naturally also lists adjacent changed files (e.g. the code a doc
+// describes) — that is NOT fabrication, so `.every()` here over-rejected a sound fix and
+// forced a wasted Tier-2 fan-out. `.some()` rejects only a verdict that confirmed ZERO
+// owned files (pure phantom).
+function someInScope(files) {
+  if (!Array.isArray(files) || !files.length || !mayEdit.length) return false
+  return files.some((f) => mayEdit.some((m) => String(f).includes(m) || m.includes(String(f))))
+}
 function collectOOS(...attemptObjs) {
   const out = []
   for (const o of attemptObjs) for (const x of (o && o.outOfScopeFindings) || []) out.push(x)
@@ -209,10 +232,16 @@ const canFanOut = (typeof budget === 'undefined' || !budget.total || budget.rema
 let tier2OOS = []
 if (canFanOut && !protectedDomain) {
   phase('Repair')
-  const angles = [
+  // F-036 — the 3-angle fan-out (root-cause / call-site / reuse-utility) is code-bug-shaped.
+  // For deterministic non-code domains (doc/test) it is 3× waste — a single targeted retry
+  // is enough. Reserve the fan-out for code/perf/ui where the angles genuinely diverge.
+  const codeShaped = !/^(doc|test)$/.test(domain)
+  const angles = codeShaped ? [
     'Fix at the root cause (change the underlying logic/contract).',
     'Fix defensively at the call site (guard/validate without changing the contract).',
     'Fix by reusing an existing utility/pattern instead of new code.',
+  ] : [
+    'Apply the single correct fix — the residual is deterministic: re-derive the exact change and apply it.',
   ]
   const tries = (await parallel(angles.map((angle, i) => () =>
     agentSafe(
@@ -249,8 +278,8 @@ async function judgeVerify(verifiedAttempts) {
   } catch (e) { if (e && e.transientExhausted) return { ok: false, best: 0 }; throw e }
   if (!judge || !(judge.best > 0)) return { ok: false, best: 0 }
   // Deterministic JS cross-check: the judge-confirmed files must be within MAY-EDIT.
-  if (mayEdit.length && Array.isArray(judge.verifiedFiles) && judge.verifiedFiles.length && !filesInScope(judge.verifiedFiles)) {
-    log('judge verifiedFiles fall outside MAY-EDIT — rejecting (possible fabrication).')
+  if (mayEdit.length && Array.isArray(judge.verifiedFiles) && judge.verifiedFiles.length && !someInScope(judge.verifiedFiles)) {
+    log('judge verifiedFiles are ENTIRELY outside MAY-EDIT — rejecting (possible fabrication).')
     return { ok: false, best: 0 }
   }
   return { ok: true, best: judge.best }
@@ -259,11 +288,12 @@ async function judgeVerify(verifiedAttempts) {
 async function materialiseFollowup(k, reason, oos) {
   let r = null
   try {
-    // F-023 — mechanical YAML write → Haiku.
+    // F-039 — backlog cards are owned by prd-card-writer (card-template + Rule C
+    // review_profile + owner_agent + traceability), NOT a hand-written Haiku stub.
     r = await agentSafe(
-      `Materialise a follow-up backlog card so this residual is TRACKED, not dropped (per ${REF}/completeness.md Phase 2.5b option 3). MECHANICAL — do not re-read large modules.\n\n${brief}\nKind: ${k}\nReason unresolved: ${reason}\n\n` +
-        `Create ${backlogDir}/${card}-followup-<gate>.yml: status: TODO + MINIMUM valid fields (requirements ≥1 from the residual, acceptance_criteria ≥1 = verbatim residual, files_likely_touched ≥1 from the card ownership / remedy files). MUST pass the /new pre-flight field check. Return the created card id.`,
-      { label: `resolve:followup:${card}`, phase: 'Verify', agentType: 'general-purpose', model: 'haiku', schema: FOLLOWUP_SCHEMA }
+      `Create ONE follow-up backlog card so this residual is TRACKED, not dropped (per ${REF}/completeness.md Phase 2.5b option 3). You are prd-card-writer: apply your card-template, Rule C (review_profile), owner_agent routing, and traceability rules — do NOT emit a minimal stub.\n\n${brief}\nKind: ${k}\nResidual domain: ${domain}\nReason unresolved: ${reason}\n\n` +
+        `Write ${backlogDir}/${card}-followup-<gate>.yml with status: TODO, derived from the residual: requirements + acceptance_criteria (the verbatim residual as ≥1 AC), owner_agent routed to the residual domain (${domain}), review_profile per Rule C, files_likely_touched ≥1 from the card ownership / remedy files. It MUST pass the /new pre-flight field check. Return the created card id.`,
+      { label: `resolve:followup:${card}`, phase: 'Verify', agentType: 'prd-card-writer', schema: FOLLOWUP_SCHEMA }
     )
   } catch (e) {
     // F-020 — could not materialise (e.g. outage): return WITHOUT a followupCard so the

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

@@ -234,6 +234,18 @@ cardIds.forEach((id, i) => { pathById[id] = cardPaths[i] || `${paths.backlog_dir
 // new2-resolve bridge — dedup (F-009) + accepted-deferral skip (F-028) + group batching (F-007).
 // `findings` is a list; a single residual is a list of 1 (retro-compat). Returns 'resolved'|'followup'|'fatal'.
 // ───────────────────────────────────────────────────────────────────────────
+// F-038 — doc-domain findings are fixed in the doc tree, NOT the card's code MAY-EDIT.
+// Passing code-only ownership made the doc fixer edit docs/ "out of scope" and the JS
+// fabrication cross-check reject a correct, judge-approved fix → a wasted Tier-2 fan-out
+// (~150k tok) and a risk of a bogus follow-up for an already-resolved finding. Give doc
+// findings their real owner territory.
+function isDocDomain(d) { return /doc|wiki|ssot|readme/i.test(String(d || '')) }
+function domainMayEdit(dom, codeScope) {
+  if (!isDocDomain(dom)) return codeScope
+  const docPaths = [paths.docs_dir, paths.references_dir, paths.wiki_dir, paths.prd_dir].filter(Boolean)
+  return docPaths.length ? docPaths : codeScope // doc-only ownership; fall back to code scope if no doc paths configured
+}
+
 async function resolve(kind, card, evidence, extra) {
   const s = sig(card, kind, evidence)
   if (resolvedSignatures.has(s) || acceptedDeferrals.has(s)) {
@@ -241,15 +253,16 @@ async function resolve(kind, card, evidence, extra) {
     return 'resolved'
   }
   resolvedSignatures.add(s)
+  const dom = (extra && extra.domain) || 'code'
   let res
   try {
     res = await workflow('new2-resolve', {
       kind, cardId: card, evidence,
-      findings: (extra && extra.findings) || [{ kind, evidence, domain: (extra && extra.domain) || 'code' }],
+      findings: (extra && extra.findings) || [{ kind, evidence, domain: dom }],
       worktreePath: sharedCtx.worktreePath,
-      mayEditPaths: (extra && extra.mayEditPaths) || [],
+      mayEditPaths: domainMayEdit(dom, (extra && extra.mayEditPaths) || []),
       scopeFiles: (extra && extra.scopeFiles) || [],
-      domain: (extra && extra.domain) || 'code',
+      domain: dom,
       refModulesBase: REF, config: cfg, ts: TS,
     })
   } catch (e) {
@@ -503,6 +516,9 @@ if (committed.length && !batchFatal && !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,
     })
   } catch (e) { if (e && isTransient(e)) noteDegraded('outage'); final = null }
 

package/package.json

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