mandrel 2.16.0 → 2.18.0

package/.agents/scripts/boot-sweep.js

@@ -46,6 +46,25 @@ import { Logger } from './lib/Logger.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
 import { sweepMergedBranches } from './lib/single-story-sweep.js';
+import { sweepTempRetention } from './lib/temp-retention.js';
+
+/**
+ * Recover the Story ids from the branch names a sweep reaped. Only the
+ * canonical `story-<id>` shape yields an id — an operator's ad-hoc branch that
+ * happened to match the include glob contributes nothing, so a purge can never
+ * be triggered by a name this framework did not create.
+ *
+ * @param {string[]|undefined} branches
+ * @returns {number[]}
+ */
+export function storyIdsFromBranches(branches) {
+  const ids = [];
+  for (const branch of Array.isArray(branches) ? branches : []) {
+    const match = /^story-(\d+)$/.exec(String(branch));
+    if (match) ids.push(Number(match[1]));
+  }
+  return ids;
+}
 
 const HELP = `Usage: node .agents/scripts/boot-sweep.js [options]
 
@@ -85,9 +104,11 @@ Options:
  *   injectedConfig?: object,
  *   injectedProvider?: object,
  *   injectedSweep?: Function,
+ *   purgeFn?: Function,
  *   logger?: { info?: Function, warn?: Function },
  * }} [args]
- * @returns {Promise<object>} the {@link sweepMergedBranches} envelope.
+ * @returns {Promise<object>} the {@link sweepMergedBranches} envelope, plus a
+ *   `tempPurge` result from the Story #4794 temp-retention catch-up.
  */
 export async function runBootSweep({
   cwd,
@@ -99,6 +120,7 @@ export async function runBootSweep({
   injectedConfig,
   injectedProvider,
   injectedSweep,
+  purgeFn = sweepTempRetention,
   logger = Logger,
 } = {}) {
   const root = path.resolve(cwd ?? PROJECT_ROOT);
@@ -125,7 +147,7 @@ export async function runBootSweep({
       config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
 
     const sweepFn = injectedSweep ?? sweepMergedBranches;
-    return await sweepFn({
+    const result = await sweepFn({
       cwd: root,
       baseBranch,
       include: includeGlobs,
@@ -140,6 +162,21 @@ export async function runBootSweep({
       lockPath,
       lockTimeoutMs,
     });
+
+    // Story #4794 — the temp-retention catch-up. Two eligibility signals, both
+    // already paid for: every branch this sweep reaped is a merge it CONFIRMED
+    // (merged PR + matching headRefOid), so those Stories' artifacts are spent;
+    // and the age floor collects everything else — the backlog from Stories
+    // merged before this existed, merged through the GitHub UI, or whose branch
+    // was already gone. Best-effort like the sweep itself: `runBootSweep`'s
+    // catch swallows any throw into the `ok: false` envelope, and exit stays 0.
+    const purge = await purgeFn({
+      config,
+      mergedStoryIds: storyIdsFromBranches(result?.reaped),
+      label: 'boot-sweep',
+      logger,
+    });
+    return { ...result, tempPurge: purge };
   } catch (err) {
     const msg = err?.message ?? String(err);
     logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);
@@ -176,8 +213,25 @@ export function buildSummaryLine(result) {
   return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${contentMergedSuffix}.`;
 }
 
