shapeup-sdlc 1.6.3 → 3.0.0

package/{hooks/slop-cleaner.mjs → kernel/reduce/leftovers.mjs}

@@ -1,27 +1,23 @@
-#!/usr/bin/env node
-// Slop cleaner — advisory Stop hook (v1.2, absorb-audit P2).
+// leftovers — what the run's own diff still carries that nobody meant to ship.
 //
-// Scans what actually changed this session (git diff of the working tree; fallback: the
-// newest WorkResult's files_touched) for the classic leftovers — TODO/FIXME markers,
-// console.log/debugger, blocks of commented-out code, one file swallowing hundreds of added
-// lines — and mentions them to the user on stop.
+// TODO/FIXME markers, `console.log`/`debugger`, blocks of commented-out code, one file swallowing
+// hundreds of added lines. Added lines only: a marker the feature did not introduce is somebody
+// else's, and a report that lists those is a report people learn to skim.
 //
-// ADVISORY ONLY, same contract as anti-rationalization.mjs: exit 0 always, at most
-// { systemMessage }, never { decision:"block" }, never exit 2 ("QA is a level-up, not a
-// gate"). Harness-scoped: silent unless a run is active.
+// WHY IT IS PART OF THE SHIP REPORT AND NOT A STOP HOOK. It used to be an advisory Stop hook that
+// printed once, into a transcript, at the moment a session ended — the channel least likely to be
+// read and impossible to check later. The ship report is the artifact a human actually reads at
+// GATE L4 and the one a teammate finds on `git pull`, so a leftover recorded there is a leftover
+// somebody can act on. Nothing about the check changed; only where its answer lands.
 //
-// Contract: Stop stdin JSON { cwd, stop_hook_active }.
+// Advisory by construction: it is a SECTION, never a verdict. QA is a level-up, not a gate.
 
 import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
-import { activeSlug } from "./anti-rationalization.mjs";
-import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
-import { LOCAL, SHARED, resultsDir } from "../skills/tech-lead/scripts/lib/paths.mjs";
+import { LOCAL, SHARED, resultsDir } from "../lib/paths.mjs";
 
-import { runHook, readStdin, settle } from "./lib/decision.mjs";
-
-// Harness bookkeeping is never "slop" — skip both storage roots, whichever names they carry.
+// Harness bookkeeping is never a leftover — skip both storage roots, whichever names they carry.
 const SKIP_PATH = new RegExp(`^(${[LOCAL, SHARED].map((r) => r.replace(/[.\\]/g, "\\$&")).join("|")})/`);
 const MAX_FILES = 30;
 const MAX_ADDED_LINES_PER_FILE = 400;
@@ -32,8 +28,16 @@ const MARKERS = [
   { name: "debugger", re: /^\s*debugger\b/ },
 ];
 
