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

package/lib/init.mjs

@@ -2,6 +2,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, readdirSync, statSync } from 'fs';
 import { join, basename } from 'path';
 import { stagePayload } from './payload.mjs';
+import { writeBaseline } from '../template/_claude/scripts/template-baseline.mjs';
 
 function ensureDir(dir) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -127,6 +128,14 @@ export async function initWorkspace(targetDir) {
     }
   }
 
+  // Record the template baseline — the sha256 of every verbatim payload file —
+  // so the first /workspace-update can tell template changes from local edits
+  // three ways (gh:183). Entries always hold the payload's content, so the
+  // components /workspace-init installs verbatim are already covered;
+  // /workspace-init refreshes the baseline after the full install anyway.
+  writeBaseline(targetDir, payloadDir, { version: toVersion });
+  console.log('  Wrote template baseline (.claude/.template-baseline.json)');
+
   console.log(`
   Workspace initialized (v${toVersion}).
 

package/lib/init.test.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Test for init.mjs (--init scaffolding)
+// Run: node lib/init.test.mjs
+//
+// --init stages the template payload, installs the bootstrap skills plus
+// hooks/scripts/lib, and must leave a template baseline behind: the sha256 of
+// every verbatim payload file, so the first /workspace-update classifies
+// three ways instead of treating every template change as a local edit
+// (gh:183).
+import { initWorkspace } from './init.mjs';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+let failed = 0;
+let passed = 0;
+function check(label, ok) {
+  if (ok) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${label}`);
+  }
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgVersion = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version;
+const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex');
+
+const root = mkdtempSync(join(tmpdir(), 'init-test-'));
+
+try {
+  await initWorkspace(root);
+
+  const baselinePath = join(root, '.claude', '.template-baseline.json');
+  check('baseline written at .claude/.template-baseline.json', existsSync(baselinePath));
+  const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+
+  check(`baseline records the payload version (${pkgVersion})`, baseline.templateVersion === pkgVersion);
+  check(
+    'baseline covers the bootstrap skills --init installs',
+    typeof baseline.files['.claude/skills/workspace-update/SKILL.md'] === 'string'
+      && typeof baseline.files['.claude/skills/workspace-init/SKILL.md'] === 'string',
+  );
+  check(
+    'baseline covers hooks and scripts',
+    typeof baseline.files['.claude/hooks/session-start.mjs'] === 'string'
+      && typeof baseline.files['.claude/scripts/classify-update.mjs'] === 'string',
+  );
+  check(
+    'baseline covers the standalone verbatim files',
+    typeof baseline.files['.mcp.json'] === 'string' && typeof baseline.files['.claudeignore'] === 'string',
+  );
+  check(
+    'entry hash matches the installed file byte-for-byte',
+    baseline.files['.claude/scripts/classify-update.mjs'] === sha(join(root, '.claude', 'scripts', 'classify-update.mjs')),
+  );
+  check(
+    'baseline never covers tests (the tarball ships none)',
+    Object.keys(baseline.files).every((k) => !k.endsWith('.test.mjs')),
+  );
+  check(
+    'baseline never covers machine-local files',
+    !('.claude/settings.local.json' in baseline.files) && !('.claude/.active-session.json' in baseline.files),
+  );
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}
+
+if (failed > 0) {
+  console.error(`${failed} check(s) failed, ${passed} passed`);
+  process.exit(1);
+}
+console.log(`${passed} checks passed`);

package/lib/scaffold.mjs

@@ -1,6 +1,7 @@
 import { cpSync, mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, rmSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { writeBaseline, INERT_PAIRS } from '../template/_claude/scripts/template-baseline.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE_DIR = join(__dirname, '..', 'template');
@@ -98,5 +99,12 @@ export async function scaffold(answers) {
     }
   }
 
+  // Record the template baseline — the sha256 of every verbatim-installed
+  // file — so /workspace-update can classify three ways (workspace vs payload
+  // vs baseline) instead of treating every template change as a local edit
+  // (gh:183). The template tree carries the inert names; entries always hold
+  // the template's content, so hashes come straight from the source of truth.
+  writeBaseline(directory, TEMPLATE_DIR, { pairs: INERT_PAIRS, version: pkgJson.version });
+
   return directory;
 }

package/lib/scaffold.test.mjs

