mandrel 2.36.0 → 2.38.0

package/.agents/scripts/check-cyclomatic.js

@@ -35,6 +35,7 @@ import {
   resolveCyclomaticPolicy,
   scanCyclomatic,
 } from './lib/cyclomatic-ceiling.js';
+import { resolveScanScope } from './lib/cyclomatic-scope.js';
 
 /**
  * Parse `--baseline <path>`, `--json`, and `--update`.
@@ -82,6 +83,86 @@ function loadCyclomaticBaseline(baselinePath) {
   }
 }
 
+/**
+ * `--update`: rewrite the baseline from the current (whole-tree) scan. The
+ * sanctioned motion after a deliberate refactor lands, and the only way the
+ * recorded breach count is allowed to rise.
+ *
+ * @param {{ scan: object, ceiling: number, baselinePath: string, writeFileImpl: Function, stdout: { write: (s: string) => void } }} args
+ * @returns {number} Always 0 — writing a baseline cannot fail the ratchet.
+ */
+function writeUpdatedBaseline({
+  scan,
+  ceiling,
+  baselinePath,
+  writeFileImpl,
+  stdout,
+}) {
+  const envelope = buildCyclomaticEnvelope({ rows: scan.rows, ceiling });
+  writeFileImpl(baselinePath, `${JSON.stringify(envelope, null, 2)}\n`);
+  stdout.write(
+    `[cyclomatic] wrote ${scan.rows.length} breach row(s) at ceiling c=${ceiling} to ${baselinePath}\n`,
+  );
+  return 0;
+}
+
+/**
+ * `--json`: the machine-readable comparison envelope.
+ *
+ * @param {{ policy: object, baseline: object|null, baselineRows: Array<object>, baselinePath: string, scan: object, diff: object, exitCode: number }} args
+ * @returns {string}
+ */
+function renderJsonReport({
+  policy,
+  baseline,
+  baselineRows,
+  baselinePath,
+  scan,
+  diff,
+  exitCode,
+}) {
+  return `${JSON.stringify(
+    {
+      kind: 'cyclomatic-report',
+      ceiling: policy.mustFix,
+      flag: policy.flag,
+      baselinePath,
+      baselineCeiling: baseline?.ceiling ?? null,
+      scannedFiles: scan.scannedFiles,
+      parseErrors: scan.parseErrors,
+      baselineRows,
+      currentRows: scan.rows,
+      ...diff,
+      exitCode,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * Announce a baseline the comparison cannot fully trust: absent, or recorded
+ * at a ceiling the config no longer uses. Both are warnings rather than
+ * failures — the diff still runs, and staying silent is what would let an
+ * operator read a meaningless verdict as a clean one.
+ *
+ * @param {{ baseline: object|null, mustFix: number, baselinePath: string, stderr: { write: (s: string) => void } }} args
+ * @returns {void}
+ */
+function warnAboutBaseline({ baseline, mustFix, baselinePath, stderr }) {
+  if (!baseline) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline not found at ${baselinePath} — treating as empty\n`,
+    );
+    return;
+  }
+  if (typeof baseline.ceiling === 'number' && baseline.ceiling !== mustFix) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${mustFix} — re-run with --update\n`,
+    );
+  }
+}
+
 /**
  * Top-level CLI entry. Exported so tests can drive the whole pipeline through
  * the injected seams below without spawning a process.
@@ -109,75 +190,64 @@ export async function runCli({
   writeFileImpl = (p, data) => fs.writeFileSync(p, data),
 } = {}) {
   const { baselinePath, json, update } = parseArgv(argv);
-  const quality = getQuality(resolveConfigImpl({ cwd }));
+  const config = resolveConfigImpl({ cwd });
+  const quality = getQuality(config);
   const policy = resolveCyclomaticPolicy(quality);
   const resolvedBaselinePath = path.resolve(
     cwd,
     baselinePath ?? DEFAULT_CYCLOMATIC_BASELINE,
   );
 
+  // Read the baseline before scanning: its rows are half the diff scope
+  // (Story #5109). `--update` rewrites the baseline from the whole tree, and
+  // `BASELINE_SCOPE=full` is the operator's explicit "re-derive everything",
+  // so both opt out of scoping entirely.
+  const baseline = loadBaselineImpl(resolvedBaselinePath);
+  const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
+  const scopeFiles = resolveScanScope({ cwd, config, update, baselineRows });
+
   const scan = scanImpl({
     targetDirs: policy.targetDirs,
     ignoreGlobs: policy.ignoreGlobs,
     ceiling: policy.mustFix,
     cwd,
+    scopeFiles,
   });
 
   if (update) {
-    const envelope = buildCyclomaticEnvelope({
-      rows: scan.rows,
+    return writeUpdatedBaseline({
+      scan,
       ceiling: policy.mustFix,
+      baselinePath: resolvedBaselinePath,
+      writeFileImpl,
+      stdout,
     });
-    writeFileImpl(
-      resolvedBaselinePath,
-      `${JSON.stringify(envelope, null, 2)}\n`,
-    );
-    stdout.write(
-      `[cyclomatic] wrote ${scan.rows.length} breach row(s) at ceiling c=${policy.mustFix} to ${resolvedBaselinePath}\n`,
-    );
-    return 0;
   }
 
-  const baseline = loadBaselineImpl(resolvedBaselinePath);
-  const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
   const diff = diffCyclomaticRows(baselineRows, scan.rows);
   const exitCode = diff.added.length + diff.worsened.length > 0 ? 1 : 0;
 
   if (json) {
     stdout.write(
-      `${JSON.stringify(
-        {
-          kind: 'cyclomatic-report',
-          ceiling: policy.mustFix,
-          flag: policy.flag,
-          baselinePath: resolvedBaselinePath,
-          baselineCeiling: baseline?.ceiling ?? null,
-          scannedFiles: scan.scannedFiles,
-          parseErrors: scan.parseErrors,
-          baselineRows,
-          currentRows: scan.rows,
-          ...diff,
-          exitCode,
-        },
-        null,
-        2,
-      )}\n`,
+      renderJsonReport({
+        policy,
+        baseline,
+        baselineRows,
+        baselinePath: resolvedBaselinePath,
+        scan,
+        diff,
+        exitCode,
+      }),
     );
     return exitCode;
   }
 
-  if (!baseline) {
-    stderr.write(
-      `[cyclomatic] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
-    );
-  } else if (
-    typeof baseline.ceiling === 'number' &&
-    baseline.ceiling !== policy.mustFix
-  ) {
-    stderr.write(
-      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${policy.mustFix} — re-run with --update\n`,
-    );
-  }
+  warnAboutBaseline({
+    baseline,
+    mustFix: policy.mustFix,
+    baselinePath: resolvedBaselinePath,
+    stderr,
+  });
   stdout.write('\n--- cyclomatic preview ---\n');
   stdout.write(`${renderCyclomaticDiff(diff, policy.mustFix)}\n`);
   return exitCode;

package/.agents/scripts/check-doc-links.js

@@ -19,7 +19,7 @@
 //
 //   3. No active doc mentions any retired slash command. The retired-command
 //      blocklist is seeded with `agents-bootstrap-github`,
-//      `single-story-plan` (renamed to `/plan`), and `mandrel`
+//      `single-story-plan` (renamed to `/mandrel-plan`), and `mandrel`
 //      (retired in favor of the generated `.agents/docs/workflows.md`
 //      catalog) and takes precedence over the workflow-resolution check —
 //      a retired token is always a non-zero exit even if a stale workflow
@@ -61,6 +61,18 @@ export const RETIRED_COMMANDS = new Set([
   'git-merge-pr',
 ]);
 
+// Command spellings a *historical* record may still name, keyed by the file
+// allowed to name them. A decisions log that cannot quote the name a command
+// had is a broken record: an ADR describes the world as it was, so freezing
+// its prose is the point. Scoped per-file and per-token rather than
+// allowlisted globally — everywhere else these are simply wrong, and a typo
+// like `/mandrl-plan` must still fail here. Story #5126 renamed `/plan` →
+// `/mandrel-plan` and `/deliver` → `/mandrel-deliver`; the ADRs that decided
+// the Story-only model still name them as they were called then.
+export const SUPERSEDED_COMMAND_SPELLINGS = new Map([
+  ['docs/decisions.md', new Set(['plan', 'deliver'])],
+]);
+
 // Tokens that look like `/foo` in prose but are not slash commands. Tokens
 // are stored WITHOUT the leading slash. The list focuses on common URL path
 // fragments and on-disk path roots that appear in tutorial prose. The
@@ -379,6 +391,20 @@ export function extractSlashTokens(masked) {
 
 // --- Per-file check --------------------------------------------------------
 
+/**
+ * The slash tokens `relFile` may name without resolving to a workflow: the
+ * global allowlist, plus any superseded spelling this particular file is
+ * allowed to quote.
+ *
+ * @param {string} relFile Repo-relative path of the file being checked.
+ * @returns {Set<string>} Tokens to skip, stored without the leading slash.
+ */
+function slashAllowlistFor(relFile) {
+  const superseded = SUPERSEDED_COMMAND_SPELLINGS.get(relFile);
+  if (!superseded) return SLASH_ALLOWLIST;
+  return new Set([...SLASH_ALLOWLIST, ...superseded]);
+}
+
 export function checkFile(absPath, repoRoot) {
   const violations = [];
   const source = fs.readFileSync(absPath, 'utf8');
@@ -454,14 +480,16 @@ export function checkFile(absPath, repoRoot) {
     }
   }
 
-  // 3. Slash-command resolution. Skip retired hits (already reported) and
-  //    allowlisted tokens. A command is valid if it resolves to a top-level
+  // 3. Slash-command resolution. Skip retired hits (already reported),
+  //    allowlisted tokens, and a superseded spelling in the one file allowed
+  //    to quote it (SUPERSEDED_COMMAND_SPELLINGS). A command is valid if it resolves to a top-level
   //    workflow file OR to a helpers/ module (helpers are not projected into
   //    the `.claude/commands/` tree but are still legitimate named workflows
   //    that parent workflows invoke by prose reference).
+  const slashAllowlist = slashAllowlistFor(relFile);
   for (const { token, line } of slashTokens) {
     if (RETIRED_COMMANDS.has(token)) continue;
-    if (SLASH_ALLOWLIST.has(token)) continue;
+    if (slashAllowlist.has(token)) continue;
     // Namespaced loop commands (`/loops:<name>`, Story #4289) resolve to a
     // loop unit under `.agents/workflows/loops/<name>.md`. Split on the `:`
     // and resolve the namespaced path rather than a flat `loops:<name>.md`.

package/.agents/scripts/check-generated-validator.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * CLI: keep the committed `.agentrc` validator in step with its schema
+ * (Story #5109).
+ *
+ * `getAgentrcValidator()` used to compile `AGENTRC_SCHEMA` with AJV in every
+ * process that touched configuration — 36 of the 79 entry scripts, at ~35 ms
+ * each — to produce a function that is a pure derivative of a literal already
+ * committed to the repository. The compile is now done **once, here**, and its
+ * output is committed as `lib/generated/agentrc-validator.js`; the runtime
+ * imports that module and only falls back to a live compile behind
+ * `MANDREL_AGENTRC_VALIDATOR=dynamic`.
+ *
+ * A generated artifact that nothing re-derives is a lie waiting to happen, so
+ * this script joins the standalone-ratchet family — `check-arch-cycles.js`,
+ * `check-cyclomatic.js`, `check-dead-exports.js` — and follows their contract:
+ *
+ *   - `--check` regenerates in memory and compares against the committed
+ *     file. Exit 0 when they agree, exit 1 (naming the fix) when they do not.
+ *     `npm run lint` runs this, so a schema edit that skips regeneration is
+ *     refused before it can ship a validator that accepts the wrong config.
+ *   - No flag rewrites the file. That is the sanctioned motion after a
+ *     deliberate schema change.
+ *
+ * The comparison is over the exact bytes, which is what makes the gate
+ * meaningful: AJV's standalone emit is deterministic for a given schema and
+ * AJV version, so a diff means either the schema moved or the compiler did,
+ * and both demand a fresh artifact.
+ */
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import { AGENTRC_SCHEMA } from './lib/config-settings-schema.js';
+
+const require = createRequire(import.meta.url);
+
+/** Repo-relative home of the committed artifact. */
+export const GENERATED_VALIDATOR_PATH =
+  '.agents/scripts/lib/generated/agentrc-validator.js';
+
+/** The command that rewrites it — quoted in every failure message. */
+const REGEN_COMMAND = 'npm run validator:gen';
+
+/**
+ * AJV options for the generated validator.
+ *
+ * `allErrors: true` MUST match the runtime fallback in
+ * `config-settings-schema.js#getAgentrcValidator` — it is the difference
+ * between reporting one error and reporting all of them, and every caller
+ * that renders `validate.errors` would change behaviour if the two diverged.
+ * `code.source` is what makes the instance emittable; `code.esm` selects the
+ * ES-module emit. Neither touches validation semantics.
+ */
+const AJV_OPTIONS = Object.freeze({
+  allErrors: true,
+  code: { source: true, esm: true },
+});
+
+/**
+ * Banner prepended to the emitted module.
+ *
+ * The `createRequire` shim is load-bearing: AJV's `esm` emit still reaches for
+ * its shared runtime helpers (`ajv/dist/runtime/*`) with `require(...)`, which
+ * is not defined inside an ES module. Handing the generated code a real
+ * `require` is the smallest fix that keeps the emit verbatim — rewriting those
+ * calls into imports would mean re-deriving AJV's own codegen by hand, and
+ * would silently rot the next time it changes shape.
+ *
+ * The coverage pragma matches `config-settings-schema.js`: generated code has
+ * no branches anyone authored, so a coverage figure over it measures nothing.
+ */
+const BANNER = `/* node:coverage ignore file -- generated artifact; see check-generated-validator.js */
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Precompiled AJV validator for \`AGENTRC_SCHEMA\`
+ * (.agents/scripts/lib/config-settings-schema.js), emitted by
+ * .agents/scripts/check-generated-validator.js.
+ *
+ * Regenerate with \`${REGEN_COMMAND}\`; \`npm run lint\` fails when this file
+ * and the schema disagree.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+`;
+
+/**
+ * Emit the standalone validator source for `AGENTRC_SCHEMA`.
+ *
+ * Exported so the parity test can assert the committed artifact and a fresh
+ * emit agree without shelling out to this CLI.
+ *
+ * @returns {string} Complete module source, newline-terminated.
+ */
+export function generateValidatorSource() {
+  const ajvModule = require('ajv');
+  const Ajv = ajvModule.default ?? ajvModule;
+  const standaloneModule = require('ajv/dist/standalone');
+  const standaloneCode = standaloneModule.default ?? standaloneModule;
+  const ajv = new Ajv(AJV_OPTIONS);
+  const validate = ajv.compile(AGENTRC_SCHEMA);
+  const body = standaloneCode(ajv, validate);
+  return `${BANNER}\n${body.trim()}\n`;
+}
+
+/**
+ * Read the committed artifact, or `null` when it is absent.
+ *
+ * @param {string} absPath
+ * @returns {string | null}
+ */
+function readCommitted(absPath) {
+  try {
+    return fs.readFileSync(absPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive both modes through the
+ * injected seams rather than by spawning a process.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   generateImpl?: () => string,
+ *   writeFileImpl?: (p: string, data: string) => void,
+ * }} [opts]
+ * @returns {number} 0 = in step (or written); 1 = stale artifact.
+ */
+export function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  generateImpl = generateValidatorSource,
+  writeFileImpl = (p, data) => fs.writeFileSync(p, data),
+} = {}) {
+  const checkOnly = argv.includes('--check');
+  const absPath = path.resolve(cwd, GENERATED_VALIDATOR_PATH);
+  const expected = generateImpl();
+
+  if (!checkOnly) {
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    writeFileImpl(absPath, expected);
+    stdout.write(
+      `[generated-validator] wrote ${expected.length} bytes to ${GENERATED_VALIDATOR_PATH}\n`,
+    );
+    return 0;
+  }
+
+  const actual = readCommitted(absPath);
+  if (actual === null) {
+    stderr.write(
+      `[generated-validator] ❌ ${GENERATED_VALIDATOR_PATH} is missing — run \`${REGEN_COMMAND}\`\n`,
+    );
+    return 1;
+  }
+  if (actual !== expected) {
+    stderr.write(
+      `[generated-validator] ❌ ${GENERATED_VALIDATOR_PATH} is stale against AGENTRC_SCHEMA ` +
+        `(committed ${actual.length} bytes, regenerated ${expected.length}) — run \`${REGEN_COMMAND}\`\n`,
+    );
+    return 1;
+  }
+  stdout.write(
+    `[generated-validator] ✅ ${GENERATED_VALIDATOR_PATH} is in step with AGENTRC_SCHEMA\n`,
+  );
+  return 0;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'generated-validator',
+  propagateExitCode: true,
+  errorPrefix: '[generated-validator] ❌ Fatal error',
+  usage: {
+    invocation: 'node .agents/scripts/check-generated-validator.js [--check]',
+    summary:
+      'Regenerate the committed AJV validator for `AGENTRC_SCHEMA`, or (with --check) fail when the committed artifact is stale against the schema.',
+    flags: [
+      [
+        '--check',
+        'Compare only: exit 1 when the committed artifact differs from a fresh emit. Writes nothing.',
+      ],
+    ],
+    notes: [
+      'Exit codes:\n  0  artifact written, or already in step\n  1  committed artifact is missing or stale',
+      `Regenerate with \`${REGEN_COMMAND}\`. The runtime falls back to a live AJV compile when MANDREL_AGENTRC_VALIDATOR=dynamic.`,
+    ],
+  },
+});

