mandrel 2.59.0 → 2.61.0

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-deliver-terminal.schema.json",
   "title": "story-deliver-terminal",
-  "description": "The single terminal envelope a Story delivery invocation emits (Story #4543). Before this schema, the delivery tail had two divergent prose return contracts — one in .agents/workflows/helpers/deliver-story.md, a different one in .agents/agents/story-worker.md — and neither was validated by anything, so a caller could not tell a landed Story from a parked one without re-probing GitHub. This is the SSOT both now reference rather than restate. status is exactly one of landed | pending | blocked | failed | escalated; phase names where the run ended; tail carries per-step booleans so a partial-tail degradation is visible without failing an otherwise-landed merge; nextCommand names the single command that resumes or remediates the run, drawn from the same vocabulary deliver-recover.js prints. escalated (Story #4746) is the one status emitted BEFORE a Story exists — /deliver-light's suitability gate refusing an over-scope prompt — which is why storyId is null exactly there and non-null everywhere else.",
+  "description": "The single terminal envelope a Story delivery invocation emits (Story #4543). Before this schema, the delivery tail had two divergent prose return contracts — one in .agents/workflows/helpers/deliver-story.md, a different one in .agents/agents/story-worker.md — and neither was validated by anything, so a caller could not tell a landed Story from a parked one without re-probing GitHub. This is the SSOT both now reference rather than restate. status is exactly one of landed | pending | blocked | failed | escalated; phase names where the run ended; tail carries per-step booleans so a partial-tail degradation is visible without failing an otherwise-landed merge; nextCommand names the single command that resumes or remediates the run, drawn from the same vocabulary deliver-recover.js prints. escalated (Story #4746) is the one status emitted BEFORE a Story exists — /deliver-light's suitability gate refusing a prompt — which is why storyId is null exactly there and non-null everywhere else.",
   "type": "object",
   "required": [
     "kind",
@@ -21,7 +21,7 @@
     },
     "status": {
       "type": "string",
-      "description": "landed — the PR merged, the Story is agent::done, and the post-land tail was attempted. pending — a bounded wait expired with the PR still in flight; NO label was mutated and no merge.unlanded event was emitted, so the run is resumable via nextCommand. blocked — a classified hard block; the Story carries agent::blocked and blocked.blockClass names the class. failed — a phase crashed; phase names which one. escalated — the /deliver-light suitability gate refused an over-scope prompt under --yes; nothing was created and the session ENDS here, nextCommand naming the /mandrel-plan invocation that owns the work instead.",
+      "description": "landed — the PR merged, the Story is agent::done, and the post-land tail was attempted. pending — a bounded wait expired with the PR still in flight; NO label was mutated and no merge.unlanded event was emitted, so the run is resumable via nextCommand. blocked — a classified hard block; the Story carries agent::blocked and blocked.blockClass names the class. failed — a phase crashed; phase names which one. escalated — /deliver-light's suitability gate refused a prompt on an un-waivable risk rule or an un-ledgered verdict; nothing was created and the LIGHT PATH ends here, nextCommand naming the /mandrel-plan invocation that owns the work instead. Story #5344 narrowed what refuses (the predicted-shape ceilings are gone) and loosened what follows (that command may be run in the same session, seeded with escalation.reasons) without touching this shape.",
       "enum": ["landed", "pending", "blocked", "failed", "escalated"]
     },
     "phase": {
@@ -179,7 +179,7 @@
     },
     "nextCommand": {
       "type": ["string", "null"],
-      "description": "The single command that advances this work from where it stopped, or null when status === \"landed\" and nothing remains. Shares its vocabulary with deliver-recover.js so recovery and normal resumption speak one language. For status escalated it is the /mandrel-plan invocation the operator runs in a FRESH session — the one case where the command is a slash command rather than a script, because the work needs planning, not resumption.",
+      "description": "The single command that advances this work from where it stopped, or null when status === \"landed\" and nothing remains. Shares its vocabulary with deliver-recover.js so recovery and normal resumption speak one language. For status escalated it is the /mandrel-plan invocation that owns the work — the one case where the command is a slash command rather than a script, because the work needs planning, not resumption. Story #4746 required it to run in a FRESH session; Story #5344 permits the same session when it is seeded with escalation.reasons, and helpers/deliver-light.md carries the seeding contract.",
       "minLength": 1
     },
     "elapsedSeconds": { "type": "number", "minimum": 0 },
