baldart 3.25.0 → 3.27.0

package/src/commands/version.js

@@ -11,28 +11,23 @@ function fmtDate(iso) {
   try { return iso.slice(0, 10); } catch (_) { return iso; }
 }
 
-async function describeDrift(git) {
-  // Returns { ahead, behind, uncommittedFiles, hasFetchHead } or null on failure.
+async function describeDrift(git, status) {
+  // Uncommitted local edits to .framework/ (working tree, NOT commits)
+  let uncommittedFiles = 0;
   try {
-    let hasFetchHead = false;
-    try {
-      const out = await git.git.raw(['rev-list', '--left-right', '--count', 'HEAD...FETCH_HEAD']);
-      const [a, b] = out.trim().split('\t').map(Number);
-      hasFetchHead = !Number.isNaN(a) && !Number.isNaN(b);
-      var ahead = a, behind = b;
-    } catch (_) { /* no FETCH_HEAD — needs fetch first */ }
+    const dirty = await git.git.raw(['diff', '--name-only', 'HEAD', '--', FRAMEWORK_DIR]);
+    uncommittedFiles = dirty.trim() ? dirty.trim().split('\n').length : 0;
+  } catch (_) { /* repo without HEAD yet */ }
 
-    // Uncommitted local edits to .framework/
-    let uncommittedFiles = 0;
-    try {
-      const dirty = await git.git.raw(['diff', '--name-only', 'HEAD', '--', FRAMEWORK_DIR]);
-      uncommittedFiles = dirty.trim() ? dirty.trim().split('\n').length : 0;
-    } catch (_) { /* repo without HEAD yet */ }
-
-    return { ahead, behind, uncommittedFiles, hasFetchHead };
-  } catch (_) {
-    return null;
-  }
+  return {
+    isAligned: status.isAligned,
+    installedVersion: status.installedVersion,
+    remoteVersion: status.remoteVersion,
+    behind: status.commitCount.behind,
+    ahead: status.commitCount.ahead,
+    uncommittedFiles,
+    hasFetchHead: status.hasFetchHead,
+  };
 }
 
 async function version(opts = {}) {
@@ -50,29 +45,42 @@ async function version(opts = {}) {
     const state = State.load();
     const cliVersion = require('../../package.json').version;
     const cliUpdate = UpdateNotifier.hint({ currentVersion: cliVersion });
+    const verbose = opts.verbose === true;
 
-    // Optionally fetch upstream to compute drift (default: yes).
-    const offline = opts.offline === true;
-    if (!offline) {
-      try {
-        await git.fetch(state.framework_repo || REPO_DEFAULT);
-      } catch (_) { /* offline — drift report falls back */ }
+    // SSOT (v3.25.0+): one query, version-compare authority.
+    const repo = state.framework_repo || REPO_DEFAULT;
+    let status;
+    if (opts.offline === true) {
+      status = {
+        installedVersion: frameworkVersion,
+        remoteVersion: 'unknown',
+        isAligned: false,
+        commitCount: { behind: 0, ahead: 0, note: '' },
+        aheadScoped: 0, hasDivergence: false, hasFetchHead: false, fetched: false,
+      };
+    } else {
+      status = await git.getUpdateStatus(repo);
     }
-    const drift = await describeDrift(git);
+    const drift = await describeDrift(git, status);
 
-    UI.newline();
-    UI.box('BALDART VERSION', [
+    // Messaging based on `isAligned` (not commit count, which is subtree noise).
+    let remoteLine;
+    if (!drift.hasFetchHead) {
+      remoteLine = 'Remote:      (offline / not fetched)';
+    } else if (drift.isAligned) {
+      remoteLine = `Remote:      v${drift.remoteVersion} (aligned)`;
+    } else if (drift.remoteVersion !== 'unknown') {
+      remoteLine = `Remote:      v${drift.remoteVersion} (installed v${drift.installedVersion} — \`npx baldart update\`)`;
+    } else {
+      remoteLine = 'Remote:      (upstream VERSION unreadable)';
+    }
+
+    const lines = [
       `Installed:   v${frameworkVersion}    ${state.install_date ? `(since ${fmtDate(state.install_date)})` : ''}`.trim(),
-      drift && drift.hasFetchHead
-        ? (drift.behind > 0
-            ? `Remote:      ${drift.behind} commit(s) ahead — pull with \`npx baldart update\``
-            : 'Remote:      up to date')
-        : 'Remote:      (offline / not fetched)',
-      drift
-        ? (drift.uncommittedFiles > 0
-            ? `Local:       v${frameworkVersion} + ${drift.uncommittedFiles} uncommitted file(s) in .framework/`
-            : `Local:       v${frameworkVersion} (clean)`)
-        : '',
+      remoteLine,
+      drift.uncommittedFiles > 0
+        ? `Local:       v${frameworkVersion} + ${drift.uncommittedFiles} uncommitted file(s) in .framework/`
+        : `Local:       v${frameworkVersion} (clean)`,
       '',
       `Last update: ${fmtDate(state.last_update_date)}`,
       `Last push:   v${state.last_pushed_version || '—'}    ${state.last_push_date ? `(${fmtDate(state.last_push_date)})` : ''}`.trim(),
@@ -80,8 +88,19 @@ async function version(opts = {}) {
       cliUpdate
         ? `CLI:         v${cliVersion} → v${cliUpdate.latest} available (npm i -g baldart@latest)`
         : `CLI:         v${cliVersion}`,
-      `Repository:  https://github.com/${state.framework_repo || REPO_DEFAULT}`,
-    ].filter((l) => l !== ''));
+      `Repository:  https://github.com/${repo}`,
+    ];
+
+    if (verbose && drift.hasFetchHead) {
+      lines.push('');
+      lines.push('Diagnostics (subtree commit history — includes auto-generated merges):');
+      lines.push(`  commits ahead:  ${drift.ahead}`);
+      lines.push(`  commits behind: ${drift.behind}`);
+      lines.push('  (these counts grow with every `git subtree pull --squash`; ignore unless investigating)');
+    }
+
+    UI.newline();
+    UI.box('BALDART VERSION', lines.filter((l) => l !== ''));
     UI.newline();
   } catch (error) {
     UI.error(`Failed to get version: ${error.message}`);

package/src/utils/__tests__/classify-divergence.test.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Fixture-driven test for classifyDivergence pattern matching.
+ *
+ * Run: node src/utils/__tests__/classify-divergence.test.js
+ * Exits 0 on success, 1 on any mismatch (CI-friendly).
+ *
+ * Fixtures cover the exact commit subjects observed during the
+ * `mayo` consumer debug (v3.25.0 release). Adversarial-review enforced.
+ */
+const GitUtils = require('../git');
+const g = new GitUtils();
+
+const SUBJECT_FIXTURES = [
+  // ─── subtree-merge (branch-agnostic) ─────────────────────────────────
+  { subject: "Merge commit 'abc123' into develop", expected: 'subtree-merge' },
+  { subject: "Merge commit 'abc123' into main", expected: 'subtree-merge' },
+  { subject: "Merge commit 'deadbeef' into feature/x", expected: 'subtree-merge' },
+  { subject: "Merge branch 'feature-x' into main", expected: 'subtree-merge' },
+
+  // ─── subtree-squash ──────────────────────────────────────────────────
+  { subject: "Squashed '.framework/' changes from abc..def", expected: 'subtree-squash' },
+  { subject: "Squashed '.framework/' content from 1234..5678", expected: 'subtree-squash' },
+
+  // ─── chore-wrapper (real commits from mayo) ──────────────────────────
+  { subject: '[CHORE] reconcile baldart state ledger v3.22.1 -> v3.25.0', expected: 'chore-wrapper' },
+  { subject: '[CHORE] register baldart agent-discovery hooks', expected: 'chore-wrapper' },
+  { subject: 'chore(baldart): post-update reconcile to v3.25.0', expected: 'chore-wrapper' },
+  { subject: 'chore: bump baldart version', expected: 'chore-wrapper' },
+  { subject: '[CHORE] baldart update → v3.12.0', expected: 'chore-wrapper' },
+
+  // ─── non-matches (should return null → fall through to path classifier) ──
+  { subject: 'feat: add new login screen', expected: null },
+  { subject: 'fix: ui-expert agent for mayo design system', expected: null },
+  { subject: 'docs: update README', expected: null },
+
+  // ─── adversarial false-positive guards ───────────────────────────────
+  // "Merge pull request" is NOT a subtree merge — must NOT match
+  { subject: 'Merge pull request #42 from feature/x', expected: null },
+  // "Squashed" without `.framework/` path — NOT subtree-squash
+  { subject: "Squashed 'docs/' content from abc..def", expected: null },
+  // Chore without 'baldart' keyword — NOT chore-wrapper
+  { subject: 'chore: update dependencies', expected: null },
+];
+
+const PATH_FIXTURES = [
+  {
+    name: 'all touched in .framework/.claude/agents → overlay-able',
+    touched: ['.framework/framework/.claude/agents/ui-expert.md'],
+    expected: 'custom-overlay-able',
+  },
+  {
+    name: 'all touched in .framework/.claude/skills → overlay-able',
+    touched: [
+      '.framework/framework/.claude/skills/ui-design/SKILL.md',
+      '.framework/framework/.claude/skills/ui-design/scripts/foo.sh',
+    ],
+    expected: 'custom-overlay-able',
+  },
+  {
+    name: 'mixed agents + skills → still overlay-able',
+    touched: [
+      '.framework/framework/.claude/agents/ui-expert.md',
+      '.framework/framework/.claude/commands/check.md',
+    ],
+    expected: 'custom-overlay-able',
+  },
+  {
+    name: 'touches .framework/src → custom-other',
+    touched: ['.framework/src/utils/git.js'],
+    expected: 'custom-other',
+  },
+  {
+    name: 'mix overlay-able + src → custom-other',
+    touched: [
+      '.framework/framework/.claude/agents/ui-expert.md',
+      '.framework/src/utils/git.js',
+    ],
+    expected: 'custom-other',
+  },
+  {
+    name: 'empty paths → custom-other (conservative default)',
+    touched: [],
+    expected: 'custom-other',
+  },
+  {
+    name: 'touches CHANGELOG → custom-other',
+    touched: ['.framework/CHANGELOG.md'],
+    expected: 'custom-other',
+  },
+];
+
+let pass = 0, fail = 0;
+
+console.log('─── Subject classifier ───');
+for (const f of SUBJECT_FIXTURES) {
+  const actual = g.classifyCommitSubject(f.subject);
+  if (actual === f.expected) {
+    pass++;
+    console.log(`  ✓ "${f.subject}" → ${actual}`);
+  } else {
+    fail++;
+    console.log(`  ✗ "${f.subject}" → ${actual} (expected ${f.expected})`);
+  }
+}
+
+console.log('\n─── Path classifier ───');
+for (const f of PATH_FIXTURES) {
+  const actual = g.classifyCommitByPaths(f.touched);
+  if (actual === f.expected) {
+    pass++;
+    console.log(`  ✓ ${f.name} → ${actual}`);
+  } else {
+    fail++;
+    console.log(`  ✗ ${f.name} → ${actual} (expected ${f.expected})`);
+  }
+}
+
+console.log(`\nResult: ${pass} pass, ${fail} fail`);
+process.exit(fail > 0 ? 1 : 0);

package/src/utils/git.js

@@ -177,6 +177,205 @@ class GitUtils {
     }
   }
 
+  // ────────────────────────────────────────────────────────────────────
+  // SSOT update-status check (v3.25.0+).
+  //
+  // Before v3.25.0 three commands answered the same question — "is this
+  // consumer up-to-date with upstream BALDART?" — with three different
+  // queries, none of them right:
+  //
+  //   - `update.js` used `hasChangesToPush()` (origin/main..HEAD — wrong
+  //     remote AND wrong direction).
+  //   - `version.js` and `doctor.js` used `HEAD...FETCH_HEAD` full-repo
+  //     symmetric diff, which counts every subtree-merge commit ever
+  //     generated by `git subtree pull --squash`. That count never
+  //     decreases (squash merges are never "equal" on both sides), so
+  //     even a perfectly-synced consumer is shown "N commits ahead".
+  //
+  // The authority for "aligned or not" is the VERSION file. The upstream
+  // BALDART repo has `VERSION` at root, so `git show FETCH_HEAD:VERSION`
+  // gives the remote version directly. Local `.framework/VERSION` gives
+  // the installed version. Identical strings → aligned, full stop.
+  //
+  // The commit count remains in the return value for diagnostic display
+  // (behind `--verbose` flags), explicitly labeled as subtree-merge noise
+  // so users don't misread it as a problem.
+  // ────────────────────────────────────────────────────────────────────
+  // ────────────────────────────────────────────────────────────────────
+  // Divergence classifier (v3.25.0+).
+  //
+  // When `aheadScoped > 0` (consumer has commits on `.framework/` not in
+  // upstream), we need to know WHETHER those commits are git plumbing
+  // noise (auto-resolve OK) or real user content (must prompt before
+  // anything destructive).
+  //
+  // Categories (in matching order — first match wins):
+  //   - subtree-merge:  `git subtree pull --squash` merge commits
+  //   - subtree-squash: the squash payload commits themselves
+  //   - chore-wrapper:  CLI-generated [CHORE]/chore(baldart): commits
+  //   - custom-overlay-able: user edited a framework agent/skill/command
+  //                          → should migrate to .baldart/overlays/
+  //   - custom-other:   anything else (src/, CHANGELOG, ad-hoc fixes)
+  //
+  // Aggregate `class`:
+  //   - all-noise:    every commit is subtree-* / chore-wrapper → auto-resolve
+  //   - overlay-able: every non-noise commit is overlay-able → suggest /overlay
+  //   - real-custom:  every non-noise commit is custom-other → prompt 3-way
+  //   - mixed:        non-noise commits span both → prompt 3-way
+  //
+  // Default-conservative: any commit whose subject + touched-paths don't
+  // match a known pattern is classified `custom-other`, never auto-resolved.
+  // ────────────────────────────────────────────────────────────────────
+  classifyCommitSubject(subject) {
+    if (/^Merge (commit '[a-f0-9]+'|branch '[^']+') into \S+$/.test(subject)) {
+      return 'subtree-merge';
+    }
+    if (/^Squashed '\.framework\/' (changes from|content from)/.test(subject)) {
+      return 'subtree-squash';
+    }
+    // Two separate conditions: must look like a chore commit AND mention
+    // baldart anywhere (subject or scope). `chore(baldart): foo` is a
+    // common case — the keyword is in the scope, not after the colon.
+    const isChorePrefix = /^(\[CHORE\]|chore(\([^)]*\))?:)/.test(subject);
+    const hasBaldartKeyword = /baldart/i.test(subject);
+    if (isChorePrefix && hasBaldartKeyword) {
+      return 'chore-wrapper';
+    }
+    return null;
+  }
+
+  classifyCommitByPaths(touched) {
+    if (!touched.length) return 'custom-other';
+    const overlayablePrefix = '.framework/framework/.claude/';
+    const overlayableDirs = ['agents/', 'skills/', 'commands/'];
+    const allOverlayable = touched.every((p) => {
+      if (!p.startsWith(overlayablePrefix)) return false;
+      const rest = p.slice(overlayablePrefix.length);
+      return overlayableDirs.some((d) => rest.startsWith(d));
+    });
+    return allOverlayable ? 'custom-overlay-able' : 'custom-other';
+  }
+
+  async classifyDivergence() {
+    // Inspect aheadScoped commits — those not on FETCH_HEAD that touch .framework/.
+    const commits = [];
+    try {
+      const raw = await this.git.raw([
+        'log',
+        'FETCH_HEAD..HEAD',
+        '--pretty=format:%H%x00%s',
+        '--',
+        FRAMEWORK_DIR
+      ]);
+      for (const line of raw.split('\n')) {
+        if (!line.trim()) continue;
+        const [sha, ...rest] = line.split('');
+        const subject = rest.join('');
+        let category = this.classifyCommitSubject(subject);
+        if (!category) {
+          // Need file list to disambiguate custom-overlay-able vs custom-other.
+          let touched = [];
+          try {
+            const filesRaw = await this.git.raw(['diff-tree', '--no-commit-id', '--name-only', '-r', sha]);
+            touched = filesRaw.split('\n').filter((l) => l.trim());
+          } catch (_) { /* leave empty → custom-other */ }
+          category = this.classifyCommitByPaths(touched);
+        }
+        commits.push({ sha, subject, category });
+      }
+    } catch (_) {
+      return { class: 'unknown', commits: [] };
+    }
+
+    if (commits.length === 0) return { class: 'all-noise', commits: [] };
+
+    const noiseCategories = new Set(['subtree-merge', 'subtree-squash', 'chore-wrapper']);
+    const nonNoise = commits.filter((c) => !noiseCategories.has(c.category));
+    if (nonNoise.length === 0) return { class: 'all-noise', commits };
+
+    const hasOverlayable = nonNoise.some((c) => c.category === 'custom-overlay-able');
+    const hasOther = nonNoise.some((c) => c.category === 'custom-other');
+    let aggregate = 'real-custom';
+    if (hasOverlayable && !hasOther) aggregate = 'overlay-able';
+    else if (hasOverlayable && hasOther) aggregate = 'mixed';
+
+    return { class: aggregate, commits };
+  }
+
+  async getUpdateStatus(repo, branch = 'main') {
+    const result = {
+      installedVersion: 'unknown',
+      remoteVersion: 'unknown',
+      isAligned: false,
+      commitCount: {
+        behind: 0,
+        ahead: 0,
+        note: 'Includes subtree-merge commits autogenerated by `git subtree pull --squash`. Does not reflect real content drift; use `isAligned` for update status.'
+      },
+      aheadScoped: 0,
+      hasDivergence: false,
+      hasFetchHead: false,
+      fetched: false,
+    };
+
+    try {
+      result.installedVersion = await this.getFrameworkVersion();
+    } catch (_) { /* leave 'unknown' */ }
+
+    try {
+      await this.fetch(repo, branch);
+      result.fetched = true;
+    } catch (_) {
+      // Offline — leave fetched=false, fall through with best-effort.
+    }
+
+    try {
+      const head = await this.git.raw(['rev-parse', 'FETCH_HEAD']);
+      result.hasFetchHead = head.trim().length > 0;
+    } catch (_) { /* no FETCH_HEAD */ }
+
+    if (result.hasFetchHead) {
+      try {
+        const v = await this.git.raw(['show', 'FETCH_HEAD:VERSION']);
+        result.remoteVersion = v.trim();
+      } catch (_) { /* upstream missing VERSION — leave 'unknown' */ }
+
+      try {
+        const out = await this.git.raw(['rev-list', '--left-right', '--count', 'HEAD...FETCH_HEAD']);
+        const [ahead, behind] = out.trim().split(/\s+/).map(Number);
+        if (!Number.isNaN(ahead)) result.commitCount.ahead = ahead;
+        if (!Number.isNaN(behind)) result.commitCount.behind = behind;
+      } catch (_) { /* leave 0/0 */ }
+
+      try {
+        const out = await this.git.raw(['rev-list', '--count', 'FETCH_HEAD..HEAD', '--', FRAMEWORK_DIR]);
+        result.aheadScoped = Number(out.trim()) || 0;
+      } catch (_) { /* leave 0 */ }
+    }
+
+    if (result.installedVersion !== 'unknown' && result.remoteVersion !== 'unknown') {
+      result.isAligned = result.installedVersion === result.remoteVersion;
+    }
+
+    result.hasDivergence = !result.isAligned && result.aheadScoped > 0;
+
+    if (result.hasDivergence) {
+      try {
+        const d = await this.classifyDivergence();
+        result.divergenceClass = d.class;
+        result.divergenceCommits = d.commits;
+      } catch (_) {
+        result.divergenceClass = 'unknown';
+        result.divergenceCommits = [];
+      }
+    } else {
+      result.divergenceClass = 'none';
+      result.divergenceCommits = [];
+    }
+
+    return result;
+  }
+
   // ────────────────────────────────────────────────────────────────────
   // `.framework/` is a git subtree — it MUST be tracked. If anything in
   // the gitignore chain (project .gitignore, .git/info/exclude, global

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) {