@ulysses-ai/create-workspace 0.18.0-beta.0 → 0.20.0-beta.0

package/template/{.claude → _claude}/skills/workspace-init/SKILL.md

@@ -26,11 +26,11 @@ If `workspace.json` has `"initialized": true` and no `.workspace-update/` payloa
 
 ## Branching
 
-Workspace-init creates a branch for all its work:
+Workspace-init creates a branch for all its work. Record the default branch first (`git branch --show-current` before switching — usually `main`), then:
 ```bash
 git checkout -b chore/workspace-init
 ```
-All commits go on this branch. After completion, the user reviews and squash-merges to main.
+All commits go on this branch. Step 18 merges the branch back into the default branch at the end — init must finish with every commit on the default branch, never stranded on the init branch (an unmerged init branch leaves `workspace.json` without `initialized: true` on the default branch, which blocks later `/workspace-update` runs). The granular per-step history stays on `chore/workspace-init` for review.
 
 ## Flow
 
@@ -373,9 +373,9 @@ git remote -v
 - Detect the org from project repo remotes in workspace.json
 - Ask: "Create workspace repo as `{org}/workspace-{project}`? Or provide a different name/URL."
 - Create via `gh repo create {org}/{name} --private` and add as remote
-- Do NOT push yet — user merges the branch first
+- Do NOT push yet — Step 18 merges the init branch and pushes the default branch after the merge
 
-### Step 18: Mark initialized and report
+### Step 18: Mark initialized, merge to the default branch, report
 
 Update workspace.json:
 - Set `initialized: true`
@@ -383,12 +383,20 @@ Update workspace.json:
 
 **Commit:** `git commit -m "chore: mark workspace as initialized"`
 
+**Merge to the default branch.** Init is not finished while its commits live only on `chore/workspace-init` — an unmerged init branch leaves the default branch without `initialized: true`, which blocks later `/workspace-update` runs. Ask: "Merge chore/workspace-init into {default-branch} now? [Y/n]" and on yes:
+```bash
+git checkout {default-branch}
+git merge --squash chore/workspace-init
+git commit -m "chore: workspace initialization"
+```
+If a remote is configured, push the default branch (`git push origin {default-branch}`; use `--force-with-lease` only if the operator explicitly accepts rewritten history after a Step 17 rebase). Keep `chore/workspace-init` — it carries the granular per-step history — unless the user asks for it to be deleted. If the user declines the merge, the final report must tell them exactly how to finish it themselves.
+
 **Final report:**
 
 ```
 "Workspace initialized. Restart Claude Code for all rules and hooks to take effect. Then run /start-work to begin.
 
-Branch: chore/workspace-init
+Branch: chore/workspace-init (merged to {default-branch} as "chore: workspace initialization")
 
 Summary:
 - {N} repos cloned
@@ -402,6 +410,7 @@ Summary:
 - {V} self-contradictions found and fixed
 - Template version: {version}
 - Remote: {status}
+- All init commits are on {default-branch}
 
 Issues encountered:
 - {list every expected behavior that failed}
@@ -414,15 +423,12 @@ Active work sessions (formalized from existing worktrees):
 Items in workspace-scratchpad/unmigrated/:
 - {list each item with a one-line description}
 
-Review the branch:
-  git log --oneline chore/workspace-init
-  git diff main..chore/workspace-init
-
-Then merge:
-  git checkout main
-  git merge --squash chore/workspace-init
-  git commit -m 'chore: workspace initialization'
-  git push origin main
+If the merge was declined, replace the branch line with:
+  Not merged yet — finish with:
+    git checkout {default-branch}
+    git merge --squash chore/workspace-init
+    git commit -m 'chore: workspace initialization'
+    git push origin {default-branch}
 
 This session is done. Start a fresh Claude Code session and run /start-work to begin."
 ```

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

