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

package/lib/upgrade.mjs

@@ -1,8 +1,26 @@
 // lib/upgrade.mjs
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { spawnSync } from 'child_process';
 import { stagePayload } from './payload.mjs';
 
+// .workspace-update/ is a transient staging area and is gitignored from
+// v0.19.0 on — but workspaces upgraded from older templates may still track
+// it from a previous run. A tracked payload gets committed, shared with
+// teammates, and confuses /workspace-update, so surface it loudly.
+function warnIfPayloadTracked(targetDir) {
+  const r = spawnSync('git', ['ls-files', '.workspace-update'], {
+    cwd: targetDir,
+    encoding: 'utf-8',
+  });
+  // Not a git repo (or git unavailable) — nothing can be tracked.
+  if (r.status !== 0) return;
+  const tracked = (r.stdout || '').split('\n').filter(Boolean);
+  if (tracked.length === 0) return;
+  console.error(`  Warning: .workspace-update/ is tracked by git (${tracked.length} file(s)) — it is a transient staging area.`);
+  console.error(`  Untrack it and commit:\n    git rm -r --cached .workspace-update\n    git commit -m "chore: untrack .workspace-update payload"\n`);
+}
+
 export async function upgradeWorkspace(targetDir) {
   const workspaceJsonPath = join(targetDir, 'workspace.json');
 
@@ -24,6 +42,8 @@ export async function upgradeWorkspace(targetDir) {
     process.exit(1);
   }
 
+  warnIfPayloadTracked(targetDir);
+
   const fromVersion = config.workspace?.templateVersion || 'unknown';
 
   // Stage payload

package/lib/upgrade.test.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Unit tests for upgrade.mjs
+// Run: node lib/upgrade.test.mjs
+//
+// Covers the tracked-payload warning: .workspace-update/ is gitignored from
+// v0.19.0, but a workspace upgraded from an older template may still carry a
+// tracked payload from a previous run — --upgrade must say so.
+import { upgradeWorkspace } from './upgrade.mjs';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { execSync, spawnSync } from 'child_process';
+
+let failed = 0;
+let passed = 0;
+function check(label, ok) {
+  if (ok) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${label}`);
+  }
+}
+
+function captureConsole(fn) {
+  const out = { log: [], error: [] };
+  const origLog = console.log;
+  const origError = console.error;
+  console.log = (...a) => { out.log.push(a.join(' ')); };
+  console.error = (...a) => { out.error.push(a.join(' ')); };
+  try {
+    return { result: fn(), out };
+  } finally {
+    console.log = origLog;
+    console.error = origError;
+  }
+}
+
+function buildWorkspace() {
+  const root = mkdtempSync(join(tmpdir(), 'upgrade-test-'));
+  execSync('git init -q -b main', { cwd: root, stdio: 'pipe' });
+  execSync('git config user.email test@example.com', { cwd: root, stdio: 'pipe' });
+  execSync('git config user.name Test', { cwd: root, stdio: 'pipe' });
+  writeFileSync(join(root, 'workspace.json'), JSON.stringify({
+    workspace: { name: 'demo', initialized: true, templateVersion: '0.15.0' },
+    repos: {},
+  }, null, 2) + '\n');
+  execSync('git add workspace.json', { cwd: root, stdio: 'pipe' });
+  execSync('git commit -q -m init', { cwd: root, stdio: 'pipe' });
+  return root;
+}
+
+function lsFilesPayload(root) {
+  return spawnSync('git', ['ls-files', '.workspace-update'], {
+    cwd: root,
+    encoding: 'utf-8',
+  }).stdout.split('\n').filter(Boolean);
+}
+
+console.log('# upgrade');
+
+// 1. Clean workspace: payload staged, no tracked-payload warning, and the
+//    freshly staged payload is not tracked.
+{
+  const root = buildWorkspace();
+  try {
+    const { out } = captureConsole(() => upgradeWorkspace(root));
+    const stderr = out.error.join('\n');
+    check('no tracked-payload warning on a clean workspace',
+      !stderr.includes('git rm -r --cached'));
+    check('payload staged', existsSync(join(root, '.workspace-update', '.manifest.json')));
+    check('freshly staged payload is not tracked', lsFilesPayload(root).length === 0);
+    check('staging reported', out.log.join('\n').includes('Staged template payload'));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 2. Workspace tracking .workspace-update/ from a pre-v0.19 upgrade: the
+//    warning fires and names the untrack command.
+{
+  const root = buildWorkspace();
+  try {
+    // Simulate the old behavior: a payload committed tracked.
+    const payload = join(root, '.workspace-update');
+    mkdirSync(payload, { recursive: true });
+    writeFileSync(join(payload, '.manifest.json'), '{"action":"upgrade"}\n');
+    execSync('git add -f .workspace-update', { cwd: root, stdio: 'pipe' });
+    execSync('git commit -q -m "track payload"', { cwd: root, stdio: 'pipe' });
+    check('fixture really tracks the payload', lsFilesPayload(root).length > 0);
+
+    const { out } = captureConsole(() => upgradeWorkspace(root));
+    const stderr = out.error.join('\n');
+    check('tracked-payload warning fires', stderr.includes('.workspace-update/') && stderr.includes('tracked by git'));
+    check('warning names the untrack command', stderr.includes('git rm -r --cached .workspace-update'));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// 3. Not a git repo at all: staging still works, warning stays silent.
+{
+  const root = mkdtempSync(join(tmpdir(), 'upgrade-nogit-'));
+  try {
+    writeFileSync(join(root, 'workspace.json'), JSON.stringify({
+      workspace: { name: 'demo', initialized: true, templateVersion: '0.15.0' },
+      repos: {},
+    }, null, 2) + '\n');
+    const { out } = captureConsole(() => upgradeWorkspace(root));
+    check('no warning outside a git repo', !out.error.join('\n').includes('tracked by git'));
+    check('payload staged outside a git repo', existsSync(join(root, '.workspace-update', '.manifest.json')));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+if (failed > 0) {
+  console.error(`${failed} check(s) failed, ${passed} passed`);
+  process.exit(1);
+}
+console.log(`${passed} checks passed`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.19.0-beta.0",
+  "version": "0.20.0-beta.0",
   "description": "A workspace convention for Claude Code: sessions, handoffs, and shared context as files in git",
   "keywords": [
     "claude",
@@ -18,7 +18,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ukt-solutions/create-ulysses-workspace.git"
+    "url": "git+https://github.com/ukt-solutions/create-ulysses-workspace.git"
   },
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
     "node": ">=20.9.0"
   },
   "bin": {
-    "create-workspace": "./bin/create.mjs"
+    "create-workspace": "bin/create.mjs"
   },
   "files": [
     "bin/",

package/template/CLAUDE.md.tmpl

@@ -33,6 +33,9 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - `/workspace-update` — apply template updates (runs maintenance before/after)
 - `/setup-tracker` — wire this workspace to an issue tracker (GitHub Issues shipped; others pluggable)
 - `/maintenance [audit|cleanup]` — workspace health checks 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
 - `/build-docs-site` — build a comprehensive Docusaurus documentation site for a project
 
 ## Compact Instructions

package/template/_claude/lib/freshness.mjs

@@ -1,21 +1,29 @@
 import './require-node.mjs';
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
-import { compareVersions, getLatestVersion, readCache, writeCache } from './registry-check.mjs';
+import { compareVersions, getLatestVersion, pickComparisonVersion, readCache, writeCache } from './registry-check.mjs';
 
 const BANNER_FILENAME = 'local-only-template-freshness.md';
 const CACHE_FILENAME = '.version-check.json';
 
 /**
  * Refresh the version cache if stale, then write or delete the banner file
- * based on a comparison of workspace.templateVersion to the latest npm version.
+ * based on a comparison of workspace.templateVersion to the npm dist-tag
+ * matching its release channel (see pickComparisonVersion).
+ *
+ * The cache stores the raw dist-tags rather than the chosen version, so a
+ * channel switch between cache write and read (e.g. an upgrade from a beta
+ * to a stable release inside the TTL) still picks the right tag.
  *
  * Returns:
  *   { status: 'outdated', current, latest, checkedAt }
- *   { status: 'current',  current, latest, checkedAt }
+ *   { status: 'current',  current, latest, prerelease, checkedAt }
  *   { status: 'unknown',  current, latest: null, checkedAt: null }
  *   { skipped: 'uninitialized' }
  *
+ * `prerelease` on a current workspace is a newer `beta` dist-tag, offered
+ * as information only — it never marks the install stale.
+ *
  * Pure I/O is parameterized via fetchFn / nowFn for testability.
  */
 export async function refreshIfStale({
@@ -46,9 +54,9 @@ export async function refreshIfStale({
   const stale = cacheAgeMs > ttlMs;
 
   if (stale) {
-    const fresh = await getLatestVersion({ fetchFn });
+    const fresh = await getLatestVersion({ current, fetchFn });
     if (fresh.version) {
-      cache = { latestVersion: fresh.version, checkedAt: now.toISOString() };
+      cache = { tags: fresh.tags, checkedAt: now.toISOString() };
       writeCache(cachePath, cache);
     }
     // On fetch error, keep whatever cache we already had (could be null).
@@ -60,7 +68,12 @@ export async function refreshIfStale({
     return { status: 'unknown', current, latest: null, checkedAt: null };
   }
 
-  const latest = cache.latestVersion;
+  const { version: latest, prerelease } = pickComparisonVersion(current, cache.tags);
+  if (!latest) {
+    // Cached tags carry nothing comparable for this channel. Refuse to
+    // guess rather than compare against the wrong tag.
+    return { status: 'unknown', current, latest: null, checkedAt: cache.checkedAt };
+  }
   const cmp = compareVersions(current, latest);
   if (cmp < 0) {
     writeFileSync(
@@ -70,6 +83,6 @@ export async function refreshIfStale({
     return { status: 'outdated', current, latest, checkedAt: cache.checkedAt };
   } else {
     if (existsSync(bannerPath)) unlinkSync(bannerPath);
-    return { status: 'current', current, latest, checkedAt: cache.checkedAt };
+    return { status: 'current', current, latest, prerelease, checkedAt: cache.checkedAt };
   }
 }

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

@@ -51,45 +51,111 @@ export function compareVersions(a, b) {
   return 0;
 }
 
-const REGISTRY_URL = 'https://registry.npmjs.org/@ulysses-ai/create-workspace/latest';
+const DIST_TAGS_URL = 'https://registry.npmjs.org/-/package/@ulysses-ai/create-workspace/dist-tags';
 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.
+ * Which release channel an installed version rides: `stable` for a plain
+ * `x.y.z`, otherwise the first pre-release identifier (`0.19.0-beta.3` →
+ * `beta`). Returns null when the string isn't a version this scaffolder
+ * publishes.
+ */
+export function channelOf(version) {
+  if (typeof version !== 'string') return null;
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(version);
+  if (!match) return null;
+  return match[4] ? match[4].split('.')[0] : 'stable';
+}
+
+/**
+ * Pick the registry version an installed version should compare against,
+ * given the package's dist-tags.
+ *
+ * A pre-release install tracks the highest semver among `latest` and its
+ * own channel's tag, so a lagging `latest` (which has sat behind `beta`
+ * for whole release cycles) never masks a newer build on the channel the
+ * workspace actually rides. A stable install compares against `latest`
+ * alone; when the `beta` tag outruns `latest`, that version is returned
+ * separately as an available pre-release, so callers can surface it
+ * without calling the install stale.
+ *
+ * Returns { version, channel, prerelease } — `version` is null when no
+ * usable tag is present.
+ */
+export function pickComparisonVersion(current, tags) {
+  const channel = channelOf(current) || 'stable';
+  const candidates = [];
+  if (typeof tags?.latest === 'string') candidates.push(tags.latest);
+  if (channel !== 'stable' && typeof tags?.[channel] === 'string') candidates.push(tags[channel]);
+  let version = null;
+  for (const candidate of candidates) {
+    if (version === null || compareVersions(candidate, version) > 0) version = candidate;
+  }
+  let prerelease = null;
+  if (
+    channel === 'stable' &&
+    typeof tags?.latest === 'string' &&
+    typeof tags?.beta === 'string' &&
+    compareVersions(tags.beta, tags.latest) > 0
+  ) {
+    prerelease = tags.beta;
+  }
+  return { version, channel, prerelease };
+}
+
+/**
+ * Fetch the scaffolder's dist-tags from the npm registry and pick the
+ * version to compare the installed `current` version against.
+ * Returns { version, channel, tags, prerelease, error } — `error` is null
+ * exactly when `version` is non-null, and the other fields are null on
+ * failure. `tags` is the dist-tag map as published, `channel` is the
+ * installed version's channel, and `prerelease` is the `beta` build when
+ * one outruns `latest` from a stable install.
  *
  * Caller injects fetchFn for testing. Default uses global fetch (Node 18+).
  */
-export async function getLatestVersion({ fetchFn = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+export async function getLatestVersion({ current = null, fetchFn = fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const empty = { version: null, channel: null, tags: null, prerelease: null };
   try {
-    const res = await fetchFn(REGISTRY_URL, { signal: controller.signal });
+    const res = await fetchFn(DIST_TAGS_URL, { signal: controller.signal });
     if (!res.ok) {
-      return { version: null, error: `registry returned ${res.status} ${res.statusText || ''}`.trim() };
+      return { ...empty, 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' };
+    const tags = {};
+    if (body && typeof body === 'object' && !Array.isArray(body)) {
+      for (const [tag, value] of Object.entries(body)) {
+        if (typeof value === 'string') tags[tag] = value;
+      }
+    }
+    const picked = pickComparisonVersion(current, tags);
+    if (!picked.version) {
+      return { ...empty, error: 'registry response missing dist-tags' };
     }
-    return { version: body.version, error: null };
+    return { version: picked.version, channel: picked.channel, tags, prerelease: picked.prerelease, error: null };
   } catch (err) {
-    return { version: null, error: err?.message || String(err) };
+    return { ...empty, 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".
+ * Read the version cache file. Returns the parsed object if it has a
+ * `tags` object holding at least one string dist-tag; otherwise null.
+ * Treats missing file, malformed JSON, and shape mismatches (including
+ * caches written before dist-tag support, which had a bare `latestVersion`)
+ * all as "no cache" — the next fetch rewrites the file in the new shape.
  */
 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;
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return null;
+    if (!data.tags || typeof data.tags !== 'object' || Array.isArray(data.tags)) return null;
+    if (!Object.values(data.tags).some((v) => typeof v === 'string')) return null;
     return data;
   } catch {
     return null;

package/template/_claude/scripts/chat-record.mjs

@@ -21,8 +21,8 @@
 //   node chat-record.mjs --root <dir> --read  <chat-name>
 //   node chat-record.mjs --root <dir> --reconcile --session-id <id> --name <n>
 //   node chat-record.mjs --root <dir> --whoami
-//   node chat-record.mjs --root <dir> --add-task    --chat <n> --work-item <id> --branch <b> [--repo <r>]
-//   node chat-record.mjs --root <dir> --remove-task --chat <n> --work-item <id> [--repo <r>]
+//   node chat-record.mjs --root <dir> --add-task    --chat <n> --branch <b> [--repo <r>] [--work-item <id>]
+//   node chat-record.mjs --root <dir> --remove-task --chat <n> (--work-item <id> | --branch <b>) [--repo <r>]
 //
 // --add-task / --remove-task report `action`: "added" | "updated" for
 // --add-task, "removed" | "unchanged" for --remove-task. They also keep the
@@ -191,20 +191,25 @@ function resolveChatName(root, { sessionId, registryName = null } = {}) {
 }
 
 
-// A task is a tracker issue plus a branch plus the repo it lands in. It is
-// created on demand and disappears when it merges — nothing about it is
-// durable except the issue and the commits, so the record holds only the
-// pointer, never a copy of the issue.
+// A task is a branch plus the repo it lands in, plus the tracker issue when
+// the workspace has one. It is created on demand and disappears when it
+// merges — nothing about it is durable except the issue and the commits, so
+// the record holds only the pointer, never a copy of the issue.
 //
 // Identity is workItem + repo: the same issue can legitimately be open against
 // two repos in a multi-repo task, and re-recording the same one must update
-// rather than duplicate. /start-work is not always run exactly once.
-function addTask(root, chatName, { workItem, branch, repo = null } = {}) {
-  if (!workItem) throw new Error('addTask: workItem is required');
+// rather than duplicate. /start-work is not always run exactly once. A task
+// recorded without a tracker (gh:173) carries `workItem: null` and is keyed
+// by branch + repo instead — the branch is the only identity it has — so
+// both add and remove take the branch for those entries.
+function addTask(root, chatName, { workItem = null, branch, repo = null } = {}) {
   if (!branch) throw new Error('addTask: branch is required');
   const rec = readRecord(root, chatName);
   if (!rec) throw new Error(`addTask: no chat record for "${chatName}"`);
-  const i = rec.tasks.findIndex((t) => t.workItem === workItem && (t.repo ?? null) === repo);
+  const i = rec.tasks.findIndex(
+    (t) => (t.workItem ?? null) === workItem && (t.repo ?? null) === repo
+      && (workItem !== null || t.branch === branch),
+  );
   const task = { workItem, branch, repo };
   if (i >= 0) rec.tasks[i] = task;
   else rec.tasks.push(task);
@@ -212,12 +217,15 @@ function addTask(root, chatName, { workItem, branch, repo = null } = {}) {
   return { record: rec, action: i >= 0 ? 'updated' : 'added', updated: i >= 0 };
 }
 
-function removeTask(root, chatName, { workItem, repo = null } = {}) {
-  if (!workItem) throw new Error('removeTask: workItem is required');
+function removeTask(root, chatName, { workItem = null, branch = null, repo = null } = {}) {
+  if (workItem === null && !branch) throw new Error('removeTask: workItem or branch is required');
   const rec = readRecord(root, chatName);
   if (!rec) throw new Error(`removeTask: no chat record for "${chatName}"`);
   const before = rec.tasks.length;
-  rec.tasks = rec.tasks.filter((t) => !(t.workItem === workItem && (t.repo ?? null) === repo));
+  rec.tasks = rec.tasks.filter(
+    (t) => !((t.workItem ?? null) === workItem && (t.repo ?? null) === repo
+      && (workItem !== null || t.branch === branch)),
+  );
   writeRecord(root, rec);
   return { record: rec, action: before - rec.tasks.length > 0 ? 'removed' : 'unchanged', removed: before - rec.tasks.length };
 }
@@ -268,11 +276,11 @@ function parseArgs(argv) {
   if (args.mode === 'reconcile' && (!args.sessionId || !args.name)) {
     throw new Error('--reconcile requires --session-id and --name');
   }
-  if (args.mode === 'add-task' && (!args.chat || !args.workItem || !args.branch)) {
-    throw new Error('--add-task requires --chat, --work-item and --branch');
+  if (args.mode === 'add-task' && (!args.chat || !args.branch)) {
+    throw new Error('--add-task requires --chat and --branch (--work-item is optional — omitted without a tracker)');
   }
-  if (args.mode === 'remove-task' && (!args.chat || !args.workItem)) {
-    throw new Error('--remove-task requires --chat and --work-item');
+  if (args.mode === 'remove-task' && (!args.chat || (!args.workItem && !args.branch))) {
+    throw new Error('--remove-task requires --chat and --work-item or --branch');
   }
   return args;
 }
@@ -292,9 +300,9 @@ function main() {
   if (args.mode === 'list') out = listRecords(args.root);
   else if (args.mode === 'read') out = readRecord(args.root, args.chat);
   else if (args.mode === 'add-task') {
-    out = addTask(args.root, args.chat, { workItem: args.workItem, branch: args.branch, repo: args.repo });
+    out = addTask(args.root, args.chat, { workItem: args.workItem ?? null, branch: args.branch, repo: args.repo });
   } else if (args.mode === 'remove-task') {
-    out = removeTask(args.root, args.chat, { workItem: args.workItem, repo: args.repo });
+    out = removeTask(args.root, args.chat, { workItem: args.workItem ?? null, branch: args.branch, repo: args.repo });
   } else out = reconcile(args.root, { sessionId: args.sessionId, name: args.name });
   process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
 }

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

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Classify an upgrade payload's files against the workspace so /workspace-update
+// can batch the safe cases and ask only where a decision is needed.
+//
+// Usage:
+//   node classify-update.mjs [--root <dir>] [--payload <dir>]
+//
+// --root    workspace root; defaults to the current working directory (never
+//           derived from this script's location — the upgrade payload runs
+//           this file from <workspace>/.workspace-update/.claude/scripts/)
+// --payload the staged payload; defaults to <root>/.workspace-update
+//
+// Prints JSON: { "new": [...], "identical": [...], "differs": [...] }
+//   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
+//
+// Only verbatim-installed files are classified: everything under .claude/,
+// plus .mcp.json and .claudeignore. The payload's templates (*.tmpl, which
+// install with {{project-name}} substitution), _gitignore (merged line-by-line
+// into the workspace's .gitignore), and .manifest.json (payload metadata) are
+// handled by their own steps in /workspace-update and are excluded here.
+
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  realpathSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+function parseArgs(argv) {
+  const args = { root: process.cwd(), payload: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--root') args.root = argv[++i];
+    else if (a === '--payload') args.payload = argv[++i];
+    else throw new Error(`Unknown arg: ${a}`);
+  }
+  return args;
+}
+
+// Payload-relative paths that install verbatim at the same relative path.
+// Everything else in the payload is a template or metadata handled elsewhere.
+const VERBATIM_ROOTS = ['.claude', '.mcp.json', '.claudeignore'];
+
+function isClassified(payloadRelPath) {
+  const first = payloadRelPath.split('/')[0];
+  return VERBATIM_ROOTS.includes(first);
+}
+
+function* walkFiles(dir, prefix = '') {
+  let entries;
+  try {
+    entries = readdirSync(dir).sort();
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    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;
+  }
+}
+
+export function classifyUpdate({ root, payload }) {
+  const absRoot = resolve(root);
+  const absPayload = resolve(payload ?? join(absRoot, '.workspace-update'));
+  if (!existsSync(absPayload)) {
+    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 installed = join(absRoot, rel);
+    if (!existsSync(installed)) {
+      result.new.push(rel);
+      continue;
+    }
+    const payloadBytes = readFileSync(join(absPayload, rel));
+    const installedBytes = readFileSync(installed);
+    if (Buffer.compare(payloadBytes, installedBytes) === 0) {
+      result.identical.push(rel);
+    } else {
+      result.differs.push(rel);
+    }
+  }
+  return result;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const result = classifyUpdate({ root: args.root, payload: args.payload });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`classify-update: ${err.message}\n`);
+    process.exit(1);
+  }
+}

package/template/_claude/scripts/cleanup-work-session.mjs

@@ -146,9 +146,11 @@ if (repos.length === 0) {
       if (found.length > 0) {
         repos = found;
         discovered = true;
+        // Informational wording: discovery is a normal success path here
+        // (gh:172) — not a warning about the tracker.
         skipped.push({
           step: 'discovery',
-          reason: `Tracker missing repos; discovered ${found.length} from ${nestedReposDir}: ${found.join(', ')}`,
+          reason: `repos discovered from disk: ${found.length} (${found.join(', ')})`,
         });
       }
     } catch (err) {
@@ -209,7 +211,7 @@ if (!branch && existsSync(wsWorktree)) {
   const res = git(wsWorktree, ['rev-parse', '--abbrev-ref', 'HEAD']);
   if (res.ok && res.out.trim() !== '' && res.out.trim() !== 'HEAD') {
     branch = res.out.trim();
-    skipped.push({ step: 'discovery', reason: `Tracker missing branch; discovered from worktree: ${branch}` });
+    skipped.push({ step: 'discovery', reason: `branch discovered from the worktree: ${branch}` });
   }
 }