baldart 4.99.0 → 5.0.0

package/framework/agents/review-protocol.md

@@ -0,0 +1,207 @@
+# Review Protocol — the shared verification engine for BALDART reviewers
+
+**Purpose**: the anti-hallucination and calibration passes every reviewer runs
+— Challenge, Actionability, Simulation, Chain-of-Verification, quantified risk
+scoring, specialist-spawn discipline — used to be duplicated (and drifting)
+across `code-reviewer` and `plan-auditor`, with partial copies in
+`security-reviewer` / `api-perf-cost-auditor`. This module is their **single
+SSOT** (v5.0.0). Each reviewer keeps a 1-line BINDING version of every pass
+inline and cites the matching section here for the full procedure. On
+divergence, **this module wins**.
+
+**What stays in the agent bodies, never here**: the pooled findings YAML
+schema, verdict-line formats, severity never-demote lists, per-domain
+checklists, spawn MATRICES (which specialist for which signal), and report
+caps — those are I/O contracts and domain knowledge, not procedure.
+
+**Consumers**: `code-reviewer`, `plan-auditor`, `security-reviewer`,
+`api-perf-cost-auditor` (body citations); `doc-reviewer` cites
+`SECTION=challenge` for its findings hygiene.
+
+## Contract
+
+- **Dispatch**: agents cite `agents/review-protocol.md SECTION=<challenge|simulation|cove|risk-scoring|specialist-spawn>`.
+  Grep for `### SECTION: <name>` and Read ONLY that section.
+- **Order of passes** (normative): generate findings → **challenge** →
+  **simulation** (already-generated `simulation_failure` hypotheses included) →
+  **cove** on every survivor → **risk-scoring** → report. Specialist spawns
+  happen early (parallel with your own review); their findings enter YOUR
+  challenge + CoVe passes like your own.
+- **Degrade-safe**: skipping a pass means less rigor, never a malformed report
+  — the report shape is defined in the agent body.
+
+---
+
+### SECTION: challenge
+
+**Challenge Pass** (before reporting). For EACH HIGH and MEDIUM finding ask:
+
+> "What is the strongest argument that this is a false positive?"
+
+Consider:
+- Is this already handled elsewhere in the codebase?
+- Is this a project convention I'm unfamiliar with (check the agent memory
+  false-positive list)?
+- Is the issue intentionally deferred to a later card per `notes` / card scope?
+- Am I applying a generic best practice that doesn't fit this context?
+
+**Suppress** the finding if the FP argument is convincing, and record it:
+
+```markdown
+<details>
+<summary>Suppressed findings (N items — challenge pass)</summary>
+- **Finding title** — FP argument: <why suppressed>
+</details>
+```
+
+**Never-demote guard**: items on the agent's never-demote list (each reviewer
+declares its own inline) are NEVER false positives — do not suppress them,
+regardless of how convincing the FP argument sounds.
+
+**Actionability Pass** (after the FP challenge). A finding that survives the
+challenge can still need NO change — the code/plan is fine as-is and the only
+honest "fix" is "acceptable as-is / verified safe". That is a **cleared
+concern, not a finding**: a downstream fixer spawned on it would no-op. Either
+omit it, or — when the pooled schema exposes `requires_action` — set
+`requires_action: false` (recorded, never routed to a writer). Record cleared
+concerns separately:
+
+```markdown
+<details>
+<summary>Verified, no action (N items)</summary>
+- **Title** — why it is safe as-is
+</details>
+```
+
+Guard: actionability applies to MEDIUM/LOW only — a BLOCKER/HIGH is never
+"no action". And if a change IS needed but is out of your scope, that is NOT
+no-action: report it as a real finding (it surfaces as residual).
+
+### SECTION: simulation
+
+Walk the artifact as if you were the runtime (diff) or the implementing
+engineer (plan). Emit findings of type `simulation_failure` with the exact
+breaking point and the broken invariant.
+
+**Diff variant** (code review) — for each non-trivial changed
+function/handler:
+1. **Input boundary**: feed it the messiest realistic input (empty, null,
+   malformed JSON, oversized payload, malicious script, expired token,
+   concurrent request from the same user). Where does it break first?
+2. **State machine consistency**: if the change mutates persistent state (DB,
+   session/local storage, cookies), trace the state at each branch — does any
+   branch leave inconsistent state?
+3. **Reversibility**: if the function fails mid-execution, can the partial
+   side effects be rolled back? A transactional/atomic write is OK; a sequence
+   of independent writes without a transaction wrapper is NOT.
+4. **Concurrent runs**: two parallel requests on the same resource — where do
+   they collide?
+5. **Loop boundary**: any `for`/`map` over unbounded data (collection without
+   limit, user-provided array)? Where does it explode?
+
+**Plan variant** (plan audit) — for each plan step:
+1. **Preconditions**: are all prerequisites from prior steps actually
+   satisfied at this point?
+2. **State machine consistency**: what is the shared state (record, env var,
+   feature flag) at this step — consistent with later steps' assumptions?
+3. **Reversibility**: if step N fails, can steps 1..N-1 roll back cleanly? If
+   not → `irreversible_step_without_safety_net`.
+4. **Concurrent runs**: two instances of this plan running simultaneously
+   (parallel cards, retry, multiple environments) — where do they collide?
+5. **External dependency clock**: async propagation (index build, DNS, CDN
+   purge, deploy) — is wait time accounted for?
+
+**Hypothesis discipline (BINDING)**: simulation is an LLM mental walk, NOT
+execution — every `simulation_failure` is a *hypothesis* until grounded.
+Each one MUST survive the CoVe pass below (grep/read the actual code path);
+set `cove_verified: true` only when the breaking branch is confirmed against
+real code. Drop any simulation claim you cannot ground — never ship an
+unverified "the runtime will break here" as HIGH.
+
+### SECTION: cove
+
+**Chain-of-Verification** (for every surviving HIGH/MEDIUM finding, after
+Challenge + Simulation). Generate 2–3 verification questions per finding and
+EXECUTE them via grep/read — this forces grounding of every citation in actual
+evidence.
+
+Example — finding "auth wrapper missing on POST handler at `<route-file>:45`"
+(`<auth-wrapper>` = the project's auth guard, resolve from
+`${paths.high_risk_modules}`):
+1. Does the file exist? → `test -f <route-file>`
+2. Is there really no auth import/wrapper? → `rg -n "<auth-wrapper>" <route-file>`
+3. Is the route actually public per docs? → `rg -l "<route-path>" ${paths.references_dir}/api/`
+
+Drop findings whose verification fails (the finding itself was wrong) and
+record them:
+
+```markdown
+### Hallucinated Findings Dropped (CoVe)
+- **Finding title** — Verification: `<command>` → `<result>` → dropped because <reason>
+```
+
+A finding whose evidence (file/line/quote) cannot be re-located verbatim is
+dropped, not "approximately relocated".
+
+### SECTION: risk-scoring
+
+**Quantified risk** (mandatory on every HIGH finding, and on risk-register
+rows):
+- **Impact** (1–5): 1 = cosmetic, 5 = data loss / security breach / production
+  outage.
+- **Likelihood** (1–5): 1 = theoretical only, 5 = will hit on first run.
+- **Priority** = Impact × Likelihood (1–25).
+
+Thresholds:
+- Priority ≥ 16 → automatic **BLOCKER**.
+- Priority 9–15 → confirms **HIGH**.
+- Priority < 9 → demote to MEDIUM — unless the item is on the agent's
+  never-demote list.
+
+**Severity calibration (BINDING)**: severity is **ABSOLUTE, per finding,
+anchored to its evidenced consequence** — never a relative ranking, never a
+quota. Positional bands ("top 20% → HIGH") manufacture mandatory findings on
+clean artifacts and demote real defects on large batches; both are calibration
+failures. For each survivor ask: *"what happens if this ships / is implemented
+exactly as written?"* A HIGH MUST cite its evidence (file/field/line + the
+code path that proves it); no evidence citation → cap at MEDIUM. **Zero HIGH —
+or zero findings at all — on a clean artifact is a legitimate, reportable
+outcome.** Do not stretch severities to fill bands.
+
+### SECTION: specialist-spawn
+
+Procedure for the specialist auto-spawn matrices (each reviewer keeps its OWN
+matrix — signal → agent — inline; this section is the shared discipline):
+
+1. **Orchestrated-mode suppression (BINDING — check FIRST).** If your spawn
+   prompt or lean contract carries a `specialist_dispatch` block
+   (`{"suppress": [...], "owner": ...}`) — or the legacy
+   `skip_doc_reviewer: true` flag — you MUST NOT spawn any agent listed in
+   `suppress`. The orchestrator owns specialist routing on that run (it runs
+   those reviews itself in dedicated phases); a nested spawn would duplicate
+   the review, untracked. Record what you would have routed as a normal
+   finding tagged `dispatch_deferred: <agent>` and let the orchestrator route
+   it. **Standalone invocations (no dispatch block): the matrix applies
+   normally.**
+2. **At most once per specialist.** If a coordinating team has independently
+   spawned (or will spawn) a matched specialist on the same artifact, consume
+   its findings instead of re-spawning.
+3. **Parallel, single message** — spawn all matched specialists in one message
+   with multiple Task calls.
+4. **Structured returns**: instruct each specialist to return its structured
+   (Mode A / pooled YAML) findings schema, never free markdown — that is what
+   makes the merge lossless.
+5. **Merge with provenance**: fold their findings into YOUR findings output
+   with their `source: <agent>` preserved. Fill any schema field the
+   specialist did not populate from their evidence, or set `N/A` — never drop
+   a real finding because a field is missing.
+6. **Specialist findings pass through YOUR Challenge + CoVe** like your own.
+7. **Deduplicate ownership**: when a specialist owns a domain's depth (e.g.
+   security-reviewer on an auth diff), do not emit your own duplicate findings
+   for the same issues — cover only what the specialist did NOT raise. On a
+   severity conflict, the specialist's rating wins.
+8. **No generic substitution**: if a named specialist is unavailable, do NOT
+   substitute `general-purpose` or any generic agent — surface
+   `CAPABILITY_UNAVAILABLE: <agent>` in your verdict context and cover that
+   domain with your own persona checklist.
+9. Zero specialist signals → no spawn; declare it in the verdict context.

