@ulysses-ai/create-workspace 0.15.0-beta.0 → 0.15.0-beta.1

package/lib/init.mjs

@@ -50,37 +50,24 @@ export async function initWorkspace(targetDir) {
     console.log(`  Installed ${dir}`);
   }
 
-  // Create shared-context structure. We always want shared-context/ and
-  // shared-context/locked/ to exist after init, even if the payload ships
-  // no files for them yet — locked/ is referenced by CLAUDE.md.tmpl via
-  // the @shared-context/locked/ import directive.
-  const payloadContext = join(payloadDir, 'shared-context');
-  const targetContext = join(targetDir, 'shared-context');
-  if (existsSync(payloadContext) && !existsSync(targetContext)) {
-    cpSync(payloadContext, targetContext, { recursive: true });
-    console.log('  Created shared-context/');
-  }
-  ensureDir(join(targetDir, 'shared-context', 'locked'));
+  // Ensure workspace-context/locked/ exists. canonical.md and index.md are
+  // generated later by /workspace-init via build-workspace-context.mjs;
+  // this just guarantees the destination directory is in place.
+  ensureDir(join(targetDir, 'workspace-context', 'locked'));
 
   // Everything else (repos/, work-sessions/, workspace-scratchpad/) is
   // lazy-created by scripts and hooks when they first need to write.
   // We intentionally do NOT pre-create these dirs — they get made on demand.
 
-  // Create workspace.json if missing
+  // Create workspace.json from template if missing. Single source of truth
+  // for shape is template/workspace.json.tmpl — mirrors the CLAUDE.md.tmpl
+  // handling below.
   if (!existsSync(workspaceJsonPath)) {
-    writeFileSync(workspaceJsonPath, JSON.stringify({
-      workspace: {
-        name,
-        templateVersion: toVersion,
-        scratchpadDir: 'workspace-scratchpad',
-        workSessionsDir: 'work-sessions',
-        sharedContextDir: 'shared-context',
-        releaseNotesDir: 'release-notes',
-        subagentContextMaxBytes: 10240,
-        greeting: `Welcome back to ${name}.`,
-      },
-      repos: {},
-    }, null, 2) + '\n');
+    const wsTmplPath = join(payloadDir, 'workspace.json.tmpl');
+    const wsTmpl = readFileSync(wsTmplPath, 'utf-8').replace(/\{\{project-name\}\}/g, name);
+    const workspaceConfig = JSON.parse(wsTmpl);
+    workspaceConfig.workspace.templateVersion = toVersion;
+    writeFileSync(workspaceJsonPath, JSON.stringify(workspaceConfig, null, 2) + '\n');
     console.log('  Created workspace.json');
   }
 

package/lib/scaffold.mjs

@@ -20,10 +20,11 @@ export async function scaffold(answers) {
     },
   });
 
-  // Ensure shared-context/locked/ exists so the CLAUDE.md import resolves.
+  // Ensure workspace-context/locked/ exists. canonical.md and index.md are
+  // generated later by /workspace-init via build-workspace-context.mjs;
   // repos/, work-sessions/, and workspace-scratchpad/ are lazy-created when
   // scripts and hooks first need them — we do NOT pre-create them here.
-  mkdirSync(join(directory, 'shared-context', 'locked'), { recursive: true });
+  mkdirSync(join(directory, 'workspace-context', 'locked'), { recursive: true });
 
   // Rename _gitignore to .gitignore
   const gitignoreSrc = join(directory, '_gitignore');

package/package.json

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

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

@@ -34,6 +34,7 @@ Every workspace-context file should have YAML frontmatter. The fields below are
 - `state` — `locked` (team truth) or `ephemeral` (working context). Locked files live under `shared/locked/`; ephemeral files live elsewhere under `shared/` or `team-member/{user}/`.
 - `lifecycle` — for ephemeral files: `active` (still relevant) or `resolved` (handled, kept for record).
 - `type` — kind of content: `reference`, `braindump`, `handoff`, `research`, `design`, `index`, `canonical`, `promoted`.
