baldart 3.26.0 → 3.27.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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).
 
+## [3.27.0] - 2026-05-28
+
+Fix critico al meccanismo di overlay-merge degli agent. Sintomo riproducibile osservato in `mayo` durante `/new FEAT-0009 -full` (team mode, claude-opus-4-7): gli agent overlay-merged (`coder`, `ui-expert`, `code-reviewer`, `doc-reviewer`, `qa-sentinel`, `security-reviewer` quando hanno un overlay) **non comparivano nella lista "Available agent types"** del Claude Code session reminder. Sequenza concreta: `codebase-architect` (symlink) parte e completa; i 4 background agent (`coder×2` + `ui-expert×2`) lanciati subito dopo falliscono con `InputValidationError: subagent_type not recognized`; l'orchestratore halta con un AskUserQuestion fuori-protocollo. Repro: `ls -la .claude/agents/` mostra 21 symlink + 6 file regolari (i 6 overlay-merged); CC discoverizza i 21 symlink e omette i 6 file regolari. Confermato su sessioni indipendenti del 2026-05-27 e 2026-05-28 → bug strutturale, non transiente. Workflow `/new` in team mode, `/check`, `/qa`, `/codexreview` e skill `prd` erano **bloccati end-to-end** su qualsiasi consumer con overlay agent.
+
+### Root cause — Claude Code upstream bug #20931
+
+Il session-start discovery scanner di Claude Code che costruisce la registry di `subagent_type` validi **skippa silenziosamente i file regolari** in `.claude/agents/` (solo i symlink vengono caricati). Il bug è già documentato in `framework/.claude/hooks/agent-discovery-gate.js:10-15`:
+
+> #20931 — file-based discovery of `.claude/agents/*.md` is documented as BROKEN in some scenarios (files ignored at session start)
+
+Dalla v3.8.0 in poi BALDART ha generato i file overlay-merged come **file regolari** direttamente in `.claude/agents/<name>.md`, intersecando esattamente la zona di rottura di CC. Tutti gli overlay agent attivi nei consumer sono stati silenziosamente invisibili per ~3 mesi, e il sintomo emergeva solo quando una skill provava ad invocare lo `subagent_type` (es. team-mode `/new`).
+
+Diagnosi precedente erroneamente attribuita a "HTML comment prima del frontmatter rompe il parser YAML" è stata rivista: il riordino del marker post-frontmatter resta una pulizia di formato corretta ma **non era la causa primaria** del sintomo.
+
+### Fixed — Symlink indirection per agent/command overlay-merged (root cause fix)
+
+- **[src/utils/symlinks.js](src/utils/symlinks.js)** `_generateOverlayedFile()`: il content merged ora vive in `.baldart/generated/<kind>s/<name>.md` (file regolare), e `.claude/agents/<name>.md` (o `.claude/commands/<name>.md`) viene creato come **symlink relativo** verso quel file. Claude Code vede il path consumer come un symlink come tutti gli altri e lo discoverizza correttamente. Stesso pattern per Codex (`.agents/skills/`) tramite il tool adapter.
+- **[src/utils/symlinks.js](src/utils/symlinks.js)** `_installPerItemSymlink()`: quando `hasOverlay` viene rimosso e il path consumer è un symlink che punta in `.baldart/generated/`, il CLI relinka al framework base e cancella lo stale generated file. Coerenza forte tra "overlay esiste" e "esiste un generated file".
+- **[src/utils/symlinks.js](src/utils/symlinks.js)**: migrazione automatica del legacy layout. Se il consumer ha un file regolare baldart-generated direttamente in `.claude/agents/<name>.md` (pre-v3.27.0), la prossima `npx baldart update` lo riconosce dal marker, sposta il content in `.baldart/generated/agents/<name>.md` e crea il symlink. Nessun intervento manuale richiesto. User-fork (file regolare senza marker baldart) restano protetti.
+
+### Added — Safety net SessionStart hook
+
+- **[framework/.claude/hooks/agent-discovery-info.sh](framework/.claude/hooks/agent-discovery-info.sh)**: oltre a rilevare gli agent **mancanti** (file assente), il hook ora rileva anche gli agent in **stato degradato** — ovvero file regolari con marker `<!-- baldart-generated: -->` presenti in `.claude/agents/` (pre-v3.27.0 layout). Quando rilevati, emette `additionalContext` esplicito al modello con il nome degli agent affected, la causa (upstream bug #20931) e l'azione richiesta (`npx baldart update`). Difesa-in-profondità: il `mergeAgents` migra automaticamente e questo hook copre l'edge case in cui un consumer non lanci `update` subito dopo l'upgrade.
+
+### Fixed — Formato file generato (cleanup secondario, non root cause)
+
+- **[src/utils/overlay-merger.js](src/utils/overlay-merger.js)**: i file generati hanno il frontmatter YAML su riga 1 e il marker `<!-- baldart-generated: -->` subito dopo il `---` di chiusura (era prima invertito). Allinea il formato alla convenzione standard CommonMark + YAML frontmatter, indipendentemente dal fatto che CC sia o meno strict sul parser.
+- **[src/utils/overlay-merger.js](src/utils/overlay-merger.js)**: nuovo export `isGeneratedFile(content)` posizione-agnostico. `readMarker()` cerca il marker in tutto il file (cap 4KB) per leggere sia file v3.27.0+ sia legacy pre-v3.27.0 (retrocompat fondamentale per la migration).
+- **[framework/.claude/hooks/framework-edit-gate.js](framework/.claude/hooks/framework-edit-gate.js)**: il PreToolUse hook controlla il marker via `head.includes` su slice 5KB, così intercetta edit ai file generati sia che il marker sia su riga 1 (legacy) sia dopo il frontmatter (v3.27.0+).
+
+### Migration path per i consumer
+
+Su un consumer con overlay agent in layout legacy (es. `mayo`):
+
+1. `npx baldart update` rileva la nuova VERSION e lancia `mergeAgents`.
+2. Per ogni file regolare baldart-generated in `.claude/agents/`: marker letto → content spostato in `.baldart/generated/agents/<name>.md` → simlink creato.
+3. `git status` mostra: `.claude/agents/<name>.md` modificato (file → symlink), `.baldart/generated/agents/<name>.md` nuovo. La `_autoCommitFn` del CLI committa con `chore(baldart): post-update reconcile to v3.27.0`.
+4. **Restart della Claude Code session** richiesto perché la registry di `subagent_type` viene letta al session-start.
+5. Verifica: `Available agent types` ora include tutti i nomi (sia symlink che generated-symlink). `/new` in team mode funziona.
+
+Nessuna perdita di overlay: i file in `.baldart/overlays/agents/*.md` sono consumer-owned e non vengono toccati. Lo skill `/baldart-update` cita esplicitamente nel report post-flight gli agent migrati e ricorda di restartare la sessione CC.
+
 ## [3.26.0] - 2026-05-27
 
 Fix definitivo del processo `baldart update` dopo che un'esecuzione reale su un consumer (`mayo`) ha esposto un workflow strutturalmente rotto. Sintomi: `update --yes` stampava "Already up to date!" mentre `version`/`doctor` riportavano correttamente "Remote: 51 commit ahead"; CLI globale (v3.18.1) silenzioso vs npm latest (v3.24.0); divergenza subtree (19 commit locali + 51 upstream) mai menzionata; output sporcato da `ExperimentalWarning` di npm a ogni invocazione; skill `/baldart-update` che narrava il workflow rotto senza accorgersene. Root cause: tre superfici (`update`, `version`, `doctor`) implementavano TRE check diversi per la stessa domanda, e nessuna era giusta — `update.js:193` usava `hasChangesToPush()` (commit LOCALI non pushati al CONSUMER's origin, niente a che vedere con BALDART upstream); `version`/`doctor` usavano `HEAD...FETCH_HEAD` full-repo che include sempre subtree-merge noise → falso positivo perenne "52 commit ahead".

