@ulysses-ai/create-workspace 0.23.0-beta.0 → 0.23.2-beta.0

package/lib/upgrade.mjs

@@ -1,6 +1,7 @@
 // lib/upgrade.mjs
 import {
   existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, rmSync, mkdtempSync, renameSync,
+  readdirSync, statSync,
 } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
@@ -85,35 +86,103 @@ function installWorkspaceUpdateSkill(targetDir, payloadDir, { copySkill = cpSync
   return true;
 }
 
+// Where --upgrade stages the template CONTENT of the version being upgraded
+// FROM, inside the payload and under live names (the paths the payload
+// itself installs). template/_claude/scripts/template-merge.mjs reads it as
+// the common ancestor of a `differs` file's three-way merge — keep the name
+// in sync with that script's TEMPLATE_BASE_DIR.
+const TEMPLATE_BASE_DIR = '.template-base';
+
+function countFiles(dir) {
+  let n = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) n += countFiles(join(dir, entry.name));
+    else if (entry.isFile()) n++;
+  }
+  return n;
+}
+
+// Copy the verbatim-installed template roots (.claude/, .mcp.json,
+// .claudeignore — via the layout pairs of the extracted tarball) into the
+// payload at .template-base/. With this staged, /workspace-update merges
+// each `differs` file three-way (local vs base vs template) instead of
+// asking apply-or-keep on it (gh:193). Best effort: a failure mid-copy
+// removes the half-written base — a partial tree must never be trusted as
+// anyone's ancestor — and warns rather than failing the upgrade.
+function stageTemplateBase(payloadDir, extracted, pairs, fromVersion, { copyBase = cpSync } = {}) {
+  const baseDir = join(payloadDir, TEMPLATE_BASE_DIR);
+  let staged = 0;
+  try {
+    for (const [sourceName, installedName] of pairs) {
+      const src = join(extracted, sourceName);
+      if (!existsSync(src)) continue;
+      copyBase(src, join(baseDir, installedName), { recursive: true });
+      staged += statSync(src).isFile() ? 1 : countFiles(src);
+    }
+  } catch (err) {
+    rmSync(baseDir, { recursive: true, force: true });
+    console.error(`  Warning: could not stage the merge base (${err.message}) — locally modified files will be decided per file.`);
+    return;
+  }
+  if (staged === 0) {
+    rmSync(baseDir, { recursive: true, force: true });
+    console.error('  Warning: no template files to stage as a merge base — locally modified files will be decided per file.');
+    return;
+  }
+  console.log(`  Staged the v${fromVersion} template as a merge base (${staged} files) — .workspace-update/${TEMPLATE_BASE_DIR}/`);
+}
+
 // A workspace upgraded from a pre-baseline template version has no
 // .claude/.template-baseline.json, so its first /workspace-update reports
 // every template change as a local edit — dozens of per-file questions
 // with a handful of real edits among them. The template tree of the
 // INSTALLED version still exists in exactly one place: its published npm
