mandrel 2.15.0 → 2.17.0

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-light.js

@@ -79,18 +79,29 @@ import { createProvider } from './lib/provider-factory.js';
 const HELP = `\
 Usage:
   deliver-light.js --prompt <text> [--creates csv] [--refactors csv]
-                   [--acceptance n] [--route lite|full] [--reason <text>]
+                   [--acceptance n] [--kinds csv] [--magnitude m]
+                   [--uncertainty u] [--route lite|full] [--reason <text>]
                    [--amends '#id'] [--yes]
   deliver-light.js --backstop --story <id>
 
 The thin /deliver-light entry point: suitability gate → inline receipt Story →
 the same single-story-init.js / single-story-close.js engine /deliver uses.
 
+The gate judges EFFORT and RISK, not artifact counts: N instances of one
+mechanical edit is one kind at N sites. It rejects only clearly-epic work; the
+--backstop pass enforces size against the actual diff.
+
 Gate options:
   --prompt <text>    Operator prompt describing the change. Required for the gate.
   --creates <csv>    Predicted NEW file paths (comma-separated).
   --refactors <csv>  Predicted edited/existing file paths (comma-separated).
-  --acceptance <n>   Predicted acceptance-criteria count (default 1).
+  --acceptance <n>   Predicted acceptance-criteria count (default 1). Not capped.
+  --kinds <csv>      Distinct KINDS of change (default: one per assumption, so
+                     N same-shaped edits count once).
+  --magnitude <m>    Coarse effort bucket: trivial | moderate | substantial
+                     (default moderate; substantial routes to /plan).
+  --uncertainty <u>  determined (the request fixes the shape) | needs-design
+                     (default determined; needs-design routes to /plan).
   --route <r>        Ledgered model verdict route: lite | full.
   --reason <text>    Recorded reason for a lite verdict (required for lite).
   --amends <#id>     Mark this as an amendment of an existing issue.
@@ -166,17 +177,25 @@ export function synthesizeAcceptance(count) {
  *   creates?: string[],
  *   refactors?: string[],
  *   acceptance?: number,
+ *   kinds?: string[],
+ *   magnitude?: string,
+ *   uncertainty?: string,
  *   route?: string,
  *   reason?: string,
  *   yes?: boolean,
  *   injectedRules?: object,
- * }} args
+ * }} args `kinds` / `magnitude` / `uncertainty` are the declared effort-and-risk
+ *   axes the gate judges (Story #4764); omitting them declares no signal, not a
+ *   small one — an unrecognized bucket fails closed.
  * @returns {{ action: string, suitability: object, outcome: object }}
  */
 export function runLightGate({
   creates = [],
   refactors = [],
   acceptance,
+  kinds,
+  magnitude,
+  uncertainty,
   route,
   reason,
   yes = false,
@@ -186,6 +205,9 @@ export function runLightGate({
   const suitability = deriveLightSuitability({
     predictedChanges,
     predictedAcceptance: synthesizeAcceptance(acceptance),
+    predictedKinds: kinds,
+    predictedMagnitude: magnitude,
+    predictedUncertainty: uncertainty,
     verdict: { route, reason },
     injectedRules,
   });
@@ -355,6 +377,9 @@ export async function runGateMode(values, deps = {}) {
     acceptance: values.acceptance
       ? Number.parseInt(String(values.acceptance), 10)
       : 1,
+    kinds: parseCsvPaths(values.kinds),
+    magnitude: values.magnitude,
+    uncertainty: values.uncertainty,
     route: values.route,
     reason: values.reason,
     yes: values.yes === true,
@@ -417,6 +442,9 @@ async function main() {
       creates: { type: 'string' },
       refactors: { type: 'string' },
       acceptance: { type: 'string' },
+      kinds: { type: 'string' },
+      magnitude: { type: 'string' },
+      uncertainty: { type: 'string' },
       route: { type: 'string' },
       reason: { type: 'string' },
       amends: { type: 'string' },

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 };
 }

package/.agents/scripts/drain-pending-cleanup.js

@@ -39,8 +39,44 @@ const progress = Logger.createProgress('drain-pending-cleanup', {
   stderr: false,
 });
 
-async function main() {
+/**
+ * The drain core, extracted from the CLI shell so the whole decision table —
+ * empty manifest, dry-run report, drain + escalate reporting — is reachable
+ * without a real worktree ledger or a real process kill.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
+ * every production caller are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   readManifestImpl?: typeof readManifest,
+ *   findHoldersInPathImpl?: typeof findHoldersInPath,
+ *   forceDrainImpl?: typeof forceDrainPendingCleanup,
+ *   gitImpl?: typeof gitUtils,
+ *   projectRoot?: string,
+ *   progressImpl?: (phase: string, message: string) => void,
+ *   logger?: { error: Function },
+ * }} [deps]
+ * @returns {Promise<{ drained: number[], remaining: number } | { remaining: number }>}
+ */
+export async function runDrainPendingCleanup(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    readManifestImpl = readManifest,
+    findHoldersInPathImpl = findHoldersInPath,
+    forceDrainImpl = forceDrainPendingCleanup,
+    gitImpl = gitUtils,
+    projectRoot = PROJECT_ROOT,
+    progressImpl = progress,
+    logger = Logger,
+  } = deps;
   const { values } = parseArgs({
+    args: argv,
     options: {
       escalate: { type: 'boolean', default: true },
       'dry-run': { type: 'boolean', default: false },
@@ -49,20 +85,23 @@ async function main() {
     strict: false,
   });
 
-  const config = resolveConfig();
+  const config = resolveConfigImpl();
   const wtConfig = config.delivery?.worktreeIsolation;
   const worktreeRoot = path.resolve(
-    PROJECT_ROOT,
+    projectRoot,
     values['worktree-root'] ?? wtConfig?.root ?? '.worktrees',
   );
 
-  const before = readManifest(worktreeRoot);
+  const before = readManifestImpl(worktreeRoot);
   if (before.length === 0) {
-    progress('SCAN', 'pending-cleanup manifest is empty — nothing to drain.');
-    return;
+    progressImpl(
+      'SCAN',
+      'pending-cleanup manifest is empty — nothing to drain.',
+    );
+    return { remaining: 0 };
   }
 
-  progress(
+  progressImpl(
     'SCAN',
     `pending-cleanup manifest has ${before.length} entry(ies): ${before
       .map((e) => `story-${e.storyId}(attempts=${e.attempts ?? 0})`)
@@ -71,8 +110,8 @@ async function main() {
 
   if (values['dry-run']) {
     for (const entry of before) {
-      const holders = findHoldersInPath(entry.path);
-      progress(
+      const holders = findHoldersInPathImpl(entry.path);
+      progressImpl(
         'DRY-RUN',
         `story-${entry.storyId} path=${entry.path} holders=${holders.length}` +
           (holders.length > 0
@@ -80,23 +119,23 @@ async function main() {
             : ''),
       );
     }
-    return;
+    return { remaining: before.length };
   }
 
-  const result = await forceDrainPendingCleanup({
-    repoRoot: PROJECT_ROOT,
+  const result = await forceDrainImpl({
+    repoRoot: projectRoot,
     worktreeRoot,
-    git: gitUtils,
+    git: gitImpl,
     escalate: values.escalate,
     logger: {
-      info: (m) => progress('DRAIN', m),
-      warn: (m) => progress('DRAIN', `⚠️ ${m}`),
-      error: (m) => Logger.error(`[drain-pending-cleanup] ${m}`),
+      info: (m) => progressImpl('DRAIN', m),
+      warn: (m) => progressImpl('DRAIN', `⚠️ ${m}`),
+      error: (m) => logger.error(`[drain-pending-cleanup] ${m}`),
     },
   });
 
   if (result.drained.length > 0) {
-    progress(
+    progressImpl(
       'DRAIN',
       `✅ drained ${result.drained.length} entry(ies): ${result.drained
         .map((id) => `story-${id}`)
@@ -107,10 +146,10 @@ async function main() {
     const summary = result.escalated
       .map((id) => `story-${id}=[${(result.killedPids[id] ?? []).join(',')}]`)
       .join(', ');
-    progress('ESCALATE', `terminated holders: ${summary}`);
+    progressImpl('ESCALATE', `terminated holders: ${summary}`);
   }
   if (result.noHolders && result.noHolders.length > 0) {
-    progress(
+    progressImpl(
       'ESCALATE',
       `⚠️ no user-mode holders for: ${result.noHolders
         .map((id) => `story-${id}`)
@@ -120,7 +159,7 @@ async function main() {
     );
   }
   if (result.persistent.length > 0) {
-    progress(
+    progressImpl(
       'PERSIST',
       `⚠️ persistent-lock remains on: ${result.persistent
         .map((id) => `story-${id}`)
@@ -128,7 +167,7 @@ async function main() {
     );
   }
   if (result.stillPending.length > 0) {
-    progress(
+    progressImpl(
       'STILL-PENDING',
       `⚠️ still-pending (below threshold): ${result.stillPending
         .map((id) => `story-${id}`)
@@ -136,12 +175,17 @@ async function main() {
     );
   }
 
-  const after = readManifest(worktreeRoot);
-  progress(
+  const after = readManifestImpl(worktreeRoot);
+  progressImpl(
     'DONE',
     `pending-cleanup manifest now has ${after.length} entry(ies). ` +
       `Drained=${result.drained.length}, escalated=${result.escalated.length}, persistent=${result.persistent.length}.`,
   );
+  return { drained: result.drained, remaining: after.length };
+}
+
+async function main() {
+  await runDrainPendingCleanup();
 }
 
 runAsCli(import.meta.url, main, {