package/VERSION

@@ -1 +1 @@
-3.26.0
+3.27.0

package/framework/.claude/hooks/agent-discovery-info.sh

@@ -62,9 +62,19 @@ CONSUMER_AGENTS_DIR=".claude/agents"
 
 [ -d "$FRAMEWORK_AGENTS_DIR" ] || exit 0  # consumer not installed — silent.
 
-# --- compute missing set --------------------------------------------------
+# --- compute missing + degraded sets --------------------------------------
+#
+# MISSING — file does not exist (or symlink is broken). agent-discovery-gate
+#           will hard-deny calls to these names.
+# DEGRADED — file exists as a *regular file* with the baldart-generated marker.
+#           Pre-v3.27.0 layout produced these, but Claude Code upstream bug
+#           #20931 skips regular files at session-start discovery, so the
+#           `subagent_type` value is silently unavailable to the orchestrator.
+#           The fix is `npx baldart update` (migrates them to a symlink into
+#           .baldart/generated/<kind>s/).
 
 MISSING=""
+DEGRADED=""
 while IFS= read -r f; do
   [ -z "$f" ] && continue
   name="$(basename "$f" .md)"
@@ -72,16 +82,21 @@ while IFS= read -r f; do
   target="$CONSUMER_AGENTS_DIR/${name}.md"
   # `test -e` returns false for broken symlinks too — exactly what we want.
   if [ ! -e "$target" ]; then