@@ -0,0 +1,177 @@
+---
+name: workspace-update
+description: Apply a staged template update to an initialized workspace. The CLI stages a payload in .workspace-update/; this skill processes it. Runs maintenance audit before and after.
+---
+
+# Workspace Update
+
+Apply a staged template update to an initialized workspace. The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload in `.workspace-update/`. This skill reads and applies it. Runs a maintenance audit before updating and verifies integrity after.
+
+## Prerequisites
+
+- `workspace.json` must have `initialized: 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
+  ```
+  If there are hits, name the branch holding the newest commit (`git branch --all --contains {sha}`) and report: "This workspace was initialized on branch `{branch}`, but that branch was never merged. Merge it first (`git merge {branch}`), then re-run /workspace-update." Only if there are no hits, report: "Workspace not initialized. Run /workspace-init first."
+- `.workspace-update/` payload directory must exist (staged by `npx @ulysses-ai/create-workspace --upgrade`)
+- If no `.workspace-update/` payload exists, report: "No update payload found. Run `npx @ulysses-ai/create-workspace --upgrade` to stage the template."
+- Read `.workspace-update/.manifest.json` for `fromVersion`, `templateVersion` (the target version), and `action`
+- If `action` is `"init"`, report: "This payload is for initial setup. Run /workspace-init instead."
+
+## Flow
+
+### Step 1: Pre-update health check
+
+Run `/maintenance audit` (read-only) to surface existing issues. Report findings briefly but **always continue to Step 2 immediately** — do not stop to ask about audit results. The audit is informational, not a gate. Any issues found will be included in the post-update report (Step 5) alongside the update results.
+
+### Step 1b: Decide where the update lands
+
+Check the workspace repo for a remote (`git remote`). This decides where every later step works:
+
+- **No remote** — apply in place. The Step 7 commit lands on the launcher's default branch: the one sanctioned launcher commit, because a repo with no remote has nowhere else for a template update to go. The payload path is `.workspace-update/`.
+- **A remote exists** — the launcher never commits to its default branch. Create a task worktree up front and treat it as the workspace root for Steps 2–6:
+  ```bash
+  node .claude/scripts/task-worktree.mjs --root . --create --repo . --branch chore/template-update-{version}
+  ```
+  The payload is untracked, so it does not appear inside the worktree — keep referencing it at the launcher's absolute path (`{launcher}/.workspace-update`). Step 7 commits, pushes, and PRs from the worktree.
+
+In the commands below, `{payload}` is `.workspace-update` in the no-remote flow and `{launcher}/.workspace-update` in the worktree flow.
+
+### Step 2: Classify the payload
+
+Run the classifier — it compares every verbatim-installed payload file (`.claude/**`, `.mcp.json`, `.claudeignore`) against the workspace by content:
+
+```bash
+node {payload}/.claude/scripts/classify-update.mjs --root . --payload {payload}
+```
+
+It runs from the payload precisely so workspaces that don't have it installed yet can use it; once installed, `node .claude/scripts/classify-update.mjs --root .` is equivalent. Output is JSON with three lists:
+
+- `new` — no installed counterpart; safe to batch-apply (Step 3) behind one confirmation
+- `identical` — installed file already equals the payload; skip silently
+- `differs` — installed file was locally modified; needs a per-file decision
+
+Templates (`*.tmpl`, which install with `{{project-name}}` substitution), `_gitignore` (merged line-by-line), and `.manifest.json` (payload metadata) are not classified — each is handled by its own sub-step in Step 3.
+
+Also list **removed files**: files present in the local `.claude/{component}/` with no counterpart in `{payload}/.claude/{component}/`.
+
+Report with version info from the manifest:
+```
+"Template update: v{fromVersion} → v{templateVersion}. {N} new files, {M} locally modified, {R} removed files, {K} unchanged."
+```
+
+If `new`, `differs`, and the removed list are all empty, report: "Workspace is up to date (template v{templateVersion}). No changes needed."
+
+### Step 2b: Historical .gitignore safety check
+
+Workspaces created before v0.5.1 are vulnerable to a destructive symlink bug in the old layout. The v0.8.0 layout removes the symlink entirely, so new workspaces are not vulnerable — but a workspace being upgraded from a pre-v0.8.0 version may still have the bad `.gitignore` pattern left over.
+
+Check the workspace `.gitignore` for the `repos/` trailing-slash pattern:
+```bash
+grep -E '^repos/$' .gitignore
+```
+
+If found, rewrite it in place to `repos` (no trailing slash). Also check for any tracked `repos` symlink that was already committed:
+```bash
+git ls-files | grep -E '^repos$'
+```
+If found, untrack it: `git rm --cached repos`.
+
+Commit the fix **before** applying other template updates. This runs ahead of Step 3 because applying other updates while the bug is still present could itself trigger the destruction on workspaces that still have the old layout.
+
+### Step 3: Selective update
+
+Batch the safe case, ask on the rest:
+
+- **New files (`new`):** present the list once — "Apply these {N} new files? [Y/n]" — and install them all on confirmation. No per-file prompting.
+- **Locally modified (`differs`):** ask per file — "Template updated {file} but you have local changes. Show diff? [y/N]" — then apply, keep, or merge per the user's decision.
+- **Removed in template:** "Template removed {file}. Delete locally? [y/N]" — conservative default.
+- **Hook migration (.sh to .mjs):** Detect old `.sh` hooks in `.claude/hooks/` that have `.mjs` replacements in the payload. Offer: "Hook {name}.sh has a .mjs replacement in the update. Replace and update settings.json commands? [Y/n]" — this is a one-time migration for workspaces upgrading from pre-0.2.0
+
+Also handle these non-component files from the payload:
+
+- **settings.json:** Merge payload values into existing `.claude/settings.json` — do not overwrite user customizations. Add new keys, update hook commands if hooks were migrated, preserve user-added entries.
+- **workspace.json keys:** Compare the `workspace` object of the payload's `workspace.json.tmpl` with the installed `workspace.json`, key by key. For each key the template ships that the workspace lacks, show its template default and ask before adding. Never remove an existing key just because the template no longer ships it. `canonicalBudgetBytes` is opt-in since v0.19 — leave an existing value alone and mention it can be removed to turn the budget off.
+- **Rules renamed to `.skip`:** For each active `.claude/rules/{name}.md` whose template counterpart now ships as `{name}.md.skip`, keep the active file — it was deliberately activated — and tell the user that's what happened.
+- **CLAUDE.md:** If `{payload}/CLAUDE.md.tmpl` exists, regenerate `CLAUDE.md` from the template. Preserve any user-added sections not present in the template.
+- **.gitignore:** Merge new entries from the payload's `_gitignore` into the existing `.gitignore` — do not remove user-added lines.
+
+### Step 4: Update version
+
+Read `templateVersion` from `.workspace-update/.manifest.json` and update `templateVersion` in `workspace.json` to match.
+
+### Step 4a: Run idempotent migrators
+
+The payload may include migrator scripts at `{payload}/.claude/scripts/migrate-*.mjs` that bring older workspaces forward in shape. They are idempotent — safe to re-run on already-migrated workspaces. Run each one in document order and surface its action in the upgrade summary.
+
+```bash
+node {payload}/.claude/scripts/migrate-claude-md-freshness-include.mjs --root .
+```
+
+Output is JSON: `{"action":"appended"|"unchanged"|"skipped"}`.
+
+- `appended` — the workspace's `CLAUDE.md` got the `@local-only-template-freshness.md` include line added at the end.
+- `unchanged` — the line was already present.
+- `skipped` — no `CLAUDE.md` exists at the workspace root (rare; surface to the user).
+
+```bash
+node {payload}/.claude/scripts/migrate-canonical-priority.mjs --root .
+```
+
+Output is JSON: `{"status":"applied"|"noop","files":[...]}`. Back-fills `priority: critical` on every `workspace-context/shared/locked/*.md` that lacks the field, preserving today's full-load behavior until the user explicitly demotes a file. Skips `local-only-*` files — they are machine-local, never canonical. Idempotent.
+
+Always run migrators with `--root .`. They resolve the workspace root from `--root` (default: the cwd) and never from their own location — a migrator invoked from the payload without `--root` would look for the workspace inside `.workspace-update/`.
+
+Add other migrators here as the template ships them.
+
+### Step 5: Post-update verification
+
+Run `/maintenance audit` again to verify the update didn't introduce:
+- Broken references (new skills not in CLAUDE.md, removed rules still referenced)
+- Contradictions between updated rules and existing shared context
+- Structural mismatches
+
+Then regenerate the context catalogs — an update that adds or renames files under `.claude/` or `workspace-context/` leaves `index.md`/`canonical.md` stale until they are rebuilt:
+
+```bash
+node .claude/scripts/build-workspace-context.mjs --write --root .
+node .claude/scripts/build-workspace-context.mjs --check --root .
+```
+
+`--check` must exit clean. If it reports drift, re-run `--write` and check again before continuing.
+
+Report: "Post-update verification: {N} issues found" or "Post-update verification clean."
+
+### Step 6: Cleanup
+
+Delete the `.workspace-update/` directory at the launcher — in the worktree flow (Step 1b) that happens after the merge and pull in Step 7. The payload has been fully processed and is no longer needed.
+
+### Step 7: Commit
+
+Where the commit lands was decided in Step 1b.
+
+- **No remote:** commit in place on the launcher's default branch — the one sanctioned launcher commit:
+  ```bash
+  git add -A
+  git commit -m "chore: update workspace from template v{fromVersion} to v{templateVersion}"
+  ```
+- **Remote exists:** from the task worktree created in Step 1b, commit the applied update, push the branch, and open a PR through the forge adapter — `node .claude/scripts/task-pr.mjs` when the workspace has it, otherwise the adapter under `.claude/scripts/forges/`. After the PR merges, pull the launcher, then delete the payload (Step 6).
+
+Report: "Workspace updated to v{templateVersion}. Restart Claude Code if rules or hooks changed."
+
+### 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.
+
+## Notes
+
+- The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload. This skill processes it.
+- Never overwrites without asking — `new` files are batched behind one confirmation; `differs` files are asked per file
+- Preserves local modifications, custom content, existing `workspace.json` keys, and deliberately activated rules
+- The launcher's default branch takes a template-update commit only when the workspace has no remote; with a remote, the update lands through a task worktree and a PR
+- Can be run multiple times safely (idempotent) — if `.workspace-update/` doesn't exist, it reports no payload and exits
+- Initial setup is handled by `npx @ulysses-ai/create-workspace --init` + `/workspace-init` — this skill is for subsequent updates only
+- The `.sh` to `.mjs` hook migration is a one-time transition for workspaces created before hooks moved to JavaScript
+- The maintenance audits are read-only and non-blocking — they surface issues but don't prevent the update

