baldart 4.13.0 → 4.14.0

package/CHANGELOG.md

@@ -5,7 +5,21 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [4.13.0] - 2026-06-04
+## [4.14.0] - 2026-06-04
+
+**Nuovo tipo di payload `.claude/workflows/` (dynamic workflow di Claude Code) + il primo workflow `new-final-review`: la Final Review F.2–F.4 di `/new` può girare come script di orchestrazione deterministico, opt-in e con fallback inline.** I dynamic workflow (research-preview di Claude Code) spostano l'orchestrazione fan-out fuori dal context-window dell'orchestrator, nel codice. Una review avversariale ha **refutato** l'idea di farne il motore *per-card* di `/new` (rompe la portabilità Codex — sono Claude-only; dipende da una preview come breaking change; duplica la logica di gate col team-mode; introduce attrito-permessi e regressione di recovery proprio dove `/new` è più intrecciata con worktree/git/stato). Il bersaglio scelto è invece la parte dove i rischi spariscono e il valore resta: la **Final Review F.1–F.6** è **read-only** (gli agenti leggono solo il diff committato), ha **definizione SSOT unica** condivisa da sequential e team mode (→ nessun twin), e ha l'**adversarial-verify già nativo** (FP-check di Codex in F.3, cross-validation `code-reviewer` a confidence<80 in F.4). **MINOR** (nuova capability additiva: nuovo payload type + un workflow; nessun breaking change, nessuna chiave `baldart.config.yml` — il gating è runtime via presenza del tool `Workflow`; i consumer senza workflow o Codex-only eseguono la Final Review inline come prima).
+
+> **Why.** La Final Review è l'unica fase di `/new` con una definizione singola condivisa da entrambe le modalità e senza ownership di stato git o gate-utente: estrarla in un workflow non duplica nulla e non regredisce nulla. Il confine è netto — il workflow incapsula **F.2 (baseline) + F.3 (fan-out Codex ‖ doc-reviewer ‖ api-perf-cost-auditor ‖ qa-sentinel) + F.4 (consolidamento + verifica)** e ritorna i finding già classificati (`VERIFIED`/`NEEDS_MANUAL_CONFIRMATION`, `FALSE_POSITIVE` scartati) + la gate table; **F.1 (scope), F.5 (apply fix + build + `AskUserQuestion`) e F.6 (wrap-up) restano nella skill**, perché un workflow non può eseguire git né chiedere all'utente. La prosa di `final-review.md` resta SSOT e fallback sempre-disponibile; il workflow ne mirrora solo la *forma di orchestrazione* (i suoi agent-brief citano il modulo per la *semantica* di review). Distribuzione: symlink per-item come skill/agent/command, ma **senza overlay** (l'overlay-merger è per `.md`; un `.js` non ha sezioni markdown) e **solo per Claude** (`codex.js` ritorna `workflowsDir()=null` → mai linkato in un albero Codex).
+
+### Added
+
+- **`framework/.claude/workflows/new-final-review.js`** (nuovo) — workflow `meta.name: 'new-final-review'`, phases `Baseline`/`Review`/`Verify`. Fan-out F.2–F.4 con fallback Codex→`code-reviewer` come branch JS, schema sui finding (`VERIFIED`/`FALSE_POSITIVE`/`NEEDS_MANUAL_CONFIRMATION`), `api-perf-cost-auditor` saltato via branch quando non ci sono file API/data. Tutto da `args` (portabile, anti-contaminazione).
+- **Payload type `.claude/workflows/`** — `src/utils/tool-adapters/claude.js` espone `workflowsDir()='.claude/workflows'`; `codex.js` `workflowsDir()=null` (Claude-only). `src/utils/symlinks.js`: `_mergeBulkDir` generalizzato con mappa per-kind (`MERGE_KINDS`: estensione + overlay on/off), nuovo `mergeWorkflows()`, chiamato in `createAllSymlinks()` e nel reconcile di `update.js`; `verifySymlinks()` esteso a `workflows`. `BALDART_MANAGED_PATTERNS` (`update.js`) include `workflows`. `doctor.js`: probe + repair advisory dei workflow non linkati (Claude-only, non bloccante).
+- **`framework/docs/WORKFLOWS.md`** (nuovo) — cos'è il payload `.claude/workflows/`, il modello opt-in + degradazione, il perché Claude-only e no-overlay.
+
+### Changed
+
+- **`framework/.claude/skills/new/references/final-review.md`** — nuovo **Step F.1.5 (workflow delegation gate)**: se il tool `Workflow` è disponibile e `new-final-review.js` è linkato → delega F.2–F.4 al workflow e porta i finding/gate-table a F.5; altrimenti inline come prima (prosa = SSOT/fallback). Drift-note per i maintainer. `SKILL.md` § Routing annota la delega.
 
 **Il SKILL.md di `/new` scende da 61k a ~10k token (−82%) — il dettaglio passo-passo di ogni fase è uscito dal corpo skill (prefisso di sistema, ri-letto a ogni turno) in moduli `references/*.md` caricati on-demand.** Diagnosi data-driven su una run reale (`/new` su ~4 card → 480k token di contesto): forensics sul transcript dell'orchestrator → il **floor statico è 152k token PRIMA che parta una card**, e il colpevole #1 è il SKILL.md monolitico da **2766 righe / 61k token**, residente nel prefisso di sistema cached e ri-validato a ogni turno (362 turni nella run osservata). Una prima ipotesi ovvia (comprimere la *prosa* degli agent, stile "caveman") è stata **misurata e scartata**: la prosa è ~8k = 2% del totale. La cura replica 1:1 il pattern già in prod su `/prd` (core snello + reference modules + routing table): il core tiene solo gli invarianti cross-fase (Context Tracking, Progress Visibility, § Context economy, Agent Routing, QA Profile, Trivial fast-lane, Risk-signal detector, Fix Application Log) + una **§ Routing** che mappa fase→modulo→skip; ogni fase carica il suo modulo via Read quando ci entra. Contenuto spostato **verbatim** (zero cambi comportamentali; le stesse fasi/gate, nello stesso ordine). **MINOR** (refactor capability-neutral + nuovo contratto interno di module-loading on-demand; install-contract e invocazione invariati, consumer auto-aggiornati via directory-symlink; nessuna chiave `baldart.config.yml`, nessuna modifica CLI).
 

package/README.md

@@ -339,6 +339,7 @@ your-project/
 │   ├── agents/             # Symlink → .framework/.claude/agents/
 │   ├── commands/           # Symlink → .framework/.claude/commands/
 │   ├── skills/             # Per-item merge dir (v2.1.1+): framework symlinks alongside your own skills
+│   ├── workflows/          # Per-item symlinks of framework dynamic workflows (v4.14.0+, Claude-only)
 │   └── hooks/              # Customizable copies
 ├── baldart.config.yml      # Project context: paths/identity/stack/features (v3.0.0+)
 ├── .baldart/
@@ -427,6 +428,7 @@ Files with symlinks auto-update when framework updates:
 - `agents/`
 - `.claude/agents/`
 - `.claude/commands/`
+- `.claude/workflows/` (v4.14.0+) — framework dynamic workflows, per-item symlinks (Claude-only; no Codex equivalent)
 
 Files managed by the CLI:
 

package/VERSION

@@ -1 +1 @@
-4.13.0
+4.14.0

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

@@ -268,7 +268,7 @@ mappa di navigazione.
 | 2.55 / 2.6 / 3 / 3.5 — Simplify + E2E + Doc + QA | dopo AC-Closure | [`references/review-cycle.md`](references/review-cycle.md) | `IS_TRIVIAL`→skip 2.55+3.5; `has_e2e_review:false`/backend-only→skip 2.6; `light`+no-doc-diff→Doc a Final; `balanced`→QA a Final |
 | 3.7 — Pre-Merge Codex Review Gate | pre-commit | [`references/codex-gate.md`](references/codex-gate.md) | solo `IS_TRIVIAL` (altrimenti unconditional; `light`/`full` è DEPTH, non skip) |
 | 4-5 — Commit + Context Clean | fine card | [`references/commit.md`](references/commit.md) | — |
-| Final review F.1-F.6 | dopo l'ultima card | [`references/final-review.md`](references/final-review.md) | mai (FULL gate unconditional) |
+| Final review F.1-F.6 | dopo l'ultima card | [`references/final-review.md`](references/final-review.md) | mai (FULL gate unconditional). **F.2–F.4 delegate al workflow `new-final-review` se il tool `Workflow` è disponibile (Step F.1.5); altrimenti inline.** F.5/F.6 sempre nella skill. |
 | 6 / 6b / 6c — Merge & cleanup | dopo Final | [`references/merge-cleanup.md`](references/merge-cleanup.md) | mai (BLOCKING) |
 | 7 — Production Readiness | dopo il merge | [`references/production-readiness.md`](references/production-readiness.md) | — |
 | 8 — Metrics Log | ultimo | [`references/metrics.md`](references/metrics.md) | mai (non-blocking, best-effort) |

package/framework/.claude/skills/new/references/final-review.md

@@ -46,6 +46,51 @@ Once ALL cards are committed in the worktree:
    batch diff, so cards reviewed at `light` in Phase 3.7 still get a guaranteed full review before
    merge. Record the union in the tracker; downstream F.3 reviews it in full.
 
+### Step F.1.5 — Workflow delegation gate (v4.14.0 — opt-in, additive)
+
+The fan-out of F.2–F.4 (architecture baseline + multi-agent review + finding
+consolidation/verification) is a **read-only** pass — it reads the committed batch
+diff and emits findings, it touches no git state and asks the user nothing. That
+makes it a clean fit for a **dynamic workflow**, which runs the fan-out as a
+deterministic script outside this orchestrator's context window.
+
+**Branch (decide once, here):**
+
+- **IF** the `Workflow` tool is available to you **AND** the script
+  `.claude/workflows/new-final-review.js` is present (linked by the framework on
+  Claude-enabled installs) → **delegate F.2–F.4** to it:
+
+  ```
+  Workflow({ name: 'new-final-review', args: {
+    firstCardId, worktreePath, baseBranch,        // from Phase 0 / tracker
+    cardPaths,                                     // backlog YAML paths
+    reviewScopeFiles,                              // the FULL union from F.1
+    archBaselinePaths,                             // per-card baselines if ALL present (F.2 dedup), else null
+    hasApiDataFiles,                               // true unless NO scope file falls under paths.api_* / data-model
+    config                                         // the parsed baldart.config.yml
+  }})
+  ```
+
+  The workflow returns `{ codexEngine, findings, gateTable, summary }` where
+  `findings` are already consolidated and classified (`VERIFIED` /
+  `NEEDS_MANUAL_CONFIRMATION`; `FALSE_POSITIVE` already dropped) and `gateTable`
+  is the qa-sentinel PASS/FAIL/SKIP table. **Skip the inline F.2/F.3/F.4 below**
+  and carry those results straight into **Step F.5** (fix application + final
+  build + the `AskUserQuestion` gates — which stay HERE, in the skill, because a
+  workflow cannot prompt the user). Log `f.final: delegated to new-final-review
+  workflow (engine: <codexEngine>)` in the tracker.
+
+- **ELSE** (no `Workflow` tool — older Claude Code, `disableWorkflows`, or a
+  Codex install where workflows have no equivalent) → run the **inline F.2–F.4
+  below exactly as written**. This prose is the SSOT and the always-available
+  fallback; the workflow is only an accelerator that mirrors it.
+
+> **Drift note (maintainers):** `new-final-review.js` encodes only the
+> *orchestration shape* of F.2–F.4; its agent briefs cite THIS module for the
+> review *semantics*, so the SSOT for what each reviewer checks stays here. When
+> you change the F.2–F.4 reviewer set, gates, or classification rules, update the
+> workflow's phase/agent wiring to match.
+
 ### Step F.2 — Architecture baseline
 
 5. **Reuse per-card baselines before re-spawning (dedup).** Phase 1 step 5b already persisted one

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

@@ -0,0 +1,215 @@
+export const meta = {
+  name: 'new-final-review',
+  description:
+    "Cross-batch final code review for /new. Fans out a multi-agent review (Codex primary + doc-reviewer + api-perf-cost-auditor + qa-sentinel gates) over the WHOLE batch diff, then adversarially verifies low-confidence findings. Read-only: it returns classified findings and a gate table, and applies NO fixes (the calling skill owns fix application + user gates). Maps to references/final-review.md steps F.2–F.4.",
+  phases: [
+    { title: 'Baseline', detail: 'architecture grounding for the batch scope (F.2)' },
+    { title: 'Review', detail: 'parallel multi-agent review of the batch diff (F.3)' },
+    { title: 'Verify', detail: 'adversarial validation of low-confidence findings (F.4)' },
+  ],
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// args contract — supplied by the /new skill at F.1 (it owns git + tracker):
+//   firstCardId        string                first card id, for labels/ids
+//   worktreePath       string                the batch worktree
+//   baseBranch         string                trunk the diff is taken against
+//   cardPaths          string[]              backlog YAML paths (agents Read them)
+//   reviewScopeFiles   string[]              FULL union of touched files (F.1)
+//   archBaselinePaths  string[] | null       per-card baselines; null → spawn architect (F.2)
+//   hasApiDataFiles    boolean               gates api-perf-cost-auditor (default true)
+//   config             object                resolved baldart.config.yml (paths.*, …)
+//
+// Return value (consumed by the skill at F.5):
+//   { codexEngine, findings:[…classified, FALSE_POSITIVE dropped], gateTable, summary }
+// ───────────────────────────────────────────────────────────────────────────
+
+const a = args || {}
+const scope = Array.isArray(a.reviewScopeFiles) ? a.reviewScopeFiles : []
+const cards = Array.isArray(a.cardPaths) ? a.cardPaths : []
+const cfg = a.config || {}
+const highRisk = (cfg.paths && cfg.paths.high_risk_modules) || [] // security-domain hint
+const protocolRef = '.claude/skills/new/references/final-review.md'
+
+if (!scope.length) {
+  log('new-final-review: empty review scope — nothing to review.')
+  return { codexEngine: 'none', findings: [], gateTable: [], summary: emptySummary() }
+}
+
+// ---- Schemas ----------------------------------------------------------------
+const FINDING = {
+  type: 'object',
+  required: ['finding_id', 'title', 'severity', 'confidence', 'evidence', 'minimal_fix_direction', 'domain'],
+  additionalProperties: false,
+  properties: {
+    finding_id: { type: 'string', description: '<CARD-ID>-F### or <agent>-F###' },
+    title: { type: 'string' },
+    severity: { enum: ['BLOCKER', 'HIGH', 'MEDIUM', 'LOW'] },
+    confidence: { type: 'number', description: '0-100' },
+    evidence: { type: 'string', description: 'exact file:line + code quote' },
+    minimal_fix_direction: { type: 'string' },
+    domain: { enum: ['doc', 'security', 'migration', 'code', 'perf', 'test'], description: 'Domain-Override routing bucket' },
+  },
+}
+const FINDINGS_SCHEMA = {
+  type: 'object', required: ['findings'], additionalProperties: false,
+  properties: { findings: { type: 'array', items: FINDING }, note: { type: 'string' } },
+}
+const CODEX_SCHEMA = {
+  type: 'object', required: ['codexAvailable', 'findings'], additionalProperties: false,
+  properties: {
+    codexAvailable: { type: 'boolean', description: 'false if CODEX_NOT_FOUND / TIMED_OUT' },
+    findings: { type: 'array', items: FINDING },
+    note: { type: 'string' },
+  },
+}
+const GATES_SCHEMA = {
+  type: 'object', required: ['gates'], additionalProperties: false,
+  properties: {
+    gates: {
+      type: 'array',
+      items: {
+        type: 'object', required: ['gate', 'status'], additionalProperties: false,
+        properties: { gate: { type: 'string' }, status: { enum: ['PASS', 'FAIL', 'SKIP'] }, detail: { type: 'string' } },
+      },
+    },
+  },
+}
+const VERDICT_SCHEMA = {
+  type: 'object', required: ['classification'], additionalProperties: false,
+  properties: {
+    classification: { enum: ['VERIFIED', 'FALSE_POSITIVE', 'NEEDS_MANUAL_CONFIRMATION'] },
+    rationale: { type: 'string' },
+  },
+}
+
+// ---- Shared brief fragments -------------------------------------------------
+const scopeBrief = [
+  `Worktree: ${a.worktreePath || '(cwd)'}`,
+  `Base branch for the diff: ${a.baseBranch || '(trunk)'}`,
+  `Backlog cards (Read each for acceptance_criteria + entrypoints):\n${cards.join('\n') || '(none)'}`,
+  `Files changed — review ALL of these in full:\n${scope.join('\n')}`,
+].join('\n\n')
+
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Baseline (F.2) — reuse per-card baselines when present, else architect ×1
+// ───────────────────────────────────────────────────────────────────────────
+phase('Baseline')
+let baselineBrief
+const baselinePaths = Array.isArray(a.archBaselinePaths) ? a.archBaselinePaths.filter(Boolean) : []
+if (baselinePaths.length) {
+  // Pass-by-path (context economy): agents Read these on demand.
+  baselineBrief = `Architecture baseline files (Read each — file paths, type signatures, patterns, high-risk paths):\n${baselinePaths.join('\n')}`
+  log(`Baseline: reusing ${baselinePaths.length} per-card baseline file(s).`)
+} else {
+  const arch = await agent(
+    `You are grounding a post-implementation code review. Map the EXISTING architecture, critical patterns, and high-risk code paths relevant to this batch's changed files, so downstream reviewers can spot regressions.\n\n${scopeBrief}\n\nReturn a concise baseline (the key modules, their contracts, and the regression-prone seams touched by this diff). Do not review the changes yet.`,
+    { label: 'arch-baseline', phase: 'Baseline', agentType: 'codebase-architect',
+      schema: { type: 'object', required: ['baseline'], additionalProperties: false, properties: { baseline: { type: 'string' } } } }
+  )
+  baselineBrief = `Architecture baseline (from codebase-architect):\n${(arch && arch.baseline) || '(unavailable)'}`
+  log('Baseline: spawned codebase-architect (no per-card baselines supplied).')
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Review (F.3) — Codex primary ‖ doc-reviewer ‖ api-perf-cost-auditor ‖ qa-sentinel
+// ───────────────────────────────────────────────────────────────────────────
+phase('Review')
+
+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` +
+  `${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.`
+
+const docPrompt =
+  `Cross-card documentation + SSOT-registry review over the batch diff, per ${protocolRef} Step F.3 (doc-reviewer row). Check doc consistency, ssot-registry completeness, and invariants across the changed files.\n\n${scopeBrief}\n\n${baselineBrief}\n\nReturn findings (domain almost always "doc"). Use the finding schema fields.`
+
+const apiPrompt =
+  `API / data-model / performance / cost defect review over the batch diff, per ${protocolRef} Step F.3 (api-perf-cost-auditor row). Look for unbounded reads, N+1, missing pagination, contract drift, and cost regressions.\n\n${scopeBrief}\n\n${baselineBrief}\n\nReturn findings with domain in {code, perf, migration, security}. Use the finding schema fields.`
+
+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')}`
+
+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) {
+  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).')
+}
+
+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'
+for (const item of reviewResults) {
+  if (item.kind === 'codex') {
+    if (item.r && item.r.codexAvailable && Array.isArray(item.r.findings)) {
+      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 })))
+    }
+  } else if (item.kind === 'qa') {
+    gateTable = (item.r && item.r.gates) || []
+  } else if (item.r && Array.isArray(item.r.findings)) {
+    raw.push(...item.r.findings.map((f) => ({ ...f, source: item.kind, preValidated: false })))
+  }
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Phase Verify (F.4) — adversarial validation of low-confidence findings
+//   Codex findings are pre-FP-validated → VERIFIED. Claude-agent findings with
+//   confidence < 80 get a code-reviewer static validator; disagreement →
+//   NEEDS_MANUAL_CONFIRMATION (never silently dropped). High-confidence Claude
+//   findings pass through as VERIFIED.
+// ───────────────────────────────────────────────────────────────────────────
+phase('Verify')
+const classified = (await parallel(raw.map((f) => () => verifyFinding(f)))).filter(Boolean)
+
+async function verifyFinding(f) {
+  if (f.preValidated || (typeof f.confidence === 'number' && f.confidence >= 80)) {
+    return { ...f, classification: 'VERIFIED' }
+  }
+  const v = await agent(
+    `Adversarially validate this code-review finding as a static reviewer over the cited file:line. Default to FALSE_POSITIVE if the evidence does not hold; use NEEDS_MANUAL_CONFIRMATION only when you genuinely cannot decide from the code.\n\n` +
+      `finding_id: ${f.finding_id}\nseverity: ${f.severity}\ntitle: ${f.title}\nevidence: ${f.evidence}\ndomain: ${f.domain}\nsecurity-sensitive paths: ${highRisk.join(', ') || '(none configured)'}`,
+    { label: `verify:${f.finding_id}`, phase: 'Verify', agentType: 'code-reviewer', schema: VERDICT_SCHEMA }
+  )
+  return { ...f, classification: (v && v.classification) || 'NEEDS_MANUAL_CONFIRMATION' }
+}
+
+// ---- Result: drop FALSE_POSITIVE, keep VERIFIED + NEEDS_MANUAL (F.4 step 9) --
+const findings = classified.filter((f) => f.classification !== 'FALSE_POSITIVE')
+const summary = {
+  total: raw.length,
+  verified: classified.filter((f) => f.classification === 'VERIFIED').length,
+  falsePositive: classified.filter((f) => f.classification === 'FALSE_POSITIVE').length,
+  needsManual: classified.filter((f) => f.classification === 'NEEDS_MANUAL_CONFIRMATION').length,
+  blockers: classified.filter((f) => f.classification === 'VERIFIED' && f.severity === 'BLOCKER').length,
+  highs: classified.filter((f) => f.classification === 'VERIFIED' && f.severity === 'HIGH').length,
+  failingGates: gateTable.filter((g) => g.status === 'FAIL').map((g) => g.gate),
+}
+log(`Final review done: ${summary.verified} verified (${summary.blockers} BLOCKER / ${summary.highs} HIGH), ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s). Engine: ${codexEngine}.`)
+
+return { codexEngine, findings, gateTable, summary }
+
+function emptySummary() {
+  return { total: 0, verified: 0, falsePositive: 0, needsManual: 0, blockers: 0, highs: 0, failingGates: [] }
+}