-// tarball. Fetch it, hash what that version shipped (the same
-// normalisation template-baseline.mjs applies everywhere), and stage a
-// baseline for it marked "reconstructed": true INSIDE THE PAYLOAD, not the
-// launcher: with a remote, /workspace-update classifies inside a task
-// worktree that can only see what travels with the payload, and an
-// untracked launcher baseline would dirty the launcher against the incoming
-// PR. classify-update.mjs falls back to the staged file automatically.
-// Any failure — unknown version, offline, unparsable tarball — warns and
-// falls back to the ask-per-file behaviour; the upgrade itself never fails.
-async function reconstructBaseline(payloadDir, fromVersion, { fetchTarball = fetchPackageTarball } = {}) {
-  const fallbackNote = '  The first /workspace-update will ask about every changed file individually.';
+// tarball. Fetch it once, best effort, and stage from it INSIDE THE
+// PAYLOAD, not the launcher: with a remote, /workspace-update classifies
+// inside a task worktree that can only see what travels with the payload,
+// and an untracked launcher baseline would dirty the launcher against the
+// incoming PR. Two things ride on the one fetch:
+//   - a baseline of what that version shipped (the same normalisation
+//     template-baseline.mjs applies everywhere), marked "reconstructed":
+//     true — classify-update.mjs falls back to the staged file
+//     automatically (gh:186); and
+//   - the file CONTENT itself at .template-base/, the common ancestor
+//     template-merge.mjs three-way-merges `differs` files against (gh:193).
+// Any failure — unknown version, offline, unparsable tarball, an IO error
+// mid-staging — warns and falls back to the ask-per-file behaviour; the
+// upgrade itself never fails.
+async function stageInstalledTemplate(payloadDir, root, fromVersion, {
+  fetchTarball = fetchPackageTarball, buildBase = buildBaseline, copyBase = cpSync,
+} = {}) {
+  const hasBaseline = readBaseline(root) !== null;
+  if (hasBaseline) {
+    console.log('  Template baseline already present — leaving it in place.');
+  }
+  const warnNothingStaged = (reason) => {
+    if (hasBaseline) {
+      console.error(`  Warning: ${reason} — no merge base staged for locally modified files.`);
+      console.error('  They will be decided per file, without a three-way merge.');
+    } else {
+      console.error(`  Warning: ${reason} — no template baseline written.`);
+      console.error('  The first /workspace-update will ask about every changed file individually.');
+    }
+  };
+
   if (typeof fromVersion !== 'string' || fromVersion === 'unknown' || fromVersion === '') {
-    console.error('  Warning: workspace.json records no templateVersion — cannot reconstruct a template baseline.');
-    console.error(fallbackNote);
-    return false;
+    warnNothingStaged('workspace.json records no templateVersion');
+    return;
   }
+  // Progress, on stderr: the fetch blocks up to 15 s (45 s through the
+  // npm-pack fallback) before its timeout — an offline operator should
+  // know what the wait is for.
+  console.error(`  Fetching the v${fromVersion} template as the merge base…`);
   let tarball = null;
   try {
     tarball = await fetchTarball(fromVersion);
   } catch { /* a failing fetch is the same as no fetch */ }
   if (tarball === null) {
-    console.error(`  Warning: could not fetch the v${fromVersion} package tarball from npm — no template baseline written.`);
-    console.error(fallbackNote);
-    return false;
+    warnNothingStaged(`could not fetch the v${fromVersion} package tarball from npm`);
+    return;
   }
 
   const tmp = mkdtempSync(join(tmpdir(), 'create-workspace-baseline-'));
@@ -121,27 +190,45 @@ async function reconstructBaseline(payloadDir, fromVersion, { fetchTarball = fet
     // npm tarballs root every file under package/; the template itself
     // ships under both layouts across versions: _claude/ and _mcp.json
     // (v0.19.0 on, same as this package) and the older live-named .claude/
-    // and .mcp.json. buildBaseline maps either onto the installed names
-    // through its pairs.
+    // and .mcp.json. Both staging jobs map either onto the installed names
+    // through the same pairs.
     const extracted = join(tmp, 'template');
-    let baseline = null;
+    let pairs = null;
     try {
       extractTarballEntries(tarball, extracted, { prefix: 'package/template/' });
-      const pairs = existsSync(join(extracted, '_claude')) ? INERT_PAIRS : LIVE_PAIRS;
-      baseline = buildBaseline(extracted, { pairs, version: fromVersion });
+      const candidate = existsSync(join(extracted, '_claude')) ? INERT_PAIRS : LIVE_PAIRS;
+      if (candidate.some(([src]) => existsSync(join(extracted, src)))) pairs = candidate;
     } catch { /* unreadable tarball or unhashable tree — the fallback below */ }
-    if (baseline === null || Object.keys(baseline.files).length === 0) {
-      console.error(`  Warning: the v${fromVersion} package tarball carries no readable template files — no template baseline written.`);
-      console.error(fallbackNote);
-      return false;
+    if (pairs === null) {
+      warnNothingStaged(`the v${fromVersion} package tarball carries no readable template files`);
+      return;
     }
-    baseline.reconstructed = true;
-    writeFileSync(
-      join(payloadDir, RECONSTRUCTED_BASELINE_NAME),
-      JSON.stringify(baseline, null, 2) + '\n',
-    );
-    console.log(`  Reconstructed template baseline for v${fromVersion} from the npm tarball (${Object.keys(baseline.files).length} files) — staged in the payload as ${RECONSTRUCTED_BASELINE_NAME}`);
-    return true;
+
+    if (!hasBaseline) {
+      // Hashing and writing the baseline is as best-effort as everything
+      // downstream of the fetch: a failure warns and behaves like the
+      // no-baseline path, never blocking the merge base staged below.
+      try {
+        const baseline = buildBase(extracted, { pairs, version: fromVersion });
+        if (Object.keys(baseline.files).length === 0) {
+          // The tree extracted fine but nothing in it is baselinable — say
+          // so, and still stage the merge base below.
+          console.error(`  Warning: the v${fromVersion} template files are not baselinable — no template baseline written.`);
+          console.error('  The first /workspace-update will ask about every changed file individually.');
+        } else {
+          baseline.reconstructed = true;
+          writeFileSync(
+            join(payloadDir, RECONSTRUCTED_BASELINE_NAME),
+            JSON.stringify(baseline, null, 2) + '\n',
+          );
+          console.log(`  Reconstructed template baseline for v${fromVersion} from the npm tarball (${Object.keys(baseline.files).length} files) — staged in the payload as ${RECONSTRUCTED_BASELINE_NAME}`);
+        }
+      } catch (err) {
+        console.error(`  Warning: could not stage a template baseline for v${fromVersion} (${err.message}) — no template baseline written.`);
+        console.error('  The first /workspace-update will ask about every changed file individually.');
+      }
+    }
+    stageTemplateBase(payloadDir, extracted, pairs, fromVersion, { copyBase });
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }
@@ -172,18 +259,17 @@ export async function upgradeWorkspace(targetDir, opts = {}) {
 
   const fromVersion = config.workspace?.templateVersion || 'unknown';
 
-  // Stage the payload first: a reconstructed baseline is staged INSIDE it.
+  // Stage the payload first: the reconstructed baseline and the merge base
+  // are staged INSIDE it.
   const { payloadDir, toVersion } = stagePayload(targetDir, { action: 'upgrade', fromVersion });
 
   // A workspace older than the baseline's introduction has no baseline —
   // and a corrupt one is as good as none (readBaseline parses it). In
-  // either case reconstruct one for the installed version into the payload,
-  // so the update can tell template changes from local edits (gh:186).
-  if (readBaseline(targetDir) !== null) {
-    console.log('  Template baseline already present — leaving it in place.');
-  } else {
-    await reconstructBaseline(payloadDir, fromVersion, opts);
-  }
+  // either case stage what the installed version shipped into the payload:
+  // a reconstructed baseline so the update can tell template changes from
+  // local edits (gh:186), and the merge base so it can merge locally edited
+  // files three-way instead of asking apply-or-keep (gh:193).
+  await stageInstalledTemplate(payloadDir, targetDir, fromVersion, opts);
 
   // Bootstrap the current /workspace-update skill — the workspace runs its
   // installed copy next, and the old one does not know this payload's flow.

package/lib/upgrade.test.mjs

@@ -6,10 +6,11 @@
 // from v0.19.0, but a workspace upgraded from an older template may still
 // carry a tracked payload), the workspace-update skill bootstrap (--upgrade
 // installs the payload's copy so the workspace never runs an outdated
-// flow), and baseline reconstruction for pre-baseline workspaces (gh:186)
+// flow), baseline reconstruction for pre-baseline workspaces (gh:186), and
+// the .template-base/ merge-base staging every upgrade attempts (gh:193)
 // — the tarball fetch is injected so the suite never touches the network.
 import { upgradeWorkspace } from './upgrade.mjs';
-import { mkdtempSync, rmSync, writeFileSync, existsSync, mkdirSync, readFileSync } from 'fs';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, mkdirSync, readFileSync, cpSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { execSync, spawnSync } from 'child_process';
@@ -92,6 +93,9 @@ function makeTarball(entries) {
 }
 
 const sha = (s) => createHash('sha256').update(s).digest('hex');
+// The fixtures are ASCII with LF endings, so a plain sha256 of the text
+// equals template-baseline's CRLF-normalized hashBytes.
+const hashFile = (p) => sha(readFileSync(p, 'utf8'));
 
 // A v0.18-era package: every path rooted under package/ (npm's layout),
 // template/ still carried the live names.
@@ -119,23 +123,27 @@ const mustNotFetch = async () => { throw new Error('fetchTarball must not be cal
 
 console.log('# upgrade');
 
-// 1. Clean workspace with a baseline: payload staged, no tracked-payload
-//    warning, no fetch, no reconstruction staged, and the freshly staged
-//    payload is not tracked.
+// 1. Clean workspace with a baseline, offline: payload staged, no
+//    tracked-payload warning, the baseline left in place, no reconstruction,
+//    and no merge base — the failure warns but never fails the upgrade.
 {
   const root = buildWorkspace({ baseline: true });
   try {
-    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: mustNotFetch }));
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: noTarball }));
     const stderr = out.error.join('\n');
     check('no tracked-payload warning on a clean workspace',
       !stderr.includes('git rm -r --cached'));
     check('payload staged', existsSync(join(root, '.workspace-update', '.manifest.json')));
     check('freshly staged payload is not tracked', lsFilesPayload(root).length === 0);
     check('staging reported', out.log.join('\n').includes('Staged template payload'));
-    check('skipped reconstruction says why',
+    check('existing baseline named as left in place',
       out.log.join('\n').includes('Template baseline already present'));
     check('no reconstructed baseline staged when one exists',
       !existsSync(join(root, '.workspace-update', '.template-baseline.reconstructed.json')));
+    check('offline warns about the missing merge base',
+      stderr.includes('no merge base staged for locally modified files'));
+    check('no template base staged offline',
+      !existsSync(join(root, '.workspace-update', '.template-base')));
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -192,7 +200,7 @@ console.log('# upgrade');
     writeFileSync(join(oldSkill, 'SKILL.md'), '# old flow\n');
     writeFileSync(join(oldSkill, 'OLD-EXTRA.md'), 'stale\n');
 
-    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: mustNotFetch }));
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: noTarball }));
     const newSkill = readFileSync(join(oldSkill, 'SKILL.md'), 'utf8');
     check('installed skill is the payload copy, not the old one',
       newSkill === readFileSync(join(root, '.workspace-update', '.claude', 'skills', 'workspace-update', 'SKILL.md'), 'utf8')
@@ -257,7 +265,7 @@ console.log('# upgrade');
     mkdirSync(oldSkill, { recursive: true });
     writeFileSync(join(oldSkill, 'SKILL.md'), '# old flow\n');
     const { out } = await captureConsole(() => upgradeWorkspace(root, {
-      fetchTarball: mustNotFetch,
+      fetchTarball: noTarball,
       copySkill: () => { throw new Error('disk full'); },
     }));
     check('a failing copy keeps the installed skill',
@@ -272,7 +280,8 @@ console.log('# upgrade');
 
 // 5. No baseline + old live-name tarball: reconstruction stages a baseline
 //    for the INSTALLED version INSIDE THE PAYLOAD — never the launcher —
-//    marked reconstructed (gh:186).
+//    marked reconstructed (gh:186), and the same fetch stages the template
+//    content as the merge base under live names (gh:193).
 {
   const root = buildWorkspace({ templateVersion: '0.15.0' });
   try {
@@ -295,13 +304,31 @@ console.log('# upgrade');
     check('reconstruction reported', out.log.join('\n').includes('Reconstructed template baseline'));
     check('reconstruction names its staged location',
       out.log.join('\n').includes('.template-baseline.reconstructed.json'));
+    check('the fetch is announced on stderr before it can stall',
+      out.error.join('\n').includes('Fetching the v0.15.0 template as the merge base'));
+
+    const base = join(root, '.workspace-update', '.template-base');
+    check('merge base staged in the payload',
+      existsSync(join(base, '.claude', 'hooks', 'session-start.mjs')));
+    check('merge base carries the tarball content',
+      readFileSync(join(base, '.claude', 'hooks', 'session-start.mjs'), 'utf8') === '// hooks v0.15\n');
+    check('merge base uses live names only',
+      !existsSync(join(base, '_claude')) && !existsSync(join(base, '_mcp.json')));
+    check('merge base keeps non-verbatim files out',
+      !existsSync(join(base, 'CLAUDE.md.tmpl')));
+    check('base staging reported',
+      out.log.join('\n').includes('.template-base'));
+    // The invariant template-merge.mjs relies on: what the baseline
+    // records is exactly what the base holds.
+    check('staged base hashes to the reconstructed baseline entry',
+      hashFile(join(base, '.claude', 'hooks', 'session-start.mjs')) === baseline.files['.claude/hooks/session-start.mjs']);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 }
 
 // 6. No baseline + new inert-name tarball: same reconstruction through the
-//    _claude/_mcp.json layout, staged in the payload the same way.
+//    _claude/_mcp.json layout, and the merge base lands under live names.
 {
   const root = buildWorkspace({ templateVersion: '0.19.0' });
   try {
@@ -317,6 +344,13 @@ console.log('# upgrade');
     check('baseline marked reconstructed', baseline.reconstructed === true);
     check('launcher still has no baseline of its own',
       !existsSync(join(root, '.claude', '.template-baseline.json')));
+    const base = join(root, '.workspace-update', '.template-base');
+    check('inert layout stages the base under live names',
+      readFileSync(join(base, '.claude', 'hooks', 'session-start.mjs'), 'utf8') === '// hooks v0.19\n');
+    check('_mcp.json staged into the base as .mcp.json',
+      readFileSync(join(base, '.mcp.json'), 'utf8') === '{"mcpServers":{}}\n');
+    check('no inert names inside the base',
+      !existsSync(join(base, '_claude')) && !existsSync(join(base, '_mcp.json')));
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -337,6 +371,8 @@ console.log('# upgrade');
       !existsSync(join(root, '.claude', '.template-baseline.json')));
     check('no reconstructed baseline staged on fetch failure',
       !existsSync(join(root, '.workspace-update', '.template-baseline.reconstructed.json')));
+    check('no template base staged on fetch failure',
+      !existsSync(join(root, '.workspace-update', '.template-base')));
     check('upgrade continues after fetch failure',
       existsSync(join(root, '.workspace-update', '.manifest.json'))
       && existsSync(join(root, '.claude', 'skills', 'workspace-update', 'SKILL.md')));
@@ -377,13 +413,14 @@ console.log('# upgrade');
   }
 }
 
-// 10. An existing baseline is left alone: no fetch, no rewrite, nothing
-//     staged in the payload.
+// 10. An existing baseline is left alone: no rewrite, nothing reconstructed
+//     alongside it. The fetch still happens (the merge base needs the
+//     content) but its result never touches the baseline.
 {
   const root = buildWorkspace({ baseline: true });
   try {
     const before = readFileSync(join(root, '.claude', '.template-baseline.json'), 'utf8');
-    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: mustNotFetch }));
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: noTarball }));
     check('existing baseline untouched',
       readFileSync(join(root, '.claude', '.template-baseline.json'), 'utf8') === before);
     check('reconstruction not reported', !out.log.join('\n').includes('Reconstructed'));
