@sabaiway/agent-workflow-kit 3.0.0 → 3.1.0

package/references/scripts/check-docs-size-cli.test.mjs

@@ -0,0 +1,41 @@
+// check-docs-size-cli.test.mjs — runCli branch pins the subprocess smokes cannot reach
+// in-process (Phase-5 coverage fill; the main spec file is parity-frozen, so these ride a
+// colocated file): the unknown-argument refusal and the written-empty-index guard.
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCli } from './check-docs-size.mjs';
+
+const cli = async (argv) => {
+  const { code, stdout, stderr } = await runCli(argv);
+  return { code, stdout, stderr };
+};
+
+describe('check-docs-size runCli — refusal branches', () => {
+  it('an unknown argument exits 2 naming it', async () => {
+    const { code, stderr } = await cli(['--bogus']);
+    assert.equal(code, 2);
+    assert.match(stderr, /Unknown argument: --bogus/);
+  });
+
+  it('--write-index landing on a sink path (index stat size 0) is the loud written-empty refusal', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
+    try {
+      mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+      writeFileSync(
+        join(root, 'docs', 'ai', 'a.md'),
+        '---\ntype: state\nlastUpdated: 2026-07-18\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# a\n',
+      );
+      // The index path is a symlink into /dev/null: the write lands, the stat reads size 0 —
+      // the guard must refuse loudly instead of reporting a written index.
+      symlinkSync('/dev/null', join(root, 'docs', 'ai', 'index.md'));
+      const { code, stderr } = await cli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.match(stderr, /index\.md was written empty/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/references/scripts/check-docs-size.mjs

@@ -103,25 +103,19 @@ export const discoverMeta = async (root = ROOT) => {
   return { projectName, hierarchicalLinks, onDemandLinks };
 };
 
+// Pure argv parser (no I/O, no exit): `help` / `error` ride out as data for runCli to render.
 const parseArgs = (argv) => {
   const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
   const opts = { today: null, root: null };
-  for (const arg of argv.slice(2)) {
+  for (const arg of argv) {
     if (arg === '--report') flags.report = true;
     else if (arg === '--write-index') flags.writeIndex = true;
     else if (arg === '--check-index') flags.checkIndex = true;
     else if (arg === '--quiet') flags.quiet = true;
     else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
     else if (arg.startsWith('--root=')) opts.root = arg.slice('--root='.length);
-    else if (arg === '--help' || arg === '-h') {
-      console.log(
-        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]',
-      );
-      process.exit(0);
-    } else {
-      console.error(`Unknown argument: ${arg}`);
-      process.exit(2);
-    }
+    else if (arg === '--help' || arg === '-h') return { flags, opts, help: true };
+    else return { flags, opts, error: `Unknown argument: ${arg}` };
   }
   return { flags, opts };
 };
@@ -218,7 +212,7 @@ const formatRow = (row) => {
   return { status, sizeCell, ...row };
 };
 
-const printReport = (rows, quiet) => {
+const printReport = (rows, quiet, log = console.log) => {
   const widths = {
     status: 2,
     path: Math.max(4, ...rows.map((r) => r.path.length)),
@@ -228,15 +222,15 @@ const printReport = (rows, quiet) => {
   };
   const printable = quiet ? rows.filter((r) => r.errors.length || r.warnings.length) : rows;
   if (printable.length > 0) {
-    console.log(
+    log(
       `${'S'.padEnd(widths.status)}  ${'PATH'.padEnd(widths.path)}  ${'SIZE/MAX'.padEnd(widths.size)}  ${'TYPE'.padEnd(widths.type)}  ${'UPDATED'.padEnd(widths.updated)}`,
     );
     for (const row of printable) {
-      console.log(
+      log(
         `${row.status.padEnd(widths.status)}  ${row.path.padEnd(widths.path)}  ${row.sizeCell.padEnd(widths.size)}  ${(row.frontmatter?.type ?? '').padEnd(widths.type)}  ${(row.frontmatter?.lastUpdated ?? '').padEnd(widths.updated)}`,
       );
-      for (const err of row.errors) console.log(`     - ERROR  ${err}`);
-      for (const warn of row.warnings) console.log(`     - WARN   ${warn}`);
+      for (const err of row.errors) log(`     - ERROR  ${err}`);
+      for (const warn of row.warnings) log(`     - WARN   ${warn}`);
     }
   }
 };
@@ -361,9 +355,29 @@ export const regenerateIndex = async (root, todayStr = null) => {
   return { indexPath, files: rows.length };
 };
 
-const main = async () => {
-  const { flags, opts } = parseArgs(process.argv);
-  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : ROOT);
+// The return-code entry point (no process.argv / process.exit / console inside): argv[] →
+// { code, stdout, stderr }. The thin shell at the bottom is the only process-coupled code.
+export const runCli = async (argv, deps = {}) => {
+  const stdoutLines = [];
+  const stderrLines = [];
+  const log = (line) => stdoutLines.push(line);
+  const logError = (line) => stderrLines.push(line);
+  const result = (code) => ({
+    code,
+    stdout: stdoutLines.length > 0 ? `${stdoutLines.join('\n')}\n` : '',
+    stderr: stderrLines.length > 0 ? `${stderrLines.join('\n')}\n` : '',
+  });
+
+  const { flags, opts, help, error } = parseArgs(argv);
+  if (help) {
+    log('Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]');
+    return result(0);
+  }
+  if (error) {
+    logError(error);
+    return result(2);
+  }
+  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : (deps.root ?? ROOT));
   const today = computeToday(opts.today);
   const files = (await walkMarkdownFiles(docsDir)).sort();
   const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
@@ -373,11 +387,11 @@ const main = async () => {
 
   if (flags.writeIndex) {
     await writeIndex(rows, today, meta, indexPath);
-    console.log(`Wrote ${relative(root, indexPath)}`);
+    log(`Wrote ${relative(root, indexPath)}`);
     const after = await stat(indexPath);
     if (after.size === 0) {
-      console.error('index.md was written empty');
-      process.exit(2);
+      logError('index.md was written empty');
+      return result(2);
     }
   }
 
@@ -385,28 +399,31 @@ const main = async () => {
     const onDisk = existsSync(indexPath) ? await readFile(indexPath, 'utf8') : null;
     const { fresh } = checkIndexFreshness(rows, onDisk, meta);
     if (!fresh) {
-      console.error(
+      logError(
         `[check-docs-size] FAIL: ${relative(root, indexPath)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
       );
-      process.exit(1);
+      return result(1);
     }
-    console.log(
+    log(
       `[check-docs-size] OK — ${relative(root, indexPath)} is in sync with source frontmatter.`,
     );
-    return;
+    return result(0);
   }
 
-  printReport(rows, flags.quiet);
+  printReport(rows, flags.quiet, log);
   const errorCount = rows.reduce((n, r) => n + r.errors.length, 0);
   const warnCount = rows.reduce((n, r) => n + r.warnings.length, 0);
-  console.log(
+  log(
     `\n${rows.length} files inspected  —  ${errorCount} error(s), ${warnCount} warning(s)`,
   );
 
-  if (errorCount > 0 && !flags.report) process.exit(1);
+  return result(errorCount > 0 && !flags.report ? 1 : 0);
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
-  await main();
+  const { code, stdout, stderr } = await runCli(process.argv.slice(2));
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
 }

package/tools/autonomy-doctor.mjs

@@ -254,7 +254,7 @@ const renderDiagnosis = ({ plan, probeResult, log }) => {
   }
 };
 
-// The untrusted degrade every lane runs FIRST (codex R1): while any sandbox binary resolves only
+// The untrusted degrade every lane runs FIRST: while any sandbox binary resolves only
 // outside the trusted dirs, no offer, no consent invitation, and no privileged path may proceed —
 // an install cannot make such a host verify-ready.
 const refuseUntrusted = ({ plan, log }) => {

package/tools/changed-surface.mjs

@@ -37,7 +37,7 @@ export const classifyChangedPath = (rel) => {
 
 // Strip the quotes and decode escapes BYTE-wise (octal escapes are UTF-8 bytes) — an unparsed
 // quoted path compares unequal to its classifier/testId form and would silently escape the
-// coverage/cap surface (agy R5, AD-047).
+// coverage/cap surface (AD-047).
 const CQUOTE_SIMPLE = { n: 10, t: 9, r: 13, f: 12, v: 11, b: 8, a: 7, '"': 34, '\\': 92 };
 export const unquoteDiffPath = (p) => {
   if (!(p.length >= 2 && p.startsWith('"') && p.endsWith('"'))) return p;
@@ -47,7 +47,7 @@ export const unquoteDiffPath = (p) => {
     const c = inner[i];
     if (c !== '\\') {
       // Consume a full CODE POINT — 16-bit-unit iteration would split a surrogate pair (an
-      // unescaped non-BMP char, reachable under core.quotepath=false) into replacement bytes (agy R6).
+      // unescaped non-BMP char, reachable under core.quotepath=false) into replacement bytes.
       const ch = String.fromCodePoint(inner.codePointAt(i));
       for (const b of Buffer.from(ch, 'utf8')) bytes.push(b);
       i += ch.length - 1;
@@ -89,7 +89,7 @@ export const parseUnifiedDiff = (diffText) => {
     }
     if (inHeader && line.startsWith('--- ')) continue;
     if (inHeader && line.startsWith('+++ ')) {
-      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, '')); // TAB/CR are git artifacts, never filename bytes (agy R6)
+      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, '')); // TAB/CR are git artifacts, never filename bytes
       current = p === '/dev/null' ? null : p.startsWith('b/') ? p.slice(2) : p;
       inHeader = false;
       continue;
@@ -114,7 +114,7 @@ export const parseUnifiedDiff = (diffText) => {
 // ── the changed surface (git-driven; the ONE computation both consumers read) ─────────────────────
 
 // The one diff-invocation shape every surface pass uses. The a/ b/ prefixes are pinned EXPLICITLY
-// (agy R6): a user's global diff.noprefix=true would otherwise drop them and the parsers would eat
+// A user's global diff.noprefix=true would otherwise drop them and the parsers would eat
 // a real directory named "a" — user git config must never bend the parse.
 export const DIFF_FLAGS = ['--unified=0', '--no-color', '--no-ext-diff', '--no-renames', '--src-prefix=a/', '--dst-prefix=b/'];
 
@@ -134,7 +134,7 @@ export const readFileSafe = (path) => {
 };
 // A changed LEAF is read only if it is a REGULAR file. lstat (no-follow): a symlinked or non-regular
 // leaf must NEVER be read/followed — following it could read outside the work tree or HANG on a
-// FIFO/device (codex R2, AD-046). A non-regular leaf fails closed (routed to `unsupported`).
+// FIFO/device (AD-046). A non-regular leaf fails closed (routed to `unsupported`).
 export const isRegularLeaf = (abs) => {
   try {
     return lstatSync(abs).isFile();
@@ -150,13 +150,13 @@ export const isRegularLeaf = (abs) => {
 // pure deletions cost nothing, subtractive folds stay free); an untracked file is wholly new, so all
 // its lines are "changed". `unsupportedLines` is the D4 cap's view of the SAME pass: unsupported
 // SOURCE files carry their new-side lines too (excluding them would gift a large-TS-fold bypass,
-// codex R2 / BUGFREE-2 D4); an unreadable/non-regular leaf counts 0 lines but stays LISTED (the
+// BUGFREE-2 D4); an unreadable/non-regular leaf counts 0 lines but stays LISTED (the
 // coverage gate still fails closed on it). excluded-test and out-of-domain never carry lines.
 export const computeChangedSurface = (root) => {
   // Unborn branch (no HEAD yet): the plain diff alone misses files STAGED for the initial commit —
   // they sit in the index, so they are neither worktree-vs-index changes nor untracked. Merge the
   // --cached diff (index vs the empty tree) with the plain one; parseUnifiedDiff unions per-file
-  // lines across concatenated diffs (codex R1).
+  // lines across concatenated diffs.
   const trackedDiff = gitStdout(['diff', 'HEAD', ...DIFF_FLAGS], root)
     ?? `${gitStdout(['diff', '--cached', ...DIFF_FLAGS], root) ?? ''}\n${gitStdout(['diff', ...DIFF_FLAGS], root) ?? ''}`;
   const trackedLines = parseUnifiedDiff(trackedDiff);
@@ -207,7 +207,7 @@ export const computeChangedSurface = (root) => {
 // ── the shared fail-closed positive-integer knob parser (AD-047 precedent) ───────────────────────
 
 // Zero / negative / fractional / non-numeric values are refusals by name — the parseInt(...)||default
-// idiom would silently accept bad truthy values (codex R2, AD-046). Unset → the default; set → a
+// idiom would silently accept bad truthy values (AD-046). Unset → the default; set → a
 // positive integer, exactly. `makeError` lets each caller throw its OWN typed STOP.
 export const parsePositiveIntKnob = (env, name, fallback, makeError = (m) => new Error(m)) => {
   const raw = env[name];

package/tools/commands.mjs

@@ -231,6 +231,15 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Check that the documented contract tokens still match the live code constants they describe — a read-only lint that fails closed on drift; --check turns it into a gate exit code.',
   },
+  {
+    // NEVER `guarded` — that kind promises dry-run-first, which these writers do not have; the
+    // honest strongest caution is `writer` with the destructive arm named in the line itself.
+    key: 'worktrees',
+    invocation: invocationOf('worktrees'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Run features in parallel git worktrees: provision an isolated sibling copy, list them, stage a finished one back onto clean main (the commit still asks in dialogue), and remove a live-verified landed one. No preview step; list is read-only; cleanup --abandon destroys unlanded work.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime

package/tools/grounding.mjs

@@ -102,7 +102,7 @@ export const assembleGrounding = ({ constraintsText = null, autonomyText = null,
 // Trim `payload` to `budget` bytes, tail-first, with a loud in-band marker. The budget is a HARD
 // ceiling: when it is smaller than the marker itself, the marker is truncated too (the output may
 // never exceed `budget` — a facts file over the reserved share would push the final wrapper prompt
-// past the argv ceiling; codex R1 finding). Returns { text, trimmedBytes }. Never a silent cut.
+// past the argv ceiling). Returns { text, trimmedBytes }. Never a silent cut.
 export const trimToBudget = (payload, budget) => {
   const bytes = Buffer.byteLength(payload, 'utf8');
   if (bytes <= budget) return { text: payload, trimmedBytes: 0 };
@@ -164,17 +164,17 @@ const gitLine = (args, cwd) => {
 // EXISTING in-repo file, even gitignored, is a project file — the .env clobber class). Refused:
 // tracked paths, in-repo not-ignored paths (a new untracked file would move the fingerprint),
 // every other outside-repo destination, symlink and existing non-regular leaves, and any
-// unverifiable lstat. The check runs on the REAL destination, never the lexical path (codex R1):
+// unverifiable lstat. The check runs on the REAL destination, never the lexical path:
 // the parent directory is realpath-resolved first, so a symlink can never route the write onto a
 // tracked/in-repo file. Returns { path, kind: 'temp' | 'repo-fresh' } — a repo-fresh caller MUST
-// write with the exclusive flag ('wx'), sealing the guard→write race (codex R11).
+// write with the exclusive flag ('wx'), sealing the guard→write race.
 export const assertScratchDestination = (outPath, cwd) => {
   const lexical = isAbsolute(outPath) ? outPath : resolve(cwd, outPath);
   let leaf = null;
   try {
     leaf = lstatSync(lexical);
   } catch (err) {
-    // ONLY an absent leaf is a fresh file; any other lstat failure fails CLOSED (codex R9 — this
+    // ONLY an absent leaf is a fresh file; any other lstat failure fails CLOSED (this
     // writer is bridge-tier auto-allowable, so an unverifiable leaf must never be written).
     if (err?.code !== 'ENOENT') {
       throw fail(1, `--out cannot inspect the destination (${outPath}: ${err?.code ?? err?.message ?? err}) — refusing to write an unverifiable leaf`);
@@ -185,7 +185,7 @@ export const assertScratchDestination = (outPath, cwd) => {
     throw fail(1, `--out refuses a symlink destination (${outPath}) — the write would follow it onto another file; name the real scratch path`);
   }
   if (leaf != null && !leaf.isFile()) {
-    throw fail(1, `--out refuses an existing non-regular destination (${outPath}) — a FIFO/device/directory write would hang or land on a non-file (codex R9); name a fresh or regular scratch path`);
+    throw fail(1, `--out refuses an existing non-regular destination (${outPath}) — a FIFO/device/directory write would hang or land on a non-file; name a fresh or regular scratch path`);
   }
   let realParent;
   try {
@@ -194,8 +194,8 @@ export const assertScratchDestination = (outPath, cwd) => {
     throw fail(1, `--out parent directory does not exist (${dirname(lexical)}) — create the scratch dir first`);
   }
   const full = join(realParent, basename(lexical));
-  // An out-of-repo (or no-repo) destination is scratch ONLY under a system temp root (codex R8
-  // blocker): the bridge tier auto-allows this tool with an args wildcard, so "anything outside
+  // An out-of-repo (or no-repo) destination is scratch ONLY under a system temp root: the bridge
+  // tier auto-allows this tool with an args wildcard, so "anything outside
   // the repo is scratch" would let an unattended run overwrite e.g. ~/.bashrc promptless.
   // $TMPDIR / os.tmpdir() / /tmp are the scratch surface; everything else refuses loudly.
   const assertTempScratch = () => {
@@ -215,7 +215,7 @@ export const assertScratchDestination = (outPath, cwd) => {
   if (top == null || top.status !== 0) return { path: assertTempScratch().path, kind: 'temp' }; // no git tree → temp-only scratch
   const root = top.stdout.replace(/\r?\n$/, '');
   const rel = relative(root, full);
-  // Segment-safe outside test (the Issue-004 class, codex R5): an in-repo file literally named
+  // Segment-safe outside test (the Issue-004 class): an in-repo file literally named
   // `..facts` has rel `..facts` — `startsWith('..')` would misread it as outside and BYPASS the
   // tracked/ignored refusals below. Only `..` exactly or a `..${sep}`-prefixed rel is outside.
   if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return { path: assertTempScratch().path, kind: 'temp' };
@@ -227,11 +227,11 @@ export const assertScratchDestination = (outPath, cwd) => {
   if (ignored == null || ignored.status !== 0) {
     throw fail(1, `--out refuses an in-repo path that is not gitignored (${rel}) — a new untracked file would move the review fingerprint; use a gitignored path or a location outside the repo`);
   }
-  // An in-repo destination must be a FRESH file (codex R10): even a gitignored existing file is a
+  // An in-repo destination must be a FRESH file: even a gitignored existing file is a
   // project file (.env is the canonical victim) — an auto-allowable writer must never clobber one.
   // The rewritable scratch surface is the system temp; in-repo gitignored writes are create-only —
   // the CALLER must open with the exclusive flag ('wx'): the kind seals the pre-check against the
-  // guard→write race (codex R11).
+  // guard→write race.
   if (leaf != null) {
     throw fail(1, `--out refuses to OVERWRITE an existing in-repo file (${rel}) — even gitignored, it is a project file (the .env class); write rewritable scratch under $TMPDIR//tmp, or remove the file first`);
   }
@@ -328,7 +328,7 @@ export const main = (argv, ctx = {}) => {
     };
     const constraintsText = constraints ? readOrStop('AGENTS.md', 'root AGENTS.md') : null;
     const autonomyText = autonomy ? resolveAutonomyFacts({ cwd }) : null;
-    // --plan is CONFINED to the git work tree (codex R4): the bridge tier auto-allows this tool
+    // --plan is CONFINED to the git work tree: the bridge tier auto-allows this tool
     // with an args wildcard, so an unattended invocation could otherwise point --plan at ANY
     // readable file and ship it into the facts payload. Plans are in-repo by contract
     // (docs/plans); an outside-tree path is a loud refusal, never a silent read.
@@ -360,7 +360,7 @@ export const main = (argv, ctx = {}) => {
     if (out != null) {
       const dest = assertScratchDestination(out, cwd);
       // repo-fresh writes are EXCLUSIVE ('wx'): the create-only pre-check would otherwise race a
-      // file created between the guard and this write (codex R11); temp scratch stays rewritable.
+      // file created between the guard and this write; temp scratch stays rewritable.
       // ctx.writeFile is a TEST seam (the EEXIST race arm is not constructible without it).
       const writeFile = ctx.writeFile ?? writeFileSync;
       try {
@@ -380,7 +380,7 @@ export const main = (argv, ctx = {}) => {
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
   const r = main(process.argv.slice(2));
-  // Exact writes + a natural exit (codex R2): console.log would append a stray newline to the
+  // Exact writes + a natural exit: console.log would append a stray newline to the
   // byte-exact facts payload, and process.exit() can truncate large piped stdout before Node
   // flushes. The payload already ends with '\n' (sliceSection normalizes); only a non-payload
   // message (help / the --out report) gains the terminating newline it lacks.

package/tools/inject-methodology.mjs

@@ -314,11 +314,31 @@ const isCapRefusal = (errorMessage) => typeof errorMessage === 'string' && error
 export const isFillCapRefusal = (errorMessage) =>
   isCapRefusal(errorMessage) && errorMessage.includes('injection would push');
 
-const main = async (argv) => {
+const EXIT = Symbol('inject-methodology.exit');
+
+// The return-code entry point (5.1): argv[] + injected env/home → { code, stdout, stderr }, no
+// process.argv / process.exit / console inside — an in-process caller is as hermetic as a spawned
+// one. The thin shell at the bottom is the only process-coupled code.
+export const runCli = async (argv, deps = {}) => {
   const { readFile, writeFile, rename, rm } = await import('node:fs/promises');
   const { dirname, basename, join, resolve } = await import('node:path');
   const { homedir } = await import('node:os');
   const { resolveEngineDir, readEngineFragment, detectEngine, ENGINE_FRAGMENT_REL, ORCHESTRATION_FRAGMENT_REL, AUTONOMY_FRAGMENT_REL } = await import('./engine-source.mjs');
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? homedir();
+
+  const stdoutLines = [];
+  const stderrLines = [];
+  const log = (line) => stdoutLines.push(line);
+  const logError = (line) => stderrLines.push(line);
+  const result = (code) => ({
+    code,
+    stdout: stdoutLines.length > 0 ? `${stdoutLines.join('\n')}\n` : '',
+    stderr: stderrLines.length > 0 ? `${stderrLines.join('\n')}\n` : '',
+  });
+  // Nested sourcing helpers end the run from arbitrary depth — a tagged throw the catch below
+  // translates into the result code (the process.exit of the pre-entry-point CLI).
+  const stop = (code) => Object.assign(new Error(`exit ${code}`), { [EXIT]: code });
 
   // `reconcile <AGENTS.md> [fragment.md]` = ensure-slot + inject-if-empty + cap (bootstrap/upgrade) for
   // ALL THREE slots; `<AGENTS.md> [fragment.md]` = the legacy inject-into-existing-(methodology)-slot mode.
@@ -326,10 +346,11 @@ const main = async (argv) => {
   const rest = mode === 'reconcile' ? argv.slice(1) : argv;
   const agentsPath = rest[0];
   if (!agentsPath) {
-    console.error('usage: inject-methodology.mjs [reconcile] <path/to/AGENTS.md> [fragment.md]');
-    process.exit(2);
+    logError('usage: inject-methodology.mjs [reconcile] <path/to/AGENTS.md> [fragment.md]');
+    return result(2);
   }
   const explicitFragmentArg = rest[1];
+  try {
   const text = await readFile(resolve(agentsPath), 'utf8');
 
   // Source a bounded fragment LAZILY, per slot. An explicit [fragment.md] arg (tests + manual) wins and
@@ -339,7 +360,7 @@ const main = async (argv) => {
   // the install command. The caller only invokes this when a fill is actually needed (the laziness).
   const sourceFragment = async (rel) => {
     if (explicitFragmentArg) return readFile(resolve(explicitFragmentArg), 'utf8');
-    const { dir, source } = resolveEngineDir({ env: process.env, home: homedir() });
+    const { dir, source } = resolveEngineDir({ env, home });
     return readEngineFragment(dir, { source, rel }); // sync; throws loudly when the engine is absent/invalid
   };
   const sourceFragmentOrStop = async (label, rel) => {
@@ -348,8 +369,8 @@ const main = async (argv) => {
     } catch (err) {
       // Engine needed-but-absent → a hard STOP, distinct from the soft cap-skip. The "methodology
       // engine not found/invalid" prefix lets the agent classify this exit (SKILL.md).
-      console.error(`[inject-methodology] ${label} — ${err.message}`);
-      process.exit(1);
+      logError(`[inject-methodology] ${label} — ${err.message}`);
+      throw stop(1);
     }
   };
 
@@ -362,16 +383,16 @@ const main = async (argv) => {
   // an unreadable fragment). Returns { fragment } on success, { skip } for the soft case, or
   // process.exit(1) for the hard STOP.
   const sourceChainedFragment = async (rel) => {
-    const { dir, source } = resolveEngineDir({ env: process.env, home: homedir() });
-    const stop = (err) => {
-      console.error(`[inject-methodology] reconcile STOP — ${err.message}`);
-      process.exit(1);
+    const { dir, source } = resolveEngineDir({ env, home });
+    const chainedStop = (err) => {
+      logError(`[inject-methodology] reconcile STOP — ${err.message}`);
+      throw stop(1);
     };
     if (detectEngine(dir, { source, rel }).ok) {
       try {
         return { fragment: readEngineFragment(dir, { source, rel }) };
       } catch (err) {
-        stop(err);
+        chainedStop(err);
       }
     }
     if (detectEngine(dir, { source }).ok) {
@@ -380,7 +401,7 @@ const main = async (argv) => {
     try {
       readEngineFragment(dir, { source, rel }); // throws the canonical install-me error
     } catch (err) {
-      stop(err);
+      chainedStop(err);
     }
   };
 
@@ -402,8 +423,8 @@ const main = async (argv) => {
     if (methResult.status === 'error') {
       // cap-refusal OR malformed/anchor STOP — preserve the single-slot classification (SKILL.md
       // distinguishes by the message); the file is byte-for-byte unchanged either way.
-      console.error(`[inject-methodology] reconcile refused — ${methResult.error}`);
-      process.exit(1);
+      logError(`[inject-methodology] reconcile refused — ${methResult.error}`);
+      return result(1);
     }
     const afterMeth = methResult.text; // === text when the methodology slot was already filled (custom)
     const describeMeth = {
@@ -421,18 +442,18 @@ const main = async (argv) => {
       const u = markerSlotUpgradeHint(afterMeth, METHODOLOGY_DESCRIPTOR); if (u) notes.push(u);
     }
     const reportNotes = () => {
-      for (const n of notes) console.log(`[inject-methodology] note: ${n}`);
+      for (const n of notes) log(`[inject-methodology] note: ${n}`);
     };
 
     // ── Explicit [fragment.md] binds methodology ONLY → skip the orchestration + autonomy reconciles ──
     if (explicitFragmentArg) {
       if (afterMeth === text) {
-        console.log('[inject-methodology] methodology slot already present and filled — nothing to do (zero-diff).');
-        return;
+        log('[inject-methodology] methodology slot already present and filled — nothing to do (zero-diff).');
+        return result(0);
       }
       await writeAtomic(afterMeth);
-      console.log(`[inject-methodology] reconcile: ${describeMeth}.`);
-      return;
+      log(`[inject-methodology] reconcile: ${describeMeth}.`);
+      return result(0);
     }
 
     // ── Slot 2: orchestration, reconciled on the methodology-reconciled text (the cap-check then guards
@@ -459,8 +480,8 @@ const main = async (argv) => {
           describeOrch = `orchestration-recipes pointer skipped — ${orchResult.error}`;
         } else {
           // Malformed orchestration slot/anchor → a hard STOP. No partial write.
-          console.error(`[inject-methodology] reconcile refused (orchestration) — ${orchResult.error}`);
-          process.exit(1);
+          logError(`[inject-methodology] reconcile refused (orchestration) — ${orchResult.error}`);
+          return result(1);
         }
       } else {
         finalText = orchResult.text;
@@ -493,8 +514,8 @@ const main = async (argv) => {
       // Malformed markers are a hard STOP on EVERY lane — validated before the soft-skip
       // short-circuits so a duplicate/reversed autonomy pair can never ride out as a "skip"
       // alongside a partial (methodology) write.
-      console.error(`[inject-methodology] reconcile refused (autonomy) — ${autSlot.reason}`);
-      process.exit(1);
+      logError(`[inject-methodology] reconcile refused (autonomy) — ${autSlot.reason}`);
+      return result(1);
     }
     if (orchSkipped) {
       // The chain is CAUSAL, not merely positional: a pointer never lands in a run that withheld
@@ -523,8 +544,8 @@ const main = async (argv) => {
             autSkipped = true;
             describeAut = `autonomy pointer skipped — ${autResult.error}`;
           } else {
-            console.error(`[inject-methodology] reconcile refused (autonomy) — ${autResult.error}`);
-            process.exit(1);
+            logError(`[inject-methodology] reconcile refused (autonomy) — ${autResult.error}`);
+            return result(1);
           }
         } else {
           finalText = autResult.text;
@@ -545,34 +566,44 @@ const main = async (argv) => {
     // ── One atomic write of the final (three-slot) text ──
     if (finalText === text) {
       // Byte-unchanged. Still report a skip (it is not "nothing to do" — a pointer was withheld).
-      if (orchSkipped || autSkipped) console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
-      else console.log('[inject-methodology] reconcile: all three pointers already present and filled — nothing to do (zero-diff).');
+      if (orchSkipped || autSkipped) log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
+      else log('[inject-methodology] reconcile: all three pointers already present and filled — nothing to do (zero-diff).');
       reportNotes();
-      return;
+      return result(0);
     }
     await writeAtomic(finalText);
-    console.log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
+    log(`[inject-methodology] reconcile: ${describeMeth}; ${describeOrch}; ${describeAut}.`);
     reportNotes();
-    return;
+    return result(0);
   }
 
   // Legacy inject-into-existing-slot mode (METHODOLOGY only). injectMethodology no-ops on absent markers
   // and errors on a malformed slot WITHOUT reading the fragment, so resolve+read the engine only when
   // there is a present (ok) slot to fill — a markerless legacy AGENTS.md stays a no-op without the engine.
   const fragment = findSlot(text).state === 'ok' ? await sourceFragmentOrStop('STOP', ENGINE_FRAGMENT_REL) : '';
-  const result = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
-  if (result.status === 'error') {
-    console.error(`[inject-methodology] malformed slot — refusing to edit: ${result.error}`);
-    process.exit(1);
+  const injected = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
+  if (injected.status === 'error') {
+    logError(`[inject-methodology] malformed slot — refusing to edit: ${injected.error}`);
+    return result(1);
+  }
+  if (injected.status === 'noop-absent') {
+    log('[inject-methodology] no methodology markers found — nothing to inject (legacy AGENTS.md).');
+    return result(0);
   }
-  if (result.status === 'noop-absent') {
-    console.log('[inject-methodology] no methodology markers found — nothing to inject (legacy AGENTS.md).');
-    return;
+  await writeAtomic(injected.text);
+  log('[inject-methodology] injected the bounded methodology fragment into the slot.');
+  return result(0);
+  } catch (err) {
+    if (err[EXIT] !== undefined) return result(err[EXIT]);
+    throw err;
   }
-  await writeAtomic(result.text);
-  console.log('[inject-methodology] injected the bounded methodology fragment into the slot.');
 };
 
 const { pathToFileURL } = await import('node:url');
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) await main(process.argv.slice(2));
+if (isDirectRun) {
+  const { code, stdout, stderr } = await runCli(process.argv.slice(2));
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
+}

package/tools/migrate-adr-store.mjs

@@ -125,7 +125,7 @@ const isUnder = (child, parent) => {
 
 // The ordered snapshot bases that are provably NOT stageable: the git dir first (always safe), then the
 // fallback base ONLY when its snapshot dir lands OUTSIDE cwd (else it is in the work tree and could be
-// committed — reject it; codex R1 minor). Returns [{ base, dir, viaGitDir }] (possibly empty).
+// committed — reject it). Returns [{ base, dir, viaGitDir }] (possibly empty).
 const snapshotBases = (cwd, stamp, gitDir, fallbackBase) => {
   const bases = [];
   if (gitDir) bases.push({ base: gitDir, dir: resolve(gitDir, `${SNAPSHOT_PREFIX}-${stamp}`), viaGitDir: true });
@@ -226,14 +226,14 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(`  snapshot → ${preview.dir ? `${preview.dir} (${preview.viaGitDir ? 'git dir' : 'out-of-tree fallback'})` : 'NONE — no out-of-tree location; run inside a git repo (apply would refuse otherwise)'}`);
       log(`  refresh ${refresh.length} enforcement script(s) to this kit's version${drifted.length ? ` (${drifted.length} locally differ: ${drifted.map((r) => r.name).join(', ')})` : ''}`);
       log('  then the conservation-checked rotation:');
-      // Surface the rotation's own exit code (codex R1 major): a failed dry-run must NOT print the
+      // Surface the rotation's own exit code: a failed dry-run must NOT print the
       // "run with --apply" go-ahead nor exit 0 — it would send the user to --apply on an unsafe tree.
       const code = runMigrate(['--migrate'], { root: cwd, log: (m) => log(`    ${m}`), logError: (m) => error(`    ${m}`) });
       if (code !== EXIT_OK) {
         throw stop(`the dry-run rotation would not conserve every ADR (exit ${code}) — NOT safe to --apply; fix the reported problem, then re-run.`);
       }
       // A null preview means --apply would refuse (no out-of-tree snapshot base) — never green-light it
-      // (codex R2 minor: a dry-run go-ahead must not send the user to an apply that will STOP).
+      // A dry-run go-ahead must not send the user to an apply that will STOP.
       if (preview.dir === null) {
         throw stop('no out-of-tree snapshot location — --apply would refuse; run inside a git repo (or point the fallback outside the project), then re-run.');
       }

package/tools/procedures.mjs

@@ -234,7 +234,7 @@ const groundingPreStepAdvice = (activity, slots, plans) => {
   if (!slots.some((s) => (s.backends ?? []).includes('agy-review'))) return [];
   const planArg = plans.length === 1 ? `--plan "${PLANS_REL}/${plans[0]}"` : '--plan <path>';
   // plan-authoring reviews the plan FILE — when exactly one plan is in flight, the review command
-  // is populated with the same discovered path (codex R3: a known path never renders a placeholder).
+  // is populated with the same discovered path (a known path never renders a placeholder).
   const reviewForm =
     activity === 'plan-authoring'
       ? plans.length === 1