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

package/template/_claude/scripts/template-baseline.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// Template baseline: the sha256 of every verbatim-installed file the template
+// last shipped, recorded at <root>/.claude/.template-baseline.json. It is the
+// third input of /workspace-update's three-way classification (workspace vs
+// payload vs baseline), so a file the template changed since the installed
+// version reads as an update to apply in batch — not a local edit to negotiate
+// file by file (gh:183).
+//
+// Shape:
+//   { "templateVersion": "0.21.0",
+//     "files": { ".claude/skills/workspace-update/SKILL.md": "<sha256>", … } }
+// Keys are root-relative posix paths covering the verbatim-installed roots
+// (.claude/**, .mcp.json, .claudeignore). The file is committed with the
+// workspace — every machine that pulls gets the same template files, so it
+// gets the same baseline.
+//
+// Written by `--init` scaffolding (lib/init.mjs), by /workspace-init once the
+// remaining components are installed, and at the end of every /workspace-update
+// (classify-update.mjs --write-baseline). Interactive scaffolding writes it
+// from the template tree (lib/scaffold.mjs).
+//
+// The rule every entry follows: record the hash of the payload's content —
+// what the template last shipped — never the workspace's on-disk bytes. A
+// file the user kept despite a template change therefore keeps the PAYLOAD
+// hash: the next update sees workspace ≠ baseline with payload == baseline
+// and reports the file as a purely local edit (informational, not re-asked
+// per file) until the template touches it again, and a deliberate divergence
+// is never silently adopted as the new baseline. One exception: an unapplied
+// update — the workspace still holds the OLD baseline content while the
+// payload ships something new (the user declined the `updated` batch) — keeps
+// the old entry, so the file re-presents as `updated` next time instead of
+// being filed away as a local edit. The invariant that matters either way: a
+// file the user never touched (workspace == baseline) is never reported as a
+// local edit.
+//
+// All hashes are CRLF-normalized for text files (see hashBytes): a Windows
+// autocrlf checkout stores CRLF where the payload carries LF, and byte-exact
+// hashing would read every such file as locally modified. Files containing
+// NUL bytes hash byte-exact.
+//
+// Not covered: *.test.mjs (the tarball never ships them; a workspace's test
+// files came from a dev checkout and age independently — classify-update
+// reports them as staleTests instead), machine-local files
+// (.claude/settings.local.json, .claude/.active-session.json), and anything
+// under .claude/worktrees/.
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const BASELINE_PATH = '.claude/.template-baseline.json';
+
+// [source name, installed name] pairs for the verbatim-installed roots. The
+// staged payload carries the live names; the template tree stores .claude/ and
+// .mcp.json under the inert names _claude/ and _mcp.json, so scaffold passes
+// the inert pairs.
+export const LIVE_PAIRS = [
+  ['.claude', '.claude'],
+  ['.mcp.json', '.mcp.json'],
+  ['.claudeignore', '.claudeignore'],
+];
+export const INERT_PAIRS = [
+  ['_claude', '.claude'],
+  ['_mcp.json', '.mcp.json'],
+  ['.claudeignore', '.claudeignore'],
+];
+
+// Machine-local or per-workspace files that never belong in the baseline.
+const OWNED_PATHS = new Set([
+  '.claude/settings.local.json',
+  '.claude/.active-session.json',
+  BASELINE_PATH,
+]);
+
+// Entire nested worktrees live under .claude/worktrees/ — never walked.
+const SKIP_DIRS = new Set(['worktrees']);
+
+/**
+ * The content hash used by the baseline and by classification: sha256 with
+ * CRLF normalized to LF for text files, byte-exact for binary (anything
+ * containing a NUL byte — git's own text/binary heuristic). Both the payload
+ * and the workspace side hash through this, so a git autocrlf checkout that
+ * stores CRLF where the payload ships LF classifies as identical instead of
+ * reading every file as locally modified.
+ */
+export function hashBytes(bytes) {
+  let body = bytes;
+  if (!bytes.includes(0)) {
+    // latin1 round-trips bytes 1:1 — safe on text that isn't valid UTF-8 too.
+    body = Buffer.from(bytes.toString('latin1').replace(/\r\n/g, '\n'), 'latin1');
+  }
+  return createHash('sha256').update(body).digest('hex');
+}
+
+function* walkFiles(dir, prefix = '') {
+  let entries;
+  try {
+    entries = readdirSync(dir).sort();
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (prefix === '.claude' && SKIP_DIRS.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);
+    else if (st.isFile()) yield rel;
+  }
+}
+
+/**
+ * Read the baseline at <root>/.claude/.template-baseline.json. Returns
+ * { templateVersion, files } or null when absent (workspaces older than the
+ * baseline's introduction) or unparseable — classification then falls back to
+ * the two-way behavior rather than failing the update.
+ */
+export function readBaseline(root) {
+  const path = join(resolve(root), BASELINE_PATH);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.files !== 'object' || parsed.files === null) {
+      return null;
+    }
+    return { templateVersion: typeof parsed.templateVersion === 'string' ? parsed.templateVersion : null, files: parsed.files };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a baseline from a template source directory (a staged payload with
+ * live names, or the template tree via INERT_PAIRS). `version` overrides the
+ * payload manifest's templateVersion — pass it when the source has no
+ * .manifest.json (the template tree).
+ */
+export function buildBaseline(sourceDir, { pairs = LIVE_PAIRS, version = null } = {}) {
+  const absSource = resolve(sourceDir);
+  const files = {};
+  for (const [sourceName, installedName] of pairs) {
+    const src = join(absSource, sourceName);
+    if (!existsSync(src)) continue;
+    let st;
+    try { st = statSync(src); } catch { continue; }
+    if (st.isFile()) {
+      if (!OWNED_PATHS.has(installedName) && !installedName.endsWith('.test.mjs')) {
+        files[installedName] = hashBytes(readFileSync(src));
+      }
+      continue;
+    }
+    for (const rel of walkFiles(src, installedName)) {
+      if (OWNED_PATHS.has(rel) || rel.endsWith('.test.mjs')) continue;
+      files[rel] = hashBytes(readFileSync(join(absSource, sourceName, rel.slice(installedName.length + 1))));
+    }
+  }
+  let templateVersion = version;
+  if (templateVersion === null) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(absSource, '.manifest.json'), 'utf8'));
+      if (typeof manifest.templateVersion === 'string') templateVersion = manifest.templateVersion;
+    } catch {
+      // No manifest (or unreadable) — caller should pass `version`.
+    }
+  }
+  return { templateVersion, files: Object.fromEntries(Object.keys(files).sort().map((k) => [k, files[k]])) };
+}
+
+/**
+ * Write the baseline for the workspace at `root`. Returns the written object.
+ *
+ * Refuses to write an empty baseline: a missing source directory or one that
+ * yields zero verbatim files throws rather than clobbering an existing good
+ * baseline with `{files:{}}` (which would make the next update classify every
+ * template change as a local edit).
+ *
+ * Before writing, entries carried over from the previous baseline are kept as
+ * they were for unapplied updates: a file whose workspace content still
+ * matches the old baseline while the payload ships something new (a declined
+ * `updated` batch) keeps the OLD entry, so the next update still offers the
+ * change instead of filing the file away as a local edit.
+ */
+export function writeBaseline(root, sourceDir, opts = {}) {
+  const absRoot = resolve(root);
+  const baseline = buildBaseline(sourceDir, opts);
+  if (Object.keys(baseline.files).length === 0) {
+    throw new Error(
+      `No verbatim template files found under ${resolve(sourceDir)} — refusing to write an empty baseline`,
+    );
+  }
+  const previous = readBaseline(absRoot);
+  if (previous) {
+    for (const rel of Object.keys(baseline.files)) {
+      const oldHash = previous.files[rel];
+      if (typeof oldHash !== 'string' || oldHash === baseline.files[rel]) continue;
+      const installed = join(absRoot, rel);
+      if (existsSync(installed) && hashBytes(readFileSync(installed)) === oldHash) {
+        // Unapplied update: the workspace never took the payload's change.
+        baseline.files[rel] = oldHash;
+      }
+    }
+  }
+  const dest = join(absRoot, BASELINE_PATH);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, JSON.stringify(baseline, null, 2) + '\n');
+  return baseline;
+}

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-init/SKILL.md

@@ -126,6 +126,12 @@ Also install these top-level files from the payload:
 
 **Per-repo CLAUDE.md stubs:** For each repo in `workspace.json`, check if `repos/{repo}/CLAUDE.md` exists. If not, ask "Scaffold a CLAUDE.md for {repo}? [Y/n]". If yes, write a blank stub from `.workspace-update/repo-claude.md.tmpl`, substituting `{{repo-name}}` with the repo name. The stub body is comment text only — no workspace-specific content — and its `## Commands` section is where you will add repo-specific test, lint, and build commands.
 
+**Write the template baseline** now that the components are installed, so future `/workspace-update` runs can tell template changes from local edits (three-way classification):
+```bash
+node .claude/scripts/classify-update.mjs --root . --write-baseline --payload .workspace-update
+```
+It hashes the payload's verbatim files — run it before Step 15 deletes the payload.
+
 **Commit:** `git commit -m "feat: install template components from payload"`
 
 ### Step 6: Activate optional rules