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

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

@@ -9,7 +9,7 @@ Apply a staged template update to an initialized workspace. The CLI (`npx @ulyss
 
 ## Prerequisites
 
-- `workspace.json` must have `initialized: true`
+- Read `workspace.json` (the file at the workspace root — the SessionStart hook's `Workspace config (workspace.json):` line is only a summary) and check `workspace.initialized` is `true`
 - If not initialized, check whether initialization was committed but never merged — the workspace-init flow ends with its commits merged to the default branch, so an unmerged init branch explains a missing flag:
   ```bash
   git log --all --format=%H -S'"initialized": true' -- workspace.json
@@ -54,14 +54,19 @@ It runs from the payload precisely so workspaces that don't have it installed ye
 - `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
 - `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 — Step 3 merges these three-way when a merge base is staged
+- `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 — Step 3 merges these three-way when a merge base is staged. A path registered in `.claude/template-modifications.json` (see the registry note below) enters as `{ file, reason }`, its reason saying why the file diverges — show it at every decision about the file
 - `config` — `.mcp.json` and `.claude/settings.json`: JSON the workspace owns jointly with the template — never compared by content, never batch-copied. Each entry carries a key-level diff (`added` keys the template ships, `workspaceOnly` keys only the workspace has, `changed` keys with different values; nested paths like `mcpServers/{server}`), element diffs for array-valued keys (`arrays`: `{ path, added, workspaceOnly }` element lists for `hooks/{event}`, `permissions/allow`/`deny`), or a `notInstalled` / `unparseable` flag. Merged key by key in Step 3.
-- `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
+- `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; registered entries carry their reason, shown in the summary
+- `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; registered entries carry their reason, shown with that ask
 - `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. The config files above never appear here (the template dropping one hands it to the workspace). 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. An entry is a plain path, `{ file, referencedBy }` — a hook a workspace-only `settings.json` entry still registers (the paths say where) — or `{ file, userOwned: true }` — no baseline record, so the template never shipped it and it is the workspace's own.
+- `removed` — installed file with no counterpart in the payload. The config files above never appear here (the template dropping one hands it to the workspace). Gitignored paths, `.claude/worktrees/`, and files claimed in `.claude/template-modifications.json` → `localFiles` (an array of `.claude/`-relative paths or globs the workspace owns; the legacy `workspace.json` → `workspace.localFiles` array still counts) are excluded automatically. An entry is a plain path, `{ file, referencedBy }` — a hook a workspace-only `settings.json` entry still registers (the paths say where) — or `{ file, userOwned: true }` — no baseline record, so the template never shipped it and it is the workspace's own; any of these may carry `reason` when the file is registered in the registry's `modifications` map.
 - `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).
 - `implicitDefaults` — `workspace.json` keys whose absence carried a default in the version being upgraded from. Today: `canonicalBudgetBytes`, an implicit 40960-byte budget between v0.15.0-beta.1 and v0.19.0-beta.0 (before v0.15 there was no budget at all; since v0.19 absent means off). An upgrade from inside that window into a workspace.json that never set the key reports `{ key, value, reason }` — Step 3's workspace.json step writes the value explicitly so trimming doesn't silently stop.