@@ -48,6 +48,26 @@ try {
   check('no _claude/ leftover', !existsSync(join(directory, '_claude')));
   check('no _mcp.json leftover', !existsSync(join(directory, '_mcp.json')));
   check('no _gitignore leftover', !existsSync(join(directory, '_gitignore')));
+
+  // Template baseline: hashes of the verbatim-installed files, for three-way
+  // update classification (gh:183)
+  const baselinePath = join(directory, '.claude', '.template-baseline.json');
+  check('template baseline written', existsSync(baselinePath));
+  const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+  const pkgVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  check(`baseline records the package version (${pkgVersion})`, baseline.templateVersion === pkgVersion);
+  check(
+    'baseline covers rules installed verbatim from the template',
+    typeof baseline.files['.claude/rules/coherent-revisions.md'] === 'string',
+  );
+  check(
+    'baseline covers .mcp.json via its inert source name',
+    typeof baseline.files['.mcp.json'] === 'string' && typeof baseline.files['.claudeignore'] === 'string',
+  );
+  check(
+    'baseline never covers tests or machine-local files',
+    Object.keys(baseline.files).every((k) => !k.endsWith('.test.mjs') && k !== '.claude/settings.local.json'),
+  );
 } finally {
   rmSync(directory, { recursive: true, force: true });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.21.0-beta.0",
+  "version": "0.22.0-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

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

@@ -4,33 +4,80 @@
 //
 // Usage:
 //   node classify-update.mjs [--root <dir>] [--payload <dir>]
+//   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
 //
-// Prints JSON with five lists:
-//   new       — no installed counterpart; safe to batch-apply after one confirm
-//   identical — installed file already equals the payload byte-for-byte
-//   differs   — installed file differs; needs a per-file decision
-//   activated — the payload ships rules/{name}.md.skip while the workspace
-//               deliberately keeps {name}.md active; nothing to install, the
-//               active rule stays (gh:180)
-//   removed   — installed file with no payload counterpart: the template
-//               stopped shipping it. Excludes what the workspace owns:
-//               *.test.mjs (the npm tarball does not ship tests, dev-checkout
-//               installs do — every test file would otherwise read as
-//               removed), 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)
+// The default mode prints JSON with these lists:
+//   new        — no installed counterpart and no baseline entry; safe to
+//                batch-apply after one confirm
+//   identical  — installed file already equals the payload
+//   updated    — installed file equals the BASELINE (what the template last
+//                shipped here) but not the payload: a pure template change the
+//                user never touched. Batched with `new` behind one confirm.
+//   differs    — installed file matches neither the payload nor the baseline
+//                while the payload also differs from the baseline: a local
+//                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).
+//   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.
+//                Listed for information only — never asked about, never
+//                applied.
+//   deletedLocally — the baseline records the file and the payload still
+//                ships it, but it is missing from the workspace: deleted
+//                locally (or never installed at /workspace-init). The skill
+//                asks once whether to restore the list.
+//   activated  — the payload ships rules/{name}.md.skip while the workspace
+//                deliberately keeps {name}.md active; nothing to install, the
+//                active rule stays (gh:180)
+//   removed    — installed file with no payload counterpart: the template
+//                stopped shipping it. Excludes what the workspace owns:
+//                *.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)
+//   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)
+//
+// 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.
+//
+// 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.
+//
+// The other two modes are /workspace-update bookends:
+//   --write-baseline  write .claude/.template-baseline.json recording the
+//                     hash of every verbatim payload file — what the template
+//                     now ships. Run at the END of an update, after all
+//                     per-file decisions. Entries record the PAYLOAD hash —
+//                     except unapplied updates (workspace still holds the old
+//                     baseline content), which keep the old entry so they
+//                     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.
 
 import {
   existsSync,
@@ -39,9 +86,10 @@ import {
   statSync,
   realpathSync,
 } from 'node:fs';
-import { join, resolve } from 'node:path';
+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';
 
 function isMainModule(metaUrl) {
   if (!process.argv[1]) return false;
@@ -51,11 +99,13 @@ function isMainModule(metaUrl) {
 }
 
 function parseArgs(argv) {
-  const args = { root: process.cwd(), payload: null };
+  const args = { root: process.cwd(), payload: 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 === '--write-baseline') args.writeBaseline = true;
+    else if (a === '--merge-claude-md') args.mergeClaudeMd = true;
     else throw new Error(`Unknown arg: ${a}`);
   }
   return args;
@@ -136,9 +186,11 @@ function globMatches(pattern, rel) {
 }
 
 function isOwnedByWorkspace(rel, localFiles) {
-  if (rel.endsWith('.test.mjs')) return true;
-  // The template's own .gitignore declares these machine-local.
-  if (rel === '.claude/settings.local.json' || rel === '.claude/.active-session.json') return true;
+  // The template's own .gitignore declares these machine-local; the baseline
+  // is per-workspace state the template never ships.
+  if (rel === '.claude/settings.local.json' || rel === '.claude/.active-session.json' || rel === BASELINE_PATH) {
+    return true;
+  }
   if (!rel.startsWith('.claude/')) return false;
   const claudeRel = rel.slice('.claude/'.length);
   return localFiles.some((pattern) => globMatches(pattern, claudeRel));
@@ -153,8 +205,20 @@ export function classifyUpdate({ root, payload }) {
 
   const payloadFiles = [...walkFiles(absPayload)].filter(isClassified);
   const payloadSet = new Set(payloadFiles);
+  const baseline = readBaseline(absRoot);
 
-  const result = { new: [], identical: [], differs: [], activated: [], removed: [] };
+  const result = {
+    new: [],
+    identical: [],
+    updated: [],
+    differs: [],
+    localOnly: [],
+    deletedLocally: [],
+    activated: [],
+    removed: [],
+    staleTests: [],
+    hasBaseline: baseline !== null,
+  };
   for (const rel of payloadFiles) {
     // A .skip rule whose active counterpart is installed was deliberately
     // activated by this workspace: report it as activated, not new.
@@ -167,14 +231,34 @@ export function classifyUpdate({ root, payload }) {
     }
     const installed = join(absRoot, rel);
     if (!existsSync(installed)) {
-      result.new.push(rel);
+      // A file the baseline records and the payload still ships, yet missing
+      // from the workspace: deleted locally (or declined at install time) —
+      // not new, the template has carried it all along.
+      if (baseline && typeof baseline.files[rel] === 'string') {
+        result.deletedLocally.push(rel);
+      } else {
+        result.new.push(rel);
+      }
       continue;
     }
-    const payloadBytes = readFileSync(join(absPayload, rel));
-    const installedBytes = readFileSync(installed);
-    if (Buffer.compare(payloadBytes, installedBytes) === 0) {
+    const wsHash = hashBytes(readFileSync(installed));
+    const payloadHash = hashBytes(readFileSync(join(absPayload, rel)));
+    if (wsHash === payloadHash) {
       result.identical.push(rel);
+      continue;
+    }
+    const baseHash = baseline ? baseline.files[rel] : undefined;
+    if (baseHash !== undefined && wsHash === baseHash) {
+      // Workspace still holds exactly what the template last shipped here —
+      // the difference is the template's own change since then.
+      result.updated.push(rel);
+    } else if (baseHash !== undefined && payloadHash === baseHash) {
+      // The payload is unchanged since the baseline; the workspace's
+      // difference is purely local. Informational — nothing to apply.
+      result.localOnly.push(rel);
     } else {
+      // A local edit on top of a template change (or no baseline entry to
+      // compare) — the one case that needs a per-file decision.
       result.differs.push(rel);
     }
   }
@@ -190,16 +274,188 @@ export function classifyUpdate({ root, payload }) {
     // not a removed one.
     if (rel.startsWith('.claude/rules/') && rel.endsWith('.md') && skipSet.has(`${rel}.skip`)) continue;
     if (gitignored.has(rel)) continue;
+    // Test files never come from the npm tarball; the payload not carrying one
+    // means the template's test suite moved on without this copy.
+    if (rel.endsWith('.test.mjs')) {
+      result.staleTests.push(rel);
+      continue;
+    }
     if (isOwnedByWorkspace(rel, localFiles)) continue;
     result.removed.push(rel);
   }
   return result;
 }
 
+// ---------- CLAUDE.md merge ----------
+
+/**
+ * Split markdown into blocks: the preamble (heading null) plus one block per
+ * `## ` heading. Deeper headings belong to their enclosing section, and `## `
+ * lines inside fenced code blocks (``` or ~~~) stay content of their section.
+ */
+function splitBlocks(text) {
+  const blocks = [];
+  let cur = { heading: null, lines: [] };
+  let fenced = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*(```|~~~)/.test(line)) fenced = !fenced;
+    if (!fenced && /^##\s/.test(line)) {
+      blocks.push(cur);
+      cur = { heading: line.trim(), lines: [] };
+    } else {
+      cur.lines.push(line);
+    }
+  }
+  blocks.push(cur);
+  return blocks;
+}
+
+/**
+ * A heading's merge key. Identical headings match; beyond that, any
+ * `## Workspace:` heading matches any other — the intro heading carries the
+ * workspace name, which differs the moment a workspace is renamed (or the
+ * fallback directory name was used), and treating them as two sections
+ * duplicated the template's intro alongside the renamed original.
+ */
+function headingKey(heading) {
+  if (heading !== null && heading.startsWith('## Workspace:')) return '## Workspace:';
+  return heading;
+}
+
+/**
+ * A list entry's merge key: the name of its first backticked `/command`
+ * token (`- \`/start-work [handoff|blank]\` — …` → start-work). Two entries
+ * with the same name are the same skill, so the template's reworded line
+ * replaces the workspace's instead of duplicating it.
+ */
+function entryKey(line) {
+  const m = line.match(/^\s*[-*]\s+`\/([a-z0-9][a-z0-9-]*)[^`]*`/);
+  return m ? m[1] : null;
+}
+
+function trimTrailingBlanks(lines) {
+  let end = lines.length;
+  while (end > 0 && lines[end - 1].trim() === '') end--;
+  return lines.slice(0, end);
+}
+
+function trimLeadingBlanks(lines) {
+  let start = 0;
+  while (start < lines.length && lines[start].trim() === '') start++;
+  return lines.slice(start);
+}
+
+/**
+ * One section's bodies merged: the template's new lines, then the workspace's
+ * lines that the template no longer carries (matched by entry name for list
+ * entries, by trimmed text otherwise).
+ */
+function mergeBody(curLines, nxtLines) {
+  const nxtKeys = new Set(nxtLines.map(entryKey).filter(Boolean));
+  const nxtTrimmed = new Set(nxtLines.map((l) => l.trim()).filter(Boolean));
+  const kept = [];
+  for (const line of curLines) {
+    const key = entryKey(line);
+    if (key !== null && nxtKeys.has(key)) continue; // template owns this entry — its line updates ours
+    const t = line.trim();
+    if (t !== '' && nxtTrimmed.has(t)) continue; // unchanged line, already present
+    kept.push(line);
+  }
+  const body = trimTrailingBlanks(nxtLines);
+  return kept.length === 0 ? body : [...body, ...trimLeadingBlanks(trimTrailingBlanks(kept))];
+}
+
+function renderBlocks(blocks, eol) {
+  const parts = [];
+  for (const b of blocks) {
+    const body = trimTrailingBlanks(b.lines);
+    if (b.heading === null) {
+      if (body.length > 0) parts.push(body.join(eol));
+    } else {
+      parts.push([b.heading, ...body].join(eol));
+    }
+  }
+  return parts.join(eol + eol) + eol;
+}
+
+/**
+ * Merge an updated template CLAUDE.md (`nextText`, already {{project-name}}-
+ * substituted) into the workspace's current one. Template-owned lines take the
+ * template's new versions; lines the template doesn't have — the workspace's
+ * own skill entries, custom bullets, whole sections — are kept. Sections are
+ * matched by heading (`## Workspace:` headings match regardless of name): the
+ * result follows the workspace's section order, new template sections are
+ * appended at the end, and kept lines land at the end of their section. The
+ * output keeps the current file's line endings — CRLF in, CRLF out.
+ */
+export function mergeClaudeMd(currentText, nextText) {
+  const eol = currentText != null && currentText.includes('\r\n') ? '\r\n' : '\n';
+  const nxtBlocks = splitBlocks(nextText);
+  if (currentText == null || currentText.trim() === '') return renderBlocks(nxtBlocks, eol);
+  const nxtByHeading = new Map(nxtBlocks.map((b) => [headingKey(b.heading), b]));
+  const used = new Set();
+  const out = [];
+  for (const cur of splitBlocks(currentText)) {
+    const nxt = nxtByHeading.get(headingKey(cur.heading));
+    if (nxt) {
+      used.add(nxt);
+      out.push({ heading: nxt.heading, lines: mergeBody(cur.lines, nxt.lines) });
+    } else {
+      out.push(cur); // a section the template doesn't have — the workspace's own
+    }
+  }
+  for (const nxt of nxtBlocks) {
+    if (!used.has(nxt)) out.push({ heading: nxt.heading, lines: trimTrailingBlanks(nxt.lines) });
+  }
+  return renderBlocks(out, eol);
+}
+
+// ---------- CLI modes ----------
+
+function resolvePayload(args) {
+  return resolve(args.payload ?? join(resolve(args.root), '.workspace-update'));
+}
+
+function writeBaselineMode(args) {
+  const baseline = writeBaseline(args.root, resolvePayload(args));
+  process.stdout.write(JSON.stringify({
+    written: true,
+    path: BASELINE_PATH,
+    templateVersion: baseline.templateVersion,
+    files: Object.keys(baseline.files).length,
+  }, null, 2) + '\n');
+}
+
+function mergeClaudeMdMode(args) {
+  const absRoot = resolve(args.root);
+  const absPayload = resolvePayload(args);
+  const tmplPath = join(absPayload, 'CLAUDE.md.tmpl');
+  if (!existsSync(tmplPath)) {
+    throw new Error(`No CLAUDE.md.tmpl in ${absPayload} — nothing to merge`);
+  }
+  // The workspace name for {{project-name}} substitution: workspace.json is
+  // the source of truth; the directory name is the fallback.
+  let name = basename(absRoot);
+  try {
+    const config = JSON.parse(readFileSync(join(absRoot, 'workspace.json'), 'utf8'));
+    if (typeof config?.workspace?.name === 'string' && config.workspace.name) name = config.workspace.name;
+  } catch { /* no workspace.json — keep the directory name */ }
+  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));
+}
+
 function main() {
   const args = parseArgs(process.argv);
-  const result = classifyUpdate({ root: args.root, payload: args.payload });
-  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  if (args.writeBaseline) {
+    writeBaselineMode(args);
+  } else if (args.mergeClaudeMd) {
+    mergeClaudeMdMode(args);
+  } else {
+    const result = classifyUpdate({ root: args.root, payload: args.payload });
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  }
 }
 
 if (isMainModule(import.meta.url)) {

package/template/_claude/scripts/template-baseline.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// Template baseline: the sha256 of every verbatim-installed file the template
+// last shipped, recorded at <root>/.claude/.template-baseline.json. It is the
+// third input of /workspace-update's three-way classification (workspace vs
+// payload vs baseline), so a file the template changed since the installed
+// version reads as an update to apply in batch — not a local edit to negotiate
+// file by file (gh:183).
+//
+// Shape:
+//   { "templateVersion": "0.21.0",
+//     "files": { ".claude/skills/workspace-update/SKILL.md": "<sha256>", … } }
+// Keys are root-relative posix paths covering the verbatim-installed roots
+// (.claude/**, .mcp.json, .claudeignore). The file is committed with the
+// workspace — every machine that pulls gets the same template files, so it
+// gets the same baseline.
+//
+// Written by `--init` scaffolding (lib/init.mjs), by /workspace-init once the
+// remaining components are installed, and at the end of every /workspace-update
+// (classify-update.mjs --write-baseline). Interactive scaffolding writes it
+// from the template tree (lib/scaffold.mjs).
+//
+// The rule every entry follows: record the hash of the payload's content —
+// what the template last shipped — never the workspace's on-disk bytes. A
+// file the user kept despite a template change therefore keeps the PAYLOAD
+// hash: the next update sees workspace ≠ baseline with payload == baseline
+// and reports the file as a purely local edit (informational, not re-asked
+// per file) until the template touches it again, and a deliberate divergence
+// is never silently adopted as the new baseline. One exception: an unapplied
+// update — the workspace still holds the OLD baseline content while the
+// payload ships something new (the user declined the `updated` batch) — keeps
+// the old entry, so the file re-presents as `updated` next time instead of
+// being filed away as a local edit. The invariant that matters either way: a
+// file the user never touched (workspace == baseline) is never reported as a
+// local edit.
+//
+// All hashes are CRLF-normalized for text files (see hashBytes): a Windows
+// autocrlf checkout stores CRLF where the payload carries LF, and byte-exact
+// hashing would read every such file as locally modified. Files containing
+// NUL bytes hash byte-exact.
+//
+// Not covered: *.test.mjs (the tarball never ships them; a workspace's test
+// files came from a dev checkout and age independently — classify-update
+// reports them as staleTests instead), machine-local files
+// (.claude/settings.local.json, .claude/.active-session.json), and anything
+// under .claude/worktrees/.
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const BASELINE_PATH = '.claude/.template-baseline.json';
+
+// [source name, installed name] pairs for the verbatim-installed roots. The
+// staged payload carries the live names; the template tree stores .claude/ and
+// .mcp.json under the inert names _claude/ and _mcp.json, so scaffold passes
+// the inert pairs.
+export const LIVE_PAIRS = [
+  ['.claude', '.claude'],
+  ['.mcp.json', '.mcp.json'],
+  ['.claudeignore', '.claudeignore'],
+];
+export const INERT_PAIRS = [
+  ['_claude', '.claude'],
+  ['_mcp.json', '.mcp.json'],
+  ['.claudeignore', '.claudeignore'],
+];
+
+// Machine-local or per-workspace files that never belong in the baseline.
+const OWNED_PATHS = new Set([
+  '.claude/settings.local.json',
+  '.claude/.active-session.json',
+  BASELINE_PATH,
+]);
+
+// Entire nested worktrees live under .claude/worktrees/ — never walked.
+const SKIP_DIRS = new Set(['worktrees']);
+
+/**
+ * The content hash used by the baseline and by classification: sha256 with
+ * CRLF normalized to LF for text files, byte-exact for binary (anything
+ * containing a NUL byte — git's own text/binary heuristic). Both the payload
+ * and the workspace side hash through this, so a git autocrlf checkout that
+ * stores CRLF where the payload ships LF classifies as identical instead of
+ * reading every file as locally modified.
+ */
+export function hashBytes(bytes) {
+  let body = bytes;
+  if (!bytes.includes(0)) {
+    // latin1 round-trips bytes 1:1 — safe on text that isn't valid UTF-8 too.
+    body = Buffer.from(bytes.toString('latin1').replace(/\r\n/g, '\n'), 'latin1');
+  }
+  return createHash('sha256').update(body).digest('hex');
+}
+
+function* walkFiles(dir, prefix = '') {
+  let entries;
+  try {
+    entries = readdirSync(dir).sort();
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (prefix === '.claude' && SKIP_DIRS.has(name)) continue;
+    const rel = prefix ? `${prefix}/${name}` : name;
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) yield* walkFiles(full, rel);
+    else if (st.isFile()) yield rel;
+  }
+}
+
+/**
+ * Read the baseline at <root>/.claude/.template-baseline.json. Returns
+ * { templateVersion, files } or null when absent (workspaces older than the
+ * baseline's introduction) or unparseable — classification then falls back to
+ * the two-way behavior rather than failing the update.
+ */
+export function readBaseline(root) {
+  const path = join(resolve(root), BASELINE_PATH);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.files !== 'object' || parsed.files === null) {
+      return null;
+    }
+    return { templateVersion: typeof parsed.templateVersion === 'string' ? parsed.templateVersion : null, files: parsed.files };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a baseline from a template source directory (a staged payload with
+ * live names, or the template tree via INERT_PAIRS). `version` overrides the
+ * payload manifest's templateVersion — pass it when the source has no
+ * .manifest.json (the template tree).
+ */
+export function buildBaseline(sourceDir, { pairs = LIVE_PAIRS, version = null } = {}) {
+  const absSource = resolve(sourceDir);
+  const files = {};
+  for (const [sourceName, installedName] of pairs) {
+    const src = join(absSource, sourceName);
+    if (!existsSync(src)) continue;
+    let st;
+    try { st = statSync(src); } catch { continue; }
+    if (st.isFile()) {
+      if (!OWNED_PATHS.has(installedName) && !installedName.endsWith('.test.mjs')) {
+        files[installedName] = hashBytes(readFileSync(src));
+      }
+      continue;
+    }
+    for (const rel of walkFiles(src, installedName)) {
+      if (OWNED_PATHS.has(rel) || rel.endsWith('.test.mjs')) continue;
+      files[rel] = hashBytes(readFileSync(join(absSource, sourceName, rel.slice(installedName.length + 1))));
+    }
+  }
+  let templateVersion = version;
+  if (templateVersion === null) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(absSource, '.manifest.json'), 'utf8'));
+      if (typeof manifest.templateVersion === 'string') templateVersion = manifest.templateVersion;
+    } catch {
+      // No manifest (or unreadable) — caller should pass `version`.
+    }
+  }
+  return { templateVersion, files: Object.fromEntries(Object.keys(files).sort().map((k) => [k, files[k]])) };
+}
+
+/**
+ * Write the baseline for the workspace at `root`. Returns the written object.
+ *
+ * Refuses to write an empty baseline: a missing source directory or one that
+ * yields zero verbatim files throws rather than clobbering an existing good
+ * baseline with `{files:{}}` (which would make the next update classify every
+ * template change as a local edit).
+ *
+ * Before writing, entries carried over from the previous baseline are kept as
+ * they were for unapplied updates: a file whose workspace content still
+ * matches the old baseline while the payload ships something new (a declined
+ * `updated` batch) keeps the OLD entry, so the next update still offers the
+ * change instead of filing the file away as a local edit.
+ */
+export function writeBaseline(root, sourceDir, opts = {}) {
+  const absRoot = resolve(root);
+  const baseline = buildBaseline(sourceDir, opts);
+  if (Object.keys(baseline.files).length === 0) {
+    throw new Error(
+      `No verbatim template files found under ${resolve(sourceDir)} — refusing to write an empty baseline`,
+    );
+  }
+  const previous = readBaseline(absRoot);
+  if (previous) {
+    for (const rel of Object.keys(baseline.files)) {
+      const oldHash = previous.files[rel];
+      if (typeof oldHash !== 'string' || oldHash === baseline.files[rel]) continue;
+      const installed = join(absRoot, rel);
+      if (existsSync(installed) && hashBytes(readFileSync(installed)) === oldHash) {
+        // Unapplied update: the workspace never took the payload's change.
+        baseline.files[rel] = oldHash;
+      }
+    }
+  }
+  const dest = join(absRoot, BASELINE_PATH);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, JSON.stringify(baseline, null, 2) + '\n');
+  return baseline;
+}

package/template/_claude/skills/workspace-init/SKILL.md

@@ -126,6 +126,12 @@ Also install these top-level files from the payload:
 
 **Per-repo CLAUDE.md stubs:** For each repo in `workspace.json`, check if `repos/{repo}/CLAUDE.md` exists. If not, ask "Scaffold a CLAUDE.md for {repo}? [Y/n]". If yes, write a blank stub from `.workspace-update/repo-claude.md.tmpl`, substituting `{{repo-name}}` with the repo name. The stub body is comment text only — no workspace-specific content — and its `## Commands` section is where you will add repo-specific test, lint, and build commands.
 
+**Write the template baseline** now that the components are installed, so future `/workspace-update` runs can tell template changes from local edits (three-way classification):
+```bash
+node .claude/scripts/classify-update.mjs --root . --write-baseline --payload .workspace-update
+```
+It hashes the payload's verbatim files — run it before Step 15 deletes the payload.
+
 **Commit:** `git commit -m "feat: install template components from payload"`
 
 ### Step 6: Activate optional rules

package/template/_claude/skills/workspace-update/SKILL.md

@@ -37,28 +37,36 @@ In the commands below, `{payload}` is `.workspace-update` in the no-remote flow
 
 ### Step 2: Classify the payload
 
-Run the classifier — it compares every verbatim-installed payload file (`.claude/**`, `.mcp.json`, `.claudeignore`) against the workspace by content, and detects files the template no longer ships:
+Run the classifier — it compares every verbatim-installed payload file (`.claude/**`, `.mcp.json`, `.claudeignore`) against the workspace and the template baseline (`.claude/.template-baseline.json`, the hashes of what the template last shipped here), and detects files the template no longer ships:
 
 ```bash
 node {payload}/.claude/scripts/classify-update.mjs --root . --payload {payload}
 ```
 
-It runs from the payload precisely so workspaces that don't have it installed yet can use it; once installed, `node .claude/scripts/classify-update.mjs --root .` is equivalent. Output is JSON with five lists:
+It runs from the payload precisely so workspaces that don't have it installed yet can use it; once installed, `node .claude/scripts/classify-update.mjs --root .` is equivalent. Output is JSON:
 
-- `new` — no installed counterpart; safe to batch-apply (Step 3) behind one confirmation
+- `new` — no installed counterpart and no baseline entry; safe to batch-apply (Step 3) behind one confirmation
 - `identical` — installed file already equals the payload; skip silently
-- `differs` — installed file was locally modified; needs a per-file decision
+- `updated` — installed file still holds the baseline content while the payload ships something new: a pure template change the user never touched. Batched with `new` behind one confirmation
+- `differs` — installed file matches neither the payload nor the baseline, and the template changed it since the baseline too: a local edit that meets a template change. Needs a per-file decision
+- `localOnly` — installed file differs from the payload, but the payload equals the baseline: these are local edits to files the template didn't touch. Informational only — never asked about, never applied
+- `deletedLocally` — the baseline records the file and the payload still ships it, but it is missing from the workspace (deleted locally, or declined at install time). Step 3 asks once whether to restore the list
 - `activated` — the payload ships `rules/{name}.md.skip` while the workspace keeps `{name}.md` active: the rule was deliberately activated. Nothing to install — the active rule stays.
-- `removed` — installed file with no counterpart in the payload. Tests (`*.test.mjs`), gitignored paths, `.claude/worktrees/`, and files listed in `workspace.json` → `workspace.localFiles` (an array of `.claude/`-relative paths or globs the workspace owns) are excluded automatically, so only real template removals are listed.
+- `removed` — installed file with no counterpart in the payload. Gitignored paths, `.claude/worktrees/`, and files listed in `workspace.json` → `workspace.localFiles` (an array of `.claude/`-relative paths or globs the workspace owns) are excluded automatically, so only real template removals are listed.
+- `staleTests` — `*.test.mjs` files under `.claude/` the payload doesn't carry. The package never ships tests, so these came from a dev checkout and no update refreshes them (Step 3 offers removal).
+
+Content is compared with line endings normalized (CRLF ≡ LF; binary files byte-exact), so a Windows autocrlf checkout does not read as locally modified.
+
+If `hasBaseline` is false (the workspace predates v0.21), tell the user: "No template baseline — this first update asks about every changed file individually; once it finishes and writes the baseline (Step 4), later updates won't." Template changes then land in `differs`.
 
 Templates (`*.tmpl`, which install with `{{project-name}}` substitution), `_gitignore` (merged line-by-line), and `.manifest.json` (payload metadata) are not classified — each is handled by its own sub-step in Step 3.
 
 Report with version info from the manifest:
 ```
-"Template update: v{fromVersion} → v{templateVersion}. {N} new files, {M} locally modified, {A} activated rules, {R} removed files, {K} unchanged."
+"Template update: v{fromVersion} → v{templateVersion}. {N} new files, {U} template-updated, {M} locally modified, {L} local-only edits, {D} deleted locally, {A} activated rules, {R} removed files, {K} unchanged."
 ```
 
-If `new`, `differs`, `activated`, and `removed` are all empty, report: "Workspace is up to date (template v{templateVersion}). No changes needed."
+If `new`, `updated`, `differs`, `deletedLocally`, `activated`, and `removed` are all empty, report: "Workspace is up to date (template v{templateVersion}). No changes needed." (`localOnly` files are informational and `staleTests` may still be worth offering.)
 
 ### Step 2b: Historical .gitignore safety check
 
@@ -79,25 +87,40 @@ Commit the fix **before** applying other template updates. This runs ahead of St
 
 ### Step 3: Selective update
 
-Batch the safe case, ask on the rest:
+Batch the safe cases, ask on the rest:
 
-- **New files (`new`):** present the list once — "Apply these {N} new files? [Y/n]" — and install them all on confirmation. No per-file prompting.
-- **Locally modified (`differs`):** ask per file — "Template updated {file} but you have local changes. Show diff? [y/N]" — then apply, keep, or merge per the user's decision.
+- **New and template-updated files (`new` + `updated`):** present both lists once — "Apply these {N} new and {U} template-updated files? [Y/n]" — and install them all on confirmation. No per-file prompting: `updated` means the file still holds exactly what the template last shipped here, so applying the new version loses nothing.
+- **Locally modified (`differs`):** ask per file — "Your version of {file} differs from the template's. Show diff? [y/N]" — then apply, keep, or merge per the user's decision.
+- **Local-only edits (`localOnly`):** nothing to decide — these are your local edits to files the template hasn't changed since the last update. List them in the summary (so the edits are visible) and move on; do not ask about them.
+- **Deleted locally (`deletedLocally`):** "These {N} files exist in the template and its baseline but not in your workspace — deleted locally (or never installed). Restore from the template? [Y/n]" — one confirmation for the whole list. Restoring installs the payload's version of each.
 - **Removed in template (`removed`):** "Template removed {file}. Delete locally? [y/N]" — conservative default.
 - **Activated rules (`activated`):** keep the active file, install nothing — report: "Rule {name} is active here and optional in the template; your activation is preserved."
+- **Stale tests (`staleTests`):** "These {N} test files under .claude/ came from a dev checkout — the package never ships them, so updates can't refresh them (tests live in the template repo). Remove them? [Y/n]" — one confirmation for the whole list.
 - **Hook migration (.sh to .mjs):** Detect old `.sh` hooks in `.claude/hooks/` that have `.mjs` replacements in the payload. Offer: "Hook {name}.sh has a .mjs replacement in the update. Replace and update settings.json commands? [Y/n]" — this is a one-time migration for workspaces upgrading from pre-0.2.0
 
 Also handle these non-component files from the payload:
 
 - **settings.json:** Merge payload values into existing `.claude/settings.json` — do not overwrite user customizations. Add new keys, update hook commands if hooks were migrated, preserve user-added entries.
 - **workspace.json keys:** Compare the `workspace` object of the payload's `workspace.json.tmpl` with the installed `workspace.json`, key by key. For each key the template ships that the workspace lacks, show its template default and ask before adding. Never remove an existing key just because the template no longer ships it. `canonicalBudgetBytes` is opt-in since v0.19 — leave an existing value alone and mention it can be removed to turn the budget off.
-- **CLAUDE.md:** If `{payload}/CLAUDE.md.tmpl` exists, regenerate `CLAUDE.md` from the template. Preserve any user-added sections not present in the template.
+- **CLAUDE.md:** If `{payload}/CLAUDE.md.tmpl` exists, merge — never regenerate from scratch:
+  ```bash
+  node {payload}/.claude/scripts/classify-update.mjs --root . --payload {payload} --merge-claude-md
+  ```
+  The command prints the merged CLAUDE.md: template-owned lines take the template's new versions (skill-list entries match by their `/name`), while lines the template doesn't have — the workspace's own skill entries, custom bullets, whole sections — are kept in place. Two consequences to watch in the diff: an edit made directly to a template-owned skill line is replaced by the template's new wording, and a template prose line that was reworded locally survives alongside the new template line (it may appear twice). The merge keeps the current file's line endings. Show the user the diff against the current CLAUDE.md before writing the merged result.
 - **.gitignore:** Merge new entries from the payload's `_gitignore` into the existing `.gitignore` — do not remove user-added lines.
 
-### Step 4: Update version
+### Step 4: Update version and write the baseline
 
 Read `templateVersion` from `.workspace-update/.manifest.json` and update `templateVersion` in `workspace.json` to match.
 
+Then write the template baseline so the NEXT update classifies three ways instead of asking per file:
+
+```bash
+node {payload}/.claude/scripts/classify-update.mjs --root . --payload {payload} --write-baseline
+```
+
+Run it after every Step 3 decision has been made (it runs from the payload because the workspace's own copy may predate this update). It records the hash of every verbatim payload file — what the template now ships — with one deliberate exception: a file whose update was declined (the workspace still holds the old baseline content while the payload ships something new) keeps the OLD entry, so the change is offered again as `updated` next time instead of being filed away. Everything else records the payload hash: a file the user kept in their own version reads as `localOnly` (informational) until the template changes it again, and a file nobody touched never reads as a local edit. The command refuses to write an empty baseline — if it errors, the payload path is wrong; do not force it.
+
 ### Step 4a: Run idempotent migrators
 
 Two migrators run on **every** update — both idempotent, safe on already-migrated workspaces. Run each and surface its action in the upgrade summary.
@@ -138,7 +161,7 @@ node .claude/scripts/build-workspace-context.mjs --check --root .
 
 `--check` must exit clean. If it reports drift, re-run `--write` and check again before continuing.
 
-Then run the scripted audit — once, covering everything (gh:180). Build the changed list — every file this update added or changed: the applied `new` and `differs` files plus the merged ones (`CLAUDE.md`, `workspace.json`, `.gitignore`, `.claude/settings.json`, `.mcp.json` as touched) — one path per line into a temp file such as `workspace-scratchpad/update-changed.txt`, then:
+Then run the scripted audit — once, covering everything (gh:180). Build the changed list — every file this update added or changed: the applied `new`, `updated`, and `differs` files, any restored `deletedLocally` files, plus the merged ones (`CLAUDE.md`, `workspace.json`, `.gitignore`, `.claude/settings.json`, `.mcp.json` as touched) — one path per line into a temp file such as `workspace-scratchpad/update-changed.txt`, then:
 
 ```bash
 node {payload}/.claude/scripts/maintenance-audit.mjs --root . --changed workspace-scratchpad/update-changed.txt
@@ -178,8 +201,9 @@ After the update is applied, if the sessions directory (`workspace.workSessionsD
 ## Notes
 
 - The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload. This skill processes it.
-- Never overwrites without asking — `new` files are batched behind one confirmation; `differs` files are asked per file
+- Never overwrites without asking — `new` and `updated` files are batched behind one confirmation; `differs` files are asked per file; `localOnly` files are never asked about (local edits to files the template didn't touch)
 - Preserves local modifications, custom content, existing `workspace.json` keys, and deliberately activated rules
+- The template baseline (`.claude/.template-baseline.json`) is what separates `updated`, `differs`, and `localOnly`: entries hold the payload hash of the last-shipped content (unapplied updates keep the older entry), so a deliberately kept local edit stays visible across updates while an untouched file never prompts
 - The launcher's default branch takes a template-update commit only when the workspace has no remote; with a remote, the update lands through a task worktree and a PR
 - Can be run multiple times safely (idempotent) — if `.workspace-update/` doesn't exist, it reports no payload and exits
 - Initial setup is handled by `npx @ulysses-ai/create-workspace --init` + `/workspace-init` — this skill is for subsequent updates only