baldart 4.10.0 → 4.11.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.11.0] - 2026-06-04
+
+**Gli overlay non costringono più a riconciliare a ogni `baldart update` — la VERSION non è più incisa nell'identità dei file generati né usata come segnale di drift quando il base file non è cambiato.** Sintomo riportato dall'utente: ogni update richiedeva una riconciliazione. La verifica del sorgente ha trovato **due trigger indipendenti con la stessa radice** — la VERSION del framework veniva trattata come parte dell'identità di overlay/file-generati, ma viene bumpata a *ogni* release a prescindere dal fatto che lo specifico base file sia cambiato. **(A) churn dei file agent/command generati:** `buildMarker()` stampava `base_version=<VERSION>` nel commento `<!-- baldart-generated -->`; a ogni update la VERSION cambiava → la riga del marker cambiava anche su contenuto byte-identico → git vedeva un diff → scattava il commit `post-update reconcile` *a ogni update*. Il campo era puramente informativo (`readMarker` lo leggeva ma nessuno gate-ava la rigenerazione su di esso). **(B) falso-drift degli skill overlay:** `doctor` e `status` confrontavano il pin `base_skill_version` *direttamente* con la VERSION installata (ignorando `base_file_sha`), così ogni bump faceva apparire ogni overlay come "drifted" anche con base SKILL.md identico — mentre `overlay drift` lo faceva già correttamente SHA-first. **MINOR** (cambia il formato del marker generato; nessuna chiave `baldart.config.yml` — la fix riusa `base_file_sha` già presente).
+
+> **Why.** Il drift deve segnalare *modifiche reali di contenuto*, non bump di versione. La radice comune era usare la VERSION come proxy di "il base è cambiato": un proxy sempre falso-positivo dato che VERSION sale a ogni release. La fix rende ogni layer **content-addressed** (SHA) e relega la VERSION a metadato informativo: (A) il marker porta solo `base_sha` + `overlay_sha` — entrambi cambiano *solo* su modifica reale → i file generati tornano byte-stabili tra update di sola-versione (il commit di reconcile scatta solo quando base o overlay cambiano davvero); (B) `doctor`/`status` diventano SHA-first come `overlay drift`, col confronto di versione come fallback solo quando manca `base_file_sha`. In più il pin `base_<kind>_version` viene rinfrescato al merge **solo quando lo SHA combacia** (base invariato) — così resta veritiero senza mai mascherare drift reale: se il base è cambiato lo SHA differisce e il pin stale resta un segnale legittimo da riconciliare. Retrocompatibile in lettura: `readMarker` tollera ancora i marker legacy con `base_version=` (i consumer pre-4.11 subiscono un diff one-shot al primo update, poi stabilità).
+
+### Changed
+
+- **`src/utils/overlay-merger.js`** — `buildMarker()` non stampa più `base_version` (identità content-addressed: solo `base_sha` + `overlay_sha`); `readMarker()` rende `base_version` opzionale nella regex (legge sia il formato nuovo sia il legacy, `baseVersion: null` quando assente); call-site di `mergeOverlay` semplificato. Nuovo helper `refreshOverlayVersionPin(overlayPath, kind, frameworkVersion, currentBaseSha)` — rinfresca il pin di versione **solo** quando `base_file_sha` combacia col base corrente (no-op su mismatch → drift preservato; no-op su already-current; fail-safe su I/O). `baseVersionTargeted` ora usa `frameworkVersion` come fallback significativo invece di `'unknown'`.
+- **`src/commands/doctor.js`** — `overlayDrift` SHA-first: confronta `base_file_sha` con lo SHA del base SKILL.md corrente; fallback al confronto di versione solo quando `base_file_sha` manca (o il base è illeggibile). Esclude i file `*.example.md`.
+- **`src/commands/status.js`** — display drift SHA-first allineato al contratto di `overlay drift` (mostra `base changed: sha X → Y` su drift reale, `base unchanged` quando lo SHA combacia; fallback di versione solo senza `base_file_sha`).
+- **`src/utils/symlinks.js`** — `_generateOverlayedFile` calcola `baseSha` una volta e, dopo il backfill di `base_file_sha`, chiama `refreshOverlayVersionPin` per tenere truthful il pin informativo quando il base è invariato.
+
+### Added
+
+- **`src/utils/__tests__/overlay-merger.test.js`** — 7 test: stabilità byte-identica del merge tra bump di sola-versione (fix Trigger A), assenza di `base_version` nel marker generato, lettura back-compat del marker legacy, e i tre rami di `refreshOverlayVersionPin` (refresh su sha-match, no-op su sha-mismatch con drift preservato, no-op su already-current).
+
+### Fixed
+
+- **`framework/.claude/skills/new/SKILL.md`** (Phase 3.7 Step A, card-scoped diff) — risoluzione della backlog card per nome file resa **case-insensitive** (`find -name` → `-iname`). Era l'unico punto in tutte le skill che risolve una card by-name, e `-name` è case-sensitive: i file su disco hanno prefisso maiuscolo (`FEAT-`/`BUG-`/`CHORE-`), ma se `CARD_ID` arriva con case diverso (es. `/new feat-0019`) `find` tornava **vuoto in silenzio** → `CARD_FILE=""` → la card veniva trattata come inesistente (stessa famiglia del case-collision docs/PRD noto). Stesso blocco: il placeholder `${paths.backlog_dir:-../../backlog}` non era bash valido (il punto nel nome variabile → `bad substitution` se eseguito verbatim) — ora emesso già risolto in una variabile `BACKLOG_DIR` (fallback `backlog`).
+- **`framework/.claude/skills/worktree-manager/SKILL.md`** (`/nw` step 3b, sync card non-tracciate) — stesso fix di normalizzazione: il token `${paths.backlog_dir:-backlog}` letterale (bash non valido) sostituito da una variabile `BACKLOG_DIR` risolta, allineando il fallback (`backlog`) tra le due skill.
+
 ## [4.10.0] - 2026-06-04
 
 **`/new` ora ha una todo list persistente e una progress bar — durante un batch sai sempre quale fase gira, quale wave del team mode è in volo, e quale gate è risolto o skippato (con motivo).** Finora `/new` era un orchestratore autonomo cieco verso l'utente: l'unica traccia di stato era il tracker file interno `/tmp/batch-tracker-<FIRST-CARD-ID>.md`, che l'utente **non vede**. Risultato: in un run lungo (15 fasi per card, 50+ gate, sequential o team mode a wave) non avevi modo di capire dove fosse il processo. La fix replica il doppio meccanismo che dà a `/prd` la sua todo list amata, adattato alla struttura `wave → card → fase/gate`: (1) un **Task spine nativo** (TaskCreate/TaskUpdate) — il pannello todo sempre visibile della UI — tenuto *coarse*, un task per card etichettato per wave (`Wave 1 · FEAT-0502 — <title>`) più i framing task `Pre-flight`/`Final review`/`Merge & cleanup`; (2) una **Progress Bar markdown** emessa **alle transizioni** (cambio fase/wave/card, decisione gate, ogni `AskUserQuestion`/STOP — non a ogni messaggio, per non fare rumore nei tratti autonomi) con tabella card×wave + un **Gate ledger** che mostra ogni gate `✅ risolto` / `⏭️ skippato (+motivo)`. **MINOR** (capability aggiunta alla skill `/new`; nessuna chiave `baldart.config.yml` — usa solo i Task tool nativi e l'`execution_strategy` già esistente).

