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

package/README.md

@@ -62,7 +62,7 @@ cd my-workspace
 npx @ulysses-ai/create-workspace@beta --upgrade
 ```
 
-This stages the new template payload to `.workspace-update/` without changing anything yet. Open Claude Code and run `/workspace-update` — the skill applies each change interactively (asks how to resolve any file you've customized) and runs a maintenance audit before and after.
+This stages the new template payload to `.workspace-update/` without changing anything yet. Open Claude Code and run `/workspace-update` — the skill applies each change interactively (asks how to resolve any file you've customized) and verifies the result with a scripted maintenance audit.
 
 ## Why "Ulysses"?
 

package/package.json

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

package/template/CLAUDE.md.tmpl

@@ -30,9 +30,9 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - `/promote` — move personal memory to shared context
 - `/release [version]` — cut a versioned release: bump, tag, forge release with generated notes
 - `/sync-work` — push branches without ceremony
-- `/workspace-update` — apply template updates (runs maintenance before/after)
+- `/workspace-update` — apply template updates, verified by a post-update audit
 - `/setup-tracker` — wire this workspace to an issue tracker (GitHub Issues shipped; others pluggable)
-- `/maintenance [audit|cleanup]` — workspace health checks and cleanup
+- `/maintenance [audit|cleanup]` — scripted health audit and cleanup
 - `/context-placement` — decide where durable content belongs and what each destination costs before writing it
 - `/goal-driven-work` — run multi-phase autonomous work under `/goal` with phase artifacts and agent-team dispatch
 - `/migrate-sessions` — drain session-model work sessions and switch the workspace to the task lifecycle

package/template/_claude/hooks/workspace-update-check.mjs

@@ -26,17 +26,17 @@ const stale = manifest?.timestamp
 const urgency = stale
   ? `URGENT: This update payload has been pending since ${manifest.timestamp}. It was not completed in a previous session. `
   : '';
-const skipAudit = stale
-  ? 'Skip the pre-update audit and proceed directly to comparing and applying changes. '
+const staleHint = stale
+  ? 'This payload survived a previous session — classify and apply the changes directly, and still run the post-update verification the skill ends with. '
   : '';
 
 if (action === 'init' || !initialized) {
   respond(`MANDATORY: ${urgency}A workspace init payload (template v${version}) is pending at .workspace-update/.
 Read .workspace-update/.claude/skills/workspace-init/SKILL.md and follow it before doing anything else.
-${skipAudit}Do not proceed with the user's request until initialization is complete.`);
+${staleHint}Do not proceed with the user's request until initialization is complete.`);
 } else {
   const from = manifest?.fromVersion || 'unknown';
   respond(`MANDATORY: ${urgency}A workspace upgrade payload (v${from} → v${version}) is pending at .workspace-update/.
 Read .workspace-update/.claude/skills/workspace-update/SKILL.md and follow it before doing anything else.
-${skipAudit}Do not proceed with the user's request until the update is complete.`);
+${staleHint}Do not proceed with the user's request until the update is complete.`);
 }

package/template/_claude/scripts/build-workspace-context.mjs

@@ -765,4 +765,6 @@ export {
   stripFrontmatter,
   gitIgnoredPaths,
   isLocalOnlyName,
+  readIgnorePrefixes,
+  isIgnored,
 };

package/template/_claude/scripts/classify-update.mjs

@@ -10,10 +10,21 @@
 //           this file from <workspace>/.workspace-update/.claude/scripts/)
 // --payload the staged payload; defaults to <root>/.workspace-update
 //
-// Prints JSON: { "new": [...], "identical": [...], "differs": [...] }
+// Prints JSON with five lists:
 //   new       — no installed counterpart; safe to batch-apply after one confirm
 //   identical — installed file already equals the payload byte-for-byte
 //   differs   — installed file differs; needs a per-file decision
+//   activated — the payload ships rules/{name}.md.skip while the workspace
+//               deliberately keeps {name}.md active; nothing to install, the
+//               active rule stays (gh:180)
+//   removed   — installed file with no payload counterpart: the template
+//               stopped shipping it. Excludes what the workspace owns:
+//               *.test.mjs (the npm tarball does not ship tests, dev-checkout
+//               installs do — every test file would otherwise read as
+//               removed), anything gitignored (machine-local), paths under
+//               .claude/worktrees/, and entries of workspace.json →
+//               workspace.localFiles (array of .claude/-relative paths or
+//               globs for files this workspace owns) (gh:180)
 //
 // Only verbatim-installed files are classified: everything under .claude/,
 // plus .mcp.json and .claudeignore. The payload's templates (*.tmpl, which
