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

package/template/.claude/scripts/context-footprint.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+// Measure the always-loaded context footprint of a workspace, and price a
+// proposed addition before it is written.
+//
+// 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,
+// on every downstream workspace too. That cost is invisible at the moment
+// someone decides where to put a durable fact, which is how the rules directory
+// silently grew to 112 KB (gh:136, gh:138). This script makes the cost visible
+// at the decision point. The `context-placement` skill and the
+// `memory-guidance` rule both require running it before writing to an
+// always-loaded destination.
+//
+// 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> --add <bytes> --as <destination>
+//
+// Destinations for --as: rule, rule-scoped, locked, shared, team-member,
+// memory, skill, nowhere.
+
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+// A rough heuristic, not a tokenizer. Good enough to tell 200 bytes from 14 KB,
+// which is the only distinction the placement decision actually turns on.
+const BYTES_PER_TOKEN = 4;
+const CONTEXT_WINDOW = 200000;
+
+// Cost model per destination. Kept as data rather than a switch so the skill's
+// routing table and this script cannot drift apart independently — the notes
+// below are the same sentences the skill quotes.
+const DESTINATIONS = {
+  'rule': {
+    alwaysLoadedCost: (n) => n,
+    note: 'Unconditional rules load at launch at the same priority as CLAUDE.md, in every session — and in every downstream workspace that inherits the file.',
+  },
+  'rule-scoped': {
+    alwaysLoadedCost: () => 0,
+    note: 'A .claude/rules/*.md carrying a paths: array of globs loads only when Claude reads a matching file. Zero always-loaded cost.',
+  },
+  'locked': {
+    alwaysLoadedCost: (n) => n,
+    note: 'Locked files are concatenated verbatim into workspace-context/canonical.md, which every session loads in full.',
+  },
+  'shared': {
+    alwaysLoadedCost: () => 120,
+    note: 'Only the generated index line is always loaded; the body is read when the topic comes up.',
+  },
+  'team-member': {
+    alwaysLoadedCost: () => 120,
+    note: 'One index line, and only for that user — loaded via their gitignored CLAUDE.local.md.',
+  },
+  'memory': {
+    alwaysLoadedCost: () => 100,
+    note: 'One MEMORY.md pointer line is always loaded; the memory body is read on demand.',
+  },
+  'skill': {
+    alwaysLoadedCost: () => 200,
+    note: 'Only the frontmatter description is always loaded; the skill body loads when invoked.',
+  },
+  'nowhere': {
+    alwaysLoadedCost: () => 0,
+    note: 'Already covered elsewhere. The cheapest and most common correct answer.',
+  },
+};
+
+function sizeOf(absPath) {
+  try { return statSync(absPath).size; } catch { return null; }
+}
+
+function toPosix(p) {
+  return p.split(sep).join('/');
+}
+
+/**
+ * Follow @-imports out of `absFile`, depth-first.
+ *
+ * Imports resolve against the *importing file's* directory, not the workspace
+ * root and emphatically not process.cwd() — a script that resolves against cwd
+ * is how gh:142 happened. `visited` is keyed on the resolved absolute path so a
+ * cycle (A imports B imports A) terminates and each file is counted once.
+ */
+function resolveImports(absFile, visited, missing) {
+  const out = [];
+  let text;
+  try { text = readFileSync(absFile, 'utf8'); } catch { return out; }
+  for (const rawLine of text.split(/\r?\n/)) {
+    const m = /^@(\S+)$/.exec(rawLine.trim());
+    if (!m) continue;
+    const target = resolve(dirname(absFile), m[1]);
+    if (visited.has(target)) continue;
+    if (!existsSync(target)) {
+      // A workspace may legitimately reference an optional file it does not
+      // have (local-only-template-freshness.md, CODEBASE.md). Not an error —
+      // but record it so the caller can see the reference is dangling.
+      missing.push(m[1]);
+      continue;
+    }
+    visited.add(target);
+    out.push(target);
+    out.push(...resolveImports(target, visited, missing));
+  }
+  return out;
+}
+
+function collectRules(absRoot) {
+  const rulesDir = join(absRoot, '.claude', 'rules');
+  if (!existsSync(rulesDir)) return [];
+  return readdirSync(rulesDir)
+    .filter((n) => n.endsWith('.md') && !n.endsWith('.md.skip'))
+    .sort()
+    .map((n) => join(rulesDir, n));
+}
+
+/**
+ * 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.
+ */
+function measure({ root = '.' } = {}) {
+  const absRoot = resolve(root);
+  const files = [];
+  const missingImports = [];
+
+  const claudeMd = join(absRoot, 'CLAUDE.md');
+  if (existsSync(claudeMd)) {
+    const visited = new Set([claudeMd]);
+    files.push({ abs: claudeMd, kind: 'claude-md' });
+    for (const imp of resolveImports(claudeMd, visited, missingImports)) {
+      files.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 });
+  }
+  entries.sort((a, b) => b.bytes - a.bytes);
+
+  const localEntries = [];
+  let localBytes = 0;
+  const localMd = join(absRoot, 'CLAUDE.local.md');
+  if (existsSync(localMd)) {
+    const visited = new Set([localMd]);
+    const localMissing = [];
+    const localFiles = [localMd, ...resolveImports(localMd, visited, localMissing)];
+    for (const abs of localFiles) {
+      const bytes = sizeOf(abs);
+      if (bytes === null) continue;
+      localBytes += bytes;
+      localEntries.push({ path: toPosix(relative(absRoot, abs)), bytes, kind: 'local' });
+    }
+    localEntries.sort((a, b) => b.bytes - a.bytes);
+  }
+
+  const totalTokens = Math.round(totalBytes / BYTES_PER_TOKEN);
+  return {
+    root: absRoot,
+    totalBytes,
+    totalTokens,
+    percentOfWindow: Number(((totalTokens / CONTEXT_WINDOW) * 100).toFixed(1)),
+    files: entries,
+    missingImports,
+    local: { totalBytes: localBytes, files: localEntries },
+  };
+}
+
+function projectCost(measurement, addedBytes, destination) {
+  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 {
+    destination,
+    addedBytes,
+    alwaysLoadedDelta: delta,
+    newTotalBytes,
+    newPercentOfWindow: Number(((newTokens / CONTEXT_WINDOW) * 100).toFixed(1)),
+    note: dest.note,
+  };
+}
+
+function parseArgs(argv) {
+  const args = { root: '.', json: false, add: null, as: null };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a === '--root') { args.root = rest[++i]; continue; }
+    if (a === '--json') { args.json = true; continue; }
+    if (a === '--add') { args.add = Number(rest[++i]); continue; }
+    if (a === '--as') { args.as = rest[++i]; continue; }
+    throw new Error(`unknown argument: ${a}`);
+  }
+  if (args.add !== null && args.as === null) {
+    throw new Error('--add requires --as <destination>');
+  }
+  if (args.as !== null && args.add === null) {
+    throw new Error('--as requires --add <bytes>');
+  }
+  if (args.add !== null && !Number.isFinite(args.add)) {
+    throw new Error('--add expects a number of bytes');
+  }
+  if (args.as !== null && !DESTINATIONS[args.as]) {
+    throw new Error(
+      `unknown destination: ${args.as}. Valid: ${Object.keys(DESTINATIONS).join(', ')}`,
+    );
+  }
+  return args;
+}
+
+function renderHuman(m, projection) {
+  const lines = [];
+  for (const f of m.files) {
+    lines.push(`${String(f.bytes).padStart(7)}  ${f.kind.padEnd(9)}  ${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`,
+  );
+  if (m.local.totalBytes > 0) {
+    lines.push(`${String(m.local.totalBytes).padStart(7)}  local      (per-user, not counted above)`);
+  }
+  if (m.missingImports.length > 0) {
+    lines.push(`         dangling @-imports: ${m.missingImports.join(', ')}`);
+  }
+  if (projection) {
+    lines.push('');
+    lines.push(
+      `+${projection.addedBytes} B as "${projection.destination}" ` +
+      `=> +${projection.alwaysLoadedDelta} B always-loaded`,
+    );
+    lines.push(
+      `${m.totalBytes} B (${m.percentOfWindow}%) -> ` +
+      `${projection.newTotalBytes} B (${projection.newPercentOfWindow}%)`,
+    );
+    lines.push(projection.note);
+  }
+  return lines.join('\n');
+}
+
+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;
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ ...m, projection }, null, 2) + '\n');
+  } else {
+    process.stdout.write(renderHuman(m, projection) + '\n');
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`context-footprint: ${err.message}\n`);
+    process.exit(2);
+  }
+}
+
+export { measure, projectCost, parseArgs, resolveImports, DESTINATIONS, BYTES_PER_TOKEN, CONTEXT_WINDOW };

