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

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/task-list-mirroring.md

@@ -0,0 +1,69 @@
+# 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.
+
+## Why
+
+`TodoWrite` is conversation-scoped — it disappears at the end of every chat. To make it useful for multi-chat work sessions, it needs a durable store that survives chat restarts, machine switches, and pause/resume cycles. `session.md` already lives on the session branch and travels with `git push`/`git pull`, so it's the natural home.
+
+## The `## Tasks` schema
+
+Anchored after `## Pre-session context` (if present) and before `## Progress`:
+
+```
+## Tasks
+
+> Linked: gh:42 — Auth timeout on mobile
+
+- [x] Start work
+- [x] Reproduce on iOS Safari
+- [ ] Identify race condition in token refresh
+- [ ] Complete work
+```
+
+- The heading is exactly `## Tasks`.
+- Optional first line is a blockquote `> Linked: {workItem-id} — {issue-title}`. Present iff `workItem:` is set in frontmatter.
+- Each task is one checkbox line. Three statuses: `- [ ]` pending, `- [-]` in_progress, `- [x]` completed. No nesting.
+- The bookends `Start work` and `Complete work` are always present, at positions 1 and N.
+
+The `- [-]` marker is non-standard GFM — GitHub's web renderer shows it as literal text rather than a checkbox. That's acceptable because `session.md` lives on session branches and is mostly read in editors (where Obsidian, JetBrains, and similar renderers do treat `[-]` as in-progress). The tradeoff buys lossless `in_progress` round-trip across chats.
+
+## Helper invocations
+
+```bash
+# Read: emits TodoWrite-shaped JSON.
+node .claude/scripts/sync-tasks.mjs --read <session.md>
+
+# Write: takes TodoWrite-shaped JSON on stdin, rewrites the section atomically.
+node .claude/scripts/sync-tasks.mjs --write <session.md>
+```
+
+The helper enforces bookends on write — Claude doesn't need to remember to include them, and any misplacement is silently corrected.
+
+## When to flush (write to disk)
+
+**Lifecycle moments — always:**
+- `/start-work` (blank): seed `## Tasks` with bookends + (if linked) tracker reference.
+- `/start-work` (resume): read-only — populate `TodoWrite` from `## Tasks`.
+- `/pause-work`: flush before the auto-commit.
+- `/complete-work`: flush before release-note synthesis.
+- `/handoff`, `/braindump`: include a snapshot of current `TodoWrite` state in the captured artifact.
+
+**Mid-session — after meaningful change:**
+- A new task was added.
+- A task moved to `completed`.
+- A task moved to `in_progress`.
+
+Trivial edits (renaming, reordering) do **not** trigger a flush — they ride on the next lifecycle commit.
+
+## What NOT to do
+
+- Do not edit the `## Tasks` section by hand or with `Edit` — always go through the helper. Manual edits will be overwritten and may miss the bookend invariant.
+- Do not add nested checkboxes — `TodoWrite` is flat, and the round-trip ignores nesting.
+- Do not omit the bookends — the helper auto-inserts them, but explicit is better than implicit.
+- Do not flush every keystroke — that creates pointless file churn. Flush on meaningful change or lifecycle moment.
+- Do not flush from inside a subagent — subagents have ephemeral context; only the main agent maintains the canonical `TodoWrite` state for the session.
+
+## Concurrency model
+
+Multi-chat-on-same-session is rare but possible. Each chat maintains its own `TodoWrite`; flushes write the file and the last writer wins. This matches the existing `## Progress` model. If you notice a divergence, the disk version is authoritative — restart your chat to reseed.

package/template/.claude/rules/token-economics.md.skip

@@ -1,6 +1,6 @@
 # Token Economics
 
-Activate this rule for token-aware behavior — cost-conscious model selection, context efficiency, and waste reduction.
+Activate this rule for token-aware behavior — cost-conscious model selection, context efficiency, command discipline, and waste detection.
 
 ## Model Selection
 
@@ -18,14 +18,29 @@ Activate this rule for token-aware behavior — cost-conscious model selection,
 - If a tool result is large and mostly irrelevant, note what matters and move on
 - Prefer exact file paths over glob searches when you know where things are
 
-## Waste Detection
+## Command Discipline
 