@@ -194,6 +194,16 @@
       },
       "additionalProperties": false
     },
+    "lockWait": {
+      "type": ["object", "null"],
+      "description": "Story #5377 — full-suite lock accounting for this close: how long its gates waited, in total, for another full suite on the same host to release the lock, and whether a wait expired. null when the close never waited. Distinct from waitBudget, which is merge-wait accounting only. An expired wait inside close spawns nothing, and the close ends pending at phase close-validation with nextCommand re-running close.",
+      "required": ["waitedSeconds", "expired"],
+      "properties": {
+        "waitedSeconds": { "type": "number", "minimum": 0 },
+        "expired": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
     "timestamp": { "type": "string", "format": "date-time" }
   },
   "allOf": [

package/.agents/schemas/validation-evidence.schema.json

@@ -40,10 +40,11 @@
               "check-baselines",
               "check-baselines-independent",
               "check-baselines-coverage",
+              "quality-preview",
               "check-maintainability",
               "check-crap"
             ],
-            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-baselines-independent` / `check-baselines-coverage` are the split pair the gate registers as when its enabled-kind set resolves (Story #5172), with `check-baselines` kept as both the unsplit fail-closed fallback and the historical name; `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
+            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-baselines-independent` / `check-baselines-coverage` are the split pair the gate registers as when its enabled-kind set resolves (Story #5172), with `check-baselines` kept as both the unsplit fail-closed fallback and the historical name; `quality-preview` replays the pre-push CRAP-scope preview at close, registered beside `coverage-capture` (Story #5378); `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
           },
           "commitSha": {
             "type": "string",

package/.agents/scripts/README.md

@@ -5,22 +5,32 @@ invoked indirectly by `npm run …`, slash-command workflows
 (`.agents/workflows/*.md`), or Husky / GitHub Actions hooks; you rarely
 need to call them by hand.
 
-This file is **not** an exhaustive index of the ~90 top-level entrypoints —
+This file is **not** an exhaustive index of the ~65 top-level entrypoints —
 it is the orientation pointer for the directory. Every script documents
 its own flags under `--help`, and each is reachable from a real caller:
 search `package.json` scripts, `.agents/workflows/`, and the Husky /
-GitHub Actions surfaces first. `check-knip-entries.js` derives that
-caller set mechanically, so a CLI no invoker names is dead, not
-operator-only.
+GitHub Actions surfaces first.
 
-It reads the entry list from whatever configuration knip itself would
-load — `knip.json`, `knip.jsonc`, `.knip.json(c)`, `knip.ts`, `knip.js`,
-`knip.config.ts`, `knip.config.js`, or `package.json#knip` — evaluating
-TS/JS modules rather than parsing them, and counting entries declared
-per-workspace as well as at the top level. A project with no knip
-configuration at all exits 0 with a skip line, so the gate is safe to
-wire everywhere; a configuration that exists but cannot be resolved
-still exits 2.
+**Only consumer-facing tooling ships here.** Every top-level CLI in this
+directory is named by a consumer surface — a workflow, skill, rule, agent
+file, template, `instructions.md`, the package's `bin/` / `lib/`, or a
+string `lib/bootstrap/` writes into a consumer's `package.json` or hooks.
+Mandrel's own contributor tooling (its lint and verify aggregates, test
+diagnostics, CI-only ratchets and baseline-maintenance utilities) lives in
+the repository's root `scripts/` directory, which is outside the npm
+`files` array and never reaches a consumer. Mandrel's CI enforces that
+boundary: a top-level CLI here that no consumer surface names fails it,
+and so does any file under `.agents/` importing from outside `.agents/`.
+
+The one script an operator-facing workflow drives **by name, repeatedly**, is
+[`deliver-run.js`](deliver-run.js): one beat of a multi-Story
+`/mandrel-deliver` run — it ticks the ready set from live state, writes each
+ready Story's dispatch prompt under `<tempRoot>/run-<id>/`, keeps the run
+ledger that replaces hand-maintained dispatch bookkeeping, and renders the
+`single-story-close.js` command for every hand-off. Everything else in the
+delivery chain (`resolve-stories.js`, `single-story-init.js`,
+`single-story-close.js`, `stories-wave-tick.js`) is reached through it or
+through a workflow step.
 
 ## See Also
 