package/framework/routines/finding-mine.routine.yml

@@ -0,0 +1,56 @@
+name: finding-mine
+description: Monthly deep mining of pooled findings, QA reports, batch trackers and reviewer memories into classified improvement proposals — the anticipatory loop behind the weekly skill-improve.
+since_version: 5.0.0
+
+schedule:
+  cron: "0 3 1 * *"            # 1st of the month, 03:00 UTC (an hour after a weekly skill-improve slot)
+  timezone: UTC
+  jitter_minutes: 0
+  cadence_label: monthly
+
+agent: skill-improver
+
+prompt: |
+  MODE: miner
+
+  Run the monthly deep mining pass per `skill-improver.md § MODE: miner`:
+
+  1. Read the past 30 days of evidence — routine reports under `docs/reports/`
+     (including the month's weekly `*-skill-improve.md` and their Upstream
+     Candidates), `qa/*.md`, the `/new` batch trackers
+     (`$(git rev-parse --git-common-dir)/baldart/run/batch-tracker-*.md`,
+     mining `## Fix Application Log` incl. the `model=` fix-pass A/B outcomes
+     and `## Lessons Learned`), and the reviewer agent memories
+     (`.claude/agent-memory/{code-reviewer,plan-auditor,qa-sentinel}/MEMORY.md`).
+     Absent sources are skipped with a one-line note.
+  2. Produce CLASSIFIED proposals (each with ≥2 independent occurrences cited):
+     `author-time-coder-rule` | `never-demote-code-reviewer` |
+     `deterministic-gate-candidate` | `card-schema-field-proposal` (proposal
+     ONLY — never applied) | `upstream-candidate` (consolidated + deduplicated
+     from the weeklies; a weekly overlay fix that KEPT recurring escalates here
+     with the failed-fix evidence).
+  3. Apply at most 3 overlay edits yourself (the strongest, evidence-backed) —
+     write surface identical to the weekly pass: `.baldart/overlays/` + `docs/`
+     only, commits prefixed `[FINDING-MINE]`. Everything else stays a proposal.
+  4. Emit `docs/reports/{{YYYYMMDD}}-finding-mine.md` — proposals grouped by
+     class with evidence citations, confidence, and effort estimate.
+
+  Graceful degradation: no recurring pattern in the month → write a short
+  "no proposals" report and exit cleanly. Never edit framework files directly
+  (the framework-edit-gate denies it — the overlay is the write surface).
+
+output:
+  path: docs/reports/{{YYYYMMDD}}-finding-mine.md
+  commit:
+    enabled: true
+    prefix: "[FINDING-MINE]"
+    branch: main
+
+required_artifacts:
+  - docs/reports/
+  - .claude/agents/skill-improver.md
+
+backend_hints:
+  - claude-code-cloud
+  - github-actions
+  - cron

