@ulysses-ai/create-workspace 0.18.0-beta.0 → 0.19.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/package.json

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

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.

package/template/{.claude → _claude}/scripts/build-workspace-context.mjs

@@ -9,12 +9,14 @@
 // Source of truth: the filesystem. Hand edits are overwritten on regeneration.
 // Gitignored files are excluded automatically. .indexignore adds prefix excludes.
 //
-// Canonical files honor a configurable byte budget. Each locked file declares
+// Canonical files honor an opt-in byte budget. Each locked file declares
 // `priority: critical | reference` in its frontmatter (default: critical).
 // Section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` markers
-// fence droppable spans inside reference files. When canonical body bytes exceed
-// the budget, the builder trims reference files first, then stubs them, in that
-// deterministic order. Critical files are never modified.
+// fence droppable spans inside reference files. When a budget is set and the
+// canonical body exceeds it, the builder trims reference files first, then
+// stubs them, in that deterministic order. Critical files are never modified.
+// `workspace.canonicalBudgetBytes` is off unless it holds a number: absent or
+// null means every locked file ships in full and nothing is trimmed.
 //
 // Usage:
 //   node build-workspace-context.mjs --write [--root <workspace-root>]
@@ -25,6 +27,7 @@
 //   0 — all artifacts current and canonical within budget
 //   1 — at least one artifact missing or stale (regenerate via --write)
 //   2 — artifacts current, but canonical body exceeds budget after trimming and stubbing
