baldart 4.16.1 → 4.17.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.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).
+
+> **Why.** `new2` è un A/B di `/new` per misurare l'economia di contesto del workflow-hosting. Il run reale ha mostrato che, oltre al costo, l'autonomia zero-ask degradava in modo **non sicuro** sotto outage (DONE falsi, codice non revisionato su trunk, follow-up persa) — esattamente il recovery che `/new` (gated, main-loop) avrebbe fermato. Decisioni utente vincolanti: *Decision-auto, infra-deferred* (niente `BALDART_AUTONOMOUS=1`; azioni infra owner-gated sempre policy-deferred) e *agenti specializzati come `/new`* (no general-purpose dove conta la qualità).
+
+### Changed
+- **`framework/.claude/workflows/new2.js` — scheduler a DAG + resilienza + integrità.** Il for-loop sequenziale e il ramo team-mode sono sostituiti da uno **scheduler dependency-gated** (semantica single-worktree): una card parte solo quando TUTTE le dipendenze in-batch sono `committed`; i dipendenti di una dep fallita vanno `blocked` (niente resolve doomed, F-017/F-021); fallimento transitorio → `pending` + re-invocazione (cap); outage sostenuto → **degrada pulito** (`degraded:true` + worktree clean + return-as-ledger, F-012/F-019/F-020). Implement usa l'**owner_agent** della card; review è un **fan-out specializzato** sfrondato dal `review_profile` (F-024/F-025); commit è **Haiku** con `git status` reconcile, mai `git add -A` (F-023). Skip-completed idempotente su commit-sha+receipt+no-open-followup, NON sul flag `DONE` (F-026). Merge **integrity-gated**: mai force-DONE (F-029), mai commit di codice non revisionato (F-030), mai merge di batch incompleto/degradato (F-031). Telemetria veritiera: `total_tokens` via `budget.spent()`, `agent_count`, `degraded`, `cards_real_done` vs `cards_force_done`=0 (F-032). Parse-guard `args` (F-001).
+- **`framework/.claude/workflows/new2-resolve.js` — short-circuit + anti-fabbricazione + batching.** Verdetto **terminale** che salta il multi-attempt quando il problema è impossibile-by-definition (`out-of-ownership` verificato in JS contro MAY-EDIT; altri reason ratificati dal judge → niente escape-hatch, F-008). **Judge avversariale OBBLIGATORIO** su ogni claim `verified`, con **cross-check JS** dei file confermati indipendentemente dal judge (defeats fabricated success, beccata 2× nel run reale — F-015/F-033). Lista **`findings` batchata** (1 resolve per fix-area, F-007/F-035/F-037). Fixer/judge **per dominio** (doc→doc-reviewer, ui→ui-expert, security→security-reviewer judge, perf→api-perf-cost-auditor judge — F-024). `outOfScopeFindings` non più persi (F-022). Follow-up su Haiku, **offline-safe** (deferita al skill se nessun agente può scrivere, F-020). Parse-guard `args` (F-004).
+- **`framework/.claude/skills/new2/SKILL.md` — reconcile + resume + telemetria reale.** Step 4 passa `ts` (il workflow non ha clock). Step 5: materializza le follow-up dei `residuals` non ancora su disco (offline-safe — il skill ha il filesystem → chiude "nothing dropped" sotto outage, F-020), **rilancia** con `resumeFromRunId` se `degraded` (idempotente via skip-completed), registra telemetria veritiera (`wall_clock_s`, `followups_on_disk` contando i file — F-032).
+- **`framework/.claude/agents/prd-card-writer.md` — Rule A.1 (AC↔ownership consistency).** Fix a monte del difetto ricorrente "AC fuori dal MAY-EDIT" (F-016): ogni AC dev'essere soddisfabile editando i file della propria card.
+- **`framework/docs/WORKFLOWS.md`** — righe `new2`/`new2-resolve` aggiornate al comportamento v4.17.0.
+
+## [4.16.2] - 2026-06-06
+
+**`baldart update` non si blocca più all'infinito su un edit `.framework/` ormai assorbito a monte.** Un edit locale a un file framework (es. `agents/ui-expert.md`) committato con un subject che *non* contiene la parola "baldart" sfuggiva alla classificazione `chore-wrapper` (rumore) e veniva marcato `custom-overlay-able`. Quel commit resta per sempre ancestor di `HEAD` ma mai di `FETCH_HEAD`, quindi `git log FETCH_HEAD..HEAD -- .framework` lo ripesca a **ogni rilascio successivo** — e il flusso seamless si fermava sul gate `divergence-capture-incomplete` perché l'overlay (additivo) non riproduceva byte-a-byte il file `.framework`, anche quando il contenuto era già identico all'upstream e la personalizzazione viveva correttamente nell'overlay. Risultato: lo stesso commit "fantasma" rifaceva muro a ogni `update`, senza via d'uscita via overlay (riconciliare un overlay additivo non può mai far passare il round-trip stretto). **PATCH** (bugfix del detector di divergenza + reset-safety degli overlay additivi; nessun cambio di capability, nessuna chiave `baldart.config.yml`).
+
+> **Why.** Il check di fedeltà capture+verify pretendeva `merge(base_upstream, overlay) == file_.framework`. Per un overlay `extend` (additivo) questo è **strutturalmente falso** quando `.framework` è pristine-upstream: il merge aggiunge sezioni, il file no → "stale" eterno. E il classifier non distingueva un edit *vivo* (da preservare) da uno *assorbito* (contenuto già a monte → un re-sync non perde nulla). Due correzioni complementari chiudono la classe di falso positivo per tutti i consumer.
+
+### Fixed
+
+- **`src/utils/git.js` — categoria `absorbed` nel classifier di divergenza.** `classifyDivergence` ora demota a rumore (`absorbed`) ogni commit `custom-*` i cui file `.framework/` toccati sono **byte-identici all'upstream (`FETCH_HEAD`)** — confronto di blob-SHA, prefisso `.framework/` strippato per mappare il path upstream; conservativo (file fuori da `.framework/`, mancante a monte, o SHA diverso → resta drift reale). `aggregateDivergenceClass` include `absorbed` tra le `noiseCategories`, così un edit ormai assorbito non spinge più la classe verso `overlay-able`/`mixed`: la batch torna `all-noise` → auto-resolve pulito.
+- **`src/utils/overlay-capture.js` — reset-safety per overlay additivi (`captureAndVerify`).** Quando esiste già un overlay agent/command, il file `.framework` viene riconosciuto come **reset-safe** (nessun edit inline da perdere) se è pristine: (a) byte-identico alla base upstream verso cui si farebbe reset, **oppure** (b) corrisponde alla base con cui l'overlay è stato autorato (`base_file_sha` in frontmatter) — pristine anche dopo che l'upstream è andato avanti. In quel caso è `captured` (non più `stale`), invece di pretendere il round-trip stretto che un overlay additivo non può mai soddisfare. Il caso *genuinamente* stale (edit inline reale che l'overlay non riproduce) resta correttamente un blocker.
+- **Test.** `classify-divergence.test.js`: 3 fixture per `absorbed` (da solo / con merge plumbing → `all-noise`; con overlay-able genuino → `overlay-able`). `overlay-capture.test.js`: 2 fixture per la reset-safety (overlay additivo + `.framework` == base → `captured`; upstream spostato ma `.framework` pristine vs `base_file_sha` → `captured`).
+
 ## [4.16.1] - 2026-06-05
 
 **Review di allineamento `new` ↔ `new2`: 9 fix di fedeltà sui workflow `new2`/`new2-resolve` emersi da una review adversariale a 3 reviewer paralleli.** La v4.16.0 ha introdotto `new2` come variante workflow-hosted di `/new`; una review di allineamento (gate-coverage · child-workflow wiring · control-flow) ha refutato l'implementazione su difetti reali — di semantica/allineamento, non di esecuzione (il wiring tra i 3 workflow era contract-fedele). **PATCH** (bugfix di allineamento del nuovo `new2`, nessun cambio di capability, nessuna chiave `baldart.config.yml`).

package/VERSION

@@ -1 +1 @@
-4.16.1
+4.17.0

package/framework/.claude/agents/prd-card-writer.md

@@ -136,6 +136,31 @@ that list — not this one — is the source of truth.
 **Epic cards** use `owner_agent: ""` (empty string) because they are
 trackers, not implementation. The dispatcher skips them.
 
+### Rule A.1 — AC↔ownership consistency (every AC must be satisfiable inside the card)
+
+For EVERY acceptance criterion you write, the file(s) that AC requires editing
+MUST be a subset of that card's `files_likely_touched` (its MAY-EDIT ownership).
+An AC whose ONLY implementation site lives in another card's file is
+**structurally unsatisfiable** by this card — at execution time it can never
+close, so it burns an entire resolve cycle and then defers anyway (and, on
+impossible tasks, *induces* fabricated "fixed" claims). Concretely:
+
+- If an AC needs the JSX **render** of a value, the card that owns the render
+  file (e.g. `homepage-store.tsx`) must carry that AC — not the data/view-model
+  card that merely computes the value.
+- If an AC needs **wiring at a call-site** (e.g. `after(() => dispatch())` inside
+  a create funnel in `data.ts`), assign it to the card that owns that file, or
+  add that file to this card's `files_likely_touched`, or express the dependency
+  explicitly via `depends_on` + a card that owns the site.
+- An AC whose remedy is an **owner-gated infra action** (remote DB push, deploy,
+  secret rotation, DNS) is NOT a code AC — phrase it as a tracked manual/ops
+  step, never as a per-card code acceptance criterion.
+
+Self-check before emitting cards: for each AC, name the file it edits and
+confirm that file is in the same card's `files_likely_touched`. If it isn't,
+move the AC or widen ownership. (This is the upstream fix for the recurring
+"AC outside MAY-EDIT" failure; `new2`/`/new` also re-assert it at pre-flight.)
+
 ### Rule B — UI cards (`ui-expert`) have UI-ONLY scope
 
 When you assign `owner_agent: ui-expert` to a card, its scope MUST cover

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

@@ -99,30 +99,55 @@ Workflow({ name: 'new2', args: {
   metricsDir,         // $METRICS
   refModulesBase,     // .claude/skills/new/references (semantic SSOT)
   config,             // the parsed baldart.config.yml (paths.*/stack.*/features.*/git.*)
+  ts,                 // ISO timestamp NOW — the workflow has no clock (Date.now() unavailable there)
   flags: { stats, effort, full }
 }})
 ```
 
+Record the kickoff time (`ts`) before the call — Step 5 uses it to stamp the
+real wall-clock duration (the workflow cannot read a clock).
+
 The workflow runs the entire batch in the background. **Do not poll it** — it
 returns when the batch is done. It returns:
 
 ```
-{ report, perCardResults, gateLedger, residualFollowups, telemetry }
+{ report, perCardResults, gateLedger, residualFollowups, residuals,
+  degraded, degradationReasons, telemetry }
 ```
 
-`report` is a ready-to-show markdown batch summary (files changed per card, review
-findings, QA, merge hash, any auto-created follow-up cards). `residualFollowups`
-lists every follow-up card `new2-resolve` materialised for an unresolved
-gate/scope-expansion (nothing was silently dropped). `telemetry` is the Phase-8
-record (same schema as `/new`, with `variant: "new2"`).
-
-### Step 5 — Present + record
-
-- Print `report` to the user verbatim (it is already the single batch summary).
-- If `residualFollowups` is non-empty, surface them prominently ("queste AC/finding
-  non risolti autonomamente sono stati tracciati come follow-up card: …") — this is
-  the post-run review that replaced the ~25 mid-run questions.
-- Append `telemetry` (with `variant: "new2"`) to `${metricsDir}/skill-runs.jsonl`
-  and, when `flags.stats`, run the session token-telemetry script the same way
-  `/new` Phase 8 does (`-stats`), so the A/B comparison has real `usage` data for
-  both variants. Do NOT re-summarise the cards yourself — the workflow already did.
+- `report` — ready-to-show markdown batch summary.
+- `residuals` — the **OFFLINE-SAFE ledger of record**: every residual the workflow
+  could not finish, each `{ card, kind, evidence, materialized }`. A residual with
+  `materialized:false` has NO follow-up card on disk yet (e.g. the workflow hit an
+  outage where no agent could write the file). **You (the skill) must reconcile it.**
+- `degraded` / `degradationReasons` — the batch stopped early under a sustained
+  outage (or another degradation). The batch is NOT complete; it must be resumed.
+- `telemetry` — the Phase-8 record (`variant:"new2"`).
+
+### Step 5 — Reconcile, resume, present, record
+
+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
+   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
+   per-card **skip-completed** guard makes the resume idempotent — already-committed
+   cards are skipped, only the incomplete/blocked ones run. Repeat until `degraded`
+   is false (or the same cards stall twice → surface to the user).
+3. **Present.** Print `report` verbatim. Surface `residuals` prominently
+   ("questi residui sono tracciati come follow-up: …") — the post-run review that
+   replaced the ~25 mid-run questions. If `degraded`, say so plainly (the run was
+   incomplete and resumed).
+4. **Record truthful telemetry.** Before appending `telemetry` to
+   `${metricsDir}/skill-runs.jsonl`, fill the fields the workflow could not compute:
+   `wall_clock_s` (now − kickoff `ts`) and `followups_on_disk` (count the actual
+   follow-up files on disk, NOT `residualFollowups.length` — which double-counts).
+   `total_tokens`/`agent_count` come from the workflow (`budget.spent()` delta +
+   spawn counter); if `total_tokens` is null, run the `/new` Phase-8 `-stats` script
+   to backfill real `usage`. Keep `degraded`/`degradation_reasons` in the record so
+   the A/B comparison can exclude or weight degraded runs. Do NOT re-summarise the
+   cards — the workflow already did.

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

@@ -1,32 +1,24 @@
 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). Runs an aggressive fix→verify loop (targeted coder → judged multi-attempt → adversarial re-verify); its TERMINAL is auto-materialising a tracked follow-up card so nothing is ever silently dropped. Domain-Override aware: doc fixes go to doc-reviewer, security/migration to coder and NEVER inline-bypassed. Agents Read /new's reference modules for semantics (args.refModulesBase). 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), 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.",
   phases: [
-    { title: 'Diagnose', detail: 'classify the problem + decide scope-expansion boundary' },
+    { title: 'Diagnose', detail: 'classify + terminal short-circuit + scope-expansion boundary' },
     { title: 'Repair', detail: 'targeted fix, then judged multi-attempt if needed' },
-    { title: 'Verify', detail: 'adversarial re-verify against the originating gate' },
+    { title: 'Verify', detail: 'mandatory adversarial judge + JS cross-check of verified files' },
   ],
 }
 
 // ───────────────────────────────────────────────────────────────────────────
 // args contract (from new2.js resolve()):
-//   kind          'ac-unmet'|'blocker'|'qa-fail'|'e2e-blocked'|'merge-blocker'
-//                 |'scope-expansion'|'agent-crash'|'baseline-fail'
-//   cardId        string      card (or finding id) the problem belongs to
-//   evidence      string      verbatim AC / failing gate / finding evidence
-//   worktreePath  string      where the fix happens
-//   mayEditPaths  string[]    the card's file-ownership MAY-EDIT set
-//   scopeFiles    string[]    files in scope for re-verify
-//   domain        'doc'|'security'|'migration'|'code'|'perf'|'test'
-//   refModulesBase string     /new reference modules dir (semantics)
-//   config        object      parsed baldart.config.yml
-//
-// return (consumed by new2.js):
-//   { status: 'resolved'|'followup'|'fatal', followupCard?, reason? }
+//   kind, cardId, evidence, worktreePath, mayEditPaths[], scopeFiles[], domain,
+//   refModulesBase, config, ts, findings[] (batched: [{kind,evidence,domain}])
+// return: { status:'resolved'|'followup'|'fatal', followupCard?, reason?, outOfScopeFindings? }
 // ───────────────────────────────────────────────────────────────────────────
 
-const a = args || {}
+// F-004 — tolerate args delivered as a JSON string.
+let a = args || {}
+if (typeof a === 'string') { try { a = JSON.parse(a) } catch (_) { a = {} } }
 const kind = a.kind || 'blocker'
 const card = a.cardId || 'CARD'
 const evidence = a.evidence || ''
@@ -34,106 +26,187 @@ 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'
+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 || {}
 const paths = cfg.paths || {}
 const backlogDir = paths.backlog_dir || 'backlog'
 const protectedDomain = domain === 'security' || domain === 'migration'
 
+// F-019 — bounded immediate retry on transient errors (shared pattern; no import allowed).
+const TRANSIENT = /overload|529|429|rate.?limit|5\d\d|econn|etimedout|timeout|temporar|unavailable/i
+function isTransient(e) { return TRANSIENT.test(String((e && e.message) || e || '')) }
+async function agentSafe(prompt, opts, maxAttempts) {
+  const cap = maxAttempts || 3
+  let lastErr = null
+  for (let i = 0; i < cap; i++) {
+    try {
+      const o = i === 0 ? opts : Object.assign({}, opts, { label: `${(opts && opts.label) || 'agent'}~retry${i}` })
+      return await agent(prompt, o)
+    } catch (e) { lastErr = e; if (!isTransient(e)) throw e }
+  }
+  const err = new Error('transient-exhausted: ' + String((lastErr && lastErr.message) || lastErr)); err.transientExhausted = true; throw err
+}
+
 const FIX_SCHEMA = {
   type: 'object', required: ['applied', 'verified'], additionalProperties: true,
   properties: {
-    applied: { type: 'boolean', description: 'true if an edit was made' },
-    verified: { type: 'boolean', description: 'true if the originating gate now passes (re-run it)' },
-    crashed: { type: 'boolean', description: 'agent could not act (for agent-crash routing)' },
+    applied: { type: 'boolean' },
+    verified: { type: 'boolean', description: 'true only if you re-ran the originating gate and it passed' },
+    // F-008 — terminal short-circuit (impossible-by-definition). Not trusted blindly.
+    terminal: { type: 'boolean', description: 'true if no in-MAY-EDIT fix can ever satisfy the gate' },
+    terminalReason: { enum: ['out-of-ownership', 'baseline-not-reached', 'owner-gated', 'not-a-code-defect', ''] },
+    remedyFiles: { type: 'array', items: { type: 'string' }, description: 'files the real fix would require editing (for out-of-ownership JS verification)' },
+    crashed: { type: 'boolean' },
+    // F-022 — incidental findings outside this card's MAY-EDIT (so they are not dropped).
+    outOfScopeFindings: { type: 'array', items: { type: 'object', additionalProperties: true } },
     note: { type: 'string' },
   },
 }
 const JUDGE_SCHEMA = {
   type: 'object', required: ['best'], additionalProperties: false,
-  properties: { best: { type: 'number', description: '1-based index of the best attempt, or 0 if none works' }, rationale: { type: 'string' } },
+  properties: {
+    best: { type: 'number', description: '1-based index of the soundest verified attempt, or 0 if none truly holds' },
+    // F-015 — the files the judge INDEPENDENTLY confirmed exist and changed (cross-checked in JS).
+    verifiedFiles: { type: 'array', items: { type: 'string' } },
+    rationale: { type: 'string' },
+  },
+}
+const TERMINAL_JUDGE_SCHEMA = {
+  type: 'object', required: ['confirmed'], additionalProperties: false,
+  properties: { confirmed: { type: 'boolean', description: 'true if the terminal verdict genuinely holds' }, rationale: { type: 'string' } },
 }
 const FOLLOWUP_SCHEMA = {
   type: 'object', required: ['created', 'followupCard'], additionalProperties: true,
   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'
+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')
 const brief = [
   `Worktree: ${worktree} (cd into it; run all gates/git yourself).`,
   `Card: ${card}`,
   `Problem kind: ${kind}`,
-  `Evidence: ${evidence}`,
+  findings.length > 1 ? `Findings to fix (batched — same fix-area):\n${findingsBlock}` : `Evidence: ${evidence}`,
   `MAY-EDIT (file-ownership — do NOT touch anything else): ${mayEdit.join(', ') || '(card scope)'}`,
   `Scope files for re-verify: ${scopeFiles.join(', ') || '(diff)'}`,
   `Domain: ${domain}${protectedDomain ? ' (PROTECTED — security/migration: never inline-bypass; the right specialist MUST apply)' : ''}`,
   `Reference modules (Read for exact semantics): ${REF}/`,
-  `UI re-verify obligation: if your fix touches a UI file (app dir / components / *.css / *.scss), you MUST re-run the Phase 2.6 E2E review (per ${REF}/review-cycle.md) before declaring verified — a code-review/Codex fix can reintroduce visual/functional drift (mirrors codex-gate.md step 6).`,
-].join('\n')
+  `UI re-verify obligation: if your fix touches a UI file, re-run the Phase 2.6 E2E review (per ${REF}/review-cycle.md) before declaring verified.`,
+  `If the fix requires editing files OUTSIDE MAY-EDIT, return terminal:true terminalReason:'out-of-ownership' remedyFiles:[...] (do NOT edit them). If the remedy is an owner-gated infra action, terminal:true terminalReason:'owner-gated'. Report any incidental defect outside MAY-EDIT in outOfScopeFindings.`,
+].filter(Boolean).join('\n')
 
-// The agent that OWNS a fix in this domain (Domain-Override): doc → doc-reviewer.
-const fixerAgent = domain === 'doc' ? 'doc-reviewer' : 'coder'
+// JS-deterministic ownership check (F-008 anti-escape-hatch): are remedy files ⊆ MAY-EDIT?
+function filesInScope(files) {
+  if (!Array.isArray(files) || !files.length) return false
+  if (!mayEdit.length) return false
+  return files.every((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)
+  return out
+}
 
-// ───────────────────────────────────────────────────────────────────────────
-// Phase Diagnose — branch by kind.
-// ───────────────────────────────────────────────────────────────────────────
 phase('Diagnose')
 
 // ---- baseline-fail (E2): try to make the trunk build; fatal if irrecoverable ---
 if (kind === 'baseline-fail') {
-  const r = await agent(
-    `The batch worktree's BASELINE build fails (trunk may not build — pre-existing). Try to make it build per ${REF}/setup.md step 6a.\n\n${brief}\n\nFix the build errors if they are tractable (missing dep, stale lock, trivial type error). Re-run tsc+lint+build. Return verified:true only if the baseline now passes. If the breakage is non-trivial/pre-existing and not safely fixable, return verified:false (the caller will treat the batch as fatal).`,
-    { label: `resolve:baseline:${card}`, phase: 'Diagnose', agentType: 'coder', schema: FIX_SCHEMA }
-  )
-  if (r && r.verified) { log('baseline recovered.'); return { status: 'resolved' } }
-  log('baseline irrecoverable — batch fatal.')
+  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' }
 }
 