package/.agents/scripts/check-lifecycle-lint.js

@@ -78,6 +78,7 @@ import { fileURLToPath } from 'node:url';
 
 import { runAsCli } from './lib/cli-utils.js';
 import { walkFilesByExtension } from './lib/fs-walk.js';
+import { stripJsComments } from './lib/source-text/strip-js-comments.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -162,73 +163,6 @@ export function findPromiseAllViolations(
   return violations;
 }
 
-/**
- * Strip block (`/* … *​/`) and line (`// …`) comments from a source
- * string. Pure — exported for tests so the comment-stripping contract
- * is explicit. Defends against the corner case where the literal
- * `'gh pr merge'` appears INSIDE a justification comment at the
- * deletion site (Story #2253 deliberately leaves a prose explanation
- * referencing the removed CLI call).
- *
- * The implementation is a tiny state machine rather than a regex so it
- * correctly handles the (legal) case of a string literal containing
- * `//` or `/​*` characters.
- *
- * @param {string} src
- * @returns {string} source with comments replaced by spaces (line
- *   numbers preserved so violations report the original line).
- */
-export function stripComments(src) {
-  let out = '';
-  let i = 0;
-  const n = src.length;
-  while (i < n) {
-    const ch = src[i];
-    const nx = src[i + 1];
-    // line comment
-    if (ch === '/' && nx === '/') {
-      while (i < n && src[i] !== '\n') {
-        i += 1;
-      }
-      continue;
-    }
-    // block comment
-    if (ch === '/' && nx === '*') {
-      i += 2;
-      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) {
-        // preserve newlines so line numbers in violation reports stay
-        // aligned with the original file.
-        if (src[i] === '\n') out += '\n';
-        i += 1;
-      }
-      i += 2; // skip closing */
-      continue;
-    }
-    // string literal — copy through unchanged (we WANT to keep these
-    // so Rule 3 can flag them).
-    if (ch === '"' || ch === "'" || ch === '`') {
-      const quote = ch;
-      out += ch;
-      i += 1;
-      while (i < n) {
-        const c = src[i];
-        out += c;
-        if (c === '\\' && i + 1 < n) {
-          out += src[i + 1];
-          i += 2;
-          continue;
-        }
-        i += 1;
-        if (c === quote) break;
-      }
-      continue;
-    }
-    out += ch;
-    i += 1;
-  }
-  return out;
-}
-
 /**
  * Rule 3 enforcement (Story #2253 / Task #2255, Epic #2172 review
  * High-1). Returns an array of `{ file, line, hint }` violations for
@@ -263,7 +197,7 @@ export function findMergeLockoutViolations(
 
     const raw = read(file, 'utf8');
     const rawLines = raw.split('\n');
-    const stripped = stripComments(raw);
+    const stripped = stripJsComments(raw);
     const lines = stripped.split('\n');
     for (let i = 0; i < lines.length; i += 1) {
       const line = lines[i];

package/.agents/scripts/check-schema-references.js

@@ -88,6 +88,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
+import { stripJsComments } from './lib/source-text/strip-js-comments.js';
 
 /** Schema root, relative to the repository root. */
 const SCHEMA_ROOT = path.join('.agents', 'schemas');