package/template/_gitignore

@@ -12,6 +12,9 @@ work-sessions/
 # Disposable workspace-scoped scratchpad (session log, hook debug output)
 workspace-scratchpad/
 
+# Staged template payload — transient input for /workspace-update, never tracked
+.workspace-update/
+
 # Personal overrides
 .claude/settings.local.json
 .claude/.active-session.json

package/template/workspace.json.tmpl

@@ -6,7 +6,7 @@
     "scratchpadDir": "workspace-scratchpad",
     "workSessionsDir": "work-sessions",
     "workspaceContextDir": "workspace-context",
-    "canonicalBudgetBytes": 40960,
+    "alwaysLoadedBudgetBytes": 65536,
     "subagentContextMaxBytes": 32768,
     "subagentInlineMaxBytes": 8192,
     "greeting": "Welcome back to {{project-name}}.",

package/template/.claude/lib/registry-check.mjs

@@ -1,106 +0,0 @@
-import './require-node.mjs';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { dirname } from 'path';
-
-/**
- * SemVer 2.0 comparison limited to the formats this scaffolder publishes:
- * `x.y.z` and `x.y.z-prerelease.N`. Returns -1, 0, or 1.
- *
- * Rules:
- *   - Compare major, minor, patch numerically.
- *   - A pre-release version is older than the same x.y.z without a tag.
- *   - Pre-release identifiers compare per-identifier; numeric identifiers
- *     compare numerically (so `beta.10 > beta.2`), non-numeric lexically.
- */
-export function compareVersions(a, b) {
-  if (a === b) return 0;
-  const [aBase, aPre] = a.split('-', 2);
-  const [bBase, bPre] = b.split('-', 2);
-  const aParts = aBase.split('.').map(Number);
-  const bParts = bBase.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    if ((aParts[i] || 0) < (bParts[i] || 0)) return -1;
-    if ((aParts[i] || 0) > (bParts[i] || 0)) return 1;
-  }
-  if (!aPre && !bPre) return 0;
-  if (!aPre && bPre)  return 1;
-  if (aPre && !bPre)  return -1;
-  const aIds = aPre.split('.');
-  const bIds = bPre.split('.');
-  const len = Math.max(aIds.length, bIds.length);
-  for (let i = 0; i < len; i++) {
-    const ai = aIds[i];
-    const bi = bIds[i];
-    if (ai === undefined) return -1;
-    if (bi === undefined) return 1;
-    const aNum = /^\d+$/.test(ai);
-    const bNum = /^\d+$/.test(bi);
-    if (aNum && bNum) {
-      const an = Number(ai), bn = Number(bi);
-      if (an < bn) return -1;
-      if (an > bn) return 1;
-    } else if (aNum && !bNum) {
-      return -1;
-    } else if (!aNum && bNum) {
-      return 1;
-    } else {
-      if (ai < bi) return -1;
-      if (ai > bi) return 1;
-    }
-  }
-  return 0;
-}
-
-const REGISTRY_URL = 'https://registry.npmjs.org/@ulysses-ai/create-workspace/latest';
-const DEFAULT_TIMEOUT_MS = 3000;
-
-/**
- * Fetch the latest version of the scaffolder from the npm registry.
- * Returns { version, error } — exactly one of them is non-null.
- *
- * Caller injects fetchFn for testing. Default uses global fetch (Node 18+).
- */
-export async function getLatestVersion({ fetchFn = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetchFn(REGISTRY_URL, { signal: controller.signal });
-    if (!res.ok) {
-      return { version: null, error: `registry returned ${res.status} ${res.statusText || ''}`.trim() };
-    }
-    const body = await res.json();
-    if (typeof body?.version !== 'string') {
-      return { version: null, error: 'registry response missing version field' };
-    }
-    return { version: body.version, error: null };
-  } catch (err) {
-    return { version: null, error: err?.message || String(err) };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-/**
- * Read the version cache file. Returns the parsed object if it has a string
- * `latestVersion` field; otherwise null. Treats missing file, malformed JSON,
- * and shape mismatches all as "no cache".
- */
-export function readCache(path) {
-  if (!existsSync(path)) return null;
-  try {
-    const data = JSON.parse(readFileSync(path, 'utf-8'));
-    if (typeof data?.latestVersion !== 'string') return null;
-    return data;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Write the version cache file, creating parent directories as needed.
- */
-export function writeCache(path, data) {
-  const dir = dirname(path);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
-}

package/template/.claude/scripts/migrate-claude-md-freshness-include.mjs

@@ -1,30 +0,0 @@
-#!/usr/bin/env node
-// Idempotent migrator: ensures CLAUDE.md includes @local-only-template-freshness.md.
-// Appends one line at end if missing. Preserves the rest of the file byte-for-byte.
-//
-// Run standalone: node .claude/scripts/migrate-claude-md-freshness-include.mjs
-// Or import { runMigration } and call programmatically.
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { join, dirname, resolve } from 'path';
-import { fileURLToPath } from 'url';
-
-const INCLUDE_LINE = '@local-only-template-freshness.md';
-
-export function runMigration({ workspaceRoot }) {
-  const path = join(workspaceRoot, 'CLAUDE.md');
-  if (!existsSync(path)) return { action: 'skipped', reason: 'no-claude-md' };
-  const before = readFileSync(path, 'utf-8');
-  if (before.includes(INCLUDE_LINE)) return { action: 'unchanged' };
-  const after = before.endsWith('\n') ? before + INCLUDE_LINE + '\n' : before + '\n' + INCLUDE_LINE + '\n';
-  writeFileSync(path, after);
-  return { action: 'appended' };
-}
-
-// CLI entry point — workspace root is two levels up from this file
-// (.claude/scripts/migrate-... → workspace root).
-if (import.meta.url === `file://${process.argv[1]}`) {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const root = resolve(here, '..', '..');
-  const result = runMigration({ workspaceRoot: root });
-  console.log(JSON.stringify(result));
-}

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

@@ -1,134 +0,0 @@
----
-name: workspace-update
-description: Apply a staged template update to an initialized workspace. The CLI stages a payload in .workspace-update/; this skill processes it. Runs maintenance audit before and after.
----
-
-# Workspace Update
-
-Apply a staged template update to an initialized workspace. The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload in `.workspace-update/`. This skill reads and applies it. Runs a maintenance audit before updating and verifies integrity after.
-
-## Prerequisites
-
-- `workspace.json` must have `initialized: true`
-- If not initialized, report: "Workspace not initialized. Run /workspace-init first."
-- `.workspace-update/` payload directory must exist (staged by `npx @ulysses-ai/create-workspace --upgrade`)
-- If no `.workspace-update/` payload exists, report: "No update payload found. Run `npx @ulysses-ai/create-workspace --upgrade` to stage the template."
-- Read `.workspace-update/.manifest.json` for `fromVersion`, `toVersion`, and `action`
-- If `action` is `"init"`, report: "This payload is for initial setup. Run /workspace-init instead."
-
-## Flow
-
-### Step 1: Pre-update health check
-
-Run `/maintenance audit` (read-only) to surface existing issues. Report findings briefly but **always continue to Step 2 immediately** — do not stop to ask about audit results. The audit is informational, not a gate. Any issues found will be included in the post-update report (Step 5) alongside the update results.
-
-### Step 2: Compare current vs payload
-
-For each component directory in `.workspace-update/.claude/` (skills, hooks, agents, rules, recipes), compare files against the corresponding `.claude/{component}/` directory locally:
-
-- **New files:** present in `.workspace-update/.claude/{component}/` but not in `.claude/{component}/`
-- **Updated files:** present in both but contents differ
-- **Unchanged files:** present in both with identical contents
-- **Removed files:** present in `.claude/{component}/` locally but not in `.workspace-update/.claude/{component}/`
-
-Report with version info from the manifest:
-```
-"Template update: v{fromVersion} → v{toVersion}. {N} new files, {M} updated files, {R} removed files, {K} unchanged."
-```
-
-If everything is unchanged and there are no new or removed files, report: "Workspace is up to date (template v{toVersion}). No changes needed."
-
-### Step 2b: Historical .gitignore safety check
-
-Workspaces created before v0.5.1 are vulnerable to a destructive symlink bug in the old layout. The v0.8.0 layout removes the symlink entirely, so new workspaces are not vulnerable — but a workspace being upgraded from a pre-v0.8.0 version may still have the bad `.gitignore` pattern left over.
-
-Check the workspace `.gitignore` for the `repos/` trailing-slash pattern:
-```bash
-grep -E '^repos/$' .gitignore
-```
-
-If found, rewrite it in place to `repos` (no trailing slash). Also check for any tracked `repos` symlink that was already committed:
-```bash
-git ls-files | grep -E '^repos$'
-```
-If found, untrack it: `git rm --cached repos`.
-
-Commit the fix **before** applying other template updates. This runs ahead of Step 3 because applying other updates while the bug is still present could itself trigger the destruction on workspaces that still have the old layout.
-
-### Step 3: Selective update
-
-For each change, ask before applying:
-
-- **New file:** "Add {file}? [Y/n]"
-- **Updated file (no local mods):** "Update {file} to latest template? [Y/n]"
-- **Updated file (locally modified):** "Template updated {file} but you have local changes. Show diff? [y/N]" — let user decide
-- **Removed in template:** "Template removed {file}. Delete locally? [y/N]" — conservative default
-- **Hook migration (.sh to .mjs):** Detect old `.sh` hooks in `.claude/hooks/` that have `.mjs` replacements in the payload. Offer: "Hook {name}.sh has a .mjs replacement in the update. Replace and update settings.json commands? [Y/n]" — this is a one-time migration for workspaces upgrading from pre-0.2.0
-
-Also handle these non-component files from the payload:
-
-- **settings.json:** Merge payload values into existing `.claude/settings.json` — do not overwrite user customizations. Add new keys, update hook commands if hooks were migrated, preserve user-added entries.
-- **CLAUDE.md:** If `.workspace-update/CLAUDE.md.tmpl` exists, regenerate `CLAUDE.md` from the template. Preserve any user-added sections not present in the template.
-- **.gitignore:** Merge new entries from the payload into the existing `.gitignore` — do not remove user-added lines.
-
-### Step 4: Update version
-
-Read `toVersion` from `.workspace-update/.manifest.json` and update `templateVersion` in `workspace.json` to match.
-
-### Step 4a: Run idempotent migrators
-
-The payload may include migrator scripts at `.workspace-update/.claude/scripts/migrate-*.mjs` that bring older workspaces forward in shape. They are idempotent — safe to re-run on already-migrated workspaces. Run each one in document order and surface its action in the upgrade summary.
-
-```bash
-node .workspace-update/.claude/scripts/migrate-claude-md-freshness-include.mjs
-```
-
-Output is JSON: `{"action":"appended"|"unchanged"|"skipped"}`.
-
-- `appended` — the workspace's `CLAUDE.md` got the `@local-only-template-freshness.md` include line added at the end.
-- `unchanged` — the line was already present.
-- `skipped` — no `CLAUDE.md` exists at the workspace root (rare; surface to the user).
-
-```bash
-node .workspace-update/.claude/scripts/migrate-canonical-priority.mjs --root .
-```
-
-Output is JSON: `{"status":"applied"|"noop","files":[...]}`. Back-fills `priority: critical` on every `workspace-context/shared/locked/*.md` that lacks the field, preserving today's full-load behavior until the user explicitly demotes a file. Idempotent — safe to re-run on already-migrated workspaces.
-
-Add other migrators here as the template ships them.
-
-### Step 5: Post-update verification
-
-Run `/maintenance audit` again to verify the update didn't introduce:
-- Broken references (new skills not in CLAUDE.md, removed rules still referenced)
-- Contradictions between updated rules and existing shared context
-- Structural mismatches
-
-Report: "Post-update verification: {N} issues found" or "Post-update verification clean."
-
-### Step 6: Cleanup
-
-Delete the `.workspace-update/` directory entirely. The payload has been fully processed and is no longer needed.
-
-### Step 7: Commit
-
-```bash
-git add -A
-git commit -m "chore: update workspace from template v{fromVersion} to v{toVersion}"
-```
-
-Report: "Workspace updated to v{toVersion}. Restart Claude Code if rules or hooks changed."
-
-### 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.
-
-## Notes
-
-- The CLI (`npx @ulysses-ai/create-workspace --upgrade`) stages the payload. This skill processes it.
-- Never overwrites without asking
-- Preserves local modifications and custom content
-- Can be run multiple times safely (idempotent) — if `.workspace-update/` doesn't exist, it reports no payload and exits
-- Initial setup is handled by `npx @ulysses-ai/create-workspace --init` + `/workspace-init` — this skill is for subsequent updates only
-- The `.sh` to `.mjs` hook migration is a one-time transition for workspaces created before hooks moved to JavaScript
-- The maintenance audits are read-only and non-blocking — they surface issues but don't prevent the update