@ulysses-ai/create-workspace 0.13.0-beta.2 → 0.14.0-beta.3

package/README.md

@@ -1,5 +1,8 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/ukt-solutions/create-ulysses-workspace/main/docs/assets/logo.png" alt="Ulysses Workspace" width="220">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ukt-solutions/create-ulysses-workspace/main/docs/assets/logo-dark.png">
+    <img src="https://raw.githubusercontent.com/ukt-solutions/create-ulysses-workspace/main/docs/assets/logo.png" alt="Ulysses Workspace" width="220">
+  </picture>
 </p>
 
 # @ulysses-ai/create-workspace
@@ -86,8 +89,8 @@ Four things, in the order you'll touch them:
 A scaffolded workspace with:
 
 - **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
-- **6 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
-- **8 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- **7 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
+- **10 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
 - A **`shared-context/`** memory system with three visibility levels: locked (team truths), root (team-visible ephemerals), user-scoped (personal)
 - Conventions for **multi-repo work sessions** with isolated git worktrees, parallelizable from separate terminals
 
@@ -131,6 +134,15 @@ The eleven [chapters](https://github.com/ukt-solutions/create-ulysses-workspace/
 
 In active pre-1.0 development. Used as dogfood and validated against external workspaces. Conventions and CLI flags are stable; small refinements continue. v1.0 will mark a stability commitment.
 
+## Feedback
+
+Beta testers, early adopters, and anyone curious — feedback of any shape is genuinely wanted.
+
+- **Bugs, rough edges, "this didn't do what I expected"** → [open an issue](https://github.com/ukt-solutions/create-ulysses-workspace/issues/new)
+- **Design questions, "why does it work this way?", ideas for new skills or rules** → [start a discussion](https://github.com/ukt-solutions/create-ulysses-workspace/discussions)
+
+First-hand reports of the scaffold-and-go-for-it experience are the single most useful thing at this stage — especially anything that surprised you, tripped you up, or felt like friction the CLI could have caught.
+
 ## License
 
 MIT

package/package.json

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

package/template/.claude/hooks/_bash-output-advisory.test.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Unit tests for bash-output-advisory.mjs pattern detection.
+// Run: node .claude/hooks/_bash-output-advisory.test.mjs
+import { detectNoisyPattern } from './bash-output-advisory.mjs';
+
+let failed = 0;
+let passed = 0;
+
+function shouldWarn(command, label) {
+  const result = detectNoisyPattern(command);
+  if (result) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${label}\n    command: ${command}\n    expected an advisory, got null`);
+  }
+}
+
+function shouldNotWarn(command, label) {
+  const result = detectNoisyPattern(command);
+  if (!result) {
+    passed++;
+  } else {
+    failed++;
+    console.error(`  FAIL: ${label}\n    command: ${command}\n    expected null, got: ${result}`);
+  }
+}
+
+// === Test runners ===
+shouldWarn('npm test', 'bare npm test');
+shouldWarn('npm run test', 'bare npm run test');
+shouldWarn('yarn test', 'bare yarn test');
+shouldWarn('pnpm test', 'bare pnpm test');
+shouldWarn('bun test', 'bare bun test');
+shouldWarn('cargo test', 'bare cargo test');
+shouldWarn('npm test --coverage', 'npm test with non-scoping flag');
+
+shouldNotWarn('npm test path/to/file.test.mjs', 'npm test with file path');
+shouldNotWarn('npm test src/', 'npm test with directory');
+shouldNotWarn('npm test -- --grep auth', 'npm test with -- args');
+shouldNotWarn('npm test myFile.test.js', 'npm test with bare filename');
+shouldNotWarn('npm test | grep FAIL', 'npm test piped to grep');
+shouldNotWarn('npm test | head -50', 'npm test piped to head');
+shouldNotWarn('cargo test auth_module', 'cargo test with module filter');
+
+// === grep -r ===
+shouldWarn('grep -r "pattern" .', 'bare grep -r');
+shouldWarn('grep --recursive "pattern" src/', 'grep --recursive long form');
+shouldWarn('grep -rn "TODO" .', 'grep -rn (recursive + line numbers)');
+
+shouldNotWarn('grep -r --include="*.js" pattern .', 'grep -r with --include');
+shouldNotWarn('grep -r pattern . --exclude="*.log"', 'grep -r with --exclude');
+shouldNotWarn('grep "pattern" file.txt', 'non-recursive grep');
+
+// === find on broad anchors ===
+shouldWarn('find /', 'find on root');
+shouldWarn('find ~', 'find on home tilde');
+shouldWarn('find $HOME', 'find on $HOME');
+
+shouldNotWarn('find / -name "*.log"', 'find / with -name');
+shouldNotWarn('find ~ -path "*node_modules*" -prune', 'find ~ with -path');
+shouldNotWarn('find . -type f', 'find on cwd');
+shouldNotWarn('find ./src -name "*.ts"', 'find on relative subdir');
+
+// === cat on log-shaped files ===
+shouldWarn('cat server.log', 'cat .log file');
+shouldWarn('cat events.jsonl', 'cat .jsonl file');
+shouldWarn('cat trace.ndjson', 'cat .ndjson file');
+shouldWarn('cat path/to/big.log', 'cat .log in subdir');
+
+shouldNotWarn('cat package.json', 'cat package.json');
+shouldNotWarn('cat README.md', 'cat README');
+shouldNotWarn('cat src/index.ts', 'cat source file');
+shouldNotWarn('cat server.log | tail -50', 'cat .log piped to tail');
+
+// === redirected output (always allowed) ===
+shouldNotWarn('npm test > /tmp/test-output.txt', 'npm test redirected to file');
+shouldNotWarn('grep -r foo . > out.txt', 'grep -r redirected to file');
+shouldNotWarn('find / 2>&1 | tee /tmp/find.txt', 'find piped to tee');
+
+// === unrelated commands ===
+shouldNotWarn('git status', 'git status');
+shouldNotWarn('ls -la', 'ls');
+shouldNotWarn('echo hello', 'echo');
+shouldNotWarn('node --version', 'node version');
+
+console.log(`Passed: ${passed}, Failed: ${failed}`);
+if (failed > 0) process.exit(1);

package/template/.claude/hooks/bash-output-advisory.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// PreToolUse hook — soft advisory for known-noisy bash commands.
+//
+// Does NOT modify the command. Emits a one-line additionalContext nudge so
+// the model can choose to scope the command before executing. Patterns are
+// deliberately narrow — false positives train the model to ignore the hook.
+//
+// Add patterns sparingly. The cost of a missed nudge is one bloated tool
+// result; the cost of crying wolf is a permanently-ignored hook.
+import { fileURLToPath } from 'url';
+import { readStdin, respond } from './_utils.mjs';
+
+// Only run the hook body when invoked directly (not when imported by tests).
+const isEntry = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isEntry) {
+  const input = await readStdin();
+  if (input.tool_name !== 'Bash') {
+    respond();
+    process.exit(0);
+  }
+
+  const command = (input.tool_input?.command || '').trim();
+  if (!command) {
+    respond();
+    process.exit(0);
+  }
+
+  const advisory = detectNoisyPattern(command);
+  if (advisory) {
+    respond(`Bash advisory: ${advisory} Consider scoping the command (path, filter, or pipe to head/tail/grep) before running.`);
+  } else {
+    respond();
+  }
+}
+
+export function detectNoisyPattern(command) {
+  // Already piped to a bounding command — caller knows what they're doing.
+  if (/\|\s*(head|tail|grep|rg|wc|less|more)\b/.test(command)) return null;
+  // Output already redirected to a file — not consuming context.
+  if (/(?:^|\s)(?:>|>>|\|\s*tee)\s+\S/.test(command)) return null;
+
+  // 1. Bare test runners with no scope.
+  // Matches `npm test`, `npm run test`, `yarn test`, `pnpm test`, `bun test`, `cargo test`
+  // followed by nothing, or only by recognized flags that don't constrain output.
+  const testRunner = /^(?:npm(?:\s+run)?|yarn|pnpm|bun)\s+test\b(.*)$/.exec(command)
+    || /^cargo\s+test\b(.*)$/.exec(command);
+  if (testRunner) {
+    const tail = testRunner[1];
+    // A scope is any non-flag positional arg (path, filename, or test-name filter).
+    // Flags that don't constrain output (--coverage, --watch, --verbose, --bail) don't count.
+    const hasScope = tail.split(/\s+/).some(arg => arg && !arg.startsWith('-'));
+    if (!hasScope) {
+      return 'Bare test-runner invocation will produce all-tests output.';
+    }
+  }
+
+  // 2. Recursive grep without an include filter.
+  // Note: ripgrep (`rg`) is recursive by default and respects .gitignore, so a
+  // bare `rg pattern .` is usually fine. We only flag classic `grep -r`.
+  if (/^grep\s+(?:-\w*r\w*|-r\b|--recursive\b)/.test(command)
+      && !/--include[=\s]|--exclude[=\s]/.test(command)) {
+    return 'Recursive grep without --include can return thousands of matches.';
+  }
+
+  // 3. find on a home/root anchor without a name/path constraint.
+  if (/^find\s+(?:\/|~|\$HOME|\$\{HOME\})(?:\s|$)/.test(command)
+      && !/-(?:name|iname|path|ipath|regex)\b/.test(command)) {
+    return 'find on a broad anchor without -name/-path enumerates the whole tree.';
+  }
+
+  // 4. cat on log-shaped files.
+  if (/^cat\s+\S*\.(?:log|jsonl|ndjson)\b/.test(command)) {
+    return 'Log-shaped files are often large.';
+  }
+
+  return null;
+}

package/template/.claude/hooks/version-freshness-check.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// SessionStart hook — refresh the template freshness banner if cache is stale.
+// Gated on workspace.versionCheck.ambient (default true; will flip to false at v1.0).
+// Always silent: surfaces only via the local-only-template-freshness.md banner,
+// which CLAUDE.md includes via @ syntax. Never blocks session start.
+import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
+import { refreshIfStale } from '../lib/freshness.mjs';
+
+const TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+const root = getWorkspaceRoot(import.meta.url);
+const config = readJSON(`${root}/workspace.json`);
+
+// Default lifecycle: ambient=true during beta, missing-block fallback flips
+// to false at v1.0 by editing this default.
+const AMBIENT_DEFAULT = true;
+const ambient = config?.workspace?.versionCheck?.ambient ?? AMBIENT_DEFAULT;
+
+if (!ambient) {
+  respond();
+  process.exit(0);
+}
+
+try {
+  await refreshIfStale({ workspaceRoot: root, ttlMs: TTL_MS });
+} catch {
+  // Hooks must never block session start. The banner reflects last-known
+  // state; the user sees stale but never broken.
+}
+respond();

package/template/.claude/lib/freshness.mjs

@@ -0,0 +1,75 @@
+import './require-node.mjs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { compareVersions, getLatestVersion, 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.
+ *
+ * Returns:
+ *   { status: 'outdated', current, latest, checkedAt }
+ *   { status: 'current',  current, latest, checkedAt }
+ *   { status: 'unknown',  current, latest: null, checkedAt: null }
+ *   { skipped: 'uninitialized' }
+ *
+ * Pure I/O is parameterized via fetchFn / nowFn for testability.
+ */
+export async function refreshIfStale({
+  workspaceRoot,
+  ttlMs,
+  fetchFn = fetch,
+  nowFn = () => new Date(),
+}) {
+  const wsConfigPath = join(workspaceRoot, 'workspace.json');
+  let wsConfig;
+  try {
+    wsConfig = JSON.parse(readFileSync(wsConfigPath, 'utf-8'));
+  } catch {
+    return { skipped: 'no-workspace-json' };
+  }
+  const current = wsConfig?.workspace?.templateVersion;
+  if (!current || current === '0.0.0') {
+    return { skipped: 'uninitialized' };
+  }
+
+  const scratchpadDir = wsConfig?.workspace?.scratchpadDir || 'workspace-scratchpad';
+  const cachePath = join(workspaceRoot, scratchpadDir, CACHE_FILENAME);
+  const bannerPath = join(workspaceRoot, BANNER_FILENAME);
+
+  let cache = readCache(cachePath);
+  const now = nowFn();
+  const cacheAgeMs = cache?.checkedAt ? now.getTime() - new Date(cache.checkedAt).getTime() : Infinity;
+  const stale = cacheAgeMs > ttlMs;
+
+  if (stale) {
+    const fresh = await getLatestVersion({ fetchFn });
+    if (fresh.version) {
+      cache = { latestVersion: fresh.version, checkedAt: now.toISOString() };
+      writeCache(cachePath, cache);
+    }
+    // On fetch error, keep whatever cache we already had (could be null).
+  }
+
+  if (!cache) {
+    // No cache and offline (or fetch error). Leave banner alone — we have no
+    // basis to write or delete it.
+    return { status: 'unknown', current, latest: null, checkedAt: null };
+  }
+
+  const latest = cache.latestVersion;
+  const cmp = compareVersions(current, latest);
+  if (cmp < 0) {
+    writeFileSync(
+      bannerPath,
+      `## Template update available\n\nYour workspace is on template v${current}; latest on npm is v${latest}.\nRun \`/maintenance\` for details or \`npx @ulysses-ai/create-workspace --upgrade\` to apply.\n`,
+    );
+    return { status: 'outdated', current, latest, checkedAt: cache.checkedAt };
+  } else {
+    if (existsSync(bannerPath)) unlinkSync(bannerPath);
+    return { status: 'current', current, latest, checkedAt: cache.checkedAt };
+  }
+}

package/template/.claude/lib/freshness.test.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// Unit tests for freshness.mjs
+// Run: node template/.claude/lib/freshness.test.mjs
+import { refreshIfStale } from './freshness.mjs';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+let failed = 0;
+let passed = 0;
+function assertEq(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a === e) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${msg}\n    expected: ${e}\n    actual:   ${a}`);
+  }
+}
+
+function setupWorkspace({ templateVersion, ambientBlock = '', cache = null } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'freshness-test-'));
+  const wsConfig = {
+    workspace: {
+      name: 'test',
+      scratchpadDir: 'workspace-scratchpad',
+      templateVersion,
+      ...(ambientBlock ? { versionCheck: { ambient: ambientBlock === 'on' } } : {}),
+    },
+    repos: {},
+  };
+  writeFileSync(join(root, 'workspace.json'), JSON.stringify(wsConfig));
+  if (cache) {
+    const cacheDir = join(root, 'workspace-scratchpad');
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(join(cacheDir, '.version-check.json'), JSON.stringify(cache));
+  }
+  return root;
+}
+
+function fakeFetchOk(version) {
+  return async () => ({ ok: true, json: async () => ({ version }) });
+}
+
+const fakeFetchErr = async () => { throw new Error('offline'); };
+
+console.log('# refreshIfStale');
+
+// Outdated workspace, fresh fetch, banner written
+{
+  const root = setupWorkspace({ templateVersion: '0.13.0' });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.status, 'outdated', 'outdated status');
+  assertEq(result.current, '0.13.0', 'current version reported');
+  assertEq(result.latest, '0.14.0', 'latest version reported');
+  assertEq(existsSync(join(root, 'local-only-template-freshness.md')), true, 'banner file created');
+  const banner = readFileSync(join(root, 'local-only-template-freshness.md'), 'utf-8');
+  assertEq(banner.includes('v0.13.0'), true, 'banner mentions current');
+  assertEq(banner.includes('v0.14.0'), true, 'banner mentions latest');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Up-to-date workspace, banner deleted if present
+{
+  const root = setupWorkspace({ templateVersion: '0.14.0' });
+  // Pre-existing banner from when it was outdated
+  writeFileSync(join(root, 'local-only-template-freshness.md'), '## stale banner');
+  await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(existsSync(join(root, 'local-only-template-freshness.md')), false, 'banner deleted when current');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Fresh cache, no fetch happens
+{
+  const root = setupWorkspace({
+    templateVersion: '0.13.0',
+    cache: { latestVersion: '0.14.0', checkedAt: '2026-04-24T20:00:00Z' },
+  });
+  let fetchCalled = false;
+  await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: async () => { fetchCalled = true; return { ok: true, json: async () => ({ version: '0.14.0' }) }; },
+    nowFn: () => new Date('2026-04-24T21:00:00Z'), // 1h after cache
+  });
+  assertEq(fetchCalled, false, 'fresh cache skips fetch');
+  assertEq(existsSync(join(root, 'local-only-template-freshness.md')), true, 'banner still written from cache');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Stale cache triggers fetch
+{
+  const root = setupWorkspace({
+    templateVersion: '0.13.0',
+    cache: { latestVersion: '0.13.5', checkedAt: '2026-04-20T20:00:00Z' },
+  });
+  let fetchCalled = false;
+  await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: async () => { fetchCalled = true; return { ok: true, json: async () => ({ version: '0.14.0' }) }; },
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(fetchCalled, true, 'stale cache triggers fetch');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Stale cache + offline: keep cached value, return unknown only if no cache
+{
+  const root = setupWorkspace({
+    templateVersion: '0.13.0',
+    cache: { latestVersion: '0.13.9', checkedAt: '2026-04-20T20:00:00Z' },
+  });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchErr,
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.status, 'outdated', 'falls back to cached value when offline');
+  assertEq(result.latest, '0.13.9', 'cached value used');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// No cache + offline: status unknown
+{
+  const root = setupWorkspace({ templateVersion: '0.13.0' });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchErr,
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.status, 'unknown', 'unknown when no cache and offline');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// Uninitialized workspace (templateVersion missing)
+{
+  const root = mkdtempSync(join(tmpdir(), 'freshness-test-'));
+  writeFileSync(join(root, 'workspace.json'), JSON.stringify({ workspace: {}, repos: {} }));
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.skipped, 'uninitialized', 'uninitialized workspace skipped');
+  rmSync(root, { recursive: true, force: true });
+}
+
+// templateVersion 0.0.0 treated as uninitialized
+{
+  const root = setupWorkspace({ templateVersion: '0.0.0' });
+  const result = await refreshIfStale({
+    workspaceRoot: root,
+    ttlMs: 86400000,
+    fetchFn: fakeFetchOk('0.14.0'),
+    nowFn: () => new Date('2026-04-24T21:00:00Z'),
+  });
+  assertEq(result.skipped, 'uninitialized', '0.0.0 treated as uninitialized');
+  rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

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

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