+- `staleModifications` — `{ file, reason }` entries from the registry whose installed file already equals the payload: the template's version was taken at some point, so the recorded reason describes nothing. `file` is the `.claude/`-prefixed path; the registry key is that path with the prefix stripped. Step 3 offers to drop them.
+- `legacyKeys` — template-modification data still sitting in `workspace.json` (`workspace.localFiles`, `workspace.templateModifications`) instead of the registry file. Step 3 offers the migration.
+- `ignoredKeys` — registry keys that escape `.claude/` (`../CLAUDE.md`, absolute paths): the registry covers `.claude/` paths only — root files (`CLAUDE.md`, `.mcp.json`, `.claudeignore`) are handled by their own merge paths — so these are reported for the operator to fix rather than sitting silently inert.
+
+The classification also consults `.claude/template-modifications.json`, the workspace's registry of deliberate divergences from the template — `{ "localFiles": [...], "modifications": { "<path>": "<reason>" } }` with paths relative to `.claude/` (backslashes and leading `./` or `.claude/` are normalized on read). The template never ships or overwrites this file. `localFiles` are paths or globs the workspace owns outright (never offered by an update); `modifications` records why edited template files are kept as they are — those files still update (three-way merge when both sides changed), the reason just travels with every decision about them. If the output carries `modificationsError`, the registry doesn't parse — STOP: report the error and ask the operator to fix the JSON before any per-file decision. Classification has already failed closed (every `removed` entry is marked `unverifiable: true`, because the file's ownership claims cannot be read), so nothing is offered as a plain removal while it is broken; never invent reasons or exclusions, and after the fix re-run the classifier.
 
 Content is compared with line endings normalized (CRLF ≡ LF; binary files byte-exact), so a Windows autocrlf checkout does not read as locally modified.
 
@@ -102,27 +107,29 @@ Batch the safe cases, ask on the rest:
   ```bash
   node {payload}/.claude/scripts/template-merge.mjs --root . --payload {payload} --baseline {baseline}
   ```
-  (`{baseline}` resolves as in Step 2; `--files a,b` re-runs a subset, `--out <dir>` redirects the output.) It merges each `differs` file with `git merge-file` — the workspace copy as "local", the staged base as the common ancestor, the payload's copy as "template" — and prints `{ merged: [{path, conflicts: 0, out}], conflicted: [{path, conflicts: N, out}], noBase: [path], errors: [...] }`, writing the merged text under `{payload}/.merged/` mirroring each path. It never writes a workspace file; applying is this skill's job, on approval:
-  - **Clean merges (`merged`):** show the diff workspace→merged for each file (`git diff --no-index` the workspace file against its `out`), then ONE batched confirmation — "Apply these {N} clean merges? [Y/n]" — listing the files. On yes, copy each `out` file to the same path in the workspace (the update worktree in the remote flow).
-  - **Conflicts (`conflicted`):** one file at a time. Show the conflict hunks (`<<<<<<< local` … `>>>>>>> template`), propose a resolution, and write the resolved file only after the operator's yes for THAT file. Never resolve a conflict silently, and never delegate resolution to a subagent or any unattended step without the operator approving each file.
-  - **`noBase`** (no staged base for the path, or its hash does not match the baseline — the base is not this workspace's ancestor): fall back to the two-way ask — "Your version of {file} differs from the template's. Show diff? [y/N]" — then apply, keep, or merge by hand per the user's decision. Expect a previously declined update here: its baseline entry keeps the older version's hash (Step 4's rule), so the newly staged base no longer validates and the file takes this per-file decision.
+  (`{baseline}` resolves as in Step 2; `--files a,b` re-runs a subset, `--out <dir>` redirects the output.) It merges each `differs` file with `git merge-file` — the workspace copy as "local", the staged base as the common ancestor, the payload's copy as "template" — and prints `{ merged: [{path, conflicts: 0, out}], conflicted: [{path, conflicts: N, out}], noBase: [path], errors: [...] }`, writing the merged text under `{payload}/.merged/` mirroring each path. Entries in `merged`/`conflicted` carry `reason` when the file is registered in `.claude/template-modifications.json`, and a registered `noBase` path prints as `{ path, reason }` — show that reason at the decision it belongs to. It never writes a workspace file; applying is this skill's job, on approval:
+  - **Clean merges (`merged`):** show the diff workspace→merged for each file (`git diff --no-index` the workspace file against its `out`), with its registered reason when it has one, then ONE batched confirmation — "Apply these {N} clean merges? [Y/n]" — listing the files. On yes, copy each `out` file to the same path in the workspace (the update worktree in the remote flow).
+  - **Conflicts (`conflicted`):** one file at a time. Show the conflict hunks (`<<<<<<< local` … `>>>>>>> template`) with the file's registered reason when it has one, propose a resolution, and write the resolved file only after the operator's yes for THAT file. Never resolve a conflict silently, and never delegate resolution to a subagent or any unattended step without the operator approving each file.
+  - **`noBase`** (no staged base for the path, or its hash does not match the baseline — the base is not this workspace's ancestor): fall back to the two-way ask — "Your version of {file} differs from the template's{ — registered reason}. Show diff? [y/N]" — then apply, keep, or merge by hand per the user's decision. Expect a previously declined update here: its baseline entry keeps the older version's hash (Step 4's rule), so the newly staged base no longer validates and the file takes this per-file decision.
+  Whenever the operator's decision KEEPS their local version — a `noBase` "keep", a conflict resolution that keeps the local wording — and the path is not yet registered, offer: "Record why you keep {file} in .claude/template-modifications.json? [y/N]" — on yes, add `"<path>": "<their reason>"` to its `modifications` map (path relative to `.claude/`, creating the file if absent), so the next update shows the reason instead of re-asking blind.
   When the payload carries no `.template-base/` at all (the CLI could not fetch the installed version — offline or unpublished; the helper reports `templateBase: null`), every `differs` file takes the `noBase` path — say so once in the report.
 - **Config files (`config`):** `.mcp.json` and `.claude/settings.json` are never copied wholesale — a batch copy wipes the workspace's own MCP servers and settings. Merge each entry key by key (values from `{payload}/{path}` and the workspace's copy): add every `added` key, keep every `workspaceOnly` key untouched, and for each `changed` key ask — "Template changed `{key}` in `{path}`. Take the template's, keep yours, or inspect?" Array-valued keys merge as a union, no ask: keep the workspace's elements in place and append each `arrays` entry's `added` elements (`workspaceOnly` elements are already in place, listed for visibility). `notInstalled` — ask once: "Install {path} from the template? [Y/n]" (never install a config silently); `unparseable` means broken JSON on one side — show the file and ask, never merge blind.
 - **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`):** a plain path — "Template removed {file}. Delete locally? [y/N]" (conservative default). An entry `{ file, referencedBy }` is a hook still registered in `.claude/settings.json`: ask once — "Template removed {file}, which your settings.json still references via {refs}. Remove the file and those settings entries together? [Y/n]" — never delete the file and leave a settings entry pointing at nothing. An entry `{ file, userOwned: true }` was never shipped by the template (no baseline record): do not offer deletion — suggest claiming it in `workspace.json` → `workspace.localFiles` instead, showing the exact entry (`"localFiles": ["skills/my-skill/**"]`, or `["rules/my-rule.md"]` for a single file) so future updates skip it.
+- **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, showing each registered reason (a registered deletion is usually deliberate). Restoring installs the payload's version of each.
+- **Removed in template (`removed`):** a plain path — "Template removed {file}. Delete locally? [y/N]" (conservative default). An entry `{ file, referencedBy }` is a hook still registered in `.claude/settings.json`: ask once — "Template removed {file}, which your settings.json still references via {refs}. Remove the file and those settings entries together? [Y/n]" — never delete the file and leave a settings entry pointing at nothing. An entry `{ file, userOwned: true }` was never shipped by the template (no baseline record): do not offer deletion — suggest claiming it in `.claude/template-modifications.json` → `localFiles` instead, showing the exact entry (`"localFiles": ["skills/my-skill/**"]`, or `["rules/my-rule.md"]` for a single file) so future updates skip it. An entry carrying `reason` shows it with its ask — the registry already says why this file is what it is. An entry carrying `unverifiable: true` means the registry didn't parse and its ownership claims were unreadable — that is Step 2's stop; never offer deletion for one until the JSON is fixed and the classification re-run.
 - **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.
+- **Template-modification registry (`legacyKeys` + `staleModifications`):** when `legacyKeys` is non-empty, offer once — "Move your localFiles/templateModifications out of workspace.json into `.claude/template-modifications.json`? [Y/n]". On yes, write the registry in the workspace being updated (the update worktree in the remote flow): merge the legacy values into its `localFiles` array and `modifications` map (paths `.claude/`-relative; create the file if absent) and remove the legacy keys from `workspace.json` there — both edits ride the update's commit, so the rest of the team gets the migration with the update. When `staleModifications` is non-empty, offer once — "These {N} modification entries match the template again ({files}, each with its reason shown) — drop them? [Y/n]"; on yes remove those paths from the registry's `modifications` map. `ignoredKeys` entries cover nothing — mention them in the report so the operator can drop or fix them. Never edit the registry without the operator's yes.
 - **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:
 
-- **workspace.json keys:** First apply any `implicitDefaults` from Step 2 — write the reported key and value into the workspace.json being updated and tell the operator: "kept your previous canonical trimming (40 KB) explicitly; remove the key to turn it off." Then 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.
+- **workspace.json keys:** First apply any `implicitDefaults` from Step 2 — write the reported key and value into the workspace.json being updated and tell the operator: "kept your previous canonical trimming (40 KB) explicitly; remove the key to turn it off." Then 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 — the one exception is the legacy `localFiles`/`templateModifications` keys, which the registry migration above removes with the operator's yes. `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, merge — never regenerate from scratch:
   ```bash
   node {payload}/.claude/scripts/classify-update.mjs --root . --payload {payload} --merge-claude-md
   ```
-  The command prints JSON `{ claudeMd, missingIncludes }`. `claudeMd` is 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. `missingIncludes` lists the `@{file}` include lines the merged file carries whose targets don't exist here (machine-local `local-only-*` targets are exempt — expected absent, never reported). 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, and act on each `missingIncludes` entry — ask "The merged CLAUDE.md includes `{file}`, which doesn't exist here. Create the stub, or leave the include out?" — never write a dangling include silently. (The two JSON configs are the `config` list's, not this block's.)
+  The command prints JSON `{ claudeMd, droppedIncludes, missingIncludes }`. `claudeMd` is 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. `droppedIncludes` names retired `@{file}` includes the workspace still carries but this payload no longer ships — today `@workspace.json`, whose config summary the SessionStart hook now injects instead (gh:196); the line is dropped from the merged result, so name the drop when you show the diff and let the operator's yes (or refusal) on the merged file decide it. `missingIncludes` lists the `@{file}` include lines the merged file carries whose targets don't exist here (machine-local `local-only-*` targets are exempt — expected absent, never reported). 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, and act on each `missingIncludes` entry — ask "The merged CLAUDE.md includes `{file}`, which doesn't exist here. Create the stub, or leave the include out?" — never write a dangling include silently. (The two JSON configs are the `config` list's, not this block's.)
 - **.gitignore:** Merge new entries from the payload's `_gitignore` into the existing `.gitignore` — do not remove user-added lines. An ignore pattern does not untrack already-committed files: if the workspace still tracks the per-machine catalogs the template now ignores (`git ls-files -- 'workspace-context/team-member/*/index.md'`), untrack them (`git rm -r --cached 'workspace-context/team-member/*/index.md'`), or every machine's regenerations keep dirtying pulls.
 
 ### Step 4: Update version and write the baseline
@@ -229,13 +236,14 @@ Report: "Workspace updated to v{templateVersion}. Restart Claude Code if rules o
 
 ### Step 8: Session-model migration nudge
 
-After the update is applied, if the sessions directory (`workspace.workSessionsDir`, default `work-sessions/`) has entries and `workspace.sessionModel` is not `"task"`, append one line to the report: "This workspace still has {N} session(s) under the session model — `/migrate-sessions` can inventory and drain them and switch to the task model whenever you're ready." Suggest only; the operator decides whether and when.
+After the update is applied, read `workspace.json` (Step 4 just rewrote its `templateVersion`, so the file is in hand): if the sessions directory (`workspace.workSessionsDir`, default `work-sessions/`) has entries and `workspace.sessionModel` is not `"task"`, append one line to the report: "This workspace still has {N} session(s) under the session model — `/migrate-sessions` can inventory and drain them and switch to the task model whenever you're ready." Suggest only; the operator decides whether and when.
 
 ## Notes
 
 - The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload, installs the current copy of this skill into `.claude/skills/workspace-update/` (so an outdated installed flow never processes a new payload; a locally customised SKILL.md is backed up as `SKILL.md.local-backup` first), stages a reconstructed baseline inside the payload as `.template-baseline.reconstructed.json` when the workspace has none, and stages the installed version's template files as `.template-base/` (the merge base `differs` files are merged against) whenever that tarball could be fetched — the launcher itself gets no new untracked files, and Step 7 restores the launcher's skill copy before the post-merge pull, rebuilds the per-user catalogs the pull may delete, and removes the update worktree with its branch
 - Never overwrites without asking — `new` and `updated` files are batched behind one confirmation; `differs` files are three-way merged against the staged base when there is one (clean merges batch behind one confirmation, conflicts are resolved one file at a time with the operator's yes, files without a base fall back to the per-file ask); `config` files (`.mcp.json`, `.claude/settings.json`) are merged key by key (array-valued keys union-merged) and never copied wholesale; `localOnly` files are never asked about (local edits to files the template didn't touch)
-- Preserves local modifications, custom content, the workspace's own MCP servers and settings, existing `workspace.json` keys, and deliberately activated rules
+- Preserves local modifications, custom content, the workspace's own MCP servers and settings, existing `workspace.json` keys (the legacy `localFiles`/`templateModifications` keys excepted — they migrate to the registry with the operator's yes), and deliberately activated rules
+- `.claude/template-modifications.json` is the workspace's own registry of deliberate divergences — `localFiles` it owns outright (never offered), `modifications` it keeps with a reason (still updated, reason shown at each decision). The template never ships or overwrites the file; this skill reads it, offers to record a reason when the operator keeps an edit, migrates the legacy `workspace.json` keys into it, offers to drop entries that no longer describe the file, and stops on a registry that doesn't parse until the operator fixes the JSON
 - 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 repo has no remote; with ANY remote, the update lands through a task worktree, a branch, and a PR/MR — the default branch is never pushed directly
 - Can be run multiple times safely (idempotent) — if `.workspace-update/` doesn't exist, it reports no payload and exits

package/template/workspace.json.tmpl

@@ -12,7 +12,8 @@
     "greeting": "Welcome back to {{project-name}}.",
     "sessionModel": "session",
     "tracker": null,
-    "forge": { "type": "github" }
+    "forge": { "type": "github" },
+    "mergeApproval": "ask"
   },
   "repos": {}
 }

