mandrel 2.60.0 → 2.62.0

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

@@ -1,46 +1,16 @@
 #!/usr/bin/env node
 /**
- * CLI: ensure `coverage/coverage-final.json` is present and fresh before the
- * CRAP gate fires. Wired into close-validation (always) and pre-push (with
- * `--skip-when-no-crap-files` so untouched-source pushes stay fast).
+ * Ensures `coverage/coverage-final.json` is fresh before the CRAP gate: skip
+ * when the gate is off, no changed file is under `crap.targetDirs`, or the
+ * content-digest stamp matches; otherwise run `test:coverage` behind the
+ * host-level full-suite lock and stamp on success.
  *
- * Behaviour:
- *   1. Resolve `delivery.quality.crap`. If `enabled === false`, exit 0.
- *   2. With `--skip-when-no-crap-files`: read `git diff --name-only <ref>...HEAD`
- *      (default ref `main`) and exit 0 if no changed file lives under
- *      `crap.targetDirs`.
- *   3. Test freshness: content digest of `crap.targetDirs` vs. the persisted
- *      capture stamp (`coverage/.capture-stamp.json`), falling back to the
- *      artifact-mtime heuristic when no stamp exists. Exit 0 when fresh.
- *   4. Otherwise announce the uncredited full-suite run — naming the
- *      invocation that would have deposited credit — and then spawn
- *      `npm run test:coverage`, serialized behind the host-level full-suite
- *      lock (Story #5173) so two concurrent runs on one checkout do not race;
- *      write a fresh capture stamp on success and propagate the exit code.
- *      With `--require-credited`, step 4 refuses instead of spawning, so the
- *      cost is never paid unannounced.
+ * `--require-credited` must stay an argument, never a config read: as policy
+ * it also refused the depositing run, leaving no path that could deposit.
  *
- * **`--require-credited` is an argument, not a config read (Story #5278).**
- * `delivery.execution.requireCreditedCapture` is a policy about *close*: the
- * close gate must not silently pay for a suite the worker was supposed to
- * have deposited. Reading it here applied the refusal to every invocation
- * including the worker's depositing one, so turning the policy on left no
- * path that could ever deposit and bricked the CRAP gate outright. The policy
- * now lives where it is enforced — `close-validation/gates.js` passes this
- * flag when the consumer sets it — and a bare invocation always runs.
- *
- * Step 3 is preceded by the changed-file skip when
- * `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` is on
- * (the default): no changed file under `crap.targetDirs` versus the ref
- * `resolveChangedFilesRef` resolves means no capture at all (Story #5365).
- *
- * Exit codes:
- *   0 — coverage is fresh (or capture skipped/succeeded).
- *   1 — capture run failed (broken tests or coverage-threshold breach), or
- *       the run was refused because it carried no credit and
- *       `--require-credited` was passed. The caller MUST
- *       surface this — silently passing here would defeat the CRAP gate's
- *       `requireCoverage: true` policy.
+ * Exit codes: 0 fresh/skipped/captured; 1 capture failed or refused (callers
+ * MUST surface it); 75 lock wait expired and deferred (only under
+ * `MANDREL_FULL_SUITE_LOCK_ON_EXPIRY=defer`); 124 suite timed out.
  */
 import { getChangedFiles } from './lib/changed-files.js';
 import { isDirectInvocation } from './lib/cli-utils.js';