-async function main() {
+/**
+ * The CLI core: parse argv, run the sweep, render the report. Extracted from
+ * the `main` shell so the argv → render decision table is reachable without
+ * spawning a real sweep against a real git tree.
+ *
+ * Both seams on the optional final `deps` parameter default to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2), so `main` and any
+ * production caller are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{ runBootSweepImpl?: typeof runBootSweep, logger?: { info: Function } }} [deps]
+ * @returns {Promise<object>} the sweep envelope that was rendered.
+ */
+export async function runBootSweepCli(
+  argv = process.argv.slice(2),
+  { runBootSweepImpl = runBootSweep, logger = Logger } = {},
+) {
   const { values } = parseArgs({
+    args: argv,
     options: {
       base: { type: 'string' },
       cwd: { type: 'string' },
@@ -192,11 +246,11 @@ async function main() {
   });
 
   if (values.help) {
-    Logger.info(HELP);
-    return;
+    logger.info(HELP);
+    return undefined;
   }
 
-  const result = await runBootSweep({
+  const result = await runBootSweepImpl({
     cwd: typeof values.cwd === 'string' ? values.cwd : undefined,
     base: typeof values.base === 'string' ? values.base : undefined,
     include: Array.isArray(values.include) ? values.include : [],
@@ -206,10 +260,15 @@ async function main() {
   });
 
   if (values.json) {
-    Logger.info(JSON.stringify(result, null, 2));
+    logger.info(JSON.stringify(result, null, 2));
   } else {
-    Logger.info(buildSummaryLine(result));
+    logger.info(buildSummaryLine(result));
   }
+  return result;
+}
+
+async function main() {
+  await runBootSweepCli();
 }
 
 runAsCli(import.meta.url, main, {

package/.agents/scripts/check-baseline-drift.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+// .agents/scripts/check-baseline-drift.js — scheduled full-scope baseline
+// drift check (Story #4776).
+//
+// The three per-PR enforcement sites (close-validation, pre-push, CI) are all
+// diff-scoped: they compare the files a branch touched against their committed
+// baseline rows. A file nobody touches after its row is written is therefore
+// never re-scored, so drift introduced indirectly — a dependency getting more
+// complex, coverage moving underneath a method — stays invisible indefinitely.
+//
+// This CLI is the periodic full-scope counterpart. It re-scores every target
+// directory through the same scorer that writes the baseline, prints a per-row
+// before/after table for everything that moved beyond the gate's tolerance,
+// and exits non-zero when it finds any — so a consumer can wire it as a
+// scheduled CI job without wrapping it in verdict-parsing glue. Wiring it is
+// deliberately consumer-side work; nothing in this repo schedules it.
+//
+// Exit codes:
+//   0 — no drift (or every kind skipped: disabled gate, no baseline, no scorer)
+//   1 — drift detected in at least one kind
+//   2 — the check itself could not run
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import {
+  DRIFT_KINDS,
+  detectBaselineDrift,
+  formatDriftReport,
+} from './lib/baselines/drift-detector.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+export const HELP_TEXT = `Usage: node .agents/scripts/check-baseline-drift.js [options]
+
+Re-score the configured baselines FULL-SCOPE and report every row whose
+current score has drifted from its committed baseline by more than the
+gate's tolerance — including files untouched by any recent diff, which the
+diff-scoped gates structurally cannot see.
+
+Options:
+  --gate <kind>       Restrict to one kind (repeatable). Default: ${DRIFT_KINDS.join(', ')}.
+  --tolerance <n>     Override the per-gate absolute tolerance.
+  --json              Emit the machine-readable report instead of the table.
+  -h, --help          Show this help.
+
+Exit codes: 0 no drift · 1 drift detected · 2 the check could not run.
+
+On drift, refresh with the printed \`*:update -- --full-scope\` command and
+commit the result with a \`baseline-refresh:\` tagged subject (non-empty body).`;
+
+/**
+ * Parse the CLI surface. Unknown flags are rejected so a typo'd `--gate`
+ * cannot silently widen a scheduled job's scope.
+ *
+ * @param {string[]} argv
+ * @returns {{ kinds: string[], tolerance: number|null, json: boolean }}
+ */
+export function parseArgs(argv = []) {
+  const kinds = [];
+  let tolerance = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--gate' && argv[i + 1]) {
+      const kind = argv[i + 1];
+      if (!DRIFT_KINDS.includes(kind)) {
+        throw new Error(
+          `[drift] unknown --gate "${kind}"; expected one of ${DRIFT_KINDS.join(', ')}`,
+        );
+      }
+      kinds.push(kind);
+      i += 1;
+    } else if (arg === '--tolerance' && argv[i + 1]) {
+      const value = Number(argv[i + 1]);
+      if (!Number.isFinite(value)) {
+        throw new Error(
+          `[drift] --tolerance must be a number (got ${argv[i + 1]})`,
+        );
+      }
+      tolerance = value;
+      i += 1;
+    } else if (arg === '--json') {
+      json = true;
+    } else {
+      throw new Error(`[drift] unrecognised argument "${arg}"`);
+    }
+  }
+  return {
+    kinds: kinds.length > 0 ? kinds : [...DRIFT_KINDS],
+    tolerance,
+    json,
+  };
+}
+
+/**
+ * Run the drift check and render it. Returns the process exit code rather
+ * than exiting, so the whole path is unit-testable.
+ *
+ * @param {{ argv?: string[], cwd?: string, detect?: typeof detectBaselineDrift }} opts
+ * @returns {Promise<{ exitCode: number, output: string }>}
+ */
+export async function runCheckBaselineDrift({
+  argv = [],
+  cwd = process.cwd(),
+  detect = detectBaselineDrift,
+} = {}) {
+  const args = parseArgs(argv);
+  const run = await detect({
+    kinds: args.kinds,
+    cwd,
+    tolerance: args.tolerance,
+  });
+  const output = args.json
+    ? JSON.stringify({ schemaVersion: '1', ...run }, null, 2)
+    : formatDriftReport(run);
+  return { exitCode: run.ok ? 0 : 1, output };
+}
+
+async function main() {
+  let result;
+  try {
+    result = await runCheckBaselineDrift({ argv: process.argv.slice(2) });
+  } catch (err) {
+    process.stdout.write(`${err?.message ?? String(err)}\n`);
+    process.exit(2);
+    return;
+  }
+  process.stdout.write(`${result.output}\n`);
+  process.exit(result.exitCode);
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'check-baseline-drift',
+  usage: HELP_TEXT,
+  exitCode: 2,
+});

package/.agents/scripts/coverage-capture.js

@@ -23,6 +23,7 @@
  */
 import path from 'node:path';
 import { getChangedFiles } from './lib/changed-files.js';
+import { isDirectInvocation } from './lib/cli-utils.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import {
   anyChangedUnderTargets,
@@ -35,7 +36,13 @@ import {
 import { Logger } from './lib/Logger.js';
 import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
 
-function parseArgs(argv) {
+/**
+ * Parse the full `process.argv` (index 2 onward) into the capture options.
+ *
+ * @param {string[]} argv
+ * @returns {{ skipWhenNoCrapFiles: boolean, ref: string, cwd: string }}
+ */
+export function parseArgs(argv) {
   const out = {
     skipWhenNoCrapFiles: false,
     ref: 'main',
@@ -50,13 +57,50 @@ function parseArgs(argv) {
   return out;
 }
 
-function main() {
-  const args = parseArgs(process.argv);
-  const config = resolveConfig({ cwd: args.cwd });
-  const { crap, coverage } = getQuality(config);
+/**
+ * The capture decision core, extracted from the CLI shell so the whole
+ * decision table (disabled gate, missing npm script, changed-file skip,
+ * freshness skip, capture + stamp) is reachable without spawning
+ * `npm run test:coverage` or touching the real filesystem.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so the CLI
+ * shell below and any production caller are unchanged.
+ *
+ * @param {string[]} [argv] Full `process.argv`-shaped array.
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   getQualityImpl?: typeof getQuality,
+ *   getChangedFilesImpl?: typeof getChangedFiles,
+ *   readPackageScriptsImpl?: typeof readPackageScripts,
+ *   hasNpmScriptImpl?: typeof hasNpmScript,
+ *   isCoverageFreshImpl?: typeof isCoverageFresh,
+ *   runCaptureImpl?: typeof runCapture,
+ *   computeContentDigestImpl?: typeof computeContentDigest,
+ *   writeCaptureStampImpl?: typeof writeCaptureStamp,
+ *   logger?: { info: Function, warn: Function, error: Function },
+ * }} [deps]
+ * @returns {number} process exit code
+ */
+export function runCoverageCapture(argv = process.argv, deps = {}) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    getQualityImpl = getQuality,
+    getChangedFilesImpl = getChangedFiles,
+    readPackageScriptsImpl = readPackageScripts,
+    hasNpmScriptImpl = hasNpmScript,
+    isCoverageFreshImpl = isCoverageFresh,
+    runCaptureImpl = runCapture,
+    computeContentDigestImpl = computeContentDigest,
+    writeCaptureStampImpl = writeCaptureStamp,
+    logger = Logger,
+  } = deps;
+  const args = parseArgs(argv);
+  const config = resolveConfigImpl({ cwd: args.cwd });
+  const { crap, coverage } = getQualityImpl(config);
 
   if (crap.enabled === false) {
-    Logger.info('[coverage-capture] CRAP gate disabled — skipping capture.');
+    logger.info('[coverage-capture] CRAP gate disabled — skipping capture.');
     return 0;
   }
 
@@ -67,8 +111,8 @@ function main() {
   // defined it. Surface a one-line, fix-naming diagnostic instead of
   // spawning `npm run test:coverage` only to propagate npm's opaque
   // "Missing script" exit code.
-  if (!hasNpmScript(readPackageScripts(args.cwd), 'test:coverage')) {
-    Logger.error(
+  if (!hasNpmScriptImpl(readPackageScriptsImpl(args.cwd), 'test:coverage')) {
+    logger.error(
       '[coverage-capture] ✖ No "test:coverage" script in package.json. ' +
         'Add one (e.g. "test:coverage": "node --test --experimental-test-coverage") ' +
         'or disable the CRAP gate via delivery.quality.gates.crap.enabled=false.',
@@ -79,45 +123,45 @@ function main() {
   if (args.skipWhenNoCrapFiles) {
     let changed;
     try {
-      changed = getChangedFiles({ ref: args.ref, cwd: args.cwd });
+      changed = getChangedFilesImpl({ ref: args.ref, cwd: args.cwd });
     } catch (err) {
       // A bad ref must not silently relax the gate. Fall through to the
       // freshness check so coverage still gets captured if needed.
-      Logger.warn(
+      logger.warn(
         `[coverage-capture] ⚠ ${err?.message ?? err} — falling back to freshness check.`,
       );
       changed = null;
     }
     if (changed && !anyChangedUnderTargets(changed, crap.targetDirs)) {
-      Logger.info(
+      logger.info(
         `[coverage-capture] No changed files under [${crap.targetDirs.join(', ')}] — skipping capture.`,
       );
       return 0;
     }
   }
 
-  const freshness = isCoverageFresh({
+  const freshness = isCoverageFreshImpl({
     coveragePath: crap.coveragePath,
     targetDirs: crap.targetDirs,
     cwd: args.cwd,
   });
   if (freshness.fresh) {
-    Logger.info(
+    logger.info(
       `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} — skipping capture.`,
     );
     return 0;
   }
 
-  Logger.info(
+  logger.info(
     `[coverage-capture] Coverage at ${crap.coveragePath} is ${freshness.reason}; running npm run test:coverage…`,
   );
-  const code = runCapture({
+  const code = runCaptureImpl({
     cwd: args.cwd,
     timeoutMs: coverage?.timeoutMs,
-    log: (m) => Logger.info(m),
+    log: (m) => logger.info(m),
   });
   if (code !== 0) {
-    Logger.error(
+    logger.error(
       `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`,
     );
     return code;
@@ -127,24 +171,29 @@ function main() {
   // freshness checks are content-aware (mtime churn from branch switches no
   // longer invalidates). Best-effort — a missing stamp just means the next
   // check falls back to the mtime heuristic.
-  const digest = computeContentDigest(args.cwd, crap.targetDirs);
+  const digest = computeContentDigestImpl(args.cwd, crap.targetDirs);
   if (
     digest &&
-    writeCaptureStamp({
+    writeCaptureStampImpl({
       cwd: args.cwd,
       coveragePath: crap.coveragePath,
       digest,
     })
   ) {
-    Logger.info('[coverage-capture] Wrote content-digest capture stamp.');
+    logger.info('[coverage-capture] Wrote content-digest capture stamp.');
   }
   return code;
 }
 
 // cli-opt-out: synchronous main returns an exit code that is forwarded via process.exit(code); runAsCli's async-main signature does not preserve the result code.
-try {
-  process.exit(main());
-} catch (err) {
-  Logger.error('[coverage-capture] unexpected error:', err);
-  process.exit(1);
+// The direct-invocation guard keeps `import`ing this module (from the unit
+// tests that drive `runCoverageCapture` with injected seams) side-effect free;
+// invoked as a CLI the behaviour — exit code and log lines — is unchanged.
+if (isDirectInvocation(import.meta.url)) {
+  try {
+    process.exit(runCoverageCapture());
+  } catch (err) {
+    Logger.error('[coverage-capture] unexpected error:', err);
+    process.exit(1);
+  }
 }

package/.agents/scripts/deliver-recover.js

@@ -82,19 +82,44 @@ export function parseArgv(argv) {
 
 /**
  * Probe and report. Exported for testing.
+ *
+ * The optional final `deps` parameter is the module's injectable seam
+ * (`.agents/rules/test-seams.md` rules 1-2): config resolution, provider
+ * construction, the probe itself, the renderer, and the log sink each default
+ * to the real implementation, so the CLI path and every production caller are
+ * unchanged. The pre-existing `injected*` fields on the first argument stay
+ * supported for callers already threading a resolved provider/config.
+ *
+ * @param {object} [args]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   createProviderImpl?: typeof createProvider,
+ *   recoverStoryImpl?: typeof recoverStory,
+ *   renderRecoveryImpl?: typeof renderRecovery,
+ *   logger?: { info: Function },
+ * }} [deps]
  */
-export async function runDeliverRecover({
-  storyId: storyIdParam,
-  cwd: cwdParam,
-  json: jsonParam,
-  reprobe: reprobeParam,
-  argv,
-  injectedProvider,
-  injectedConfig,
-  injectedGh,
-  injectedGitSpawn,
-  injectedSleepFn,
-} = {}) {
+export async function runDeliverRecover(
+  {
+    storyId: storyIdParam,
+    cwd: cwdParam,
+    json: jsonParam,
+    reprobe: reprobeParam,
+    argv,
+    injectedProvider,
+    injectedConfig,
+    injectedGh,
+    injectedGitSpawn,
+    injectedSleepFn,
+  } = {},
+  {
+    resolveConfigImpl = resolveConfig,
+    createProviderImpl = createProvider,
+    recoverStoryImpl = recoverStory,
+    renderRecoveryImpl = renderRecovery,
+    logger = Logger,
+  } = {},
+) {
   const parsed =
     storyIdParam !== undefined
       ? {
@@ -106,7 +131,7 @@ export async function runDeliverRecover({
       : parseArgv(argv ?? process.argv.slice(2));
 
   if (parsed.help) {
-    Logger.info(HELP);
+    logger.info(HELP);
     return { success: true, result: null };
   }
   if (!Number.isInteger(parsed.storyId) || parsed.storyId <= 0) {
@@ -116,10 +141,10 @@ export async function runDeliverRecover({
   }
 
   const cwd = parsed.cwd ?? PROJECT_ROOT;
-  const config = injectedConfig || resolveConfig({ cwd });
-  const provider = injectedProvider || createProvider(config);
+  const config = injectedConfig || resolveConfigImpl({ cwd });
+  const provider = injectedProvider || createProviderImpl(config);
 
-  const recovery = await recoverStory({
+  const recovery = await recoverStoryImpl({
     storyId: parsed.storyId,
     cwd,
     provider,
@@ -130,8 +155,10 @@ export async function runDeliverRecover({
     ...(injectedSleepFn ? { sleepFn: injectedSleepFn } : {}),
   });
 
-  Logger.info(
-    parsed.json ? JSON.stringify(recovery, null, 2) : renderRecovery(recovery),
+  logger.info(
+    parsed.json
+      ? JSON.stringify(recovery, null, 2)
+      : renderRecoveryImpl(recovery),
   );
   return { success: true, result: recovery };
 }