@@ -114,33 +115,6 @@ const EXEMPTION_KEY = 'x-mandrel-uncompiled';
  */
 const COMPUTED_PATH_RE = /\$\{[^}]*\}\.schema\.json/;
 
-/** Block comments, including the JSDoc prose every module here opens with. */
-const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
-
-/**
- * Line comments. Anchored to start-of-line or whitespace so a `//` inside a
- * URL (`http://…`) is left alone — truncating that line could delete a real
- * reference sitting after it.
- */
-const LINE_COMMENT_RE = /(^|\s)\/\/[^\n]*/g;
-
-/**
- * Strip comments from a source before matching.
- *
- * Prose is not a compile. This module's own header names
- * `friction-event.schema.json` a dozen times while compiling nothing, and
- * every schema-loading module documents the path it loads directly above the
- * line that loads it — matching raw text would let a gate certify itself and
- * would count a docblock as enforcement, which is precisely the confusion
- * Story #4938 exists to end.
- *
- * @param {string} text raw source
- * @returns {string} source with comment bodies removed
- */
-function stripComments(text) {
-  return text.replace(BLOCK_COMMENT_RE, ' ').replace(LINE_COMMENT_RE, '$1');
-}
-
 /**
  * Parse argv. Exported so a unit test can pin the parser without spawning.
  *
@@ -194,7 +168,7 @@ function walk(dir, extensions, acc = []) {
 function readSources(root) {
   return walk(root, JS_EXTENSIONS).map((file) => ({
     rel: path.relative(root, file),
-    text: stripComments(fs.readFileSync(file, 'utf8')),
+    text: stripJsComments(fs.readFileSync(file, 'utf8')),
   }));
 }
 

package/.agents/scripts/check-test-temp-hygiene.js

@@ -422,7 +422,7 @@ export function findReservedIdStreamFiles(tempDir) {
  * the **repository-root** temp tree (Story #4892).
  *
  * Resolution matters more than it looks: every writer anchors a relative
- * `tempRoot` to the *main checkout* (so a Story worktree and its `/deliver`
+ * `tempRoot` to the *main checkout* (so a Story worktree and its `/mandrel-deliver`
  * host converge on one ledger), so a guard that scanned `cwd` would scan an
  * empty worktree tree and pass vacuously on the very tree it is meant to
  * protect. `resolveRoot` is the injection seam for tests.

package/.agents/scripts/check-workflow-cli-lint.js

@@ -136,7 +136,7 @@ export function toParagraphs(lines) {
  *      heading (inclusive) — i.e. the section is *about* that script, so the
  *      table is restating its surface.
  *
- * A slash command's own argument table (`/plan`, `/deliver`) has no script
+ * A slash command's own argument table (`/mandrel-plan`, `/mandrel-deliver`) has no script
  * behind it — nothing owns those flags but the workflow prose itself — so
  * condition 2 leaves it alone by design.
  *