@@ -30,6 +41,7 @@ import {
 } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { gitIgnoredPaths } from './build-workspace-context.mjs';
 
 function isMainModule(metaUrl) {
   if (!process.argv[1]) return false;
@@ -58,7 +70,12 @@ function isClassified(payloadRelPath) {
   return VERBATIM_ROOTS.includes(first);
 }
 
-function* walkFiles(dir, prefix = '') {
+// Directories never walked when looking for removed files. .claude/worktrees/
+// holds entire nested worktrees — walking them is slow and every file inside
+// is unmanaged by the template.
+const SKIPPED_DIRS = new Set(['worktrees']);
+
+function* walkFiles(dir, prefix = '', skipDirs = null) {
   let entries;
   try {
     entries = readdirSync(dir).sort();
@@ -66,15 +83,67 @@ function* walkFiles(dir, prefix = '') {
     return;
   }
   for (const name of entries) {
+    if (skipDirs && skipDirs.has(name)) continue;
     const rel = prefix ? `${prefix}/${name}` : name;
     const full = join(dir, name);
     let st;
     try { st = statSync(full); } catch { continue; }
-    if (st.isDirectory()) yield* walkFiles(full, rel);
+    if (st.isDirectory()) yield* walkFiles(full, rel, skipDirs);
     else if (st.isFile()) yield rel;
   }
 }
 
+// Installed files under the verbatim-managed roots: the .claude/ tree (minus
+// skipped directories) plus the two standalone files. Nothing else in the
+// workspace root is walked — repos/ and work-sessions/ hold entire worktrees
+// the template never manages.
+function* walkInstalledFiles(absRoot) {
+  yield* walkFiles(join(absRoot, '.claude'), '.claude', SKIPPED_DIRS);
+  for (const name of ['.mcp.json', '.claudeignore']) {
+    if (existsSync(join(absRoot, name))) yield name;
+  }
+}
+
+/** workspace.json → workspace.localFiles, normalized to .claude/-relative globs. */
+function readLocalFiles(absRoot) {
+  const configPath = join(absRoot, 'workspace.json');
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    const entries = config?.workspace?.localFiles;
+    if (!Array.isArray(entries)) return [];
+    return entries
+      .filter((e) => typeof e === 'string' && e.length > 0)
+      .map((e) => e.replace(/^(\.claude\/)+/, ''));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Match `rel` (a .claude/-relative posix path) against a localFiles entry —
+ * an exact path or a glob where `**` spans separators and `*` does not.
+ * No glob library: the shapes localFiles needs are these two stars.
+ */
+function globMatches(pattern, rel) {
+  if (pattern === rel) return true;
+  if (!pattern.includes('*')) return false;
+  const re = new RegExp(
+    `^${pattern.split('**').map(
+      (part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*'),
+    ).join('.*')}$`,
+  );
+  return re.test(rel);
+}
+
+function isOwnedByWorkspace(rel, localFiles) {
+  if (rel.endsWith('.test.mjs')) return true;
+  // The template's own .gitignore declares these machine-local.
+  if (rel === '.claude/settings.local.json' || rel === '.claude/.active-session.json') return true;
+  if (!rel.startsWith('.claude/')) return false;
+  const claudeRel = rel.slice('.claude/'.length);
+  return localFiles.some((pattern) => globMatches(pattern, claudeRel));
+}
+
 export function classifyUpdate({ root, payload }) {
   const absRoot = resolve(root);
   const absPayload = resolve(payload ?? join(absRoot, '.workspace-update'));
@@ -82,9 +151,20 @@ export function classifyUpdate({ root, payload }) {
     throw new Error(`No payload found at ${absPayload} — run npx @ulysses-ai/create-workspace --upgrade first`);
   }
 
-  const result = { new: [], identical: [], differs: [] };
-  for (const rel of walkFiles(absPayload)) {
-    if (!isClassified(rel)) continue;
+  const payloadFiles = [...walkFiles(absPayload)].filter(isClassified);
+  const payloadSet = new Set(payloadFiles);
+
+  const result = { new: [], identical: [], differs: [], activated: [], removed: [] };
+  for (const rel of payloadFiles) {
+    // A .skip rule whose active counterpart is installed was deliberately
+    // activated by this workspace: report it as activated, not new.
+    if (rel.startsWith('.claude/rules/') && rel.endsWith('.md.skip')) {
+      const active = rel.replace(/\.skip$/, '');
+      if (existsSync(join(absRoot, active)) && !existsSync(join(absRoot, rel))) {
+        result.activated.push({ skip: rel, active });
+        continue;
+      }
+    }
     const installed = join(absRoot, rel);
     if (!existsSync(installed)) {
       result.new.push(rel);
@@ -98,6 +178,21 @@ export function classifyUpdate({ root, payload }) {
       result.differs.push(rel);
     }
   }
+
+  // Removed: installed verbatim-managed files with no payload counterpart.
+  const skipSet = new Set(payloadFiles);
+  const localFiles = readLocalFiles(absRoot);
+  const installedFiles = [...walkInstalledFiles(absRoot)];
+  const gitignored = gitIgnoredPaths(absRoot, installedFiles);
+  for (const rel of installedFiles) {
+    if (skipSet.has(rel)) continue;
+    // An active rule whose .skip twin is in the payload is an activated rule,
+    // not a removed one.
+    if (rel.startsWith('.claude/rules/') && rel.endsWith('.md') && skipSet.has(`${rel}.skip`)) continue;
+    if (gitignored.has(rel)) continue;
+    if (isOwnedByWorkspace(rel, localFiles)) continue;
+    result.removed.push(rel);
+  }
   return result;
 }
 

package/template/_claude/skills/maintenance/SKILL.md

@@ -16,33 +16,41 @@ Keep the workspace healthy. Combines integrity auditing with active cleanup reco
 
 Read-only integrity checks. Reports problems but never modifies files.
 
+The mechanical checks are scripted (gh:180) — run the audit and present its report:
+
+```bash
+node .claude/scripts/maintenance-audit.mjs --root .
+```
+
+The report prints one block per section — ✓ ok lines, ✗ issues, ⚠ warnings, ℹ infos — then a result summary. Severity drives the exit code: any issue-severity finding → exit `1`, otherwise `0` (a non-zero exit is the report above it, not a crash). `--offline` skips section 7, the only network user; `--json` emits `{issues, summary}` instead of the human report when another step needs the machine-readable numbers.
+
+Sections 1–7 below explain what the script checks, so its findings can be interpreted. Each also names what it does not carry — those residual checks Claude performs alongside the script run.
+
 ### 1. Cross-reference consistency
-Scan all workspace-context files against each other:
-- **Stale references** — file A mentions "2 mandatory rules" but there are now 4
-- **Path references** — file A mentions a file that was moved or deleted
-- **Contradictions** — file A says "user-scoped is default" but file B says "root is default"
+The script checks the CLAUDE.md skill list against `.claude/skills/` in both directions, and walks CLAUDE.md's `@`-import graph for dangling imports. A missing `local-only-*` file or the optional `CODEBASE.md` stub is info, not an issue — expected states on machines that never generated them.
+
+Semantic drift between context files — one saying "2 mandatory rules" when there are now 4, or two files contradicting each other — is not mechanically decidable; cleanup step 10's reconciliation covers it.
 
 ### 2. Frontmatter integrity
-For each workspace-context `.md` file and each `work-sessions/*/workspace/session.md`:
-- Valid frontmatter? (state, lifecycle, type, topic, author, updated; plus name/status/branch/repos for session trackers)
-- `branch` field references a branch that still exists?
-- `repo`/`repos` field references repos that exist in workspace.json?
-- `lifecycle: active` on a file not updated in 7+ days? (stale candidate)
-- `lifecycle: resolved` files that should have been processed by /complete-work?
-- Session tracker `status: active` but the workspace worktree at `work-sessions/{name}/workspace/` is missing? (orphaned)
-- `confidence` field present? Must be one of `high`, `medium`, `low` if set.
+For each non-gitignored workspace-context `.md` and each `work-sessions/*/workspace/session.md`, the script checks:
+- Frontmatter parses
+- Session trackers carry `name`, `status`, `branch`
+- `branch` references a branch that still exists
+- `repo`/`repos` reference repos in workspace.json
+- `lifecycle: active` untouched in 7+ days (stale candidate)
+- `lifecycle: resolved` (info — confirm /complete-work has processed it)
+- `confidence`, when set, is one of `high`, `medium`, `low`
 
 ### 3. Workspace structure
-- Actual directory layout matches what workspace-structure rule describes?
-- CLAUDE.md references skills and rules that actually exist?
-- Orphaned rules or skills not referenced anywhere?
-- workspace.json repos all present in `repos/`?
+The script checks that workspace.json and CLAUDE.md are present and parseable, that `workspace-context/` and `.claude/rules`, `skills`, `scripts` directories exist, and that every manifest repo is cloned under `repos/`.
 
 ### 4. Git state
+The script covers the launcher itself: on its default branch, tracked tree clean. Untracked paths are info — gitignored content is not counted.
+
+The worktree-level checks are not carried by the script; perform them alongside it:
 - Worktrees with no recent commits? (orphaned)
 - Local branches with no remote tracking? (unpushed work)
 - Worktrees whose branch has already been merged? (cleanup candidates)
-- Workspace repo on expected branch?
 - Orphan worktree records in project repos — run `git -C repos/{repo} worktree list` for each repo and flag any `prunable` markers. These usually come from a workspace-first teardown (the unsafe order) leaving stale admin records behind. Suggest `git worktree prune` on the affected repo.
 - Task-model state (gh:146), three checks:
   - **Unrecorded task worktrees** — list `repos/*/.claude/worktrees/*` and `.claude/worktrees/*`, read each candidate's branch (`git -C "{path}" rev-parse --abbrev-ref HEAD`), and keep only those on a task-prefixed branch (`feature/`, `bugfix/`, `chore/`) — Claude Code's own worktrees carry other branch names, so the prefix filter skips them without guessing a name convention. Cross-reference the chat records (`node .claude/scripts/chat-record.mjs --root . --list`): a task-prefixed worktree no record entry claims is *unrecorded* — it may be a legitimate no-tracker task (those are never recorded), so present it and ask before suggesting `node .claude/scripts/task-worktree.mjs --root . --remove --repo "{repo}" --branch "{branch}"`.
@@ -50,92 +58,29 @@ For each workspace-context `.md` file and each `work-sessions/*/workspace/sessio
   - **Merged but never completed** — a recorded task branch that already merged. Judge merged-ness by the forge's merged PRs for that repo, matching on head branch — never `git branch --merged`, which a squash merge (never an ancestor) silently misses. `/complete-work` never ran. Suggest running `/complete-work` for that branch (detection from the chat record finds it).
 
 ### 5. Workspace-context auto-file integrity
+The script regenerates `workspace-context/index.md`, `canonical.md`, and each `workspace-context/team-member/{user}/index.md` in memory and compares fingerprints — the same semantics as `build-workspace-context.mjs --check`:
+- Missing or stale artifact → issue; regenerate with `node .claude/scripts/build-workspace-context.mjs --write --root .`
+- A missing gitignored per-user index → info (regenerated per machine, the normal fresh-checkout state)
+- Canonical body over budget after trim and stub → warning, deferred to cleanup triage
+- Trimmed or stubbed but within budget → info
 
-`workspace-context/index.md`, `workspace-context/canonical.md`, and each `workspace-context/team-member/{user}/index.md` are auto-generated from frontmatter and locked content. Run the check:
+The canonical budget is opt-in: `workspace.canonicalBudgetBytes` off (absent or `null`) means canonical ships every locked file in full and over-budget cannot occur. When set, selection walks `ok` → `trimmed` → `stubbed` → `over-budget` as the generator gives up progressively more reference content to fit: `trimmedFiles` are reference files whose `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` spans were dropped, `stubbedFiles` are reference files reduced to a one-line breadcrumb. `over-budget` means the budget is still exceeded after stubbing — regeneration cannot fix it; the locked content itself needs triage via `/maintenance cleanup` (step 11). Stale wins over over-budget: a stale canonical is reported as stale, hiding any over-budget condition until it is regenerated.
 
-```bash
-node .claude/scripts/build-workspace-context.mjs --check --root .
-```
-
-The script reports per-artifact status as JSON and uses three exit codes to distinguish what's wrong:
-
-- `0` — all artifacts current and, when a canonical budget is set, the rendered canonical fits inside `workspace.canonicalBudgetBytes`.
-- `1` — at least one artifact is `missing` or `stale`. Run `--write` to regenerate. `missing` means the artifact does not exist yet; `stale` means it exists but no longer matches its sources (a file was added or deleted, a `description:` changed, a `shared/locked/` file was edited, an `.indexignore` rule was added).
-- `2` — artifacts are current but canonical body bytes exceed the budget after the trim and stub stages have already run. Only reachable when a budget is set. Regeneration cannot fix this; the locked content itself needs triage. Stale wins over over-budget when both apply, so a `1` can hide an over-budget condition until you regen.
-
-The JSON payload always includes a `canonical` block summarizing the budget outcome:
-
-```json
-{
-  "status": "current",
-  "missing": [],
-  "stale": [],
-  "canonical": {
-    "budget": 40960,
-    "current": 47802,
-    "overBy": 6842,
-    "selectionStatus": "stubbed",
-    "trimmedFiles": ["post-release-discipline"],
-    "stubbedFiles": ["project-status", "release-flow-recipes"]
-  }
-}
-```
-
-`selectionStatus` walks `ok` → `trimmed` → `stubbed` → `over-budget` as the script gives up progressively more reference content trying to fit the budget. `trimmedFiles` lists reference files whose `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` spans were dropped; `stubbedFiles` lists reference files whose entire body was replaced with a one-line breadcrumb. `overBy` is present only when `selectionStatus === 'over-budget'` and reports the bytes still over after stubbing.
-
-The canonical budget is opt-in. `workspace.canonicalBudgetBytes` is off unless workspace.json sets it — absent or `null` means no budget. When off, `canonical.md` ships every locked file in full, the `canonical` block reports `"budget": null` with `selectionStatus: "ok"`, exit `2` cannot occur, and the audit reports one informational line in place of the budget OK/warning line:
-
-```
-• Canonical budget: off (alwaysLoadedBudgetBytes covers the total)
-```
-
-No warning accompanies it. To turn the budget back on, set a byte count in workspace.json (e.g. `"canonicalBudgetBytes": 40960`) and regenerate.
-
-Audit mode reports the status verbatim. When a budget is set and `selectionStatus` is `over-budget`, audit emits the budget violation and recommends `/maintenance cleanup` to triage — regeneration will not resolve it. Cleanup mode runs `--write` when `missing` or `stale`, re-checks, and then enters the budget triage flow described in cleanup step 11 if the post-regen check still reports `over-budget`.
-
-While the indexes are being read, also flag entries with weak fallbacks: filename-slug-only descriptions (e.g., "project status" with no period) usually indicate the underlying file is missing a `description:` or has no usable opening sentence. Suggest adding `description:` to those source files — the index will pick it up on the next regeneration.
+Residual, not in the script: while reading the indexes, flag filename-slug-only descriptions (e.g., "project status" with no period) — usually the source file is missing a `description:` or has no usable opening sentence. Suggest adding `description:`; the index picks it up on the next regeneration.
 
 ### 6. Always-loaded context budget
+The script measures everything Claude reads at launch — CLAUDE.md, its @-imports, and the active rules — against `workspace.alwaysLoadedBudgetBytes`. Rules with `paths:` frontmatter are conditional (they load only when a matching file is touched) and count separately; with no budget in workspace.json the check passes trivially.
 
-Everything Claude reads at launch — CLAUDE.md, its @-imports, and the active rules — is measured against `workspace.alwaysLoadedBudgetBytes`:
-
-```bash
-node .claude/scripts/context-footprint.mjs --root .
-```
-
-Rules carrying `paths:` frontmatter are conditional (they load only when a matching file is touched); the script lists them in a separate conditional section and excludes them from the total. With no `alwaysLoadedBudgetBytes` in workspace.json there is no budget and this check passes trivially.
-
-Within budget → an OK line: `✓ Always-loaded context: 43 KB / 64 KB`. Over budget → a Warning (the workspace still functions; this is drift, not breakage) naming the top contributors and the fixes:
-
-```
-⚠ Always-loaded context exceeds budget: 78 KB / 64 KB. Top contributors:
-  .claude/rules/git-conventions.md (12 KB), CLAUDE.md (9 KB),
-  .claude/rules/workspace-structure.md (8 KB). Scope situational rules with
-  paths: frontmatter, or move reference content to shared/.
-```
-
-The script itself exits `1` when over budget; `/maintenance` reports that as the warning above, not as a failed run.
+Within budget → an OK line (`✓ Always-loaded context: 43 KB / 64 KB`). Over → a warning — the workspace still functions; this is drift, not breakage — naming the top contributors. Fixes: scope situational rules with `paths:` frontmatter, or move reference content to `shared/`.
 
 ### 7. Template freshness
+The script invokes `refreshIfStale` with a 24h TTL regardless of `workspace.versionCheck.ambient` — the user explicitly ran `/maintenance` — and reports:
+- `outdated` → warning: `Template v{current} → v{latest} available. Run npx @ulysses-ai/create-workspace --upgrade.`
+- `current` → ✓ Template is up to date (v{latest})
+- `unknown` → warning: could not reach the npm registry
+- `skipped: 'uninitialized'` → info: workspace not initialized, freshness check unavailable
 
-Compare the workspace's pinned template version against the latest published on npm.
-
-Always invoke `refreshIfStale` from the audit (regardless of `workspace.versionCheck.ambient` — the user explicitly ran `/maintenance`):
-
-```javascript
-import { refreshIfStale } from './.claude/lib/freshness.mjs';
-const result = await refreshIfStale({
-  workspaceRoot: process.cwd(),
-  ttlMs: 24 * 60 * 60 * 1000,
-});
-```
-
-Report one of:
-- `outdated` → `✗ Template v{current} → v{latest} available. Run npx @ulysses-ai/create-workspace --upgrade.`
-- `current` → `✓ Template is up to date (v{latest}).`
-- `unknown` (with cache) → `⚠ Could not reach npm registry; last cached latest was v{latest} as of {checkedAt}.`
-- `unknown` (no cache) → `⚠ Could not reach npm registry; no cached version on file. Try again when online.`
-- `skipped: 'uninitialized'` → `⚠ Workspace not initialized; freshness check unavailable.`
+An `outdated` result also rewrites the `local-only-template-freshness.md` banner and the version cache, as this check always has.
 
 ## Cleanup
 
@@ -173,7 +118,7 @@ When stale candidates are found, surface them as warnings in the output format a
 
 ### 11. Canonical budget triage
 
-This step runs only when a canonical budget is set (`workspace.canonicalBudgetBytes` holds a number) and the post-regen `--check` from the cleanup regen pass (Flow step 9) still reports `selectionStatus: 'over-budget'`. With the budget off — absent or `null` in workspace.json — `--check` can never report over-budget, so this step is unreachable. Skip it too if the regular regen pass cleared the budget, or if `--check` was already `ok`, `trimmed`, or `stubbed` after that pass.
+This step runs only when a canonical budget is set (`workspace.canonicalBudgetBytes` holds a number) and the post-regen `--check` from the cleanup regen pass (Flow step 4) still reports `selectionStatus: 'over-budget'`. With the budget off — absent or `null` in workspace.json — `--check` can never report over-budget, so this step is unreachable. Skip it too if the regular regen pass cleared the budget, or if `--check` was already `ok`, `trimmed`, or `stubbed` after that pass.
 
 The rest of cleanup is suggestion-list-with-confirmation: surface a candidate, ask before applying, move on. Triage is the one meaningfully more interactive surface in `/maintenance`. It runs as a small REPL: present the budget state and a triage menu, take one action, re-run `--check`, present the menu again with the new state. No suggestion is auto-applied; every action is the user's choice.
 
@@ -231,8 +176,8 @@ Read `workspace.json`. If `workspace.tracker?.type === 'github-issues'` and `wor
 This is migration guidance for workspaces created before the `forge` field landed — the field is back-compat with a sensible default, so the unset case is not a bug, just an opportunity to make the implicit explicit. If `workspace.forge.type` is set to a value with no adapter at `.claude/scripts/forges/{type}.mjs`, that IS an error and goes in the Issues section.
 
 ### 13. Health metrics
-- Canonical budget — read from the same `--check` invocation as step 5. When a budget is set, reported as `current / budget` bytes with the selection status (e.g., `full`, `2 reference files trimmed`); over-budget cases are deferred to the cleanup triage flow rather than re-reported here. When off, report the step 5 one-liner: `• Canonical budget: off (alwaysLoadedBudgetBytes covers the total)`.
-- Always-loaded context — read from the same `context-footprint.mjs` invocation as audit step 6, reported the same way (`current / budget` bytes); over-budget is already surfaced as a warning there.
+- Canonical budget — read from the audit script's section 5 outcome (the same regenerate-and-compare it already ran). When a budget is set, reported as `current / budget` bytes with the selection status (e.g., `full`, `2 reference files trimmed`); over-budget cases are deferred to the cleanup triage flow rather than re-reported here. When off, report the step 5 one-liner: `• Canonical budget: off (alwaysLoadedBudgetBytes covers the total)`.
+- Always-loaded context — read from the audit script's section 6 outcome, reported the same way (`current / budget` bytes); over-budget is already surfaced as a warning there.
 - Number of ephemeral files — flag if accumulating without resolution
 - Session log stats (if `workspace-scratchpad/session-log.jsonl` exists):
   - Sessions without capture
@@ -272,16 +217,11 @@ OK (6):
 
 ## Flow
 
-1. Scan workspace-context/ recursively — read all `.md` files and their frontmatter
-2. Read CLAUDE.md — extract skill and rule references
-3. Read workspace.json — extract repo manifest
-4. Check `.claude/rules/`, `.claude/skills/`, `.claude/agents/` against references
-5. Check git state (worktrees, branches, remotes)
-6. Run `node .claude/scripts/build-workspace-context.mjs --check --root .` — capture status. Exit `0` = clean (and within budget when one is set), `1` = artifact missing or stale, `2` = artifacts current but canonical body over budget — only possible with a budget set. The `canonical` block in the JSON output drives both the audit budget line and the cleanup triage decision; `"budget": null` means the canonical budget is off.
-7. Run `node .claude/scripts/context-footprint.mjs --root .` — capture the total and the `BUDGET` line. Exit `0` = within budget or no budget set; exit `1` = over budget, reported as a warning with the top contributors (audit step 6).
-8. Read session-log.jsonl if it exists
-9. If cleanup mode: regenerate the workspace-context auto-files if stale (index.md, canonical.md, per-user team-member indexes); compare files pairwise for overlap; scan for stale cross-references. If post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 11.
-10. Compile and present findings grouped by severity
+1. Run `node .claude/scripts/maintenance-audit.mjs --root .` and present its report — it carries audit sections 1–7. Add `--offline` when there is no network (section 7 is the only network user), or `--json` when step 13's health metrics want the machine-readable `summary.canonical` / `summary.alwaysLoaded` numbers.
+2. Perform the residual checks the script does not carry — the worktree-level git checks from audit section 4 (orphaned worktrees, unpushed branches, merged worktrees, prunable worktree records, the task-model checks against `chat-record.mjs --list`).
+3. Read session-log.jsonl if it exists (feeds step 13's session log stats)
+4. If cleanup mode: run `node .claude/scripts/build-workspace-context.mjs --check --root .` — exit `0` = clean (and within budget when one is set), `1` = artifact missing or stale → regenerate with `--write`, `2` = artifacts current but canonical body over budget (only possible with a budget set). The `canonical` block in the JSON drives the triage decision; `"budget": null` means the canonical budget is off. Then compare context files pairwise for overlap and scan for stale cross-references; if the post-regen `--check` reports `over-budget`, enter the canonical-budget triage flow described in cleanup step 11.
+5. Compile and present findings grouped by severity (Output Format above): the script's findings plus the residual checks, with cleanup suggestions from steps 3–4 folded in.
 
 ## Notes
 - Audit mode is always read-only — never modifies files

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

@@ -1,11 +1,11 @@
 ---
 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.
+description: Apply a staged template update to an initialized workspace. The CLI stages a payload in .workspace-update/; this skill processes it and verifies the result with a scripted audit.
 ---
 
 # 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.
+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, then verifies the result with the scripted maintenance audit — one audit, at the end, when there is something to verify (gh:180).
 
 ## Prerequisites
 
@@ -22,11 +22,7 @@ Apply a staged template update to an initialized workspace. The CLI (`npx @ulyss
 
 ## 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
+### Step 1: Decide where the update lands
 
 Check the workspace repo for a remote (`git remote`). This decides where every later step works:
 
@@ -41,28 +37,28 @@ In the commands below, `{payload}` is `.workspace-update` in the no-remote 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:
+Run the classifier — it compares every verbatim-installed payload file (`.claude/**`, `.mcp.json`, `.claudeignore`) against the workspace by content, and detects files the template no longer ships:
 
 ```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:
+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 five 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
+- `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. Tests (`*.test.mjs`), 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, so only real template removals are listed.
 
 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."
+"Template update: v{fromVersion} → v{templateVersion}. {N} new files, {M} locally modified, {A} activated rules, {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."
+If `new`, `differs`, `activated`, and `removed` are all empty, report: "Workspace is up to date (template v{templateVersion}). No changes needed."
 
 ### Step 2b: Historical .gitignore safety check
 
@@ -87,14 +83,14 @@ 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.
+- **Removed in template (`removed`):** "Template removed {file}. Delete locally? [y/N]" — conservative default.
+- **Activated rules (`activated`):** keep the active file, install nothing — report: "Rule {name} is active here and optional in the template; your activation is preserved."
 - **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.
 
@@ -104,7 +100,7 @@ Read `templateVersion` from `.workspace-update/.manifest.json` and update `templ
 
 ### 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.
+Two migrators run on **every** update — both idempotent, safe on already-migrated workspaces. Run each and surface its action in the upgrade summary.
 
 ```bash
 node {payload}/.claude/scripts/migrate-claude-md-freshness-include.mjs --root .
@@ -120,20 +116,20 @@ Output is JSON: `{"action":"appended"|"unchanged"|"skipped"}`.
 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.
+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.
 
-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/`.
+The other `migrate-*.mjs` in the payload are **one-shot, version-gated migrations**: each applies to a specific step of the template's history and runs only when the manifest's `fromVersion` is older than the version that introduced it. Never run them unconditionally.
 
-Add other migrators here as the template ships them.
+- `migrate-session-layout.mjs` — pre-v0.10.0 → v0.10.0: moves session content from launcher-side paths into each session's workspace worktree.
+- `migrate-to-workspace-context.mjs` — pre-v0.15.0 → v0.15.0: renames `shared-context/` to `workspace-context/` and rebuilds its structure.
+- `migrate-sessions.mjs` — pre-v0.18.0: drains session-model work sessions onto the task lifecycle. Not run inline — it has interactive inventory/backup/archive modes; `/migrate-sessions` drives it (Step 8 nudges when it applies).
+- `migrate-open-work.mjs` — manual, any version: converts the deprecated `open-work.md` into tracker issues. Takes the file path as an argument and needs a configured tracker; run it only if the workspace still carries an `open-work.md` and the user asks.
 
-### Step 5: Post-update verification
+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/`.
 
-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
+### Step 5: Post-update verification
 
-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:
+First 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 .
@@ -142,22 +138,36 @@ 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.
 
+Then run the scripted audit — once, covering everything (gh:180). Build the changed list — every file this update added or changed: the applied `new` and `differs` files plus the merged ones (`CLAUDE.md`, `workspace.json`, `.gitignore`, `.claude/settings.json`, `.mcp.json` as touched) — one path per line into a temp file such as `workspace-scratchpad/update-changed.txt`, then:
+
+```bash
+node {payload}/.claude/scripts/maintenance-audit.mjs --root . --changed workspace-scratchpad/update-changed.txt
+```
+
+Run it from the payload for the same reason as the classifier in Step 2: the workspace's own copy may predate this update. It reuses the sections of `/maintenance` audit that a script can decide (cross-references, frontmatter, structure, git state, catalog integrity, budgets, freshness) and marks findings on changed files `(from this update)`.
+
+Present its report as the verification result. Git-state warnings are expected here — the update's commit hasn't landed yet (Step 7). Delete the temp changed list afterwards.
+
+- Findings labeled `(from this update)` — caused by this update; fix before committing (usually a new skill missing from CLAUDE.md's list, or a stale catalog).
+- Other findings — pre-existing; mention briefly.
+- If the audit found issue-severity findings, offer to walk through them with the full `/maintenance` skill. Warnings and infos alone need no follow-up.
+
 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.
+Delete the `.workspace-update/` directory at the launcher — in the worktree flow (Step 1) 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.
+Where the commit lands was decided in Step 1.
 
 - **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).
+- **Remote exists:** from the task worktree created in Step 1, 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."
 
@@ -174,4 +184,4 @@ After the update is applied, if the sessions directory (`workspace.workSessionsD
 - 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
+- The post-update audit is read-only and non-blocking — it surfaces issues, labels the ones this update caused, and never prevents the update itself

package/template/workspace.json.tmpl

@@ -10,7 +10,6 @@
     "subagentContextMaxBytes": 32768,
     "subagentInlineMaxBytes": 8192,
     "greeting": "Welcome back to {{project-name}}.",
-    "releaseMode": "per-repo",
     "sessionModel": "session",
     "tracker": null,
     "forge": { "type": "github" }