mandrel 2.41.0 → 2.42.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -79,6 +79,10 @@ import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
  *   runScopedFormatAutofix?: typeof defaultRunScopedFormatAutofix,
  *   createGateLogSink?: typeof defaultCreateGateLogSink,
  * }} args
+ * @returns {Promise<{ gates: Record<string, 'passed'|'skipped'> }>} Per-gate
+ *   outcomes keyed by gate name — the terminal envelope reports the split
+ *   baselines entries from this (Story #5172). A failure throws instead, with
+ *   `err.closeGate` naming the gate that died.
  */
 export async function runCloseValidationPhase({
   cwd,
@@ -144,17 +148,18 @@ export async function runCloseValidationPhase({
   // Story #4736 — one sink for both `log` seams (gate construction and gate
   // execution), so nothing in the chain can route around the artifact.
   const gateLog = createGateLogSink({ storyId, config });
+  const gateList = buildDefaultGates({
+    config,
+    baseBranch,
+    cwd: worktreePath || cwd,
+    log: gateLog.log,
+  });
   let validation;
   try {
     validation = await runCloseValidation({
       cwd,
       worktreePath,
-      gates: buildDefaultGates({
-        config,
-        baseBranch,
-        cwd: worktreePath || cwd,
-        log: gateLog.log,
-      }),
+      gates: gateList,
       log: gateLog.log,
       storyId,
       // Story #4250 — standalone storyId-anchored evidence keyspace. No
@@ -182,10 +187,37 @@ export async function runCloseValidationPhase({
     // The evidence is the point on this path: replay the captured tail inline
     // rather than making the caller open a file to learn why close stopped.
     gateLog.replay();
-    throw new Error(
+    const err = new Error(
       `[single-story-close] Gate failed: ${gate.name} (exit ${status})${gateCwd ? ` in ${gateCwd}` : ''}.` +
         (gate.hint ? ` ${gate.hint}` : ''),
     );
+    // Story #5172 — the phase tracker tags `closePhase`; this tags WHICH gate
+    // inside the phase died, so the failed terminal can name the split
+    // baselines entry rather than reporting a generic validation failure.
+    err.closeGate = gate.name;
+    throw err;
   }
   progress('VALIDATE', `✅ All gates passed. ${gateLog.digest()}`);
+  return { gates: gateOutcomes(gateList, validation) };
+}
+
+/**
+ * Per-gate outcomes for a validation run that passed (Story #5172).
+ *
+ * Every registered gate passed unless the runner reported it skipped — an
+ * evidence short-circuit at unchanged HEAD, or a changed-file scope that
+ * matched nothing. `skipped` is the honest verdict for both: the gate did not
+ * run in THIS invocation, and the terminal schema's own contract is that a
+ * skipped gate is reported as skipped rather than quietly counted as a pass.
+ *
+ * @param {Array<{ name: string }>} gateList The gates this run registered.
+ * @param {{ skipped?: Array<{ gate: { name: string } }> }} validation
+ * @returns {Record<string, 'passed'|'skipped'>}
+ */
+function gateOutcomes(gateList, validation) {
+  const outcomes = {};
+  for (const gate of gateList) outcomes[gate.name] = 'passed';
+  for (const { gate } of validation.skipped ?? [])
+    outcomes[gate.name] = 'skipped';
+  return outcomes;
 }

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -1,6 +1,9 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
-import { buildDefaultGates } from '../../close-validation/gates.js';
+import {
+  BASELINES_GATE_NAMES,
+  buildDefaultGates,
+} from '../../close-validation/gates.js';
 import { runCloseValidation } from '../../close-validation/runner.js';
 import { getCiDelivery } from '../../config/ci.js';
 import { resolveConfig } from '../../config-resolver.js';
@@ -135,12 +138,57 @@ async function alreadyClosedResult(storyId, stateReason = null, config) {
   return { success: true, result, terminal };
 }
 
+/**
+ * Project the baselines entries out of close-validation's per-gate outcomes,
+ * keyed by the gate's own name (Story #5172).
+ *
+ * The envelope's `gates` map used to roll the whole gate chain up into a
+ * single `validation` verdict, which was fine while the baselines gate was
+ * one entry and stopped being fine when it became two: a reader of a failed
+ * close could not tell whether the cheap coverage-independent baselines had
+ * breached or the expensive coverage-consuming ones had. Only registered
+ * entries are reported — a consumer whose config registers just one of the
+ * pair gets just that one, never a phantom key for a gate that never existed.
+ *
+ * @param {Record<string, string>|null|undefined} validationGates
+ * @returns {Record<string, string>}
+ */
+function baselinesEnvelopeGates(validationGates) {
+  const registered = Object.values(BASELINES_GATE_NAMES);
+  const out = {};
+  for (const [name, outcome] of Object.entries(validationGates ?? {})) {
+    if (registered.includes(name)) out[name] = outcome;
+  }
+  return out;
+}
+
 function resolveWorktreePath({ cwd, config, storyId }) {
   const root = config.delivery?.worktreeIsolation?.root ?? '.worktrees';
   const candidate = path.resolve(cwd, root, `story-${storyId}`);
   return nodeFs.existsSync(candidate) ? candidate : null;
 }
 
+/**
+ * The pre-push phases, in the order the pipeline walks them: wrong-tree
+ * guard → base-sync → close-validation.
+ *
+ * Story #5172 put base-sync AHEAD of close-validation, for two reasons that
+ * are really one. The cheap one: a base-sync conflict is a hard block that
+ * costs nothing to detect, so paying for the full gate chain before
+ * discovering it burns the pipeline's most expensive minutes on a tree that
+ * was never going to be pushed. The load-bearing one: with the gates last,
+ * **the validated tree is the pushed tree**. Under the old order the merge
+ * commit base-sync writes landed AFTER validation, so every close pushed a
+ * tree no gate had ever seen.
+ *
+ * `--skip-sync` and `--skip-validation` stay independent — either, both or
+ * neither may be set, and each still elides exactly its own phase.
+ *
+ * @returns {Promise<{ validationGates: Record<string, string>|null }>}
+ *   The per-gate outcomes close-validation observed, or `null` when the phase
+ *   was skipped. Feeds the terminal envelope's `gates` map so the split
+ *   baselines entries are separable there.
+ */
 async function runPrePushPhases({
   cwd,
   worktreePath,
@@ -166,22 +214,6 @@ async function runPrePushPhases({
     progress,
     gitSpawn: injectedGitSpawn,
   });
-  if (!skipValidation) {
-    setPhase('close-validation');
-    await runCloseValidationPhase({
-      cwd,
-      worktreePath,
-      config,
-      baseBranch,
-      storyBranch,
-      storyId,
-      progress,
-      runCloseValidation,
-      buildDefaultGates,
-    });
-  } else {
-    progress('VALIDATE', '⏭ Skipped (--skip-validation).');
-  }
   if (!skipSync) {
     setPhase('base-sync');
     await runBaseSyncPhase({
@@ -198,6 +230,23 @@ async function runPrePushPhases({
   } else {
     progress('SYNC', '⏭ Skipped (--skip-sync).');
   }
+  if (skipValidation) {
+    progress('VALIDATE', '⏭ Skipped (--skip-validation).');
+    return { validationGates: null };
+  }
+  setPhase('close-validation');
+  const validation = await runCloseValidationPhase({
+    cwd,
+    worktreePath,
+    config,
+    baseBranch,
+    storyBranch,
+    storyId,
+    progress,
+    runCloseValidation,
+    buildDefaultGates,
+  });
+  return { validationGates: validation?.gates ?? null };
 }
 
 async function openAndReviewPr({
@@ -743,7 +792,7 @@ async function runClosePipeline({
     config,
     injectedReleaseLease,
   };
-  await releaseLeaseOnBlock(
+  const { validationGates } = await releaseLeaseOnBlock(
     () =>
       runPrePushPhases({
         ...options,
@@ -881,6 +930,9 @@ async function runClosePipeline({
     startedAtMs,
     gates: {
       validation: options.skipValidation ? 'skipped' : 'passed',
+      // Story #5172 — the split baselines entries, named individually so a
+      // reader can tell the two apart. Absent when validation was skipped.
+      ...baselinesEnvelopeGates(validationGates),
       baseSync: options.skipSync ? 'skipped' : 'passed',
       // An overridden blocker reports `overridden`, never
       // `passed`. The review DID fail; a human authorized shipping anyway, and

package/.agents/scripts/lib/orchestration/verify-credit.js

@@ -0,0 +1,207 @@
+/**
+ * verify-credit.js — decide whether a Story `verify[]` entry has already been
+ * paid for by the delivery's single credited full-suite run (Story #5174).
+ *
+ * A Story's `verify[]` is meant to be *scoped* entries plus the one credited
+ * full-suite run the worker makes just before the hand-off push
+ * (`helpers/deliver-digest.md` § 5). When a `verify[]` entry is itself a
+ * full-suite command, running it spends a second whole-suite spawn for a
+ * result the credited run already established — and the close gate chain then
+ * makes a third. This module is the read side of that credit: given the
+ * entry's command it consults **the same stamp close consults** and reports
+ * the entry as credited instead of telling the caller to spawn it.
+ *
+ * It only ever *reads*. Nothing here writes a capture stamp or an evidence
+ * record — an entry that is not covered by a fresh stamp is reported
+ * `spawn: true` and runs for real, so the credit can never manufacture a pass.
+ *
+ * @see .agents/scripts/lib/coverage-capture.js (`isCoverageFresh`)
+ * @see .agents/scripts/lib/validation-evidence.js (`shouldSkip`)
+ */
+
+import { getQuality, resolveConfig } from '../config-resolver.js';
+import { isCoverageFresh } from '../coverage-capture.js';
+import { gitSpawn } from '../git-utils.js';
+import { hasNpmScript, readPackageScripts } from '../npm-scripts.js';
+import { hashCommandConfig, shouldSkip } from '../validation-evidence.js';
+
+/**
+ * The shape a `verify[]` array is supposed to have, stated once so the
+ * warning a caller surfaces and the prose in `deliver-digest.md` § 5 say the
+ * same thing.
+ * @type {string}
+ */
+export const FULL_SUITE_SHAPE_WARNING =
+  'verify[] should be scoped entries plus the single credited full-suite run ' +
+  '(deliver-digest.md § 5) — a full-suite command listed in verify[] is ' +
+  'reported credited against that run, never respawned.';
+
+/** Package managers whose `test` script means "the whole suite". */
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
+
+/** Script names that mean "the whole suite" rather than a scoped subset. */
+const FULL_SUITE_SCRIPTS = new Set(['test', 'test:coverage']);
+
+/**
+ * Split a Story `verify[]` line into its command and its tier tag.
+ *
+ * Story bodies write entries as `` `<command>` (<tier>) `` — the tier is
+ * planning metadata, not part of the command, and leaving it attached would
+ * make every entry look scoped.
+ *
+ * @param {string} entry
+ * @returns {{ command: string, tier: string|null }}
+ */
+export function parseVerifyEntry(entry) {
+  const text = String(entry ?? '').trim();
+  const tagged = /^(.*?)\s*\(([a-z-]+)\)$/i.exec(text);
+  const command = (tagged ? tagged[1] : text).trim().replace(/^`|`$/g, '');
+  return { command: command.trim(), tier: tagged ? tagged[2] : null };
+}
+
+/**
+ * Is this command a whole-suite run?
+ *
+ * Deliberately narrow. A false positive here would report a *scoped* command
+ * as credited without ever running it, which is how a gate stops gating — so
+ * anything carrying its own positional argument (`npm test -- tests/x.js`,
+ * `node --test tests/x.js`) is scoped by construction.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isFullSuiteCommand(command) {
+  const tokens = String(command ?? '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (tokens.length === 0) return false;
+
+  if (tokens[0] === 'node') {
+    // `node --test` with no path argument walks the default test globs.
+    const rest = tokens.slice(1);
+    return rest.length > 0 && rest.every((t) => t.startsWith('-'));
+  }
+
+  if (!PACKAGE_MANAGERS.has(tokens[0])) return false;
+  const rest = tokens[1] === 'run' ? tokens.slice(2) : tokens.slice(1);
+  if (rest.length === 0 || !FULL_SUITE_SCRIPTS.has(rest[0])) return false;
+  // `npm test -- <path>` narrows the run; only a bare invocation is the suite.
+  return rest.length === 1;
+}
+
+/**
+ * Read HEAD from a worktree. `null` when the tree cannot be read — which
+ * routes to `spawn`, never to a credit.
+ *
+ * @param {string} cwd
+ * @param {Function} gitSpawnFn
+ * @returns {string|null}
+ */
+function readHeadSha(cwd, gitSpawnFn) {
+  const res = gitSpawnFn(cwd, 'rev-parse', 'HEAD');
+  if (res?.status !== 0) return null;
+  const sha = String(res.stdout ?? '').trim();
+  return sha.length > 0 ? sha : null;
+}
+
+/**
+ * Decide how a single `verify[]` entry should be executed.
+ *
+ * @param {object} input
+ * @param {string} input.command — the entry's command (tier tag already off).
+ * @param {number|string} input.storyId
+ * @param {string} input.worktree — ABSOLUTE path to the Story worktree.
+ * @param {string} [input.cwd] — main checkout (evidence keyspace root).
+ *   Defaults to `worktree`.
+ * @param {object} [deps] — test seams; every one defaults to the real impl.
+ * @returns {{
+ *   command: string, fullSuite: boolean, credited: boolean, spawn: boolean,
+ *   mode: 'capture'|'evidence'|null, reason: string, warning: string|null
+ * }}
+ */
+export function resolveVerifyCredit(
+  { command, storyId, worktree, cwd = worktree },
+  deps = {},
+) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    getQualityImpl = getQuality,
+    readPackageScriptsImpl = readPackageScripts,
+    hasNpmScriptImpl = hasNpmScript,
+    isCoverageFreshImpl = isCoverageFresh,
+    shouldSkipImpl = shouldSkip,
+    hashCommandConfigImpl = hashCommandConfig,
+    gitSpawnFn = gitSpawn,
+  } = deps;
+
+  const base = { command, fullSuite: false, mode: null, warning: null };
+  if (!isFullSuiteCommand(command)) {
+    return { ...base, credited: false, spawn: true, reason: 'scoped' };
+  }
+
+  const scoped = {
+    ...base,
+    fullSuite: true,
+    warning: FULL_SUITE_SHAPE_WARNING,
+  };
+  const { crap } = getQualityImpl(resolveConfigImpl({ cwd: worktree }));
+  const mode =
+    crap?.enabled !== false &&
+    hasNpmScriptImpl(readPackageScriptsImpl(worktree), 'test:coverage')
+      ? 'capture'
+      : 'evidence';
+
+  if (mode === 'capture') {
+    const freshness = isCoverageFreshImpl({
+      coveragePath: crap.coveragePath,
+      targetDirs: crap.targetDirs,
+      cwd: worktree,
+    });
+    const fresh = freshness?.fresh === true;
+    return {
+      ...scoped,
+      mode,
+      credited: fresh,
+      spawn: !fresh,
+      reason: fresh ? 'capture-stamp-fresh' : (freshness?.reason ?? 'unknown'),
+    };
+  }
+
+  const headSha = readHeadSha(worktree, gitSpawnFn);
+  if (!headSha) {
+    return { ...scoped, mode, credited: false, spawn: true, reason: 'no-head' };
+  }
+  const [cmd, ...args] = command.split(/\s+/).filter(Boolean);
+  const verdict = shouldSkipImpl(
+    {
+      storyId,
+      gateName: 'test',
+      currentSha: headSha,
+      configHash: hashCommandConfigImpl({ cmd, args, cwd: worktree }),
+    },
+    { cwd, standalone: true },
+  );
+  return {
+    ...scoped,
+    mode,
+    credited: verdict.skip === true,
+    spawn: verdict.skip !== true,
+    reason: verdict.reason,
+  };
+}
+
+/**
+ * Classify a whole `verify[]` array in one pass.
+ *
+ * @param {string[]} entries — raw `verify[]` lines, tier tags included.
+ * @param {{ storyId: number|string, worktree: string, cwd?: string }} context
+ * @param {object} [deps]
+ * @returns {Array<ReturnType<typeof resolveVerifyCredit> & { tier: string|null }>}
+ */
+export function planVerifyExecution(entries, context, deps = {}) {
+  return (Array.isArray(entries) ? entries : []).map((entry) => {
+    const { command, tier } = parseVerifyEntry(entry);
+    return { ...resolveVerifyCredit({ ...context, command }, deps), tier };
+  });
+}

package/.agents/scripts/lib/single-story-sweep/sweep-lock.js

@@ -161,6 +161,30 @@ function readLockOwner(lockPath, fsImpl = fs) {
   }
 }
 
+/**
+ * Read the pid a lockfile was created by (its third line — see
+ * {@link tryCreateLock}'s body format). Returns `null` when the file is
+ * absent, unreadable, or its pid line is not a positive integer.
+ *
+ * Exists so a *waiting* caller can name the holder in its wait line: a bounded
+ * wait with no attribution is indistinguishable from a hang, and the pid is
+ * the one field an operator can act on (`ps`, `kill`). Reading it is
+ * advisory — a `null` just means the wait line says less.
+ *
+ * @param {string} lockPath
+ * @param {object} [fsImpl]
+ * @returns {number|null}
+ */
+export function readLockHolderPid(lockPath, fsImpl = fs) {
+  try {
+    const lines = String(fsImpl.readFileSync(lockPath, 'utf8')).split('\n');
+    const pid = Number.parseInt(lines[2] ?? '', 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Pure: do two identity tuples describe the same lockfile instance? A `null`
  * on either side is "not the same" — an absent file is never the file we

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -113,6 +113,18 @@ mid-delivery, and evaluates the actual work product.
      optional advisory pre-flight — a criterion cannot be scored `met` without
      the supporting `verify[]` evidence where a `verify[]` command is relevant
      to it.
+   - **Reuses the credited full-suite run instead of re-paying for it.**
+     Before spawning a `verify[]` entry, classify it with `resolveVerifyCredit`
+     from
+     [`verify-credit.js`](../../scripts/lib/orchestration/verify-credit.js): an
+     entry that is itself a full-suite command (`npm test`, `pnpm run test`,
+     a bare `node --test`) is consulted against the **same stamp close reads**
+     and, when that stamp is fresh, recorded as `pass` with a `detail` naming
+     the credit — **never respawned**. A stale or absent stamp reports
+     `spawn: true` and the command runs for real, so the credit can never
+     manufacture a pass. The gate warns on any such entry: the intended shape
+     is scoped `verify[]` entries **plus** the one credited run
+     ([`deliver-digest.md`](deliver-digest.md) § 5).
    - **Shares `lint` / `typecheck` evidence with close.** When a
      `verify[]` command is **byte-identical** to a close-validation gate — in
      practice only the cheap, command-identical `lint` and `typecheck` gates

package/.agents/workflows/helpers/deliver-digest.md

@@ -2,9 +2,9 @@
 description: >-
   The deliver path's one bundled framework read. Carries what
   every Story delivery always needs — dispatch decision, engine invariants,
-  the change-set/ceremony incantation, the acceptance-eval gate, and the
-  terminal envelope contract — so the engine reads one file instead of
-  re-reading the helper/schema set each session.
+  the change-set/ceremony incantation, the acceptance-eval gate, the credited
+  full-suite run, and the terminal envelope contract — so the engine reads one
+  file instead of re-reading the helper/schema set each session.
 ---
 
 # Deliver digest (read once per session)
@@ -27,10 +27,8 @@ rule produces it:
    whatever its shape — sub-agent isolation is load-bearing only against a
    *concurrent* sibling racing the same checkout, and a one-Story run has none.
 2. **Every other run is `subagent`.** A multi-Story run dispatches every Story
-   as a sub-agent however trivial its shape — a lite body does not conjure a
-   second session for a sibling, and the wave tick may hand you the whole set
-   on one beat. Shape still sets ceremony; the `route::lite` label is a
-   human-visible hint, never the control signal.
+   as a sub-agent however trivial its shape. Shape still sets ceremony; the
+   `route::lite` label is a human-visible hint, never the control signal.
 
 `inline` removes model-side fan-out only — no `story-worker` boot, no fresh
 acceptance-critic spawn. **`subagent` and `inline` run the same engine**: same
@@ -112,7 +110,30 @@ an unmerged cluster verdict scores a fraction of the criteria and still reports
 not close**: post a `friction` comment and flip `agent::blocked`.
 Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
 
-## 5. Terminal envelope — the return contract
+## 5. The one creditable full-suite run
+
+**After the self-eval loop's last fix commit, immediately before the push** —
+the credit is keyed on the tree, so any later commit invalidates it. Redraft
+rounds run scoped tests; only this final run needs credit, and a bare
+`npm test` / `pnpm run test` deposits **none**, so close re-runs the identical
+suite. Shape it by the predicate `close-validation/gates.js` uses for its test
+gate:
+
+```bash
+# CRAP gate on (default) + a `test:coverage` script — writes the stamp the
+# close `coverage-capture` gate reads:
+node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>
+# otherwise — the record the close `test` gate reads. <workCwd> ABSOLUTE,
+# runner exactly `npm test`: both sides hash {cmd, args, cwd}.
+node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
+  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
+```
+
+`verify[]` is scoped entries **plus** this one run: an entry that is itself a
+full-suite command is reported credited against the same stamp, never
+respawned.
+
+## 6. Terminal envelope — the return contract
 
 `single-story-close.js` emits exactly one envelope on stdout between
 `--- STORY DELIVER TERMINAL ---` markers, schema-validated against
@@ -129,7 +150,7 @@ Relay it verbatim; never hand-compose one, never substitute prose.
 
 Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
 `phase`, `elapsedSeconds`, `nextCommand`. `phase` is one of `init`,
-`wrong-tree-guard`, `close-validation`, `base-sync`, `push`, `pull-request`,
+`wrong-tree-guard`, `base-sync`, `close-validation`, `push`, `pull-request`,
 `code-review`, `auto-merge`, `confirm-merge`, `post-land`, `done`. `gates`
 reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
 reported, never omitted, so a missing gate is never read as a passing one.
@@ -139,7 +160,7 @@ reported, never omitted, so a missing gate is never read as a passing one.
 success; a failed gate replays its tail inline. `AGENT_LOG_LEVEL=verbose`
 restores live streaming.
 
-## 6. When to leave this file
+## 7. When to leave this file
 
 - Unclear state / a re-run refusal → `deliver-recover.js --story <id>` (read-only).
 - Lease, sweep, worktree-scope detail → [`deliver-story-reference.md`](deliver-story-reference.md).