@@ -28,7 +38,7 @@ still exits 2.
 - [`/docs/architecture.md`](../../docs/architecture.md) — system
   architecture; the "Key Scripts" section lists the standard
   orchestration entrypoints.
-- [`.agents/docs/quality-gates.md`](../docs/quality-gates.md) — coverage,
+- [`docs/quality-gates.md`](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md) — coverage,
   CRAP, and maintainability baselines + floors.
 - `package.json` `scripts` — the canonical list of standard CLIs
   (`test`, `verify`, `coverage:update`, …).

package/.agents/scripts/acceptance-eval.js

@@ -1,76 +1,18 @@
 #!/usr/bin/env node
 
 /**
- * acceptance-eval.js — bounded per-Story acceptance self-eval gate (Story #3819).
+ * acceptance-eval.js — bounded per-Story acceptance gate. The deterministic
+ * scorer of the round's single authored verdict: validate it against the
+ * schema (malformed is a hard error), decide `proceed | redraft | block` under
+ * `delivery.acceptanceEval.maxRounds`, emit an `acceptance-eval` signal, and
+ * print one JSON envelope. Only `block` exits non-zero; the ticket transition
+ * stays the workflow's job.
  *
- * The Story-implementation phase runs ONE verdict-owner per acceptance
- * cluster (Story #4723) — the fresh-context critic when
- * `ceremony-routing.js` sensitivity-routes the cluster fresh, the
- * contract-identical inline self-eval otherwise — which scores the
- * caller-injected change set against each inline `acceptance[]` item and
- * emits one verdict file per round
- * (`.agents/schemas/acceptance-eval-verdict.schema.json`). This CLI is the
- * deterministic SCORER of that single authored verdict — it validates and
- * decides, it never re-scores the criteria as an independent additional
- * pass — turning the verdict into the loop's next action:
- *
- *   1. Validate the verdict file against the verdict JSON Schema (a
- *      malformed verdict is a hard error — the loop refuses to guess).
- *   2. Decide `proceed | redraft | block` from the per-criterion verdicts
- *      and the resolved redraft budget (`delivery.acceptanceEval.maxRounds`;
- *      `0` means the verdict is scored once with no redraft round).
- *   3. Emit one per-criterion `acceptance-eval` signal into the retro /
- *      feedback substrate so the retro and `/mandrel-plan` Phase 0 feedback
- *      fetch can see which acceptance items needed rework and the round
- *      count.
- *   4. Print a single JSON envelope and exit:
- *        - `proceed` → exit 0; the workflow flips the Story to `closing`.
- *        - `redraft` → exit 0; the workflow reworks the flagged criteria
- *          and re-runs the critic pass for the next round.
- *        - `block`   → exit non-zero; the workflow transitions the Story
- *          to `agent::blocked`, posts a `friction` comment naming the
- *          unmet criteria, and stops. It never silently proceeds to close.
- *
- * The ticket transition / friction-comment authoring stays the workflow
- * agent's job (via `story-phase.js --phase blocked` + `diagnose-friction.js`)
- * — this CLI is the decision + signal boundary, mirroring how the existing
- * gates separate decision from ticket mutation.
- *
- * One invocation shape: per-Story. The diff is one Story's; round scoping
- * is per Story off the Story's `signals.ndjson`. (v2.0.0 removed the Epic
- * tier along with the per-AC-cluster `--epic <id> --cluster <id>` mode that
- * scored an Epic `## Acceptance Table` against a `main..epic/<id>` diff.)
- *
- * One gate call per round (Story #4951). A round may fan out into N parallel
- * maker-blind cluster critics, but their per-cluster verdicts are merged by
- * the caller into ONE verdict — `criteria[]` in acceptance-array order — and
- * scored here exactly once. Invoking the gate per cluster instead would burn
- * one Story-level round per cluster (distinct fingerprints defeat the replay
- * guard) and race the `signals.ndjson` round ledger. The gate reads the
- * Story's own `acceptance[]` count off its body (Story #5313) and rejects a
- * verdict whose `criteria[]` length differs **before** scoring, so the
- * mistake costs no round. `--expected-criteria` is still accepted but is
- * redundant with the derived count: when both are known they must agree.
- * An inline-owned verdict is one file scored in one call — the cluster
- * merge applies only to fresh critics.
- *
- * CLI:
- *   --story <id>              Story ID (required).
- *   --verdict <path>          Path to the round's verdict JSON (required).
- *   --expected-criteria <n>   Optional; must equal the Story's acceptance[]
- *                             count when the body is readable.
- *   --no-signal               Suppress the signal emit (tests).
- *
- * Stdout: a single JSON envelope
- *   { storyId, epicId, fullSuiteVerifyCommands[], decision, round, cap,
- *     capReached, totalCriteria, metCount, unmetCriteria[], signalEmitted,
- *     replay, verdictFingerprint }
- *   (`epicId` is retained as a always-null field for envelope stability.)
- *
- * Reading is free (Story #4874): re-invoking the gate over a verdict the
- * ledger has already scored replays that round (`replay: true`,
- * `signalEmitted: false`) instead of consuming one, so an unchanged verdict
- * can never escalate from `redraft` to `block` by being looked at twice.
+ * One verdict, one gate call per round, covering every `acceptance[]` item in
+ * order — the count is read off the Story body and a mismatch is rejected
+ * before scoring, so it costs no round. Re-scoring an already-scored verdict
+ * replays its round (`replay: true`) and never escalates. `epicId` is an
+ * always-null envelope field kept for stability.
  *
  * @see .agents/scripts/lib/orchestration/acceptance-eval-decision.js
  * @see .agents/schemas/acceptance-eval-verdict.schema.json
@@ -111,13 +53,8 @@ const VERDICT_SCHEMA_PATH = path.resolve(
 );
 
 /**
- * Compile the Ajv2020 validator for the verdict schema.
- *
- * Deliberately **not** memoised in a module-level variable: a module-level
- * cache is reset only on re-import, so it silently defeats the `io` seam below
- * (the second caller's injected reader is never consulted) and makes parallel
- * test isolation impossible — `.agents/rules/test-seams.md` rule 3. The gate
- * compiles the schema once per CLI run, so there is nothing to memoise.
+ * Deliberately not memoised: a module-level cache would bypass the `io` seam
+ * for every later caller. One compile per CLI run.
  *
  * @param {string} [schemaPath]
  * @param {{ readFileSync: typeof readFileSync }} [io]
@@ -134,10 +71,7 @@ function getVerdictValidator(
 }
 
 /**
- * Validate a parsed verdict object against the verdict schema. Throws on
- * any violation so the loop never acts on a malformed verdict.
- *
- * Exported for tests.
+ * Throws on any schema violation.
  *
  * @param {unknown} verdict
  * @param {{ schemaPath?: string, io?: { readFileSync: typeof readFileSync } }} [opts]
@@ -179,22 +113,14 @@ function parseCliArgs(argv) {
   };
 }
 
-/**
- * The merge contract, stated once so both the flag error and the coverage
- * error name the same shape the caller has to produce.
- */
 const MERGE_CONTRACT =
