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

package/lib/upgrade.mjs

@@ -1,8 +1,15 @@
 // lib/upgrade.mjs
-import { existsSync, readFileSync } from 'fs';
+import {
+  existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, rmSync, mkdtempSync, renameSync,
+} from 'fs';
 import { join } from 'path';
+import { tmpdir } from 'os';
 import { spawnSync } from 'child_process';
-import { stagePayload } from './payload.mjs';
+import { stagePayload, extractTarballEntries, fetchPackageTarball } from './payload.mjs';
+import {
+  buildBaseline, RECONSTRUCTED_BASELINE_NAME, LIVE_PAIRS, INERT_PAIRS,
+  readBaseline, readBaselineFile, hashBytes,
+} from '../template/_claude/scripts/template-baseline.mjs';
 
 // .workspace-update/ is a transient staging area and is gitignored from
 // v0.19.0 on — but workspaces upgraded from older templates may still track
@@ -21,7 +28,126 @@ function warnIfPayloadTracked(targetDir) {
   console.error(`  Untrack it and commit:\n    git rm -r --cached .workspace-update\n    git commit -m "chore: untrack .workspace-update payload"\n`);
 }
 
-export async function upgradeWorkspace(targetDir) {
+// The workspace runs its INSTALLED /workspace-update after the CLI exits,
+// and an older installed copy predates the classifier/baseline/audit flow
+// the new payload ships — the assistant would improvise the update. So
+// --upgrade bootstraps the payload's copy into .claude/skills/ before
+// finishing, the same way --init installs bootstrap skills. The directory
+// is REPLACED, not merged: stale files inside the old skill must not
+// survive next to the new flow. Two safety properties (gh:186):
+//   - a locally customised SKILL.md (matching neither the payload's copy
+//     nor the hash of what the installed template version shipped) is
+//     backed up as SKILL.md.local-backup before the swap, and
+//   - the new tree is copied to a sibling staging directory and swapped in
+//     only once the copy succeeded — a copy that fails partway leaves the
+//     old skill in place, never an empty directory.
+function installWorkspaceUpdateSkill(targetDir, payloadDir, { copySkill = cpSync } = {}) {
+  const src = join(payloadDir, '.claude', 'skills', 'workspace-update');
+  if (!existsSync(src)) return false;
+  const skillsDir = join(targetDir, '.claude', 'skills');
+  const dest = join(skillsDir, 'workspace-update');
+
+  let backup = null;
+  const installedSkillMd = join(dest, 'SKILL.md');
+  if (existsSync(installedSkillMd)) {
+    const installedHash = hashBytes(readFileSync(installedSkillMd));
+    const payloadHash = hashBytes(readFileSync(join(src, 'SKILL.md')));
+    const oldBaseline = readBaselineFile(join(payloadDir, RECONSTRUCTED_BASELINE_NAME));
+    const shippedHash = oldBaseline ? oldBaseline.files['.claude/skills/workspace-update/SKILL.md'] : undefined;
+    if (installedHash !== payloadHash && shippedHash !== installedHash) {
+      backup = readFileSync(installedSkillMd);
+    }
+  }
+
+  const incoming = join(skillsDir, '.workspace-update.incoming');
+  mkdirSync(skillsDir, { recursive: true });
+  rmSync(incoming, { recursive: true, force: true });
+  try {
+    copySkill(src, incoming, { recursive: true });
+    rmSync(dest, { recursive: true, force: true });
+    try {
+      renameSync(incoming, dest);
+    } catch {
+      // rename across filesystems or onto a slow handle — a plain copy of
+      // the already-verified staging tree still completes the install.
+      copySkill(incoming, dest, { recursive: true });
+      rmSync(incoming, { recursive: true, force: true });
+    }
+  } catch (err) {
+    rmSync(incoming, { recursive: true, force: true });
+    console.error(`  Warning: could not install the current workspace-update skill (${err.message}) — the installed copy stays.`);
+    return false;
+  }
+  if (backup !== null) {
+    writeFileSync(join(dest, 'SKILL.md.local-backup'), backup);
+    console.log('  Existing workspace-update skill was modified locally — backed up to .claude/skills/workspace-update/SKILL.md.local-backup');
+  }
+  return true;
+}
+
+// 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.';
+  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;
+  }
+  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;
+  }
+
+  const tmp = mkdtempSync(join(tmpdir(), 'create-workspace-baseline-'));
+  try {
+    // 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.
+    const extracted = join(tmp, 'template');
+    let baseline = null;
+    try {
+      extractTarballEntries(tarball, extracted, { prefix: 'package/template/' });
+      const pairs = existsSync(join(extracted, '_claude')) ? INERT_PAIRS : LIVE_PAIRS;
+      baseline = buildBaseline(extracted, { pairs, version: fromVersion });
+    } 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;
+    }
+    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;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+export async function upgradeWorkspace(targetDir, opts = {}) {
   const workspaceJsonPath = join(targetDir, 'workspace.json');
 
   console.log(`\n  @ulysses-ai/create-workspace --upgrade`);
@@ -46,12 +172,28 @@ export async function upgradeWorkspace(targetDir) {
 
   const fromVersion = config.workspace?.templateVersion || 'unknown';
 
-  // Stage payload
-  const { toVersion } = stagePayload(targetDir, { action: 'upgrade', fromVersion });
+  // Stage the payload first: a reconstructed baseline is 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);
+  }
+
+  // Bootstrap the current /workspace-update skill — the workspace runs its
+  // installed copy next, and the old one does not know this payload's flow.
+  if (installWorkspaceUpdateSkill(targetDir, payloadDir, opts)) {
+    console.log('  Installed the current workspace-update skill (.claude/skills/workspace-update/)');
+  }
 
   if (fromVersion === toVersion) {
     console.log(`  Workspace is already on template v${toVersion}.`);
-    console.log(`  Payload staged anyway — run /workspace-update to verify integrity.\n`);
+    console.log(`  Payload staged anyway — run /workspace-update to verify integrity.`);
   } else {
     console.log(`  Staged template payload (v${fromVersion} → v${toVersion})`);
   }

package/lib/upgrade.test.mjs

@@ -2,14 +2,19 @@
 // Unit tests for upgrade.mjs
 // Run: node lib/upgrade.test.mjs
 //
-// Covers the tracked-payload warning: .workspace-update/ is gitignored from
-// v0.19.0, but a workspace upgraded from an older template may still carry a
-// tracked payload from a previous run — --upgrade must say so.
+// Covers the tracked-payload warning (.workspace-update/ is gitignored
+// 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)
+// — the tarball fetch is injected so the suite never touches the network.
 import { upgradeWorkspace } from './upgrade.mjs';
-import { mkdtempSync, rmSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, mkdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { execSync, spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import { gzipSync } from 'zlib';
 
 let failed = 0;
 let passed = 0;
@@ -20,29 +25,36 @@ function check(label, ok) {
   }
 }
 
-function captureConsole(fn) {
+async function captureConsole(fn) {
   const out = { log: [], error: [] };
   const origLog = console.log;
   const origError = console.error;
   console.log = (...a) => { out.log.push(a.join(' ')); };
   console.error = (...a) => { out.error.push(a.join(' ')); };
   try {
-    return { result: fn(), out };
+    return { result: await fn(), out };
   } finally {
     console.log = origLog;
     console.error = origError;
   }
 }
 
-function buildWorkspace() {
+function buildWorkspace({ templateVersion = '0.15.0', baseline = false } = {}) {
   const root = mkdtempSync(join(tmpdir(), 'upgrade-test-'));
   execSync('git init -q -b main', { cwd: root, stdio: 'pipe' });
   execSync('git config user.email test@example.com', { cwd: root, stdio: 'pipe' });
   execSync('git config user.name Test', { cwd: root, stdio: 'pipe' });
   writeFileSync(join(root, 'workspace.json'), JSON.stringify({
-    workspace: { name: 'demo', initialized: true, templateVersion: '0.15.0' },
+    workspace: { name: 'demo', initialized: true, templateVersion },
     repos: {},
   }, null, 2) + '\n');
+  if (baseline) {
+    mkdirSync(join(root, '.claude'), { recursive: true });
+    writeFileSync(join(root, '.claude', '.template-baseline.json'), JSON.stringify({
+      templateVersion,
+      files: { '.claude/hooks/a.mjs': '0'.repeat(64) },
+    }) + '\n');
+  }
   execSync('git add workspace.json', { cwd: root, stdio: 'pipe' });
   execSync('git commit -q -m init', { cwd: root, stdio: 'pipe' });
   return root;
@@ -55,20 +67,75 @@ function lsFilesPayload(root) {
   }).stdout.split('\n').filter(Boolean);
 }
 
+// ---- fixture tarballs (old live-name layout and new inert layout) ----
+
+function tarEntry(name, content, type = '0') {
+  const body = Buffer.from(content, 'utf8');
+  const header = Buffer.alloc(512);
+  header.write(name, 0, 100, 'utf8');
+  header.write(body.length.toString(8).padStart(11, '0') + '\0', 124, 'ascii');
+  header.write(type, 156, 'ascii');
+  header.write('ustar', 257, 'ascii');
+  header.write('00', 263, 'ascii');
+  let sum = 0;
+  for (const byte of header) sum += byte;
+  header.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 'ascii');
+  const pad = Buffer.alloc((512 - (body.length % 512)) % 512);
+  return Buffer.concat([header, body, pad]);
+}
+
+function makeTarball(entries) {
+  return gzipSync(Buffer.concat([
+    ...entries.map(([name, content, type]) => tarEntry(name, content, type)),
+    Buffer.alloc(1024),
+  ]));
+}
+
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+
+// A v0.18-era package: every path rooted under package/ (npm's layout),
+// template/ still carried the live names.
+const OLD_LAYOUT_TARBALL = makeTarball([
+  ['package/package.json', '{"name":"@ulysses-ai/create-workspace"}\n'],
+  ['package/template/CLAUDE.md.tmpl', '## Workspace: {{project-name}}\n'],
+  ['package/template/.claude/hooks/session-start.mjs', '// hooks v0.15\n'],
+  ['package/template/.claude/scripts/old.mjs', '// script\n'],
+  ['package/template/.mcp.json', '{"mcpServers":{}}\n'],
+  ['package/template/.claudeignore', 'scratch/\n'],
+]);
+
+// A v0.19-on package: template/ stores the inert names.
+const NEW_LAYOUT_TARBALL = makeTarball([
+  ['package/template/_claude/hooks/session-start.mjs', '// hooks v0.19\n'],
+  ['package/template/_claude/scripts/new.mjs', '// script\n'],
+  ['package/template/_mcp.json', '{"mcpServers":{}}\n'],
+  ['package/template/.claudeignore', 'scratch/\n'],
+]);
+
+// Injected fetch results: null means "not fetchable", a throwing fetch must
+// never be reached.
+const noTarball = async () => null;
+const mustNotFetch = async () => { throw new Error('fetchTarball must not be called'); };
+
 console.log('# upgrade');
 
-// 1. Clean workspace: payload staged, no tracked-payload warning, and the
-//    freshly staged payload is not tracked.
+// 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.
 {
-  const root = buildWorkspace();
+  const root = buildWorkspace({ baseline: true });
   try {
-    const { out } = captureConsole(() => upgradeWorkspace(root));
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: mustNotFetch }));
     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',
+      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')));
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -77,7 +144,7 @@ console.log('# upgrade');
 // 2. Workspace tracking .workspace-update/ from a pre-v0.19 upgrade: the
 //    warning fires and names the untrack command.
 {
-  const root = buildWorkspace();
+  const root = buildWorkspace({ baseline: true });
   try {
     // Simulate the old behavior: a payload committed tracked.
     const payload = join(root, '.workspace-update');
@@ -87,7 +154,7 @@ console.log('# upgrade');
     execSync('git commit -q -m "track payload"', { cwd: root, stdio: 'pipe' });
     check('fixture really tracks the payload', lsFilesPayload(root).length > 0);
 
-    const { out } = captureConsole(() => upgradeWorkspace(root));
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: mustNotFetch }));
     const stderr = out.error.join('\n');
     check('tracked-payload warning fires', stderr.includes('.workspace-update/') && stderr.includes('tracked by git'));
     check('warning names the untrack command', stderr.includes('git rm -r --cached .workspace-update'));
