@ulysses-ai/create-workspace 0.22.0-beta.0 → 0.23.1-beta.0

package/template/_claude/scripts/classify-update.mjs

@@ -3,14 +3,20 @@
 // can batch the safe cases and ask only where a decision is needed.
 //
 // Usage:
-//   node classify-update.mjs [--root <dir>] [--payload <dir>]
+//   node classify-update.mjs [--root <dir>] [--payload <dir>] [--baseline <file>]
 //   node classify-update.mjs --root <dir> --payload <dir> --write-baseline
 //   node classify-update.mjs --root <dir> --payload <dir> --merge-claude-md
 //
-// --root    workspace root; defaults to the current working directory (never
-//           derived from this script's location — the upgrade payload runs
-//           this file from <workspace>/.workspace-update/.claude/scripts/)
-// --payload the staged payload; defaults to <root>/.workspace-update
+// --root     workspace root; defaults to the current working directory (never
+//            derived from this script's location — the upgrade payload runs
+//            this file from <workspace>/.workspace-update/.claude/scripts/)
+// --payload  the staged payload; defaults to <root>/.workspace-update
+// --baseline the baseline to classify against; defaults to
+//            <root>/.claude/.template-baseline.json, falling back to
+//            <payload>/.template-baseline.reconstructed.json (what --upgrade
+//            reconstructs for pre-baseline workspaces) when the root has none.
+//            Pass it explicitly in the worktree flow, where <root> is the
+//            worktree and the launcher's baseline may not be reachable.
 //
 // The default mode prints JSON with these lists:
 //   new        — no installed counterpart and no baseline entry; safe to
@@ -24,6 +30,23 @@
 //                edit AND a template change — the one case that needs a
 //                per-file decision (or the workspace predates baselines and
 //                has no entry to compare).
+//   config     — .mcp.json and .claude/settings.json: JSON the workspace
+//                owns jointly with the template (its own MCP servers and
+//                settings live beside template keys). Never classified by
+//                content and never batch-copied — instead each entry carries
+//                a key-level diff (`added` keys the template ships, keys
+//                `workspaceOnly`, keys `changed` in both, nested paths joined
+//                with '/'), and /workspace-update merges key by key: add
+//                template keys, keep workspace-only keys, ask on conflicting
+//                keys. Array-valued keys (hooks event lists,
+//                permissions.allow/deny) diff by ELEMENT instead of whole:
+//                each `arrays` entry is { path, added, workspaceOnly } with
+//                the element lists, and the skill merges arrays as a union —
+//                the workspace's elements kept, the template's new ones
+//                appended — so only true scalar conflicts ask. Entries flag
+//                `notInstalled` (no workspace file — ask once whether to
+//                install the payload's copy) or `unparseable` (broken JSON on
+//                either side — ask, never merge blind).
 //   localOnly  — installed file differs from the payload, but the payload
 //                equals the baseline: the template hasn't touched the file
 //                since the last update, so the difference is purely local.
@@ -38,31 +61,51 @@
 //                active rule stays (gh:180)
 //   removed    — installed file with no payload counterpart: the template
 //                stopped shipping it. Excludes what the workspace owns:
+//                the config files above (the template dropping one hands it
+//                to the workspace, it never deletes user content),
 //                *.test.mjs (see staleTests), anything gitignored
 //                (machine-local), paths under .claude/worktrees/, and entries
 //                of workspace.json → workspace.localFiles (array of
 //                .claude/-relative paths or globs for files this workspace
-//                owns) (gh:180)
+//                owns) (gh:180). Two markers refine the per-file offer
+//                (gh:190): `{ file, referencedBy }` — a removed hook that a
+//                workspace-only settings.json entry still registers (the
+//                config-diff paths); the skill removes file and settings
+//                entry together. `{ file, userOwned: true }` — no baseline
+//                entry, so the template never shipped it: the workspace's
+//                own, offered a workspace.localFiles entry, not deletion.
 //   staleTests — *.test.mjs files under .claude/ with no payload counterpart.
 //                The npm tarball ships no tests, so these came from a dev
 //                checkout and are never updated by /workspace-update; the
 //                skill offers to remove them (tests live in the template repo)