package/lib/init.test.mjs

@@ -1,75 +0,0 @@
-#!/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/payload.test.mjs

@@ -1,210 +0,0 @@
-#!/usr/bin/env node
-// Unit tests for payload.mjs
-// Run: node lib/payload.test.mjs
-//
-// The staged .workspace-update/ payload is an on-disk format shared with
-// 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. 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;
-function check(label, ok) {
-  if (ok) { passed++; } else {
-    failed++;
-    console.error(`  FAIL: ${label}`);
-  }
-}
-
-const root = mkdtempSync(join(tmpdir(), 'payload-test-'));
-
-try {
-  const { payloadDir, toVersion } = stagePayload(root, { action: 'init' });
-
-  check('payload staged at .workspace-update/', existsSync(payloadDir));
-  check('manifest written', existsSync(join(payloadDir, '.manifest.json')));
-  check('returns the package version', typeof toVersion === 'string' && toVersion.length > 0);
-
-  // The payload keeps the live names older workspaces' skills expect
-  check('.claude/ staged under live name', existsSync(join(payloadDir, '.claude')));
-  check('.claude/skills/workspace-update/SKILL.md staged', existsSync(join(payloadDir, '.claude', 'skills', 'workspace-update', 'SKILL.md')));
-  check('.claude/settings.json staged', existsSync(join(payloadDir, '.claude', 'settings.json')));
-  check('.mcp.json staged under live name', existsSync(join(payloadDir, '.mcp.json')));
-  check('_gitignore stays inert (skills merge it under that name)', existsSync(join(payloadDir, '_gitignore')));
-
-  // The template's inert names must not leak into the payload
-  check('no _claude/ in payload', !existsSync(join(payloadDir, '_claude')));
-  check('no _mcp.json in payload', !existsSync(join(payloadDir, '_mcp.json')));
-
-  // cleanPayload removes the staging directory
-  cleanPayload(root);
-  check('cleanPayload removes .workspace-update/', !existsSync(payloadDir));
-} finally {
-  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);
-}
-console.log(`${passed} checks passed`);