-  'One round = N parallel cluster critics -> ONE merged verdict -> ONE gate call: ' +
-  "merge every cluster's records into a single criteria[] in acceptance[] order, " +
-  'one per acceptance item, before scoring.';
+  'One round = ONE verdict -> ONE gate call: the verdict must carry one ' +
+  'criteria[] record per acceptance[] item, in acceptance-array order, ' +
+  'before scoring.';
 
 /**
- * Read the Story's `acceptance[]` count off its body (Story #5313), so the
- * coverage assertion no longer depends on the caller restating a number it
- * already read. Total: any failure — no provider, an unreadable ticket, an
- * unparseable body — yields `null`, which routes the caller to the flag (when
- * passed) and otherwise to a stated, logged skip. It never manufactures a
- * count.
+ * The Story body's `acceptance[]` count; any failure yields `null`, never a
+ * manufactured count.
  *
  * @param {{ storyId: number, config: object }} args
  * @param {{ createProviderFn?: typeof createProvider, parseBodyFn?: typeof parseStoryBody }} [deps]
@@ -218,9 +144,7 @@ export async function readStoryAcceptanceCount(
 }
 
 /**
- * Reconcile the body-derived count with the optional flag (Story #5313): the
- * derived count is authoritative; a flag that disagrees with it is a wiring
- * error worth failing on rather than a value to prefer silently.
+ * The derived count wins; a disagreeing flag is a wiring error and throws.
  *
  * @param {{ derived: number|null, flagged: number|null }} args
  * @returns {number|null}
@@ -236,10 +160,7 @@ export function reconcileExpectedCriteria({ derived, flagged }) {
 }
 
 /**
- * The count the coverage assertion runs against: the body-derived count,
- * reconciled with the optional flag, with a stated skip when neither is
- * readable (Story #5313). Split out of `runAcceptanceEvalCli` so the CLI
- * body's own branching stays inside its committed cyclomatic budget.
+ * The coverage count, with a logged skip when neither source is readable.
  *
  * @param {{ storyId: number, config: object, flagged: number|null, readAcceptanceCountImpl: typeof readStoryAcceptanceCount, logger: { warn?: Function } }} args
  * @returns {Promise<number|null>}
@@ -262,22 +183,14 @@ async function resolveExpectedCriteriaCount({
 }
 
 /**
- * Resolve the optional `--expected-criteria` flag to a positive integer, or
- * `null` when the flag is absent. Since Story #5313 the gate derives the
- * count from the Story body; the flag remains accepted for callers that
- * still pass it and is checked against the derived value.
- *
- * Exported for tests.
+ * `--expected-criteria` as a positive integer, or `null` when absent.
  *
  * @param {string|null|undefined} raw
  * @returns {number|null}
  */
 export function resolveExpectedCriteria(raw) {
   if (raw === null || raw === undefined) return null;
-  // Digits only. `Number.parseInt` stops at the first non-digit, so `4abc`
-  // resolved to 4 — a guard whose entire job is to reject a wrong-sized
-  // verdict was itself accepting a malformed count, and a typo'd `--expected-
-  // criteria` would then wave through a verdict of the wrong length.
+  // Digits only — `parseInt('4abc')` is 4, which would wave a typo through.
   const text = String(raw).trim();
   const expected = /^\d+$/.test(text) ? Number(text) : Number.NaN;
   if (!Number.isInteger(expected) || expected < 1) {
@@ -289,13 +202,8 @@ export function resolveExpectedCriteria(raw) {
 }
 
 /**
- * Reject a verdict that does not cover exactly `expectedCriteria` criteria.
- *
- * Called **before** `runAcceptanceEval`, which is where the round ledger is
- * read and appended — so a partial cluster verdict handed to the gate by
- * mistake costs no round and can never escalate a `redraft` into a `block`.
- *
- * Exported for tests.
+ * Reject a verdict not covering exactly `expectedCriteria` criteria — before
+ * the round ledger is touched, so the mistake costs no round.
  *
  * @param {object} verdict — schema-validated verdict.
  * @param {number|null} expectedCriteria — `null` disables the assertion.
@@ -312,17 +220,9 @@ export function assertCriteriaCoverage(verdict, expectedCriteria) {
 }
 
 /**
- * Collect the distinct `verify[]` commands a verdict recorded that are
- * themselves full-suite runs (Story #5174).
- *
- * The intended `verify[]` shape is scoped entries **plus** the one credited
- * full-suite run the worker makes before the hand-off push. A full-suite
- * command sitting in `verify[]` is the misshapen case: it either re-pays for
- * the credited run or, worse, gets skipped as "already covered" without
- * anyone saying so. The gate is where every round's evidence passes through,
- * so it is where the shape is called out.
- *
- * Exported for tests.
+ * Distinct full-suite commands in the verdict's `verify[]` evidence — a
+ * misshapen `verify[]` that re-pays (or silently skips) the one credited
+ * full-suite run.
  *
  * @param {object} verdict — schema-validated verdict.
  * @returns {string[]} distinct offending commands, in first-seen order.
@@ -341,13 +241,6 @@ export function collectFullSuiteVerifyCommands(verdict) {
 }
 
 /**
- * Surface the misshapen-`verify[]` warning, if there is one.
- *
- * Extracted from `runAcceptanceEvalCli` rather than inlined: the CLI shell is
- * already the file's worst-CRAP method, and a branch added there costs more
- * than the same branch in a small, fully-covered helper. Module-private: it is
- * reached through the CLI shell, which is where the tests drive it.
- *
  * @param {object} verdict — schema-validated verdict.
  * @param {{ warn?: Function }} logger
  * @returns {string[]} the offending commands (empty when the shape is fine).
@@ -364,20 +257,15 @@ function warnOnFullSuiteVerify(verdict, logger) {
 }
 
 /**
- * Compose the operator-facing envelope and emit the per-criterion signal.
- *
- * Exported for tests so the decision + signal path can be exercised
- * without spawning the CLI.
+ * Decide, emit the signal, and compose the envelope.
  *
  * @param {object} args
  * @param {number} args.storyId
  * @param {object} args.verdict — validated verdict object.
  * @param {object} args.config — resolved `.agentrc.json`.
  * @param {boolean} args.emitSignal
- * @param {number} [args.round] — explicit round override (tests). When
- *   absent, the round is derived by counting prior `acceptance-eval`
- *   signals in the Story's `signals.ndjson` (Story #4019); the verdict's
- *   self-reported `round` is never load-bearing for the cap.
+ * @param {number} [args.round] — override (tests); otherwise derived from the
+ *   signals ledger, never from the verdict's self-reported round.
  * @param {object} [deps]
  * @param {Function} [deps.appendSignalFn]
  * @param {Function} [deps.resolveRoundFn]
@@ -395,9 +283,7 @@ export async function runAcceptanceEval(
   } = deps;
   const { maxRounds } = getAcceptanceEval(config);
   const verdictFingerprint = fingerprintFn(verdict);
-  // Story #4874: re-reading an already-scored verdict is a replay — it
-  // reports the round that verdict was scored under and appends nothing, so
-  // observation alone can never advance the counter or escalate a redraft.
+  // An already-scored verdict replays its round and appends nothing.
   const resolved = resolveRoundFn({
     epicId: null,
     storyId,
@@ -432,8 +318,7 @@ export async function runAcceptanceEval(
         config,
       });
     } catch (err) {
-      // Observability is best-effort — a failed signal write must never
-      // take down the gate. The decision still stands.
+      // Best-effort: a failed signal write never takes down the gate.
       Logger.warn(
         `acceptance-eval: failed to append signal: ${
           err instanceof Error ? err.message : String(err)
@@ -461,28 +346,16 @@ export async function runAcceptanceEval(
       evidence: c.evidence,
     })),
     signalEmitted,
-    // True when this invocation re-read a verdict the ledger had already
-    // scored: the round was replayed, not advanced, and nothing was appended.
     replay,
     verdictFingerprint,
   };
 
-  // `block` is the only non-zero exit: the loop has exhausted its bounded
-  // budget with criteria still unmet, and the workflow must escalate to
-  // `agent::blocked` rather than proceed to close.
   const exitCode = outcome.decision === 'block' ? 1 : 0;
   return { envelope, exitCode };
 }
 
 /**
- * The gate's CLI core: argv → verdict read → schema validation → decision →
- * envelope. Extracted from the `main` shell so the whole error table (missing
- * flags, unreadable verdict, non-JSON verdict, storyId mismatch, block) is
- * reachable without spawning the CLI or writing a real verdict file.
- *
- * 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 invocation are unchanged.
+ * CLI core: argv → verdict → validation → coverage → decision → envelope.
  *
  * @param {string[]} [argv]
  * @param {{
@@ -544,9 +417,6 @@ export async function runAcceptanceEvalCli(
 
   const verdict = validateVerdictImpl(parsed);
 
-  // Story #4951 / #5313: a merged verdict must cover every acceptance[] item,
-  // and the count comes from the Story body itself. This runs before the
-  // round ledger is touched, so a partial cluster verdict is a free mistake.
   const config = resolveConfigImpl();
   const expected = await resolveExpectedCriteriaCount({
     storyId,
@@ -557,17 +427,13 @@ export async function runAcceptanceEvalCli(
   });
   assertCriteriaCoverage(verdict, expected);
 
-  // A verdict whose embedded storyId disagrees with the CLI flag is a
-  // wiring error worth failing on, not a silent mismatch.
   if (Number.isInteger(verdict.storyId) && verdict.storyId !== storyId) {
     throw new Error(
       `acceptance-eval: verdict storyId (${verdict.storyId}) does not match --story ${storyId}.`,
     );
   }
 
-  // Story #5174 — the shape warning is derived from the VALIDATED verdict, not
-  // from the envelope, so it fires for the real decision path and for every
-  // caller that injects its own scorer.
+  // From the validated verdict, so it fires even with an injected scorer.
   warnOnFullSuiteVerify(verdict, logger);
 
   const { envelope, exitCode } = await runAcceptanceEvalImpl({