package/VERSION

@@ -1 +1 @@
-4.10.0
+4.11.0

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

@@ -1485,12 +1485,13 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 Run this exact bash block in the worktree. It is deterministic (grep + path match), not LLM-discretionary.
 
-`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, autodetected when the key is absent — see Phase 0 step 0). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.**
+`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, autodetected when the key is absent — see Phase 0 step 0). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.** `BACKLOG_DIR` is the value of `paths.backlog_dir` from `baldart.config.yml` (fallback `backlog` when the key is absent — emit it resolved, never the literal `${paths.backlog_dir}` token, which is not valid bash). The card lookup uses `-iname` (case-insensitive) on purpose: card filenames carry uppercase prefixes (`FEAT-`/`BUG-`/`CHORE-`) but `CARD_ID` may arrive lowercased (e.g. `/new feat-0019`), and a case-sensitive `-name` would return empty silently → the card would be treated as non-existent.
 
 ```bash
 cd <worktree-path>
 CARD_ID="<CARD-ID>"
-CARD_FILE="$(find "${paths.backlog_dir:-../../backlog}" -name "${CARD_ID}*.yml" 2>/dev/null | head -1)"
+BACKLOG_DIR="<value of paths.backlog_dir, or 'backlog' if the key is absent>"
+CARD_FILE="$(find "$BACKLOG_DIR" -iname "${CARD_ID}*.yml" 2>/dev/null | head -1)"
 # Detect what THIS card's commits changed against the trunk (post-commit), with an uncommitted fallback:
 CHANGED="$(git diff --name-only "$TRUNK...HEAD" 2>/dev/null || git diff --name-only HEAD~1..HEAD)"
 # High-risk path alternation from config (empty when paths.high_risk_modules is unset):

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -453,13 +453,17 @@ Backlog cards created during `/prd` sessions may exist as untracked files in the
 but are NOT on the trunk branch yet. The worktree (branched from the trunk) won't have them.
 
 ```bash