+//       (only reachable when a budget is set; off means nothing can exceed it)
 // Stale wins over over-budget when both apply.
 
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, realpathSync } from 'node:fs';
@@ -301,16 +304,19 @@ export function extractCanonicalVariants({ name, rawContent }) {
 }
 
 /**
- * Read `workspace.canonicalBudgetBytes` from `workspace.json`.
+ * Read `workspace.canonicalBudgetBytes` from `workspace.json`. The budget is
+ * opt-in — the whole always-loaded set is measured by `alwaysLoadedBudgetBytes`
+ * instead, so a canonical-only ceiling is something a workspace opts into.
  * Returns:
- *   - The integer value when set to a non-negative integer.
- *   - 0 when set to 0 or a negative number (treated as disabled).
- *   - DEFAULT_CANONICAL_BUDGET when the field is absent or workspace.json is missing.
+ *   - 0 when the field is absent or `null`, or workspace.json is missing (off).
+ *   - 0 when set to 0 or a negative number (treated as off).
+ *   - The integer value when set to a positive number.
+ *   - DEFAULT_CANONICAL_BUDGET when set to a non-number (invalid, rejected as before).
  *   - DEFAULT_CANONICAL_BUDGET (with a stderr warning) when workspace.json fails to parse.
  */
 export function readWorkspaceBudget(workspaceRoot) {
   const path = join(workspaceRoot, 'workspace.json');
-  if (!existsSync(path)) return DEFAULT_CANONICAL_BUDGET;
+  if (!existsSync(path)) return 0;
   let parsed;
   try {
     parsed = JSON.parse(readFileSync(path, 'utf-8'));
@@ -319,9 +325,10 @@ export function readWorkspaceBudget(workspaceRoot) {
     return DEFAULT_CANONICAL_BUDGET;
   }
   const ws = parsed && typeof parsed === 'object' ? parsed.workspace : null;
-  if (!ws || typeof ws !== 'object') return DEFAULT_CANONICAL_BUDGET;
-  if (!('canonicalBudgetBytes' in ws)) return DEFAULT_CANONICAL_BUDGET;
+  if (!ws || typeof ws !== 'object') return 0;
+  if (!('canonicalBudgetBytes' in ws)) return 0;
   const v = ws.canonicalBudgetBytes;
+  if (v === null) return 0;
   if (typeof v !== 'number' || !Number.isFinite(v)) return DEFAULT_CANONICAL_BUDGET;
   if (v <= 0) return 0;
   return Math.floor(v);
@@ -359,7 +366,8 @@ export function renderCanonicalBody(resolvedItems) {
  *   4. Keep stage-3 resolution; status `over-budget`, overBy populated.
  *
  * Special cases:
- *   - budgetBytes <= 0: stage 1 always wins, selection.budgetBytes = null.
+ *   - budgetBytes <= 0 (off — absent, null, 0, or negative): stage 1 always
+ *     wins, selection.budgetBytes = null.
  *   - No reference items present and stage 1 fails: status `over-budget`,
  *     no transformation possible. Stderr warning is emitted.
  */
@@ -380,7 +388,7 @@ export function selectCanonicalContent(items, budgetBytes, opts) {
     return { name: item.name, priority: item.priority, content: item.full };
   });
 
-  // Disabled-budget path.
+  // No-budget path (off because unset, or explicitly disabled).
   if (!Number.isFinite(budgetBytes) || budgetBytes <= 0) {
     const resolved = resolveAt(1);
     return {
@@ -537,6 +545,8 @@ function renderCanonical(resolvedItems, selection) {
     lines.push(
       `> Budget: ${selection.budgetBytes} bytes (body); current: ${selection.currentBytes} bytes; status: ${selection.status} (${summarizeSelection(selection)}).`,
     );
+  } else if (selection) {
+    lines.push(`> Budget: off; current: ${selection.currentBytes} bytes.`);
   }
   lines.push('');
 
@@ -673,7 +683,8 @@ function regenerateAll(workspaceRoot) {
  *   0 — all artifacts current and canonical body is within budget.
  *   1 — at least one artifact is missing or stale on disk. Run `--write`.
  *   2 — artifacts are current but canonical body exceeds budget after
- *       trimming and stubbing eligible reference files. Triage via
+ *       trimming and stubbing eligible reference files (only reachable when
+ *       a budget is set — off means nothing can exceed it). Triage via
  *       `/maintenance cleanup`. If both stale and over-budget, exit 1.
  *
  * `--write` always exits 0 on successful regeneration; over-budget is

package/template/{.claude → _claude}/scripts/chat-record.mjs

@@ -20,6 +20,18 @@
 //   node chat-record.mjs --root <dir> --list
 //   node chat-record.mjs --root <dir> --read  <chat-name>
 //   node chat-record.mjs --root <dir> --reconcile --session-id <id> --name <n>
+//   node chat-record.mjs --root <dir> --whoami
+//   node chat-record.mjs --root <dir> --add-task    --chat <n> --work-item <id> --branch <b> [--repo <r>]
+//   node chat-record.mjs --root <dir> --remove-task --chat <n> --work-item <id> [--repo <r>]
+//
+// --add-task / --remove-task report `action`: "added" | "updated" for
+// --add-task, "removed" | "unchanged" for --remove-task. They also keep the
+// older `updated` boolean / `removed` count fields — `updated` means "an
+// existing entry was replaced", not "anything changed" — but new callers
+// should read `action`. --whoami prints this chat's record name by matching
+// $CLAUDE_CODE_SESSION_ID against the records' sessionId, nothing and exit
+// 1 when there is no match: the `Chat record:` hook line can be missing
+// after context compaction, and this is the recovery path.
 
 import {
   readFileSync, writeFileSync, existsSync, mkdirSync,
@@ -197,7 +209,7 @@ function addTask(root, chatName, { workItem, branch, repo = null } = {}) {
   if (i >= 0) rec.tasks[i] = task;
   else rec.tasks.push(task);
   writeRecord(root, rec);
-  return { record: rec, updated: i >= 0 };
+  return { record: rec, action: i >= 0 ? 'updated' : 'added', updated: i >= 0 };
 }
 
 function removeTask(root, chatName, { workItem, repo = null } = {}) {
@@ -207,7 +219,18 @@ function removeTask(root, chatName, { workItem, repo = null } = {}) {
   const before = rec.tasks.length;
   rec.tasks = rec.tasks.filter((t) => !(t.workItem === workItem && (t.repo ?? null) === repo));
   writeRecord(root, rec);
-  return { record: rec, removed: before - rec.tasks.length };
+  return { record: rec, action: before - rec.tasks.length > 0 ? 'removed' : 'unchanged', removed: before - rec.tasks.length };
+}
+
+// The record name for the chat running now. The SessionStart hook injects
+// a `Chat record:` line, but compaction can drop it; the sessionId the
+// hook keyed on is stable, so matching it against the records recovers the
+// name without guessing. Null when the env var is unset or nothing matches.
+function whoami(root, { env = process.env } = {}) {
+  const sid = env.CLAUDE_CODE_SESSION_ID;
+  if (!sid) return null;
+  const mine = listRecords(root).find((r) => r.sessionId === sid);
+  return mine ? mine.chat : null;
 }
 
 // Scope is what a chat declares it owns. The Aug 26 coordination burst had
@@ -230,6 +253,7 @@ function parseArgs(argv) {
     if (a === '--list') { args.mode = 'list'; continue; }
     if (a === '--read') { args.mode = 'read'; args.chat = rest[++i]; continue; }
     if (a === '--reconcile') { args.mode = 'reconcile'; continue; }
+    if (a === '--whoami') { args.mode = 'whoami'; continue; }
     if (a === '--add-task') { args.mode = 'add-task'; continue; }
     if (a === '--remove-task') { args.mode = 'remove-task'; continue; }
     if (a === '--chat') { args.chat = rest[++i]; continue; }
@@ -240,7 +264,7 @@ function parseArgs(argv) {
     if (a === '--name') { args.name = rest[++i]; continue; }
     throw new Error(`unknown argument: ${a}`);
   }
-  if (!args.mode) throw new Error('one of --list, --read <chat>, --reconcile is required');
+  if (!args.mode) throw new Error('one of --list, --read <chat>, --reconcile, --whoami is required');
   if (args.mode === 'reconcile' && (!args.sessionId || !args.name)) {
     throw new Error('--reconcile requires --session-id and --name');
   }
@@ -255,6 +279,15 @@ function parseArgs(argv) {
 
 function main() {
   const args = parseArgs(process.argv);
+  if (args.mode === 'whoami') {
+    // A bare name, not JSON: the caller wants something to put on a command
+    // line. No match prints nothing and exits 1 — the caller decides what
+    // an unidentified chat means.
+    const name = whoami(args.root);
+    if (name === null) process.exit(1);
+    process.stdout.write(`${name}\n`);
+    return;
+  }
   let out;
   if (args.mode === 'list') out = listRecords(args.root);
   else if (args.mode === 'read') out = readRecord(args.root, args.chat);
@@ -278,5 +311,5 @@ if (isMainModule(import.meta.url)) {
 export {
   recordPath, drawerPath, emptyRecord, readRecord, writeRecord,
   listRecords, reconcile, parseArgs, readSessionRegistry, resolveChatName,
-  addTask, removeTask, setScope, CHATS_DIR,
+  addTask, removeTask, setScope, whoami, CHATS_DIR,
 };