package/lib/scaffold.test.mjs

@@ -1,79 +0,0 @@
-#!/usr/bin/env node
-// End-to-end test for scaffold.mjs
-// Run: node lib/scaffold.test.mjs
-//
-// The template stores .gitignore, .claude/, and .mcp.json under the inert
-// names _gitignore, _claude/, and _mcp.json (Claude Code protects the live
-// names from headless edits). scaffold() must install every one under its
-// live name and leave no inert leftovers behind.
-import { scaffold } from './scaffold.mjs';
-import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-let failed = 0;
-let passed = 0;
-function check(label, ok) {
-  if (ok) { passed++; } else {
-    failed++;
-    console.error(`  FAIL: ${label}`);
-  }
-}
-
-const directory = mkdtempSync(join(tmpdir(), 'scaffold-test-'));
-
-try {
-  await scaffold({
-    name: 'demo',
-    directory,
-    repos: [],
-    userName: 'tester',
-    activateRules: [],
-  });
-
-  // Live names installed
-  check('.claude/ directory installed', existsSync(join(directory, '.claude')));
-  check('.claude/settings.json installed', existsSync(join(directory, '.claude', 'settings.json')));
-  check('.claude/settings.local.json written', existsSync(join(directory, '.claude', 'settings.local.json')));
-  check('.claude/rules/ installed', existsSync(join(directory, '.claude', 'rules')));
-  check('.claude/rules/coherent-revisions.md installed', existsSync(join(directory, '.claude', 'rules', 'coherent-revisions.md')));
-  check('.mcp.json installed', existsSync(join(directory, '.mcp.json')));
-  check('.gitignore installed', existsSync(join(directory, '.gitignore')));
-
-  // .mcp.json is the template's payload, unmodified
-  const mcp = JSON.parse(readFileSync(join(directory, '.mcp.json'), 'utf8'));
-  check('.mcp.json parses with mcpServers object', typeof mcp.mcpServers === 'object' && mcp.mcpServers !== null);
-
-  // Inert names are gone
-  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 });
-}
-
-if (failed > 0) {
-  console.error(`${failed} check(s) failed, ${passed} passed`);
-  process.exit(1);
-}
-console.log(`${passed} checks passed`);