package/framework/docs/WORKFLOWS.md

@@ -0,0 +1,62 @@
+# Dynamic Workflows (`.claude/workflows/`)
+
+**Since v4.14.0.** BALDART can ship Claude Code **dynamic workflows** — JavaScript
+orchestration scripts that fan out subagents at scale, with the plan held in code
+(deterministic branches/loops) instead of in the orchestrator's context window.
+They are distributed as a new per-item payload under `.claude/workflows/`.
+
+This is an **opt-in accelerator**, never a hard dependency. Every skill that
+delegates to a workflow keeps a complete inline fallback, so a repo where
+workflows are unavailable behaves exactly as before.
+
+## What ships today
+
+| 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). |
+
+## How distribution works
+
+- **Per-item symlink**, same model as `.claude/skills/`, `.claude/agents/`,
+  `.claude/commands/`: each framework `<name>.js` under
+  `.framework/framework/.claude/workflows/` is symlinked into the consumer's
+  `.claude/workflows/<name>.js`. `baldart add` / `update` / `doctor` create and
+  reconcile these links.
+- **Claude-only.** Dynamic workflows are a Claude Code runtime feature with no
+  OpenAI Codex equivalent. The Codex tool adapter returns `workflowsDir() = null`,
+  so workflow scripts are never linked into a Codex tree. Codex consumers (and any
+  Claude consumer with workflows disabled) run the delegating skill's inline path.
+- **No overlay.** Overlays are a markdown construct (`## [OVERRIDE]` sections + an
+  HTML-comment marker) and do not apply to `.js`. Workflows are distributed as
+  plain symlinks; customise the *delegation decision* in the skill/overlay layer,
+  not the script.
+- **Contamination-scanned.** The `framework-edit-gate` hook scans workflow `.js`
+  content by path (not extension), so a hardcoded project path or identity token
+  in a workflow is blocked exactly like in any other framework file. Workflows
+  must read all project-specific facts from their `args` (passed by the skill from
+  `baldart.config.yml`), never hardcode them.
+
+## The opt-in / degradation contract
+
+A delegating skill decides **at runtime**, with no new `baldart.config.yml` key:
+
+1. **IF** the `Workflow` tool is available to the model **AND** the workflow
+   script is linked → call `Workflow({ name, args })` and use its return value.
+2. **ELSE** → run the skill's inline fallback (the prose remains the SSOT).
+
+There is deliberately no `features.use_workflows` flag: workflow availability is a
+property of the Claude Code session (research-preview, plan tier, the native
+`disableWorkflows` setting), not a fact the repo can record. Force-disabling is the
+native Claude Code toggle; the skill simply detects and degrades.
+
+## Authoring notes (maintainers)
+
+- A workflow script begins with a pure-literal `export const meta = { name,
+  description, phases }`, then a body using `agent()` / `parallel()` / `pipeline()`
+  / `phase()` / `log()` and the `args` / `budget` globals.
+- The script cannot run bash/git/fs — only its agents can. Keep anything that
+  needs git, shared state, or a user prompt in the calling skill; give the
+  workflow the read-only fan-out.
+- Single-source the *semantics*: a workflow's agent briefs should cite the skill's
+  reference module for what each agent checks, so the workflow encodes only the
+  *orchestration shape*. Carry a drift note in the reference module.

