npm - mandrel - Versions diffs - 2.57.0 → 2.58.0 - Mend

mandrel 2.57.0 → 2.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/.agents/scripts/lib/orchestration/review-base-ref.js ADDED Viewed

@@ -0,0 +1,138 @@
+/**
+ * lib/orchestration/review-base-ref.js — the base ref a Story-scope review is
+ * allowed to measure against (Story #5325).
+ *
+ * ## The defect this closes
+ *
+ * A close runs base-sync and the Story-scope review against what everyone
+ * called "the base branch" — but the two meant different refs. Base-sync
+ * fetches and merges `origin/<base>`; the review passed the **bare** branch
+ * name, which git resolves to the LOCAL `refs/heads/<base>`, i.e. to whatever
+ * that ref last fast-forwarded to. On a checkout whose local base is behind
+ * its remote, the review's `<base>...<head>` diff therefore contains every
+ * commit the local ref is missing — other people's landed work, scored as if
+ * this Story had written it. Those findings gate the land, and the operator's
+ * only exit is a `review-block-overridden` on blockers that were never real.
+ *
+ * ## Contract
+ *
+ * One resolution, at the review phase boundary, threaded into the change-set
+ * enumeration, the provider review and the local lens pass — so both arms of
+ * the review agree about what changed and neither can inherit local drift.
+ *
+ * Resolution **fails safe rather than falling back**. Base-sync normally
+ * guarantees the remote ref is present, but a `--skip-sync` close or a
+ * remote-less checkout can reach the review with no `origin/<base>` at all.
+ * Reviewing the local ref anyway is the defect, so an unresolvable base
+ * produces a degradation record — carried on the review's existing
+ * `degraded` / `degradations[]` envelope — and no findings whatsoever.
+ */
+import { gitSpawn } from '../git-utils.js';
+import { degradationEnvelope } from './review-providers/degraded-gates.js';
+/**
+ * The remote-tracking spelling of a base branch — `main` → `origin/main`.
+ * Already-qualified input passes through, so a caller naming `origin/main`
+ * is not double-prefixed.
+ *
+ * @param {unknown} baseBranch
+ * @returns {string|null} the remote-tracking ref, or `null` when unnameable.
+ */
+export function remoteBaseRef(baseBranch) {
+  const base = typeof baseBranch === 'string' ? baseBranch.trim() : '';
+  if (base.length === 0) return null;
+  return base.startsWith('origin/') ? base : `origin/${base}`;
+}
+/**
+ * Resolve the base ref base-sync merged from, **verified present** in this
+ * clone. See the module header for why there is no local-ref fallback.
+ *
+ * @param {{
+ *   baseBranch: string,
+ *   cwd?: string,
+ *   gitSpawnFn?: typeof gitSpawn,
+ * }} args
+ * @returns {{ ref: string|null, resolved: boolean, remoteRef: string|null }}
+ *   `ref` is non-null only when `resolved`; `remoteRef` is the ref that was
+ *   probed, for the caller's degradation surface.
+ */
+export function resolveSharedBaseRef({
+  baseBranch,
+  cwd = process.cwd(),
+  gitSpawnFn = gitSpawn,
+} = {}) {
+  const remoteRef = remoteBaseRef(baseBranch);
+  if (remoteRef === null) {
+    return { ref: null, resolved: false, remoteRef: null };
+  }
+  try {
+    const probe = gitSpawnFn(
+      cwd,
+      'rev-parse',
+      '--verify',
+      '--quiet',
+      `${remoteRef}^{commit}`,
+    );
+    if (probe?.status === 0) {
+      return { ref: remoteRef, resolved: true, remoteRef };
+    }
+  } catch {
+    // A spawn failure and a missing ref are the same answer here: the shared
+    // base cannot be vouched for.
+  }
+  return { ref: null, resolved: false, remoteRef };
+}
+/**
+ * The review outcome for a close that cannot establish the shared base.
+ *
+ * Shaped as the same envelope a completed review returns — an all-zero
+ * severity tally, nothing posted, and the `degraded` / `degradations[]` pair
+ * the close and the rendered comment already read — so the surfaces reading
+ * it cannot mistake "no findings" for "reviewed and clean". Reported, not
+ * blocking, matching the posture of every other degraded review gate.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   baseBranch: string,
+ *   remoteRef: string|null,
+ *   progress: (tag: string, msg: string) => void,
+ *   progressTag?: string,
+ * }} args
+ * @returns {object}
+ */
+export function unresolvedBaseReviewOutcome({
+  storyId,
+  baseBranch,
+  remoteRef,
+  progress,
+  progressTag = 'REVIEW',
+}) {
+  const surface = remoteRef ?? `origin/${baseBranch}`;
+  progress(
+    progressTag,
+    `⚠️ Story-scope review for Story #${storyId} did not run: cannot resolve ` +
+      `${surface}, the base ref base-sync merges from. Diffing the local ` +
+      `${baseBranch} instead would score commits this Story never made, so no ` +
+      'findings are raised. Fetch the base ref (or re-run without ' +
+      '--skip-sync) to restore the review.',
+  );
+  return {
+    halted: false,
+    skipped: true,
+    severity: { critical: 0, high: 0, medium: 0, suggestion: 0 },
+    posted: false,
+    postedCommentId: null,
+    ...degradationEnvelope([
+      {
+        tool: 'story-scope-review',
+        gate: 'base-ref-resolution',
+        surface,
+        reason: 'remote-base-ref-unresolved',
+      },
+    ]),
+    crossRefPosted: false,
+  };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js CHANGED Viewed

@@ -25,9 +25,21 @@
  * shares a single invocation pattern (Story #3653). Review depth needs no
  * input here: it is derived from this Story's own diff inside `runCodeReview`
  * (Story #4542).
+ *
+ * Story #5325 — this phase boundary is where the base ref is resolved, once.
+ * The resolved ref threads into `runStoryReviewCore`, which hands it to both
+ * the change-set enumeration (and through it the provider review) and the
+ * local lens pass, so one resolution corrects both arms. It resolves to
+ * `origin/<baseBranch>` — the ref base-sync merged from — rather than the bare
+ * branch name git would resolve to the local `refs/heads/<baseBranch>`, whose
+ * drift would otherwise be scored as this Story's own change.
  */
 import { parsePrNumberFromUrl } from '../../../github-url.js';
+import {
+  resolveSharedBaseRef,
+  unresolvedBaseReviewOutcome,
+} from '../../review-base-ref.js';
 import { degradationEnvelope } from '../../review-providers/degraded-gates.js';
 import { runStoryReviewCore } from '../../story-close/phases/review-core.js';
 import { postStructuredComment } from '../../ticketing/state.js';
@@ -78,23 +90,25 @@ export function buildStoryReviewCrossRefBody({
 async function invokeStoryReviewCore({
   storyId,
   storyBranch,
-  baseBranch,
+  baseRef,
   prNumber,
   provider,
   runCodeReviewFn,
   runLocalLensReviewFn,
   appendFindingsYieldFn,
+  gitSpawnFn,
   progress,
 }) {
   return runStoryReviewCore({
     storyId,
-    baseRef: baseBranch,
+    baseRef,
     headRef: storyBranch,
     commentTargetId: prNumber,
     provider,
     progress,
     progressTag: 'REVIEW',
     runCodeReviewFn,
+    gitSpawnFn,
     // Forward the seams only when the caller injects them; otherwise
     // `runStoryReviewCore` uses its defaults. `undefined` deep-merges to
     // the default via the destructuring default there.
@@ -153,6 +167,9 @@ async function postStoryReviewCrossRef({
  * Failure modes:
  *   - When `prNumber` is null (couldn't parse), the review is skipped
  *     and the function returns `{ halted: false, skipped: true }`.
+ *   - When `origin/<baseBranch>` cannot be resolved, the review is skipped,
+ *     a `base-ref-resolution` degradation is recorded on the returned
+ *     envelope, and no findings are raised (Story #5325).
  *   - When the runner throws, the close fails non-zero (the throw
  *     propagates) — a Story-scope review failure is not silently
  *     ignored.
@@ -170,6 +187,7 @@ async function postStoryReviewCrossRef({
  *   runCodeReviewFn: Function,
  *   runLocalLensReviewFn?: Function,
  *   appendFindingsYieldFn?: Function,
+ *   gitSpawnFn?: Function,
  *   progress: (tag: string, msg: string) => void,
  * }} args
  * @returns {Promise<{
@@ -185,7 +203,7 @@ async function postStoryReviewCrossRef({
  * }>}
  */
 export async function runStoryScopeReview({
-  cwd: _cwd,
+  cwd,
   storyId,
   storyBranch,
   baseBranch,
@@ -195,6 +213,7 @@ export async function runStoryScopeReview({
   runCodeReviewFn,
   runLocalLensReviewFn,
   appendFindingsYieldFn,
+  gitSpawnFn,
   progress,
 }) {
   if (prNumber == null) {
@@ -205,20 +224,33 @@ export async function runStoryScopeReview({
     return { halted: false, skipped: true };
   }
+  // One resolution per close, at the phase boundary: `baseRef` threads from
+  // here into the change set, the provider review and the local lens pass.
+  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
+  if (!base.resolved) {
+    return unresolvedBaseReviewOutcome({
+      storyId,
+      baseBranch,
+      remoteRef: base.remoteRef,
+      progress,
+    });
+  }
   progress(
     'REVIEW',
-    `Running Story-scope code review for Story #${storyId} (${baseBranch}...${storyBranch}) → PR #${prNumber}...`,
+    `Running Story-scope code review for Story #${storyId} (${base.ref}...${storyBranch}) → PR #${prNumber}...`,
   );
   const result = await invokeStoryReviewCore({
     storyId,
     storyBranch,
-    baseBranch,
+    baseRef: base.ref,
     prNumber,
     provider,
     runCodeReviewFn,
     runLocalLensReviewFn,
     appendFindingsYieldFn,
+    gitSpawnFn,
     progress,
   });

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

@@ -7,7 +7,7 @@ import {
 import { runCloseValidation } from '../../close-validation/runner.js';
 import { getCiDelivery } from '../../config/ci.js';
 import { resolveConfig } from '../../config-resolver.js';
-import { getStoryBranch, gitSync } from '../../git-utils.js';
+import { getStoryBranch, gitSpawn, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
 import { emitTerminalFriction } from '../../observability/runtime-friction.js';
 import { emitTerseResult } from '../../observability/terse-result.js';
@@ -318,6 +318,11 @@ async function openAndReviewPr({
     prNumber,
     provider,
     runCodeReviewFn: injectedRunCodeReview ?? runCodeReviewDefault,
+    // The runner owns the git seam it hands its phases (same as `gitSync` to
+    // `pushStoryBranch`). The review needs it to resolve `origin/<base>` —
+    // the ref base-sync merged from — before it will score anything
+    // (Story #5325).
+    gitSpawnFn: gitSpawn,
     progress,
   });
   if (reviewOutcome.halted) {

package/.agents/scripts/lib/story-body/story-body.js CHANGED Viewed

@@ -164,7 +164,14 @@ const HUMANIZED_PATH_ENTRY_RE = /^`([^`]+)`\s+—\s+(\S+)$/;
 // AC-<n> presentation prefix on acceptance checkboxes (Story #4600). The
 // numbering is a stable 1-based human handle only — parse() strips it so the
 // top-level acceptance[] machine contract round-trips byte-identical.
-const AC_PREFIX_RE = /^AC-\d+:\s+/;
+//
+// The lettered form (`AC-14a:`) is accepted too (Story #5323). Nothing emits
+// one — `serialize()` numbers from the array index — but a Story planned from
+// an existing ticket can copy one out of the source issue's rendered
+// checkboxes, and a body that already carries one must still parse to the
+// handle-free text or the round-trip invariant breaks for it alone. Trailing
+// whitespace is optional so `AC-3:text` normalises as readily as `AC-3: text`.
+const AC_PREFIX_RE = /^AC-\d+[a-z]?:\s*/i;
 // Machine-managed marker lines a body authored before Story #5312 may still
 // carry: the `> **Wide:** <reason>` rationale line (Story #4600), the
@@ -560,6 +567,33 @@ function parseTextListSection(lines) {
  * @returns {ParseResult}
  * @throws {StoryBodyParseError} When the body is structurally unrecoverable.
  */
+/**
+ * Strip the presentation `AC-<n>:` handle off one acceptance item.
+ *
+ * The handle belongs to {@link serialize}, which numbers every checkbox from
+ * its position in `acceptance[]`; an authored item that already carries one
+ * would render doubled (`- [ ] AC-1: AC-1: …`) and a lettered handle copied
+ * from a source ticket would survive into the machine contract. Both parse
+ * and the persist-side normalisation resolve the grammar here so the two can
+ * never disagree about what a handle is (Story #5323).
+ *
+ * Stacked handles are peeled in full — a body persisted while the doubling
+ * was live carries two, and leaving the inner one would normalise to
+ * something that still is not the authored text.
+ *
+ * @param {string} item
+ * @returns {{ text: string, stripped: boolean }} The handle-free text, and
+ *   whether anything was removed.
+ */
+export function stripAcceptanceHandle(item) {
+  const original = String(item ?? '');
+  let text = original;
+  while (AC_PREFIX_RE.test(text)) {
+    text = text.replace(AC_PREFIX_RE, '');
+  }
+  return { text, stripped: text !== original };
+}
 export function parse(input) {
   if (input === null || input === undefined) {
     throw new StoryBodyParseError('Story body is null or undefined', {
@@ -618,7 +652,7 @@ export function parse(input) {
   // The AC-<n> checkbox prefix is presentation-only (Story #4600): strip it
   // so acceptance[] round-trips byte-identical to the authored array.
   const acceptance = parseTextListSection(sections.get('acceptance') ?? []).map(
-    (a) => a.replace(AC_PREFIX_RE, ''),
+    (a) => stripAcceptanceHandle(a).text,
   );
   const verify = parseTextListSection(sections.get('verify') ?? []);
   const references = parsePathEntrySection(

package/.agents/scripts/lib/templates/decomposer-prompts.js CHANGED Viewed

@@ -28,10 +28,14 @@ import { BODY_FORMAT_LINTS } from '../story-body/body-format-lints.js';
  *     partition rules that only mean anything once a draft has siblings:
  *     every Story must earn its slot in the wave schedule, and every
  *     acceptance criterion belongs to exactly one Story.
+ *   - **The tickets-mode rules** ({@link ticketsModePromptField}, Story
+ *     #5323) — what to re-derive rather than carry when the seed is an
+ *     existing ticket whose body is already in Story shape.
  *
- * The envelope carries the core as `systemPrompts.story` and the split rules
- * as `systemPrompts.storySplitRules`; a planner reads the second only when
- * the default-single split policy clears.
+ * The envelope carries the core as `systemPrompts.story`, the split rules as
+ * `systemPrompts.storySplitRules` and the tickets rules as
+ * `systemPrompts.storyTicketsRules`; a planner reads the second only when the
+ * default-single split policy clears, and the third only in tickets mode.
  */
 /**
@@ -132,7 +136,7 @@ The **persisted** \`body\` renders these markdown sections (in order) — you au
 - **goal** (in body string): One sentence stating WHY this Story exists.
 - **spec** (optional, in body string as \`## Spec\`): The technical approach at the altitude the SPEC PROSE CONTRACT below fixes — contract and invariants, never implementation narration. Write as much as the work needs and no more; persist keeps Specs inline at any length and never writes them under \`docs/\`.
 - **slicing** (optional): Ordered intra-session checkpoints for one Story, one line each. Not a fan-out table and not a duplicate of Acceptance.
-- **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals. Persist probes every path against the base branch and repairs a plain-string bullet or a trailing parenthetical into the object form for you; a \`creates\` on an existing path or a \`refactors-existing\` on an absent one is a dry-run warning, and only a \`deletes\` naming an absent path is refused.
+- **changes** (in body string): Each entry is an object \`{ path, assumption }\` where \`assumption\` is one of \`creates | refactors-existing | deletes\`. **Name the files the deliverer authors, and omit generated artifacts** — quality baselines, generated test indexes, migration journals, lockfiles and the like are regenerated by the work itself, the refresh is a close-gate concern, and declaring one needlessly reserves a footprint that serializes sibling Stories at dispatch. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals. Persist probes every path against the base branch and repairs a plain-string bullet or a trailing parenthetical into the object form for you; a \`creates\` on an existing path or a \`refactors-existing\` on an absent one is a dry-run warning, and only a \`deletes\` naming an absent path is refused.
 - **acceptance** (top-level array on the ticket object): Each item is an **outcome a PR reviewer can confirm from the diff and the verify output** — what is true of the codebase once the Story lands, stated at the altitude of the capability (a command that now exits 0 against a named input, a behavior a named test now asserts, a config that now fails validation on a retired key, a document that now records a decision). Aim for **three to six** items: fewer than three usually means the outcome is under-specified; more than six usually means acceptance is re-listing the footprint or the mechanical checks that belong in \`verify[]\`. Push grep-shaped probes, file-exists checks and exit-code tests down into \`verify[]\`; never pin an internal helper name or a private file path into an acceptance item the advisory \`changes[]\` is free to reshape. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec".
 - **verify** (top-level array on the ticket object): The **mechanical checks** — exact commands or test paths the deliverer runs and the acceptance critic consumes as evidence: \`node --test tests/x.test.js\`, \`npm run lint\`, \`npm run validate\`, a scoped grep. Every acceptance item should be confirmable from at least one verify entry's output plus the diff. Stories with zero verify entries fail validation.
 - **Bodies record decisions, never questions to the operator.** Never persist an open question ("Flag if…", "TBD", "confirm with the operator") into a Story body — the executing sub-agent is non-interactive and cannot answer it, and the dry-run warns on every one it finds. Triage each unknown by who can resolve it: an AFK-shaped unknown (a fact in docs, a third-party API surface, observable repo behavior) MUST be resolved by your own research before authoring — never restated as an assumption; only a HITL-shaped unknown (a genuine product or architecture call the operator owns) may be restated as a declarative Key Assumption the agent can act on, stating the default chosen (a decision-made-by-default).
@@ -221,6 +225,32 @@ You are splitting past the default-single policy, so simulate the delivery sched
 - Express ordering with \`depends_on\` (a sibling slug, or \`#<id>\` for an open Story from an earlier plan). A Story whose \`verify[]\` runs against a file a sibling creates MUST \`depends_on\` that sibling, so the file exists when verification runs.`;
 }
+/**
+ * The rules that only apply when the seed is an existing ticket (Story
+ * #5323).
+ *
+ * A `--tickets` seed arrives already in Story shape — rendered `AC-<n>:`
+ * checkboxes, a `## Verify` list, a `## Changes` footprint — and an author
+ * reading it as a template carries that shape forward instead of re-deriving
+ * it. The observed failure (swarm-os #2707 / #2708, planned from #2542 under
+ * mandrel 2.57.0) was a Story whose acceptance list was the source's, handles
+ * and all, and whose verify entries carried a tier suffix retired two
+ * releases earlier. The source ticket is **evidence**, not a draft.
+ *
+ * @returns {string}
+ */
+function renderStoryTicketsRules() {
+  return `#### TICKETS-MODE DRAFT — the source ticket is evidence, not a template:
+You are planning from one or more existing tickets. Read them for **what the work is** — the problem, the constraints, the commands that verify it — and re-derive everything else. Specifically:
+1. **Re-derive \`acceptance[]\` from the goal.** Do not copy the source's \`## Acceptance\` list, and never carry its \`AC-<n>:\` handles — the body renderer numbers the checkboxes itself, so a copied handle renders doubled. A source ticket carrying fifteen criteria is telling you its acceptance was over-specified, not that yours must be: state the three to six outcomes a PR reviewer can confirm, and let the rest fall to \`verify[]\`.
+2. **A mechanical check is a \`verify[]\` command, not an acceptance item.** "Baselines refreshed", "lint exits 0", "the generated index is regenerated", "the quality gate passes" are commands the deliverer runs and the critic reads as evidence. Carrying them as acceptance items inflates the binding contract with work every close already gates.
+3. **Read the source's \`verify[]\` for the commands it names, not for its shape.** Take the test paths and scripts; drop any trailing tier suffix (\`(unit)\`, \`(contract)\`, \`(e2e)\`, \`(validate)\`) and any \`manual:<reason>\` escape — a verify entry is a bare command.
+4. **Re-derive the footprint against the tree as it is now.** The source ticket's \`## Changes\` predicted a repository that has since moved; probe the paths you cite and omit the generated artifacts it listed.
+5. **Do not carry the source's prose wholesale.** Its current-state narration and per-file walkthroughs are exactly what the SPEC PROSE CONTRACT above forbids. Restate the contract and the invariants; the deliverer reads the code for the rest.`;
+}
 /**
  * Render the story-author prompt for a draft of `storyCount` Stories: the
  * N=1 core, plus the schedule and partition rules when the draft has
@@ -233,3 +263,22 @@ export function renderStoryAuthorPrompt({ storyCount = 1 } = {}) {
   const core = renderStoryAuthorCore();
   return storyCount > 1 ? `${core}\n\n${renderStorySplitRules()}` : core;
 }
+/**
+ * The mode-conditional slice of `systemPrompts`.
+ *
+ * `storyTicketsRules` only means anything when the seed is an existing
+ * ticket, and an envelope carrying it in every mode teaches the author to
+ * look for a source ticket a `--seed` run does not have. Returning a
+ * spreadable object rather than a nullable string keeps the decision here,
+ * beside the prompt it selects, instead of as a branch in the envelope
+ * builder.
+ *
+ * @param {string|undefined} mode The plan-context mode.
+ * @returns {{ storyTicketsRules?: string }}
+ */
+export function ticketsModePromptField(mode) {
+  return mode === 'tickets'
+    ? { storyTicketsRules: renderStoryTicketsRules() }
+    : {};
+}

package/.agents/scripts/lib/test-run-credit.js CHANGED Viewed

@@ -1,15 +1,23 @@
 /**
- * lib/test-run-credit.js — let a green bare `npm test` earn the credit close
- * reads (Story #5313).
+ * lib/test-run-credit.js — let a green `npm test` **that routes through
+ * mandrel's own runner** earn the credit close reads (Story #5313, scoped by
+ * Story #5324).
  *
- * Until this module the only suite run that deposited credit was the one
- * shaped exactly like the close gate — `coverage-capture.js --cwd <worktree>`
- * or `evidence-gate.js --standalone … -- npm test` — and the digest, the
- * worker boot context and the reference all carried prose explaining which
- * invocation to type. A worker that ran the project's own test runner paid
- * for the suite and then close paid for it again. The runner is the natural
- * depositor: it knows the tree it ran against, whether the run was green,
- * and whether it ran the whole suite.
+ * This is a **bonus, not the contract.** The deposit every project can rely
+ * on is `evidence-gate.js --standalone --scope-id <id> --gate test --worktree
+ * <workCwd> -- npm test`: it spawns whatever `npm test` resolves to and
+ * stamps what it just ran, so it is honest on any runner. What this module
+ * adds is that a repo whose `test` script *is* `run-tests.js` need not type
+ * that wrapper — the runner already knows the tree it ran against, whether
+ * the run was green, and whether it ran the whole suite, so it deposits on
+ * the way out.
+ *
+ * The reach is therefore exactly one call site: `run-tests.js`. A consumer
+ * whose `npm test` is `vitest run` or `jest` never loads this module, so it
+ * deposits nothing **and prints nothing** — silence is not a signal, and no
+ * delivery surface may tell an agent to confirm credit by reading for the
+ * line below. `mandrel doctor`'s `test-credit-path` check reports which of
+ * the two shapes a project is and names the wrapper as the remedy.
  *
  * On a green **full-tier** run inside a `story-<id>` checkout the runner
  * records the `test` gate's evidence in the same keyspace
@@ -143,8 +151,11 @@ export function depositTestRunCredit({
 }
 /**
- * Deposit and say so on stderr — the runner's one-line hook. The line is
- * the only surface a worker sees, so it names the outcome by reason.
+ * Deposit and say so on stderr — the runner's one-line hook, printed only
+ * when this runner is the one running. It names the outcome by reason, so a
+ * green run that deposited nothing (wrong branch, partial tier) says so
+ * rather than passing silently; a project on another runner prints no line
+ * at all, which is why absence of this line is never evidence either way.
  *
  * @param {Parameters<typeof depositTestRunCredit>[0] & { log?: (line: string) => void }} args
  * @returns {ReturnType<typeof depositTestRunCredit>}

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

@@ -94,26 +94,33 @@ whose `criteria[]` length differs **before** scoring, consuming no round;
 not close**: post a `friction` comment and flip `agent::blocked`.
 Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
-## 5. The one full-suite run
+## 5. The one credited suite run
-After the self-eval loop's last fix commit, run the project test runner
-**once** in the worktree:
+After the self-eval loop's last fix commit, run the suite **once** in the
+worktree through the depositor — it spawns the project's own `npm test`,
+whatever that resolves to, and stamps the result, so any runner earns the
+credit:
 ```bash
-npm test   # in <workCwd>
+node <main-repo>/.agents/scripts/evidence-gate.js --standalone \
+  --scope-id <storyId> --gate test --worktree <workCwd> -- npm test
 ```
-A green full run on `story-<id>` deposits the `test` evidence close reads,
-keyed on the tree, so close reports the gate as **credited** at unchanged
-HEAD — a later commit voids it. The CRAP gate still captures coverage itself
-when it needs an artifact. If the suite outruns the host's sync Bash
-ceiling, dispatch it in the **background** — its completion re-invokes you;
-never spawn a task to poll or `sleep`-loop against it
-([`parallel-tooling.md`](parallel-tooling.md) Rule 2). Read the **output**,
-not the exit code: the runner prints whether it deposited credit, and a run
-off the Story branch or of a partial tier deposits nothing and says so.
-Redraft rounds run the scoped projects for the roots you changed plus
-`verify[]`, not the whole suite; only this run needs credit.
+Green deposits the `test` evidence close reads, keyed on the tree, so close
+reports the gate as **credited** at unchanged HEAD — a later commit voids it.
+Read its **output**, not the exit code: `✓ test passed` is the signal. The
+CRAP gate still captures coverage itself when it needs an artifact.
+A bare `npm test` earns the same credit **only** where the project's test
+script routes through mandrel's own runner, which prints the outcome. On any
+other runner it deposits nothing and prints nothing, so silence is never
+evidence of credit; `mandrel doctor`'s `test-credit-path` check names which
+shape this project is. If the suite outruns the host's sync Bash ceiling,
+dispatch it in the **background** — its completion re-invokes you; never spawn
+a task to poll or `sleep`-loop against it
+([`parallel-tooling.md`](parallel-tooling.md) Rule 2). Redraft rounds run the
+scoped projects for the roots you changed plus `verify[]`, not the whole
+suite; only this run needs credit.
 `verify[]` is scoped entries **plus** this one run: an entry that is itself a
 full-suite command is reported credited against the same record, never

package/.agents/workflows/helpers/deliver-story-reference.md CHANGED Viewed

@@ -237,17 +237,37 @@ the failure class that actually bounces deliveries: close-validation
 discovers them only after the whole close pipeline has run, at several times
 the cost of one full-suite run in the worktree.
-**Run it once, last, so close can credit it.** The run belongs **after** the
-self-eval loop's last fix commit; redraft rounds run scoped tests. A green
-`npm test` in the worktree on `story-<id>` deposits the `test` evidence
-record close reads (Story #5313 — `lib/test-run-credit.js`), keyed on HEAD
-and the tree fingerprint and hashed on the exact command close spawns, so
-close reports the gate as credited at unchanged HEAD instead of re-running
-the suite. The credit expires the moment it stops describing the tree: any
-later commit invalidates it and close re-runs the suite for real, so this
-never trades away the gate. The CRAP gate still runs `coverage-capture.js`
-itself when it needs a fresh artifact — the capture stamp is a claim about
-`coverage/coverage-final.json`, which a bare `npm test` does not produce.
+**Run it once, last, through the depositor.** The run belongs **after** the
+self-eval loop's last fix commit; redraft rounds run scoped tests. Run it in
+the worktree on `story-<id>` as
+```bash
+node <main-repo>/.agents/scripts/evidence-gate.js \
+  --standalone --scope-id <storyId> --gate test \
+  --worktree <workCwd> -- npm test
+```
+The wrapper spawns the project's own `npm test` — whatever that resolves to —
+and records the pass into the Story evidence keyspace, so the credit is
+runner-agnostic by construction: it stamps only what it just ran. The record
+is keyed on HEAD and the tree fingerprint and hashed on the exact command
+close spawns, so close reports the gate as credited at unchanged HEAD instead
+of re-running the suite. The credit expires the moment it stops describing the
+tree: any later commit invalidates it and close re-runs the suite for real, so
+this never trades away the gate. The CRAP gate still runs
+`coverage-capture.js` itself when it needs a fresh artifact — the capture
+stamp is a claim about `coverage/coverage-final.json`, which `npm test` alone
+does not produce.
+**A bare `npm test` is a bonus, not the contract.** It deposits the same
+record only where the project's `test` script routes through mandrel's own
+runner (`run-tests.js` → `lib/test-run-credit.js`, Story #5313), which prints
+the outcome. A project whose `npm test` is `vitest run`, `jest` or any other
+runner never reaches that code, so it prints nothing and deposits nothing —
+silence is not a signal, and nothing here asks you to confirm the credit by
+reading for a line that cannot appear. `mandrel doctor`'s `test-credit-path`
+check reports which shape a project is and names the command above as its
+remedy.
 **`verify[]` reuses the same credit.** A `verify[]` entry that is itself a
 full-suite command is reported **credited** against that record rather than

package/.agents/workflows/helpers/deliver-story.md CHANGED Viewed

@@ -93,12 +93,13 @@ are reference § Step 2. Hard gates always run in Step 3 — the derived level
 never disables them; do **not** pre-run the chain here — Step 2.5's credited
 suite run is the sole exception.
-### Step 2.5 — The one full-suite run, the push, then hand off
+### Step 2.5 — The one credited suite run, the push, then hand off
-After the self-eval loop's last fix commit, run `npm test` **once** in the
-worktree (**digest § 5**): a green full run deposits the `test` credit close
-reads, keyed on the tree, so only a *later* commit invalidates it. Red →
-fix, commit, re-run.
+After the self-eval loop's last fix commit, run the suite **once** in the
+worktree through the depositor — `evidence-gate.js … --gate test -- npm test`,
+spelled out in **digest § 5**. It runs whatever `npm test` resolves to and
+stamps that, so the `test` credit is earned on any runner and only a *later*
+commit invalidates it. Red → fix, commit, re-run.
 Push `story-<storyId>` to `origin`, confirming the remote ref moved. Then
 (sub-agent dispatch only) return the hand-off — Story id, `workCwd`,