@ulysses-ai/create-workspace 0.17.0-beta.0 → 0.19.0-beta.0

package/README.md

@@ -74,11 +74,11 @@ Rules say what's safe. Skills say how to do the recurring things. Hooks notice w
 
 Four things, in the order you'll touch them:
 
-1. **A workflow lifecycle that survives chat boundaries.** `/start-work` provisions a session — branch, worktree, tracker — atomically. `/pause-work` and `/sync-work` checkpoint mid-stream. `/complete-work` rebases, synthesizes release notes, opens PRs, and tears down. The same session resumes cleanly in a fresh chat.
+1. **A workflow lifecycle that survives chat boundaries.** `/start-work` provisions a session — branch, worktree, tracker — atomically. `/pause-work` and `/sync-work` checkpoint mid-stream. `/complete-work` rebases, opens PRs, merges, and tears down. The same session resumes cleanly in a fresh chat.
 
 2. **Parallel work sessions you can run from separate terminals.** Each session lives in its own folder under `work-sessions/{name}/` with its own workspace worktree and nested project worktrees. Two sessions can't collide on a branch or a working directory.
 
-3. **Multi-repo support with versioning across repos.** A workspace wraps your project repos rather than replacing them. Each session can span one repo or many. `/release` synthesizes versioned release docs across the repos that contributed.
+3. **Multi-repo support with versioning across repos.** A workspace wraps your project repos rather than replacing them. Each session can span one repo or many. `/release` cuts a versioned release per repo — bump, tag, forge release with notes generated from merged PRs.
 
 4. **Shared context with a locked layer that stays in the window.** `shared-context/locked/` is loaded every turn and injected into subagents. Team truths arrive in the model's context window without anyone remembering to paste them.
 
@@ -88,7 +88,7 @@ Four things, in the order you'll touch them:
 
 A scaffolded workspace with:
 
-- **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
+- **17 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
 - **9 active rules** + **9 optional `.skip` rules** for behaviors you can opt into
 - **9 hooks** for SessionStart, SubagentStart, PreCompact, 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)

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.17.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.md.tmpl

@@ -8,6 +8,7 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - Each session is a self-contained folder at `work-sessions/{name}/` containing the worktree, nested project worktrees, and the session tracker
 - From root: only `local-only-*` and `workspace-scratchpad/` are writable
 - Team knowledge lives in `workspace-context/`
+- Run `/rename` to label this chat before `/clear` — keeps the chat findable in your CLI history after the context is wiped
 
 ## Workspace Config
 @workspace.json
@@ -25,11 +26,27 @@ This is a claude-workspace. All conventions are defined in .claude/rules/.
 - `/braindump [name]` — capture discussion/reasoning
 - `/aside [--quick] <thought>` — capture a drive-by idea without interrupting current work
 - `/pause-work` — suspend work, push, draft PR
-- `/complete-work` — finalize branch, release notes, real PR
+- `/complete-work` — finalize the work — rebase, PR, merge, close the issue
 - `/promote` — move personal memory to shared context