+//   implicitDefaults — workspace.json keys whose ABSENCE carried a default
+//                in the version being upgraded FROM but not in the payload's:
+//                canonicalBudgetBytes meant a 40960-byte budget when absent
+//                from v0.15.0-beta.1 until v0.19.0-beta.0 made it opt-in
+//                (absent since means off; before v0.15 there was no budget).
+//                An upgrade from inside that window into a workspace.json
+//                without the key reports { key, value, reason } so the skill
+//                writes the value explicitly (gh:190).
 //
-// Plus `hasBaseline`: whether .claude/.template-baseline.json exists. Without
-// it (workspaces older than the baseline's introduction) template changes
-// cannot be told from local edits, so they land in `differs` — the first
-// update after v0.21 asks per file; once it writes the baseline, later updates
-// won't.
+// Plus `hasBaseline`: whether a usable baseline was found, `baselineSource`
+// (which file it came from) and `baselineReconstructed`. The default
+// resolution is <root>/.claude/.template-baseline.json, then the payload's
+// .template-baseline.reconstructed.json (both unparseable-as-absent); without
+// either, template changes cannot be told from local edits, so they land in
+// `differs` — the first update asks per file; once it writes the baseline,
+// later updates won't.
 //
 // Content comparisons hash with CRLF normalized to LF on both sides (binary
 // files hash byte-exact), so a git autocrlf checkout that stores CRLF where
 // the payload ships LF classifies as identical rather than locally modified.
 //
-// Only verbatim-installed files are classified: everything under .claude/,
-// plus .mcp.json and .claudeignore. The payload's templates (*.tmpl, which
-// install with {{project-name}} substitution), _gitignore (merged line-by-line
-// into the workspace's .gitignore), and .manifest.json (payload metadata) are
-// handled by their own steps in /workspace-update and are excluded here.
+// Only verbatim-installed files are classified: everything under .claude/
+// except .claude/settings.json, plus .mcp.json and .claudeignore — the two
+// JSON configs route to `config` instead of the content lists. The payload's
+// templates (*.tmpl, which install with {{project-name}} substitution),
+// _gitignore (merged line-by-line into the workspace's .gitignore), and
+// .manifest.json (payload metadata) are handled by their own steps in
+// /workspace-update and are excluded here.
 //
 // The other two modes are /workspace-update bookends:
 //   --write-baseline  write .claude/.template-baseline.json recording the
@@ -74,10 +117,15 @@
 //                     present as `updated` again next time; see
 //                     template-baseline.mjs. Throws rather than writing an
 //                     empty baseline.
