@ulysses-ai/create-workspace 0.18.0-beta.0 → 0.20.0-beta.0

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// Measure the always-loaded context footprint of a workspace, and price a
-// proposed addition before it is written.
+// Measure the always-loaded context footprint of a workspace, price a proposed
+// addition before it is written, and check the total against a budget.
 //
 // Every unconditional rule and every locked context file is a permanent tax on
 // every session in this workspace — and, for anything shipped in the template,
@@ -11,11 +11,23 @@
 // `memory-guidance` rule both require running it before writing to an
 // always-loaded destination.
 //
+// A rule whose frontmatter declares `paths:` is conditional — Claude Code loads
+// it only when a file matching one of its globs is read — so it is listed under
+// `conditional`, excluded from the total, and priced at zero by the
+// `rule-scoped` destination.
+//
+// The budget is `workspace.alwaysLoadedBudgetBytes` from <root>/workspace.json
+// (absent means no budget); `--budget <bytes>` overrides it. With a budget set,
+// human output ends with a `BUDGET <total>/<budget> bytes — ok|OVER` line, JSON
+// gains `budget` and `overBudget`, a projection reports whether the addition
+// lands over, and the process exits 1 when the measured total is over.
+//
 // Reads only. Writes nothing. Makes no network calls.
 //
 // Usage:
 //   node context-footprint.mjs --root <dir>
 //   node context-footprint.mjs --root <dir> --json
+//   node context-footprint.mjs --root <dir> --budget <bytes>
 //   node context-footprint.mjs --root <dir> --add <bytes> --as <destination>
 //
 // Destinations for --as: rule, rule-scoped, locked, shared, team-member,
@@ -123,38 +135,86 @@ function collectRules(absRoot) {
     .map((n) => join(rulesDir, n));
 }
 