package/package.json

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

package/src/commands/doctor.js

@@ -292,6 +292,37 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on probe */ }
 
+    // ---- Workflow symlink integrity (since v4.14.0) --------------------
+    // Dynamic workflows (.js) are Claude-only and per-item symlinked into
+    // `.claude/workflows/`. Unlike agents there is NO hard discovery gate —
+    // a missing workflow just makes the consuming skill fall back to its
+    // inline path (e.g. /new's Final Review) — so this is advisory self-heal,
+    // not a blocker. Gated on `claude` being enabled (workflows have no Codex
+    // equivalent, so a Codex-only install must not be flagged).
+    state.workflowSymlinksBroken = [];
+    try {
+      if (state.frameworkPresent) {
+        const toolsEnabled = (config && !config.__malformed && config.tools && Array.isArray(config.tools.enabled))
+          ? config.tools.enabled : ['claude'];
+        if (toolsEnabled.includes('claude')) {
+          const frameworkWorkflowsDir = path.join(cwd, '.framework', 'framework', '.claude', 'workflows');
+          const consumerWorkflowsDir = path.join(cwd, '.claude', 'workflows');
+          if (fs.existsSync(frameworkWorkflowsDir)) {
+            const baldartWorkflows = fs.readdirSync(frameworkWorkflowsDir)
+              .filter((f) => f.endsWith('.js') && !f.startsWith('.'))
+              .map((f) => f.replace(/\.js$/, ''));
+            for (const name of baldartWorkflows) {
+              try {
+                fs.statSync(path.join(consumerWorkflowsDir, `${name}.js`));
+              } catch (_) {
+                state.workflowSymlinksBroken.push(name);
+              }
+            }
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on probe */ }
+
     // `.framework/` is a git subtree — gitignore matching it breaks every
     // future `git add` under that path (the failure mode that hit v3.13.0
     // consumers during push). Detect any gitignore rule that catches the
@@ -584,6 +615,29 @@ function planActions(state) {
     });
   }
 
+  // Workflow symlink integrity (since v4.14.0). Advisory — a missing workflow
+  // symlink degrades the consuming skill to its inline path, it does not block.
+  // Re-runs only the workflow merge pass (same rationale as the agent repair).
+  if (state.workflowSymlinksBroken && state.workflowSymlinksBroken.length > 0) {
+    actions.push({
+      key: 'repair-workflow-symlinks',
+      label: `Link ${state.workflowSymlinksBroken.length} framework workflow(s)`,
+      why: `These framework dynamic workflows are not linked into .claude/workflows/: ${state.workflowSymlinksBroken.join(', ')}. Skills that delegate to them (e.g. /new's Final Review) fall back to their inline path until the symlinks exist — not a failure, but you lose the workflow acceleration.`,
+      autoOk: true,
+      run: async () => {
+        const SymlinkUtils = require('../utils/symlinks');
+        const cfg = loadConfig(process.cwd());
+        const enabledTools = (cfg && !cfg.__malformed
+          && cfg.tools && Array.isArray(cfg.tools.enabled))
+          ? cfg.tools.enabled
+          : ['claude'];
+        const symlinks = new SymlinkUtils();
+        symlinks.mergeWorkflows({ tools: enabledTools });
+        UI.success(`Linked framework workflows for tools: ${enabledTools.join(', ')}`);
+      },
+    });
+  }
+
   if (state.lspEnabled && state.lspBroken && state.lspBroken.length > 0) {
     actions.push({
       key: 'lsp-fix',

package/src/commands/update.js

@@ -103,7 +103,7 @@ const BALDART_MANAGED_PATTERNS = [
   /^\.framework(\/|$)/,
   /^AGENTS\.md$/,
   /^agents(\.backup)?(\/|$)/,
-  /^\.claude\/(agents|commands|skills|hooks|routines|settings\.json)(\/|$)/,
+  /^\.claude\/(agents|commands|skills|workflows|hooks|routines|settings\.json)(\/|$)/,
   /^\.baldart(\/|$)/,
   /^baldart\.config\.yml$/,
   /^docs\/references\/(ui-guidelines\.template\.md|brand-guidelines\.md)$/,
@@ -1180,6 +1180,7 @@ async function update(options = {}, unknownArgs = []) {
       symlinks.mergeSkills({ tools: enabledTools });
       symlinks.mergeAgents({ tools: enabledTools });
       symlinks.mergeCommands({ tools: enabledTools });
+      symlinks.mergeWorkflows({ tools: enabledTools });
     }
 
     // Routines wizard (since v2.1.0) — surfaces routines added in the new framework version

package/src/utils/symlinks.js

@@ -12,6 +12,22 @@ const FRAMEWORK_DIR = '.framework';
 const FRAMEWORK_PAYLOAD = path.join(FRAMEWORK_DIR, 'framework');
 const CONFLICT_LOG = path.join('.baldart', 'skill-conflicts.json');
 
+// Per-item merge kinds whose framework source is a flat directory of single
+// files under `.claude/<kind>s/`. Each entry declares:
+//   - dirGetter: the adapter method returning the consumer-side target dir
+//     (null when the tool doesn't support the kind, e.g. Codex → workflows).
+//   - ext:       the file extension of the source items.
+//   - overlay:   whether the base+overlay generation path applies. Overlays
+//     are a markdown construct (`## [OVERRIDE]` sections + HTML-comment
+//     marker), so they only make sense for `.md` kinds. Workflows are `.js`
+//     and are distributed as plain per-item symlinks — no overlay.
+//   - exclude:   filenames in the source dir that are NOT installable items.
+const MERGE_KINDS = {
+  agent:    { dirGetter: 'agentsDir',    ext: '.md', overlay: true,  exclude: new Set(['REGISTRY.md']) },
+  command:  { dirGetter: 'commandsDir',  ext: '.md', overlay: true,  exclude: new Set(['REGISTRY.md']) },
+  workflow: { dirGetter: 'workflowsDir', ext: '.js', overlay: false, exclude: new Set() },
+};
+
 /**
  * Symlink management for BALDART.
  *
@@ -325,6 +341,10 @@ class SymlinkUtils {
     UI.section('Merging Framework Commands');
     this.mergeCommands({ tools: opts.tools });
 
+    UI.newline();
+    UI.section('Merging Framework Workflows');
+    this.mergeWorkflows({ tools: opts.tools });
+
     UI.newline();
   }
 
@@ -339,15 +359,20 @@ class SymlinkUtils {
 
   mergeAgents(opts = {}) { return this._mergeBulkDir('agent', opts); }
   mergeCommands(opts = {}) { return this._mergeBulkDir('command', opts); }
+  mergeWorkflows(opts = {}) { return this._mergeBulkDir('workflow', opts); }
 
   /**
    * Generic per-item merge for kinds whose framework source is a directory
-   * of single .md files (agents, commands). For each enabled tool whose
-   * adapter declares a target directory (claude.agentsDir(), etc.), this
-   * either symlinks each base file or — when an overlay exists — writes a
-   * generated real file with the overlay applied.
+   * of single files (agents/commands → .md, workflows → .js). For each
+   * enabled tool whose adapter declares a target directory
+   * (claude.agentsDir(), claude.workflowsDir(), …), this symlinks each base
+   * file or — for overlay-capable `.md` kinds with an overlay present —
+   * writes a generated real file with the overlay applied. Workflows are
+   * `.js` and overlay-free, so they always take the plain-symlink path.
    */
   _mergeBulkDir(kind, opts = {}) {
+    const cfg = MERGE_KINDS[kind];
+    if (!cfg) throw new Error(`_mergeBulkDir: unknown kind '${kind}'`);
     const tools = (opts.tools && opts.tools.length) ? opts.tools : ['claude'];
     const aggregate = { linked: [], generated: [], skipped: [], conflicts: [], warnings: [] };
     const { getAdapter } = require('./tool-adapters');
@@ -359,20 +384,20 @@ class SymlinkUtils {
     }
 
     const fwItems = fs.readdirSync(fwSourceDir)
-      .filter((n) => n.endsWith('.md') && !n.startsWith('.') && n !== 'REGISTRY.md');
+      .filter((n) => n.endsWith(cfg.ext) && !n.startsWith('.') && !cfg.exclude.has(n));
 
     const frameworkVersion = this._readFrameworkVersion();
 
     for (const tool of tools) {
       const adapter = getAdapter(tool, this.cwd);
-      const dirGetter = kind === 'agent' ? adapter.agentsDir : adapter.commandsDir;
-      const targetRel = dirGetter ? dirGetter.call(adapter) : null;
-      if (!targetRel) continue; // tool doesn't support this kind (e.g. Codex)
+      const dirGetter = adapter[cfg.dirGetter];
+      const targetRel = (typeof dirGetter === 'function') ? dirGetter.call(adapter) : null;
+      if (!targetRel) continue; // tool doesn't support this kind (e.g. Codex → workflows)
 
       this.ensureDirectory(targetRel);
 
       for (const filename of fwItems) {
-        const baseName = filename.replace(/\.md$/, '');
+        const baseName = filename.slice(0, -cfg.ext.length);
         const linkPath = path.join(this.cwd, targetRel, filename);
         const fwAbsolute = path.join(fwSourceDir, filename);
 
@@ -384,7 +409,7 @@ class SymlinkUtils {
 
         const overlayRel = path.join('.baldart', 'overlays', `${kind}s`, filename);
         const overlayAbs = path.join(this.cwd, overlayRel);
-        const hasOverlay = fs.existsSync(overlayAbs);
+        const hasOverlay = cfg.overlay && fs.existsSync(overlayAbs);
 
         // Inspect what currently lives at the link path (if anything).
         let lstat = null;
@@ -474,7 +499,10 @@ class SymlinkUtils {
       aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
       return;
     }
-    UI.warning(`[${adapter.label}] ${kind} name conflict (user file at ${path.join(targetRel, filename)}). Framework version NOT installed. Move user content to .baldart/overlays/${kind}s/${filename} to specialize without losing upstream updates.`);
+    const specializeHint = MERGE_KINDS[kind] && MERGE_KINDS[kind].overlay
+      ? ` Move user content to .baldart/overlays/${kind}s/${filename} to specialize without losing upstream updates.`
+      : ` Rename your local ${kind} to keep both.`;
+    UI.warning(`[${adapter.label}] ${kind} name conflict (user file at ${path.join(targetRel, filename)}). Framework version NOT installed.${specializeHint}`);
     aggregate.conflicts.push({
       tool: adapter.name, kind, name: baseName,
       local_path: path.join(targetRel, filename),
@@ -647,7 +675,8 @@ class SymlinkUtils {
       }
 
       // v3.8.0+: agents and commands also use per-item merge with overlay support.
-      for (const [kindGetter, kindLabel] of [['agentsDir', 'agents'], ['commandsDir', 'commands']]) {
+      // v4.14.0+: workflows (.js) use the same per-item merge, overlay-free.
+      for (const [kindGetter, kindLabel] of [['agentsDir', 'agents'], ['commandsDir', 'commands'], ['workflowsDir', 'workflows']]) {
         if (typeof adapter[kindGetter] !== 'function') continue;
         const rel = adapter[kindGetter]();
         if (!rel) continue;

package/src/utils/tool-adapters/claude.js

@@ -5,6 +5,7 @@
  *   - `.claude/skills/<skill>/SKILL.md`           (skills, per-item symlinks)
  *   - `.claude/agents/<agent>.md`                 (subagents, bulk symlink)
  *   - `.claude/commands/<command>.md`             (slash commands, bulk symlink)
+ *   - `.claude/workflows/<workflow>.js`           (dynamic workflows, per-item symlinks)
  *   - `.claude/settings.json`                     (hooks, ide config)
  *   - `AGENTS.md`                                 (root coordination protocol)
  *
@@ -27,6 +28,9 @@ class ClaudeAdapter {
   /** Where this tool reads slash commands from (null if unsupported). */
   commandsDir() { return '.claude/commands'; }
 
+  /** Where this tool reads dynamic workflow scripts from (null if unsupported). */
+  workflowsDir() { return '.claude/workflows'; }
+
   /** Whether this tool consumes subagent definitions (`.claude/agents/`). */
   supportsSubagents() { return true; }
 

package/src/utils/tool-adapters/codex.js

@@ -40,6 +40,12 @@ class CodexAdapter {
   agentsDir() { return null; }
   commandsDir() { return null; }
 
+  // Codex has no equivalent of Claude Code dynamic workflows (the JS
+  // orchestration runtime is Claude-only). Returning null disables the
+  // per-item workflow merge for Codex — the same source workflow scripts are
+  // simply never linked into a Codex tree.
+  workflowsDir() { return null; }
+
   supportsSubagents() { return false; }
   supportsSlashCommands() { return false; }
   supportsHooks() { return false; }