@@ -416,6 +453,93 @@ console.log('# upgrade');
   }
 }
 
+// 12. A workspace WITH a baseline still gets the merge base: the fetch now
+//     serves the base staging alone, and no reconstruction happens (gh:193).
+{
+  const root = buildWorkspace({ baseline: true, templateVersion: '0.15.0' });
+  try {
+    const { out } = await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: async () => OLD_LAYOUT_TARBALL,
+    }));
+    const base = join(root, '.workspace-update', '.template-base');
+    check('merge base staged beside an existing baseline',
+      readFileSync(join(base, '.claude', 'hooks', 'session-start.mjs'), 'utf8') === '// hooks v0.15\n');
+    check('no reconstruction next to an existing baseline',
+      !existsSync(join(root, '.workspace-update', '.template-baseline.reconstructed.json'))
+        && !out.log.join('\n').includes('Reconstructed'));
+    check('existing baseline named as left in place',
+      out.log.join('\n').includes('Template baseline already present'));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 13. The offline skip with a baseline present: the upgrade completes, only
+//     the merge base is missing, and the warning says exactly that — not the
+//     pre-baseline fallback wording.
+{
+  const root = buildWorkspace({ baseline: true, templateVersion: '0.15.0' });
+  try {
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: noTarball }));
+    const stderr = out.error.join('\n');
+    check('offline with baseline warns about the merge base only',
+      stderr.includes('no merge base staged') && !stderr.includes('ask about every changed file'));
+    check('no template base staged', !existsSync(join(root, '.workspace-update', '.template-base')));
+    check('the upgrade still completes',
+      existsSync(join(root, '.workspace-update', '.manifest.json'))
+      && existsSync(join(root, '.claude', 'skills', 'workspace-update', 'SKILL.md')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 14. Staging is best-effort end to end: a failing baseline build warns and
+//     still stages the merge base; a base copy that fails partway removes
+//     the partial base — never trusted as an ancestor — and the upgrade
+//     itself never fails (gh:193).
+{
+  const root = buildWorkspace({ templateVersion: '0.15.0' });
+  try {
+    const { out } = await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: async () => OLD_LAYOUT_TARBALL,
+      buildBase: () => { throw new Error('EACCES: permission denied'); },
+    }));
+    const stderr = out.error.join('\n');
+    check('baseline build failure warns', stderr.includes('no template baseline written'));
+    check('no reconstructed baseline on a build failure',
+      !existsSync(join(root, '.workspace-update', '.template-baseline.reconstructed.json')));
+    check('the merge base still stages after a baseline failure',
+      existsSync(join(root, '.workspace-update', '.template-base', '.claude', 'hooks', 'session-start.mjs')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 15. A base copy failing MID-WAY leaves a partial .template-base on disk
+//     for a moment — it must be removed, not left where template-merge
+//     could trust it.
+{
+  const root = buildWorkspace({ baseline: true, templateVersion: '0.15.0' });
+  try {
+    let calls = 0;
+    const { out } = await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: async () => OLD_LAYOUT_TARBALL,
+      copyBase: (src, dest, opts) => {
+        if (calls++ > 0) throw new Error('disk full');
+        cpSync(src, dest, opts); // the first root lands, the rest fail
+      },
+    }));
+    check('a mid-copy failure warns about the merge base',
+      out.error.join('\n').includes('could not stage the merge base'));
+    check('the partial base is removed',
+      !existsSync(join(root, '.workspace-update', '.template-base')));
+    check('the upgrade completes after a base-copy failure',
+      existsSync(join(root, '.workspace-update', '.manifest.json')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
 if (failed > 0) {
   console.error(`${failed} check(s) failed, ${passed} passed`);
   process.exit(1);

package/package.json

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

package/template/_claude/rules/workspace-structure.md

@@ -11,7 +11,8 @@ All paths are relative to the workspace root. Two work lifecycles coexist, selec
 | `.claude/worktrees/{slug}/` | Task worktree for the workspace repo (`--repo .`) — Claude Code's native worktree location; the two converge | No |
 | `work-sessions/{name}/workspace/…` | Session lifecycle: workspace worktree, nested project worktrees at `workspace/repos/{repo}/`, `session.md` + artifacts (`design/plan/goal/research/crossref-*.md`) on top | Session branch |
 | `workspace-context/` | Team knowledge: `shared/` (ephemerals), `shared/locked/` (canonical truths), `team-member/{user}/` (per-user) | Yes |
-| `workspace-context/index.md`, `canonical.md`, `team-member/{user}/index.md` | Auto-generated catalogs (`canonical.md` = verbatim `shared/locked/`; `.indexignore` excludes paths) — regenerate with `build-workspace-context.mjs`, never hand-edit | Yes |
+| `workspace-context/index.md`, `canonical.md` | Auto-generated catalogs (`canonical.md` = verbatim `shared/locked/`; `.indexignore` excludes paths) — regenerate with `build-workspace-context.mjs`, never hand-edit | Yes |
+| `workspace-context/team-member/{user}/index.md` | The per-user slice of that catalog — gitignored: generated per machine, so a tracked copy would conflict across users; the personal files beside it stay tracked | No |
 | `workspace-scratchpad/` | Machine-local, regenerable: session log, hook debug output, chat records `chats/{chat}.json`, chat drawers `chats/{chat}/` (task-lifecycle designs, plans, braindumps, research in progress) | No |
 | `CLAUDE.md`, `CLAUDE.local.md`, `.claude/` | Launcher prompt (imports `canonical.md` + `index.md`); per-user prompt; rules, agents, skills, hooks, scripts | All but `CLAUDE.local.md`, `settings.local.json`, `.claude/.active-session.json`, and `.claude/worktrees/` |