+# BACKLOG_DIR = value of paths.backlog_dir from baldart.config.yml (fallback `backlog`
+# when the key is absent — emit it resolved, never the literal ${paths.backlog_dir}
+# token, which is not valid bash). Same resolution as /new's card-scoped diff block.
+BACKLOG_DIR="<value of paths.backlog_dir, or 'backlog' if the key is absent>"
 MAIN_ROOT="$(git -C "$WORKTREE_PATH" rev-parse --show-superproject-working-tree 2>/dev/null || pwd)"
 
 # For each card in the batch, check if its YAML exists in the main repo but not in the worktree
-for CARD_FILE in $(ls "$MAIN_ROOT/${paths.backlog_dir:-backlog}"/*.yml 2>/dev/null); do
+for CARD_FILE in $(ls "$MAIN_ROOT/$BACKLOG_DIR"/*.yml 2>/dev/null); do
   BASENAME=$(basename "$CARD_FILE")
-  if [ ! -f "$WORKTREE_PATH/${paths.backlog_dir:-backlog}/$BASENAME" ]; then
-    cp "$CARD_FILE" "$WORKTREE_PATH/${paths.backlog_dir:-backlog}/$BASENAME"
+  if [ ! -f "$WORKTREE_PATH/$BACKLOG_DIR/$BASENAME" ]; then
+    cp "$CARD_FILE" "$WORKTREE_PATH/$BACKLOG_DIR/$BASENAME"
     echo "Synced untracked card: $BASENAME"
   fi
 done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.10.0",
+  "version": "4.11.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

@@ -94,19 +94,39 @@ function countOverlays(cwd) {
   return counts('') + counts('agents') + counts('commands');
 }
 
+// SHA-first drift detection for skill overlays, mirroring `overlay drift`
+// (overlay.js): a pinned `base_file_sha` is the source of truth — an overlay is
+// drifted only when the base SKILL.md content actually changed. The version is
+// a fallback ONLY when no `base_file_sha` is present, because VERSION bumps on
+// every release regardless of whether THIS base file changed; comparing it
+// directly flagged every unchanged overlay as drifted after any update (v4.11.0).
 function overlayDrift(cwd, frameworkVersion) {
   if (!frameworkVersion) return [];
   const dir = path.join(cwd, '.baldart', 'overlays');
   if (!fileExists(dir)) return [];
+  let computeBaseFileSha;
+  try { ({ computeBaseFileSha } = require('../utils/overlay-merger')); }
+  catch (_) { computeBaseFileSha = null; }
   const drifted = [];
   try {
     for (const f of fs.readdirSync(dir)) {
-      if (!f.endsWith('.md')) continue;
+      if (!f.endsWith('.md') || f.endsWith('.example.md')) continue;
       const txt = fs.readFileSync(path.join(dir, f), 'utf8');
       const fm = txt.match(/^---\n([\s\S]*?)\n---/);
       if (!fm) continue;
       try {
         const meta = yaml.load(fm[1]) || {};
+        const name = f.replace(/\.md$/, '');
+        const baseAbs = path.join(cwd, '.framework', 'framework', '.claude', 'skills', name, 'SKILL.md');
+        // SHA-first: trust the pinned base_file_sha when we can read the base.
+        if (meta.base_file_sha && computeBaseFileSha && fileExists(baseAbs)) {
+          const currentSha = computeBaseFileSha(fs.readFileSync(baseAbs, 'utf8'));
+          if (String(meta.base_file_sha) !== currentSha) {
+            drifted.push({ name: f, target: meta.base_skill_version || 'sha', installed: frameworkVersion });
+          }
+          continue;
+        }
+        // Fallback: no base_file_sha (or base unreadable) → version comparison.
         if (meta.base_skill_version && meta.base_skill_version !== frameworkVersion) {
           drifted.push({ name: f, target: meta.base_skill_version, installed: frameworkVersion });
         }

package/src/commands/status.js

@@ -81,9 +81,16 @@ async function status() {
       if (overlays.length === 0) {
         UI.info('No overlays authored. Examples in: .framework/templates/overlays/');
       } else {
-        // Best-effort version-drift check
+        // Best-effort drift check — SHA-first (mirrors `overlay drift`): the
+        // pinned base_file_sha is the source of truth; an overlay is drifted
+        // only when the base SKILL.md content actually changed. Version is a
+        // fallback ONLY when base_file_sha is absent, since VERSION bumps every
+        // release regardless of whether THIS base changed (v4.11.0).
         const yaml = require('js-yaml');
         const fwVersion = version;
+        let computeBaseFileSha;
+        try { ({ computeBaseFileSha } = require('../utils/overlay-merger')); }
+        catch (_) { computeBaseFileSha = null; }
         overlays.forEach((file) => {
           const full = path.join(overlaysDir, file);
           let line = `Overlay: ${file}`;
@@ -92,6 +99,21 @@ async function status() {
             const fmMatch = txt.match(/^---\n([\s\S]*?)\n---/);
             if (fmMatch) {
               const fm = yaml.load(fmMatch[1]) || {};
+              const name = file.replace(/\.md$/, '');
+              const baseAbs = path.join(process.cwd(), '.framework', 'framework', '.claude', 'skills', name, 'SKILL.md');
+              // SHA-first when we can read the base file.
+              if (fm.base_file_sha && computeBaseFileSha && fs.existsSync(baseAbs)) {
+                const currentSha = computeBaseFileSha(fs.readFileSync(baseAbs, 'utf8'));
+                if (String(fm.base_file_sha) !== currentSha) {
+                  line += ` (base changed: sha ${fm.base_file_sha} → ${currentSha} — review for drift)`;
+                  UI.warning(line);
+                  return;
+                }
+                if (fm.base_skill_version) line += ` (v${fm.base_skill_version}, base unchanged)`;
+                UI.success(line);
+                return;
+              }
+              // Fallback: no base_file_sha → version comparison.
               if (fm.base_skill_version && fwVersion && fm.base_skill_version !== fwVersion) {
                 line += ` (targets v${fm.base_skill_version}, installed v${fwVersion} — review for drift)`;
                 UI.warning(line);

package/src/utils/__tests__/overlay-merger.test.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Unit tests for overlay-merger marker stability + version-pin refresh (v4.11.0).
+ *
+ * Run: node src/utils/__tests__/overlay-merger.test.js
+ * Exits 0 on success, non-zero on failure (CI-friendly via node:test).
+ *
+ * Contract under test:
+ *   - The generated-file marker is CONTENT-ADDRESSED only (base_sha + overlay_sha)
+ *     so `mergeOverlay` produces BYTE-IDENTICAL output across version-only bumps —
+ *     killing the per-update reconcile churn (Trigger A).
+ *   - `readMarker` still reads legacy markers that carry `base_version=`.
+ *   - `refreshOverlayVersionPin` only rewrites the pin when the base is unchanged
+ *     (sha matches), never masking real drift.
+ */
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  mergeOverlay, readMarker, isGeneratedFile, computeBaseFileSha,
+  refreshOverlayVersionPin, MARKER_PREFIX,
+} = require('../overlay-merger');
+
+const BASE = `---
+name: coder
+description: coding agent
+---
+
+Preamble line.
+
+## Role
+You write code.
+
+## Rules
+Be careful.
+`;
+
+const OVERLAY = `---
+base_agent: coder
+base_agent_version: 4.9.0
+base_file_sha: "${computeBaseFileSha(BASE)}"
+mode: extend
+---
+
+## [APPEND] Rules
+Always run the linter.
+`;
+
+test('marker is byte-stable across version-only bumps (Trigger A fix)', () => {
+  const a = mergeOverlay({ kind: 'agent', name: 'coder', baseContent: BASE, overlayContent: OVERLAY, frameworkVersion: '4.10.0' });
+  const b = mergeOverlay({ kind: 'agent', name: 'coder', baseContent: BASE, overlayContent: OVERLAY, frameworkVersion: '4.11.0' });
+  assert.strictEqual(a.generated, b.generated, 'generated output must be identical when only frameworkVersion changes');
+});
+
+test('generated marker no longer stamps base_version', () => {
+  const { generated } = mergeOverlay({ kind: 'agent', name: 'coder', baseContent: BASE, overlayContent: OVERLAY, frameworkVersion: '4.11.0' });
+  assert.ok(generated.includes(MARKER_PREFIX), 'must carry the generated marker');
+  assert.ok(!/base_version=/.test(generated), 'marker must NOT contain base_version=');
+  assert.ok(/base_sha=/.test(generated), 'marker must keep base_sha=');
+  assert.ok(/overlay_sha=/.test(generated), 'marker must keep overlay_sha=');
+});
+
+test('readMarker reads NEW marker (no base_version)', () => {
+  const { generated } = mergeOverlay({ kind: 'agent', name: 'coder', baseContent: BASE, overlayContent: OVERLAY, frameworkVersion: '4.11.0' });
+  const m = readMarker(generated);
+  assert.ok(m, 'marker must be detected');
+  assert.strictEqual(m.kind, 'agent');
+  assert.strictEqual(m.name, 'coder');
+  assert.strictEqual(m.baseVersion, null, 'new markers have no base_version');
+  assert.ok(m.baseSha && m.overlaySha);
+  assert.ok(isGeneratedFile(generated));
+});
+
+test('readMarker still reads LEGACY marker (with base_version)', () => {
+  const legacy = `---\nname: coder\n---\n${MARKER_PREFIX} kind=agent name=coder base_version=4.5.0 base_sha=abc123def456 overlay_sha=deadbeef0000\n   DO NOT EDIT. -->\n\n## Role\nx\n`;
+  const m = readMarker(legacy);
+  assert.ok(m, 'legacy marker must still parse');
+  assert.strictEqual(m.baseVersion, '4.5.0');
+  assert.strictEqual(m.baseSha, 'abc123def456');
+  assert.strictEqual(m.overlaySha, 'deadbeef0000');
+  assert.ok(isGeneratedFile(legacy));
+});
+
+function withTempOverlay(content, fn) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'baldart-pin-'));
+  const p = path.join(dir, 'coder.md');
+  fs.writeFileSync(p, content);
+  try { return fn(p); } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+test('refreshOverlayVersionPin: refreshes when sha matches and version differs', () => {
+  withTempOverlay(OVERLAY, (p) => {
+    const r = refreshOverlayVersionPin(p, 'agent', '4.11.0', computeBaseFileSha(BASE));
+    assert.strictEqual(r.changed, true, r.reason);
+    assert.match(fs.readFileSync(p, 'utf8'), /base_agent_version:\s*4\.11\.0/);
+  });
+});
+
+test('refreshOverlayVersionPin: NO-OP when base sha mismatches (drift preserved)', () => {
+  withTempOverlay(OVERLAY, (p) => {
+    const r = refreshOverlayVersionPin(p, 'agent', '4.11.0', 'feedfacefeed'); // wrong sha → base changed
+    assert.strictEqual(r.changed, false);
+    assert.match(fs.readFileSync(p, 'utf8'), /base_agent_version:\s*4\.9\.0/, 'stale pin must remain as a drift signal');
+  });
+});
+
+test('refreshOverlayVersionPin: NO-OP when already current', () => {
+  const overlayCurrent = OVERLAY.replace('4.9.0', '4.11.0');
+  withTempOverlay(overlayCurrent, (p) => {
+    const r = refreshOverlayVersionPin(p, 'agent', '4.11.0', computeBaseFileSha(BASE));
+    assert.strictEqual(r.changed, false);
+    assert.strictEqual(r.reason, 'already-current');
+  });
+});

