mandrel 2.35.0 → 2.37.0

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

@@ -90,6 +90,7 @@
  *     confirm.
  */
 
+import { getCiDelivery } from '../../../config/ci.js';
 import { createGh } from '../../../gh-exec.js';
 import {
   confirmStoryMerged as defaultConfirmStoryMerged,
@@ -106,8 +107,10 @@ import { classifyMergeBlock as defaultClassifyMergeBlock } from '../../merge-blo
 import {
   DEFAULT_INTERVAL_SECONDS,
   DEFAULT_MAX_BUDGET_SECONDS,
+  decideAdvisoryGateBlock,
   decideMergeWaitFailFast,
   deriveChecksStatus,
+  deriveRedHeadRuns,
   deriveRequiredRunEvidence,
   MERGE_WAIT_GH_TIMEOUT_MS,
 } from '../../merge-poll.js';
@@ -117,6 +120,7 @@ import {
   STATE_LABELS,
   transitionTicketState,
 } from '../../ticketing.js';
+import { disarmAutoMerge } from './auto-merge.js';
 import { runPostLandTail as defaultRunPostLandTail } from './post-land.js';
 
 /**
@@ -256,6 +260,10 @@ export async function readPrWaitProbe({
       // the aggregate `checksStatus` folds together. `null` when the rollup is
       // absent/empty — the loop's consecutive-probe fallback owns that path.
       requiredRunEvidence: deriveRequiredRunEvidence(view?.statusCheckRollup),
+      // The named red head runs (Story #5096), so an `advisory-gate-red`
+      // verdict can name the offending job and match the allowlist. Same
+      // red-ness test as `requiredRunEvidence`, so the two cannot disagree.
+      redHeadRuns: deriveRedHeadRuns(view?.statusCheckRollup),
     };
   } catch (err) {
     return {
@@ -263,6 +271,7 @@ export async function readPrWaitProbe({
       mergedAt: null,
       createdAt: null,
       checksStatus: 'pending',
+      redHeadRuns: [],
       error: `PR probe failed: ${err?.message ?? err}`,
     };
   }
@@ -541,6 +550,46 @@ async function blockOnFlipFailed({
  * is best-effort logged rather than thrown — the caller owns surfacing the
  * non-zero exit once this returns.
  */
+/**
+ * Story #5096 — resolve the advisory-gate terminal for one poll.
+ *
+ * Takes the poll's current `unlanded` and returns it unchanged when a terminal
+ * is already decided, so the caller is a single assignment with NO added
+ * branch. `runMergePoll` is already above `check-cyclomatic`'s ceiling; the
+ * three decision points this would otherwise cost inline are a real gate
+ * regression, and they belong with the policy either way.
+ *
+ * Disarms BEFORE returning the terminal: an armed PR can merge out from under
+ * the block the caller is about to record.
+ */
+async function resolveAdvisoryUnlanded({
+  unlanded,
+  probe,
+  blockOnAdvisoryFailure,
+  advisoryAllowlist,
+  prNumber,
+  gh,
+  progress,
+  disarmAutoMergeFn,
+  elapsedSeconds,
+}) {
+  if (unlanded) return unlanded;
+  const advisory = decideAdvisoryGateBlock({
+    probe,
+    blockOnAdvisoryFailure,
+    advisoryAllowlist,
+  });
+  if (!advisory) return null;
+  progress?.('CONFIRM', `🛑 PR #${prNumber}: ${advisory.reason}`);
+  await disarmAutoMergeFn({ prNumber, gh, progress });
+  return {
+    prProbe: probe,
+    budget: { exhausted: false, elapsedSeconds },
+    blockClassOverride: 'advisory-gate-red',
+    reasonOverride: advisory.reason,
+  };
+}
+
 async function blockOnUnlanded({
   storyId,
   prNumber,
@@ -552,12 +601,24 @@ async function blockOnUnlanded({
   progress,
   classifyMergeBlockFn,
   emitMergeUnlandedFn,
+  blockClassOverride,
+  reasonOverride,
 }) {
-  const { blockClass, reason } = classifyMergeBlockFn({
-    armResult,
-    prProbe,
-    budget,
-  });
+  // Story #5096 — `advisory-gate-red` is emitted DIRECTLY, never derived.
+  // `classifyMergeBlock` cannot produce it: by construction GitHub is NOT
+  // gating this merge (`mergeStateStatus: UNSTABLE`), which is the entire
+  // condition the class names, so every classifier heuristic reads the PR as
+  // healthy.
+  const { blockClass, reason } = blockClassOverride
+    ? {
+        blockClass: blockClassOverride,
+        reason: reasonOverride ?? blockClassOverride,
+      }
+    : classifyMergeBlockFn({
+        armResult,
+        prProbe,
+        budget,
+      });
   const elapsedSeconds = budget?.elapsedSeconds ?? 0;
   // Which evidence path produced a `checks-failed` verdict (Story #4695):
   // `per-run` (head-anchored required-run evidence) or `consecutive-probe`
@@ -820,6 +881,7 @@ export async function runConfirmMergePhase({
   prUrl,
   autoMergeEnabled,
   autoMergeReason,
+  advisoryGate,
   provider,
   config,
   maxWaitSeconds: maxWaitSecondsOverride,
@@ -834,6 +896,7 @@ export async function runConfirmMergePhase({
   emitMergeUnlandedFn = defaultEmitMergeUnlanded,
   emitMergeFlipFailedFn = defaultEmitMergeFlipFailed,
   runPostLandTailFn = defaultRunPostLandTail,
+  disarmAutoMergeFn = disarmAutoMerge,
   sleepFn = defaultSleep,
   nowMsFn = Date.now,
   ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
@@ -857,6 +920,15 @@ export async function runConfirmMergePhase({
       progress,
       classifyMergeBlockFn,
       emitMergeUnlandedFn,
+      // Story #5096 — the arm phase already refused over a red advisory gate;
+      // carry its verdict through instead of letting the classifier read this
+      // as a generic `arm-failure`.
+      ...(autoMergeReason === 'advisory-gate-red'
+        ? {
+            blockClassOverride: 'advisory-gate-red',
+            reasonOverride: advisoryGate?.reason,
+          }
+        : {}),
     });
   }
 
@@ -871,6 +943,8 @@ export async function runConfirmMergePhase({
     maxWaitSecondsOverride,
     mergeWatchModeOverride,
   );
+  // Story #5096 — the advisory-gate knobs, read once for the whole wait.
+  const { blockOnAdvisoryFailure, advisoryAllowlist } = getCiDelivery(config);
   const intervalMs = intervalSeconds * 1000;
   const startedAtMs = nowMsFn();
   let anchorMs = startedAtMs;
@@ -1020,6 +1094,23 @@ export async function runConfirmMergePhase({
           },
         };
       }
+
+      // Story #5096 — the ADVISORY counterpart, and the half that catches the
+      // common shape. Close arms immediately after opening the PR, while the
+      // gate is still QUEUED, so the pre-arm refusal in `auto-merge.js` sees
+      // nothing; the gate reddens here, mid-wait, and native auto-merge would
+      // land the PR the moment the REQUIRED contexts go green.
+      unlanded = await resolveAdvisoryUnlanded({
+        unlanded,
+        probe,
+        blockOnAdvisoryFailure,
+        advisoryAllowlist,
+        prNumber,
+        gh: injectedGh,
+        progress,
+        disarmAutoMergeFn,
+        elapsedSeconds: Math.round(waitedMs / 1000),
+      });
     }
 
     if (!unlanded) {

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

@@ -87,6 +87,50 @@ export function resolveWaitForMerge({
   };
 }
 
+/**
+ * Flags this CLI advertised in its `--help` descriptor and never implemented
+ * (Story #5100). `--dry-run` was transcribed into the usage block by the
+ * #4750 self-describing sweep and read by nothing in this pipeline —
+ * `git log -S dryRun` over it is empty in every revision — so an operator who
+ * trusted it got a real base-sync merge, an `agent::blocked` Story, and a
+ * terminal envelope that then captured `deliver-recover`'s routing.
+ * `--no-evidence` names a working flag on the gate wrappers
+ * (`evidence-gate.js`), but the slot this CLI parsed had no reader at all.
+ *
+ * Deleting them from the descriptor is NOT enough. `parseSprintArgs` runs
+ * `parseArgs` with `strict: false`, so an unknown flag is silently ignored and
+ * the close proceeds for real — the identical injury, now with no help text to
+ * explain it. Fail closed instead, exactly as `parseMergeWatchMode` does for an
+ * unrecognized mode: throw during option parsing, before the first phase, so
+ * the CLI boundary reports `failed` at phase `init` and nothing is mutated.
+ */
+const RETIRED_FLAGS = Object.freeze({
+  '--dry-run':
+    'this pipeline has never had a dry-run mode; it was advertised in error.',
+  '--no-evidence':
+    'per-close evidence control was never wired here; the working flag of that name belongs to the gate wrappers.',
+});
+
+/**
+ * Reject a retired flag before any phase runs.
+ *
+ * Matches `--flag` and `--flag=value`; a bare `--` terminator or a positional
+ * that merely contains the text is not a flag and does not trip it.
+ *
+ * @param {string[]} argv argv tail (`process.argv.slice(2)`)
+ * @throws {Error} naming the flag, why it is gone, and that nothing was mutated
+ */
+function assertNoRetiredFlags(argv) {
+  for (const [flag, why] of Object.entries(RETIRED_FLAGS)) {
+    const present = argv.some((a) => a === flag || a.startsWith(`${flag}=`));
+    if (!present) continue;
+    throw new Error(
+      `${flag} was retired: ${why} Nothing was mutated — no branch, label, ` +
+        `comment, or PR was touched. Re-run without it to close for real.`,
+    );
+  }
+}
+
 /**
  * Parse and resolve all CLI / injection options for `runSingleStoryClose`.
  *
@@ -116,7 +160,14 @@ export function parseCloseOptions({
   // which is precisely what `resolveFlag` already does below, preferring the
   // param over the parsed slot. One expression per flag now serves both
   // callers, so a new flag is added in one place instead of two that can drift.
-  const parsed = storyIdParam === undefined ? parseSprintArgs() : {};
+  // The guard runs on the argv door only: an injecting caller supplies
+  // `storyIdParam` and never reads argv, so the host process's flags (a test
+  // runner's, say) are none of its business.
+  let parsed = {};
+  if (storyIdParam === undefined) {
+    assertNoRetiredFlags(process.argv.slice(2));
+    parsed = parseSprintArgs();
+  }
   // Preserve undefined so resolveWaitForMerge can apply the closeAndLand
   // config default when neither flag was supplied.
   const waitForMergeExplicit = resolveFlag(

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

@@ -485,6 +485,7 @@ async function resolveAutoMergeOutcome({ alreadyMerged, ...phaseArgs }) {
       autoMergeReason: null,
       localCleanupDeferred: false,
       directMerged: false,
+      advisoryGate: null,
     };
   }
   return await runAutoMergePhase(phaseArgs);
@@ -541,6 +542,7 @@ async function finishWithMergeWait(prCtx, deps) {
     prUrl: prCtx.prUrl,
     autoMergeEnabled: prCtx.autoMergeEnabled,
     autoMergeReason: prCtx.autoMergeReason,
+    advisoryGate: prCtx.advisoryGate,
     provider: deps.provider,
     config: prCtx.config,
     maxWaitSeconds: deps.maxWaitSeconds,
@@ -796,18 +798,23 @@ async function runClosePipeline({
     WorktreeManager,
   });
   setPhase('auto-merge');
+  const ciDelivery = getCiDelivery(config);
   const {
     autoMergeEnabled,
     autoMergeReason,
     localCleanupDeferred,
     directMerged,
+    advisoryGate,
   } = await resolveAutoMergeOutcome({
     alreadyMerged,
     cwd: options.cwd,
     prNumber,
     prUrl,
     noAutoMerge: options.noAutoMerge,
-    autoMergePolicy: getCiDelivery(config).autoMerge,
+    autoMergePolicy: ciDelivery.autoMerge,
+    // Story #5096 — the pre-arm advisory-gate refusal.
+    blockOnAdvisoryFailure: ciDelivery.blockOnAdvisoryFailure,
+    advisoryAllowlist: ciDelivery.advisoryAllowlist,
     gh: injectedGh,
     progress,
   });
@@ -866,6 +873,7 @@ async function runClosePipeline({
     prUrl,
     autoMergeEnabled,
     autoMergeReason,
+    advisoryGate,
     worktreeReaped,
     localCleanupDeferred,
     directMerged,

package/.agents/scripts/lib/orchestration/story-close/format-autofix.js

@@ -63,7 +63,7 @@ export const FORMAT_AUTOFIX_TIMEOUT_EXIT_CODE = 124;
  * @param {(args: string[], opts: object) => string} git
  * @returns {string[]}
  */
-export function listDirtyPaths(cwd, git) {
+function listDirtyPaths(cwd, git) {
   const out = git(['status', '--porcelain'], {
     cwd,
     encoding: 'utf8',
@@ -91,10 +91,7 @@ export function listDirtyPaths(cwd, git) {
  * }} [opts]
  * @returns {{ writeCmdString: string, writeCmd: string, writeArgs: string[] }}
  */
-export function resolveFormatterCmd({
-  commands,
-  dropTrailingDot = false,
-} = {}) {
+function resolveFormatterCmd({ commands, dropTrailingDot = false } = {}) {
   // `resolveFormatWriteCommand` reads `config.project.commands`; wrap the
   // caller-supplied `commands` map into that canonical shape.
   const writeCmdString = resolveFormatWriteCommand({ project: { commands } });

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -24,7 +24,7 @@ import {
 } from './retro-proposals.js';
 import { upsertStructuredComment } from './ticketing.js';
 
-export const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
+const FOLLOW_UPS_COMMENT_TYPE = 'follow-ups';
 
 /** Milliseconds in one day — the unit `frictionWindowDays` is expressed in. */
 const MS_PER_DAY = 24 * 60 * 60 * 1000;

package/.agents/scripts/lib/orchestration/ticket-lease.js

@@ -29,8 +29,9 @@
  *                       a claim back from whoever took over).
  *
  * Provider contract (a subset of `ITicketingProvider`):
- *   - `getTicket(id)`            → `{ assignees: string[], ... }`
- *   - `updateTicket(id, { assignees })` writes the assignee list.
+ *   - `getTicket(id)`               → `{ assignees: string[], ... }`
+ *   - `updateTicket(id, { assignees })`    replaces the assignee list.
+ *   - `updateTicket(id, { addAssignees })` appends to it (Story #5112).
  */
 
 /**
@@ -128,11 +129,13 @@ function normaliseOpts(op, opts) {
  *                                     operator out, `acquired: false`,
  *                                     `owner: <foreign>`, `reason: 'lost-race'`.
  *
- * Every claiming write is verified: GitHub's assignee PATCH is not a
+ * Every claiming write is verified: GitHub's assignee write is not a
  * compare-and-set, so two runs that both read the ticket unassigned will both
  * write themselves. {@link claimAndVerify} re-reads after the write and refuses
  * (fail-closed) when a foreign login is present, so the loser of a simultaneous
- * claim never proceeds as though it holds the lease.
+ * claim never proceeds as though it holds the lease. Story #5112 made the
+ * first claim **additive** so that verify can actually see the collision —
+ * see {@link claimAndVerify}.
  *
  * @param {object} opts
  * @param {object} opts.provider              Ticketing provider.
@@ -199,7 +202,7 @@ export async function acquireLease(opts) {
  *
  * The assignee write is not atomic — GitHub offers no compare-and-set on the
  * assignees surface — so two runs that both observed the ticket unassigned (or
- * a stale foreign claim) will both PATCH themselves in. Without a check the
+ * a stale foreign claim) will both write themselves in. Without a check the
  * loser of that race returns `acquired: true` and marches into the worktree
  * the winner is already building. The verify closes that window: it re-reads
  * with `fresh: true` (bypassing any provider cache so it sees the other run's
@@ -208,9 +211,16 @@ export async function acquireLease(opts) {
  * returns `acquired: false` / `reason: 'lost-race'` so the fail-closed caller
  * refuses. A clean read (assignees exactly `[operator]`) confirms the claim.
  *
- * It does not eliminate the race — two writes still happen — but it makes the
- * outcome deterministic: exactly one operator survives as the sole assignee,
- * and the other is told it lost.
+ * **The write must be additive for the verify to work (Story #5112).** With
+ * the replacing PATCH this used unconditionally, a simultaneous claim
+ * *evicted* the other operator rather than joining it, so the co-assignment
+ * the `lost-race` branch keys on was a state the PATCH could never produce:
+ * each run read a clean `[self]` on verify and both proceeded. Claiming an
+ * unowned ticket therefore goes through the additive assignees endpoint
+ * (`addAssignees`), which makes the collision observable and lets exactly one
+ * claimer survive. The replacing form stays for the two cases that genuinely
+ * mean "replace": the `--steal` transfer of a foreign claim, and the loser's
+ * own back-out below.
  *
  * @param {object} args
  * @param {object} args.provider              Ticketing provider.
@@ -220,6 +230,21 @@ export async function acquireLease(opts) {
  * @param {string} args.reason                Success reason when the claim holds.
  * @returns {Promise<{ acquired: boolean, owner: string, previousOwner: string|null, reason: string }>}
  */
+/**
+ * The assignee mutation a claim writes. Additive when the ticket has no
+ * previous owner — that is what makes a simultaneous claim show up as a
+ * co-assignment {@link claimAndVerify} can detect. Replacing only for a
+ * steal, where evicting the previous owner *is* the intent.
+ *
+ * @param {string} operator
+ * @param {string|null} previousOwner
+ * @returns {{ addAssignees: string[] }|{ assignees: string[] }}
+ */
+function claimMutation(operator, previousOwner) {
+  if (previousOwner === null) return { addAssignees: [operator] };
+  return { assignees: [operator] };
+}
+
 async function claimAndVerify({
   provider,
   ticketId,
@@ -227,7 +252,7 @@ async function claimAndVerify({
   previousOwner,
   reason,
 }) {
-  await provider.updateTicket(ticketId, { assignees: [operator] });
+  await provider.updateTicket(ticketId, claimMutation(operator, previousOwner));
 
   const after = await provider.getTicket(ticketId, { fresh: true });
   const assignees = Array.isArray(after?.assignees) ? after.assignees : [];

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -81,7 +81,9 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
   'epic-run-state',
   'epic-run-progress',
   'epic-plan-state',
-  'parked-follow-ons',
+  // `parked-follow-ons` retired in Story #5114 with the module that was its
+  // only writer. A kind the reader still recognises but nothing emits is the
+  // same dead wiring in a new place.
   // Story #566 — per-phase wall-clock summary posted by single-story-close.js.
   'phase-timings',
   // Story #831 — story-init upserts a `story-init` comment that

package/.agents/scripts/lib/preflight-runner.js

@@ -124,7 +124,7 @@ function pick(logger, level) {
  * @param {Array<object>} fixed
  * @param {object} [logger]
  */
-export function logFixes(fixed, logger = DEFAULT_LOGGER) {
+function logFixes(fixed, logger = DEFAULT_LOGGER) {
   const info = pick(logger, 'info');
   info(`[preflight] auto-fixed ${fixed.length} finding(s):`);
   for (const f of fixed) {
@@ -141,7 +141,7 @@ export function logFixes(fixed, logger = DEFAULT_LOGGER) {
  * @param {Array<object>} blockers
  * @param {object} [logger]
  */
-export function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
+function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
   const error = pick(logger, 'error');
   error(
     `[preflight] ${scope}: ${blockers.length} blocker finding(s) — refusing to proceed.`,
@@ -180,7 +180,7 @@ export function logBlockers(scope, blockers, logger = DEFAULT_LOGGER) {
  * @param {Array<object>} findings
  * @param {object} [logger]
  */
-export function logNonBlockers(findings, logger = DEFAULT_LOGGER) {
+function logNonBlockers(findings, logger = DEFAULT_LOGGER) {
   const warn = pick(logger, 'warn');
   for (const f of findings) {
     warn(`[preflight] ${f.severity}: ${f.id} — ${f.summary ?? ''}`);

package/.agents/scripts/lib/qa/qa-session.js

@@ -36,7 +36,7 @@ import path from 'node:path';
 import { tempRootFrom } from '../config/temp-paths.js';
 
 /** Directory segment (under `tempRoot`) that holds every QA session ledger. */
-export const QA_LEDGER_DIRNAME = 'qa';
+const QA_LEDGER_DIRNAME = 'qa';
 
 /**
  * Triaged dispositions, mirrored from the `disposition` enum in

package/.agents/scripts/lib/runtime-deps/manifest.js

@@ -26,13 +26,7 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
  * `.agents/scripts/lib/runtime-deps/`; the manifest sits at the `.agents/`
  * root, three directories up.
  */
-export const MANIFEST_PATH = path.resolve(
-  HERE,
-  '..',
-  '..',
-  '..',
-  'runtime-deps.json',
-);
+const MANIFEST_PATH = path.resolve(HERE, '..', '..', '..', 'runtime-deps.json');
 
 /**
  * @typedef {object} RuntimeDepsManifest

package/.agents/scripts/lib/runtime-deps/scan-imports.js

@@ -26,9 +26,10 @@
 import fs from 'node:fs';
 import { builtinModules } from 'node:module';
 import path from 'node:path';
+import { stripJsComments } from '../source-text/strip-js-comments.js';
 
 /** Node builtins, with and without the `node:` prefix. */
-export const BUILTIN_MODULES = new Set([
+const BUILTIN_MODULES = new Set([
   ...builtinModules,
   ...builtinModules.map((m) => `node:${m}`),
 ]);
@@ -71,62 +72,6 @@ const SIDE_EFFECT = /^\s*import\s*['"]([^'"]+)['"]/gm;
 // `require(...)` and dynamic `import(...)` may appear mid-expression.
 const CALL_FORM = /\b(?:require|import)\s*\(\s*['"]([^'"]+)['"]/g;
 
-/**
- * Remove `//` line comments and block comments while preserving string and
- * template literals (which carry the import specifiers we extract). A
- * char-by-char state machine is used rather than a regex so that comment
- * markers inside string literals (e.g. a `https://` URL) are not mistaken
- * for comments, and example import syntax inside *comments* (e.g. a
- * `// require('x')` doc line) does not register as a phantom dependency.
- *
- * @param {string} source
- * @returns {string}
- */
-export function stripComments(source) {
-  let out = '';
-  let i = 0;
-  const n = source.length;
-  while (i < n) {
-    const ch = source[i];
-    const next = source[i + 1];
-    // Enter a string / template literal — copy verbatim until it closes.
-    if (ch === '"' || ch === "'" || ch === '`') {
-      const quote = ch;
-      out += ch;
-      i += 1;
-      while (i < n) {
-        const c = source[i];
-        out += c;
-        if (c === '\\') {
-          // Copy the escaped char too, then continue.
-          if (i + 1 < n) out += source[i + 1];
-          i += 2;
-          continue;
-        }
-        i += 1;
-        if (c === quote) break;
-      }
-      continue;
-    }
-    // Line comment — drop to end of line (keep the newline).
-    if (ch === '/' && next === '/') {
-      i += 2;
-      while (i < n && source[i] !== '\n') i += 1;
-      continue;
-    }
-    // Block comment — drop until the closing `*/`.
-    if (ch === '/' && next === '*') {
-      i += 2;
-      while (i < n && !(source[i] === '*' && source[i + 1] === '/')) i += 1;
-      i += 2;
-      continue;
-    }
-    out += ch;
-    i += 1;
-  }
-  return out;
-}
-
 /**
  * Extract the set of third-party top-level package names imported by a
  * single source string.
@@ -136,7 +81,7 @@ export function stripComments(source) {
  */
 export function extractThirdPartyImports(source) {
   const found = new Set();
-  const cleaned = stripComments(source);
+  const cleaned = stripJsComments(source);
   for (const re of [STATIC_FROM, SIDE_EFFECT, CALL_FORM]) {
     re.lastIndex = 0;
     let match = re.exec(cleaned);