-//   --merge-claude-md print CLAUDE.md with the payload's CLAUDE.md.tmpl
-//                     merged in: template lines updated, the workspace's own
-//                     lines (custom skill entries, sections) kept. The skill
-//                     shows the diff against the current file before writing.
+//   --merge-claude-md print JSON { claudeMd, missingIncludes }: CLAUDE.md
+//                     with the payload's CLAUDE.md.tmpl merged in — template
+//                     lines updated, the workspace's own lines (custom skill
+//                     entries, sections) kept — plus the `@{path}` include
+//                     lines the merged file carries whose targets don't
+//                     exist at the root (machine-local local-only-* targets
+//                     exempt). The skill shows the diff against the current
+//                     file before writing, and asks on each missing include
+//                     instead of leaving it dangling (gh:190).
 
 import {
   existsSync,
@@ -89,7 +137,14 @@ import {
 import { basename, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gitIgnoredPaths } from './build-workspace-context.mjs';
-import { BASELINE_PATH, hashBytes, readBaseline, writeBaseline } from './template-baseline.mjs';
+import { compareVersions } from '../lib/registry-check.mjs';
+import {
+  BASELINE_PATH,
+  RECONSTRUCTED_BASELINE_NAME,
+  hashBytes,
+  readBaselineFile,
+  writeBaseline,
+} from './template-baseline.mjs';
 
 function isMainModule(metaUrl) {
   if (!process.argv[1]) return false;
@@ -99,11 +154,12 @@ function isMainModule(metaUrl) {
 }
 
 function parseArgs(argv) {
-  const args = { root: process.cwd(), payload: null, writeBaseline: false, mergeClaudeMd: false };
+  const args = { root: process.cwd(), payload: null, baseline: null, writeBaseline: false, mergeClaudeMd: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--root') args.root = argv[++i];
     else if (a === '--payload') args.payload = argv[++i];
+    else if (a === '--baseline') args.baseline = argv[++i];
     else if (a === '--write-baseline') args.writeBaseline = true;
     else if (a === '--merge-claude-md') args.mergeClaudeMd = true;
     else throw new Error(`Unknown arg: ${a}`);
@@ -115,6 +171,104 @@ function parseArgs(argv) {
 // Everything else in the payload is a template or metadata handled elsewhere.
 const VERBATIM_ROOTS = ['.claude', '.mcp.json', '.claudeignore'];
 
+// JSON configs the workspace owns jointly with the template: its own MCP
+// servers sit inside .mcp.json's mcpServers, its own settings beside the
+// template's keys in .claude/settings.json. Content classification would
+// file every one of them as `differs` the moment the workspace adds
+// anything, and a batch copy would wipe the workspace's entries — so they
+// are reported in `config` with a key-level diff and merged key by key,
+// never compared by bytes and never copied wholesale (gh:186).
+const CONFIG_PATHS = new Set(['.mcp.json', '.claude/settings.json']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Key-level diff between the payload's config object and the workspace's.
+ * Paths join keys with '/' (mcpServers/playwright) and stop at two
+ * segments: these configs are maps of named units — mcpServers/{server},
+ * permissions/{allow} — and a unit's own internals (a server's args vs
+ * command) merge as one decision, not as separate asks. Arrays the key
+ * carries on both sides diff by ELEMENT (a union merge needs no decision),
+ * and any other non-object value compares by JSON value and reports at its
+ * unit's path.
+ */
+const CONFIG_DIFF_DEPTH = 2;
+
+function arrayElementDiff(payloadArr, workspaceArr) {
+  const wsSet = new Set(workspaceArr.map((e) => JSON.stringify(e)));
+  const plSet = new Set(payloadArr.map((e) => JSON.stringify(e)));
+  return {
+    added: payloadArr.filter((e) => !wsSet.has(JSON.stringify(e))),
+    workspaceOnly: workspaceArr.filter((e) => !plSet.has(JSON.stringify(e))),
+  };
+}
+
+function configKeyDiff(payloadObj, workspaceObj, prefix = '') {
+  const added = [];
+  const workspaceOnly = [];
+  const changed = [];
+  const arrays = [];
+  const keys = new Set([...Object.keys(payloadObj), ...Object.keys(workspaceObj)]);
+  for (const key of [...keys].sort()) {
+    const path = prefix ? `${prefix}/${key}` : key;
+    const inPayload = Object.prototype.hasOwnProperty.call(payloadObj, key);
+    const inWorkspace = Object.prototype.hasOwnProperty.call(workspaceObj, key);
+    if (inPayload && !inWorkspace) { added.push(path); continue; }
+    if (!inPayload && inWorkspace) { workspaceOnly.push(path); continue; }
+    const pv = payloadObj[key];
+    const wv = workspaceObj[key];
+    if (
+      prefix.split('/').filter(Boolean).length + 1 < CONFIG_DIFF_DEPTH
+      && isPlainObject(pv) && isPlainObject(wv)
+    ) {
+      const sub = configKeyDiff(pv, wv, path);
+      added.push(...sub.added);
+      workspaceOnly.push(...sub.workspaceOnly);
+      changed.push(...sub.changed);
+      arrays.push(...sub.arrays);
+    } else if (Array.isArray(pv) && Array.isArray(wv)) {
+      // An array both sides hold is a set the workspace extends: element
+      // lists let the skill union-merge instead of choosing one side whole.
+      const diff = arrayElementDiff(pv, wv);
+      if (diff.added.length > 0 || diff.workspaceOnly.length > 0) {
+        arrays.push({ path, ...diff });
+      }
+    } else if (JSON.stringify(pv) !== JSON.stringify(wv)) {
+      changed.push(path);
+    }
+  }
+  return { added, workspaceOnly, changed, arrays };
+}
+
+/**
+ * One `config` entry: the key-level diff for a payload-shipped config file
+ * against the workspace's copy, or a flag when no diff is possible —
+ * `notInstalled` (no workspace file; the skill asks once whether to install
+ * the payload's copy) and `unparseable` (broken JSON on either side; the
+ * skill asks rather than merging blind).
+ */
+function configEntry(absRoot, absPayload, rel) {
+  let payloadJson;
+  try {
+    payloadJson = JSON.parse(readFileSync(join(absPayload, rel), 'utf8'));
+  } catch {
+    return { path: rel, unparseable: true };
+  }
+  if (!isPlainObject(payloadJson)) return { path: rel, unparseable: true };
+  const installed = join(absRoot, rel);
+  if (!existsSync(installed)) return { path: rel, notInstalled: true };
+  let workspaceJson;
+  try {
+    workspaceJson = JSON.parse(readFileSync(installed, 'utf8'));
+  } catch {
+    return { path: rel, unparseable: true };
+  }
+  if (!isPlainObject(workspaceJson)) return { path: rel, unparseable: true };
+  return { path: rel, ...configKeyDiff(payloadJson, workspaceJson) };
+}
+
 function isClassified(payloadRelPath) {
   const first = payloadRelPath.split('/')[0];
   return VERBATIM_ROOTS.includes(first);
@@ -196,7 +350,72 @@ function isOwnedByWorkspace(rel, localFiles) {
   return localFiles.some((pattern) => globMatches(pattern, claudeRel));
 }
 
-export function classifyUpdate({ root, payload }) {
+/**
+ * Which baseline the classification runs against. An explicit --baseline
+ * wins; otherwise the workspace's own <root>/.claude/.template-baseline.json
+ * is tried first, then the payload's .template-baseline.reconstructed.json
+ * (staged by --upgrade for workspaces that predate baselines). The fallback
+ * matters in the worktree flow: <root> is the task worktree, which cannot
+ * see launcher-only files, while the payload travels there by absolute path.
+ * A file that exists but does not parse counts as absent — a corrupt
+ * baseline must not block the reconstructed one (gh:186).
+ */
+export function resolveBaseline({ root, payload, baseline = null }) {
+  const candidates = baseline !== null
+    ? [{ path: resolve(baseline), label: baseline }]
+    : [
+      { path: join(resolve(root), BASELINE_PATH), label: BASELINE_PATH },
+      { path: join(resolve(payload), RECONSTRUCTED_BASELINE_NAME), label: `.workspace-update/${RECONSTRUCTED_BASELINE_NAME}` },
+    ];
+  for (const candidate of candidates) {
+    const parsed = readBaselineFile(candidate.path);
+    if (parsed !== null) return { baseline: parsed, source: candidate.label };
+  }
+  return { baseline: null, source: null };
+}
+
+/**
+ * workspace.json keys whose absence carried a default in the version being
+ * upgraded FROM but not in the payload's. The canonical budget existed as an
+ * implicit default only between v0.15.0-beta.1 (gh:97, which introduced it:
+ * absent meant a 40960-byte budget) and v0.19.0-beta.0 (gh:164, which made
+ * it opt-in: absent means off since). Before v0.15 there was no budget at
+ * all, so a workspace upgrading from there also has none to preserve —
+ * reporting the key would turn trimming ON. Only an upgrade from inside
+ * that window into a workspace.json that never wrote the key reports it,
+ * and the skill writes the explicit value and says so (gh:190).
+ */
+const CANONICAL_BUDGET_INTRODUCED = '0.15.0-beta.1';
+const CANONICAL_BUDGET_OPT_IN = '0.19.0-beta.0';
+const CANONICAL_BUDGET_DEFAULT = 40960;
+
+function implicitDefaults(absRoot, absPayload) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(absPayload, '.manifest.json'), 'utf8'));
+  } catch {
+    return []; // no manifest — the payload path is wrong; nothing to infer
+  }
+  const { fromVersion } = manifest;
+  if (typeof fromVersion !== 'string' || fromVersion === 'unknown') return [];
+  if (compareVersions(fromVersion, CANONICAL_BUDGET_INTRODUCED) < 0) return [];
+  if (compareVersions(fromVersion, CANONICAL_BUDGET_OPT_IN) >= 0) return [];
+  let config;
+  try {
+    config = JSON.parse(readFileSync(join(absRoot, 'workspace.json'), 'utf8'));
+  } catch {
+    return []; // no workspace.json to preserve a default in
+  }
+  const ws = config?.workspace && typeof config.workspace === 'object' ? config.workspace : null;
+  if (!ws || Object.prototype.hasOwnProperty.call(ws, 'canonicalBudgetBytes')) return [];
+  return [{
+    key: 'canonicalBudgetBytes',
+    value: CANONICAL_BUDGET_DEFAULT,
+    reason: `absent meant a ${CANONICAL_BUDGET_DEFAULT}-byte canonical budget before v0.19 and means off since — write the value explicitly or trimming silently stops`,
+  }];
+}
+
+export function classifyUpdate({ root, payload, baseline: baselineArg = null }) {
   const absRoot = resolve(root);
   const absPayload = resolve(payload ?? join(absRoot, '.workspace-update'));
   if (!existsSync(absPayload)) {
@@ -205,21 +424,31 @@ export function classifyUpdate({ root, payload }) {
 
   const payloadFiles = [...walkFiles(absPayload)].filter(isClassified);
   const payloadSet = new Set(payloadFiles);
-  const baseline = readBaseline(absRoot);
+  const { baseline, source } = resolveBaseline({ root: absRoot, payload: absPayload, baseline: baselineArg });
 
   const result = {
     new: [],
     identical: [],
     updated: [],
     differs: [],
+    config: [],
     localOnly: [],
     deletedLocally: [],
     activated: [],
     removed: [],
     staleTests: [],
+    implicitDefaults: [],
     hasBaseline: baseline !== null,
+    baselineSource: source,
+    baselineReconstructed: baseline !== null && baseline.reconstructed === true,
   };
   for (const rel of payloadFiles) {
+    // Jointly-owned JSON configs never compare by content — the config
+    // list carries a key-level diff for the skill to merge instead.
+    if (CONFIG_PATHS.has(rel)) {
+      result.config.push(configEntry(absRoot, absPayload, rel));
+      continue;
+    }
     // A .skip rule whose active counterpart is installed was deliberately
     // activated by this workspace: report it as activated, not new.
     if (rel.startsWith('.claude/rules/') && rel.endsWith('.md.skip')) {
@@ -270,6 +499,9 @@ export function classifyUpdate({ root, payload }) {
   const gitignored = gitIgnoredPaths(absRoot, installedFiles);
   for (const rel of installedFiles) {
     if (skipSet.has(rel)) continue;
+    // A config file the payload dropped stays with the workspace: it holds
+    // user content the template never deletes.
+    if (CONFIG_PATHS.has(rel)) continue;
     // An active rule whose .skip twin is in the payload is an activated rule,
     // not a removed one.
     if (rel.startsWith('.claude/rules/') && rel.endsWith('.md') && skipSet.has(`${rel}.skip`)) continue;
@@ -281,11 +513,71 @@ export function classifyUpdate({ root, payload }) {
       continue;
     }
     if (isOwnedByWorkspace(rel, localFiles)) continue;
-    result.removed.push(rel);
+    // No baseline record means the template never shipped the file here —
+    // the workspace's own, not a template removal. Marked so the skill
+    // offers a workspace.localFiles entry instead of deletion; only a real
+    // baseline can prove the negative. An activated optional rule is the
+    // exception: the baseline records its .skip twin, which proves the
+    // template shipped it, so its removal stays plain (gh:190).
+    const templateShipped = typeof baseline?.files[rel] === 'string'
+      || (rel.startsWith('.claude/rules/') && rel.endsWith('.md')
+        && typeof baseline?.files[`${rel}.skip`] === 'string');
+    if (baseline && !templateShipped) {
+      result.removed.push({ file: rel, userOwned: true });
+    } else {
+      result.removed.push(rel);
+    }
   }
+  linkRemovedHooks(result, absRoot);
+  result.implicitDefaults = implicitDefaults(absRoot, absPayload);
   return result;
 }
 
+/**
+ * A removed hook that a workspace-only settings.json entry still registers
+ * must not be deleted while its registration stays: mark the removal with
+ * `referencedBy` — the config-diff paths (`settings.json hooks.{Event}`) —
+ * so the skill removes the file and the settings entry together (gh:190).
+ * References are looked for where the config diff shows the workspace
+ * holding what the payload doesn't: `arrays[].workspaceOnly` elements and
+ * `workspaceOnly` keys (whose value is read from its settings.json).
+ */
+function linkRemovedHooks(result, absRoot) {
+  const settings = result.config.find((c) => c.path === '.claude/settings.json');
+  if (!settings || settings.notInstalled || settings.unparseable) return;
+  const removedHooks = result.removed.filter(
+    (entry) => typeof entry === 'string' && entry.startsWith('.claude/hooks/'),
+  );
+  if (removedHooks.length === 0) return;
+  let wsHooks = null;
+  try {
+    const wsSettings = JSON.parse(readFileSync(join(absRoot, '.claude', 'settings.json'), 'utf8'));
+    if (isPlainObject(wsSettings?.hooks)) wsHooks = wsSettings.hooks;
+  } catch {
+    return; // the config entry already flagged it unparseable
+  }
+  for (let i = 0; i < result.removed.length; i++) {
+    const rel = result.removed[i];
+    if (typeof rel !== 'string' || !rel.startsWith('.claude/hooks/')) continue;
+    const referencedBy = [];
+    for (const arr of settings.arrays) {
+      if (arr.path.startsWith('hooks/') && arr.workspaceOnly.some((el) => JSON.stringify(el).includes(rel))) {
+        referencedBy.push(`settings.json ${arr.path.split('/').join('.')}`);
+      }
+    }
+    for (const path of settings.workspaceOnly) {
+      if (!path.startsWith('hooks/')) continue;
+      const event = wsHooks && wsHooks[path.split('/')[1]];
+      if (event !== undefined && JSON.stringify(event).includes(rel)) {
+        referencedBy.push(`settings.json ${path.split('/').join('.')}`);
+      }
+    }
+    if (referencedBy.length > 0) {
+      result.removed[i] = { file: rel, referencedBy };
+    }
+  }
+}
+
 // ---------- CLAUDE.md merge ----------
 
 /**
@@ -417,7 +709,17 @@ function resolvePayload(args) {
 }
 
 function writeBaselineMode(args) {
-  const baseline = writeBaseline(args.root, resolvePayload(args));
+  const absPayload = resolvePayload(args);
+  // The previous baseline decides which declined updates keep their old
+  // entry — resolve it exactly as classification does, so the worktree flow
+  // (no baseline of its own yet) carries over from the payload's
+  // reconstructed one instead of starting from nothing.
+  const { baseline: previous } = resolveBaseline({
+    root: args.root,
+    payload: absPayload,
+    baseline: args.baseline,
+  });
+  const baseline = writeBaseline(args.root, absPayload, { previous });
   process.stdout.write(JSON.stringify({
     written: true,
     path: BASELINE_PATH,
@@ -426,6 +728,25 @@ function writeBaselineMode(args) {
   }, null, 2) + '\n');
 }
 
+/**
+ * `@{path}` include lines in a CLAUDE.md body whose target file does not
+ * exist at the workspace root. Machine-local targets (`local-only-*`
+ * basenames) are expected absent on machines that never wrote them — the
+ * same exemption the maintenance audit gives those imports — so they never
+ * report. The include-line shape mirrors context-footprint's resolveImports:
+ * a line whose trimmed content is exactly `@` plus a path.
+ */
+function missingIncludes(absRoot, text) {
+  const missing = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const m = /^@(\S+)$/.exec(rawLine.trim());
+    if (!m) continue;
+    if (m[1].split('/').pop().startsWith('local-only-')) continue;
+    if (!existsSync(resolve(absRoot, m[1]))) missing.push(m[1]);
+  }
+  return missing;
+}
+
 function mergeClaudeMdMode(args) {
   const absRoot = resolve(args.root);
   const absPayload = resolvePayload(args);
@@ -443,7 +764,14 @@ function mergeClaudeMdMode(args) {
   const next = readFileSync(tmplPath, 'utf8').replace(/\{\{project-name\}\}/g, name);
   const claudeMdPath = join(absRoot, 'CLAUDE.md');
   const current = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf8') : '';
-  process.stdout.write(mergeClaudeMd(current, next));
+  const claudeMd = mergeClaudeMd(current, next);
+  // The gained-@include check is deterministic, not something to eyeball in
+  // the diff: every include line whose target is absent here is reported so
+  // the skill asks (stub or omit) instead of writing it silently (gh:190).
+  process.stdout.write(JSON.stringify({
+    claudeMd,
+    missingIncludes: missingIncludes(absRoot, claudeMd),
+  }, null, 2) + '\n');
 }
 
 function main() {
@@ -453,7 +781,7 @@ function main() {
   } else if (args.mergeClaudeMd) {
     mergeClaudeMdMode(args);
   } else {
-    const result = classifyUpdate({ root: args.root, payload: args.payload });
+    const result = classifyUpdate({ root: args.root, payload: args.payload, baseline: args.baseline });
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   }
 }

package/template/_claude/scripts/cleanup-work-session.mjs

@@ -4,7 +4,10 @@
 // Teardown order is MANDATORY:
 //   1. Remove each project worktree from its project repo
 //   2. Remove the workspace worktree from the workspace repo
-//   3. Prune each project repo (belt-and-suspenders)
+//   3. Prune each project repo (belt-and-suspenders — and only when every
+//      prunable record in the repo belongs to this session; a repo also
+//      holding an unrelated external worktree is never pruned, so its
+//      record survives gh:187)
 //   4. Delete all local branches
 //   5. Remove the whole work-sessions/{name}/ folder
 //
@@ -83,6 +86,25 @@ function isRepoSegment(name) {
   return !/^\.+$/.test(segs[0]);
 }
 
+// `worktree list --porcelain` stanzas reduced to what prune scoping needs:
+// each stanza's worktree path and whether git marked it prunable. Paths
+// are kept exactly as git printed them (realOf is applied by callers, so
+// a record whose directory is gone survives the comparison).
+function worktreeStanzas(porcelain) {
+  const stanzas = [];
+  let cur = null;
+  for (const line of String(porcelain).split(/\r?\n/)) {
+    if (line.startsWith('worktree ')) {
+      if (cur) stanzas.push(cur);
+      cur = { path: line.slice(9), prunable: false };
+    } else if (cur && line.startsWith('prunable')) {
+      cur.prunable = true;
+    }
+  }
+  if (cur) stanzas.push(cur);
+  return stanzas;
+}
+
 const args = process.argv.slice(2);
 const getArg = (name) => {
   const idx = args.indexOf(`--${name}`);
@@ -335,9 +357,42 @@ if (existsSync(wsWorktree)) {
 }
 
 // === Step 3: Prune each project repo to mop up orphans ===
+//
+// `git worktree prune` has no path filter: one invocation drops EVERY
+// prunable record the repo holds, including records of worktrees that
+// have nothing to do with this workspace — a scratch checkout in tmp, a
+// directory on another drive (gh:187). Those belong to no session, so
+// prune runs only when every prunable record in the repo sits under this
+// session's folder; otherwise it is skipped and the records are named in
+// the output, left registered for whoever owns them.
+const sessionFolderReal = realOf(sessionFolder);
+const sessionFolderAbs = resolve(sessionFolder);
+const underSessionFolder = (recordedPath) => {
+  const normalized = realOf(recordedPath);
+  return [sessionFolderReal, sessionFolderAbs].some(
+    (base) => normalized === base || normalized.startsWith(base + sep)
+      || recordedPath === base || recordedPath.startsWith(base + sep),
+  );
+};
 for (const repo of repos) {
   const repoDir = join(reposDir, repo);
   if (!existsSync(repoDir)) continue;
+  const listRes = git(repoDir, ['worktree', 'list', '--porcelain']);
+  if (!listRes.ok) {
+    errors.push(`Could not list worktrees in ${repo}: ${listRes.err || listRes.out}`);
+    continue;
+  }
+  const foreign = worktreeStanzas(listRes.out)
+    .filter((s) => s.prunable && !underSessionFolder(s.path))
+    .map((s) => s.path);
+  if (foreign.length > 0) {
+    skipped.push({
+      step: 'prune',
+      repo,
+      reason: `prune skipped: ${repo} has prunable worktree records outside this session (${foreign.join(', ')}) — a blanket prune would drop them; they were left registered for their owner`,
+    });
+    continue;
+  }
   const res = git(repoDir, ['worktree', 'prune']);
   if (!res.ok) {
     // Prune is a safety net, but if it fails on a repo we touched, surface
@@ -407,8 +462,14 @@ for (const repo of repos) {
     continue;
   }
   const wtList = listRes.out;
-  if (wtList.includes('prunable')) {
-    errors.push(`Prunable worktree record remains in ${repo} after cleanup (gh:119 symptom)`);
+  // Only this session's own prunable records are a leftover gh:119 orphan;
+  // a prunable record elsewhere in the repo is someone else's worktree and
+  // stays exactly as found (step 3 refused to prune it for that reason).
+  const leftover = worktreeStanzas(wtList)
+    .filter((s) => s.prunable && underSessionFolder(s.path))
+    .map((s) => s.path);
+  if (leftover.length > 0) {
+    errors.push(`Prunable worktree record(s) remain in ${repo} after cleanup (${leftover.join(', ')}) — the gh:119 symptom; inspect them, then run git -C ${repoDir} worktree prune yourself`);
   }
   if (wtList.includes(wsPath)) {
     errors.push(`${repo} still has a worktree record referencing the session path`);