-    if [ -z "$MISSING" ]; then
-      MISSING="$name"
-    else
-      MISSING="$MISSING, $name"
+    if [ -z "$MISSING" ]; then MISSING="$name"; else MISSING="$MISSING, $name"; fi
+    continue
+  fi
+  # File exists. If it's a symlink → CC discovery sees it, healthy.
+  # If it's a regular file with the baldart-generated marker → degraded
+  # state (legacy overlay layout before v3.27.0).
+  if [ ! -L "$target" ] && [ -f "$target" ]; then
+    if head -c 4096 "$target" 2>/dev/null | grep -q "<!-- baldart-generated:" ; then
+      if [ -z "$DEGRADED" ]; then DEGRADED="$name"; else DEGRADED="$DEGRADED, $name"; fi
     fi
   fi
 done < <(find "$FRAMEWORK_AGENTS_DIR" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort)
 
-# Nothing missing — exit silently. No noise when everything is healthy.
-[ -z "$MISSING" ] && exit 0
+# Nothing to report — exit silently. No noise when everything is healthy.
+[ -z "$MISSING" ] && [ -z "$DEGRADED" ] && exit 0
 
 # --- emit additionalContext ----------------------------------------------
 
@@ -90,7 +105,14 @@ escape_json() {
   printf '%s' "$1" | awk 'BEGIN{ORS=""} {gsub(/\\/,"\\\\"); gsub(/"/,"\\\""); gsub(/\r/,""); gsub(/\n/,"\\n"); print}'
 }
 
