baldart 4.99.0 → 5.0.1

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`

package/src/utils/symlinks.js

@@ -30,7 +30,10 @@ const CONFLICT_LOG = path.join('.baldart', 'skill-conflicts.json');
 //     kind name doesn't pluralize to the on-disk dir — e.g. `outputStyle` lives in
 //     the hyphenated `output-styles/` dir Claude Code requires, not `outputStyles/`.
 const MERGE_KINDS = {
-  agent:       { dirGetter: 'agentsDir',       ext: '.md', overlay: true,  exclude: new Set(['REGISTRY.md']) },
+  //  - slots: `.md` sources may carry `{{#flag}}` conditionals resolved at
+  //    install-time from baldart.config.yml (v5.0.0 — see agent-slots.js).
+  //    A slot-bearing source is GENERATED per-consumer even without an overlay.
+  agent:       { dirGetter: 'agentsDir',       ext: '.md', overlay: true,  slots: true, exclude: new Set(['REGISTRY.md', 'CHANGELOG.md']) },
   command:     { dirGetter: 'commandsDir',     ext: '.md', overlay: true,  exclude: new Set(['REGISTRY.md']) },
   workflow:    { dirGetter: 'workflowsDir',    ext: '.js', overlay: false, exclude: new Set() },
   outputStyle: { dirGetter: 'outputStylesDir', ext: '.md', overlay: false, exclude: new Set(), srcDir: 'output-styles' },
@@ -415,6 +418,28 @@ class SymlinkUtils {
 
     const frameworkVersion = this._readFrameworkVersion();
 
+    // v5.0.0 — install-time slot resolution (kinds with cfg.slots). Flags are
+    // resolved ONCE per merge run from baldart.config.yml; only sources that
+    // actually carry `{{#flag}}` syntax pay the fill (others stay symlinks).
+    let slotEnv = null;
+    const slotFillFor = (fwAbsolute) => {
+      if (!cfg.slots) return null;
+      const raw = fs.readFileSync(fwAbsolute, 'utf8');
+      const slots = require('./agent-slots');
+      if (!slots.hasAgentSlots(raw)) return null;
+      if (!slotEnv) {
+        const flags = slots.resolveAgentFlags(slots.loadAgentConfig(this.cwd));
+        slotEnv = { flags, configSha: slots.computeAgentConfigSha(flags) };
+      }
+      const filled = slots.fillAgentSlots(raw, slotEnv.flags);
+      return {
+        content: filled.content,
+        residual: filled.residual,
+        configSha: slotEnv.configSha,
+        rawBaseSha: require('./overlay-merger').shortSha(raw),
+      };
+    };
+
     for (const tool of tools) {
       const adapter = getAdapter(tool, this.cwd);
       const dirGetter = adapter[cfg.dirGetter];
@@ -438,14 +463,25 @@ class SymlinkUtils {
         const overlayAbs = path.join(this.cwd, overlayRel);
         const hasOverlay = cfg.overlay && fs.existsSync(overlayAbs);
 
+        // Slot fill (v5.0.0): resolved BEFORE overlay merge and BEFORE transpile,
+        // so both consume the config-effective markdown. A leftover `{{…}}` after
+        // the fill is an authoring error — surfaced, never silently stripped.
+        const slotFill = slotFillFor(fwAbsolute);
+        if (slotFill && slotFill.residual.length) {
+          const w = `unresolved slot token(s) after fill: ${slotFill.residual.join(' ')} — check the flag names in the framework source`;
+          UI.warning(`[${adapter.label}] ${kind} ${baseName}: ${w}`);
+          aggregate.warnings.push({ tool: adapter.name, kind, name: baseName, warning: w });
+        }
+
         // Transpile path: when the adapter declares a transpiler for this kind
         // (e.g. Codex agents → TOML), do NOT symlink the `.md` source — generate
-        // the tool-native file from it (overlay-merged first when present).
+        // the tool-native file from it (slot-filled + overlay-merged first).
         const transpiler = (typeof adapter.transpilerFor === 'function') ? adapter.transpilerFor(kind) : null;
         if (transpiler) {
           this._installTranspiledFile({
             kind, baseName, fwAbsolute, overlayAbs, hasOverlay,
-            targetRel, transpiler, adapter, frameworkVersion, aggregate
+            targetRel, transpiler, adapter, frameworkVersion, aggregate,
+            baseContentOverride: slotFill ? slotFill.content : null,
           });
           continue;
         }
@@ -454,11 +490,14 @@ class SymlinkUtils {
         let lstat = null;
         try { lstat = fs.lstatSync(linkPath); } catch (_) { /* absent */ }
 
-        if (hasOverlay) {
-          // Generate a real file from base + overlay.
+        if (hasOverlay || slotFill) {
+          // Generate a real file: slot-filled base + (optional) overlay.
           this._generateOverlayedFile({
             kind, name: baseName, fwAbsolute, overlayAbs, linkPath, lstat,
-            frameworkVersion, aggregate, adapter, targetRel
+            frameworkVersion, aggregate, adapter, targetRel, hasOverlay,
+            baseContentOverride: slotFill ? slotFill.content : null,
+            configSha: slotFill ? slotFill.configSha : null,
+            baseShaOverride: slotFill ? slotFill.rawBaseSha : null,
           });
         } else {
           // Plain symlink, with broken-symlink recovery (same fix-pattern as v3.5.1).
@@ -562,13 +601,14 @@ class SymlinkUtils {
    * `# baldart-generated:` marker so a later update can safely regenerate it
    * and a user fork (no marker) is never clobbered.
    */
-  _installTranspiledFile({ kind, baseName, fwAbsolute, overlayAbs, hasOverlay, targetRel, transpiler, adapter, frameworkVersion, aggregate }) {
+  _installTranspiledFile({ kind, baseName, fwAbsolute, overlayAbs, hasOverlay, targetRel, transpiler, adapter, frameworkVersion, aggregate, baseContentOverride = null }) {
     const outName = `${baseName}${transpiler.outExt}`;
     const outPath = path.join(this.cwd, targetRel, outName);
     const relOut = path.join(targetRel, outName);
 
-    // Effective markdown = overlay-merged when an overlay exists, else the base.
-    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    // Effective markdown = slot-filled (v5.0.0, when the source carries {{#flag}})
+    // then overlay-merged when an overlay exists, else the base.
+    const baseContent = baseContentOverride != null ? baseContentOverride : fs.readFileSync(fwAbsolute, 'utf8');
     let effectiveMd = baseContent;
     if (hasOverlay) {
       try {
@@ -621,27 +661,33 @@ class SymlinkUtils {
     aggregate.generated.push({ tool: adapter.name, kind, name: baseName });
   }
 
-  _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
+  _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel, hasOverlay = true, baseContentOverride = null, configSha = null, baseShaOverride = null }) {
     const { mergeOverlay, isGeneratedFile, computeBaseFileSha, ensureBaseFileShaInOverlay, refreshOverlayVersionPin } = require('./overlay-merger');
-    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
-    const baseSha = computeBaseFileSha(baseContent);
-    // Backfill base_file_sha into the overlay frontmatter so `overlay drift` is
-    // deterministic for EVERY overlay, not just freshly-scaffolded ones
-    // (additive-only, never overwrites). Done BEFORE reading overlayContent so
-    // the marker's overlay_sha already reflects it — no one-time regen churn.
-    // (v3.33.0)
-    try {
-      const bf = ensureBaseFileShaInOverlay(overlayAbs, baseSha);
-      if (bf.changed) UI.info(`[${adapter.label}] ${kind} ${name}: backfilled base_file_sha into overlay frontmatter.`);
-      // Keep the informational base_<kind>_version pin truthful — but ONLY when
-      // the base content is unchanged (sha matches). When the base HAS changed
-      // the sha differs and the pin is left stale on purpose, so it stays a
-      // legitimate drift signal to reconcile. (v4.11.0)
-      const vp = refreshOverlayVersionPin(overlayAbs, kind, frameworkVersion, baseSha);
-      if (vp.changed) UI.info(`[${adapter.label}] ${kind} ${name}: refreshed base_${kind}_version pin to v${frameworkVersion} (base unchanged).`);
-    } catch (_) { /* non-fatal — never block a merge on backfill */ }
-    const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
-    const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion });
+    // baseContentOverride = the slot-filled markdown (v5.0.0). The overlay pin
+    // and the marker's base_sha stay anchored to the RAW framework source
+    // (baseShaOverride) so upstream drift and config drift are separate signals.
+    const baseContent = baseContentOverride != null ? baseContentOverride : fs.readFileSync(fwAbsolute, 'utf8');
+    const baseSha = baseShaOverride || computeBaseFileSha(baseContent);
+    let overlayContent = '';
+    if (hasOverlay) {
+      // Backfill base_file_sha into the overlay frontmatter so `overlay drift` is
+      // deterministic for EVERY overlay, not just freshly-scaffolded ones
+      // (additive-only, never overwrites). Done BEFORE reading overlayContent so
+      // the marker's overlay_sha already reflects it — no one-time regen churn.
+      // (v3.33.0)
+      try {
+        const bf = ensureBaseFileShaInOverlay(overlayAbs, baseSha);
+        if (bf.changed) UI.info(`[${adapter.label}] ${kind} ${name}: backfilled base_file_sha into overlay frontmatter.`);
+        // Keep the informational base_<kind>_version pin truthful — but ONLY when
+        // the base content is unchanged (sha matches). When the base HAS changed
+        // the sha differs and the pin is left stale on purpose, so it stays a
+        // legitimate drift signal to reconcile. (v4.11.0)
+        const vp = refreshOverlayVersionPin(overlayAbs, kind, frameworkVersion, baseSha);
+        if (vp.changed) UI.info(`[${adapter.label}] ${kind} ${name}: refreshed base_${kind}_version pin to v${frameworkVersion} (base unchanged).`);
+      } catch (_) { /* non-fatal — never block a merge on backfill */ }
+      overlayContent = fs.readFileSync(overlayAbs, 'utf8');
+    }
+    const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion, configSha, baseShaOverride: baseSha });
 
     if (merged.warnings && merged.warnings.length) {
       merged.warnings.forEach((w) => {
@@ -684,20 +730,34 @@ class SymlinkUtils {
       // Legacy generated file at linkPath — migrate (delete in-place, rewrite at generatedPath, symlink).
     }
 
-    // Write merged content to the indirect location.
-    fs.writeFileSync(generatedPath, merged.generated);
-
     // Compute the relative symlink target (portable across moves of the
     // project root).
     const relativeTarget = path.relative(path.dirname(linkPath), generatedPath);
 
+    // Byte-stability (v5.0.0): when the generated content is unchanged AND the
+    // consumer-visible symlink already points at it, this is a no-op — skip
+    // silently so repeated `baldart update` runs produce zero churn.
+    try {
+      if (fs.existsSync(generatedPath)
+          && fs.readFileSync(generatedPath, 'utf8') === merged.generated
+          && lstat && lstat.isSymbolicLink()
+          && path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath)) === generatedPath) {
+        aggregate.skipped.push({ tool: adapter.name, kind, name, reason: 'already-generated' });
+        return;
+      }
+    } catch (_) { /* fall through to the full write */ }
+
+    // Write merged content to the indirect location.
+    fs.writeFileSync(generatedPath, merged.generated);
+
     // Replace whatever currently lives at linkPath with the new symlink.
     if (lstat) {
       try { fs.unlinkSync(linkPath); }
       catch (_) { try { fs.rmSync(linkPath, { recursive: true, force: true }); } catch (_) { /* noop */ } }
     }
     fs.symlinkSync(relativeTarget, linkPath);
-    UI.success(`[${adapter.label}] ${kind} generated (overlay applied): ${path.join(targetRel, name)}.md → ${relativeTarget}`);
+    const mode = hasOverlay && configSha ? 'slots + overlay' : (hasOverlay ? 'overlay applied' : 'slots resolved');
+    UI.success(`[${adapter.label}] ${kind} generated (${mode}): ${path.join(targetRel, name)}.md → ${relativeTarget}`);
     aggregate.generated.push({ tool: adapter.name, kind, name, overlaySha: merged.overlaySha });
   }