+- `priority` — for locked files only: `critical` (always loaded into canonical) or `reference` (eligible for trim/stub under canonical budget pressure). Default when absent is `critical`. See `build-workspace-context.mjs` for selection semantics.
 - `topic` — kebab-case slug matching the filename (after the type prefix, when one is present).
 - `author` — username scope owner. Required for `team-member/{user}/` files.
 - `updated` — ISO date of last meaningful edit. `/maintenance` flags stale `lifecycle: active` files based on this.
@@ -71,6 +72,8 @@ A single generator at `.claude/scripts/build-workspace-context.mjs` produces thr
 
 Gitignored files (e.g. anything matching `local-only-*`) are excluded automatically, and `workspace-context/.indexignore` adds path-prefix excludes for tracked files that shouldn't appear in the shared index (e.g. archived release notes).
 
+When `workspace-context/canonical.md` exceeds `workspace.canonicalBudgetBytes` (default 40960), the builder honors per-file `priority` and section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` markers to fit: `priority: reference` files are trimmed first, then stubbed, while `priority: critical` files are always included in full. `/maintenance` audits the budget and offers a triage flow when over.
+
 ```bash
 node .claude/scripts/build-workspace-context.mjs --check --root .   # exits 1 if any artifact is stale or missing
 node .claude/scripts/build-workspace-context.mjs --write --root .   # regenerate all three

package/template/.claude/scripts/build-workspace-context.mjs

@@ -9,12 +9,23 @@
 // 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
+// `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.
+//
 // Usage:
 //   node build-workspace-context.mjs --write [--root <workspace-root>]
 //   node build-workspace-context.mjs --check [--root <workspace-root>]
 //
 // --write regenerates all three artifacts.
-// --check exits 0 if everything matches, 1 if any is stale or missing. Reports per-file status.
+// --check exit codes:
+//   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
+// Stale wins over over-budget when both apply.
 
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, realpathSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
@@ -29,6 +40,8 @@ function isMainModule(metaUrl) {
   } catch { return false; }
 }
 
+export const DEFAULT_CANONICAL_BUDGET = 40960;
+
 const WC_DIR = 'workspace-context';
 const SHARED_DIR = 'shared';
 const LOCKED_DIR = 'locked';