-// ---- scope-expansion (Asse 2): deterministic boundary, no arbitrary threshold ---
+// ---- scope-expansion (Asse 2): deterministic boundary ---
 if (kind === 'scope-expansion') {
-  // Integrate iff: within MAY-EDIT ownership AND not security/migration AND not a NEW AC.
-  const decide = await agent(
-    `A review finding EXPANDS scope beyond card ${card}'s acceptance criteria (not a fail — extra legitimate work). Decide per the deterministic boundary (no line-count threshold):\n` +
-      `INTEGRATE NOW iff ALL hold: (1) the fix stays inside MAY-EDIT ownership; (2) domain is NOT security/migration; (3) it does NOT introduce a new user-facing acceptance criterion. Otherwise → MATERIALISE A FOLLOW-UP.\n\n${brief}\n\n` +
-      `If INTEGRATE: apply the fix via the domain owner discipline (you are ${fixerAgent}), re-run lint+tsc, return applied:true verified:true. If FOLLOW-UP: return applied:false verified:false note:'needs-followup: <why boundary failed>'. Do NOT prompt.`,
-    { label: `resolve:scope:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
-  )
-  if (decide && decide.verified) { log('scope-expansion integrated within ownership.'); return { status: 'resolved' } }
-  return await materialiseFollowup('scope-expansion', (decide && decide.note) || 'outside ownership / new AC / protected domain')
+  let decide = null
+  try {
+    decide = await agentSafe(
+      `A review finding EXPANDS scope beyond card ${card}'s acceptance criteria. Decide per the deterministic boundary (no line-count threshold):\n` +
+        `INTEGRATE NOW iff ALL: (1) fix stays inside MAY-EDIT; (2) domain NOT security/migration; (3) no NEW user-facing AC. Else MATERIALISE A FOLLOW-UP.\n\n${brief}\n\n` +
+        `If INTEGRATE: apply (you are ${fixerAgent}), re-run lint+tsc, return applied:true verified:true. If FOLLOW-UP: applied:false verified:false note:'needs-followup: <why>'.`,
+      { label: `resolve:scope:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
+    )
+  } catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during scope-expansion', outOfScopeFindings: [] }; throw e }
+  if (decide && decide.verified) {
+    const ok = await judgeVerify([{ i: 1, r: decide }])
+    if (ok.ok) { log('scope-expansion integrated within ownership.'); return { status: 'resolved', outOfScopeFindings: collectOOS(decide) } }
+  }
+  return await materialiseFollowup('scope-expansion', (decide && decide.note) || 'outside ownership / new AC / protected', collectOOS(decide))
 }
 
-// ---- agent-crash (E1): retry → route to the right specialist; protected = never bypass --
+// ---- agent-crash (E1) ---
 if (kind === 'agent-crash') {
-  const r = await agent(
-    `A subagent crashed while handling this work. Re-attempt it with the CORRECT specialist (${fixerAgent}) per ${REF}/commit.md § Sub-agent failure protocol.\n\n${brief}\n\nRetry the work once. ${protectedDomain ? 'This is a PROTECTED domain (security/migration): if you cannot complete it, return verified:false — NEVER inline-bypass.' : 'If transient, complete it.'} Re-verify the originating gate. Return verified:true only if done + verified.`,
-    { label: `resolve:crash:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
-  )
-  if (r && r.verified) return { status: 'resolved' }
-  return await materialiseFollowup('agent-crash', 'subagent crash unrecovered' + (protectedDomain ? ' (protected domain — not bypassed)' : ''))
+  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 (ac-unmet | blocker | qa-fail | e2e-blocked | merge-blocker)
-// Tier 1: targeted fix → re-verify. Tier 2: judged multi-attempt. Terminal: follow-up.
+// Asse 1 — Tier-1 (with terminal short-circuit) → judged multi-attempt → follow-up.
 // ───────────────────────────────────────────────────────────────────────────
 const gateHint = {
-  'ac-unmet': `Implement the unmet acceptance criterion EXACTLY (no scope expansion), per ${REF}/completeness.md Phase 2.5b. Re-verify the AC against the code.`,
+  'ac-unmet': `Implement the unmet acceptance criterion EXACTLY, per ${REF}/completeness.md Phase 2.5b. Re-verify against the code.`,
   blocker: `Fix the blocking finding per ${REF}/codex-gate.md / ${REF}/completeness.md. Re-run the failing gate.`,
-  'qa-fail': `Fix the failing QA gates per ${REF}/review-cycle.md Phase 3.5 — fix the code, not the tests (unless a test is wrong). Re-run qa-sentinel.`,
-  'e2e-blocked': `Fix the implementation so the E2E review passes per ${REF}/review-cycle.md Phase 2.6 (never override known-broken UI). Re-run /e2e-review.`,
+  'qa-fail': `Fix the failing QA gates per ${REF}/review-cycle.md Phase 3.5 — fix the code, not the tests. Re-run qa-sentinel.`,
+  'e2e-blocked': `Fix so the E2E review passes per ${REF}/review-cycle.md Phase 2.6. Re-run /e2e-review.`,
   'merge-blocker': `Fix the verified BLOCKER/HIGH from the final review per ${REF}/final-review.md F.5. Re-verify.`,
 }[kind] || `Fix the blocker and re-verify.`
 
 phase('Repair')
-let attempt = await agent(
-  `Tier-1 targeted repair for card ${card} (${kind}).\n\n${brief}\n\n${gateHint}\n\nApply the minimal correct fix within MAY-EDIT only. Re-run the originating gate yourself and report verified honestly (do NOT claim verified without re-running it).`,
-  { label: `resolve:${kind}:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
-)
-if (attempt && attempt.verified) { log(`${kind} resolved (tier 1).`); return { status: 'resolved' } }
-
-// Tier 2 — judged multi-attempt (parallel divergent fixes → judge → adversarial verify).
-// Budget guard: skip the fan-out when the run is near its token target.
-const canFanOut = !budget.total || budget.remaining() > 60000
+let attempt = null
+try {
+  attempt = await agentSafe(
+    `Tier-1 targeted repair for card ${card} (${kind}).\n\n${brief}\n\n${gateHint}\n\nApply the minimal correct fix within MAY-EDIT only. Re-run the originating gate and report verified honestly (never claim verified without re-running it).`,
+    { label: `resolve:${kind}:${card}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
+  )
+} catch (e) { if (e && e.transientExhausted) return { status: 'followup', reason: 'outage during tier-1', outOfScopeFindings: [] }; throw e }
+
+// F-008 — terminal short-circuit, verified not trusted.
+if (attempt && attempt.terminal) {
+  const tr = attempt.terminalReason || ''
+  let confirmed = false
+  if (tr === 'out-of-ownership') {
+    confirmed = !filesInScope(attempt.remedyFiles) // genuinely terminal iff remedy files are NOT in MAY-EDIT
+  } else {
+    // owner-gated / not-a-code-defect / baseline-not-reached — ratify with the judge.
+    try {
+      const tj = await agentSafe(
+        `A repair agent declared this problem TERMINAL (reason: ${tr}) — no in-MAY-EDIT code fix can satisfy it.\n\n${brief}\n\nIndependently verify: is that verdict genuinely correct, or is it an excuse to avoid work? Return confirmed:true only if it truly holds.`,
+        { label: `resolve:terminal-judge:${card}`, phase: 'Verify', agentType: judgeAgent, schema: TERMINAL_JUDGE_SCHEMA }
+      )
+      confirmed = !!(tj && tj.confirmed)
+    } catch (_) { confirmed = false }
+  }
+  if (confirmed) { log(`${kind} terminal (${tr}) — short-circuit to follow-up.`); return await materialiseFollowup(kind, `terminal: ${tr} — ${attempt.note || ''}`, collectOOS(attempt)) }
+  log(`terminal verdict (${tr}) rejected — proceeding to multi-attempt.`)
+}
+
+// F-015 — a verified Tier-1 still goes through the mandatory judge cross-check.
+if (attempt && attempt.verified) {
+  const ok = await judgeVerify([{ i: 1, r: attempt }])
+  if (ok.ok) { log(`${kind} resolved (tier 1, judge-confirmed).`); return { status: 'resolved', outOfScopeFindings: collectOOS(attempt) } }
+  log('tier-1 verified rejected by judge cross-check — escalating.')
+}
+
+// Tier 2 — judged multi-attempt (budget-guarded; single specialist for protected domains).
+const canFanOut = (typeof budget === 'undefined' || !budget.total || budget.remaining() > 60000)
+let tier2OOS = []
 if (canFanOut && !protectedDomain) {
   phase('Repair')
   const angles = [
@@ -141,40 +214,64 @@ if (canFanOut && !protectedDomain) {
     'Fix defensively at the call site (guard/validate without changing the contract).',
     'Fix by reusing an existing utility/pattern instead of new code.',
   ]
-  const attempts = (await parallel(angles.map((angle, i) => () =>
-    agent(
-      `Tier-2 repair attempt #${i + 1} for card ${card} (${kind}), angle: ${angle}\n\n${brief}\n\n${gateHint}\n\nApply your fix within MAY-EDIT, re-run the gate, and report whether it now passes. Work in isolation; the best attempt will be selected.`,
+  const tries = (await parallel(angles.map((angle, i) => () =>
+    agentSafe(
+      `Tier-2 repair attempt #${i + 1} for card ${card} (${kind}), angle: ${angle}\n\n${brief}\n\n${gateHint}\n\nApply within MAY-EDIT, re-run the gate, report whether it passes. Work in isolation; the best attempt is selected.`,
       { label: `resolve:${kind}:${card}#${i + 1}`, phase: 'Repair', agentType: fixerAgent, schema: FIX_SCHEMA }
     ).then((r) => ({ i: i + 1, r })).catch(() => null)
   ))).filter(Boolean)
-
-  const verified = attempts.filter((x) => x.r && x.r.verified)
+  tier2OOS = collectOOS(...tries.map((t) => t.r))
+  const verified = tries.filter((x) => x.r && x.r.verified)
   if (verified.length) {
-    phase('Verify')
-    // Adversarial pick: judge which verified attempt is the soundest (refute the rest).
-    const judge = await agent(
-      `Adversarially judge these repair attempts for card ${card} (${kind}). Each claims the gate now passes. Pick the SOUNDEST (best minimal, least regression-prone) — try to refute each with path:line reasoning. Return its 1-based index, or 0 if none truly holds.\n\nEvidence: ${evidence}\nAttempts that claim verified: ${verified.map((v) => `#${v.i}: ${v.r.note || ''}`).join(' | ')}`,
-      { label: `resolve:judge:${card}`, phase: 'Verify', agentType: 'code-reviewer', schema: JUDGE_SCHEMA }
-    )
-    if (judge && judge.best > 0) { log(`${kind} resolved (tier 2, attempt #${judge.best}).`); return { status: 'resolved' } }
+    const ok = await judgeVerify(verified)
+    if (ok.ok) { log(`${kind} resolved (tier 2, attempt #${ok.best}, judge-confirmed).`); return { status: 'resolved', outOfScopeFindings: collectOOS(attempt).concat(tier2OOS) } }
   }
 } else if (protectedDomain) {
-  log('protected domain — single specialist attempt only (no parallel fan-out).')
+  log('protected domain — single specialist attempt only (no fan-out).')
 } else {
   log('budget near target — skipping tier-2 fan-out.')
 }
 
-// Terminal — nothing resolved autonomously: materialise a tracked follow-up card.
-return await materialiseFollowup(kind, attempt && attempt.note ? attempt.note : 'unresolved after repair tiers')
+return await materialiseFollowup(kind, (attempt && attempt.note) || 'unresolved after repair tiers', collectOOS(attempt).concat(tier2OOS))
 
 // ───────────────────────────────────────────────────────────────────────────
-async function materialiseFollowup(k, reason) {
-  const r = await agent(
-    `Materialise a follow-up backlog card so this residual is TRACKED, not dropped (per ${REF}/completeness.md Phase 2.5b option 3 — the sanctioned, NON-silent deferral).\n\n${brief}\nKind: ${k}\nReason it could not be auto-resolved: ${reason}\n\n` +
-      `Create ${backlogDir}/${card}-followup-<gate>.yml with status: TODO and the MINIMUM valid fields (non-empty requirements ≥1 derived from the residual, acceptance_criteria ≥1 = the verbatim residual, files_likely_touched ≥1 from this card's ownership). It MUST pass the /new pre-flight field check. Return the created card id.`,
-    { label: `resolve:followup:${card}`, phase: 'Verify', agentType: 'general-purpose', schema: FOLLOWUP_SCHEMA }
-  )
-  const followupCard = (r && r.followupCard) || `${card}-followup`
-  log(`${k} → follow-up card ${followupCard} (nothing dropped).`)
-  return { status: 'followup', followupCard, reason }
+// F-015/F-033 — mandatory adversarial judge + deterministic JS cross-check.
+// The judge (cross-model code-reviewer / domain specialist) does its OWN grep and
+// returns the files it independently confirmed changed; we cross-check ⊆ MAY-EDIT.
+async function judgeVerify(verifiedAttempts) {
+  if (!verifiedAttempts.length) return { ok: false, best: 0 }
+  let judge = null
+  try {
+    judge = await agentSafe(
+      `Adversarially judge these repair attempts for card ${card} (${kind}). Each CLAIMS the gate now passes — verify INDEPENDENTLY (grep/read the files yourself; do NOT trust the claim). Pick the SOUNDEST (best minimal, least regression-prone); return 0 if NONE genuinely holds. Also return verifiedFiles = the files you independently confirmed exist AND changed.\n\nEvidence: ${evidence}\nAttempts claiming verified: ${verifiedAttempts.map((v) => `#${v.i}: ${(v.r && v.r.note) || ''}`).join(' | ')}`,
+      { label: `resolve:judge:${card}`, phase: 'Verify', agentType: judgeAgent, schema: JUDGE_SCHEMA }
+    )
+  } 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).')
+    return { ok: false, best: 0 }
+  }
+  return { ok: true, best: judge.best }
+}
+
+async function materialiseFollowup(k, reason, oos) {
+  let r = null
+  try {
+    // F-023 — mechanical YAML write → Haiku.
+    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 }
+    )
+  } catch (e) {
+    // F-020 — could not materialise (e.g. outage): return WITHOUT a followupCard so the
+    // SKILL writes it from the offline-safe residual ledger. Never claim it was created.
+    log(`follow-up materialisation failed (${String(e && e.message)}) — skill will reconcile.`)
+    return { status: 'followup', followupCard: null, reason, outOfScopeFindings: oos || [] }
+  }
+  const followupCard = (r && r.created && r.followupCard) ? r.followupCard : null
+  log(`${k} → follow-up ${followupCard || '(deferred to skill)'} (nothing dropped).`)
+  return { status: 'followup', followupCard, reason, outOfScopeFindings: oos || [] }
 }