-- `/release [version]` — combine unreleased notes into versioned doc
+- `/release [version]` — cut a versioned release: bump, tag, forge release with generated notes
 - `/sync-work` — push branches without ceremony
 - `/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
 - `/build-docs-site` — build a comprehensive Docusaurus documentation site for a project
+
+## Compact Instructions
+
+When auto-compacting context, preserve in the summary:
+- Decisions made in this session and their rationale
+- Constraints and conventions established or confirmed
+- Active task list state and the next concrete step
+- File paths touched and the nature of the change
+- Errors hit and what was tried
+
+Drop from the summary:
+- Verbose tool output already reflected in committed code
+- Exploratory reads that did not lead to a change
+- Conversational asides
+
+Files in `workspace-context/`, the session tracker (`session.md`) or chat drawer (`workspace-scratchpad/chats/{chat}/`), and any `design-*.md`/`plan-*.md` survive compaction — they're on disk. Re-read them on demand instead of trying to keep their contents in summary.

package/template/{.claude → _claude}/hooks/_utils.mjs

@@ -150,7 +150,7 @@ export function createSessionTracker(root, sessionName, fields, body) {
 
 /**
  * Delete the entire work-sessions/{name}/ folder. Used by /complete-work
- * after the session is finalized and archived into release notes.
+ * after the session is finalized and its artifacts promoted or discarded.
  * Caller is responsible for any git bookkeeping (branch deletes, prunes).
  */
 export function deleteSessionFolder(root, sessionName) {

package/template/_claude/hooks/repo-write-detection.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// PreToolUse hook — enforce workspace root write restrictions and detect
+// out-of-session repo writes.
+//
+// New layout paths:
+//   Workspace worktree: work-sessions/{name}/workspace/
+//   Project worktree:   work-sessions/{name}/workspace/repos/{repo}/
+//   Bare clone:         repos/{repo}/  (at workspace root)
+//   Task worktree:      repos/{repo}/.claude/worktrees/{slug}/  (gh:132)
+//   Workspace task worktree: {root}/.claude/worktrees/{slug}/  (gh:146)
+import { join, basename, resolve, relative, sep, isAbsolute, dirname } from 'path';
+import { realpathSync } from 'fs';
+import { fileURLToPath } from 'url';
+import {
+  getWorkspaceRoot,
+  readStdin,
+  respond,
+  getActiveSessionPointer,
+  readSessionTracker,
+  readJSON,
+  getWorkspacePaths,
+} from './_utils.mjs';
+
+// .native resolves Windows 8.3 short names; the plain fallback covers
+// filesystems where the native binding is unavailable.
+function realPath(p) {
+  try { return realpathSync.native(p); } catch { /* fall through */ }
+  try { return realpathSync(p); } catch { /* fall through */ }
+  return resolve(p);
+}
+
+// Realpaths BOTH sides: Node resolves the module URL through symlinks
+// (import.meta.url is the real path) while argv[1] stays exactly as the
+// host passed it — a bare comparison silently disables the hook whenever
+// the hook is reached through a symlinked workspace.
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realPath(fileURLToPath(metaUrl)) === realPath(process.argv[1]);
+  } catch { return false; }
+}
+
+// realpath the deepest existing ancestor and reattach the missing tail:
+// the file being written may not exist yet, but the worktree directory it
+// lands in does. When no ancestor exists at all, no symlink can be in
+// play, so the resolved input is returned as-is.
+function realPathDeepest(p) {
+  let cur = p;
+  const tail = [];
+  for (;;) {
+    try { return join(realpathSync.native(cur), ...tail); } catch { /* climb */ }
+    const parent = dirname(cur);
+    if (parent === cur) return resolve(p);
+    tail.unshift(basename(cur));
+    cur = parent;
+  }
+}
+
+// relative() output is "inside" when it is a plain descent — not '', '..',
+// a '..'-prefixed climb, or a cross-volume absolute path (Windows drives).
+function isDescent(rel) {
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+/**
+ * True when filePath sits inside repos/{repo}/.claude/worktrees/{slug}/ —
+ * the task model's project work area (gh:132) — or inside
+ * {root}/.claude/worktrees/{slug}/, the workspace repo's own task
+ * worktrees (gh:146). Task chats run at the workspace root and edit there
+ * by design, so these writes are legitimate and must not trip the "you're
+ * on main" repo/template warnings. The worktrees directory itself and any
+ * other {root}/.claude/... path stay warnable.
+ *
+ * Pure path arithmetic (realpath + relative + segment split), so it is
+ * sep-safe on Windows, symlink-safe on macOS, and never stats the file
+ * itself.
+ */
+export function isTaskWorktreeWrite(root, filePath) {
+  if (!root || !filePath) return false;
+  const rootReal = realPath(resolve(root));
+  const fileReal = realPathDeepest(resolve(filePath));
+
+  // The workspace repo's own worktrees: {root}/.claude/worktrees/{slug}/…
+  const relRoot = relative(rootReal, fileReal);
+  if (isDescent(relRoot)) {
+    const rootParts = relRoot.split(sep);
+    if (rootParts.length >= 3 && rootParts[0] === '.claude' && rootParts[1] === 'worktrees') return true;
+  }
+
+  // Project worktrees: repos/{repo}/.claude/worktrees/{slug}/…
+  const rel = relative(realPath(join(rootReal, 'repos')), fileReal);
+  if (!isDescent(rel)) return false;
+  const parts = rel.split(sep);
+  return parts.length >= 4 && parts[1] === '.claude' && parts[2] === 'worktrees';
+}
+
+async function main() {
+  const root = getWorkspaceRoot(import.meta.url);
+  const input = await readStdin();
+  const toolName = input.tool_name || '';
+
+  if (!['Bash', 'Edit', 'Write'].includes(toolName)) {
+    respond();
+    process.exit(0);
+  }
+
+  const toolInput = input.tool_input || {};
+  const paths = [toolInput.file_path, toolInput.command, toolInput.path]
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\\/g, '/');
+
+  // If we're in a workspace worktree, check for out-of-session repo writes
+  const pointer = getActiveSessionPointer(root);
+  if (pointer) {
+    const mainRoot = pointer.rootPath || root;
+    const config = readJSON(join(mainRoot, 'workspace.json'));
+    const tracker = readSessionTracker(mainRoot, pointer.name);
+
+    if (tracker && config?.repos) {
+      // Find references to repos inside work-sessions/{name}/workspace/repos/{repo}/
+      // and also the workspace-root repos/{repo}/ for direct writes.
+      const wtMatch = paths.match(/work-sessions\/[^/\s]+\/workspace\/repos\/([^/\s]+)/);
+      const cloneMatch = paths.match(/(?:^|\s|\/)repos\/([^/\s]+)/);
+      const targetRepo = wtMatch ? wtMatch[1] : (cloneMatch ? cloneMatch[1] : null);
+      if (targetRepo) {
+        const sessionRepos = tracker.repos || [];
+        if (config.repos[targetRepo] && !sessionRepos.includes(targetRepo)) {
+          respond(`You're about to write to ${targetRepo}, which isn't part of this session. Consider adding it first so changes land on the session branch.`);
+          process.exit(0);
+        }
+      }
+    }
+
+    respond();
+    process.exit(0);
+  }
+
+  // We're at the main workspace root — restrict writes
+
+  const { scratchpadDir } = getWorkspacePaths(root);
+  const scratchpadName = scratchpadDir.slice(root.length + 1); // "workspace-scratchpad"
+
+  // Allow writes to the workspace scratchpad
+  if (paths.includes(scratchpadName)) {
+    respond();
+    process.exit(0);
+  }
+
+  // Allow writes to local-only-* files
+  const filePathArg = toolInput.file_path || '';
+  if (basename(filePathArg).startsWith('local-only-')) {
+    respond();
+    process.exit(0);
+  }
+
+  // Task-model writes: repos/{repo}/.claude/worktrees/{slug}/ is the task
+  // model's work area at the root (gh:132). Those tokens are stripped from
+  // what the warning checks judge — an Edit/Write inside a worktree leaves
+  // nothing to judge and is exempt, while a Bash command that ALSO touches
+  // the source clone or template files is judged on, and warned about,
+  // everything else it names.
+  const taskTokens = toolName === 'Bash'
+    ? String(toolInput.command || '').split(/\s+/).map((t) => t.replace(/^["']+|["']+$/g, ''))
+    : [toolInput.file_path, toolInput.path].filter(Boolean);
+  const judged = taskTokens
+    .filter((t) => !isTaskWorktreeWrite(root, t))
+    .join(' ')
+    .replace(/\\/g, '/');
+
+  // For Bash commands, check if the command targets allowed paths
+  if (toolName === 'Bash') {
+    const cmd = toolInput.command || '';
+    if (/^\s*(git|ls|cat|head|tail|grep|rg|find|echo|pwd|cd|which|node\s+-c)\b/.test(cmd)) {
+      respond();
+      process.exit(0);
+    }
+    if (cmd.includes(scratchpadName) || cmd.includes('local-only-')) {
+      respond();
+      process.exit(0);
+    }
+    // Allow helper script invocations from the workspace root
+    if (/node\s+.*\.claude\/scripts\//.test(cmd)) {
+      respond();
+      process.exit(0);
+    }
+  }
+
+  // Check if this write targets repos/, workspace-context/, work-sessions/, or template files
+  const isRepoWrite = /(?:^|[\s/])repos\//.test(judged) || judged.includes('work-sessions/');
+  const isContextWrite = judged.includes('workspace-context/') && !basename(filePathArg).startsWith('local-only-');
+  const isTemplateWrite = judged.includes('.claude/') && !judged.includes(scratchpadName);
+
+  if (isRepoWrite || isContextWrite || isTemplateWrite) {
+    respond("You're on main. All work should happen in a workspace worktree. Run /start-work to create or resume a work session.");
+    process.exit(0);
+  }
+
+  respond();
+}
+
+if (isMainModule(import.meta.url)) {
+  await main();
+}

package/template/{.claude → _claude}/hooks/session-start.mjs

@@ -16,6 +16,7 @@ import {
   sessionFolderPath,
   timeAgo,
 } from './_utils.mjs';
+import { reconcile, readSessionRegistry, resolveChatName } from '../scripts/chat-record.mjs';
 
 const root = getWorkspaceRoot(import.meta.url);
 const input = await readStdin();
@@ -34,6 +35,40 @@ if (!config) {
 
 lines.push(`Workspace: ${config.workspace?.name || 'unnamed'}`);
 
+// Keep this chat's record in step with its identity (gh:132). The record is
+// keyed on sessionId and filed under the chat name, so a rename moves the file
+// and its drawer rather than orphaning them.
+//
+// No live set is passed, deliberately: the registry lists running processes,
+// not chats that exist, so a chat the operator merely closed is
+// indistinguishable from one that is gone. Pruning here would delete the scope
+// and open tasks of every chat not currently open.
+if (chatId) {
+  try {
+    const registry = readSessionRegistry();
+    const me = registry.find((r) => r.sessionId === chatId);
+    // The registry only knows names for chats it has seen. An unnamed chat
+    // keeps whatever name its record already carries rather than being
+    // relabeled with its raw UUID; only a truly new chat falls back to the id.
+    const name = resolveChatName(root, { sessionId: chatId, registryName: me?.name });
+    const res = reconcile(root, { sessionId: chatId, name });
+    if (res.renamed) {
+      lines.push(`Chat renamed: ${res.renamed.from} -> ${res.renamed.to} (record and drawer moved)`);
+    }
+    // Name the record so a skill can find its own chat's state without
+    // guessing (gh:132) — /start-work's task flow keys off this line.
+    lines.push(`Chat record: ${name}`);
+  } catch {
+    // The chat record is a convenience, not a precondition for a session.
+    // A failure here must never stop Claude from starting.
+  }
+
+  // Name the workspace root so skills can address it without deriving it
+  // from git internals — which resolve to the source clone, not the
+  // launcher, when a chat runs from inside a task worktree (gh:132).
+  lines.push(`Workspace root: ${root}`);
+}
+
 // If we're inside a workspace worktree, its .claude/.active-session.json
 // tells us which session this is.
 const pointer = getActiveSessionPointer(root);
@@ -117,7 +152,6 @@ if (trackers.length > 0) {
 // Surface team-shared workspace context (secondary)
 // Only scan shared/ — locked/ is now a sub-dir of shared/ and is included
 // naturally. team-member/ is per-user (loaded via CLAUDE.local.md).
-// release-notes/ is operational, not knowledge.
 if (existsSync(sharedDir)) {
   const entries = [];
 

package/template/_claude/hooks/subagent-start.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// SubagentStart hook — give subagents the workspace's canonical truths.
+//
+// Subagents do not load CLAUDE.md, so without this they start with no team context.
+// They do, however, get a full model context window and their own file tools, so the
+// right shape is not "paste everything" — it is: inline the short constraints that
+// should frame every task, and hand over a pointer for the long reference material.
+// That follows the just-in-time guidance and keeps the injection stable as canon grows.
+import { readdirSync, readFileSync, existsSync, statSync } from 'fs';
+import { join, basename, relative, sep } from 'path';
+import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
+import {
+  readDescription,
+  gitIgnoredPaths,
+  stripFrontmatter,
+  isLocalOnlyName,
+} from '../scripts/build-workspace-context.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const config = readJSON(join(root, 'workspace.json'));
+const lockedRel = 'workspace-context/shared/locked';
+const lockedDir = join(root, 'workspace-context', 'shared', 'locked');
+
+// Per-file ceiling for inlining. Files above it become pointers regardless of headroom,
+// so one long document cannot crowd out every short constraint.
+const inlineMax = config?.workspace?.subagentInlineMaxBytes || 8192;
+// Total ceiling as a backstop. Overflow demotes the largest inlined files to pointers.
+const totalMax = config?.workspace?.subagentContextMaxBytes || 32768;
+
+if (!existsSync(lockedDir)) {
+  respond();
+  process.exit(0);
+}
+
+let names = [];
+try {
+  names = readdirSync(lockedDir).filter((f) => f.endsWith('.md') && f !== '.keep').sort();
+} catch {
+  respond();
+  process.exit(0);
+}
+
+// canonical.md excludes gitignored files; this path must match it. Without the filter a
+// local-only-*.md dropped into shared/locked/ is broadcast to every subagent.
+const relPaths = names.map((n) => relative(root, join(lockedDir, n)).split(sep).join('/'));
+let ignored = new Set();
+try {
+  ignored = gitIgnoredPaths(root, relPaths);
+} catch {
+  /* filter unavailable — fall through with nothing ignored */
+}
+
+const entries = [];
+for (let i = 0; i < names.length; i++) {
+  // gitIgnoredPaths fails open when git is unavailable; local-only-* is excluded by
+  // name as well so a non-git workspace cannot broadcast a private file to subagents.
+  if (ignored.has(relPaths[i]) || isLocalOnlyName(names[i])) continue;
+  const file = join(lockedDir, names[i]);
+  let content = '';
+  let size = 0;
+  try {
+    content = readFileSync(file, 'utf-8');
+    size = statSync(file).size;
+  } catch {
+    continue;
+  }
+  entries.push({
+    name: basename(names[i], '.md'),
+    path: `${lockedRel}/${names[i]}`,
+    description: readDescription(file),
+    content,
+    size,
+    inline: size <= inlineMax,
+  });
+}
+
+if (entries.length === 0) {
+  respond();
+  process.exit(0);
+}
+
+const render = () => {
+  const inlined = entries.filter((e) => e.inline);
+  const pointers = entries.filter((e) => !e.inline);
+  const parts = [];
+  if (inlined.length > 0) {
+    parts.push('Canonical workspace context (team truths that apply to every task):');
+    for (const e of inlined) parts.push(`\n--- ${e.name} (${e.path}) ---\n${stripFrontmatter(e.content).trim()}`);
+  }
+  if (pointers.length > 0) {
+    parts.push(
+      '\nAlso canonical, not inlined here — read the file if your task touches it:',
+      ...pointers.map((e) => `- ${e.name} — ${e.description} [${e.path}, ${e.size} bytes]`),
+    );
+  }
+  return parts.join('\n');
+};
+
+// Demote largest-first until the total fits. Short constraints survive; long reference
+// material degrades to a pointer, which is what it should have been anyway.
+let out = render();
+while (
+  Buffer.byteLength(out) > totalMax &&
+  entries.some((e) => e.inline)
+) {
+  const biggest = entries.filter((e) => e.inline).sort((a, b) => b.size - a.size)[0];
+  biggest.inline = false;
+  out = render();
+}
+
+respond(out);