@@ -104,7 +171,7 @@ console.log('# upgrade');
       workspace: { name: 'demo', initialized: true, templateVersion: '0.15.0' },
       repos: {},
     }, null, 2) + '\n');
-    const { out } = captureConsole(() => upgradeWorkspace(root));
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: noTarball }));
     check('no warning outside a git repo', !out.error.join('\n').includes('tracked by git'));
     check('payload staged outside a git repo', existsSync(join(root, '.workspace-update', '.manifest.json')));
   } finally {
@@ -112,6 +179,243 @@ console.log('# upgrade');
   }
 }
 
+// 4. --upgrade installs the payload's workspace-update skill, REPLACING
+//    whatever old copy the workspace carries. An old SKILL.md that matches
+//    neither the payload's copy nor any known-shipped copy is the operator's
+//    own edit — it is backed up before the swap (gh:186).
+{
+  const root = buildWorkspace({ baseline: true });
+  try {
+    // An outdated installed skill with a stale extra file.
+    const oldSkill = join(root, '.claude', 'skills', 'workspace-update');
+    mkdirSync(oldSkill, { recursive: true });
+    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 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')
+      && newSkill !== '# old flow\n');
+    check('stale files inside the old skill do not survive', !existsSync(join(oldSkill, 'OLD-EXTRA.md')));
+    check('skill install reported', out.log.join('\n').includes('workspace-update skill'));
+    check('a locally modified old skill is backed up',
+      readFileSync(join(oldSkill, 'SKILL.md.local-backup'), 'utf8') === '# old flow\n');
+    check('backup reported', out.log.join('\n').includes('SKILL.md.local-backup'));
+    // The staged payload itself is unchanged: its skill directory stays.
+    check('payload still carries the skill directory',
+      existsSync(join(root, '.workspace-update', '.claude', 'skills', 'workspace-update', 'SKILL.md')));
+    check('no staging directory left behind',
+      !existsSync(join(root, '.claude', 'skills', '.workspace-update.incoming')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 4b. A PRISTINE old skill — its bytes match what the installed version
+//     shipped (the reconstructed baseline records the hash) — replaces
+//     without a backup: nothing of the operator's is at risk.
+{
+  // The tarball of the installed version shipped exactly this skill.
+  const PRISTINE_TARBALL = makeTarball([
+    ['package/template/.claude/skills/workspace-update/SKILL.md', '# pristine old flow\n'],
+    ['package/template/.claudeignore', 'scratch/\n'],
+  ]);
+  const root = buildWorkspace({ templateVersion: '0.15.0' });
+  try {
+    const oldSkill = join(root, '.claude', 'skills', 'workspace-update');
+    mkdirSync(oldSkill, { recursive: true });
+    writeFileSync(join(oldSkill, 'SKILL.md'), '# pristine old flow\n');
+    await captureConsole(() => upgradeWorkspace(root, { fetchTarball: async () => PRISTINE_TARBALL }));
+    check('pristine old skill replaced without a backup',
+      !existsSync(join(oldSkill, 'SKILL.md.local-backup'))
+      && readFileSync(join(oldSkill, 'SKILL.md'), 'utf8') !== '# pristine old flow\n');
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+
+  // The same workspace but with the operator's own edit on top: backed up.
+  const editedRoot = buildWorkspace({ templateVersion: '0.15.0' });
+  try {
+    const oldSkill = join(editedRoot, '.claude', 'skills', 'workspace-update');
+    mkdirSync(oldSkill, { recursive: true });
+    writeFileSync(join(oldSkill, 'SKILL.md'), '# my customized flow\n');
+    await captureConsole(() => upgradeWorkspace(editedRoot, { fetchTarball: async () => PRISTINE_TARBALL }));
+    check('a customized old skill is backed up when the shipped hash is known',
+      readFileSync(join(oldSkill, 'SKILL.md.local-backup'), 'utf8') === '# my customized flow\n');
+  } finally {
+    rmSync(editedRoot, { recursive: true, force: true });
+  }
+}
+
+// 4c. A copy that fails partway leaves the installed skill in place — the
+//     swap happens only after the staging copy succeeded.
+{
+  const root = buildWorkspace({ baseline: true });
+  try {
+    const oldSkill = join(root, '.claude', 'skills', 'workspace-update');
+    mkdirSync(oldSkill, { recursive: true });
+    writeFileSync(join(oldSkill, 'SKILL.md'), '# old flow\n');
+    const { out } = await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: mustNotFetch,
+      copySkill: () => { throw new Error('disk full'); },
+    }));
+    check('a failing copy keeps the installed skill',
+      readFileSync(join(oldSkill, 'SKILL.md'), 'utf8') === '# old flow\n');
+    check('a failing copy warns', out.error.join('\n').includes('could not install the current workspace-update skill'));
+    check('a failing copy leaves no staging directory',
+      !existsSync(join(root, '.claude', 'skills', '.workspace-update.incoming')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 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).
+{
+  const root = buildWorkspace({ templateVersion: '0.15.0' });
+  try {
+    const { out } = await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: async (version) => (version === '0.15.0' ? OLD_LAYOUT_TARBALL : null),
+    }));
+    const baselinePath = join(root, '.workspace-update', '.template-baseline.reconstructed.json');
+    check('reconstructed baseline staged in the payload', existsSync(baselinePath));
+    check('launcher gets no new baseline file',
+      !existsSync(join(root, '.claude', '.template-baseline.json')));
+    const baseline = JSON.parse(readFileSync(baselinePath, 'utf8'));
+    check('baseline records the installed version', baseline.templateVersion === '0.15.0');
+    check('baseline is marked reconstructed', baseline.reconstructed === true);
+    check('live-name layout hashes map to installed keys',
+      baseline.files['.claude/hooks/session-start.mjs'] === sha('// hooks v0.15\n'));
+    check('.mcp.json baselined from the old live name',
+      baseline.files['.mcp.json'] === sha('{"mcpServers":{}}\n'));
+    check('non-verbatim payload roots are not baselined',
+      !Object.keys(baseline.files).some((k) => k.endsWith('.tmpl') || k.startsWith('package')));
+    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'));
+  } 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.
+{
+  const root = buildWorkspace({ templateVersion: '0.19.0' });
+  try {
+    await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: async () => NEW_LAYOUT_TARBALL,
+    }));
+    const baseline = JSON.parse(
+      readFileSync(join(root, '.workspace-update', '.template-baseline.reconstructed.json'), 'utf8'));
+    check('inert-name layout maps to installed keys',
+      baseline.files['.claude/hooks/session-start.mjs'] === sha('// hooks v0.19\n'));
+    check('_mcp.json baselined as .mcp.json',
+      baseline.files['.mcp.json'] === sha('{"mcpServers":{}}\n'));
+    check('baseline marked reconstructed', baseline.reconstructed === true);
+    check('launcher still has no baseline of its own',
+      !existsSync(join(root, '.claude', '.template-baseline.json')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 7. Fetch failure and unknown version: warn and continue — the upgrade
+//    itself never fails, and the payload plus skill still land.
+{
+  const root = buildWorkspace({ templateVersion: '0.15.0' });
+  try {
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: noTarball }));
+    const stderr = out.error.join('\n');
+    check('fetch failure warns about the missing baseline',
+      stderr.includes('no template baseline written'));
+    check('fetch failure names the per-file fallback',
+      stderr.includes('ask about every changed file'));
+    check('no baseline written on fetch failure',
+      !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('upgrade continues after fetch failure',
+      existsSync(join(root, '.workspace-update', '.manifest.json'))
+      && existsSync(join(root, '.claude', 'skills', 'workspace-update', 'SKILL.md')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 8. A corrupt tarball is a warning, not a crash.
+{
+  const root = buildWorkspace({ templateVersion: '0.15.0' });
+  try {
+    const { out } = await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: async () => Buffer.from('not a tarball at all'),
+    }));
+    check('corrupt tarball warns', out.error.join('\n').includes('no template baseline written'));
+    check('corrupt tarball does not fail the upgrade',
+      existsSync(join(root, '.workspace-update', '.manifest.json')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 9. No usable templateVersion: named warning, no network attempt.
+{
+  const root = buildWorkspace({ templateVersion: null });
+  try {
+    writeFileSync(join(root, 'workspace.json'), JSON.stringify({
+      workspace: { name: 'demo', initialized: true },
+      repos: {},
+    }, null, 2) + '\n');
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: mustNotFetch }));
+    check('missing templateVersion warns', out.error.join('\n').includes('no templateVersion'));
+    check('no baseline written without a version',
+      !existsSync(join(root, '.claude', '.template-baseline.json')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 10. An existing baseline is left alone: no fetch, no rewrite, nothing
+//     staged in the payload.
+{
+  const root = buildWorkspace({ baseline: true });
+  try {
+    const before = readFileSync(join(root, '.claude', '.template-baseline.json'), 'utf8');
+    const { out } = await captureConsole(() => upgradeWorkspace(root, { fetchTarball: mustNotFetch }));
+    check('existing baseline untouched',
+      readFileSync(join(root, '.claude', '.template-baseline.json'), 'utf8') === before);
+    check('reconstruction not reported', !out.log.join('\n').includes('Reconstructed'));
+    check('no reconstructed baseline staged alongside',
+      !existsSync(join(root, '.workspace-update', '.template-baseline.reconstructed.json')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 11. A CORRUPT baseline file is as good as none: reconstruction runs and
+//     stages its result in the payload; the broken launcher file itself is
+//     left exactly as it was (gh:186).
+{
+  const root = buildWorkspace({ templateVersion: '0.15.0' });
+  try {
+    mkdirSync(join(root, '.claude'), { recursive: true });
+    writeFileSync(join(root, '.claude', '.template-baseline.json'), '{ not json at all\n');
+    const { out } = await captureConsole(() => upgradeWorkspace(root, {
+      fetchTarball: async () => OLD_LAYOUT_TARBALL,
+    }));
+    check('a corrupt baseline does not block reconstruction',
+      existsSync(join(root, '.workspace-update', '.template-baseline.reconstructed.json')));
+    check('the corrupt file is left as it was',
+      readFileSync(join(root, '.claude', '.template-baseline.json'), 'utf8') === '{ not json at all\n');
+    check('reconstruction reported despite the corrupt file',
+      out.log.join('\n').includes('Reconstructed template baseline'));
+  } 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.21.0-beta.0",
+  "version": "0.23.0-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",

package/template/_claude/rules/forge-operations.md

@@ -25,11 +25,31 @@ adapter takes an injectable `spawnFn`, so tests mock subprocesses rather than ru
 
 ## Configuration
 
-`workspace.json` → `workspace.forge`: `{ "type": "github" }`. `type` names the adapter module;
-`github` is the default and the only complete one, `gitlab.mjs` is a stub that throws
-`NOT_IMPLEMENTED`. Optional `repo` is an `owner/name` slug; unset or `"auto"` resolves from the
-git `origin` remote. An absent `workspace.forge` is treated as `{ type: 'github' }`; setting it
-to `false` makes every adapter method throw `FORGE_DISABLED`.
+`workspace.json` → `workspace.forge`: `{ "type": "github" | "gitlab" }`. `type` names the adapter
+module — `github.mjs` wraps `gh`, `gitlab.mjs` wraps `glab`; both implement the same method
+surface. With no `type`, the adapter is picked from the target repo's host: gitlab.com (or the
+configured `host`) selects GitLab, anything else stays GitHub — which is how one workspace can
+mix GitHub and GitLab repos, each origin naming its own forge. Optional `repo` is the project
+slug (`owner/name` on GitHub, `group/sub/project` at any depth on GitLab); unset or `"auto"`
+resolves from the git `origin` remote. A self-managed GitLab sets `host` — glab receives it as
+`GITLAB_HOST` (and `--hostname` on `glab api`), always, so an exported foreign `GITLAB_HOST`
+never leaks in. One host per workspace: the origin-based selection recognizes gitlab.com plus
+exactly this host, so a workspace spanning two self-managed instances can't be expressed. An
+origin with an explicit non-default port keeps the port in its host, so `host` carries it too
+(`gitlab.example.com:8443`); default ports drop (`github.com:443` reads as github.com). An
+absent `workspace.forge` is treated as `{ type: 'github' }`; setting it to `false` makes every
+adapter method throw `FORGE_DISABLED`.
+
+GitLab gaps, by design: `releaseCreate` with `generateNotes: true` throws `NOT_SUPPORTED` —
+GitLab cannot generate notes from merged MRs, so callers (the `/release` skill does) assemble
+the merged-MR list themselves and pass it as `notes` with `generateNotes: false`. Workflow runs
+map onto pipelines: `workflowRunFind` ignores the workflow name (one pipeline per ref) and
+`workflowRunWatch` polls instead of streaming, treating a `manual` job as still running —
+approving it resumes the pipeline. `reviewDecision` is always empty, and `mergeStateStatus`
+carries GitLab's `detailed_merge_status` vocabulary (`not_approvable`, `ci_still_running`, …),
+not GitHub's — treat it as opaque rather than comparing GitHub strings. `prMerge` disables
+glab's auto-merge (which queues the merge behind a passing pipeline and still exits 0) and
+verifies the MR actually landed, throwing `MergeRejected` otherwise.
 
 ## Deliberate exceptions — do not "fix" these
 
@@ -40,7 +60,8 @@ alone:
   See `work-item-tracking.md`. The two abstractions are intentionally separate.
 - **`/setup-tracker` repo configuration** — `gh repo view --json hasIssuesEnabled` and
   `gh api repos/{slug} -X PATCH -f has_issues=true` are GitHub-API-specific setup, not
-  cross-cutting operations. A GitLab user's setup flow differs entirely.
+  cross-cutting operations. GitLab projects have issues on by default, so its setup flow
+  needs no equivalent check.
 - **`gh repo view` as a remote-type probe** — a one-line capability check, not an operation.
 - **`gh repo create`** — an interactive one-off when a workspace has no remote.
 - **Manual recovery prose** — `gh run rerun`, `gh run view`, `gh release view` in `/release`