-- Flag when context is heavy with resolved discussions that could be compacted
-- Suggest /braindump to offload discussion into files, freeing context for work
-- Note when subagent context is bloated relative to the task size
-- If locked context exceeds the 10KB target, mention it
+The single biggest source of session bloat is bash output you didn't bound. The model has to read every line that comes back, and there's no after-the-fact way to truncate it.
+
+- Don't run unbounded commands. Pipe to `head`, `tail`, or `grep` first.
+- For test runs, prefer scoped invocations: `npm test path/to/file.test.mjs` over bare `npm test`. If you only need failures, pipe through `grep -E "FAIL|✗|Error"`.
+- For `find` and `grep -r` / `rg -r`, always supply a constraint (`-name`, `-path`, `--include`, `-g`). Bare `find ~/` against home is almost never what you want.
+- For inspecting a large file, write to a tmp file and grep into it rather than `cat`ing the whole thing into context.
+- For long-running processes (servers, watchers), use `run_in_background: true` and stream with the Monitor tool — don't let stdout pile up in a single tool result.
+- Do not claim a task is done before running its tests. The cost of a forgotten test run is a follow-up cycle that bloats the session more than the test would have.
+
+## Ghost-Token Detection
+
+"Ghost tokens" are context spend you can't see in any single tool result — structural bloat that accumulates across the session. Watch for:
+
+- **Unused skills.** A loaded skill that you never invoke costs input tokens every turn. If a workspace ships skills you don't use in the current task, that's silent overhead.
+- **Oversized locked context.** `shared-context/locked/` is injected into every session and every subagent. If it grows past 5% of the active model's context window, flag it (yellow); past 15%, treat as red. Absolute byte count is a weak proxy — duplicated coverage and stale references matter more.
+- **Unused MCP servers.** Each MCP server's tool list is in your prompt whether you call it or not. If a server is registered but never used in this workspace's flow, surface it for cleanup.
+- **Resolved discussions still in context.** If the conversation has worked through a long debate that's now settled, that text is still occupying the window. Suggest `/braindump` to offload it into a file.
+- **Subagent context bloat.** A subagent prompt that ships more context than the task requires wastes tokens twice — once for the subagent, once for the dispatching model that wrote the prompt.
 
 ## Compaction Awareness
 
-- When approaching compaction threshold, prioritize capturing over continuing
-- After compaction, avoid re-reading files that were already discussed — check shared-context first
+- When approaching the compaction threshold, prioritize capturing over continuing. A `/braindump` or `/handoff` *before* compaction preserves reasoning that gets summarized away.
+- After compaction, avoid re-reading files that were already discussed — check `shared-context/` and the session tracker first.
+- The `PreCompact` hook will prompt for capture; treat that prompt as a real checkpoint, not a dismissable nag.

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) |