-/** Scan a unified diff for slop in ADDED lines only.
- *  Returns [{ file, markers: {name: count}, added, big, commented_code }]. */
+/**
+ * Scan a unified diff for leftovers in ADDED lines only.
+ *
+ * Added lines only, deliberately: a TODO the feature did not introduce is somebody else's, and a
+ * report that lists it is a report people learn to skim.
+ *
+ * @param {string} diffText - A unified diff.
+ * @returns {Array<{file:string, markers:Object<string,number>, added:number, big:boolean, commented_code:boolean}>}
+ *   One entry per dirty file, capped at MAX_FILES.
+ */
 export function scanDiff(diffText) {
   const findings = [];
   let current = null;
@@ -78,7 +82,11 @@ export function scanDiff(diffText) {
   return findings;
 }
 
-/** One human-readable fragment per finding. */
+/**
+ * One human-readable fragment per finding.
+ * @param {Array} findings - The result of {@link scanDiff}.
+ * @returns {string[]} At most six lines, each naming a file and what it carries.
+ */
 export function summarize(findings) {
   return findings.slice(0, 6).map((f) => {
     const bits = Object.entries(f.markers).map(([name, n]) => `${name} ×${n}`);
@@ -88,12 +96,24 @@ export function summarize(findings) {
   });
 }
 
+/**
+ * Run git, returning stdout on success and null otherwise.
+ * @param {string} cwd - Working directory.
+ * @param {string[]} args - Arguments after `git`.
+ * @returns {(string|null)} stdout, or null when git failed or is absent.
+ */
 function git(cwd, args) {
   const r = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
   return r.status === 0 ? r.stdout : null;
 }
 
-/** The session's change set as a unified diff — git first, WorkResult fallback. */
+/**
+ * The run's change set as a unified diff — git first, WorkResult fallback.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {(string|null)} A unified diff, or null when there is nothing to scan.
+ */
+export
 function collectDiff(cwd, slug) {
   const tracked = git(cwd, ["diff", "HEAD"]);
   if (tracked !== null) {
@@ -137,40 +157,3 @@ function collectDiff(cwd, slug) {
   } catch { return null; }
   return diff || null;
 }
-
-async function main() {
-  await runHook("slop-cleaner", async () => {
-  const raw = await readStdin();
-  let p;
-  /** Stay silent — with the reason on the record (hooks/lib/decision.mjs). */
-  const defer = (reason, rule) => settle({ verdict: "allow", event: "Stop", cwd: p?.cwd, reason, rule });
-  try { p = JSON.parse(raw || "{}"); }
-  catch (e) { settle({ verdict: "error", event: "Stop", reason: `unparseable payload: ${e.message}` }); }
-
-  if (p.stop_hook_active) defer("stop_hook_active — never participate in a stop-hook loop", "loop-guard");
-
-  const cwd = p.cwd || process.cwd();
-  const slug = activeSlug(cwd);
-  if (!slug) defer("no active run — stay silent", "no-run");
-
-  const diff = collectDiff(cwd, slug);
-  if (!diff) defer("no diff to scan", "no-diff");
-
-  const findings = scanDiff(diff);
-  if (findings.length === 0) defer("diff scanned, no leftovers found — inspected and permitted", "diff-clean");
-
-  return {
-    verdict: "allow", event: "Stop", cwd, subject: slug, rule: "slop-found", emit: true,
-    reason: `${findings.length} leftover(s) in the recent diff — advisory note emitted, not a block`,
-    payload: {
-      systemMessage:
-        `slop-cleaner (advisory): recent edits carry leftovers — ${summarize(findings).join("; ")}. ` +
-        `Not blocking — consider a cleanup pass.`,
-    },
-  };
-  });
-}
-
-if (isMain(import.meta.url)) {
-  main();
-}

package/{skills/tech-lead/scripts/ship-report.mjs → kernel/reduce/ship.mjs}

@@ -21,20 +21,21 @@
 // Zero dependencies, zero network.
 //
 // Usage:
-//   node ship-report.mjs --slug <slug> [--cwd <dir>] [--verdict PASS|FAIL|not-evaluated]
+//   node `harness reduce ship` --slug <slug> [--cwd <dir>] [--verdict PASS|FAIL|not-evaluated]
 //                        [--qa run|skipped] [--stdout]
 //
 // Exit: 0 written (path on stdout), 2 usage error.
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
+import { runArgs } from "../lib/argv.mjs";
 import {
   report as reportPath, tasksDir, verdictsDir, trials, evaluationDir, qaDir,
-  roundLedger, discoveryLedger, receipt as receiptPath, harnessRun, relShared,
-} from "./lib/paths.mjs";
-import { readTrials } from "./t0-verify.mjs";
+  roundLedger, discoveryLedger, receipt as receiptPath, harnessRun, relShared, resultsDir,
+} from "../lib/paths.mjs";
+import { readTrials } from "../verify/t0.mjs";
+import { ratchetReport } from "../probe/stats.mjs";
+import { collectDiff, scanDiff, summarize } from "./leftovers.mjs";
 
 /** @returns {string} Today as `YYYY-MM-DD` (UTC). */
 const today = () => new Date().toISOString().slice(0, 10);
@@ -66,7 +67,7 @@ export function frontmatter(text) {
 }
 
 /**
- * Board census, from task frontmatter — the same two-source discipline `gate-l2` uses, reduced to
+ * Board census, from task frontmatter — the same two-source discipline the GATE L2 block uses, reduced to
  * the authoritative one.
  * @param {string} cwd - Project root.
  * @param {string} slug - Feature slug.
@@ -164,8 +165,8 @@ export function section(md, heading) {
  */
 export function buildReport(facts) {
   const {
-    slug, at, verdict, qa, rounds, board, t0, artifacts,
-    evalCriteria, evalBugs, qaFindings, decisions, discovered, intakeSha,
+    slug, at, verdict, qa, rounds, board, t0, artifacts, ratchet,
+    evalCriteria, evalBugs, qaFindings, decisions, discovered, intakeSha, leftovers,
   } = facts;
 
   const L = [];
@@ -190,6 +191,16 @@ export function buildReport(facts) {
       "> The verdict above grades what was built, not what was planned.", "");
   }
 
+  // Leftovers — advisory, and a SECTION rather than a verdict. It was a Stop hook that printed once
+  // into a transcript; here it lands in the artifact a human reads at GATE L4 and a teammate finds
+  // on `git pull`, which is the difference between a note and a record.
+  if (leftovers?.length) {
+    L.push("## Leftovers (advisory)", "");
+    L.push("Markers in lines this run ADDED. Not a gate and not part of the verdict — a cleanup list.", "");
+    for (const line of leftovers) L.push(`- ${line}`);
+    L.push("");
+  }
+
   if (t0.length) {
     L.push("## Verification (T0)", "");
     L.push("The surviving trial per scope — the one describing code that is actually on the branch.", "");
@@ -202,6 +213,35 @@ export function buildReport(facts) {
     L.push("");
   }
 
+  // The ratchet aggregate is derived, ~10 scalars that do not grow with the run, which is why it
+  // can live in the committed tier while `metrics/` correctly stays gitignored (ADR-0001: a
+  // committed shard keyed on $HOSTNAME only grows). Without this the instrument existed and was
+  // never read — the trial ledger it reduces is harvested at SHIP or lost with the local tier.
+  if (ratchet && ratchet.trials > 0) {
+    L.push("## Ratchet", "");
+    L.push("Measured over this run's trial ledger. A monotone series is a ratchet working; a flat or",
+      "sawtooth series says the loop is still a budgeted retry loop wearing a ratchet's shape.", "");
+    L.push("| | |", "|---|---|");
+    L.push(`| Trials | ${ratchet.trials} across ${ratchet.scopes} scope(s), ${ratchet.scopes_multi_trial} with more than one attempt |`);
+    L.push(`| Improvement rate | ${ratchet.improvement_rate} — kept ÷ trials after the first |`);
+    L.push(`| Monotone rate | ${ratchet.monotone_rate} — multi-trial scopes whose score never decreased |`);
+    L.push(`| Sawtooth count | ${ratchet.sawtooth_count} — a revert immediately after a keep |`);
+    L.push(`| Mean trials to green | ${ratchet.mean_trials_to_green ?? "— (no scope reached green)"} |`);
+    const hist = Object.entries(ratchet.status_histogram).map(([k, v]) => `${k} ${v}`).join(", ");
+    L.push(`| Statuses | ${hist || "—"} |`);
+    L.push("");
+    // A zero improvement_rate means one of two opposite things, and the number alone cannot say
+    // which: the loop tried again and failed to improve, or nothing ever needed a second attempt.
+    // Measured on the first two real runs — every scope went green on attempt 1 — so the reading a
+    // reviewer meets by default is the degenerate one. `stats --ratchet` says so on the terminal;
+    // the committed report has to say it too, or a 0 here is read as "the ratchet did not work".
+    if (ratchet.scopes_multi_trial === 0) {
+      L.push("> No scope needed a second attempt, so the rates above are vacuous rather than bad:",
+        "> the ratchet was never asked to climb. The Day-1 question — does the loop measurably",
+        "> improve across attempts — needs a run where at least one scope retries.", "");
+    }
+  }
+
   if (evalCriteria) L.push("## Evaluation", "", evalCriteria, "");
   if (evalBugs) L.push("### Refuted criteria and bugs", "", evalBugs, "");
   if (qaFindings) L.push("## QA findings", "", qaFindings, "");
@@ -210,11 +250,37 @@ export function buildReport(facts) {
 
   L.push("---", "",
     "*Run state (board, orders, results, T0 artifacts, evaluation and QA reports) stays in the",
-    "gitignored local tier — see `docs/design/adr/0001-consumer-file-organization.md`. This report",
+    "gitignored local tier (ADR-0001). This report",
     "is the frozen conclusion of it.*", "");
   return L.join("\n");
 }
 
+/**
+ * How many BUILD/EVAL rounds this run actually completed.
+ *
+ * `harness-run.md`'s `rounds_used` frontmatter field is written ONCE, at GATE L0.1 (`init run`),
+ * as `0` — nothing in the round loop ever rewrites it as rounds complete. The orchestrator's own
+ * `RunReturn` carries the real count (`shapeup-run.js`'s `rounds_used: round`), but that value
+ * never reaches `reduce ship`, so every real run's report printed "Rounds used | 0" beside its own
+ * `results/evaluate-r1.json` — a claim the frontmatter makes about the run, contradicted by the
+ * artifact sitting next to it. Derived instead, the same way `probe resume`'s `eval_rounds_done`
+ * already does: the highest `evaluate-r<N>.json` result on disk. Falls back to the frontmatter
+ * value only when no EVAL round ever ran (the `--tiny` lane has no round concept at all), so a
+ * bare or tiny run's reporting is unchanged.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {(string|undefined)} fallback - `run.rounds_used` from the frontmatter.
+ * @returns {(number|string|undefined)} The derived round count, or the fallback.
+ */
+function roundsUsed(cwd, slug, fallback) {
+  const dir = resultsDir(cwd, slug);
+  const done = (existsSync(dir) ? readdirSync(dir) : [])
+    .map((f) => f.match(/^evaluate-r(\d+)\.json$/))
+    .filter(Boolean)
+    .map((m) => Number(m[1]));
+  return done.length ? Math.max(...done) : fallback;
+}
+
 /**
  * Gather every fact from disk and render the report.
  * @param {{cwd:string, slug:string, verdict?:string, qa?:string}} opts - Inputs.
@@ -234,16 +300,22 @@ export function generate({ cwd, slug, verdict, qa }) {
     at: today(),
     verdict: verdict || run.final_verdict || "not-evaluated",
     qa: qa || (huntReport ? "run" : "skipped"),
-    rounds: run.rounds_used,
+    rounds: roundsUsed(cwd, slug, run.rounds_used),
     intakeSha: receipt.intake_sha256,
     board: boardCensus(cwd, slug),
     t0: t0Summary(cwd, slug),
+    ratchet: ratchetReport(readTrials(trials(cwd, slug))),
     artifacts: verdictArtifactCount(cwd, slug),
     evalCriteria: section(evalReport, /^#+\s.*criteria/i) || section(evalReport, /^#+\s*spec-conformance/i),
     evalBugs: section(evalReport, /^#+\s*Bugs?\b/i),
     qaFindings: section(huntReport, /^#+\s*Findings?\b/i),
     decisions: section(ledger, /^#+\s*Decisions?\b/i),
     discovered: section(discovery, /^#+\s*Discovered\b/i),
+    leftovers: (() => {
+      // Advisory, and derived like everything else here: the run's own diff, added lines only.
+      const diff = collectDiff(cwd, slug);
+      return diff ? summarize(scanDiff(diff)) : [];
+    })(),
   };
   return { markdown: buildReport(facts), path: reportPath(cwd, slug), facts };
 }
@@ -251,7 +323,7 @@ export function generate({ cwd, slug, verdict, qa }) {
 // ---------------------------------------------------------------------------
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "ship-report.mjs --slug <slug> [--cwd <dir>] [--verdict PASS|FAIL|not-evaluated] " +
+  usage: "harness.mjs reduce ship --slug <slug> [--cwd <dir>] [--verdict PASS|FAIL|not-evaluated] " +
          "[--qa run|skipped] [--stdout]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
@@ -261,8 +333,15 @@ export const ARGV_SPEC = {
   stdout: { type: "flag" },
 };
 
-if (isMain(import.meta.url)) {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Generate the ship report from the artifacts on disk.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
   const { markdown, path } = generate({ cwd, slug: args.slug, verdict: args.verdict, qa: args.qa });
   if (args.stdout) {

package/{skills/tech-lead/scripts/run-snapshot.mjs → kernel/reduce/snapshot.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Run snapshot — the compaction-resilience derivation (v1.2, absorb-audit P4).
+// Run snapshot — the compaction-resilience derivation (v1.2).
 //
 // Derives a RunSnapshot (domain.schema.json#/$defs/RunSnapshot) from FILES ONLY: the
 // active-scope pointer, harness-run.md frontmatter, board task frontmatter, t0/verdicts
@@ -9,22 +9,22 @@
 // re-dispatching an already-ingested order, miscounting attempts (breaking the inner circuit
 // breaker), or "remembering" a hill phase instead of re-deriving it.
 //
-// Consumers (both in hooks/): compact-snapshot.mjs persists it before compaction (audit
-// anchor); session-rehydrate.mjs re-derives it fresh after compaction and injects the
-// rehydrate_hint as additionalContext.
+// Consumers: `--write` persists it as an audit anchor; `--format text` prints the rehydrate_hint
+// for whoever asks. Nothing fires it automatically — the orchestrator re-derives after a context
+// loss by running it, which answers whenever the question is asked rather than only at the two
+// moments a lifecycle hook happened to see.
 //
 // Output is self-validated against the registry before it is emitted — the same
-// refuse-to-emit-schema-drift discipline as compile-order.mjs.
+// refuse-to-emit-schema-drift discipline as `harness compile`.
 //
-// Usage: node run-snapshot.mjs [--cwd <dir>] [--format json|text] [--write]
+// Usage: node `harness reduce snapshot` [--cwd <dir>] [--format json|text] [--write]
 //   exit 0 with empty stdout when no run is active (fail-open), 1 on schema drift.
 
 import { readFileSync, readdirSync, existsSync, writeFileSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { validate } from "./validate-envelope.mjs";
-import { isMain } from "./lib/is-main.mjs";
-import { runArgs } from "./lib/argv.mjs";
-import { localDir, localRoot, relLocal, globLocal, runSnapshot as runSnapshotPath } from "./lib/paths.mjs";
+import { validate } from "../verify/envelope.mjs";
+import { runArgs } from "../lib/argv.mjs";
+import { localDir, localRoot, relLocal, globLocal, runSnapshot as runSnapshotPath } from "../lib/paths.mjs";
 
 /**
  * Read a JSON file, tolerating absence/parse errors.
@@ -84,13 +84,13 @@ function findRun(cwd) {
   // The pointer names the run the sandbox guard is scoping, NOT necessarily a run still open.
   // `.shapeup/active-scope` has existed since v0.3 and nothing has ever cleared it, because
   // its original reader (sandbox-guard) fails OPEN on a stale one — a pointer at a finished run
-  // simply stops matching any substrate. session-rehydrate is the opposite kind of reader: it
+  // simply stops matching any substrate. `harness reduce graph --subgraph run` is the opposite kind of reader: it
   // turns a pointer into "a run is ALREADY OPEN in this workspace … do NOT open a new run", and
   // it now fires on `startup`/`clear`. Following the pointer without checking the run's status
   // therefore made every cold session in every repo that had EVER run the harness open with a
   // false claim about its own workspace — including sessions with nothing to do with the harness,
   // and including the case where the user's next act is to open the run the injection forbids.
-  // This function's own contract (and session-rehydrate's header) always said "a run only for an
+  // This function's own contract (and `harness reduce graph --subgraph run`'s header) always said "a run only for an
   // active-scope pointer or a mid-run harness-run.md"; the status check is what makes that true.
   const pointer = readJSON(join(root, "active-scope"));
   if (pointer?.slug && isMidRun(root, pointer.slug)) {
@@ -176,11 +176,6 @@ export function deriveSnapshot(cwd) {
     if (board.total > 0) snapshot.board = board;
   }
 
-  const escDir = join(root, "escalates");
-  snapshot.open_escalates = existsSync(escDir)
-    ? readdirSync(escDir).filter((f) => f.endsWith(".json")).length
-    : 0;
-
   const ordersDir = join(root, "orders");
   const resultsDir = join(root, "results");
   const results = new Set(existsSync(resultsDir) ? readdirSync(resultsDir) : []);
@@ -242,16 +237,22 @@ function assertValid(snapshot) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "run-snapshot.mjs [--cwd <dir>] [--format json|text] [--write]",
+  usage: "harness.mjs reduce snapshot [--cwd <dir>] [--format json|text] [--write]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   cwd: { type: "path" },
   format: { type: "enum", values: ["json", "text"], default: "json" },
   write: { type: "flag" },
 };
 
-const isMainModule = isMain(import.meta.url);
-if (isMainModule) {
-  const args = runArgs(ARGV_SPEC);
+/**
+ * Derive the file-based run snapshot, and optionally freeze it to disk.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
   const format = args.format;
 

package/{skills/spec-evaluator/scripts/verdict-ledger.mjs → kernel/reduce/verdict.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Verdict-ledger reference implementation (audit Stage D1) — spec-evaluator's own skill-local
+// Verdict-ledger reference implementation — spec-evaluator's own skill-local
 // reference impl (ships beside SKILL.md; not invoked at runtime).
 //
 // The `spec-evaluator` skill performs verdict re-probe / confidence / flip-detection as a
@@ -12,12 +12,11 @@
 //   { run, task, dimension, criterion, verdict:"PASS"|"FAIL", confidence, reprobed, flip, evidence, at }
 //
 // Library use:
-//   import { reconcile, detectFlips, stability } from "skills/spec-evaluator/scripts/verdict-ledger.mjs";
+//   import { reconcile, detectFlips, stability } from "kernel/reduce/verdict.mjs";
 //   const { records, summary } = reconcile(priorLines, currentRecords);
 
 // Most recent prior line for a (dimension, criterion), by highest run number.
-import { isMain } from "../../tech-lead/scripts/lib/is-main.mjs";
-import { runArgs } from "../../tech-lead/scripts/lib/argv.mjs";
+import { runArgs } from "../lib/argv.mjs";
 
 /**
  * Find the most recent prior ledger line for a record's (dimension, criterion), by highest run.
@@ -139,15 +138,22 @@ export function parseLedger(text) {
 }
 
 // --- CLI entry: summarize a ledger file -------------------------------------
-/** The typed argv contract (see `skills/tech-lead/scripts/lib/argv.mjs`). */
+/** The typed argv contract (see `kernel/lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "verdict-ledger.mjs <.verdicts-TASK.jsonl>",
+  usage: "harness.mjs reduce verdict <.verdicts-TASK.jsonl>",
   _: { arity: 1, max: 1, name: ".verdicts-TASK.jsonl" },
 };
 
-if (isMain(import.meta.url)) {
+/**
+ * Reconcile a verdict ledger and report its flips and stability.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
+ *   call `process.exit()` with the subcommand's documented code rather than returning.
+ */
+export async function cli(rawArgv) {
   const { readFileSync } = await import("node:fs");
-  const path = runArgs(ARGV_SPEC)._[0];
+  const path = runArgs(ARGV_SPEC, rawArgv)._[0];
   let lines;
   try { lines = parseLedger(readFileSync(path, "utf8")); }
   catch (e) { console.error(`cannot read ledger ${path}: ${e.message}`); process.exit(2); }