baldart 4.12.0 → 4.14.0

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/agents/coding-standards.md

@@ -91,8 +91,8 @@ if (error) {
 > **SSOT.** This section is the canonical policy for reference-aliasing mutation
 > hazards. It is cited as the source of truth by `coder.md`
 > (§ Reference-Aliasing Mutation Hazards), `code-reviewer.md` (review checklist),
-> and `.claude/skills/new/SKILL.md` (Phase 2.5 step 5c deterministic detector +
-> Phase 3.7 trigger #6). When those files cite "§ Reference-Aliasing Mutation
+> and `.claude/skills/new/references/{completeness,codex-gate}.md` (Phase 2.5 step 5c
+> deterministic detector + Phase 3.7 gate). When those files cite "§ Reference-Aliasing Mutation
 > Patterns", they mean this section.
 
 ### The hazard
@@ -165,10 +165,10 @@ the helper's JSDoc so future editors find the contract.
 - **This section** — full policy + JSDoc contract + remediation menu.
 - `coder.md § Reference-Aliasing Mutation Hazards` — pre-implementation check.
 - `code-reviewer.md` review checklist — flags un-guarded patterns at review time.
-- `.claude/skills/new/SKILL.md § Phase 2.5 step 5c` — deterministic detector
-  that flags un-guarded patterns as `[ALIAS-MUTATION] BLOCKER` in
+- `.claude/skills/new/references/completeness.md § Phase 2.5 step 5c` — deterministic
+  detector that flags un-guarded patterns as `[ALIAS-MUTATION] BLOCKER` in
   `## Issues & Flags`.
-- `.claude/skills/new/SKILL.md § Phase 3.7 trigger #6` — a mutation-after-helper
+- `.claude/skills/new/references/codex-gate.md § Phase 3.7` — a mutation-after-helper
   call invokes a per-card adversarial cross-model review before commit.
 
 ## Commit Message Format

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.12.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; }