+/**
+ * Does this text carry YAML frontmatter with a top-level `paths:` key?
+ *
+ * Frontmatter on rules is a flat, hand-written key block, so a deliberately
+ * naive scan — opening `---` line, closing `---` line, any top-level `paths:`
+ * key between them — is enough. A YAML library would buy fidelity the one
+ * decision this feeds (conditional vs always-loaded) never needs.
+ */
+function frontmatterHasPaths(text) {
+  const lines = /^---\r?\n/.test(text) ? text.split(/\r?\n/) : null;
+  if (!lines) return false;
+  const close = lines.findIndex((line, i) => i > 0 && (line === '---' || line === '...'));
+  if (close === -1) return false; // no closing delimiter: not frontmatter
+  return lines.slice(1, close).some((line) => /^paths:/.test(line));
+}
+
+function ruleIsConditional(absRule) {
+  try {
+    return frontmatterHasPaths(readFileSync(absRule, 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The always-loaded budget from <root>/workspace.json, or null when the file or
+ * the `workspace.alwaysLoadedBudgetBytes` field is absent. A present but
+ * malformed workspace.json throws — silently ignoring a corrupt config would
+ * report "no budget" for a workspace that tried to set one.
+ */
+function readBudget(absRoot) {
+  const configPath = join(absRoot, 'workspace.json');
+  if (!existsSync(configPath)) return null;
+  const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+  const budget = raw?.workspace?.alwaysLoadedBudgetBytes;
+  return typeof budget === 'number' && Number.isFinite(budget) && budget >= 0 ? budget : null;
+}
+
 /**
  * Measure the always-loaded set under `root`.
  *
- * CLAUDE.local.md and anything it imports are reported separately under
- * `local`: they are per-user and gitignored, so folding them into the shared
- * total would overstate what the team actually pays.
+ * Three groups, kept separate because they cost different things:
+ * - `files` / `totalBytes` — CLAUDE.md, its @-imports, and unconditional
+ *   rules: what every session pays, and the number the budget judges.
+ * - `conditional` — rules with `paths:` frontmatter, reported with kind
+ *   `rule-scoped` but excluded from the total: they load only when Claude
+ *   touches a file matching one of their globs.
+ * - `local` — CLAUDE.local.md and its imports: per-user and gitignored, so
+ *   folding them into the shared total would overstate what the team pays.
  */
 function measure({ root = '.' } = {}) {
   const absRoot = resolve(root);
-  const files = [];
+  const always = [];
+  const conditional = [];
   const missingImports = [];
 
   const claudeMd = join(absRoot, 'CLAUDE.md');
   if (existsSync(claudeMd)) {
     const visited = new Set([claudeMd]);
-    files.push({ abs: claudeMd, kind: 'claude-md' });
+    always.push({ abs: claudeMd, kind: 'claude-md' });
     for (const imp of resolveImports(claudeMd, visited, missingImports)) {
-      files.push({ abs: imp, kind: 'import' });
+      always.push({ abs: imp, kind: 'import' });
     }
   }
 
-  for (const r of collectRules(absRoot)) files.push({ abs: r, kind: 'rule' });
-
-  const entries = [];
-  let totalBytes = 0;
-  for (const f of files) {
-    const bytes = sizeOf(f.abs);
-    if (bytes === null) continue;
-    totalBytes += bytes;
-    entries.push({ path: toPosix(relative(absRoot, f.abs)), bytes, kind: f.kind });
+  for (const r of collectRules(absRoot)) {
+    if (ruleIsConditional(r)) conditional.push({ abs: r, kind: 'rule-scoped' });
+    else always.push({ abs: r, kind: 'rule' });
   }
-  entries.sort((a, b) => b.bytes - a.bytes);
+
+  const toEntries = (group) => group
+    .map((f) => {
+      const bytes = sizeOf(f.abs);
+      return bytes === null ? null : { path: toPosix(relative(absRoot, f.abs)), bytes, kind: f.kind };
+    })
+    .filter((e) => e !== null)
+    .sort((a, b) => b.bytes - a.bytes);
+
+  const entries = toEntries(always);
+  const conditionalEntries = toEntries(conditional);
 
   const localEntries = [];
   let localBytes = 0;
@@ -172,6 +232,7 @@ function measure({ root = '.' } = {}) {
     localEntries.sort((a, b) => b.bytes - a.bytes);
   }
 
+  const totalBytes = entries.reduce((sum, e) => sum + e.bytes, 0);
   const totalTokens = Math.round(totalBytes / BYTES_PER_TOKEN);
   return {
     root: absRoot,
@@ -179,18 +240,22 @@ function measure({ root = '.' } = {}) {
     totalTokens,
     percentOfWindow: Number(((totalTokens / CONTEXT_WINDOW) * 100).toFixed(1)),
     files: entries,
+    conditional: {
+      totalBytes: conditionalEntries.reduce((sum, e) => sum + e.bytes, 0),
+      files: conditionalEntries,
+    },
     missingImports,
     local: { totalBytes: localBytes, files: localEntries },
   };
 }
 
-function projectCost(measurement, addedBytes, destination) {
+function projectCost(measurement, addedBytes, destination, budgetBytes = null) {
   const dest = DESTINATIONS[destination];
   if (!dest) throw new Error(`unknown destination: ${destination}`);
   const delta = dest.alwaysLoadedCost(addedBytes);
   const newTotalBytes = measurement.totalBytes + delta;
   const newTokens = Math.round(newTotalBytes / BYTES_PER_TOKEN);
-  return {
+  const projection = {
     destination,
     addedBytes,
     alwaysLoadedDelta: delta,
@@ -198,10 +263,15 @@ function projectCost(measurement, addedBytes, destination) {
     newPercentOfWindow: Number(((newTokens / CONTEXT_WINDOW) * 100).toFixed(1)),
     note: dest.note,
   };
+  if (budgetBytes !== null) {
+    projection.budgetBytes = budgetBytes;
+    projection.overBudgetAfter = newTotalBytes > budgetBytes;
+  }
+  return projection;
 }
 
 function parseArgs(argv) {
-  const args = { root: '.', json: false, add: null, as: null };
+  const args = { root: '.', json: false, add: null, as: null, budget: null };
   const rest = argv.slice(2);
   for (let i = 0; i < rest.length; i += 1) {
     const a = rest[i];
@@ -209,6 +279,7 @@ function parseArgs(argv) {
     if (a === '--json') { args.json = true; continue; }
     if (a === '--add') { args.add = Number(rest[++i]); continue; }
     if (a === '--as') { args.as = rest[++i]; continue; }
+    if (a === '--budget') { args.budget = Number(rest[++i]); continue; }
     throw new Error(`unknown argument: ${a}`);
   }
   if (args.add !== null && args.as === null) {
@@ -225,25 +296,42 @@ function parseArgs(argv) {
       `unknown destination: ${args.as}. Valid: ${Object.keys(DESTINATIONS).join(', ')}`,
     );
   }
+  if (args.budget !== null && (!Number.isFinite(args.budget) || args.budget < 0)) {
+    throw new Error('--budget expects a non-negative number of bytes');
+  }
   return args;
 }
 
-function renderHuman(m, projection) {
+function renderHuman(m, budget, projection) {
+  const row = (bytes, label, rest) =>
+    `${String(bytes).padStart(7)}  ${label.padEnd(12)}  ${rest}`;
   const lines = [];
   for (const f of m.files) {
-    lines.push(`${String(f.bytes).padStart(7)}  ${f.kind.padEnd(9)}  ${f.path}`);
+    lines.push(row(f.bytes, f.kind, f.path));
   }
   lines.push('-'.repeat(60));
   lines.push(
-    `${String(m.totalBytes).padStart(7)}  TOTAL      ~${m.totalTokens} tokens, ` +
-    `${m.percentOfWindow}% of a ${CONTEXT_WINDOW / 1000}k window`,
+    row(m.totalBytes, 'TOTAL',
+      `~${m.totalTokens} tokens, ${m.percentOfWindow}% of a ${CONTEXT_WINDOW / 1000}k window`),
   );
   if (m.local.totalBytes > 0) {
-    lines.push(`${String(m.local.totalBytes).padStart(7)}  local      (per-user, not counted above)`);
+    lines.push(row(m.local.totalBytes, 'local', '(per-user, not counted above)'));
+  }
+  if (m.conditional.totalBytes > 0) {
+    lines.push('');
+    lines.push('conditional (loads only on matching paths, not counted above):');
+    for (const f of m.conditional.files) {
+      lines.push(row(f.bytes, f.kind, f.path));
+    }
+    lines.push(row(m.conditional.totalBytes, 'scoped', '(conditional rules, not counted above)'));
   }
   if (m.missingImports.length > 0) {
     lines.push(`         dangling @-imports: ${m.missingImports.join(', ')}`);
   }
+  if (budget) {
+    lines.push('');
+    lines.push(`BUDGET  ${m.totalBytes}/${budget.bytes} bytes — ${budget.overBudget ? 'OVER' : 'ok'}`);
+  }
   if (projection) {
     lines.push('');
     lines.push(
@@ -254,6 +342,13 @@ function renderHuman(m, projection) {
       `${m.totalBytes} B (${m.percentOfWindow}%) -> ` +
       `${projection.newTotalBytes} B (${projection.newPercentOfWindow}%)`,
     );
+    if (projection.overBudgetAfter !== undefined) {
+      lines.push(
+        projection.overBudgetAfter
+          ? `over budget: ${projection.newTotalBytes} > ${projection.budgetBytes} B`
+          : `within budget: ${projection.newTotalBytes} / ${projection.budgetBytes} B`,
+      );
+    }
     lines.push(projection.note);
   }
   return lines.join('\n');
@@ -262,12 +357,23 @@ function renderHuman(m, projection) {
 function main() {
   const args = parseArgs(process.argv);
   const m = measure({ root: args.root });
-  const projection = args.add !== null ? projectCost(m, args.add, args.as) : null;
+  const budgetBytes = args.budget !== null ? args.budget : readBudget(m.root);
+  const budget = budgetBytes === null
+    ? null
+    : { bytes: budgetBytes, overBudget: m.totalBytes > budgetBytes };
+  const projection = args.add !== null ? projectCost(m, args.add, args.as, budgetBytes) : null;
   if (args.json) {
-    process.stdout.write(JSON.stringify({ ...m, projection }, null, 2) + '\n');
+    process.stdout.write(
+      JSON.stringify(
+        { ...m, budget: budgetBytes, overBudget: budget ? budget.overBudget : false, projection },
+        null,
+        2,
+      ) + '\n',
+    );
   } else {
-    process.stdout.write(renderHuman(m, projection) + '\n');
+    process.stdout.write(renderHuman(m, budget, projection) + '\n');
   }
+  if (budget?.overBudget) process.exitCode = 1;
 }
 
 if (isMainModule(import.meta.url)) {
@@ -279,4 +385,7 @@ if (isMainModule(import.meta.url)) {
   }
 }
 
-export { measure, projectCost, parseArgs, resolveImports, DESTINATIONS, BYTES_PER_TOKEN, CONTEXT_WINDOW };
+export {
+  measure, projectCost, parseArgs, resolveImports, readBudget, frontmatterHasPaths,
+  DESTINATIONS, BYTES_PER_TOKEN, CONTEXT_WINDOW,
+};

package/template/{.claude → _claude}/scripts/forges/github.mjs

@@ -114,7 +114,7 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
   // complete rather than merely empty (gh:89). `search` takes gh's raw search
   // syntax so callers can bound by merge date without this adapter growing a
   // date-range vocabulary of its own.
-  async function prList({ state = 'merged', base, search, limit = 100, repo }) {
+  async function prList({ state = 'merged', base, head, search, limit = 100, repo }) {
     const target = repoFor(repo);
     const args = [
       'pr', 'list', '--repo', target,
@@ -123,6 +123,7 @@ export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
       '--json', 'number,title,url,headRefName,baseRefName,mergedAt,state',
     ];
     if (base) args.push('--base', base);
+    if (head) args.push('--head', head);
     if (search) args.push('--search', search);
     const stdout = ghOrThrow(args).trim();
     const raw = stdout ? JSON.parse(stdout) : [];

package/template/{.claude → _claude}/scripts/forges/interface.mjs

@@ -17,11 +17,12 @@
 //   prView({ id, repo?, json? })
 //     → { id, url, state, mergeable, mergeStateStatus, reviewDecision, title }
 //     json may name additional fields to pass through
-//   prList({ state = 'merged', base?, search?, limit = 100, repo? })
+//   prList({ state = 'merged', base?, head?, search?, limit = 100, repo? })
 //     → [{ id, number, title, url, headRefName, baseRefName, mergedAt, state }]
-//     `search` passes through the forge's own search syntax (e.g.
-//     'merged:>2026-01-01'), so callers can bound a window without this
-//     interface growing a date vocabulary.
+//     `base`/`head` filter by target/source branch (e.g. the open PR for a
+//     task branch); `search` passes through the forge's own search syntax
+//     (e.g. 'merged:>2026-01-01'), so callers can bound a window without
+//     this interface growing a date vocabulary.
 //   releaseView({ tag, repo? })
 //     → { tag, url, name, publishedAt }
 //     throws ReleaseNotFound if the tag has no release

package/template/_claude/scripts/merge-mode.mjs

@@ -0,0 +1,61 @@
+// Merge-mode resolution for the task lifecycle (gh:173), shared by
+// task-worktree.mjs (which branch a new task worktree starts from) and
+// task-pr.mjs (push-and-PR versus merge-in-the-source-clone). It lives in
+// its own module because those two import each other's helpers: housing
+// the rule here keeps its definition singular without a circular import.
+
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// The workspace repo (the launcher) is addressed as "." — the one repo
+// name that is not a directory under repos/.
+const WORKSPACE_REPO = '.';
+
+// "." is the workspace repo itself — the git repo at the root. Every other
+// name is a directory under repos/.
+function repoDirFor(rootDir, repo) {
+  return repo === WORKSPACE_REPO ? rootDir : join(rootDir, 'repos', repo);
+}
+
+function readWorkspace(rootDir) {
+  try {
+    return JSON.parse(readFileSync(join(rootDir, 'workspace.json'), 'utf-8'));
+  } catch {
+    throw new Error(`cannot read ${join(rootDir, 'workspace.json')} — is --root the launcher?`);
+  }
+}
+
+// Same remote shapes the forge adapters resolve a repo from. A URL that
+// does not match is not forge-hosted, and the forge path supports
+// forge-hosted repos only — a local/bare remote has no PR concept to aim at.
+const FORGE_REMOTE_RE = /github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/;
+
+function parseForgeRemote(url) {
+  const m = String(url).trim().match(FORGE_REMOTE_RE);
+  return m ? { owner: m[1], name: m[2] } : null;
+}
+
+/**
+ * Resolve how a task repo merges: "local" — nothing pushed, merged in the
+ * repo's own source clone — when workspace.json asks for it
+ * (repos.{repo}.merge, or workspace.merge for the workspace repo; the
+ * right call for a clone whose origin is a third-party upstream nobody
+ * here may push to) or when the repo has no origin remote at all;
+ * "forge" — pushed and PR'd — when its origin parses as a forge-hosted
+ * owner/name. An origin that is neither (say a local bare mirror with no
+ * override) resolves to null: the caller stops with the override spelled
+ * out rather than pushing somewhere that cannot host a PR.
+ */
+function mergeModeFor(root, repo, deps = {}) {
+  const gitFn = deps.gitFn ?? spawnSync;
+  const rootDir = resolve(root);
+  const ws = readWorkspace(rootDir);
+  const override = repo === WORKSPACE_REPO ? ws?.workspace?.merge : ws?.repos?.[repo]?.merge;
+  if (override === 'local') return 'local';
+  const res = gitFn('git', ['-C', repoDirFor(rootDir, repo), 'remote', 'get-url', 'origin'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) return 'local'; // no origin — nowhere to push
+  return parseForgeRemote(String(res.stdout || '').trim()) ? 'forge' : null;
+}
+
+export { WORKSPACE_REPO, repoDirFor, readWorkspace, parseForgeRemote, mergeModeFor };

package/template/{.claude → _claude}/scripts/migrate-canonical-priority.mjs

@@ -7,7 +7,9 @@
 //   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).
+//   - Skip non-.md files, local-only-* files (machine-local drafts that
+//     happen to sit under shared/locked/ — never canonical), 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.
 //
@@ -62,6 +64,10 @@ export function migrateCanonicalPriority({ root }) {
 
   for (const name of entries) {
     if (!name.endsWith('.md')) continue;
+    // local-only-* files are machine-local and gitignored — they are never
+    // canonical, so back-filling a canonical priority field on them would be
+    // both wrong and a surprise on the next build-workspace-context run.
+    if (name.startsWith('local-only-')) continue;
     const full = join(lockedDir, name);
     let st;
     try { st = statSync(full); } catch { continue; }

package/template/_claude/scripts/migrate-claude-md-freshness-include.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Idempotent migrator: ensures CLAUDE.md includes @local-only-template-freshness.md.
+// Appends one line at end if missing. Preserves the rest of the file byte-for-byte.
+//
+// Run standalone: node migrate-claude-md-freshness-include.mjs [--root <dir>]
+// Or import { runMigration } and call programmatically.
+//
+// The root is --root when given, else the current working directory. It is
+// never derived from this script's location: the upgrade payload runs this
+// file from <workspace>/.workspace-update/.claude/scripts/, and a
+// script-relative root would point inside the payload instead of at the
+// workspace.
+import { existsSync, readFileSync, writeFileSync, realpathSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const INCLUDE_LINE = '@local-only-template-freshness.md';
+
+export function runMigration({ workspaceRoot }) {
+  const path = join(workspaceRoot, 'CLAUDE.md');
+  if (!existsSync(path)) return { action: 'skipped', reason: 'no-claude-md' };
+  const before = readFileSync(path, 'utf-8');
+  if (before.includes(INCLUDE_LINE)) return { action: 'unchanged' };
+  const after = before.endsWith('\n') ? before + INCLUDE_LINE + '\n' : before + '\n' + INCLUDE_LINE + '\n';
+  writeFileSync(path, after);
+  return { action: 'appended' };
+}
+
+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;
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const args = parseArgs(process.argv);
+    const result = runMigration({ workspaceRoot: resolve(args.root) });
+    console.log(JSON.stringify(result));
+  } catch (err) {
+    console.error(`migrate-claude-md-freshness-include: ${err.message}`);
+    process.exit(1);
+  }
+}

package/template/{.claude → _claude}/scripts/migrate-session-layout.mjs

@@ -22,15 +22,26 @@ import {
   readdirSync,
   copyFileSync,
   statSync,
+  realpathSync,
 } from 'fs';
 import { join } from 'path';
+import { fileURLToPath } from 'url';
 import {
-  getWorkspaceRoot,
   getWorkspacePaths,
   getMainRoot,
   readJSON,
 } from '../hooks/_utils.mjs';
 
+// Compare real paths: macOS temp dirs are symlinked (/var → /private/var),
+// so a naive import.meta.url === `file://${process.argv[1]}` silently fails
+// to detect main-module runs from tmpdir fixtures.
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
 export function migrateSession(root, sessionName) {
   const { workSessionsDir } = getWorkspacePaths(root);
   const sessionFolder = join(workSessionsDir, sessionName);
@@ -189,19 +200,19 @@ export function migrateMain(root) {
 }
 
 // CLI entry
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   const args = process.argv.slice(2);
   const getArg = (name) => {
     const i = args.indexOf(`--${name}`);
     return i >= 0 && args[i + 1] ? args[i + 1] : null;
   };
 
-  // The script lives in either the launcher's .claude/scripts/ or a session
-  // worktree's .claude/scripts/. getWorkspaceRoot returns the script's
-  // grandparent; when that's a worktree, promote it to the launcher via
-  // the .active-session.json pointer.
-  const inferred = getWorkspaceRoot(import.meta.url);
-  const root = getArg('root') || getMainRoot(inferred);
+  // The workspace root is --root when given, else the cwd — promoted to the
+  // launcher via the .active-session.json pointer when the cwd is a session
+  // worktree. It is never derived from this script's location: an upgrade
+  // payload runs this file from <workspace>/.workspace-update/.claude/scripts/,
+  // and a script-relative root would point inside the payload.
+  const root = getArg('root') || getMainRoot(process.cwd());
 
   const runAll = args.includes('--all');
   const runMain = args.includes('--main');