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

package/lib/init.mjs

@@ -20,7 +20,10 @@ export async function initWorkspace(targetDir) {
   const { toVersion, payloadDir } = stagePayload(targetDir, { action: 'init' });
   console.log(`  Staged template payload (v${toVersion})`);
 
-  // Install only the bootstrap skills needed to complete initialization
+  // Install only the bootstrap skills needed to complete initialization.
+  // The payload keeps live names (.claude/, .mcp.json) — stagePayload()
+  // maps them back from the template's inert names so the staged layout
+  // stays readable by skills already installed in the workspace.
   const bootstrapSkills = ['workspace-init', 'workspace-update'];
   const payloadSkills = join(payloadDir, '.claude', 'skills');
   const targetSkills = join(targetDir, '.claude', 'skills');

package/lib/payload.mjs

@@ -1,5 +1,5 @@
 // lib/payload.mjs
-import { existsSync, cpSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { existsSync, cpSync, rmSync, mkdirSync, writeFileSync, readFileSync, renameSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -22,6 +22,23 @@ export function stagePayload(targetDir, { action, fromVersion = null }) {
   // Copy template to payload directory
   cpSync(TEMPLATE_DIR, payloadDir, { recursive: true });
 
+  // The template stores .claude/ and .mcp.json under the inert names
+  // _claude/ and _mcp.json (Claude Code protects the live names from
+  // headless edits). The staged payload is an on-disk format shared with
+  // the /workspace-update skill ALREADY INSTALLED in the workspace, which
+  // reads .workspace-update/.claude/... — so it must keep the live names
+  // exactly as older package versions staged them. _gitignore stays inert:
+  // the skills have always merged it under that name.
+  for (const [from, to] of [
+    ['_claude', '.claude'],
+    ['_mcp.json', '.mcp.json'],
+  ]) {
+    const src = join(payloadDir, from);
+    if (existsSync(src)) {
+      renameSync(src, join(payloadDir, to));
+    }
+  }
+
   // Write manifest
   const manifest = {
     action,

package/lib/payload.test.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Unit tests for payload.mjs
+// Run: node lib/payload.test.mjs
+//
+// The staged .workspace-update/ payload is an on-disk format shared with
+// the /workspace-update skill already installed in existing workspaces,
+// which reads .workspace-update/.claude/... and .workspace-update/.mcp.json.
+// These tests pin that layout even though template/ itself stores the
+// protected paths under the inert names _claude/ and _mcp.json.
+import { stagePayload, cleanPayload } from './payload.mjs';
+import { mkdtempSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+let failed = 0;
+let passed = 0;
+function check(label, ok) {
+  if (ok) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${label}`);
+  }
+}
+
+const root = mkdtempSync(join(tmpdir(), 'payload-test-'));
+
+try {
+  const { payloadDir, toVersion } = stagePayload(root, { action: 'init' });
+
+  check('payload staged at .workspace-update/', existsSync(payloadDir));
+  check('manifest written', existsSync(join(payloadDir, '.manifest.json')));
+  check('returns the package version', typeof toVersion === 'string' && toVersion.length > 0);
+
+  // The payload keeps the live names older workspaces' skills expect
+  check('.claude/ staged under live name', existsSync(join(payloadDir, '.claude')));
+  check('.claude/skills/workspace-update/SKILL.md staged', existsSync(join(payloadDir, '.claude', 'skills', 'workspace-update', 'SKILL.md')));
+  check('.claude/settings.json staged', existsSync(join(payloadDir, '.claude', 'settings.json')));
+  check('.mcp.json staged under live name', existsSync(join(payloadDir, '.mcp.json')));
+  check('_gitignore stays inert (skills merge it under that name)', existsSync(join(payloadDir, '_gitignore')));
+
+  // The template's inert names must not leak into the payload
+  check('no _claude/ in payload', !existsSync(join(payloadDir, '_claude')));
+  check('no _mcp.json in payload', !existsSync(join(payloadDir, '_mcp.json')));
+
+  // cleanPayload removes the staging directory
+  cleanPayload(root);
+  check('cleanPayload removes .workspace-update/', !existsSync(payloadDir));
+} 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/lib/scaffold.mjs

@@ -1,4 +1,4 @@
-import { cpSync, mkdirSync, readFileSync, writeFileSync, renameSync, existsSync } from 'fs';
+import { cpSync, mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, rmSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -26,11 +26,28 @@ export async function scaffold(answers) {
   // scripts and hooks first need them — we do NOT pre-create them here.
   mkdirSync(join(directory, 'workspace-context', 'locked'), { recursive: true });
 
-  // Rename _gitignore to .gitignore
-  const gitignoreSrc = join(directory, '_gitignore');
-  const gitignoreDest = join(directory, '.gitignore');
-  if (existsSync(gitignoreSrc)) {
-    renameSync(gitignoreSrc, gitignoreDest);
+  // The template stores some files under inert names — _gitignore,
+  // _claude/, _mcp.json — because Claude Code treats .claude/ directories
+  // and .mcp.json files as protected paths and would block automated edits
+  // to the template. Install each under its live name in the target.
+  const inertNames = [
+    { from: '_gitignore', to: '.gitignore' },
+    { from: '_claude', to: '.claude' },
+    { from: '_mcp.json', to: '.mcp.json' },
+  ];
+  for (const { from, to } of inertNames) {
+    const src = join(directory, from);
+    const dest = join(directory, to);
+    if (!existsSync(src)) continue;
+    if (existsSync(dest) && statSync(src).isDirectory()) {
+      // Pre-populated target: merge into the existing directory — template
+      // files overwrite same-named ones, extra local files survive — then
+      // drop the inert copy.
+      cpSync(src, dest, { recursive: true });
+      rmSync(src, { recursive: true });
+    } else {
+      renameSync(src, dest);
+    }
   }
 
   // Process CLAUDE.md template

package/lib/scaffold.test.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// End-to-end test for scaffold.mjs
+// Run: node lib/scaffold.test.mjs
+//
+// The template stores .gitignore, .claude/, and .mcp.json under the inert
+// names _gitignore, _claude/, and _mcp.json (Claude Code protects the live
+// names from headless edits). scaffold() must install every one under its
+// live name and leave no inert leftovers behind.
+import { scaffold } from './scaffold.mjs';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+let failed = 0;
+let passed = 0;
+function check(label, ok) {
+  if (ok) { passed++; } else {
+    failed++;
+    console.error(`  FAIL: ${label}`);
+  }
+}
+
+const directory = mkdtempSync(join(tmpdir(), 'scaffold-test-'));
+
+try {
+  await scaffold({
+    name: 'demo',
+    directory,
+    repos: [],
+    userName: 'tester',
+    activateRules: [],
+  });
+
+  // Live names installed
+  check('.claude/ directory installed', existsSync(join(directory, '.claude')));
+  check('.claude/settings.json installed', existsSync(join(directory, '.claude', 'settings.json')));
+  check('.claude/settings.local.json written', existsSync(join(directory, '.claude', 'settings.local.json')));
+  check('.claude/rules/ installed', existsSync(join(directory, '.claude', 'rules')));
+  check('.claude/rules/coherent-revisions.md installed', existsSync(join(directory, '.claude', 'rules', 'coherent-revisions.md')));
+  check('.mcp.json installed', existsSync(join(directory, '.mcp.json')));
+  check('.gitignore installed', existsSync(join(directory, '.gitignore')));
+
+  // .mcp.json is the template's payload, unmodified
+  const mcp = JSON.parse(readFileSync(join(directory, '.mcp.json'), 'utf8'));
+  check('.mcp.json parses with mcpServers object', typeof mcp.mcpServers === 'object' && mcp.mcpServers !== null);
+
+  // Inert names are gone
+  check('no _claude/ leftover', !existsSync(join(directory, '_claude')));
+  check('no _mcp.json leftover', !existsSync(join(directory, '_mcp.json')));
+  check('no _gitignore leftover', !existsSync(join(directory, '_gitignore')));
+} finally {
+  rmSync(directory, { recursive: true, force: true });
+}
+
+if (failed > 0) {
+  console.error(`${failed} check(s) failed, ${passed} passed`);
+  process.exit(1);
+}
+console.log(`${passed} checks passed`);

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.18.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 → _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

@@ -0,0 +1,172 @@
+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 DIST_TAGS_URL = 'https://registry.npmjs.org/-/package/@ulysses-ai/create-workspace/dist-tags';
+const DEFAULT_TIMEOUT_MS = 3000;
+
+/**
+ * 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({ 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(DIST_TAGS_URL, { signal: controller.signal });
+    if (!res.ok) {
+      return { ...empty, error: `registry returned ${res.status} ${res.statusText || ''}`.trim() };
+    }
+    const body = await res.json();
+    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: picked.version, channel: picked.channel, tags, prerelease: picked.prerelease, error: null };
+  } catch (err) {
+    return { ...empty, error: err?.message || String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 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 (!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;
+  }
+}
+
+/**
+ * Write the version cache file, creating parent directories as needed.
+ */
+export function writeCache(path, data) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}

package/template/{.claude → _claude}/rules/forge-operations.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "**/.claude/skills/**"
+  - "**/.claude/scripts/**"
+---
+
 Activate this rule if the workspace creates PRs, watches CI runs, or interacts with releases from skills. Sibling to `work-item-tracking.md` (which covers issues); together they cover everything a workspace does against a code-hosting forge.
 
 # Forge Operations

package/template/{.claude → _claude}/rules/memory-guidance.md

@@ -32,6 +32,10 @@ not need to be in context while editing documentation.
 node .claude/scripts/context-footprint.mjs --root . --add <bytes> --as <destination>
 ```
 
+A rule that applies only to certain files should carry `paths:` frontmatter — it costs nothing
+until a matching file is touched — and the same script checks the live total against
+`workspace.alwaysLoadedBudgetBytes`.
+
 ## The canonical test
 
 Canonical describes what *is* and what *to do*, never what *to think*.

package/template/{.claude → _claude}/rules/task-list-mirroring.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - "work-sessions/**"
+  - "**/session.md"
+---
+
 # Task List Mirroring
 
 The Claude Code `TodoWrite` checklist is a live mirror of the workspace lifecycle. The durable backing store is a `## Tasks` section in `session.md`, round-tripped by `.claude/scripts/sync-tasks.mjs`. This rule defines the contract.