package/framework/routines/index.yml

@@ -89,3 +89,14 @@ routines:
       registry context, runs lint, and commits directly to the trunk (no PR).
       Optional (only runs when features.has_i18n is true and target languages
       are configured).
+
+  - name: finding-mine
+    file: finding-mine.routine.yml
+    cadence: monthly
+    since_version: 5.0.0
+    summary: |
+      Monthly deep mining pass (skill-improver MODE: miner) — 30 days of
+      pooled findings, QA reports, batch trackers and reviewer memories
+      distilled into classified proposals (author-time rules, never-demote
+      rows, deterministic-gate candidates, card-schema proposals, upstream
+      candidates). The anticipatory loop behind the weekly skill-improve.

package/package.json

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

package/src/commands/configure.js

@@ -1487,6 +1487,21 @@ async function configure(opts = {}) {
   fs.writeFileSync(outPath, serialize(merged), 'utf8');
   UI.success(`Wrote ${CONFIG_FILE}`);
 
+  // v5.0.0 — slot-generated agents depend on the flags just written (features.*,
+  // stack.database, …): re-run the agent merge so `.claude/agents/` reflects the
+  // new config immediately (closes the "config changed without update" gap).
+  // Fail-safe: configure must never die on a merge hiccup — doctor heals later.
+  try {
+    const SymlinkUtils = require('../utils/symlinks');
+    const enabledTools = (merged.tools && Array.isArray(merged.tools.enabled) && merged.tools.enabled.length)
+      ? merged.tools.enabled : ['claude'];
+    if (fs.existsSync(path.join(cwd, '.framework'))) {
+      new SymlinkUtils(cwd).mergeAgents({ tools: enabledTools });
+    }
+  } catch (err) {
+    UI.warning(`Agent re-merge after configure failed (${err.message}) — run \`npx baldart doctor\` to heal.`);
+  }
+
   // Ensure overlays dir exists (user-owned)
   const overlaysAbs = path.join(cwd, OVERLAYS_DIR);
   if (!fs.existsSync(overlaysAbs)) {

package/src/commands/doctor.js

@@ -324,7 +324,7 @@ async function detectState(cwd, opts = {}) {
         const consumerAgentsDir = path.join(cwd, '.claude', 'agents');
         if (fs.existsSync(frameworkAgentsDir)) {
           const baldartAgents = fs.readdirSync(frameworkAgentsDir)
-            .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md')
+            .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md' && f !== 'CHANGELOG.md')
             .map((f) => f.replace(/\.md$/, ''));
           for (const name of baldartAgents) {
             try {
@@ -337,6 +337,47 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on probe */ }
 
+    // ---- Slot-generated agents integrity (since v5.0.0) -----------------
+    // An agent whose framework source carries `{{#flag}}` conditionals is
+    // installed as a GENERATED file (.baldart/generated/agents/<name>.md behind
+    // a symlink), stamped with base_sha (RAW framework source), config_sha
+    // (resolved flag set) and overlay_sha. Stale = any of the three drifted,
+    // or the agent is still a plain pre-5.0 symlink (slots never resolved).
+    // Heal = `regenerate-agents` action (delegates to SymlinkUtils.mergeAgents
+    // — the doctor never duplicates merge logic). Fully fail-safe.
+    state.generatedAgentsStale = [];
+    try {
+      if (state.frameworkPresent) {
+        const slots = require('../utils/agent-slots');
+        const om = require('../utils/overlay-merger');
+        const flags = slots.resolveAgentFlags((config && !config.__malformed) ? config : {});
+        const wantConfigSha = slots.computeAgentConfigSha(flags);
+        const frameworkAgentsDir = path.join(cwd, '.framework', 'framework', '.claude', 'agents');
+        if (fs.existsSync(frameworkAgentsDir)) {
+          for (const f of fs.readdirSync(frameworkAgentsDir)) {
+            if (!f.endsWith('.md') || f === 'REGISTRY.md' || f === 'CHANGELOG.md') continue;
+            const raw = fs.readFileSync(path.join(frameworkAgentsDir, f), 'utf8');
+            if (!slots.hasAgentSlots(raw)) continue;
+            const name = f.replace(/\.md$/, '');
+            let reason = null;
+            try {
+              const content = fs.readFileSync(path.join(cwd, '.claude', 'agents', f), 'utf8'); // follows the symlink
+              const marker = om.readMarker(content);
+              if (!marker || marker.kind !== 'agent') reason = 'slots not resolved (plain pre-5.0 symlink)';
+              else if (marker.baseSha !== om.shortSha(raw)) reason = 'framework source changed';
+              else if (marker.configSha !== wantConfigSha) reason = 'baldart.config.yml flags changed';
+              else {
+                const overlayAbs = path.join(cwd, '.baldart', 'overlays', 'agents', f);
+                const wantOverlaySha = fs.existsSync(overlayAbs) ? om.shortSha(fs.readFileSync(overlayAbs, 'utf8')) : 'none';
+                if (marker.overlaySha !== wantOverlaySha) reason = 'overlay changed';
+              }
+            } catch (_) { reason = 'not installed'; }
+            if (reason) state.generatedAgentsStale.push({ name, reason });
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on probe */ }
+
     // ---- Codex agent transpile integrity (S6) --------------------------
     // When Codex is an enabled tool, every framework agent (.md) must have been
     // transpiled to `.codex/agents/<name>.toml` (generated on install/update).
@@ -357,7 +398,7 @@ async function detectState(cwd, opts = {}) {
           const codexAgentsDir = path.join(cwd, '.codex', 'agents');
           if (fs.existsSync(frameworkAgentsDir)) {
             const baldartAgents = fs.readdirSync(frameworkAgentsDir)
-              .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md')
+              .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md' && f !== 'CHANGELOG.md')
               .map((f) => f.replace(/\.md$/, ''));
             for (const name of baldartAgents) {
               try { fs.statSync(path.join(codexAgentsDir, `${name}.toml`)); }
@@ -963,6 +1004,32 @@ function planActions(state) {
     });
   }
 
+  // Slot-generated agents integrity (since v5.0.0). Regenerates any agent whose
+  // installed copy drifted from source/config/overlay, or that a pre-5.0 install
+  // left as a plain symlink (slot conditionals never resolved — the model would
+  // read ALL variants). Delegates to `SymlinkUtils.mergeAgents`, same rationale
+  // as `repair-agent-symlinks`: only the merge pass, never a full update.
+  if (state.generatedAgentsStale && state.generatedAgentsStale.length > 0) {
+    const detail = state.generatedAgentsStale.map((a) => `${a.name}: ${a.reason}`).join('; ');
+    actions.push({
+      key: 'regenerate-agents',
+      label: `Regenerate ${state.generatedAgentsStale.length} slot-generated agent(s)`,
+      why: `These agents are generated per-consumer from their framework source + baldart.config.yml flags (+ overlay), and the installed copy is out of date (${detail}). They are BALDART-generated — edit .baldart/overlays/agents/<name>.md, not the file itself.`,
+      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.mergeAgents({ tools: enabledTools });
+        UI.success(`Regenerated slot-generated agents for tools: ${enabledTools.join(', ')}`);
+      },
+    });
+  }
+
   // 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).

package/src/utils/agent-slots.js

@@ -0,0 +1,109 @@
+/**
+ * agent-slots.js — install-time slot resolution for agent definitions (v5.0.0).
+ *
+ * Agent sources under framework/.claude/agents/ may carry `{{#flag}}…{{/flag}}`
+ * conditionals (SLOT syntax — flags ONLY: no `{{ scalar }}`, no `{{> partial}}`;
+ * `${paths.*}` references stay runtime-resolved prose, unchanged). At install/
+ * update time the conditionals are resolved from the consumer's
+ * `baldart.config.yml`, so the installed agent contains ONLY the variant that
+ * matches this project (e.g. one `stack.database` block instead of four).
+ *
+ * Every flag derives from EXISTING config keys — this module introduces no new
+ * `baldart.config.yml` surface (schema-change propagation rule: N/A).
+ *
+ * Consumed by SymlinkUtils._mergeBulkDir (kind `agent`, MERGE_KINDS.slots) and
+ * by the doctor staleness probe. Pure functions except loadAgentConfig (fs read).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { shortSha } = require('./overlay-merger');
+
+/** Parse baldart.config.yml; {} when absent/malformed (fail-open: no flags → all conditionals drop). */
+function loadAgentConfig(cwd) {
+  try {
+    return yaml.load(fs.readFileSync(path.join(cwd, 'baldart.config.yml'), 'utf8')) || {};
+  } catch (_) {
+    return {};
+  }
+}
+
+/**
+ * Derive the agent-slot flag set from the config. Keep this list in sync with
+ * the flags actually used by framework/.claude/agents/*.md sources — doctor's
+ * staleness probe hashes exactly this object (config_sha).
+ */
+function resolveAgentFlags(cfg) {
+  const features = (cfg && cfg.features) || {};
+  const stack = (cfg && cfg.stack) || {};
+  const db = String(stack.database || 'none').toLowerCase();
+  const relational = ['postgres', 'postgresql', 'supabase', 'mysql', 'sqlite'].includes(db);
+  return {
+    // features.* (existing keys only)
+    has_backlog: features.has_backlog === true,
+    has_adrs: features.has_adrs === true,
+    has_i18n: features.has_i18n === true,
+    has_design_system: features.has_design_system === true,
+    has_toolchain: features.has_toolchain === true,
+    has_lsp_layer: features.has_lsp_layer === true,
+    has_code_graph: features.has_code_graph === true,
+    has_wiki_overlay: features.has_wiki_overlay === true,
+    multi_tenant_theming: features.multi_tenant_theming === true,
+    // stack.database → exactly one db_* true (db_none when unset/none)
+    db_firestore: db === 'firestore',
+    db_relational: relational,
+    db_mongodb: db === 'mongodb',
+    db_dynamodb: db === 'dynamodb',
+    db_none: !relational && !['firestore', 'mongodb', 'dynamodb'].includes(db),
+    // stack.* accents
+    fw_nextjs: String(stack.framework || '').toLowerCase() === 'nextjs',
+    deploy_vercel: String(stack.deployment || '').toLowerCase() === 'vercel',
+    e2e_playwright: String((stack.testing && stack.testing.e2e) || '').toLowerCase() === 'playwright',
+  };
+}
+
+/** True when the content carries slot syntax (flag conditionals only). */
+function hasAgentSlots(content) {
+  return /\{\{#/.test(content);
+}
+
+/**
+ * Resolve `{{#flag}}…{{/flag}}` conditionals against the flag set. Returns
+ * { content, residual } where residual lists any `{{…}}` still present after
+ * the fill — always an authoring error (unknown flag / malformed block), never
+ * silently stripped, so the caller can surface it.
+ *
+ * Deliberately NOT root-primitives' fillTemplate: that engine also substitutes
+ * scalars/partials and blanks unknown `{{ x }}` tokens — for agents a leftover
+ * token must be a loud warning, not an empty string.
+ */
+function fillAgentSlots(content, flags) {
+  // Iterate to a fixpoint (bounded) so NESTED conditionals resolve too: a kept
+  // outer block re-exposes its inner `{{#flag}}` blocks on the next pass; a
+  // dropped outer block removes its inner blocks with it (correct semantics).
+  let out = content;
+  for (let i = 0; i < 5; i++) {
+    const next = out.replace(/\{\{#([\w.]+)\}\}\n?([\s\S]*?)\{\{\/\1\}\}\n?/g, (_, key, body) =>
+      (flags[key] ? body : ''));
+    if (next === out) break;
+    out = next;
+  }
+  const residual = [...new Set((out.match(/\{\{[^}]*\}\}/g) || []))];
+  // collapse blank runs left by dropped blocks; keep everything else verbatim
+  const cleaned = out.replace(/\n{3,}/g, '\n\n');
+  return { content: cleaned, residual };
+}
+
+/** Stable hash of the resolved flag set — stamped as config_sha in the marker. */
+function computeAgentConfigSha(flags) {
+  return shortSha(JSON.stringify(flags));
+}
+
+module.exports = {
+  loadAgentConfig,
+  resolveAgentFlags,
+  hasAgentSlots,
+  fillAgentSlots,
+  computeAgentConfigSha,
+};

package/src/utils/overlay-merger.js

@@ -133,9 +133,13 @@ function refreshOverlayVersionPin(overlayPath, kind, frameworkVersion, currentBa
   return { changed: true, reason: 'refreshed' };
 }
 
-function buildMarker({ kind, name, baseSha, overlaySha }) {
+function buildMarker({ kind, name, baseSha, overlaySha, configSha }) {
   const baseShaField = baseSha ? ` base_sha=${baseSha}` : '';
-  return `${MARKER_PREFIX} kind=${kind} name=${name}${baseShaField} overlay_sha=${overlaySha}
+  // config_sha (v5.0.0, slot-generated agents) is a TRAILING field on purpose:
+  // readMarker and the edit-gate's GENERATED_MARKER_RE match a prefix ending at
+  // overlay_sha, so older readers tolerate it transparently.
+  const configShaField = configSha ? ` config_sha=${configSha}` : '';
+  return `${MARKER_PREFIX} kind=${kind} name=${name}${baseShaField} overlay_sha=${overlaySha}${configShaField}
      DO NOT EDIT MANUALLY. Edit .baldart/overlays/${kind}s/${name}.md instead;
      this file is regenerated by \`npx baldart update\`. -->`;
 }
@@ -162,9 +166,9 @@ function readMarker(content) {
   const block = content.slice(idx, idx + 4000);
   const end = block.indexOf('-->');
   if (end === -1) return null;
-  const m = block.slice(0, end).match(/kind=(\S+)\s+name=(\S+)(?:\s+base_version=(\S+))?(?:\s+base_sha=(\S+))?\s+overlay_sha=(\S+)/);
+  const m = block.slice(0, end).match(/kind=(\S+)\s+name=(\S+)(?:\s+base_version=(\S+))?(?:\s+base_sha=(\S+))?\s+overlay_sha=(\S+)(?:\s+config_sha=(\S+))?/);
   if (!m) return null;
-  return { kind: m[1], name: m[2], baseVersion: m[3] || null, baseSha: m[4] || null, overlaySha: m[5] };
+  return { kind: m[1], name: m[2], baseVersion: m[3] || null, baseSha: m[4] || null, overlaySha: m[5], configSha: m[6] || null };
 }
 
 /**
@@ -234,7 +238,7 @@ function rebuildSections(sections) {
  * @param {string} args.frameworkVersion - the installed framework VERSION
  * @returns {{ generated: string, warnings: string[], baseVersionTargeted: string, overlayMode: string }}
  */
-function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion }) {
+function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion, configSha, baseShaOverride }) {
   const warnings = [];
 
   // Parse overlay frontmatter for metadata.
@@ -293,9 +297,14 @@ function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersio
     ? '\n' + trailing.map((s) => `## ${s.heading}\n${s.body}`).join('\n').replace(/\n+$/, '\n')
     : '';
 
-  const overlaySha = shortSha(overlayContent);
-  const baseSha = shortSha(baseContent);
-  const marker = buildMarker({ kind, name, baseSha, overlaySha });
+  // An absent overlay (slot-only generation, v5.0.0) is stamped `none`, not
+  // sha-of-empty-string — truthful and stable for byte-identity comparisons.
+  const overlaySha = overlayContent ? shortSha(overlayContent) : 'none';
+  // baseShaOverride: slot-generated agents pin the RAW framework source here
+  // (upstream-drift signal), not the filled content (which changes with config
+  // — that drift is config_sha's job).
+  const baseSha = baseShaOverride || shortSha(baseContent);
+  const marker = buildMarker({ kind, name, baseSha, overlaySha, configSha });
 
   const fmBlock = baseParsed.frontmatter
     ? `---\n${baseParsed.frontmatter}\n---\n`