@@ -190,37 +203,334 @@ function renderSharedIndex(entries, generatedAt) {
 
 // ---------- canonical concat ----------
 
+const TRIM_OPEN_RE = /<!--\s*canonical:trim\s*-->/g;
+const TRIM_CLOSE_RE = /<!--\s*canonical:end-trim\s*-->/g;
+const TRIM_BLOCK_RE = /<!--\s*canonical:trim\s*-->[\s\S]*?<!--\s*canonical:end-trim\s*-->\n?/g;
+const ANY_MARKER_RE = /<!--\s*canonical:(?:end-)?trim\s*-->\n?/g;
+
+/**
+ * Validate that canonical:trim markers are well-formed in `body`. Throws an
+ * Error if an opener has no matching closer, or if a second opener appears
+ * before the corresponding end-trim. Used by extractCanonicalVariants.
+ */
+function validateTrimMarkers(body, name) {
+  let depth = 0;
+  let idx = 0;
+  while (idx < body.length) {
+    TRIM_OPEN_RE.lastIndex = idx;
+    TRIM_CLOSE_RE.lastIndex = idx;
+    const openMatch = TRIM_OPEN_RE.exec(body);
+    const closeMatch = TRIM_CLOSE_RE.exec(body);
+    const openAt = openMatch ? openMatch.index : -1;
+    const closeAt = closeMatch ? closeMatch.index : -1;
+    if (openAt === -1 && closeAt === -1) break;
+    if (openAt !== -1 && (closeAt === -1 || openAt < closeAt)) {
+      if (depth > 0) {
+        throw new Error(`canonical:trim parse error in ${name}: nested opener at offset ${openAt}`);
+      }
+      depth = 1;
+      idx = openAt + openMatch[0].length;
+    } else {
+      if (depth === 0) {
+        throw new Error(`canonical:trim parse error in ${name}: unmatched end-trim at offset ${closeAt}`);
+      }
+      depth = 0;
+      idx = closeAt + closeMatch[0].length;
+    }
+  }
+  if (depth !== 0) {
+    throw new Error(`canonical:trim parse error in ${name}: unmatched opener (no end-trim before EOF)`);
+  }
+}
+
+/**
+ * Collapse runs of three or more consecutive newlines to two so that variant
+ * outputs do not grow extra blank lines after marker removal.
+ */
+function collapseBlankLines(s) {
+  return s.replace(/\n{3,}/g, '\n\n');
+}
+
+/**
+ * Compute the three body variants for a single locked file.
+ *
+ * Inputs: { name, rawContent } where rawContent is the file as read from disk
+ * (frontmatter still present). Output: { full, trimmed, stub } — each is the
+ * body string used for canonical rendering when that variant is selected.
+ *
+ * - `full` — frontmatter stripped, all `canonical:trim`/`canonical:end-trim`
+ *   marker lines removed but their content kept.
+ * - `trimmed` — fenced spans (markers + content) replaced with a one-line
+ *   breadcrumb. Consecutive breadcrumbs collapse to one. Bare markers are
+ *   stripped defensively.
+ * - `stub` — the entire body is replaced with a one-line breadcrumb pointing
+ *   to the source file.
+ *
+ * Throws if markers are malformed (unmatched opener or nested opener).
+ */
+export function extractCanonicalVariants({ name, rawContent }) {
+  const body = stripFrontmatter(rawContent);
+  validateTrimMarkers(body, name);
+
+  // full: drop all marker lines but keep content.
+  const full = collapseBlankLines(body.replace(ANY_MARKER_RE, '')).trimEnd();
+
+  // trimmed: replace fenced spans with breadcrumb, collapse consecutive
+  // breadcrumbs, then strip any remaining bare markers (defensive).
+  const breadcrumb = `> _Trimmed for canonical budget — see \`shared/locked/${name}.md\` for full content._\n`;
+  let trimmed = body.replace(TRIM_BLOCK_RE, breadcrumb);
+  // Collapse consecutive identical breadcrumb lines into one.
+  const breadcrumbLine = breadcrumb.trimEnd();
+  const escapedBreadcrumb = breadcrumbLine.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const consecutiveBreadcrumbs = new RegExp(`(?:${escapedBreadcrumb}\\n)+`, 'g');
+  trimmed = trimmed.replace(consecutiveBreadcrumbs, breadcrumb);
+  trimmed = trimmed.replace(ANY_MARKER_RE, '');
+  trimmed = collapseBlankLines(trimmed).trimEnd();
+
+  const stub = `> _Dropped for canonical budget — see \`shared/locked/${name}.md\`._`;
+
+  return { full, trimmed, stub };
+}
+
+/**
+ * Read `workspace.canonicalBudgetBytes` from `workspace.json`.
+ * 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.
+ *   - 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;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (err) {
+    process.stderr.write(`warning: failed to parse workspace.json (${err.message}); using default canonical budget\n`);
+    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;
+  const v = ws.canonicalBudgetBytes;
+  if (typeof v !== 'number' || !Number.isFinite(v)) return DEFAULT_CANONICAL_BUDGET;
+  if (v <= 0) return 0;
+  return Math.floor(v);
+}
+
+/**
+ * Render just the per-item body of canonical (no frontmatter, no header).
+ * Pure function used both by selectCanonicalContent (to measure body bytes)
+ * and by renderCanonical (to emit the final document).
+ */
+export function renderCanonicalBody(resolvedItems) {
+  if (resolvedItems.length === 0) return '';
+  const parts = [];
+  for (const item of resolvedItems) {
+    parts.push(`## ${item.name}\n\n${item.content}\n`);
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Pick a canonical resolution that fits the budget when possible.
+ *
+ * Items shape: { name, priority, full, trimmed, stub }.
+ * Returns { resolvedItems, selection } where selection has:
+ *   - status: 'ok' | 'trimmed' | 'stubbed' | 'over-budget'
+ *   - budgetBytes: number or null (null when budget is disabled)
+ *   - currentBytes: body bytes after the chosen resolution
+ *   - overBy?: number (present when status === 'over-budget')
+ *   - trimmedFiles, stubbedFiles: names of items resolved that way
+ *
+ * Algorithm (deterministic, four stages):
+ *   1. All items → full. If body ≤ budget: status `ok`.
+ *   2. Reference items → trimmed; critical → full. If ≤ budget: `trimmed`.
+ *   3. Reference items → stub; critical → full. If ≤ budget: `stubbed`.
+ *   4. Keep stage-3 resolution; status `over-budget`, overBy populated.
+ *
+ * Special cases:
+ *   - budgetBytes <= 0: 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.
+ */
+export function selectCanonicalContent(items, budgetBytes, opts) {
+  const measure = opts && typeof opts.measureBodyBytes === 'function'
+    ? opts.measureBodyBytes
+    : (resolved) => Buffer.byteLength(renderCanonicalBody(resolved), 'utf-8');
+
+  const resolveAt = (stage) => items.map((item) => {
+    if (stage === 1) return { name: item.name, priority: item.priority, content: item.full };
+    if (item.priority === 'reference') {
+      return {
+        name: item.name,
+        priority: item.priority,
+        content: stage === 2 ? item.trimmed : item.stub,
+      };
+    }
+    return { name: item.name, priority: item.priority, content: item.full };
+  });
+
+  // Disabled-budget path.
+  if (!Number.isFinite(budgetBytes) || budgetBytes <= 0) {
+    const resolved = resolveAt(1);
+    return {
+      resolvedItems: resolved,
+      selection: {
+        status: 'ok',
+        budgetBytes: null,
+        currentBytes: measure(resolved),
+        trimmedFiles: [],
+        stubbedFiles: [],
+      },
+    };
+  }
+
+  // Stage 1: full.
+  const stage1 = resolveAt(1);
+  const stage1Bytes = measure(stage1);
+  if (stage1Bytes <= budgetBytes) {
+    return {
+      resolvedItems: stage1,
+      selection: {
+        status: 'ok',
+        budgetBytes,
+        currentBytes: stage1Bytes,
+        trimmedFiles: [],
+        stubbedFiles: [],
+      },
+    };
+  }
+
+  const referenceNames = items.filter((i) => i.priority === 'reference').map((i) => i.name);
+
+  // No reference files exist → cannot trim. Report over-budget at stage 1.
+  if (referenceNames.length === 0) {
+    process.stderr.write('warning: no priority:reference files exist — consider demoting one via /maintenance cleanup\n');
+    return {
+      resolvedItems: stage1,
+      selection: {
+        status: 'over-budget',
+        budgetBytes,
+        currentBytes: stage1Bytes,
+        overBy: stage1Bytes - budgetBytes,
+        trimmedFiles: [],
+        stubbedFiles: [],
+      },
+    };
+  }
+
+  // Stage 2: trim reference files.
+  const stage2 = resolveAt(2);
+  const stage2Bytes = measure(stage2);
+  if (stage2Bytes <= budgetBytes) {
+    return {
+      resolvedItems: stage2,
+      selection: {
+        status: 'trimmed',
+        budgetBytes,
+        currentBytes: stage2Bytes,
+        trimmedFiles: referenceNames,
+        stubbedFiles: [],
+      },
+    };
+  }
+
+  // Stage 3: stub reference files.
+  const stage3 = resolveAt(3);
+  const stage3Bytes = measure(stage3);
+  if (stage3Bytes <= budgetBytes) {
+    return {
+      resolvedItems: stage3,
+      selection: {
+        status: 'stubbed',
+        budgetBytes,
+        currentBytes: stage3Bytes,
+        trimmedFiles: [],
+        stubbedFiles: referenceNames,
+      },
+    };
+  }
+
+  // Stage 4: still over. Keep stage-3 resolution.
+  return {
+    resolvedItems: stage3,
+    selection: {
+      status: 'over-budget',
+      budgetBytes,
+      currentBytes: stage3Bytes,
+      overBy: stage3Bytes - budgetBytes,
+      trimmedFiles: [],
+      stubbedFiles: referenceNames,
+    },
+  };
+}
+
 function buildCanonical(workspaceRoot) {
   const lockedDir = join(workspaceRoot, WC_DIR, SHARED_DIR, LOCKED_DIR);
   if (!existsSync(lockedDir)) return [];
-  return walkMarkdown(lockedDir)
-    .filter((f) => !f.endsWith('.keep'))
-    .sort()
-    .map((f) => ({
-      name: f.split(sep).pop().replace(/\.md$/, ''),
-      content: stripFrontmatter(readFileSync(f, 'utf-8')).trimEnd(),
-    }));
+  const files = walkMarkdown(lockedDir).filter((f) => !f.endsWith('.keep')).sort();
+  const items = [];
+  for (const f of files) {
+    const name = f.split(sep).pop().replace(/\.md$/, '');
+    const rawContent = readFileSync(f, 'utf-8');
+    let priority = 'critical';
+    try {
+      const parsed = parseSessionContent(rawContent);
+      const fields = parsed.fields || {};
+      if (typeof fields.priority === 'string' && fields.priority.trim()) {
+        priority = fields.priority.trim();
+      }
+    } catch {
+      // No parseable frontmatter — keep default 'critical'.
+    }
+    const variants = extractCanonicalVariants({ name, rawContent });
+    if (priority === 'reference' && variants.trimmed === variants.full) {
+      process.stderr.write(`warning: reference file '${name}' has no canonical:trim markers; trimming is a no-op for it\n`);
+    }
+    items.push({ name, priority, full: variants.full, trimmed: variants.trimmed, stub: variants.stub });
+  }
+  return items;
+}
+
+function summarizeSelection(selection) {
+  if (selection.status === 'ok') return 'full';
+  if (selection.status === 'trimmed') return `${selection.trimmedFiles.length} reference files trimmed`;
+  if (selection.status === 'stubbed') return `${selection.stubbedFiles.length} reference files stubbed`;
+  return `over budget by ${selection.overBy} bytes`;
 }
 
-function renderCanonical(items, generatedAt) {
+function renderCanonical(resolvedItems, selection, generatedAt) {
+  const showBudget = selection && selection.budgetBytes !== null && selection.budgetBytes !== undefined;
+  const fmLines = ['---', 'type: canonical', `generated: ${generatedAt}`];
+  if (showBudget) {
+    fmLines.push(`budget: ${selection.budgetBytes}`);
+    fmLines.push(`status: ${selection.status}`);
+  }
+  fmLines.push('---', '');
+
   const lines = [
-    '---',
-    'type: canonical',
-    `generated: ${generatedAt}`,
-    '---',
-    '',
+    ...fmLines,
     '# workspace-context — canonical truths',
     '',
     '> Auto-generated concatenation of `shared/locked/*.md`. Hand edits will be overwritten — update source files instead.',
-    '',
   ];
-  for (const item of items) {
-    lines.push(`## ${item.name}`, '', item.content, '');
+  if (showBudget) {
+    lines.push(
+      `> Budget: ${selection.budgetBytes} bytes (body); current: ${selection.currentBytes} bytes; status: ${selection.status} (${summarizeSelection(selection)}).`,
+    );
   }
-  if (items.length === 0) {
+  lines.push('');
+
+  if (resolvedItems.length === 0) {
     lines.push('_(no canonical entries yet — promote one via `/release`)_', '');
+    return lines.join('\n');
   }
-  return lines.join('\n');
+
+  const body = renderCanonicalBody(resolvedItems);
+  // body already ends with \n (each item ends in \n, joined by \n). Append directly.
+  return lines.join('\n') + body;
 }
 
 // ---------- team-member indexes ----------
@@ -300,10 +610,15 @@ function regenerateAll(workspaceRoot, generatedAt) {
   });
 
   const canonicalItems = buildCanonical(workspaceRoot);
+  const budget = readWorkspaceBudget(workspaceRoot);
+  const { resolvedItems, selection } = selectCanonicalContent(canonicalItems, budget, {
+    measureBodyBytes: (resolved) => Buffer.byteLength(renderCanonicalBody(resolved), 'utf-8'),
+  });
   out.push({
     path: join(wcRoot, CANONICAL_FILENAME),
     label: 'canonical.md',
-    content: renderCanonical(canonicalItems, generatedAt) + '\n',
+    content: renderCanonical(resolvedItems, selection, generatedAt) + '\n',
+    selection,
   });
 
   for (const user of listTeamMembers(workspaceRoot)) {
@@ -318,6 +633,19 @@ function regenerateAll(workspaceRoot, generatedAt) {
   return out;
 }
 
+/**
+ * CLI entry point.
+ *
+ * Exit codes for `--check`:
+ *   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
+ *       `/maintenance cleanup`. If both stale and over-budget, exit 1.
+ *
+ * `--write` always exits 0 on successful regeneration; over-budget is
+ * surfaced as a stderr warning during selection but does not block the write.
+ */
 function main() {
   const args = parseArgs(process.argv);
   const generatedAt = new Date().toISOString();
@@ -331,11 +659,30 @@ function main() {
       const onDisk = readFileSync(a.path, 'utf-8');
       if (fingerprint(onDisk) !== fingerprint(a.content)) stale.push(a.label);
     }
+
+    const canonicalArtifact = artifacts.find((a) => a.label === 'canonical.md');
+    const sel = canonicalArtifact ? canonicalArtifact.selection : null;
+    const canonicalBlock = sel ? {
+      budget: sel.budgetBytes,
+      current: sel.currentBytes,
+      ...(sel.overBy !== undefined ? { overBy: sel.overBy } : {}),
+      selectionStatus: sel.status,
+      trimmedFiles: sel.trimmedFiles,
+      stubbedFiles: sel.stubbedFiles,
+    } : null;
+
     if (missing.length === 0 && stale.length === 0) {
-      process.stdout.write(JSON.stringify({ status: 'current', artifacts: artifacts.length }) + '\n');
-      process.exit(0);
+      const overBudget = sel && sel.status === 'over-budget';
+      const payload = { status: 'current', missing: [], stale: [] };
+      if (canonicalBlock) payload.canonical = canonicalBlock;
+      payload.artifacts = artifacts.length;
+      process.stdout.write(JSON.stringify(payload) + '\n');
+      process.exit(overBudget ? 2 : 0);
     }
-    process.stdout.write(JSON.stringify({ status: 'stale', missing, stale }) + '\n');
+
+    const payload = { status: 'stale', missing, stale };
+    if (canonicalBlock) payload.canonical = canonicalBlock;
+    process.stdout.write(JSON.stringify(payload) + '\n');
     process.exit(1);
   }
 

package/template/.claude/scripts/migrate-canonical-priority.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Idempotent migrator: back-fill `priority: critical` on locked workspace-context
+// files that lack the field. Default-to-critical preserves existing behavior —
+// no surprise drops on upgrade.
+//
+// Usage:
+//   node migrate-canonical-priority.mjs [--root <path>]
+//
+// Walks <root>/workspace-context/shared/locked/*.md. For each file:
+//   - Skip non-.md files and files without parseable frontmatter (warn to stderr).
+//   - If `priority` is already set (any value), leave the file untouched.
+//   - Otherwise add `priority: critical` losslessly via updateSessionContent.
+//
+// Returns { status, files: { applied, unchanged } } where status is 'applied'
+// when at least one file was modified, else 'noop'. Always exits 0 — idempotent
+// migrations don't fail.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  realpathSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSessionContent, updateSessionContent } from '../lib/session-frontmatter.mjs';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+function parseArgs(argv) {
+  const args = { root: process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--root') args.root = argv[++i];
+    else throw new Error(`Unknown arg: ${a}`);
+  }
+  return args;
+}
+
+export function migrateCanonicalPriority({ root }) {
+  const absRoot = resolve(root);
+  const lockedDir = join(absRoot, 'workspace-context', 'shared', 'locked');
+  const files = { applied: [], unchanged: [] };
+
+  if (!existsSync(lockedDir)) {
+    return { status: 'noop', files };
+  }
+
+  let entries;
+  try {
+    entries = readdirSync(lockedDir).sort();
+  } catch {
+    return { status: 'noop', files };
+  }
+
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const full = join(lockedDir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (!st.isFile()) continue;
+
+    const raw = readFileSync(full, 'utf-8');
+    let parsed;
+    try {
+      parsed = parseSessionContent(raw);
+    } catch {
+      console.error(`warning: skipping ${full}: no parseable frontmatter`);
+      continue;
+    }
+
+    if (parsed?.fields?.priority !== undefined) {
+      files.unchanged.push(name);
+      continue;
+    }
+
+    const updated = updateSessionContent(raw, { priority: 'critical' });
+    writeFileSync(full, updated);
+    files.applied.push(name);
+  }
+
+  return {
+    status: files.applied.length > 0 ? 'applied' : 'noop',
+    files,
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const result = migrateCanonicalPriority({ root: args.root });
+  process.stdout.write(JSON.stringify(result) + '\n');
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`migrate-canonical-priority: ${err.message}\n`);
+    process.exit(1);
+  }
+}