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

package/lib/payload.mjs

@@ -1,7 +1,13 @@
 // lib/payload.mjs
-import { existsSync, cpSync, rmSync, mkdirSync, writeFileSync, readFileSync, renameSync } from 'fs';
-import { join, dirname } from 'path';
+import {
+  existsSync, cpSync, rmSync, mkdirSync, writeFileSync, readFileSync, renameSync,
+  mkdtempSync, readdirSync,
+} from 'fs';
+import { join, dirname, resolve, sep } from 'path';
 import { fileURLToPath } from 'url';
+import { tmpdir } from 'os';
+import { spawnSync } from 'child_process';
+import { gunzipSync } from 'zlib';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE_DIR = join(__dirname, '..', 'template');
@@ -59,3 +65,165 @@ export function cleanPayload(targetDir) {
     rmSync(payloadDir, { recursive: true });
   }
 }
+
+// ---------- published-tarball reader ----------
+//
+// Baseline reconstruction (lib/upgrade.mjs) needs the template tree of an
+// OLDER published version, and the npm registry is the only place that
+// still has it. Node ships no tar module and the package takes no
+// dependencies, so what follows is a minimal reader for the tar variants
+// npm actually writes: ustar headers, PAX extended headers ('x'), and GNU
+// long names ('L'). Links and devices are skipped — the template is plain
+// files and directories.
+
+const TAR_BLOCK = 512;
+
+function tarString(buffer, offset, length) {
+  const slice = buffer.subarray(offset, offset + length);
+  const nul = slice.indexOf(0);
+  return slice.subarray(0, nul === -1 ? length : nul).toString('utf8');
+}
+
+function tarSize(header) {
+  // GNU tar sets the high bit and switches to base-256 once a size no
+  // longer fits octal; npm's tarballs stay far below that, but reading
+  // the flag is two lines and keeps the reader from truncating silently.
+  if (header[124] & 0x80) {
+    let value = 0n;
+    for (let i = 125; i < 136; i++) value = (value << 8n) | BigInt(header[i]);
+    return Number(value);
+  }
+  const s = tarString(header, 124, 12).trim();
+  return s === '' ? 0 : parseInt(s, 8);
+}
+
+function ustarName(header) {
+  const name = tarString(header, 0, 100);
+  const prefix = tarString(header, 345, 155);
+  return prefix ? `${prefix}/${name}` : name;
+}
+
+// A version that can name a real published tarball. It comes from the
+// workspace's own workspace.json, so anything that is not plain semver is
+// rejected before it reaches a URL or an npm argument.
+function isVersionString(version) {
+  return typeof version === 'string' && /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version);
+}
+
+/**
+ * Extract every entry under `prefix` (e.g. 'template/') from a gzipped
+ * tarball into `destDir`, returning the number of files written. Entries
+ * that would escape destDir are skipped — absolute paths, '..' segments,
+ * and anything the resolved destination fails to prove is inside destDir.
+ * The tarball comes from the npm registry, but the guard costs a line and
+ * tar names written on Windows can carry '\' separators, which are treated
+ * as directory separators like '/'.
+ */
+export function extractTarballEntries(tarballBytes, destDir, { prefix = '' } = {}) {
+  const tar = gunzipSync(tarballBytes);
+  const absDestDir = resolve(destDir);
+  let files = 0;
+  let pendingName = null; // set by a preceding GNU 'L' or PAX 'x' entry
+  for (let off = 0; off + TAR_BLOCK <= tar.length;) {
+    const header = tar.subarray(off, off + TAR_BLOCK);
+    if (header.every((b) => b === 0)) break; // end-of-archive marker
+    const size = tarSize(header);
+    const type = String.fromCharCode(header[156] || 0x30);
+    const dataStart = off + TAR_BLOCK;
+    const data = tar.subarray(dataStart, dataStart + size);
+    off = dataStart + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+
+    if (type === 'L') {
+      pendingName = tarString(data, 0, data.length);
+    } else if (type === 'x') {
+      // PAX records are "<length> key=value" lines; only the path override
+      // matters here.
+      const m = data.toString('utf8').match(/(?:^|\n)\d+ path=([^\n]+)/);
+      if (m) pendingName = m[1];
+    } else {
+      // Every other entry consumes or discards the pending name — an 'L'/'x'
+      // record naming a link or device must not leak onto the entry after it.
+      const raw = (pendingName !== null ? pendingName : ustarName(header)).replace(/\\/g, '/');
+      pendingName = null;
+      if (type === '5' || type === '0') {
+        if (!raw.startsWith(prefix)) continue;
+        const relParts = raw.slice(prefix.length).split('/');
+        const rel = relParts.join('/');
+        const dest = join(absDestDir, rel);
+        // Belt and braces beyond the '..' check: whatever the parts say, the
+        // resolved destination must land inside destDir.
+        const inside = rel !== '' && !relParts.includes('..')
+          && resolve(dest).startsWith(absDestDir + sep);
+        if (!inside) continue;
+        if (type === '5') {
+          mkdirSync(dest, { recursive: true });
+        } else {
+          mkdirSync(dirname(dest), { recursive: true });
+          writeFileSync(dest, data);
+          files++;
+        }
+      }
+      // Links, devices, fifos, global PAX never appear in an npm tarball of
+      // this package — skip them (their name, pending or not, is gone).
+    }
+  }
+  return files;
+}
+
+// Both network paths are bounded: a hung registry or npm must not stall an
+// upgrade indefinitely — reconstruction is best-effort and falls back to
+// asking per file on the next /workspace-update.
+const FETCH_TIMEOUT_MS = 15000;
+const NPM_PACK_TIMEOUT_MS = 30000;
+
+/**
+ * Fetch the published package tarball for `version` as bytes, or null when
+ * it cannot be fetched. The registry URL needs no subprocess and works on
+ * every platform; `npm pack` is the fallback because it honors the user's
+ * configured registry and auth.
+ */
+export async function fetchPackageTarball(version, { registry = process.env.NPM_CONFIG_REGISTRY } = {}) {
+  if (!isVersionString(version)) return null;
+  const base = (registry || 'https://registry.npmjs.org').replace(/\/+$/, '');
+  try {
+    const res = await fetch(`${base}/@ulysses-ai/create-workspace/-/create-workspace-${version}.tgz`, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (res.ok) return Buffer.from(await res.arrayBuffer());
+  } catch { /* offline, blocked host, timed out — try npm pack */ }
+  return npmPackTarball(version);
+}
+
+function npmPackTarball(version) {
+  const dest = mkdtempSync(join(tmpdir(), 'create-workspace-pack-'));
+  try {
+    const argv = [
+      'pack', `@ulysses-ai/create-workspace@${version}`, '--pack-destination', dest, '--json',
+    ];
+    // Windows resolves `npm` to npm.cmd, which spawnSync cannot execute
+    // without a shell. The args are a validated semver spec and one temp
+    // path — quoting each keeps the joined command line honest even when
+    // the temp path contains spaces. Elsewhere argv runs shell-free.
+    const isWin = process.platform === 'win32';
+    const r = isWin
+      ? spawnSync('npm.cmd', argv.map((a) => `"${a}"`), {
+        shell: true, timeout: NPM_PACK_TIMEOUT_MS, encoding: 'utf-8',
+      })
+      : spawnSync('npm', argv, { timeout: NPM_PACK_TIMEOUT_MS, encoding: 'utf-8' });
+    if (r.error || r.status !== 0) return null;
+    let name = null;
+    try {
+      const parsed = JSON.parse(r.stdout);
+      name = Array.isArray(parsed) ? parsed[0]?.filename : parsed?.filename;
+    } catch { /* older npm prints a bare filename line — take the directory listing */ }
+    const candidates = name
+      ? [join(dest, name)]
+      : readdirSync(dest).filter((f) => f.endsWith('.tgz')).map((f) => join(dest, f));
+    for (const path of candidates) {
+      if (existsSync(path)) return readFileSync(path);
+    }
+    return null;
+  } finally {
+    rmSync(dest, { recursive: true, force: true });
+  }
+}

package/lib/payload.test.mjs

@@ -6,11 +6,14 @@
 // the /workspace-update skill already installed in existing workspaces,
 // which reads .workspace-update/.claude/... and .workspace-update/.mcp.json.
 // These tests pin that layout even though template/ itself stores the
-// protected paths under the inert names _claude/ and _mcp.json.
-import { stagePayload, cleanPayload } from './payload.mjs';
-import { mkdtempSync, rmSync, existsSync } from 'fs';
+// protected paths under the inert names _claude/ and _mcp.json. The
+// published-tarball reader (baseline reconstruction's input) is covered
+// here too, against fixture tarballs built in-memory — no network.
+import { stagePayload, cleanPayload, extractTarballEntries, fetchPackageTarball } from './payload.mjs';
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { tmpdir } from 'os';
+import { gzipSync } from 'zlib';
 
 let failed = 0;
 let passed = 0;
@@ -48,6 +51,158 @@ try {
   rmSync(root, { recursive: true, force: true });
 }
 
+// ---- extractTarballEntries ----
+
+// Minimal ustar writer: 512-byte header + padded body, matching what npm's
+// tarballs carry for paths under 100 chars.
+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),
+  ]));
+}
+
+// A GNU long-name record ('L') followed by the entry it names.
+function makeTarballWithLongName(longPath, content) {
+  const blocks = [
+    tarEntry('././@LongLink', longPath, 'L'),
+    tarEntry(longPath.slice(0, 20), content),
+    Buffer.alloc(1024),
+  ];
+  return gzipSync(Buffer.concat(blocks));
+}
+
+// A PAX extended header ('x') carrying a path override, then the entry.
+function makeTarballWithPaxPath(path, content) {
+  const record = `${path.length + 20} path=${path}\n`;
+  const blocks = [
+    tarEntry('PaxHeaders/x', record, 'x'),
+    tarEntry('short-name', content),
+    Buffer.alloc(1024),
+  ];
+  return gzipSync(Buffer.concat(blocks));
+}
+
+{
+  const dest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+  try {
+    const files = extractTarballEntries(makeTarball([
+      ['template/_claude/hooks/a.mjs', '// a\n'],
+      ['template/_claude/rules', '', '5'],
+      ['template/_mcp.json', '{"mcpServers":{}}\n'],
+      ['template/.claudeignore', 'scratch/\n'],
+      ['package/package.json', '{"version":"9.9.9"}\n'],
+      ['README.md', 'not under the prefix\n'],
+    ]), dest, { prefix: 'template/' });
+    check('extracts the three prefixed files', files === 3);
+    check('nested file content round-trips',
+      readFileSync(join(dest, '_claude', 'hooks', 'a.mjs'), 'utf8') === '// a\n');
+    check('directory entry materializes', existsSync(join(dest, '_claude', 'rules')));
+    check('entries outside the prefix are not extracted',
+      !existsSync(join(dest, '..', 'package')) && !existsSync(join(dest, 'package')));
+    check('unprefixed top-level files are not extracted', !existsSync(join(dest, 'README.md')));
+
+    // A traversal attempt inside the prefix is skipped, not written.
+    const guardDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarball([
+      ['template/../escape.txt', 'nope\n'],
+      ['template/ok.txt', 'fine\n'],
+    ]), guardDest, { prefix: 'template/' });
+    check('.. paths are refused', !existsSync(join(guardDest, '..', 'escape.txt')));
+    check('sibling of .. entry still extracted', existsSync(join(guardDest, 'ok.txt')));
+    rmSync(guardDest, { recursive: true, force: true });
+
+    // GNU long names and PAX path overrides both resolve to the real name.
+    const longPath = `template/_claude/scripts/${'very-long-name-'.repeat(8)}.mjs`;
+    const longDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarballWithLongName(longPath, '// long\n'), longDest, { prefix: 'template/' });
+    check('GNU long-name entries extract under their full path',
+      readFileSync(join(longDest, '_claude', 'scripts', `${'very-long-name-'.repeat(8)}.mjs`), 'utf8') === '// long\n');
+    rmSync(longDest, { recursive: true, force: true });
+
+    const paxDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarballWithPaxPath('template/_claude/pax.mjs', '// pax\n'), paxDest, { prefix: 'template/' });
+    check('PAX path overrides extract under the overridden path',
+      readFileSync(join(paxDest, '_claude', 'pax.mjs'), 'utf8') === '// pax\n');
+    rmSync(paxDest, { recursive: true, force: true });
+
+    // A PAX override that belongs to a NON-file entry (a symlink) dies with
+    // it: the file after the link extracts under its own header name, never
+    // under the leaked override.
+    const leakDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    const record = `${'template/_claude/leaked.mjs'.length + 20} path=template/_claude/leaked.mjs\n`;
+    extractTarballEntries(makeTarball([
+      ['PaxHeaders/x', record, 'x'],
+      ['target', 'template/elsewhere.mjs', '2'],
+      ['template/_claude/own-name.mjs', '// own\n'],
+    ]), leakDest, { prefix: 'template/' });
+    check('a PAX name followed by a non-file entry does not leak',
+      !existsSync(join(leakDest, '_claude', 'leaked.mjs'))
+      && !existsSync(join(leakDest, '_claude', 'elsewhere.mjs')));
+    check('the entry after a discarded override uses its own name',
+      readFileSync(join(leakDest, '_claude', 'own-name.mjs'), 'utf8') === '// own\n');
+    rmSync(leakDest, { recursive: true, force: true });
+
+    // Tar names written on Windows carry '\' separators — treated as
+    // directory separators like '/'.
+    const bsDest = mkdtempSync(join(tmpdir(), 'payload-tar-'));
+    extractTarballEntries(makeTarball([
+      ['template\\_claude\\hooks\\win.mjs', '// win\n'],
+    ]), bsDest, { prefix: 'template/' });
+    check('backslash-separated entry names extract as directories',
+      readFileSync(join(bsDest, '_claude', 'hooks', 'win.mjs'), 'utf8') === '// win\n');
+    rmSync(bsDest, { recursive: true, force: true });
+  } finally {
+    rmSync(dest, { recursive: true, force: true });
+  }
+}
+
+// fetchPackageTarball rejects non-semver versions before any network or
+// npm call — a workspace.json value is user input.
+{
+  const bogus = await fetchPackageTarball('0.15.0; rm -rf /');
+  check('non-semver version fetches nothing', bogus === null);
+  const alsoBogus = await fetchPackageTarball('');
+  check('empty version fetches nothing', alsoBogus === null);
+}
+
+// The registry fetch is bounded: a hung connection must not stall an
+// upgrade indefinitely (reconstruction falls back to asking per file).
+{
+  const realFetch = globalThis.fetch;
+  const tarball = makeTarball([['package/template/.claudeignore', 'x/\n']]);
+  let seenInit = null;
+  globalThis.fetch = async (url, init) => {
+    seenInit = { url, init };
+    return { ok: true, arrayBuffer: async () => tarball };
+  };
+  try {
+    const bytes = await fetchPackageTarball('0.15.0');
+    check('registry fetch returns the tarball bytes', bytes !== null && bytes.equals(tarball));
+    check('registry fetch targets the versioned tarball URL',
+      seenInit !== null && seenInit.url.endsWith('/create-workspace-0.15.0.tgz'));
+    check('registry fetch carries an abort timeout signal',
+      seenInit !== null && seenInit.init?.signal instanceof AbortSignal);
+  } finally {
+    globalThis.fetch = realFetch;
+  }
+}
+
 if (failed > 0) {
   console.error(`${failed} check(s) failed, ${passed} passed`);
   process.exit(1);

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})`);
   }