-MSG="BALDART expects the following sub-agents to be reachable via the Agent tool in this session, but their backing files are missing from .claude/agents/: ${MISSING}. Calling Agent with one of these subagent_type values will be denied by the agent-discovery-gate PreToolUse hook. Run \`npx baldart doctor\` to repair, then restart this session."
+MSG=""
+if [ -n "$MISSING" ]; then
+  MSG="BALDART expects the following sub-agents to be reachable via the Agent tool in this session, but their backing files are missing from .claude/agents/: ${MISSING}. Calling Agent with one of these subagent_type values will be denied by the agent-discovery-gate PreToolUse hook. Run \`npx baldart doctor\` to repair, then restart this session."
+fi
+if [ -n "$DEGRADED" ]; then
+  DEG_MSG="BALDART detected overlay-merged agents stored in the legacy pre-v3.27.0 layout (regular files in .claude/agents/ with the baldart-generated marker): ${DEGRADED}. Claude Code upstream bug #20931 silently skips regular files at session-start discovery, so calling Agent with one of these subagent_type values will fail with InputValidationError even though the file is on disk. Run \`npx baldart update\` to migrate to the v3.27.0+ symlink-indirection layout (the file is moved to .baldart/generated/<kind>s/<name>.md and .claude/agents/<name>.md becomes a symlink to it), then restart this session."
+  if [ -n "$MSG" ]; then MSG="${MSG} | ${DEG_MSG}"; else MSG="$DEG_MSG"; fi
+fi
 
 cat <<JSON
 {

package/framework/.claude/hooks/framework-edit-gate.js

@@ -163,18 +163,24 @@ function main() {
 
   // v3.8.0+: also block direct edits to BALDART-generated files (agents /
   // commands generated from base + overlay). These live OUTSIDE .framework/
-  // but carry the baldart-generated marker comment as their first line.
-  // The user should edit the overlay, not the generated file, otherwise the
-  // next `baldart update` will overwrite their changes.
+  // but carry the baldart-generated marker comment in their head. Pre-v3.27.0
+  // the marker was on line 1; v3.27.0+ places it after the YAML frontmatter
+  // and the actual file lives in .baldart/generated/<kind>s/<name>.md with a
+  // symlink from .claude/agents/<name>.md. Match both layouts. The structural
+  // regex (requires kind=…name=…overlay_sha=…) avoids false-positives on
+  // framework source files that mention the marker as a string literal
+  // (e.g. this hook itself, agent-discovery-info.sh, overlay-merger.js).
+  const GENERATED_MARKER_RE =
+    /<!-- baldart-generated:[\s\S]{0,400}?kind=\S+[\s\S]{0,400}?name=\S+[\s\S]{0,400}?overlay_sha=\S+/;
   try {
     const fs = require('fs');
     if (fs.existsSync(filePath)) {
-      const head = fs.readFileSync(filePath, 'utf8').slice(0, 200);
-      if (head.startsWith('<!-- baldart-generated:')) {
-        // Allow ONLY if the edit explicitly retains the marker on line 1 —
+      const head = fs.readFileSync(filePath, 'utf8').slice(0, 5000);
+      if (GENERATED_MARKER_RE.test(head)) {
+        // Allow ONLY if the edit explicitly retains the marker —
         // catches accidental overwrites while letting BALDART itself regenerate.
         const newContent = extractNewContent(toolName, input.tool_input) || '';
-        if (!newContent.startsWith('<!-- baldart-generated:')) {
+        if (!GENERATED_MARKER_RE.test(newContent)) {
           const reason =
             `Cannot edit BALDART-generated file (${filePath}).\n` +
             `This file is auto-generated by \`npx baldart update\` from a base ` +

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -312,11 +312,23 @@ Report to the user, in order:
    baldart@…", surface it once so the user knows the CLI bumped too.
 4. **Hooks reconciled**: any hook backfilled (parse "Auto-registered N
    missing hook(s)" or per-line "Registered hook" from stdout).
-5. **Schema notes**: any missing key still flagged → suggest
+5. **Agent layout migration (v3.27.0+)**: parse stdout for lines matching
+   `agent generated (overlay applied): .claude/agents/<name>.md → ../../.baldart/generated/agents/<name>.md`.
+   Pre-v3.27.0 overlay-merged agents (`coder`, `ui-expert`, `code-reviewer`,
+   `doc-reviewer`, `qa-sentinel`, `security-reviewer` when overlayed) lived
+   as regular files in `.claude/agents/` and were silently invisible to
+   Claude Code session-start discovery (upstream bug #20931). The CLI now
+   stores merged content in `.baldart/generated/<kind>s/<name>.md` and
+   places a symlink at `.claude/agents/<name>.md`. Report the migrated
+   names so the user knows they should restart their CC session for the
+   new layout to take effect on `subagent_type` resolution.
+6. **Schema notes**: any missing key still flagged → suggest
    `npx baldart configure`.
-6. **Stash-pop status**: clean / conflicts present (with file list).
-7. **Suggested next step**: if schema drift residual or other non-update
-   doctor checks fired, suggest `npx baldart` (smart doctor).
+7. **Stash-pop status**: clean / conflicts present (with file list).
+8. **Suggested next step**: if schema drift residual or other non-update
+   doctor checks fired, suggest `npx baldart` (smart doctor). Also remind:
+   if any agent was migrated (step 5), **restart the Claude Code session**
+   so the discovery scanner sees the new symlinks.
 
 ## Failure modes
 

package/package.json

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

package/src/utils/overlay-merger.js

@@ -49,20 +49,38 @@ function buildMarker({ kind, name, baseVersion, baseSha, overlaySha }) {
 }
 
 /**
- * Returns the marker fields encoded in the first line if present, or null.
- * Used by `update` to know "is this file ours (safe to regenerate) or did the
- * user edit it manually?"
+ * Returns the marker fields encoded in the generated-marker block if present,
+ * or null. Used by `update` to know "is this file ours (safe to regenerate) or
+ * did the user edit it manually?"
+ *
+ * The marker block can appear in two positions:
+ *   - line 1 (pre-v3.26.1 generated files — kept for back-compat reading)
+ *   - 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.
  */
 function readMarker(content) {
-  const firstLine = content.split('\n').slice(0, 3).join('\n');
-  if (!firstLine.includes(MARKER_PREFIX)) return null;
-  const m = firstLine.match(/kind=(\S+) name=(\S+) base_version=(\S+)(?: base_sha=(\S+))? overlay_sha=(\S+)/);
+  const idx = content.indexOf(MARKER_PREFIX);
+  if (idx === -1) return null;
+  // The marker block ends at the next `-->`. Cap the search to the first 4KB
+  // to avoid scanning huge files when the marker isn't actually there.
+  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+)/);
   if (!m) return null;
   return { kind: m[1], name: m[2], baseVersion: m[3], baseSha: m[4] || null, overlaySha: m[5] };
 }
 
+/**
+ * Tells whether `content` is a BALDART-generated file (agent or command).
+ * Position-agnostic — accepts both pre-v3.26.1 (marker on line 1) and v3.26.1+
+ * (marker after the frontmatter) layouts.
+ */
+function isGeneratedFile(content) {
+  return readMarker(content) !== null;
+}
+
 /**
  * Split markdown text into:
  *   - frontmatter: the raw text between leading `---` fences (or '')
@@ -193,12 +211,17 @@ function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersio
     ? `---\n${baseParsed.frontmatter}\n---\n`
     : '';
 
-  const generated =
-    `${marker}\n` +
-    fmBlock +
-    (baseParsed.preamble || '') +
-    sectionsOut +
-    trailingOut;
+  // v3.26.1+ layout: frontmatter MUST be the first thing in the file —
+  // Claude Code's agent discovery uses a strict YAML-frontmatter parser that
+  // skips files where `---` is not on line 1. Pre-v3.26.1 placed the marker
+  // first, which silently de-registered every overlay-merged agent (no
+  // `subagent_type` exposed → spawns failed with "agent not found"). The
+  // marker now sits as a CommonMark HTML comment immediately after the
+  // closing `---`, which `readMarker` still finds via position-agnostic
+  // scan. If the base has no frontmatter (unusual), marker still goes first.
+  const generated = fmBlock
+    ? fmBlock + `${marker}\n` + (baseParsed.preamble || '') + sectionsOut + trailingOut
+    : `${marker}\n` + (baseParsed.preamble || '') + sectionsOut + trailingOut;
 
   return {
     generated,
@@ -212,6 +235,7 @@ function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersio
 module.exports = {
   mergeOverlay,
   readMarker,
+  isGeneratedFile,
   parseMarkdown,
   shortSha,
   computeBaseFileSha,

package/src/utils/symlinks.js

@@ -423,6 +423,20 @@ class SymlinkUtils {
         aggregate.skipped.push({ tool: adapter.name, kind, name: baseName, reason: 'already-linked' });
         return;
       }
+      // Symlink pointing into .baldart/generated/ → BALDART-managed from a
+      // previous overlay state. Overlay has just been removed, so revert to
+      // the framework-base symlink and clean up the now-stale generated file.
+      if (current.split(path.sep).includes('generated') && current.includes('.baldart')) {
+        fs.unlinkSync(linkPath);
+        fs.symlinkSync(target, linkPath);
+        try {
+          const staleGenerated = path.join(this.cwd, '.baldart', 'generated', `${kind}s`, filename);
+          if (fs.existsSync(staleGenerated)) fs.unlinkSync(staleGenerated);
+        } catch (_) { /* best effort */ }
+        UI.info(`[${adapter.label}] ${kind} overlay removed — relinking ${path.join(targetRel, filename)} → framework base`);
+        aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
+        return;
+      }
       // Broken or pointing elsewhere — replace if broken, else respect user override
       if (!fs.existsSync(linkPath)) {
         fs.unlinkSync(linkPath);
@@ -438,6 +452,10 @@ class SymlinkUtils {
     // Real file. Could be:
     //  (a) A baldart-generated file from a previous run where overlay USED to
     //      exist but now doesn't — safe to replace with symlink.
+    //      Pre-v3.27.0 layout: marker file directly at linkPath. v3.27.0+
+    //      stores the merged file under .baldart/generated/ and points a
+    //      symlink at it, so the "real file at linkPath" case here is the
+    //      legacy layout that no longer regenerates — just unlink and resymlink.
     //  (b) A user-authored fork — leave alone.
     const { readMarker } = require('./overlay-merger');
     const content = fs.readFileSync(linkPath, 'utf8');
@@ -447,6 +465,12 @@ class SymlinkUtils {
       UI.info(`[${adapter.label}] ${kind} overlay removed — replacing generated file with symlink: ${path.join(targetRel, filename)}`);
       fs.unlinkSync(linkPath);
       fs.symlinkSync(target, linkPath);
+      // Also clean up any stale .baldart/generated/<kind>s/<name>.md from
+      // the v3.27.0+ indirect layout (no overlay means no generated file).
+      try {
+        const staleGenerated = path.join(this.cwd, '.baldart', 'generated', `${kind}s`, filename);
+        if (fs.existsSync(staleGenerated)) fs.unlinkSync(staleGenerated);
+      } catch (_) { /* best effort */ }
       aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
       return;
     }
@@ -460,7 +484,7 @@ class SymlinkUtils {
   }
 
   _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
-    const { mergeOverlay, readMarker } = require('./overlay-merger');
+    const { mergeOverlay, readMarker, isGeneratedFile } = require('./overlay-merger');
     const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
     const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
     const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion });
@@ -472,13 +496,28 @@ class SymlinkUtils {
       });
     }
 
-    // If a previously generated file is on disk, check ownership via marker
-    // before overwriting. If it lacks the marker (= user edited manually after
-    // a previous generation, or a pre-3.8 fork), refuse to overwrite.
+    // v3.27.0+ layout: the merged content lives at
+    //   .baldart/generated/<kind>s/<name>.md            (real file)
+    // and the consumer-visible path is a symlink:
+    //   .claude/agents/<name>.md → ../../.baldart/generated/agents/<name>.md
+    // This is a workaround for Claude Code upstream bug #20931, where the
+    // session-start scanner that builds the `subagent_type` registry skips
+    // regular files in .claude/agents/ (only symlinks are picked up). The
+    // pre-v3.27.0 layout wrote the merged file directly at linkPath as a
+    // real file, which made every overlay-merged agent silently invisible
+    // to the orchestrator — see CHANGELOG 3.27.0 root cause analysis.
+    const generatedDir = path.join(this.cwd, '.baldart', 'generated', `${kind}s`);
+    const generatedPath = path.join(generatedDir, `${name}.md`);
+    fs.mkdirSync(generatedDir, { recursive: true });
+
+    // Inspect what currently sits at linkPath. Three legal states:
+    //   (1) symlink we already manage (resolves into .baldart/generated/) → stale, replace
+    //   (2) symlink to the framework base (no overlay last time) → upgrade to indirect symlink
+    //   (3) regular file with baldart-generated marker (legacy pre-v3.27.0 layout) → migrate
+    //   (4) regular file without marker → user fork, refuse to touch
     if (lstat && !lstat.isSymbolicLink()) {
       const existing = fs.readFileSync(linkPath, 'utf8');
-      const m = readMarker(existing);
-      if (!m) {
+      if (!isGeneratedFile(existing)) {
         UI.warning(`[${adapter.label}] ${kind} ${name}: existing file at ${path.join(targetRel, name)}.md has no baldart-generated marker — NOT overwriting (user fork?). Move it aside (or merge it into the overlay) and re-run update.`);
         aggregate.conflicts.push({
           tool: adapter.name, kind, name,
@@ -488,15 +527,23 @@ class SymlinkUtils {
         });
         return;
       }
+      // Legacy generated file at linkPath — migrate (delete in-place, rewrite at generatedPath, symlink).
     }
 
-    // Replace any existing symlink/file with the freshly generated content.
+    // 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);
+
+    // 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.writeFileSync(linkPath, merged.generated);
-    UI.success(`[${adapter.label}] ${kind} generated (overlay applied): ${path.join(targetRel, name)}.md`);
+    fs.symlinkSync(relativeTarget, linkPath);
+    UI.success(`[${adapter.label}] ${kind} generated (overlay applied): ${path.join(targetRel, name)}.md → ${relativeTarget}`);
     aggregate.generated.push({ tool: adapter.name, kind, name, overlaySha: merged.overlaySha });
   }
 
@@ -598,13 +645,13 @@ class SymlinkUtils {
           UI.warning(`[${adapter.label}] Legacy bulk symlink at ${rel}. Run \`npx baldart update\` to convert to per-item layout.`);
           allValid = false;
         } else {
+          const { isGeneratedFile } = require('./overlay-merger');
           const entries = fs.readdirSync(full);
           const frameworkOwned = entries.filter((n) => {
             const p = path.join(full, n);
             try {
               if (fs.lstatSync(p).isSymbolicLink()) return true;
-              const content = fs.readFileSync(p, 'utf8');
-              return content.startsWith('<!-- baldart-generated:');
+              return isGeneratedFile(fs.readFileSync(p, 'utf8'));
             } catch { return false; }
           });
           if (frameworkOwned.length === 0) {