@ulysses-ai/create-workspace 0.16.0-beta.1 → 0.18.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,9 +88,9 @@ Four things, in the order you'll touch them:
 
 A scaffolded workspace with:
 
-- **14 skills** covering the workflow lifecycle, releases, handoffs, and maintenance
-- **8 active rules** + **8 optional `.skip` rules** for behaviors you can opt into
-- **10 hooks** for SessionStart, SubagentStart, PreCompact, WorktreeCreate, and the rest of the small set the conventions rely on
+- **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)
 - Conventions for **multi-repo work sessions** with isolated git worktrees, parallelizable from separate terminals
 

package/lib/init.mjs

@@ -105,6 +105,25 @@ export async function initWorkspace(targetDir) {
     }
   }
 
+  // Set up .claudeignore
+  const payloadClaudeignore = join(payloadDir, '.claudeignore');
+  const claudeignorePath = join(targetDir, '.claudeignore');
+  if (existsSync(payloadClaudeignore)) {
+    if (existsSync(claudeignorePath)) {
+      const existing = readFileSync(claudeignorePath, 'utf-8');
+      const template = readFileSync(payloadClaudeignore, 'utf-8');
+      const existingLines = new Set(existing.split('\n').map(l => l.trim()));
+      const newLines = template.split('\n').filter(l => l.trim() && !existingLines.has(l.trim()));
+      if (newLines.length > 0) {
+        writeFileSync(claudeignorePath, existing.trimEnd() + '\n\n# From workspace template\n' + newLines.join('\n') + '\n');
+        console.log('  Merged template entries into .claudeignore');
+      }
+    } else {
+      cpSync(payloadClaudeignore, claudeignorePath);
+      console.log('  Created .claudeignore');
+    }
+  }
+
   console.log(`
   Workspace initialized (v${toVersion}).
 

package/package.json

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

package/template/.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

@@ -6,7 +6,11 @@
 //   Workspace worktree: work-sessions/{name}/workspace/
 //   Project worktree:   work-sessions/{name}/workspace/repos/{repo}/
 //   Bare clone:         repos/{repo}/  (at workspace root)
-import { join, basename } from 'path';
+//   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,
@@ -17,91 +21,184 @@ import {
   getWorkspacePaths,
 } from './_utils.mjs';
 
-const root = getWorkspaceRoot(import.meta.url);
-const input = await readStdin();
-const toolName = input.tool_name || '';
+// .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);
+}
 
-if (!['Bash', 'Edit', 'Write'].includes(toolName)) {
-  respond();
-  process.exit(0);
+// 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; }
 }
 
-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);
-      }
-    }
+// 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;
   }
+}
 
-  respond();
-  process.exit(0);
+// 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);
 }
 
-// We're at the main workspace root — restrict writes
+/**
+ * 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));
 
-const { scratchpadDir } = getWorkspacePaths(root);
-const scratchpadName = scratchpadDir.slice(root.length + 1); // "workspace-scratchpad"
+  // 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;
+  }
 
-// Allow writes to the workspace scratchpad
-if (paths.includes(scratchpadName)) {
-  respond();
-  process.exit(0);
+  // 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';
 }
 
-// Allow writes to local-only-* files
-const filePathArg = toolInput.file_path || '';
-if (basename(filePathArg).startsWith('local-only-')) {
-  respond();
-  process.exit(0);
-}
+async function main() {
+  const root = getWorkspaceRoot(import.meta.url);
+  const input = await readStdin();
+  const toolName = input.tool_name || '';
 
-// 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)) {
+  if (!['Bash', 'Edit', 'Write'].includes(toolName)) {
     respond();
     process.exit(0);
   }
-  if (cmd.includes(scratchpadName) || cmd.includes('local-only-')) {
+
+  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);
   }
-  // Allow helper script invocations from the workspace root
-  if (/node\s+.*\.claude\/scripts\//.test(cmd)) {
+
+  // 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);
   }
-}
 
-// Check if this write targets repos/, workspace-context/, work-sessions/, or template files
-const isRepoWrite = /(?:^|[\s/])repos\//.test(paths) || paths.includes('work-sessions/');
-const isContextWrite = paths.includes('workspace-context/') && !basename(filePathArg).startsWith('local-only-');
-const isTemplateWrite = paths.includes('.claude/') && !paths.includes(scratchpadName);
+  // Allow writes to local-only-* files
+  const filePathArg = toolInput.file_path || '';
+  if (basename(filePathArg).startsWith('local-only-')) {
+    respond();
+    process.exit(0);
+  }
 
-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);
+  // 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();
 }
 
-respond();
+if (isMainModule(import.meta.url)) {
+  await main();
+}

package/template/.claude/hooks/session-end.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 // SessionEnd hook — mark this chat's `ended` timestamp in the session
-// tracker and append a small safety-net note to the session.md body.
-import { appendFileSync, mkdirSync, existsSync } from 'fs';
+// tracker, append a small safety-net note to the session.md body, and
+// write a disk-durable reflection record if the session.md ## Progress
+// section contains heuristic correction-pattern sentences.
+import { appendFileSync, mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';
 import {
@@ -71,6 +73,70 @@ if (pointer && sessionId) {
       } catch {
         // Non-fatal
       }
+
+      // Disk-durable reflection sub-step (BP-10).
+      // Read the ## Progress section of session.md (last 2000 chars max),
+      // scan for heuristic correction-pattern sentences, and write any
+      // candidates to workspace-scratchpad/session-reflect.json. The file
+      // is gitignored (workspace-scratchpad/ is in _gitignore). We do NOT
+      // emit additionalContext for this — per the canonical known limitation,
+      // additionalContext does not always reach Claude. Disk is the primary
+      // durable output.
+      try {
+        const sessionContent = readFileSync(trackerPath, 'utf8');
+
+        // Extract ## Progress section — find the section and take last 2000 chars.
+        const progressMatch = sessionContent.match(/^## Progress\s*\n([\s\S]*?)(?=\n^##|\s*$)/m);
+        const progressText = progressMatch
+          ? progressMatch[1].slice(-2000)
+          : sessionContent.slice(-2000);
+
+        // Split into sentences on '. ' or '.\n' boundaries.
+        const sentences = progressText
+          .split(/(?<=\.)\s+|\n/)
+          .map(s => s.trim())
+          .filter(s => s.length > 10);
+
+        // Correction-pattern keywords — case-insensitive.
+        const correctionPatterns = [
+          /actually/i,
+          /instead of/i,
+          /the right way is/i,
+          /i was wrong/i,
+          /correction:/i,
+        ];
+
+        const candidates = sentences
+          .filter(sentence => correctionPatterns.some(re => re.test(sentence)))
+          .map(text => ({ text, source: '## Progress' }));
+
+        if (candidates.length > 0) {
+          if (!existsSync(scratchpadDir)) mkdirSync(scratchpadDir, { recursive: true });
+          const reflectPath = join(scratchpadDir, 'session-reflect.json');
+
+          // Read existing records to append (create-or-append pattern).
+          let records = [];
+          if (existsSync(reflectPath)) {
+            try {
+              records = JSON.parse(readFileSync(reflectPath, 'utf8'));
+              if (!Array.isArray(records)) records = [records];
+            } catch {
+              records = [];
+            }
+          }
+
+          records.push({
+            sessionId: sessionId || `ts-${Date.now()}`,
+            date: new Date().toISOString(),
+            workSession: pointer.name,
+            candidates,
+          });
+
+          writeFileSync(reflectPath, JSON.stringify(records, null, 2), 'utf8');
+        }
+      } catch {
+        // Non-fatal — reflection is best-effort.
+      }
     }
   }
 }

package/template/.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

@@ -1,44 +1,111 @@
 #!/usr/bin/env node
-// SubagentStart hook — inject workspace-context/shared/locked/ into subagent context
-import { readdirSync, readFileSync, existsSync } from 'fs';
-import { join, basename } from 'path';
+// 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');
 
-const maxBytes = config?.workspace?.subagentContextMaxBytes || 10240;
+// 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);
 }
 
-const files = readdirSync(lockedDir)
-  .filter(f => f.endsWith('.md') && f !== '.keep')
-  .sort();
-
-if (files.length === 0) {
+let names = [];
+try {
+  names = readdirSync(lockedDir).filter((f) => f.endsWith('.md') && f !== '.keep').sort();
+} catch {
   respond();
   process.exit(0);
 }
 
-let context = '';
-for (const file of files) {
-  const name = basename(file, '.md');
-  const content = readFileSync(join(lockedDir, file), 'utf-8');
-  context += `\n--- ${name} ---\n${content}\n`;
+// 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);
 }
 
-if (Buffer.byteLength(context) > maxBytes) {
-  const summary = files.map(f => {
-    const content = readFileSync(join(lockedDir, f), 'utf-8');
-    const firstLine = content.split('\n').find(l => l.trim() && !l.startsWith('---'))?.replace(/^#*\s*/, '') || '';
-    return `- ${basename(f, '.md')}: ${firstLine}`;
-  }).join('\n');
+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');
+};
 
-  context = `[Locked shared context exceeds ${maxBytes} byte limit (${Buffer.byteLength(context)} bytes). Summary of ${files.length} files:]\n${summary}\n[Read individual files from workspace-context/shared/locked/ if you need full content.]`;
+// 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(context);
+respond(out);

package/template/.claude/lib/session-frontmatter.mjs

@@ -263,3 +263,31 @@ export function writeSessionFile(filePath, fields, body = '') {
 export function readSessionFields(filePath) {
   return readSessionFile(filePath).fields;
 }
+
+// This module is a LIBRARY, not a CLI. Several skills say "update the tracker
+// via the session-frontmatter helper", and the natural reading of that — given
+// that everything else a skill invokes (sync-tasks.mjs, create-work-session.mjs,
+// build-workspace-context.mjs) is a real CLI — is to run this file with flags.
+//
+// Without this guard, Node imports the module, finds no side effects, ignores
+// the arguments and EXITS 0. The caller sees success, the frontmatter is
+// untouched, and a `cmd || fallback` idiom never fires because exit 0 is
+// success. That silently dropped a `workItem:` linkage during the gh:89
+// session and was only caught by re-reading the file (gh:143).
+//
+// So: fail loudly and say what to call instead.
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  process.stderr.write(
+    'session-frontmatter.mjs is a library, not a CLI — it takes no arguments.\n' +
+    '\n' +
+    'Import it instead:\n' +
+    '  node --input-type=module -e \'\n' +
+    '  import { updateSessionFile } from "./.claude/lib/session-frontmatter.mjs";\n' +
+    '  updateSessionFile("session.md", { workItem: "gh:42" });\n' +
+    '  \'\n' +
+    '\n' +
+    'Exports: parseSessionContent, updateSessionContent, updateSessionFile,\n' +
+    'readSessionFile, readSessionFields, writeSessionFile.\n',
+  );
+  process.exit(2);
+}

package/template/.claude/rules/coherent-revisions.md

@@ -19,6 +19,6 @@ Injected revisions create fragmented, hard-to-follow output where the seams betw
 
 - When updating a section of a document, rewrite the entire section — not just the changed sentences
 - When updating a workspace-context file, rewrite it as a fresh snapshot of current understanding
-- When synthesizing multiple sources into release notes, write the narrative from scratch — don't concatenate
+- When synthesizing multiple sources into a PR body or summary, write the narrative from scratch — don't concatenate
 - When revising code with comments, ensure the comments tell a coherent story, not a changelog
 - Small, isolated edits (fixing a typo, updating a single value) are fine — this rule targets substantive revisions