mandrel 2.60.0 → 2.62.0

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

@@ -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,13 +5,22 @@ 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.
+
+**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
@@ -23,22 +32,13 @@ 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.
 
-`check-knip-entries.js` 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.
-
 ## See Also
 
 - [`/.agents/README.md`](../README.md) — consumer user guide.
 - [`/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,74 +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 Story
- * (Story #4723, narrowed by #5343) — the contract-identical inline self-eval
- * under `ceremonyProfile` `minimal` / `standard`, a fresh-context maker-blind
- * critic under `strict` — 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; Story #5343 retired the cluster
- * protocol that used to fan a round out). The round's owner authors ONE
- * verdict covering every `acceptance[]` item — `criteria[]` in
- * acceptance-array order — and it is scored here exactly once. A second call
- * inside one round would burn a Story-level round for nothing (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.
- *
- * 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
@@ -109,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]
@@ -132,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]
@@ -177,22 +113,14 @@ function parseCliArgs(argv) {
   };
 }
 
-/**
- * The coverage 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 = 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]
@@ -216,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}
@@ -234,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>}
@@ -260,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) {
@@ -287,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 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.
@@ -310,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.
@@ -339,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).
@@ -362,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]
@@ -393,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,
@@ -430,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)
@@ -459,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 {{
@@ -542,9 +417,6 @@ export async function runAcceptanceEvalCli(
 
   const verdict = validateVerdictImpl(parsed);
 
-  // Story #4951 / #5313: the 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 verdict is a free mistake.
   const config = resolveConfigImpl();
   const expected = await resolveExpectedCriteriaCount({
     storyId,
@@ -555,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({