package/template/.claude/scripts/build-shared-context-index.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// Generate shared-context/index.md by walking shared-context/ and reading frontmatter.
+//
+// Source of truth is the filesystem. Hand edits to index.md are overwritten.
+//
+// Usage:
+//   node build-shared-context-index.mjs --write [--root <workspace-root>]
+//   node build-shared-context-index.mjs --check [--root <workspace-root>]
+//
+// --write regenerates shared-context/index.md.
+// --check exits 0 if the on-disk index matches what would be generated, 1 otherwise.
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { parseSessionContent } from '../lib/session-frontmatter.mjs';
+
+const INDEX_FILENAME = 'index.md';
+const LOCKED_DIR = 'locked';
+const IGNORE_FILENAME = '.indexignore';
+
+function parseArgs(argv) {
+  const args = { mode: null, root: process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--write') args.mode = 'write';
+    else if (a === '--check') args.mode = 'check';
+    else if (a === '--root') args.root = argv[++i];
+  }
+  if (!args.mode) {
+    throw new Error('Specify --write or --check');
+  }
+  return args;
+}
+
+function walkMarkdown(dir) {
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      out.push(...walkMarkdown(full));
+    } else if (st.isFile() && name.endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function readDescription(filePath) {
+  let frontmatter = {};
+  let body = '';
+  try {
+    const parsed = parseSessionContent(readFileSync(filePath, 'utf-8'));
+    frontmatter = parsed.fields || {};
+    body = parsed.body || '';
+  } catch {
+    body = readFileSync(filePath, 'utf-8');
+  }
+
+  if (typeof frontmatter.description === 'string' && frontmatter.description.trim()) {
+    return frontmatter.description.trim();
+  }
+
+  const stripped = body.replace(/^#.*$/m, '').trim();
+  const firstParagraph = stripped.split(/\n\s*\n/, 1)[0] || '';
+  const firstSentence = firstParagraph.replace(/\n/g, ' ').match(/[^.!?]+[.!?]/);
+  if (firstSentence) {
+    const candidate = firstSentence[0].trim();
+    if (candidate.length > 0 && candidate.length <= 200) return candidate;
+  }
+
+  const filename = filePath.split(sep).pop() || '';
+  return filename.replace(/\.md$/, '').replace(/-/g, ' ');
+}
+
+function classify(relativePath) {
+  const parts = relativePath.split(sep);
+  if (parts.length === 1) return { group: '__root__', sortKey: parts[0] };
+  if (parts[0] === LOCKED_DIR) return { group: LOCKED_DIR, sortKey: parts.slice(1).join('/') };
+  return { group: parts[0], sortKey: parts.slice(1).join('/') };
+}
+
+function readIgnorePrefixes(sharedContextDir) {
+  const ignorePath = join(sharedContextDir, IGNORE_FILENAME);
+  if (!existsSync(ignorePath)) return [];
+  return readFileSync(ignorePath, 'utf-8')
+    .split('\n')
+    .map((line) => line.replace(/#.*/, '').trim())
+    .filter((line) => line.length > 0);
+}
+
+function isIgnored(relativePath, prefixes) {
+  for (const prefix of prefixes) {
+    if (relativePath === prefix) return true;
+    if (relativePath.startsWith(prefix.endsWith('/') ? prefix : prefix + '/')) return true;
+  }
+  return false;
+}
+
+function buildEntries(workspaceRoot) {
+  const sharedContextDir = join(workspaceRoot, 'shared-context');
+  if (!existsSync(sharedContextDir)) return [];
+
+  const ignorePrefixes = readIgnorePrefixes(sharedContextDir);
+
+  const files = walkMarkdown(sharedContextDir).filter((f) => {
+    const rel = relative(sharedContextDir, f).split(sep).join('/');
+    if (rel === INDEX_FILENAME) return false;
+    if (isIgnored(rel, ignorePrefixes)) return false;
+    return true;
+  });
+
+  return files
+    .map((file) => {
+      const rel = relative(sharedContextDir, file);
+      const { group, sortKey } = classify(rel);
+      return {
+        group,
+        sortKey,
+        relativePath: rel.split(sep).join('/'),
+        description: readDescription(file),
+      };
+    })
+    .sort((a, b) => {
+      const groupOrder = (g) =>
+        g === LOCKED_DIR ? 0 : g === '__root__' ? 1 : 2;
+      const ga = groupOrder(a.group);
+      const gb = groupOrder(b.group);
+      if (ga !== gb) return ga - gb;
+      if (a.group !== b.group) return a.group.localeCompare(b.group);
+      return a.sortKey.localeCompare(b.sortKey);
+    });
+}
+
+function groupHeading(group) {
+  if (group === LOCKED_DIR) return 'Locked (team truths, always loaded)';
+  if (group === '__root__') return 'Team-shared (root)';
+  return group;
+}
+
+function renderIndex(entries, generatedAt) {
+  const lines = [
+    '---',
+    'type: index',
+    `generated: ${generatedAt}`,
+    '---',
+    '',
+    '# shared-context — index',
+    '',
+    '> Auto-generated by `.claude/scripts/build-shared-context-index.mjs`. Hand edits will be overwritten — update the source files instead.',
+    '',
+  ];
+
+  let currentGroup = null;
+  for (const entry of entries) {
+    if (entry.group !== currentGroup) {
+      if (currentGroup !== null) lines.push('');
+      lines.push(`## ${groupHeading(entry.group)}`, '');
+      currentGroup = entry.group;
+    }
+    lines.push(`- [${entry.relativePath}](${entry.relativePath}) — ${entry.description}`);
+  }
+
+  if (entries.length === 0) {
+    lines.push('_(no shared-context files yet)_');
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function fingerprint(content) {
+  return content
+    .split('\n')
+    .filter((line) => !line.startsWith('generated:'))
+    .join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const indexPath = join(args.root, 'shared-context', INDEX_FILENAME);
+  const entries = buildEntries(args.root);
+  const generatedAt = new Date().toISOString();
+  const fresh = renderIndex(entries, generatedAt);
+
+  if (args.mode === 'check') {
+    if (!existsSync(indexPath)) {
+      process.stdout.write(JSON.stringify({ status: 'missing' }) + '\n');
+      process.exit(1);
+    }
+    const onDisk = readFileSync(indexPath, 'utf-8');
+    if (fingerprint(onDisk) === fingerprint(fresh)) {
+      process.stdout.write(JSON.stringify({ status: 'current', entries: entries.length }) + '\n');
+      process.exit(0);
+    }
+    process.stdout.write(JSON.stringify({ status: 'stale', entries: entries.length }) + '\n');
+    process.exit(1);
+  }
+
+  if (args.mode === 'write') {
+    writeFileSync(indexPath, fresh);
+    process.stdout.write(
+      JSON.stringify({ status: 'written', entries: entries.length, path: indexPath }) + '\n',
+    );
+    process.exit(0);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { buildEntries, renderIndex, fingerprint, readDescription };