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