mandrel 2.59.0 → 2.60.0

package/.agents/scripts/file-ci-gap.js

@@ -35,7 +35,11 @@ import {
   INTAKE_VERDICTS,
   REFUSED_VERDICT,
 } from './lib/orchestration/ci-gap-intake.js';
-import { readCiDigest } from './lib/orchestration/ci-rerun-guard.js';
+import {
+  RERUN_ALLOWANCE_VERDICTS,
+  readCiDigest,
+  recordRerunAllowance,
+} from './lib/orchestration/ci-rerun-guard.js';
 import {
   STATE_LABELS,
   transitionTicketState,
@@ -55,7 +59,7 @@ const USAGE = {
     ],
     [
       '--verdict <verdict>',
-      `One of ${INTAKE_VERDICTS.join(' | ')}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source.`,
+      `One of ${INTAKE_VERDICTS.join(' | ')}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source. ${RERUN_ALLOWANCE_VERDICTS.join(' / ')} also record the one-rerun allowance on the CI digest.`,
     ],
     [
       '--owner <bucket>',
@@ -138,7 +142,12 @@ function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
  * @param {object} opts
  * @returns {string}
  */
-export function renderFrictionComment({ verdict, result, digest }) {
+export function renderFrictionComment({
+  verdict,
+  result,
+  digest,
+  rerunAllowance = null,
+}) {
   const target = result.issue?.url ?? result.issue?.number ?? '(not filed)';
   const lines = [
     `### CI gap filed — verdict \`${verdict}\``,
@@ -158,14 +167,31 @@ export function renderFrictionComment({ verdict, result, digest }) {
       `- **Routing:** deferred from \`${result.routing.deferredFrom}\` (${result.routing.deferralReason}) — filed locally instead.`,
     );
   }
-  lines.push(
-    '',
-    'This verdict does **not** license a re-run of the failed job. Graduate the',
-    'intake issue with `/mandrel-plan <issue number>` to turn it into a Story.',
-  );
+  lines.push('', renderRerunLine(rerunAllowance), GRADUATE_LINE);
   return lines.join('\n');
 }
 
+/** The graduation instruction every filing carries, verdict-independent. */
+const GRADUATE_LINE =
+  'Graduate the intake issue with `/mandrel-plan <issue number>` to turn it into a Story.';
+
+/**
+ * What this filing says about rerunning the failed job (Story #5343). An
+ * allowance is stated with its head SHA and its one-shot bound, because the
+ * comment is where an operator reads whether the rerun they are about to do
+ * is the sanctioned one.
+ *
+ * @param {{ headSha: string } | null} rerunAllowance
+ * @returns {string}
+ */
+function renderRerunLine(rerunAllowance) {
+  return rerunAllowance
+    ? 'This verdict is environmental and proven, so **one** rerun of the failed ' +
+        `job is now admitted on head \`${rerunAllowance.headSha}\` — and one only. ` +
+        'A second red after it is real and routes to Option 1.'
+    : 'This verdict does **not** license a re-run of the failed job.';
+}
+
 /**
  * File the CI-gap intake issue for one Story, post the `friction` comment,
  * and optionally flip the Story to `agent::blocked`.
@@ -198,7 +224,12 @@ export async function runFileCiGap({
     throw new Error('--story <id> is required (a positive issue number).');
   }
   const resolved = config ?? resolveConfig();
-  const ciDigest = digest ?? readCiDigest({ storyId: sid, tempRoot, cwd });
+  // The digest's temp root, resolved exactly as `pr-watch-with-update.js`
+  // resolves it when it WRITES the digest — the CLI never passed one, so the
+  // default read crashed on `undefined` before it could find the file.
+  const digestRoot = tempRoot ?? resolved?.project?.paths?.tempRoot ?? 'temp';
+  const ciDigest =
+    digest ?? readCiDigest({ storyId: sid, tempRoot: digestRoot, cwd });
   if (!ciDigest) {
     throw new Error(
       `no CI digest for Story #${sid}. The digest is written by \`pr-watch-with-update.js --story ${sid}\` on the first red; without it there is no run link or failure signature to file.`,
@@ -237,9 +268,26 @@ export async function runFileCiGap({
     now,
   });
 
+  // Story #5343 — a proven-environmental verdict earns the one same-SHA
+  // rerun the watcher's guard will admit. Recorded on the digest, keyed to
+  // the head SHA the red was observed on, and never on a dry run.
+  const rerunAllowance = dryRun
+    ? null
+    : recordRerunAllowance({
+        storyId: sid,
+        verdict,
+        tempRoot: digestRoot,
+        cwd,
+      });
+
   const actions = { commented: false, blocked: false };
   if (!dryRun && ticketing) {
-    const body = renderFrictionComment({ verdict, result, digest: ciDigest });
+    const body = renderFrictionComment({
+      verdict,
+      result,
+      digest: ciDigest,
+      rerunAllowance,
+    });
     try {
       await upsertStructuredComment(ticketing, sid, 'friction', body);
       actions.commented = true;
@@ -258,7 +306,7 @@ export async function runFileCiGap({
     }
   }
 
-  return { storyId: sid, verdict, ...result, actions };
+  return { storyId: sid, verdict, ...result, actions, rerunAllowance };
 }
 
 /**

package/.agents/scripts/lib/baselines/crap-preview-incremental.js

@@ -6,7 +6,7 @@
  * so the Story's opt-in wiring lands as new code, not a same-file expansion
  * of the pre-existing preview runner.
  */
-import { getChangedFiles } from '../changed-files.js';
+import { getChangedFiles, resolveChangedFilesRef } from '../changed-files.js';
 
 /**
  * Resolve the `incremental` option `scanAndScore` (`crap-utils.js`) expects,
@@ -14,6 +14,10 @@ import { getChangedFiles } from '../changed-files.js';
  * not be resolved — a resolution failure falls back to full-scope rather
  * than silently relaxing the gate.
  *
+ * The join's ref comes from `resolveChangedFilesRef` (Story #5365), the same
+ * rule capture applies: the `--changed-since` ref the preview was handed wins
+ * over a configured `baseRef`, so one hook invocation cannot resolve two.
+ *
  * Gated by `incrementalCoverage.baselineJoin` alone (Story #5173). It MUST
  * NOT consult `skipWhenUnchanged`: the join loosens what the gate demands,
  * while the skip only decides whether a capture runs, so a consumer that took
@@ -36,7 +40,7 @@ export function resolveCrapPreviewIncremental({
   getChangedFilesImpl = getChangedFiles,
 }) {
   if (crap.incrementalCoverage?.baselineJoin !== true) return null;
-  const baseRef = crap.incrementalCoverage.baseRef || diffRef || 'main';
+  const baseRef = resolveChangedFilesRef({ crap, ref: diffRef });
   try {
     const touchedFiles = new Set(getChangedFilesImpl({ ref: baseRef, cwd }));
     return { touchedFiles, baselineRows };

package/.agents/scripts/lib/changed-files.js

@@ -1,5 +1,35 @@
 import { createGitInterface } from './git-utils.js';
 
+/**
+ * Resolve the ONE git ref a step of the pre-push chain computes its
+ * changed-file set against — the whole rule, stated once (Story #5365).
+ *
+ * **A ref the caller named wins; `crap.incrementalCoverage.baseRef` is the
+ * default for a caller that named none, and `main` the default for neither.**
+ * `.husky/pre-push` captures coverage at `--ref origin/main` and then previews
+ * CRAP at `--changed-since origin/main`, and the preview only reads its own
+ * tree when the artifact under it was captured over the same change set.
+ * Letting the configured value outrank the named ref meant a consumer that set
+ * `baseRef` captured one scope while the preview scored another — precisely
+ * the stale-artifact read the capture-before-preview ordering (Story #5356)
+ * closed. This repository sets no `baseRef`, so that divergence was invisible
+ * locally and only a consumer who configured one would have paid for it.
+ *
+ * Callers that name no ref — the close-validation gate, whose argv carries no
+ * `--ref` — still get the configured value, so the key keeps the meaning it
+ * was added with.
+ *
+ * Every step that derives that change set calls this: both `coverage-capture`
+ * paths and the preview's CRAP baseline join. A new consumer routes through it
+ * rather than reading `baseRef` itself.
+ *
+ * @param {{ crap: object, ref: string | null | undefined }} opts
+ * @returns {string}
+ */
+export function resolveChangedFilesRef({ crap, ref }) {
+  return ref ?? crap?.incrementalCoverage?.baseRef ?? 'main';
+}
+
 /**
  * Parse the stdout from `git diff --name-only` into a normalized file list.
  * Trims whitespace, drops blank lines, and converts backslash separators to

package/.agents/scripts/lib/config/delivery-routing.js

@@ -5,10 +5,11 @@
  * Stage 6 dropped `delivery.routing.singleDelivery` (the v1 epic
  * single-vs-fan-out kill-switch). Story #5313 dropped
  * `delivery.routing.freshCriticSampleRate` (the maker-checker sampling
- * floor): the standard profile now routes purely off the derived change
- * level — high or underivable → fresh critic, low → inline self-eval. v2 has
- * one Story delivery path; routing here is only about spawn boot context and
- * the ceremony profile.
+ * floor), and Story #5343 dropped the derived-level routing that replaced
+ * it: `minimal` and `standard` resolve the inline self-eval as the Story's
+ * verdict owner whatever the diff touches, and `strict` is the one profile
+ * that spawns a fresh-context critic. v2 has one Story delivery path;
+ * routing here is only about spawn boot context and the ceremony profile.
  *
  * `delivery.routing.roleScopedAgents` is the **kill-switch for the role-scoped
  * boot contexts** (Epic #4478, M7-B). It defaults to `true`: a converted spawn

package/.agents/scripts/lib/config/explain.js

@@ -159,11 +159,9 @@ const KEY_MEANINGS = Object.freeze({
   'delivery.routing.roleScopedAgents':
     'Whether delivery spawns boot on role-scoped .claude/agents/<role>.md contexts.',
   'delivery.routing.ceremonyProfile':
-    'Acceptance-ceremony depth: minimal (always inline), standard (derived-level routed), or strict (always fresh).',
+    'Who authors the Story acceptance verdict: minimal and standard = the inline self-eval, strict = a fresh maker-blind critic.',
   'delivery.routing.closeAndLand':
     'When true, single-story-close lands through merge in one close (opt out with --no-wait-merge).',
-  'delivery.feedbackLoop.auditResultsAutoFile':
-    'When true, auto-file non-blocking audit findings as follow-up issues.',
   'delivery.feedbackLoop.retroProposals':
     'When true, auto-file actionable retro proposals as follow-up issues.',
   'delivery.quality.formatAutofix.timeoutMs':

package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js

@@ -53,7 +53,7 @@ export const INCREMENTAL_COVERAGE_SCHEMA = {
       type: 'string',
       minLength: 1,
       description:
-        'Git ref the changed-file set is computed against. Omitted falls back to the gate’s own `--ref` (`main`).',
+        'Default git ref the changed-file set is computed against, for a caller that passes no `--ref`. A `--ref` the caller named wins over this value, so a caller that anchors another gate on the same ref — `.husky/pre-push`, which passes `--ref origin/main` and then previews `--changed-since origin/main` — resolves ONE scope for both steps (Story #5365). Omitted and unpassed, the gate’s own default `main` applies.',
     },
   },
   additionalProperties: false,

package/.agents/scripts/lib/config-resolver.js

@@ -62,6 +62,7 @@ export { resolveListValue } from './config/shared.js';
 export { validateOrchestrationConfig } from './config/validate-orchestration.js';
 export {
   defaultNodeModulesStrategy,
+  getWorktreeIsolation,
   WORKTREE_ISOLATION_DEFAULTS,
 } from './config/worktree-isolation.js';
 export { PROJECT_ROOT } from './project-root.js';

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -258,12 +258,12 @@ const MERGE_WATCH_SCHEMA = {
 // context; false falls back to `subagent_type: general-purpose` (the instant
 // per-consumer revert + the escape for hosts that ignore `.claude/agents/`).
 // Story #5313 retired `delivery.routing.freshCriticSampleRate` (the
-// maker-checker sampling floor): the standard profile now routes purely off
-// the derived change level.
+// maker-checker sampling floor). Story #5343 then retired the derived-level
+// routing it left behind: the profile alone decides the verdict owner.
 const ROUTING_SCHEMA = {
   type: 'object',
   description:
-    'v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313.',
+    'v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313 and the derived-level ceremony routing in Story #5343.',
   properties: {
     roleScopedAgents: {
       type: 'boolean',
@@ -275,7 +275,7 @@ const ROUTING_SCHEMA = {
       type: 'string',
       enum: ['minimal', 'standard', 'strict'],
       description:
-        'Acceptance-ceremony depth. minimal = always inline critic; strict = always fresh-context critic; standard (default) = routed off the change level derived from the Story diff: high or underivable → fresh, low → inline.',
+        'Acceptance-ceremony depth — who authors the Story acceptance verdict. minimal and standard (default) = the inline self-eval, whatever the diff touches; strict = a fresh-context maker-blind critic. Review depth is a separate decision and still derives `deep` for any sensitive path (review-depth.js).',
       default: DELIVERY_ROUTING_DEFAULTS.ceremonyProfile,
     },
     closeAndLand: {
@@ -452,18 +452,31 @@ const REVIEW_SCHEMA = {
 };
 
 /**
- * `delivery.feedbackLoop` — opt-out toggles consumed by the Epic finalize
- * listener's auto-file graduators (`lib/feedback-loop/*-graduator.js`, read
- * via `graduator-core.js#makeIsAutoFileEnabled`). All default to `true`
- * (auto-file on); set any to `false` to suppress auto-filing the
- * corresponding non-blocking findings as follow-up issues.
+ * `delivery.feedbackLoop` — the **opt-in** toggle consumed by the retro
+ * auto-file graduator (`lib/feedback-loop/retro-proposals-graduator.js`, read
+ * via `graduator-core.js#makeIsAutoFileEnabled`), plus the friction window.
  *
- * `retroProposals` (Story #4418) governs the retro auto-filer: when true
- * (default) the retro's actionable routed proposals are filed as
+ * `auditResultsAutoFile` used to sit beside `retroProposals` here. Its
+ * graduator was deleted two releases ago, so by Story #5341 — which flipped
+ * its default from `true` to `false` on the measured record of what the
+ * channel produced — there was nothing left to switch either way. Story #5366
+ * removed the key: a toggle with no runtime reader reads as a live control,
+ * and a consumer that set it was configuring nothing. The
+ * `2.60.0-retire-audit-results-autofile` migration strips it from both config
+ * surfaces, because this block is closed to additional properties and a
+ * surviving key is a hard validation failure on upgrade.
+ *
+ * `retroProposals` (Story #4418) governs the retro auto-filer, and defaults to
+ * `false` for the same Story #5341 reasons: Story #5324's roll-up carried 116
+ * signals and filed nothing, and issues #4653, #4833, #4834 and #4836 are
+ * filings that were false or leaked from test fixtures. An auto-filer whose
+ * output is dominated by noise costs triage on every run and buys nothing, so
+ * a consumer that wants it now asks for it. When `true` the
+ * retro's actionable routed proposals are filed as
  * `meta::<framework-gap|consumer-improvement>` + `friction::<category>`
  * issues via the graduator pre-parsed-findings seam, and the rendered retro
  * sections list the filed issue numbers instead of paste-ready `gh` command
- * stanzas; set it to `false` to fall back to the command stanzas.
+ * stanzas; left `false` it renders the command stanzas.
  *
  * `frictionWindowDays` (Story #4850) bounds the run-scope friction recurrence
  * window by row age. The window deliberately spans every surviving signal
@@ -475,19 +488,13 @@ const REVIEW_SCHEMA = {
 const FEEDBACK_LOOP_SCHEMA = {
   type: 'object',
   description:
-    'Opt-out toggles for the close-time auto-file graduators. All default to auto-filing on.',
+    'Opt-in toggle for the close-time retro auto-file graduator, plus the friction recurrence window. Auto-filing defaults to OFF (Story #5341).',
   properties: {
-    auditResultsAutoFile: {
-      type: 'boolean',
-      description:
-        'When true (default), the close-time audit-results graduator auto-files non-blocking audit-results findings as follow-up issues routed by source classification. Set to false to suppress auto-filing; findings remain accessible in the structured comments on the Story.',
-      default: true,
-    },
     retroProposals: {
       type: 'boolean',
       description:
-        'When true (default), the retro auto-files its actionable routed proposals as meta::<framework-gap|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Set to false to fall back to the command stanzas.',
-      default: true,
+        'When true, the retro auto-files its actionable routed proposals as meta::<framework-gap|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Defaults to false (Story #5341), which renders the command stanzas instead.',
+      default: false,
     },
     frictionWindowDays: {
       type: 'integer',

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

@@ -8,6 +8,7 @@
  * logic; behaviour is byte-for-byte the pre-#4981 body.
  */
 import path from 'node:path';
+import { resolveChangedFilesRef } from './changed-files.js';
 import {
   anyChangedUnderTargets,
   describeFreshness,
@@ -19,10 +20,14 @@ import {
  * content-digest freshness probe, and — when stale — the full-repo
  * `npm run test:coverage` capture + stamp write.
  *
+ * The skip check scores the ref `resolveChangedFilesRef` resolves — the rule,
+ * and the same answer, incremental mode applies, so a fall-through from it
+ * cannot change scope mid-run (Story #5365).
+ *
  * @param {{
  *   crap: object,
  *   coverage: object,
- *   args: { skipWhenNoCrapFiles: boolean, ref: string, cwd: string },
+ *   args: { skipWhenNoCrapFiles: boolean, ref: string | null, cwd: string },
  *   getChangedFilesImpl: Function,
  *   isCoverageFreshImpl: Function,
  *   runCaptureImpl: Function,
@@ -46,7 +51,10 @@ export function runFullScopeCapture({
   if (args.skipWhenNoCrapFiles) {
     let changed;
     try {
-      changed = getChangedFilesImpl({ ref: args.ref, cwd: args.cwd });
+      changed = getChangedFilesImpl({
+        ref: resolveChangedFilesRef({ crap, ref: args.ref }),
+        cwd: args.cwd,
+      });
     } catch (err) {
       // A bad ref must not silently relax the gate. Fall through to the
       // freshness check so coverage still gets captured if needed.

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

@@ -9,6 +9,7 @@
  * parameter (`.agents/rules/test-seams.md` rules 1-2, 4).
  */
 import path from 'node:path';
+import { resolveChangedFilesRef } from './changed-files.js';
 import { stampCapturedTree } from './coverage-capture.js';
 
 /**
@@ -38,7 +39,7 @@ import { stampCapturedTree } from './coverage-capture.js';
  * @param {{
  *   crap: object,
  *   coverage: object,
- *   args: { ref: string, cwd: string },
+ *   args: { ref: string | null, cwd: string },
  *   getChangedFilesImpl: Function,
  *   filterFilesUnderTargetsImpl: Function,
  *   isCoverageFreshImpl: Function,
@@ -63,7 +64,7 @@ export function tryIncrementalCapture({
 }) {
   if (crap.incrementalCoverage?.skipWhenUnchanged !== true) return null;
 
-  const ref = crap.incrementalCoverage.baseRef || args.ref;
+  const ref = resolveChangedFilesRef({ crap, ref: args.ref });
   let changed = null;
   try {
     changed = getChangedFilesImpl({ ref, cwd: args.cwd });

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

@@ -39,7 +39,10 @@ const COVERAGE_CAPTURE_USAGE = {
       '--require-credited',
       'Refuse (exit 1) instead of spawning when no credited capture stamp covers this tree. Passed by the close gate when delivery.execution.requireCreditedCapture is set; a bare invocation always runs, so the deposit path stays open.',
     ],
-    ['--ref <git-ref>', 'Git ref the changed-file set is computed against.'],
+    [
+      '--ref <git-ref>',
+      'Git ref the changed-file set is computed against. Passing it wins over delivery.quality.gates.crap.incrementalCoverage.baseRef, so a caller that anchors another gate on the same ref gets one scope for both.',
+    ],
     ['--cwd <path>', 'Repository root the capture runs in.'],
   ],
 };

package/.agents/scripts/lib/doc-tiers.js

@@ -27,8 +27,10 @@
  *   - `agentBoot`     — the role-scoped boot contexts `.agents/agents/*.md`
  *                       (issue #4478). Each is a standalone system prompt a
  *                       converted spawn boots on **instead of** the always-loaded
- *                       closure, so it is budgeted independently (per-file ≤8KB
- *                       ceiling gated by `check-context-budget.js`).
+ *                       closure, so it is measured independently. Its per-file
+ *                       8 KB ceiling was deleted by Story #5340;
+ *                       `check-context-budget.js` now reports these sizes and
+ *                       gates nothing on them.
  *   - `workflow` /    — the `.agents/workflows/**` read-tier (Story #4752),
  *     `workflowOnDemand` resolved as each entry point's transitive
  *                       markdown-link closure by

package/.agents/scripts/lib/feedback-loop/graduator-core.js

@@ -290,18 +290,19 @@ export function runChild({
 
 /**
  * Build an `isAutoFileEnabled(config)` reader bound to a specific
- * `delivery.feedbackLoop.<key>` toggle. The feature is opt-out: the
- * toggle defaults to `true` and only an explicit `false` disables it.
+ * `delivery.feedbackLoop.<key>` toggle. The feature is **opt-in** since Story
+ * #5341: the toggle defaults to `false` and only an explicit `true` enables
+ * it, because the filings the channel produced unattended were dominated by
+ * noise (see `config-settings-schema-delivery.js` for the measured record).
  *
  * @param {string} toggleKey — key under `config.delivery.feedbackLoop`
- *   (e.g. "auditResultsAutoFile", "retroProposals")
+ *   (today, only "retroProposals" — the factory stays keyed so the next
+ *   graduator does not have to reinvent the resolution)
  * @returns {(config: object|undefined|null) => boolean}
  */
 export function makeIsAutoFileEnabled(toggleKey) {
   return function isAutoFileEnabled(config) {
-    const value = config?.delivery?.feedbackLoop?.[toggleKey];
-    if (value === false) return false;
-    return true;
+    return config?.delivery?.feedbackLoop?.[toggleKey] === true;
   };
 }
 

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -28,9 +28,9 @@
  * is gone from the whole path, not just from this module. The `meta::<framework-gap|consumer-improvement>` +
  * `friction::<category>` labels are lifted verbatim from the routed item.
  *
- * Behind the `delivery.feedbackLoop.retroProposals` toggle (default ON,
- * per `graduator-core.js#makeIsAutoFileEnabled`). NEVER throws — every
- * failure path is captured in `errors[]`.
+ * Behind the `delivery.feedbackLoop.retroProposals` toggle (default OFF
+ * since Story #5341, per `graduator-core.js#makeIsAutoFileEnabled`). NEVER
+ * throws — every failure path is captured in `errors[]`.
  */
 
 import {
@@ -46,8 +46,10 @@ import {
 } from './graduator-core.js';
 
 /**
- * Resolve the toggle from the resolved agentrc config. Defaults to `true`
- * — the feature is opt-out (mirrors auditResultsAutoFile).
+ * Resolve the toggle from the resolved agentrc config. Defaults to `false`
+ * — the feature is opt-in (Story #5341). It is now the only such toggle: the
+ * audit-results sibling was removed by Story #5366, its graduator having been
+ * deleted two releases earlier.
  *
  * @param {object|undefined|null} config
  * @returns {boolean}