package/template/.claude/scripts/forges/github.mjs

@@ -0,0 +1,255 @@
+// GitHub forge adapter. Wraps the `gh` CLI via an injectable spawnFn so
+// tests can mock without spawning a real subprocess (mirrors the pattern
+// in trackers/github-issues.mjs).
+//
+// All operations target a single default `repo` resolved at construction
+// time from `config.repo` (e.g. `"owner/name"`) or from the local git
+// origin remote when `config.repo` is unset or `"auto"`. Per-call `repo`
+// overrides allow targeting a different repo when needed.
+
+import '../../lib/require-node.mjs';
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import {
+  PrNotFound,
+  ReleaseNotFound,
+  WorkflowNotFound,
+  MergeRejected,
+} from './interface.mjs';
+
+const PR_VIEW_FIELDS = 'number,url,state,title,mergeable,mergeStateStatus,reviewDecision,headRefName,baseRefName,isDraft,mergedAt';
+
+export function createGithubAdapter(config, { spawnFn = nodeSpawnSync } = {}) {
+  const defaultRepo = resolveRepo(config, spawnFn);
+
+  function gh(args, { input } = {}) {
+    const result = spawnFn('gh', args, {
+      input,
+      encoding: 'utf-8',
+      stdio: input !== undefined ? ['pipe', 'pipe', 'pipe'] : ['inherit', 'pipe', 'pipe'],
+    });
+    return result;
+  }
+
+  function ghOrThrow(args, opts) {
+    const result = gh(args, opts);
+    if (result.status !== 0) {
+      throw new Error(`gh ${args.join(' ')} failed: ${(result.stderr || '').trim()}`);
+    }
+    return result.stdout || '';
+  }
+
+  function repoFor(override) {
+    return override || defaultRepo;
+  }
+
+  async function prCreate({ title, body = '', draft = false, base, head, repo }) {
+    if (!title) throw new Error('prCreate: title is required');
+    const args = ['pr', 'create', '--repo', repoFor(repo), '--title', title, '--body-file', '-'];
+    if (draft) args.push('--draft');
+    if (base) args.push('--base', base);
+    if (head) args.push('--head', head);
+    const stdout = ghOrThrow(args, { input: body }).trim();
+    // gh pr create prints the PR URL on success; sometimes preceded by warnings.
+    const url = stdout.split('\n').filter(Boolean).pop();
+    const m = url.match(/\/pull\/(\d+)/);
+    if (!m) throw new Error(`Could not parse PR number from gh output: ${stdout}`);
+    const number = parseInt(m[1], 10);
+    return { id: `${repoFor(repo)}#${number}`, url, number };
+  }
+
+  async function prMerge({ id, strategy = 'merge', deleteBranch = false, repo }) {
+    if (!id) throw new Error('prMerge: id is required');
+    const { number, repo: parsedRepo } = parsePrId(id, repoFor(repo));
+    const args = ['pr', 'merge', String(number), '--repo', parsedRepo];
+    switch (strategy) {
+      case 'merge': args.push('--merge'); break;
+      case 'squash': args.push('--squash'); break;
+      case 'rebase': args.push('--rebase'); break;
+      default: throw new Error(`prMerge: unknown strategy: ${strategy}`);
+    }
+    if (deleteBranch) args.push('--delete-branch');
+    const result = gh(args);
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      // Distinguish "not found" from "rejected" so callers can react.
+      if (/not\s+found|could\s+not\s+resolve/i.test(stderr)) {
+        throw new PrNotFound(id);
+      }
+      throw new MergeRejected(id, stderr || 'gh pr merge exited non-zero');
+    }
+    return { merged: true, url: `https://github.com/${parsedRepo}/pull/${number}` };
+  }
+
+  async function prView({ id, repo, json }) {
+    if (!id) throw new Error('prView: id is required');
+    const { number, repo: parsedRepo } = parsePrId(id, repoFor(repo));
+    const fields = json || PR_VIEW_FIELDS;
+    const result = gh(['pr', 'view', String(number), '--repo', parsedRepo, '--json', fields]);
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      if (/not\s+found|could\s+not\s+resolve/i.test(stderr)) {
+        throw new PrNotFound(id);
+      }
+      throw new Error(`gh pr view failed: ${stderr}`);
+    }
+    const raw = JSON.parse(result.stdout);
+    return {
+      id,
+      number: raw.number,
+      url: raw.url,
+      state: raw.state,
+      title: raw.title,
+      mergeable: raw.mergeable,
+      mergeStateStatus: raw.mergeStateStatus,
+      reviewDecision: raw.reviewDecision,
+      headRefName: raw.headRefName,
+      baseRefName: raw.baseRefName,
+      isDraft: raw.isDraft,
+      mergedAt: raw.mergedAt,
+      _raw: raw,
+    };
+  }
+
+  // Listing merged PRs is how /release proves the unreleased-notes pile is
+  // 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 }) {
+    const target = repoFor(repo);
+    const args = [
+      'pr', 'list', '--repo', target,
+      '--state', state,
+      '--limit', String(limit),
+      '--json', 'number,title,url,headRefName,baseRefName,mergedAt,state',
+    ];
+    if (base) args.push('--base', base);
+    if (search) args.push('--search', search);
+    const stdout = ghOrThrow(args).trim();
+    const raw = stdout ? JSON.parse(stdout) : [];
+    return raw.map((p) => ({
+      id: `${target}#${p.number}`,
+      number: p.number,
+      title: p.title,
+      url: p.url,
+      headRefName: p.headRefName,
+      baseRefName: p.baseRefName,
+      mergedAt: p.mergedAt,
+      state: p.state,
+    }));
+  }
+
+  async function releaseView({ tag, repo }) {
+    if (!tag) throw new Error('releaseView: tag is required');
+    const target = repoFor(repo);
+    const result = gh(['release', 'view', tag, '--repo', target, '--json', 'name,tagName,url,publishedAt,isDraft,isPrerelease']);
+    if (result.status !== 0) {
+      const stderr = (result.stderr || '').trim();
+      if (/release\s+not\s+found|not\s+found/i.test(stderr)) {
+        throw new ReleaseNotFound(tag);
+      }
+      throw new Error(`gh release view failed: ${stderr}`);
+    }
+    const raw = JSON.parse(result.stdout);
+    return {
+      tag: raw.tagName,
+      name: raw.name,
+      url: raw.url,
+      publishedAt: raw.publishedAt,
+      isDraft: raw.isDraft,
+      isPrerelease: raw.isPrerelease,
+    };
+  }
+
+  // Creating the release is where release notes now come from: with
+  // --generate-notes the forge builds them from merged PR titles, so the
+  // workspace keeps no notes files of its own (gh:157).
+  async function releaseCreate({ tag, target, title, generateNotes = true, repo }) {
+    if (!tag) throw new Error('releaseCreate: tag is required');
+    const args = ['release', 'create', tag, '--repo', repoFor(repo)];
+    if (target) args.push('--target', target);
+    if (title) args.push('--title', title);
+    if (generateNotes) args.push('--generate-notes');
+    const stdout = ghOrThrow(args).trim();
+    // gh prints the release URL on success; sometimes preceded by warnings.
+    const url = stdout.split('\n').filter(Boolean).pop();
+    return { url, tag };
+  }
+
+  async function workflowRunFind({ workflow, branch, repo, limit = 1 }) {
+    if (!workflow) throw new Error('workflowRunFind: workflow is required');
+    const target = repoFor(repo);
+    const args = [
+      'run', 'list',
+      '--repo', target,
+      '--workflow', workflow,
+      '--limit', String(limit),
+      '--json', 'databaseId,status,conclusion,url,headBranch,createdAt',
+    ];
+    if (branch) args.push('--branch', branch);
+    const result = gh(args);
+    if (result.status !== 0) {
+      throw new Error(`gh run list failed: ${(result.stderr || '').trim()}`);
+    }
+    const runs = JSON.parse(result.stdout);
+    if (runs.length === 0) return null;
+    const first = runs[0];
+    return {
+      runId: String(first.databaseId),
+      status: first.status,
+      conclusion: first.conclusion,
+      url: first.url,
+      branch: first.headBranch,
+      createdAt: first.createdAt,
+    };
+  }
+
+  async function workflowRunWatch({ runId, repo, exitStatus = false }) {
+    if (!runId) throw new Error('workflowRunWatch: runId is required');
+    const target = repoFor(repo);
+    const args = ['run', 'watch', String(runId), '--repo', target];
+    if (exitStatus) args.push('--exit-status');
+    const result = gh(args);
+    if (result.status === 0) return { exitCode: 0 };
+    // Distinguish "couldn't find" from "ran but failed".
+    const stderr = (result.stderr || '').trim();
+    if (/not\s+found|could\s+not\s+find/i.test(stderr)) {
+      throw new WorkflowNotFound({ runId });
+    }
+    // `--exit-status` makes gh exit non-zero on workflow failure; surface
+    // that without throwing so callers can record the failure URL.
+    return { exitCode: result.status, stderr };
+  }
+
+  return {
+    prCreate,
+    prMerge,
+    prView,
+    prList,
+    releaseView,
+    releaseCreate,
+    workflowRunFind,
+    workflowRunWatch,
+    get identity() { return `github:${defaultRepo}`; },
+  };
+}
+
+// "owner/name#NUMBER" or just NUMBER (defaulting to the adapter's repo).
+function parsePrId(id, fallbackRepo) {
+  if (typeof id === 'number') return { number: id, repo: fallbackRepo };
+  const m1 = String(id).match(/^(?<repo>[^#\s]+\/[^#\s]+)#(?<number>\d+)$/);
+  if (m1) return { number: parseInt(m1.groups.number, 10), repo: m1.groups.repo };
+  const m2 = String(id).match(/^#?(\d+)$/);
+  if (m2) return { number: parseInt(m2[1], 10), repo: fallbackRepo };
+  throw new Error(`Unparseable PR id: ${id}`);
+}
+
+function resolveRepo(config, spawnFn) {
+  if (config?.repo && config.repo !== 'auto') return config.repo;
+  const result = spawnFn('git', ['remote', 'get-url', 'origin'], { encoding: 'utf-8' });
+  if (result.status !== 0) {
+    throw new Error(`git remote get-url failed: ${(result.stderr || '').trim()}`);
+  }
+  const m = result.stdout.trim().match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/);
+  if (!m) throw new Error(`Cannot parse GitHub remote: ${result.stdout.trim()}`);
+  return `${m[1]}/${m[2]}`;
+}

package/template/.claude/scripts/forges/gitlab.mjs

@@ -0,0 +1,20 @@
+// GitLab forge adapter — stub. Reserved as the next sibling of github.mjs
+// so the discovery pattern stays uniform: workspaces opting into GitLab
+// set `workspace.forge.type: gitlab` in workspace.json and get a clear
+// "not implemented" error pointing at the gap, rather than silently
+// routing through GitHub.
+//
+// When implemented, this adapter wraps the `glab` CLI the same way
+// github.mjs wraps `gh`: same method surface (prCreate, prMerge, prView,
+// prList, releaseView, releaseCreate, workflowRunFind, workflowRunWatch),
+// same spawnFn-injectable shape for testability, same error types from
+// interface.mjs.
+
+import { ForgeError } from './interface.mjs';
+
+export function createGitlabAdapter(config /* , options */) {
+  throw new ForgeError(
+    'GitLab forge adapter is not implemented yet. Set workspace.forge.type to "github", or contribute a glab-based adapter at .claude/scripts/forges/gitlab.mjs following the shape of github.mjs.',
+    'NOT_IMPLEMENTED',
+  );
+}

package/template/.claude/scripts/forges/interface.mjs

@@ -0,0 +1,125 @@
+// Forge adapter interface. Skills import only from this module.
+//
+// Where `trackers/` covers issue lifecycle (issues, comments, labels,
+// milestones), `forges/` covers cross-cutting repo-host operations:
+// pull requests, releases, and workflow runs. The two abstractions are
+// intentionally separate — a workspace could in principle mix
+// (e.g. `github-issues` tracker + `gitlab` forge), though the common
+// case is forge = same host as tracker.
+//
+// Method contracts:
+//
+//   prCreate({ title, body, draft = false, base, head, repo? })
+//     → { id, url, number }
+//   prMerge({ id, strategy = 'merge', deleteBranch = false, repo? })
+//     → { merged: true, url }
+//     strategy: 'merge' | 'squash' | 'rebase'
+//   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? })
+//     → [{ 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.
+//   releaseView({ tag, repo? })
+//     → { tag, url, name, publishedAt }
+//     throws ReleaseNotFound if the tag has no release
+//   releaseCreate({ tag, target?, title?, generateNotes = true, repo? })
+//     → { url, tag }
+//     target: commitish the tag points at (default: the repo's default
+//     branch head); title: release name (default: the tag)
+//     generateNotes: when true (the default) the forge generates the
+//     release notes from merged PRs — this is the only notes mechanism
+//     the workspace ships.
+//   workflowRunFind({ workflow, branch, repo?, limit = 1 })
+//     → { runId, status, conclusion, url } | null
+//   workflowRunWatch({ runId, repo?, exitStatus = false })
+//     → { exitCode }
+//     exitStatus: when true, the underlying command exits non-zero on
+//     workflow failure; the adapter still returns the exit code rather
+//     than throwing — callers decide how to handle a failed run.
+//
+// `repo` defaults: each adapter resolves a default repo at construction
+// time (e.g. from `workspace.forge.repo` or the local git origin remote);
+// callers pass `repo` only when targeting a different one.
+//
+// All methods are async and may throw `ForgeError` subclasses on
+// adapter-detectable failures. Raw spawn failures throw `Error`.
+
+import '../../lib/require-node.mjs';
+import { createGithubAdapter } from './github.mjs';
+import { createGitlabAdapter } from './gitlab.mjs';
+
+export class ForgeError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'ForgeError';
+    this.code = code;
+  }
+}
+
+export class PrNotFound extends ForgeError {
+  constructor(id) {
+    super(`Pull request not found: ${id}`, 'PR_NOT_FOUND');
+    this.name = 'PrNotFound';
+    this.id = id;
+  }
+}
+
+export class ReleaseNotFound extends ForgeError {
+  constructor(tag) {
+    super(`Release not found for tag: ${tag}`, 'RELEASE_NOT_FOUND');
+    this.name = 'ReleaseNotFound';
+    this.tag = tag;
+  }
+}
+
+export class WorkflowNotFound extends ForgeError {
+  constructor(query) {
+    super(`Workflow run not found: ${JSON.stringify(query)}`, 'WORKFLOW_NOT_FOUND');
+    this.name = 'WorkflowNotFound';
+    this.query = query;
+  }
+}
+
+export class MergeRejected extends ForgeError {
+  constructor(id, reason) {
+    super(`Merge rejected for ${id}: ${reason}`, 'MERGE_REJECTED');
+    this.name = 'MergeRejected';
+    this.id = id;
+    this.reason = reason;
+  }
+}
+
+// createForge takes the `workspace.forge` config block. If the block is
+// absent (`undefined`/`null`), default to GitHub — this matches the
+// migration story documented in `.claude/rules/forge-operations.md`:
+// existing workspaces predate the field, so an unset value means
+// "behave as you always have." A workspace that wants to opt out of
+// forge operations entirely should set `workspace.forge: false`;
+// callers passing `false` will get a no-op throw on every method.
+export function createForge(config, options = {}) {
+  if (config === false) {
+    throw new ForgeError(
+      'Forge operations disabled — set workspace.forge in workspace.json to enable.',
+      'FORGE_DISABLED',
+    );
+  }
+  const resolved = config ?? { type: 'github' };
+  if (typeof resolved !== 'object') {
+    throw new ForgeError(
+      `Invalid workspace.forge config: expected object, got ${typeof resolved}`,
+      'INVALID_CONFIG',
+    );
+  }
+  const type = resolved.type ?? 'github';
+  switch (type) {
+    case 'github':
+      return createGithubAdapter(resolved, options);
+    case 'gitlab':
+      return createGitlabAdapter(resolved, options);
+    default:
+      throw new ForgeError(`Unknown forge type: ${type}`, 'UNKNOWN_TYPE');
+  }
+}