mandrel 2.36.0 → 2.37.0

package/.agents/scripts/lib/install-cmd-parser.js

@@ -17,7 +17,7 @@ import { spawnSync as defaultSpawnSync } from 'node:child_process';
  * @param {string} installCmd
  * @returns {{ bin: string, args: string[], shell: boolean }}
  */
-export function parseInstallCmd(installCmd) {
+function parseInstallCmd(installCmd) {
   const tokens = String(installCmd ?? '')
     .trim()
     .split(/\s+/)

package/.agents/scripts/lib/knip-entry-sync.js

@@ -59,6 +59,7 @@ import {
   resolveKnipEntryPatterns,
   __testing as resolverTesting,
 } from './knip-config-resolver.js';
+import { stripJsComments } from './source-text/strip-js-comments.js';
 
 // Only `resolveEntrySync` and `renderEntrySyncReport` are public — they are
 // what `check-knip-entries.js` calls. Everything else is module-private and
@@ -89,63 +90,6 @@ const INVOCATION_SURFACES = Object.freeze([
   { kind: 'dir', at: SCRIPTS_DIR, test: /\.js$/ },
 ]);
 
-/**
- * Strip line and block comments from JavaScript source, preserving string and
- * template literals so a `'https://…'` or a `` `${x}//y` `` is not mangled.
- *
- * Comments are stripped before scanning `.js` surfaces so a JSDoc paragraph
- * that merely *names* a CLI ("superseded by `node .agents/scripts/foo.js`")
- * cannot confer liveness on it. Several such mentions exist today; every one
- * of them is prose about a script's internals, not a call.
- *
- * Replaces comment bodies with equivalent whitespace rather than deleting
- * them, so byte offsets and line numbers survive for any future caller that
- * wants to report a position.
- *
- * @param {string} source
- * @returns {string}
- */
-function stripJsComments(source) {
-  const text = String(source ?? '');
-  let out = '';
-  let i = 0;
-  const blank = (s) => s.replace(/[^\n]/g, ' ');
-  while (i < text.length) {
-    const two = text.slice(i, i + 2);
-    if (two === '//') {
-      const end = text.indexOf('\n', i);
-      const stop = end === -1 ? text.length : end;
-      out += blank(text.slice(i, stop));
-      i = stop;
-    } else if (two === '/*') {
-      const end = text.indexOf('*/', i + 2);
-      const stop = end === -1 ? text.length : end + 2;
-      out += blank(text.slice(i, stop));
-      i = stop;
-    } else {
-      const ch = text[i];
-      if (ch === "'" || ch === '"' || ch === '`') {
-        let j = i + 1;
-        while (j < text.length) {
-          if (text[j] === '\\') {
-            j += 2;
-            continue;
-          }
-          if (text[j] === ch) break;
-          j += 1;
-        }
-        const stop = Math.min(j + 1, text.length);
-        out += text.slice(i, stop);
-        i = stop;
-      } else {
-        out += ch;
-        i += 1;
-      }
-    }
-  }
-  return out;
-}
-
 /**
  * Recursively list files under `dir`, skipping `node_modules` and `.git`.
  *

package/.agents/scripts/lib/maintainability-utils.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { minimatch } from 'minimatch';
+import { Minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
@@ -27,6 +27,57 @@ const IGNORED_DIRS = new Set([
   '.next',
 ]);
 
+/**
+ * Compiled-matcher cache for `isIgnoredByGlobs`, keyed on the pattern list.
+ *
+ * `minimatch(path, glob)` re-parses `glob` into an AST on every call, so the
+ * scan was paying O(files × globs) glob *compilations* to answer O(files ×
+ * globs) glob *matches* — 12–17 ms over the 619-file tree against 0.5 ms
+ * once the patterns are compiled (Story #5109). The number of distinct
+ * pattern lists in a process is tiny (one per gate), and each list is
+ * config-derived and immutable, so an unbounded `Map` keyed on the joined
+ * patterns is bounded in practice.
+ *
+ * Each entry also memoises the per-path verdict. The baseline gates ask the
+ * same question about the same path many times over — `crap.json` carries
+ * thousands of method rows spread over a few hundred files, and the evaluate
+ * phase filters every row — so the second and later asks about a path cost a
+ * `Map` lookup instead of a globstar walk. Both caches are keyed on
+ * config-derived, immutable inputs, and both are bounded by the tree the
+ * process is scanning.
+ *
+ * `\u0000` is the join separator because it cannot occur in a glob, so two
+ * different lists cannot collide onto one key.
+ *
+ * @type {Map<string, {matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}>}
+ */
+const IGNORE_MATCHER_CACHE = new Map();
+
+/**
+ * Compile (once) the `Minimatch` instances for a pattern list, alongside the
+ * per-path verdict memo that shares their lifetime.
+ *
+ * Non-string patterns are dropped rather than compiled — `minimatch()` would
+ * have thrown on them, and the functional call site never fed it any, so
+ * dropping preserves the observable result set.
+ *
+ * @param {string[]} ignoreGlobs
+ * @returns {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}}
+ */
+function ignoreMatcherEntry(ignoreGlobs) {
+  const key = ignoreGlobs.join('\u0000');
+  let entry = IGNORE_MATCHER_CACHE.get(key);
+  if (entry) return entry;
+  entry = {
+    matchers: ignoreGlobs
+      .filter((g) => typeof g === 'string')
+      .map((g) => new Minimatch(g, { dot: true })),
+    verdicts: new Map(),
+  };
+  IGNORE_MATCHER_CACHE.set(key, entry);
+  return entry;
+}
+
 /**
  * Test whether an absolute (or repo-relative) file path matches any of the
  * configured `ignoreGlobs`. This is the single source of truth for how the
@@ -39,22 +90,62 @@ const IGNORED_DIRS = new Set([
  *
  * Matching mirrors `scanDirectory`: the path is reduced to a canonicalised,
  * POSIX, repo-relative form and tested against each glob with minimatch's
- * `{ dot: true }` so dot-prefixed roots like `.agents/` match.
+ * `{ dot: true }` so dot-prefixed roots like `.agents/` match. The patterns
+ * are compiled at most once per distinct list (see `IGNORE_MATCHER_CACHE`);
+ * the matched set is identical to the functional `minimatch()` call this
+ * replaced, which is what the `gate-scan-fast-path` test pins over the real
+ * configured `ignoreGlobs`.
  *
  * @param {string} filePath absolute or relative path to the source file
  * @param {string[]} ignoreGlobs minimatch patterns; empty/absent is a no-op
  * @param {string} [cwd] root for repo-relative resolution; defaults to cwd
  * @returns {boolean} true when the file matches at least one ignore glob
  */
-export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
-  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return false;
-  const matchCwd = cwd ?? process.cwd();
+/**
+ * Reduce an absolute-or-relative path to the canonicalised, POSIX,
+ * repo-relative form the ignore patterns are written against.
+ *
+ * @param {string} filePath
+ * @param {string} matchCwd
+ * @returns {string}
+ */
+function canonicalRelPath(filePath, matchCwd) {
   const absFilePath = path.isAbsolute(filePath)
     ? filePath
     : path.resolve(matchCwd, filePath);
   const rawRel = path.relative(matchCwd, absFilePath).replace(/\\/g, '/');
-  const relPath = canonicalisePath(rawRel);
-  return ignoreGlobs.some((g) => minimatch(relPath, g, { dot: true }));
+  return canonicalisePath(rawRel);
+}
+
+/**
+ * Answer "does this path match any of the entry's patterns", consulting and
+ * populating the entry's verdict memo.
+ *
+ * Split out of `isIgnoredByGlobs` rather than inlined: the memo's
+ * hit/miss test is a branch, and folding it into the caller pushed that
+ * function from cyclomatic 4 to 5 — over the per-method CRAP contract the
+ * pre-push preview enforces. The lookup belongs beside the cache it reads
+ * anyway, and the hot function keeps a flat shape.
+ *
+ * @param {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}} entry
+ * @param {string} relPath Canonicalised, POSIX, repo-relative path.
+ * @returns {boolean}
+ */
+function memoisedIgnoreVerdict(entry, relPath) {
+  const memoised = entry.verdicts.get(relPath);
+  if (memoised !== undefined) return memoised;
+  const verdict = entry.matchers.some((m) => m.match(relPath));
+  entry.verdicts.set(relPath, verdict);
+  return verdict;
+}
+
+export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
+  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return false;
+  const matchCwd = cwd ?? process.cwd();
+  return memoisedIgnoreVerdict(
+    ignoreMatcherEntry(ignoreGlobs),
+    canonicalRelPath(filePath, matchCwd),
+  );
 }
 
 /**
@@ -107,7 +198,7 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * Calculates maintainability scores for a list of file paths.
  *
  * Each file's transpile-then-analyze unit is dispatched to a
- * worker_threads pool sized to `os.availableParallelism()`. Workers
+ * worker_threads pool whose width `runOnPool` resolves. Workers
  * are recycled across files so TypeScript loads at most once per
  * worker. The pool is bypassed for batches of fewer than
  * `SERIAL_THRESHOLD` files because spawn overhead dominates at small
@@ -129,9 +220,16 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * and nothing said so.
  *
  * @param {string[]} paths
+ * @param {{serialThreshold?: number}} [opts] `serialThreshold` overrides the
+ *   pool-vs-serial cutover for this call only. Production callers omit it;
+ *   the parity tests use it to drive the pooled path on a small fixture set
+ *   rather than materialising 256 files to clear the cutover.
  * @returns {Promise<Record<string, number>>}
  */
-export async function calculateAll(paths) {
+export async function calculateAll(paths, opts = {}) {
+  const serialThreshold = Number.isFinite(opts?.serialThreshold)
+    ? opts.serialThreshold
+    : SERIAL_THRESHOLD;
   const cwd = process.cwd();
   const indexed = paths.map((p) => ({
     abs: p,
@@ -139,7 +237,7 @@ export async function calculateAll(paths) {
   }));
 
   let perFile;
-  if (indexed.length < SERIAL_THRESHOLD) {
+  if (indexed.length < serialThreshold) {
     perFile = indexed.map(({ abs, relPath }) => {
       try {
         return { relPath, ...scoreFile(abs) };

package/.agents/scripts/lib/observability/source-classifier.js

@@ -94,6 +94,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-cyclomatic.js',
   'check-dead-exports.js',
   'check-doc-links.js',
+  'check-generated-validator.js',
   'check-gherkin-corpus.js',
   'check-knip-entries.js',
   'check-lifecycle-lint.js',

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -197,6 +197,26 @@ function planFingerprintMarker(fingerprint) {
   return `<!-- ${PLAN_FINGERPRINT_MARKER_PREFIX} ${fingerprint} -->`;
 }
 
+/** The one parser for the marker {@link planFingerprintMarker} renders. */
+const PLAN_FINGERPRINT_MARKER_RE = new RegExp(
+  `<!--\\s*${PLAN_FINGERPRINT_MARKER_PREFIX}\\s*([0-9a-f]+)\\s*-->`,
+);
+
+/**
+ * Recover the plan fingerprint an issue body was stamped with, or `null` when
+ * the body carries no marker. Module-private: both readers of the marker (the
+ * resume index and the create-retry adoption probe) go through it so they can
+ * never drift into recognising different Stories as "already created".
+ *
+ * @param {unknown} body
+ * @returns {string|null}
+ */
+function extractPlanFingerprint(body) {
+  if (typeof body !== 'string') return null;
+  const match = body.match(PLAN_FINGERPRINT_MARKER_RE);
+  return match ? match[1] : null;
+}
+
 /**
  * Labels the authoring pass is never allowed to set. The `agent::*` axis is
  * the runtime's lifecycle state (persist owns the terminal `agent::ready`
@@ -617,14 +637,9 @@ async function indexExistingStories(provider) {
     if (title !== '') {
       idsByTitle.set(title, [...(idsByTitle.get(title) ?? []), id]);
     }
-    const body = typeof issue?.body === 'string' ? issue.body : '';
-    const match = body.match(
-      new RegExp(
-        `<!--\\s*${PLAN_FINGERPRINT_MARKER_PREFIX}\\s*([0-9a-f]+)\\s*-->`,
-      ),
-    );
-    if (!match) continue;
-    byFingerprint.set(match[1], {
+    const fingerprint = extractPlanFingerprint(issue?.body);
+    if (!fingerprint) continue;
+    byFingerprint.set(fingerprint, {
       id,
       title,
       url: issue.html_url ?? issue.url ?? undefined,
@@ -633,6 +648,42 @@ async function indexExistingStories(provider) {
   return { byFingerprint, idsByTitle };
 }
 
+/**
+ * Re-run the resume lookup for a single fingerprint and return the **raw**
+ * issue, or `null`.
+ *
+ * This is the probe `createIssue` calls before any retry POST (Story #5112).
+ * A create whose response was lost has already filed the issue; retrying
+ * blind duplicates it. Because the body posted carries the fingerprint
+ * marker, the same content-keyed lookup the resume path uses answers "did
+ * attempt 1 land?" authoritatively — from the server's state, not from a
+ * client-side guess about where the connection broke.
+ *
+ * Best-effort like {@link indexExistingStories}: a provider without the
+ * listing surface, or a listing that throws, yields `null` and the retry
+ * proceeds exactly as it did before.
+ *
+ * @param {{ provider: object, fingerprint: string }} args
+ * @returns {Promise<object|null>}
+ */
+async function findOpenStoryByPlanFingerprint({ provider, fingerprint }) {
+  if (typeof provider?.listIssuesByLabel !== 'function') return null;
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) return null;
+  let issues;
+  try {
+    issues = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.STORY,
+    });
+  } catch {
+    return null;
+  }
+  for (const issue of Array.isArray(issues) ? issues : []) {
+    if (extractPlanFingerprint(issue?.body) === fingerprint) return issue;
+  }
+  return null;
+}
+
 /**
  * Warn when a Story with this title is already open but did **not** match the
  * fingerprint — i.e. its authored content differs from what this run is about
@@ -1000,6 +1051,14 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
         ...(applyCohortLabel ? [cohortLabel] : []),
         ...(applyRouteLabel ? [routeLabel] : []),
       ],
+      // Story #5112 — hand the provider the same content-keyed lookup this
+      // loop's resume path uses, so a retry after a lost response adopts the
+      // issue attempt 1 already filed instead of creating a twin.
+      findExisting: () =>
+        findOpenStoryByPlanFingerprint({
+          provider,
+          fingerprint: story.fingerprint,
+        }),
     });
     const id = result?.id ?? result?.number;
     if (!Number.isInteger(id)) {
@@ -1012,7 +1071,9 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       id,
       title: story.title,
       url: result.url,
-      adopted: false,
+      // True when the provider's retry probe adopted an issue a lost-response
+      // first attempt had already filed — pre-existing either way.
+      adopted: result.adopted === true,
     });
     idBySlug.set(story.slug, id);
   }

package/.agents/scripts/lib/orchestration/pr-watch.js

@@ -50,35 +50,6 @@ import { applyBehindUpdate } from './behind-recovery.js';
  * values collapse to `'skipped'` so any future GitHub state we haven't
  * enumerated still maps into the vocabulary.
  */
-/**
- * The raw check-state tokens `normalizeCheckState` recognizes (lowercased).
- * A token absent from this set is one we have NOT enumerated — the watch
- * path collapses it to `'skipped'` (validate-anything), but a fail-closed
- * consumer (the auto-merge arming probe) must treat it as unknown-therefore-
- * blocking rather than trust the `'skipped'` collapse. Exported so that
- * stricter consumer lives here as the single vocabulary owner.
- */
-export const RECOGNIZED_CHECK_STATES = Object.freeze(
-  new Set([
-    '',
-    'pending',
-    'queued',
-    'in_progress',
-    'requested',
-    'waiting',
-    'success',
-    'completed',
-    'failure',
-    'startup_failure',
-    'neutral',
-    'cancelled',
-    'timed_out',
-    'action_required',
-    'stale',
-    'skipped',
-  ]),
-);
-
 export function normalizeCheckState(raw) {
   const v = String(raw ?? '')
     .trim()
@@ -325,7 +296,7 @@ export function allTerminal(outcomes) {
  * red check): a `'still-running'` map means "re-arm the watch / hand off
  * to `/loop`," never "the change is broken."
  */
-export const STILL_RUNNING = 'still-running';
+const STILL_RUNNING = 'still-running';
 
 /**
  * Promote any leftover `'pending'` outcomes to the schema-valid

package/.agents/scripts/lib/orchestration/reassert-status-column.js

@@ -38,14 +38,14 @@ import { ColumnSync, columnForLabels } from './column-sync.js';
  * long enough to outlast the typical GitHub built-in workflow fire
  * timing without ballooning the close-path wall clock.
  */
-export const DEFAULT_POLL_ATTEMPTS = 4;
+const DEFAULT_POLL_ATTEMPTS = 4;
 
 /**
  * Default delay between drift checks (ms). Five seconds is a sweet
  * spot: short enough that the operator doesn't perceive the close
  * path as hung, long enough that one re-fire usually wins the race.
  */
-export const DEFAULT_POLL_DELAY_MS = 5000;
+const DEFAULT_POLL_DELAY_MS = 5000;
 
 /**
  * Production sleep function. Tests inject `sleepFn: () => Promise.resolve()`

package/.agents/scripts/lib/orchestration/review-providers/codex.js

@@ -57,7 +57,7 @@ export const CODEX_REMEDIATIONS = Object.freeze({
  *
  * Exported so tests can extend the list without monkey-patching `os`.
  */
-export const DEFAULT_PLUGIN_MARKERS = Object.freeze([
+const DEFAULT_PLUGIN_MARKERS = Object.freeze([
   path.join(os.homedir(), '.claude', 'plugins', 'codex-plugin-cc'),
   path.join(os.homedir(), '.claude', 'plugins', 'openai', 'codex-plugin-cc'),
 ]);
@@ -194,7 +194,7 @@ export function parseCodexFindings(rawStdout) {
  * @param {{ baseRef: string, headRef: string, depth?: import('./types.js').ReviewDepth }} args
  * @returns {string}
  */
-export function buildCodexReviewPrompt({ baseRef, headRef, depth }) {
+function buildCodexReviewPrompt({ baseRef, headRef, depth }) {
   return (
     `/codex:review --base ${baseRef} --head ${headRef} --wait ` +
     `${renderDepthDirective(depth)}`
@@ -214,7 +214,7 @@ export function buildCodexReviewPrompt({ baseRef, headRef, depth }) {
  * @param {{ baseRef: string, headRef: string, depth?: import('./types.js').ReviewDepth }} args
  * @returns {{ status: number, stdout: string, stderr: string }}
  */
-export function defaultInvokeCodexReview({ baseRef, headRef, depth }) {
+function defaultInvokeCodexReview({ baseRef, headRef, depth }) {
   const cliArgs = [
     '--print',
     buildCodexReviewPrompt({ baseRef, headRef, depth }),

package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js

@@ -102,7 +102,7 @@ export function renderFinding(finding) {
  * @param {ReadonlyArray<string>} messages
  * @returns {string[]}  lines to append (empty when no messages)
  */
-export function renderManualPromptsSection(messages) {
+function renderManualPromptsSection(messages) {
   const filtered = Array.isArray(messages)
     ? messages.filter((m) => typeof m === 'string' && m.trim().length > 0)
     : [];

package/.agents/scripts/lib/orchestration/review-providers/native.js

@@ -267,8 +267,14 @@ function isJsMaintainabilityFile(relPath) {
  * `reportFn` forces the serial path (the injected scorer cannot cross the
  * worker boundary).
  *
+ * `serialThreshold` overrides the pool-vs-serial cutover for one call. It is
+ * the seam the parity test uses to drive the pooled branch: Story #5109
+ * retuned `POOL_SERIAL_THRESHOLD` from 8 to 256 against measured data, and a
+ * fixture sized to clear the old number would otherwise have gone quietly
+ * serial while still claiming to cover the pool.
+ *
  * @param {string[]} changedFiles
- * @param {{ reportFn?: Function, classifier?: Function, runOnPoolFn?: typeof runOnPool, headRef?: string|null, gitSpawnFn?: typeof gitSpawn, readHeadSourceFn?: typeof readHeadSource }} [deps]
+ * @param {{ reportFn?: Function, classifier?: Function, runOnPoolFn?: typeof runOnPool, headRef?: string|null, gitSpawnFn?: typeof gitSpawn, readHeadSourceFn?: typeof readHeadSource, serialThreshold?: number }} [deps]
  * @returns {Promise<{ totalFiles: number, jsFiles: number, maintainability: object[], criticalFindings: Finding[], mediumFindings: Finding[] }>}
  */
 export async function analyzeChangedFiles(
@@ -280,6 +286,7 @@ export async function analyzeChangedFiles(
     headRef = null,
     gitSpawnFn = gitSpawn,
     readHeadSourceFn = readHeadSource,
+    serialThreshold = SERIAL_THRESHOLD,
   } = {},
 ) {
   const results = {
@@ -308,7 +315,7 @@ export async function analyzeChangedFiles(
   const customReportFn = reportFn != null;
 
   // Serial path: small batches, or whenever a caller injects its own scorer.
-  if (jsFiles.length < SERIAL_THRESHOLD || customReportFn) {
+  if (jsFiles.length < serialThreshold || customReportFn) {
     for (let i = 0; i < jsFiles.length; i += 1) {
       const relPath = jsFiles[i];
       const source = sources[i];

package/.agents/scripts/lib/orchestration/review-providers/review-depth.js

@@ -28,7 +28,7 @@
  *
  * @type {Readonly<Record<ReviewDepth, string>>}
  */
-export const DEPTH_DIRECTIVES = Object.freeze({
+const DEPTH_DIRECTIVES = Object.freeze({
   light:
     'Review depth: LIGHT. Run a single pass focused on spec adherence over the ' +
     'changed surface — confirm the change matches its stated intent. Reduce the ' +
@@ -54,7 +54,7 @@ export const DEPTH_DIRECTIVES = Object.freeze({
  * @param {unknown} depth
  * @returns {ReviewDepth}
  */
-export function normalizeDepth(depth) {
+function normalizeDepth(depth) {
   return depth === 'light' || depth === 'deep' ? depth : 'standard';
 }
 

package/.agents/scripts/lib/orchestration/review-providers/security-review.js

@@ -59,7 +59,7 @@ export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
  * @param {{ spawnFn?: typeof spawnSync }} [opts]
  * @returns {boolean}
  */
-export function defaultProbeClaudeCli(opts = {}) {
+function defaultProbeClaudeCli(opts = {}) {
   const spawnFn = opts.spawnFn ?? spawnSync;
   try {
     const result = spawnFn('claude', ['--version'], {
@@ -162,7 +162,7 @@ export function parseSecurityReviewFindings(rawStdout) {
  * (Story #3937) so a high-risk Epic instructs the model toward a deeper
  * second-pass review while a low-risk one keeps it light.
  */
-export const SECURITY_REVIEW_INVOKE_PROMPT =
+const SECURITY_REVIEW_INVOKE_PROMPT =
   'Run /security-review against the diff `{baseRef}`...`{headRef}` ' +
   'for {scopeLabel} #{ticketId}. {depthDirective} After the review, emit ' +
   'ONLY a JSON array of findings on stdout with this exact shape:\n\n' +
@@ -208,7 +208,7 @@ export function buildSecurityReviewPrompt(input) {
  * @param {ReviewInput} input
  * @returns {{ status: number, stdout: string, stderr: string }}
  */
-export function defaultInvokeSecurityReview(input) {
+function defaultInvokeSecurityReview(input) {
   const prompt = buildSecurityReviewPrompt(input);
   const result = spawnSync('claude', ['--print', prompt], {
     encoding: 'utf-8',

package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js

@@ -87,6 +87,50 @@ export function resolveWaitForMerge({
   };
 }
 
+/**
+ * Flags this CLI advertised in its `--help` descriptor and never implemented
+ * (Story #5100). `--dry-run` was transcribed into the usage block by the
+ * #4750 self-describing sweep and read by nothing in this pipeline —
+ * `git log -S dryRun` over it is empty in every revision — so an operator who
+ * trusted it got a real base-sync merge, an `agent::blocked` Story, and a
+ * terminal envelope that then captured `deliver-recover`'s routing.
+ * `--no-evidence` names a working flag on the gate wrappers
+ * (`evidence-gate.js`), but the slot this CLI parsed had no reader at all.
+ *
+ * Deleting them from the descriptor is NOT enough. `parseSprintArgs` runs
+ * `parseArgs` with `strict: false`, so an unknown flag is silently ignored and
+ * the close proceeds for real — the identical injury, now with no help text to
+ * explain it. Fail closed instead, exactly as `parseMergeWatchMode` does for an
+ * unrecognized mode: throw during option parsing, before the first phase, so
+ * the CLI boundary reports `failed` at phase `init` and nothing is mutated.
+ */
+const RETIRED_FLAGS = Object.freeze({
+  '--dry-run':
+    'this pipeline has never had a dry-run mode; it was advertised in error.',
+  '--no-evidence':
+    'per-close evidence control was never wired here; the working flag of that name belongs to the gate wrappers.',
+});
+
+/**
+ * Reject a retired flag before any phase runs.
+ *
+ * Matches `--flag` and `--flag=value`; a bare `--` terminator or a positional
+ * that merely contains the text is not a flag and does not trip it.
+ *
+ * @param {string[]} argv argv tail (`process.argv.slice(2)`)
+ * @throws {Error} naming the flag, why it is gone, and that nothing was mutated
+ */
+function assertNoRetiredFlags(argv) {
+  for (const [flag, why] of Object.entries(RETIRED_FLAGS)) {
+    const present = argv.some((a) => a === flag || a.startsWith(`${flag}=`));
+    if (!present) continue;
+    throw new Error(
+      `${flag} was retired: ${why} Nothing was mutated — no branch, label, ` +
+        `comment, or PR was touched. Re-run without it to close for real.`,
+    );
+  }
+}
+
 /**
  * Parse and resolve all CLI / injection options for `runSingleStoryClose`.
  *
@@ -116,7 +160,14 @@ export function parseCloseOptions({
   // which is precisely what `resolveFlag` already does below, preferring the
   // param over the parsed slot. One expression per flag now serves both
   // callers, so a new flag is added in one place instead of two that can drift.
-  const parsed = storyIdParam === undefined ? parseSprintArgs() : {};
+  // The guard runs on the argv door only: an injecting caller supplies
+  // `storyIdParam` and never reads argv, so the host process's flags (a test
+  // runner's, say) are none of its business.
+  let parsed = {};
+  if (storyIdParam === undefined) {
+    assertNoRetiredFlags(process.argv.slice(2));
+    parsed = parseSprintArgs();
+  }
   // Preserve undefined so resolveWaitForMerge can apply the closeAndLand
   // config default when neither flag was supplied.
   const waitForMergeExplicit = resolveFlag(

package/.agents/scripts/lib/orchestration/story-close/format-autofix.js

@@ -63,7 +63,7 @@ export const FORMAT_AUTOFIX_TIMEOUT_EXIT_CODE = 124;
  * @param {(args: string[], opts: object) => string} git
  * @returns {string[]}
  */
-export function listDirtyPaths(cwd, git) {
+function listDirtyPaths(cwd, git) {
   const out = git(['status', '--porcelain'], {
     cwd,
     encoding: 'utf8',
@@ -91,10 +91,7 @@ export function listDirtyPaths(cwd, git) {
  * }} [opts]
  * @returns {{ writeCmdString: string, writeCmd: string, writeArgs: string[] }}
  */
-export function resolveFormatterCmd({
-  commands,
-  dropTrailingDot = false,
-} = {}) {
+function resolveFormatterCmd({ commands, dropTrailingDot = false } = {}) {
   // `resolveFormatWriteCommand` reads `config.project.commands`; wrap the
   // caller-supplied `commands` map into that canonical shape.
   const writeCmdString = resolveFormatWriteCommand({ project: { commands } });

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -24,7 +24,7 @@ import {
 } from './retro-proposals.js';
 import { upsertStructuredComment } from './ticketing.js';
 
-export const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
+const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
 
 /** Milliseconds in one day — the unit `frictionWindowDays` is expressed in. */
 const MS_PER_DAY = 24 * 60 * 60 * 1000;