baldart 4.17.0 → 4.17.2

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.17.2] - 2026-06-08
+
+**`new2` hardening: 7 lacune latenti chiuse da una revisione adversariale dell'intero workflow.** Dopo i fix di v4.17.1 (nati da run reali), una revisione olistica di `new2` (orchestratore + resolve + final-review + skill) ha isolato 7 lacune non ancora emerse nei run ma reali alla lettura del codice — validate di persona scartando i falsi positivi (l'integrity gate di merge è corretto; lo skill "prose-only" è by-design). **PATCH** (hardening dei workflow `new2`/`new2-resolve` + skill/doc; nessuna nuova capability/layout, **nessuna chiave `baldart.config.yml`** → schema-propagation N/A).
+
+### Fixed
+
+- **G1 — `new2-resolve.js`: rimossi gli handler self-healing orfani (`agent-crash`, `baseline-fail`).** `new2.js` non vi instradava MAI (un crash → `crashResult` marca `failed` + residual; un baseline fail → `batchFatal`). Erano codice morto irraggiungibile: `runCard` va in crash PRIMA della fase commit, quindi un eventuale `resolved` non potrebbe comunque committare/mergiare. Il path residual (lo skill materializza la follow-up) è la SSOT; commento esplicativo in `crashResult`.
+- **G2 — `new2.js`: detection Codex G3 cross-card deterministica + skip mono-card.** Il check Codex del pre-flight usava ancora il **soft self-report** che v4.17.1 aveva corretto solo nella final review (stesso falso negativo, per batch multi-card). Ora il bullet G3 risolve PRIMA il glob del companion (esistenza decisa dal glob, non dal giudizio dell'agent), gira Codex in **background con poll**, e vieta un `CODEX_NOT_FOUND` prematuro; su batch **mono-card** il check è saltato del tutto (niente cross-card). Nuovo `codexResolved` nello schema pre-flight + ledger `G3-codex` + campo telemetria `codex_resolved` → un falso negativo è ora visibile.
+- **G3 — `new2.js`: niente silent drop dei finding merge-artifact.** Il filtro F-035 scartava i finding "esiste già nel worktree" con solo un ledger SKIP; un regex lasco poteva far sparire un BLOCKER reale. Ora ogni finding scartato diventa anche un `residuals` (`merge-artifact-skipped`, `materialized:false`) → tracciato, nulla perso.
+- **G4 — `new2/SKILL.md`: materializzazione follow-up offline-safe via `prd-card-writer`.** Il fallback dello skill scriveva uno stub minimale, incoerente col fix #2 (F-039, workflow → prd-card-writer). Ora lo Step 5.1 delega a `prd-card-writer` (card-template, Rule C, owner_agent, traceability), con stub minimale solo come ultima risorsa in outage totale.
+- **G5 — `new2.js`: routing `security-reviewer` non solo da `scopeFiles`.** Una card di sicurezza con file non-matchanti saltava la security review quando `high_risk_modules` non è configurato. Ora il trigger considera anche l'`owner_agent` della card e il suo brief (titolo/requirements), oltre allo scope.
+- **G6 — classificatore di dominio doc allineato.** `isDocDomain` (new2.js) e la branch `doc` di `normDomain` (new2-resolve.js) ora portano un commento di sincronizzazione reciproca (stessi token `doc|wiki|ssot|readme`) per prevenire drift.
+- **G7 — sync documentazione.** `WORKFLOWS.md` (righe `new-final-review`/`new2`/`new2-resolve`) e `new2/SKILL.md` allineati al comportamento v4.17.1/v4.17.2 (doc routing, prd-card-writer followup, Codex deterministico, final review snella mono-card, rimozione handler orfani).
+
+## [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.2

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

@@ -128,10 +128,15 @@ returns when the batch is done. It returns:
 
 1. **Materialise missing follow-ups (offline-safe — you have filesystem access, the
    workflow does not).** For every `residuals[]` entry with `materialized:false`,
-   write a follow-up card `${paths.backlog_dir}/<card>-followup-<kind>.yml` (status:
-   TODO; ≥1 requirement derived from the residual; acceptance_criteria = the verbatim
-   residual; files_likely_touched from the card's ownership) — it MUST pass the `/new`
-   pre-flight field check. This is the layer that guarantees **nothing is ever
+   create a follow-up card `${paths.backlog_dir}/<card>-followup-<kind>.yml` (status:
+   TODO). **Delegate the write to the `prd-card-writer` agent** — the same owner the
+   workflow uses (card-template, Rule C `review_profile`, `owner_agent` routed to the
+   residual's domain, traceability) — derived from the residual (≥1 requirement;
+   `acceptance_criteria` = the verbatim residual; `files_likely_touched` from the card's
+   ownership). Do NOT hand-write a minimal stub — the offline path must match the
+   agent-path quality (F-039). It MUST pass the `/new` pre-flight field check. If
+   `prd-card-writer` itself is unavailable (total outage), fall back to a minimal valid
+   stub so the card still exists. This is the layer that guarantees **nothing is ever
    dropped, even when every agent was dead** during the run.
 2. **Resume if degraded.** If `degraded` is true, re-invoke the workflow with
    `Workflow({ scriptPath, resumeFromRunId })` (same `args` + the new `ts`). The

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

@@ -1,7 +1,7 @@
 export const meta = {
   name: 'new2-resolve',
   description:
-    "Self-healing resolution pass for the autonomous new2 batch workflow. Called by new2 whenever a deterministic gate would otherwise need a human: a card fail/blocker (ac-unmet | blocker | qa-fail | e2e-blocked | merge-blocker), a legitimate scope-EXPANDING finding (scope-expansion), or a cross-cutting edge (agent-crash | baseline-fail). Tier-1 targeted fix with a TERMINAL short-circuit (skips the costly multi-attempt when the problem is impossible-by-definition, verified not trusted), then a judged multi-attempt; a MANDATORY adversarial judge cross-checks every verified claim against the real diff (prevents fabricated success). Specialized per domain (doc→doc-reviewer, ui→ui-expert, security→security-reviewer judge, perf→api-perf-cost-auditor judge). Terminal is a tracked follow-up. Accepts a `findings` list (batched per area). Uses agent()/parallel() only — no nested workflows.",
+    "Self-healing resolution pass for the autonomous new2 batch workflow. Called by new2 whenever a deterministic gate would otherwise need a human: a card fail/blocker (ac-unmet | blocker | qa-fail | e2e-blocked | merge-blocker) or a legitimate scope-EXPANDING finding (scope-expansion). Tier-1 targeted fix with a TERMINAL short-circuit (skips the costly multi-attempt when the problem is impossible-by-definition, verified not trusted), then a judged multi-attempt; a MANDATORY adversarial judge cross-checks every verified claim against the real diff (prevents fabricated success). Specialized per domain (doc→doc-reviewer, ui→ui-expert, security→security-reviewer judge, perf→api-perf-cost-auditor judge). Terminal is a tracked follow-up. Accepts a `findings` list (batched per area). Uses agent()/parallel() only — no nested workflows.",
   phases: [
     { title: 'Diagnose', detail: 'classify + terminal short-circuit + scope-expansion boundary' },
     { title: 'Repair', detail: 'targeted fix, then judged multi-attempt if needed' },
@@ -25,7 +25,22 @@ 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).
+// G6: the doc token set below MUST stay in sync with isDocDomain() in new2.js (which picks
+// the doc MAY-EDIT) — drift would route a finding to doc-reviewer but with code ownership.
+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 +96,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 +121,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)
@@ -113,18 +138,10 @@ function collectOOS(...attemptObjs) {
 
 phase('Diagnose')
 
-// ---- baseline-fail (E2): try to make the trunk build; fatal if irrecoverable ---
-if (kind === 'baseline-fail') {
-  let r = null
-  try {
-    r = await agentSafe(
-      `The batch worktree's BASELINE build fails (trunk may not build). Try to make it build per ${REF}/setup.md step 6a.\n\n${brief}\n\nFix tractable build errors (missing dep, stale lock, trivial type error). Re-run tsc+lint+build. verified:true only if the baseline now passes; else verified:false.`,
-      { label: `resolve:baseline:${card}`, phase: 'Diagnose', agentType: 'coder', schema: FIX_SCHEMA }
-    )
-  } catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during baseline repair', outOfScopeFindings: [] } ; throw e }
-  if (r && r.verified) { log('baseline recovered.'); return { status: 'resolved', outOfScopeFindings: collectOOS(r) } }
-  return { status: 'fatal', reason: 'baseline build irrecoverable' }
-}
+// NOTE: new2.js never routes 'baseline-fail' (→ batchFatal at pre-flight) nor 'agent-crash'
+// (→ crashResult marks the card 'failed' + residual) here — a crash happens BEFORE runCard's
+// commit phase, so a 'resolved' verdict could never be committed/merged. Those self-healing
+// branches were removed (v4.17.2 G1) as unreachable dead code; the residual path is the SSOT.
 
 // ---- scope-expansion (Asse 2): deterministic boundary ---
 if (kind === 'scope-expansion') {
@@ -144,19 +161,6 @@ if (kind === 'scope-expansion') {
   return await materialiseFollowup('scope-expansion', (decide && decide.note) || 'outside ownership / new AC / protected', collectOOS(decide))
 }
 
-// ---- agent-crash (E1) ---
-if (kind === 'agent-crash') {
-  let r = null
-  try {
-    r = await agentSafe(
-      `A subagent crashed. Re-attempt with the CORRECT specialist (${fixerAgent}) per ${REF}/commit.md § Sub-agent failure protocol.\n\n${brief}\n\nRetry once. ${protectedDomain ? 'PROTECTED domain: if you cannot complete it, verified:false — NEVER inline-bypass.' : ''} Re-verify the gate; verified:true only if done.`,
-      { label: `resolve:crash:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
-    )
-  } catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during crash recovery', outOfScopeFindings: [] }; throw e }
-  if (r && r.verified) { const ok = await judgeVerify([{ i: 1, r }]); if (ok.ok) return { status: 'resolved', outOfScopeFindings: collectOOS(r) } }
-  return await materialiseFollowup('agent-crash', 'subagent crash unrecovered' + (protectedDomain ? ' (protected — not bypassed)' : ''), collectOOS(r))
-}
-
 // ───────────────────────────────────────────────────────────────────────────
 // Asse 1 — Tier-1 (with terminal short-circuit) → judged multi-attempt → follow-up.
 // ───────────────────────────────────────────────────────────────────────────
@@ -209,10 +213,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 +259,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 +269,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

@@ -144,6 +144,9 @@ const PREFLIGHT_SCHEMA = {
     excluded: { type: 'array', items: { type: 'object', additionalProperties: true } },
     ownershipMapPath: { type: 'string' },
     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.
+    codexResolved: { type: 'boolean' },
     workspaceNote: { type: 'string' },
     archBaselinePaths: { type: 'array', items: { type: 'string' } },
   },
@@ -173,6 +176,14 @@ const projectBrief = [
 // ───────────────────────────────────────────────────────────────────────────
 // Phase Pre-flight — ONE ops agent runs all git-heavy work + returns the dep graph.
 // ───────────────────────────────────────────────────────────────────────────
+// G2 — Codex cross-card grounding. SKIP entirely on a single-card batch (nothing
+// cross-card to find). For multi-card, make the availability DETERMINISTIC: resolve the
+// companion glob FIRST (existence taken out of the agent's judgement), run it in the
+// BACKGROUND with a file poll, and forbid a premature CODEX_NOT_FOUND — same discipline as
+// new-final-review.js, fixing the parallel false-negative the v4.17.1 fix #3 left here.
+const g3Bullet = cardIds.length < 2
+  ? `• G3 cross-card grounding: SKIPPED — only one runnable card, nothing cross-card exists. Set crossCard='N/A-single-card' and codexResolved:false (not probed).\n`
+  : `• G3 cross-card grounding (setup.md 3d), MULTI-card: FIRST resolve the Codex companion deterministically — run \`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\` and set codexResolved:true IFF it prints a path (existence is glob-decided, NOT your judgement; ALWAYS return codexResolved). If resolved, run the cross-card conflict check by launching \`node "$CODEX" task "<cross-card conflict questions: FILE_CONFLICT/IMPLICIT_DEP/ORDER_RISK/STATE_MUTATION>" > "$FILE" 2>&1\` in the BACKGROUND (run_in_background:true) and POLL "$FILE" to completion (full window). Read the audit ONLY via the [codex]-stripping filter; return DISTILLED findings. Fall to code-reviewer / set crossCard='CAPABILITY_UNAVAILABLE' ONLY when the glob is EMPTY, or it resolved but "$FILE" held CODEX_NOT_FOUND / stayed empty after the FULL window — NEVER because a single synchronous Bash call returned slowly. Provenance-skip still applies (same-provenance cards → nothing cross-card). If conflicts FOUND you MUST APPLY them: FILE_CONFLICT/ORDER_RISK → force the cards SEQUENTIAL and encode it in dependsOn (the conflicting later card dependsOn the earlier).\n`
 phase('Pre-flight')
 let preflight = null
 try {
@@ -183,7 +194,7 @@ try {
       `DETERMINISTIC GATE POLICIES (NO user prompts):\n` +
       `• G1 dirty-tree (main repo ${MAIN}): partition framework-managed noise exactly as setup.md step 3 ($METRICS=${METRICS}, .baldart/generated|state.json|skill-conflicts.json — NOT overlays/). Genuine user work → auto-stash 'baldart-new2-${firstCard}' (main checkout) and record the label. Never commit/abort/prompt.\n` +
       `• Worktree (setup.md step 4): create ONE code worktree off ${TRUNK}; install deps; assign a port; run the baseline (tsc+lint+build). Copy ONLY the artifacts needed (env/.env.local/.env.example/supabase/.temp) — do NOT bulk-copy untracked files from the main repo (avoids stray backlog cards in the worktree). Use the git-authoritative idempotency pre-check. E2: baseline FAILS → fix once; still failing → baseline:'fail' + baselineLog (batch-fatal).\n` +
-      `• G3 cross-card grounding (setup.md 3d): run the Codex cross-card check (provenance skip; CODEX_NOT_FOUND → code-reviewer; both unavailable → crossCard='CAPABILITY_UNAVAILABLE'). Read the audit ONLY via the [codex]-stripping filter; return DISTILLED findings. If conflicts FOUND you MUST APPLY them: FILE_CONFLICT/ORDER_RISK → force the cards SEQUENTIAL and encode it in dependsOn (the conflicting later card dependsOn the earlier).\n` +
+      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 }.\n` +
@@ -206,6 +217,8 @@ if (!preflight || preflight.ok === false || preflight.baseline === 'fail') {
 for (const ex of preflight.excluded || []) ledger(ex.card, 'preflight-exclude', 'EXCLUDED', ex.reason)
 if (preflight.workspaceNote) ledger(firstCard, 'G1/G2-workspace', 'AUTO', preflight.workspaceNote)
 if (preflight.crossCard) ledger(firstCard, 'G3-cross-card', 'INFO', preflight.crossCard)
+// G2 — surface the deterministic Codex availability (false negative now visible in telemetry).
+if (cardIds.length >= 2) ledger(firstCard, 'G3-codex', preflight.codexResolved ? 'CODEX' : 'FALLBACK', preflight.codexResolved ? 'companion glob-resolved' : 'companion not found → code-reviewer')
 
 const runnableCards = preflight.cards || []
 const cardGraph = preflight.cardGraph || []
@@ -234,6 +247,20 @@ 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.
+// G6 — token set MUST stay in sync with the doc branch of normDomain() in new2-resolve.js;
+// drift would route a finding to doc-reviewer there but pass code ownership from here.
+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 +268,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) {
@@ -350,10 +378,15 @@ async function runCard(cardId, cardPath, lessons) {
   }
 
   // --- Review fan-out (F-024/F-025): specialized agents, trimmed by review_profile. ---
+  // G5 — scopeFiles tokens alone miss a security card whose files don't carry them. Also
+  // trigger security-reviewer on the card's owner_agent and its brief (title/requirements).
+  const securityRelevant = highRisk.length
+    || ownerAgent === 'security-reviewer'
+    || /auth|security|secret|migration|rls/i.test(`${scopeFiles.join(' ')} ${cardBrief}`)
   const reviewers = reviewProfile === 'skip' ? []
     : reviewProfile === 'light' ? ['code-reviewer']
     : ['code-reviewer', 'doc-reviewer', 'qa-sentinel', 'api-perf-cost-auditor'].concat(
-        (highRisk.length || /auth|security|secret|migration|rls/i.test(scopeFiles.join(' '))) ? ['security-reviewer'] : [])
+        securityRelevant ? ['security-reviewer'] : [])
   let reviewResults = []
   try {
     reviewResults = (await parallel(reviewers.map((ra) => () => agentSafe(
@@ -503,6 +536,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 }
 
@@ -512,7 +548,12 @@ if (committed.length && !batchFatal && !degraded) {
     const all = (final.findings || []).filter((f) => (f.classification === 'VERIFIED' || f.classification === 'NEEDS_MANUAL_CONFIRMATION') && (f.severity === 'BLOCKER' || f.severity === 'HIGH'))
     // F-035 — drop merge-artifact doc findings (content exists in worktree, the merge carries it).
     const actionable = all.filter((f) => !/in (the )?main repo|not (in|on) (the )?main|merge[- ]?time|worktree.*(not|missing).*main/i.test(`${f.title} ${f.evidence}`))
-    for (const f of all) if (!actionable.includes(f)) ledger(f.finding_id || firstCard, 'final-merge-artifact', 'SKIP', 'resolved-by-merge')
+    // G3 — the merge-artifact regex is loose; a BLOCKER/HIGH it over-matches must NOT vanish.
+    // Track every skipped finding as a residual (the skill materialises it) — no silent drop.
+    for (const f of all) if (!actionable.includes(f)) {
+      ledger(f.finding_id || firstCard, 'final-merge-artifact', 'SKIP', 'resolved-by-merge')
+      residuals.push({ card: f.finding_id || firstCard, kind: 'merge-artifact-skipped', evidence: `${f.severity} ${f.title}: ${f.evidence}`, materialized: false })
+    }
     // F-007/F-037 — group actionable findings by fix-area (file) → one resolve per area.
     const byArea = {}
     for (const f of actionable) {
@@ -624,6 +665,7 @@ function buildTelemetry() {
     degraded,
     degradation_reasons: degradationReasons,
     execution_mode: preflight ? preflight.executionMode : 'sequential',
+    codex_resolved: (preflight && cardIds.length >= 2) ? !!preflight.codexResolved : null, // G2 — null = not probed (single-card)
     // cost — total_tokens via budget.spent() delta; agent_count via counter; wall_clock_s stamped by the SKILL.
     total_tokens: totalTokens,
     agent_count: agentCount,

package/framework/docs/WORKFLOWS.md

@@ -13,9 +13,9 @@ 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). |
-| `new2` (v4.17.0) | `/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. **v4.17.0 hardening (single-wave):** 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); mechanical steps (commit / follow-up) run on **Haiku**; telemetry carries real **cost** (`total_tokens` via `budget.spent()`, `agent_count`, skill-stamped `wall_clock_s`) + `degraded`. Agents Read `/new`'s reference modules for semantics. |
-| `new2-resolve` (v4.17.0) | `new2` (self-healing) | Resolution pass for any gate that would otherwise need a human. **v4.17.0:** 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 they fall inside MAY-EDIT (defeats fabricated success); accepts a **batched `findings` list** (one resolve per fix-area); domain-specialized fixer + judge (doc→doc-reviewer, ui→ui-expert, security→security-reviewer judge, perf→api-perf-cost-auditor judge); incidental out-of-scope findings are surfaced (not dropped); follow-up materialisation is offline-safe (deferred to the skill if no agent can write). |
+| `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. |
+| `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). |
 
 > **`new2` is an experiment, not a replacement.** It exists to A/B-test the
 > context-economy of workflow-hosting `/new`. `/new` remains the SSOT, the

package/package.json

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