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

package/README.md

@@ -90,7 +90,7 @@ A scaffolded workspace with:
 
 - **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
 - **7 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
-- **9 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulysses-ai/create-workspace",
-  "version": "0.14.0-beta.1",
+  "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/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');
+}

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

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// Unit tests for registry-check.mjs
+// Run: node template/.claude/lib/registry-check.test.mjs
+import { compareVersions } from './registry-check.mjs';
+
+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}`);
+  }
+}
+
+console.log('# compareVersions');
+assertEq(compareVersions('0.13.0', '0.14.0'),               -1, 'older minor');
+assertEq(compareVersions('0.14.0', '0.13.0'),                1, 'newer minor');
+assertEq(compareVersions('0.13.0', '0.13.0'),                0, 'equal');
+assertEq(compareVersions('1.0.0',  '0.99.99'),               1, 'newer major');
+assertEq(compareVersions('0.14.0-beta.1', '0.14.0'),        -1, 'prerelease < release');
+assertEq(compareVersions('0.14.0', '0.14.0-beta.1'),         1, 'release > prerelease');
+assertEq(compareVersions('0.14.0-beta.1', '0.14.0-beta.2'), -1, 'prerelease numeric ordering');
+assertEq(compareVersions('0.14.0-beta.10', '0.14.0-beta.2'), 1, 'prerelease numeric not lexical');
+assertEq(compareVersions('0.14.0-beta.5', '0.14.0-beta.5'),  0, 'equal prerelease');
+assertEq(compareVersions('0.14.0-alpha.1', '0.14.0-beta.1'),-1, 'alpha < beta lexical');
+
+import { getLatestVersion } from './registry-check.mjs';
+
+console.log('\n# getLatestVersion');
+
+// Helper: build a fake fetch
+function fakeFetch(response) {
+  return async () => response;
+}
+
+// Success path
+{
+  const fakeOk = fakeFetch({
+    ok: true,
+    json: async () => ({ version: '0.14.0', name: '@ulysses-ai/create-workspace' }),
+  });
+  const result = await getLatestVersion({ fetchFn: fakeOk });
+  assertEq(result, { version: '0.14.0', error: null }, 'success returns version');
+}
+
+// Non-2xx response
+{
+  const fake404 = fakeFetch({ ok: false, status: 404, statusText: 'Not Found' });
+  const result = await getLatestVersion({ fetchFn: fake404 });
+  assertEq(result.version, null, 'non-2xx version is null');
+  assertEq(typeof result.error, 'string', 'non-2xx returns error string');
+}
+
+// Malformed body (no version field)
+{
+  const fakeBad = fakeFetch({ ok: true, json: async () => ({ name: 'foo' }) });
+  const result = await getLatestVersion({ fetchFn: fakeBad });
+  assertEq(result.version, null, 'missing version field is null');
+  assertEq(typeof result.error, 'string', 'missing version returns error');
+}
+
+// Network error (fetch throws)
+{
+  const fakeThrow = async () => { throw new Error('ECONNREFUSED'); };
+  const result = await getLatestVersion({ fetchFn: fakeThrow });
+  assertEq(result.version, null, 'thrown error returns null version');
+  assertEq(result.error.includes('ECONNREFUSED'), true, 'thrown error message preserved');
+}
+
+import { readCache, writeCache } from './registry-check.mjs';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+console.log('\n# readCache / writeCache');
+
+function withTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'reg-cache-test-'));
+  try { fn(dir); } finally { rmSync(dir, { recursive: true, force: true }); }
+}
+
+// readCache: missing file returns null
+withTempDir((dir) => {
+  const result = readCache(join(dir, 'missing.json'));
+  assertEq(result, null, 'missing file returns null');
+});
+
+// readCache: malformed JSON returns null
+withTempDir((dir) => {
+  const path = join(dir, 'bad.json');
+  writeFileSync(path, '{not json');
+  const result = readCache(path);
+  assertEq(result, null, 'malformed JSON returns null');
+});
+
+// readCache: valid file returns parsed object
+withTempDir((dir) => {
+  const path = join(dir, 'good.json');
+  writeFileSync(path, JSON.stringify({ latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' }));
+  const result = readCache(path);
+  assertEq(result, { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' }, 'valid file parsed');
+});
+
+// readCache: missing required fields returns null
+withTempDir((dir) => {
+  const path = join(dir, 'partial.json');
+  writeFileSync(path, JSON.stringify({ checkedAt: '2026-04-24T21:00:00Z' }));
+  const result = readCache(path);
+  assertEq(result, null, 'missing latestVersion returns null');
+});
+
+// writeCache + readCache round-trip
+withTempDir((dir) => {
+  const path = join(dir, 'rt.json');
+  writeCache(path, { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' });
+  assertEq(readCache(path), { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' }, 'round-trip equal');
+});
+
+// writeCache creates parent dir if missing
+withTempDir((dir) => {
+  const path = join(dir, 'nested', 'deep', 'cache.json');
+  writeCache(path, { latestVersion: '0.14.0', checkedAt: '2026-04-24T21:00:00Z' });
+  assertEq(readCache(path)?.latestVersion, '0.14.0', 'parent dir created');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/template/.claude/rules/memory-guidance.md

@@ -24,3 +24,50 @@ When a work session is active:
 - Decisions and progress from this session → update the session tracker body at `work-sessions/{name}/workspace/session.md` (consumed by /complete-work)
 - Patterns, corrections, and insights that apply beyond this session → auto-memory (persists across all sessions)
 - Don't duplicate: if something is already in the session tracker, don't also save it to auto-memory
+
+## Shared-Context Frontmatter
+
+Every shared-context file should have YAML frontmatter. The fields below are conventions, not all required.
+
+**Standard fields:**
+
+- `state` — `locked` (team truth) or `ephemeral` (working context). Locked files live under `locked/`; ephemeral files live elsewhere.
+- `lifecycle` — for ephemeral files: `active` (still relevant) or `resolved` (handled, kept for record).
+- `type` — kind of content: `reference`, `braindump`, `handoff`, `research`, `design`, `index`, `promoted`.
+- `topic` — kebab-case slug matching the filename (without `.md`).
+- `author` — username scope owner. Required for `{user}/` files.
+- `updated` — ISO date of last meaningful edit. `/maintenance` flags stale `lifecycle: active` files based on this.
+
+**Index-feeding field:**
+
+- `description` — one-line summary, used verbatim by `shared-context/index.md`. When omitted, the index falls back to the first sentence of the body, then the filename slug. Adding a `description:` to a file with a weak fallback is the cheapest way to improve the index.
+
+**Optional confidence marker:**
+
+- `confidence` — `high` | `medium` | `low`. Apply to research, design, and exploration files where the conclusions might still shift. Skip on locked files (locked = high by definition) and on workflow artifacts like handoffs and braindumps. The frontmatter integrity check in `/maintenance` validates the value if present.
+
+**Example for a research file:**
+
+```yaml
+---
+state: ephemeral
+lifecycle: active
+type: research
+topic: vector-search-evaluation
+description: Evaluation of FAISS for shared-context — concluded NL index is sufficient at our scale.
+author: alex
+confidence: medium
+updated: 2026-04-25
+---
+```
+
+## Shared-Context Index
+
+`shared-context/index.md` is auto-generated by `.claude/scripts/build-shared-context-index.mjs`. It's a one-line catalog of every shared-context file (excluding paths in `shared-context/.indexignore`). The script regenerates from frontmatter on demand:
+
+```bash
+node .claude/scripts/build-shared-context-index.mjs --check --root .   # exits 1 if stale
+node .claude/scripts/build-shared-context-index.mjs --write --root .   # regenerate
+```
+
+`/maintenance` checks the index for staleness in audit mode and regenerates in cleanup mode. Hand edits to `index.md` are overwritten — update source files (or their `description:` frontmatter) instead.

package/template/.claude/rules/workspace-structure.md

@@ -15,6 +15,8 @@ This workspace follows the claude-workspace convention. All paths are relative t
 | `work-sessions/{name}/workspace/repos/` | Real directory holding nested project worktrees for this session | No (gitignored) |
 | `work-sessions/{name}/workspace/repos/{repo}/` | Project worktree nested inside the workspace worktree | No (gitignored) |
 | `shared-context/` | Shared memory — handoffs, braindumps, team knowledge | Yes |
+| `shared-context/index.md` | Auto-generated catalog of every shared-context file (one-line per file) | Yes |
+| `shared-context/.indexignore` | Path prefixes to exclude from `index.md` (e.g., archived release notes) | Yes |
 | `shared-context/locked/` | Team truths — loaded every session, injected into subagents | Yes |
 | `shared-context/{user}/` | User-scoped working context — default for all captures | Yes |
 | `workspace-scratchpad/` | Disposable workspace-scoped files — session log, hook debug output | No (gitignored, lazy) |