package/src/utils/overlay-merger.js

@@ -81,9 +81,61 @@ function ensureBaseFileShaInOverlay(overlayPath, baseSha) {
   return { changed: true, reason: 'backfilled' };
 }
 
-function buildMarker({ kind, name, baseVersion, baseSha, overlaySha }) {
+// The marker identity is CONTENT-ADDRESSED only: `base_sha` + `overlay_sha`,
+// both of which change exclusively when the base file or the overlay actually
+// change. `base_version` is deliberately NOT stamped here — VERSION bumps on
+// every framework release regardless of whether THIS base file changed, so
+// embedding it made every `baldart update` rewrite this line and produce a
+// spurious git diff on byte-identical generated files (→ a "post-update
+// reconcile" commit every single update). The field was informational only
+// (readMarker parsed it but nothing gated regeneration on it), so dropping it
+// buys byte-stability across version-only bumps at zero cost. (v4.11.0)
+/**
+ * Refresh the overlay's informational `base_<kind>_version` pin to the installed
+ * VERSION — but ONLY when the base content is unchanged (the overlay's
+ * `base_file_sha` still matches the current base sha). This keeps the pin
+ * truthful (it tracks the version the overlay was last reconciled against)
+ * without ever masking real drift: when the base content HAS changed the sha
+ * differs, so we leave the stale pin alone and it remains a legitimate
+ * "review me" signal for `overlay drift` / `status` / `doctor`.
+ *
+ * Contract: NO-OP unless `base_file_sha` is present AND equals `currentBaseSha`
+ * AND the version field actually differs. Fail-safe: any I/O error returns
+ * `changed:false` so it can never block a merge. (v4.11.0)
+ *
+ * @param {string} overlayPath    absolute path to `.baldart/overlays/<…>.md`
+ * @param {string} kind           'agent' | 'command' | 'skill'
+ * @param {string} frameworkVersion installed framework VERSION
+ * @param {string} currentBaseSha  computeBaseFileSha(currentBaseContent)
+ * @returns {{ changed: boolean, reason: string }}
+ */
+function refreshOverlayVersionPin(overlayPath, kind, frameworkVersion, currentBaseSha) {
+  if (!frameworkVersion || !currentBaseSha) return { changed: false, reason: 'missing-input' };
+  let content;
+  try { content = fs.readFileSync(overlayPath, 'utf8'); }
+  catch (_) { return { changed: false, reason: 'unreadable' }; }
+  const m = content.match(/^(?\s*)---\n([\s\S]*?)\n---(\r?\n|$)/);
+  if (!m) return { changed: false, reason: 'no-frontmatter' };
+  const fmBody = m[2];
+  // Only refresh when the base is provably unchanged — never mask drift.
+  const shaMatch = fmBody.match(/^\s*base_file_sha\s*:\s*["']?([0-9a-f]+)["']?\s*$/m);
+  if (!shaMatch || shaMatch[1] !== currentBaseSha) return { changed: false, reason: 'sha-mismatch-or-absent' };
+  const versionKey = `base_${kind}_version`;
+  const verRe = new RegExp(`^(\\s*${versionKey}\\s*:\\s*).*$`, 'm');
+  if (!verRe.test(fmBody)) return { changed: false, reason: 'no-version-field' };
+  const current = fmBody.match(verRe)[0].split(':').slice(1).join(':').trim();
+  if (current === String(frameworkVersion)) return { changed: false, reason: 'already-current' };
+  const newFmBody = fmBody.replace(verRe, `$1${frameworkVersion}`);
+  const replaced = `${m[1]}---\n${newFmBody}\n---${m[3]}`;
+  const updated = content.slice(0, m.index) + replaced + content.slice(m.index + m[0].length);
+  try { fs.writeFileSync(overlayPath, updated, 'utf8'); }
+  catch (_) { return { changed: false, reason: 'unwritable' }; }
+  return { changed: true, reason: 'refreshed' };
+}
+
+function buildMarker({ kind, name, baseSha, overlaySha }) {
   const baseShaField = baseSha ? ` base_sha=${baseSha}` : '';
-  return `${MARKER_PREFIX} kind=${kind} name=${name} base_version=${baseVersion}${baseShaField} overlay_sha=${overlaySha}
+  return `${MARKER_PREFIX} kind=${kind} name=${name}${baseShaField} overlay_sha=${overlaySha}
      DO NOT EDIT MANUALLY. Edit .baldart/overlays/${kind}s/${name}.md instead;
      this file is regenerated by \`npx baldart update\`. -->`;
 }
@@ -98,6 +150,9 @@ function buildMarker({ kind, name, baseVersion, baseSha, overlaySha }) {
  *   - immediately after the closing `---` of the YAML frontmatter (v3.26.1+)
  *
  * `base_sha` is optional — older generated files (pre-v3.19.0) won't have it.
+ * `base_version` is optional too: v4.11.0+ stops stamping it (see buildMarker),
+ * but files generated by older versions still carry it, so the regex tolerates
+ * either shape and surfaces `baseVersion` as null when absent.
  */
 function readMarker(content) {
   const idx = content.indexOf(MARKER_PREFIX);
@@ -107,9 +162,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+)/);
   if (!m) return null;
-  return { kind: m[1], name: m[2], baseVersion: m[3], 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] };
 }
 
 /**
@@ -191,7 +246,8 @@ function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersio
       warnings.push(`overlay frontmatter parse error (${err.message}) — treating overlay as plain markdown without metadata`);
     }
   }
-  const baseVersionTargeted = String(overlayMeta[`base_${kind}_version`] || '').trim() || 'unknown';
+  const baseVersionTargeted = String(overlayMeta[`base_${kind}_version`] || '').trim()
+    || (frameworkVersion ? String(frameworkVersion) : 'unknown');
   const overlayMode = (overlayMeta.mode || 'extend').trim();
 
   // Parse the base. Keep its frontmatter verbatim — that's what Claude reads.
@@ -239,13 +295,7 @@ function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersio
 
   const overlaySha = shortSha(overlayContent);
   const baseSha = shortSha(baseContent);
-  const marker = buildMarker({
-    kind,
-    name,
-    baseVersion: frameworkVersion || baseVersionTargeted,
-    baseSha,
-    overlaySha
-  });
+  const marker = buildMarker({ kind, name, baseSha, overlaySha });
 
   const fmBlock = baseParsed.frontmatter
     ? `---\n${baseParsed.frontmatter}\n---\n`
@@ -280,5 +330,6 @@ module.exports = {
   shortSha,
   computeBaseFileSha,
   ensureBaseFileShaInOverlay,
+  refreshOverlayVersionPin,
   MARKER_PREFIX
 };

package/src/utils/symlinks.js

@@ -484,16 +484,23 @@ class SymlinkUtils {
   }
 
   _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
-    const { mergeOverlay, isGeneratedFile, computeBaseFileSha, ensureBaseFileShaInOverlay } = require('./overlay-merger');
+    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, computeBaseFileSha(baseContent));
+      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 });