@@ -62,18 +32,13 @@ import { Logger } from './lib/Logger.js';
 import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
 
 /**
- * Parse the full `process.argv` (index 2 onward) into the capture options.
- *
- * A `ref` of `null` means the caller named none; `resolveChangedFilesRef` owns
- * the fallback (Story #5365).
- *
+ * A `null` ref defers the fallback to `resolveChangedFilesRef`.
  * @param {string[]} argv
  * @returns {{ skipWhenNoCrapFiles: boolean, requireCredited: boolean, ref: string | null, cwd: string }}
  */
 export function parseArgs(argv) {
   const out = {
     skipWhenNoCrapFiles: false,
-    // Story #5278 — an ARGUMENT, never a config read. See `runCoverageCapture`.
     requireCredited: false,
     ref: null,
     cwd: process.cwd(),
@@ -89,16 +54,7 @@ export function parseArgs(argv) {
 }
 
 /**
- * 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 {string[]} [argv]
  * @param {{
  *   resolveConfigImpl?: typeof resolveConfig,
  *   getQualityImpl?: typeof getQuality,
@@ -112,9 +68,9 @@ export function parseArgs(argv) {
  *   filterFilesUnderTargetsImpl?: typeof filterFilesUnderTargets,
  *   logger?: { info: Function, warn: Function, error: Function },
  * }} [deps]
- * @returns {number} process exit code
+ * @returns {Promise<number>}
  */
-export function runCoverageCapture(argv = process.argv, deps = {}) {
+export async function runCoverageCapture(argv = process.argv, deps = {}) {
   const {
     resolveConfigImpl = resolveConfig,
     getQualityImpl = getQuality,
@@ -137,13 +93,7 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     return 0;
   }
 
-  // Story #4473 — detect the "missing npm script" misconfiguration
-  // distinctly. `close-validation/gates.js` already declines to register
-  // this gate when `test:coverage` is absent, so reaching here without the
-  // script means a direct/pre-push invocation in a consumer that never
-  // 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.
+  // Name the fix rather than propagate npm's opaque "Missing script" exit.
   if (!hasNpmScriptImpl(readPackageScriptsImpl(args.cwd), 'test:coverage')) {
     logger.error(
       '[coverage-capture] ✖ No "test:coverage" script in package.json. ' +
@@ -153,29 +103,15 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     return 1;
   }
 
-  // Story #5173 — the host-level full-suite lock. Resolved once here, where
-  // the config is already in scope, and composed over the capture runner so
-  // whichever path reaches the spawn is serialized without either of them
-  // knowing about it. `delivery.execution.fullSuiteLock: false` and
-  // `MANDREL_FULL_SUITE_LOCK=0` each disable it; both hatches live in
-  // `isFullSuiteLockEnabled`.
-  // Two wrappers, composed outermost-first: the credit probe announces (or
-  // refuses) the run, and only a run that survives it reaches the host lock.
-  // Whichever capture path gets here spawns through both without knowing
-  // about either.
+  // Outermost first: the credit probe announces or refuses the run, and only
+  // a surviving run reaches the host-level full-suite lock.
   const capture = creditedCapture(lockedCapture(runCaptureImpl, config), {
     requireCredited: args.requireCredited,
     logger,
   });
 
-  // Story #4981/#5173 — the capture skip, gated by
-  // `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` (on
-  // by default). `null` means "not applicable" (switched off, or a
-  // ref-resolution error) — fall through to the full-scope path below rather
-  // than silently skipping capture.
-  // The two capture paths take the same collaborators bar one; naming that
-  // set once keeps a new seam from being threaded into one and forgotten on
-  // the other.
+  // Shared so a new seam cannot reach one capture path and miss the other.
+  // An incremental `null` means not applicable: fall through to full scope.
   const shared = {
     crap,
     coverage,
@@ -188,29 +124,26 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     logger,
   };
 
-  const incrementalResult = tryIncrementalCapture({
+  const incrementalResult = await tryIncrementalCapture({
     ...shared,
     filterFilesUnderTargetsImpl,
   });
   if (incrementalResult !== null) return incrementalResult;
 
-  return runFullScopeCapture(shared);
+  return await runFullScopeCapture(shared);
 }
 
-// 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.
-// 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.
+// cli-opt-out: main resolves an exit code that is forwarded via process.exit(code); runAsCli's async-main signature does not preserve the result code.
 if (isDirectInvocation(import.meta.url)) {
-  try {
-    // `--help` is answered before the decision core runs: it used to fall
-    // through to the capture path, so asking this script to describe itself
-    // spawned the whole coverage suite.
-    process.exit(
-      handleCoverageCaptureHelp(process.argv) ? 0 : runCoverageCapture(),
-    );
-  } catch (err) {
-    Logger.error('[coverage-capture] unexpected error:', err);
-    process.exit(1);
-  }
+  // `--help` must not reach the core, which would spawn the whole suite.
+  (handleCoverageCaptureHelp(process.argv)
+    ? Promise.resolve(0)
+    : runCoverageCapture()
+  ).then(
+    (code) => process.exit(code),
+    (err) => {
+      Logger.error('[coverage-capture] unexpected error:', err);
+      process.exit(1);
+    },
+  );
 }

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

@@ -1,58 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * deliver-light.js — the `/deliver-light` entry point (Story #4740).
+ * `/deliver-light` entry point — a thin shell, not a second engine: a
+ * risk-only suitability gate, a receipt Story, then the same init/close
+ * scripts `/mandrel-deliver` uses (never reimplemented). `--backstop`
+ * re-checks the ACTUAL diff, the only size block. An escalation ends the
+ * light path, not the session.
  *
- * A **thin entry point, not a second delivery engine.** It runs the
- * suitability gate, authors a minimal receipt `type::story`, and then hands off
- * to the SAME engine scripts `/mandrel-deliver` uses:
- *
- *   suitability gate  →  inline receipt Story  →  single-story-init.js
- *     →  (agent implements + self-evals)  →  diff backstop
- *     →  single-story-close.js  (close-and-land, every gate byte-identical)
- *
- * Worktree, branch, lease, PR, and merge mechanics are **invoked, never
- * reimplemented** — this file contains no parallel init/close logic
- * ({@link buildNextCommands} references the engine scripts by name). The
- * reusable decision core lives in
- * {@link module:lib/orchestration/light-suitability}; this module is the CLI
- * shell plus the receipt-authoring and diff-backstop wiring.
- *
- * Two modes:
- *
- *   - **gate** (default) — judge a prompt's predicted footprint for RISK. On
- *     `proceed-light` it authors the receipt Story (via the plan-persist
- *     `createStoryIssues` surface) and prints the init/close hand-off. An
- *     un-ledgered verdict or an un-waivable risk rule emits an `escalated`
- *     terminal envelope, never landing silently. Story #5313 demoted the
- *     predicted-shape ceilings to warnings and Story #5344 deleted them: a
- *     size bucket the caller declares about its own request is not evidence,
- *     and the backstop below measures the real thing.
- *   - **backstop** (`--backstop --story <id>`) — re-check the ACTUAL diff of
- *     the Story branch after implementation; exit non-zero when it exceeds the
- *     light ceilings, so an over-scope diff is blocked rather than landed.
- *
- * ## Escalation is terminal for THIS path, not for the session (Story #5344)
- *
- * A refused gate emits a schema-validated `story-deliver-terminal` envelope
- * with status `escalated`: nothing was created, and there is no smaller version
- * of the light path to attempt. Story #4746 additionally required the SESSION
- * to end, on one mandrel-bench 2.13.0 observation where an in-session
- * `/mandrel-plan` under-decomposed. Story #5344 relaxes that half — the
- * escalation still ends the light path, and `/mandrel-plan` may now be seeded
- * with `escalation.reasons` in the same session (see
- * `helpers/deliver-light.md`).
- * {@link module:lib/orchestration/story-deliver-terminal.buildEscalationTerminal}
- * carries the guarantees the schema enforces either way.
- *
- * Usage:
- *   node .agents/scripts/deliver-light.js --prompt "<text>" \
- *     --creates path,path --reason "<why>"
- *   node .agents/scripts/deliver-light.js --prompt "<text>" --amends '#123' --reason "<why>"
- *   node .agents/scripts/deliver-light.js --backstop --story 4741
- *
- * Exit codes: 0 ok (proceed / clean backstop), 1 usage error, 2 the gate did
- * not proceed light (an `escalated` terminal), 3 the diff backstop blocked.
+ * Exit codes: 0 ok, 1 usage error, 2 escalated, 3 backstop blocked.
  */
 
 import { parseArgs } from 'node:util';
@@ -115,8 +70,6 @@ Backstop options:
 `;
 
 /**
- * Split a comma-separated path list into trimmed, non-empty entries.
- *
  * @param {string|undefined} csv
  * @returns {string[]}
  */
@@ -129,9 +82,6 @@ export function parseCsvPaths(csv) {
 }
 
 /**
- * Assemble the predicted `changes[]` footprint from the declared creates /
- * refactors lists — the input {@link deriveLightSuitability} shape-checks.
- *
  * @param {{ creates?: string[], refactors?: string[] }} args
  * @returns {Array<{ path: string, assumption: string }>}
  */
@@ -143,22 +93,14 @@ export function buildPredictedChanges({ creates = [], refactors = [] } = {}) {
 }
 
 /**
- * Run the suitability gate purely — no I/O. Returns the outcome envelope the
- * CLI serializes. The prompt text and `--amends` target are deliberately **not**
- * inputs: routing is shape-checked identically whether or not the change is an
- * amendment (Story #4740 R3), and the prompt's text carries no routing signal —
- * the predicted footprint does. Both flow into the receipt Story instead.
- *
+ * Pure. The prompt and `--amends` are deliberately not inputs: only the
+ * recorded reason and the predicted paths carry a routing signal.
  * @param {{
  *   creates?: string[],
  *   refactors?: string[],
  *   reason?: string,
  *   injectedRules?: object,
- * }} args `reason` is the ledgered verdict (Story #5344: the `--route` half is
- *   gone, and so are the declared effort axes it sat beside — the recorded
- *   reason and the predicted paths are what the gate reads. Story #5366
- *   removed the last of them, `--acceptance`, whose value the gate clamped to
- *   a floor of one before reading it).
+ * }} args
  * @returns {{ action: string, suitability: object, outcome: object }}
  */
 export function runLightGate({
@@ -178,9 +120,6 @@ export function runLightGate({
 }
 
 /**
- * Author the receipt Story via the plan-persist creation surface (reused, not
- * reimplemented). Injectable seams keep it unit-testable without a network.
- *
  * @param {{
  *   provider: object,
  *   prompt: string,
@@ -216,10 +155,6 @@ export async function createLightReceipt({
 }
 
 /**
- * The engine hand-off — the SAME scripts `/mandrel-deliver` uses. Named here as
- * commands, never reimplemented: this is the whole of deliver-light's
- * relationship to worktree/branch/lease/PR/merge mechanics.
- *
  * @param {number} storyId
  * @returns {{ init: string, close: string }}
  */
@@ -231,9 +166,6 @@ export function buildNextCommands(storyId) {
 }
 
 /**
- * Emit a JSON envelope on stdout (the machine surface) so a headless caller can
- * branch on it. Human-readable log lines stay on stderr.
- *
  * @param {object} envelope
  * @param {boolean} pretty
  */
@@ -246,10 +178,7 @@ function emit(envelope, pretty) {
 }
 
 /**
- * Backstop mode — re-check the actual diff. The decision lives in
- * {@link module:lib/orchestration/light-backstop}; this branches and prints.
- *
- * @param {object} values Parsed CLI values.
+ * @param {object} values
  * @param {{ resolveFn?: typeof resolveBackstopOutcome }} [deps]
  * @returns {Promise<number>}
  */
@@ -270,24 +199,9 @@ async function runBackstopMode(values, deps = {}) {
 }
 
 /**
- * Gate mode — judge the prompt and, on proceed, author the receipt Story.
- *
- * The two outcomes are deliberately asymmetric in what they emit:
- *
- *   - **`escalate-plan`** returns a schema-validated `escalated` **terminal
- *     envelope** and stops (Story #4746). It is placed **first**, above every
- *     creation call site, so "nothing was started" is a property of the
- *     control flow rather than a claim the envelope makes about itself.
- *   - **`proceed-light`** authors the receipt Story and prints the hand-off.
- *     The former attended stop-and-ask outcome is gone, and so are the
- *     predicted-shape warnings Story #5313 left behind (Story #5344): the gate
- *     never had a question a human could answer that the diff backstop does
- *     not answer better.
- *
- * The injectable seams exist so the no-side-effect guarantee is testable
- * without a network: a test asserts the escalate path never reaches them.
- *
- * @param {object} values Parsed CLI values.
+ * The escalate branch sits above every creation call site, so "nothing was
+ * started" is a property of the control flow, not a claim of the envelope.
+ * @param {object} values
  * @param {{
  *   createProviderFn?: typeof createProvider,
  *   resolveConfigFn?: typeof resolveConfig,
@@ -324,8 +238,7 @@ export async function runGateMode(values, deps = {}) {
       reasons: gate.outcome.reasons,
     });
     emitTerminalFn(envelope);
-    // The refusal is still telemetered (Story #4856): the ceilings stay
-    // recalibratable from evidence even now that only risk rules refuse.
+    // Telemetered so the rules stay recalibratable from evidence.
     await recordRefusalFn({ gate, amends: values.amends });
     Logger.warn(
       `[deliver-light] ESCALATED to /mandrel-plan — the light path ENDS here; run ${envelope.nextCommand}, seeded with these reasons: ${gate.outcome.reasons.join('; ')}`,

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

@@ -1,40 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * deliver-recover.js — probe a stranded Story's live state and print the ONE
- * command that resumes it (Story #4543).
+ * Read-only: probes a stranded Story's live state and prints the ONE command
+ * that resumes it — never a menu, and never a re-dispatch, which would re-run
+ * init under live work and put a second close on one PR. Covers the
+ * merged-but-label-stale Story that `/mandrel-deliver` refuses outright.
  *
- * Read-only by construction. This CLI mutates nothing: it reads the ticket's
- * labels and lease, the Story branch locally and via its tracking ref, the
- * worktree, and the PR (state + checks), then walks a fixed decision table
- * and prints one command with the evidence it was derived from. It never
- * prints a menu — a menu of options is what the operator already has, and it
- * is the thing they cannot act on.
- *
- * The strand this exists for above all others is the **merged-but-label-stale**
- * Story: a `/mandrel-deliver` re-run refuses it outright, because
- * `single-story-init.js` hard-errors on an already-closed Story. Before this
- * surface, that Story had no automated way back.
- *
- * Every command it prints **resumes** — it re-enters the in-flight worker or
- * close, or closes the branch that is already pushed. None of them re-dispatch
- * the Story, and that is deliberate: since Story #4876 the close-and-land tail
- * belongs to the dispatching orchestrator, so a worker returning without a
- * terminal envelope is the expected shape rather than evidence the Story never
- * ran. Answering it with a fresh dispatch re-runs `single-story-init.js`
- * underneath live work and puts a second close on one PR.
- *
- * Usage:
- *   node .agents/scripts/deliver-recover.js --story <STORY_ID> [--cwd <main-repo>]
- *                                           [--json]
- *
- * Exit codes:
- *   0 — a recovery shape was resolved and its next command printed (including
- *       the "nothing to recover" shapes). Reading state is not a failure.
- *   1 — the probe itself could not run (unreadable ticket, bad input).
- *
- * @see .agents/scripts/lib/orchestration/deliver-recover.js
- * @see .agents/schemas/story-deliver-terminal.schema.json
+ * Exit codes: 0 a shape resolved (including nothing-to-recover), 1 the probe
+ * itself could not run.
  */
 
 import { parseArgs } from 'node:util';
@@ -94,15 +67,6 @@ 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,