mandrel 2.21.0 → 2.22.0

package/.agents/scripts/lib/orchestration/complexity-gate.js

@@ -31,15 +31,16 @@
  *      cardinality is deliberately not an axis (Story #4764).
  *   4. **Deliver re-derives.** `/deliver` computes the route from the fetched
  *      Story body via the **same** shape function at dispatch
- *      ({@link resolveStoryDispatchMode}) and honors it: a lite-shaped Story
- *      executes inline — no story-worker sub-agent boot, no fresh
- *      acceptance-critic dispatch — while every `single-story-close.js` gate
- *      runs unchanged. The `route::lite` label is a **human-visible hint
- *      only**, never the control signal: a lost label or an unread marker can
- *      no longer misroute delivery. Ahead of the shape read sits one
- *      shape-independent rule (Story #4736): a **single-Story run** is inline
- *      whatever its shape, because sub-agent isolation buys nothing when
- *      there is no concurrent sibling to isolate from.
+ *      ({@link resolveStoryDispatchMode}) and **reports** it, while the
+ *      dispatch *mode* answers a different question: may the engine run in the
+ *      router's own session? Only a **single-Story run** may (Story #4736) —
+ *      sub-agent isolation buys nothing when there is no concurrent sibling to
+ *      isolate from. Shape cannot grant that session (Story #4829): a lite body
+ *      makes work cheap, it does not conjure a second session for a sibling to
+ *      run in. The `route::lite` label is a **human-visible hint only**, never
+ *      the control signal: a lost label or an unread marker can no longer
+ *      misroute delivery. Either way every `single-story-close.js` gate runs
+ *      unchanged.
  *
  * The shape taxonomy is deliberately the one `review-depth.js` already
  * applies to the landed diff at close (`deriveChangeLevel` over the
@@ -864,27 +865,34 @@ function routeForReporting(body, opts) {
 /**
  * Decide how `/deliver` executes a Story.
  *
- * Two independent premises, checked in this order:
- *
- * 1. **Run topology (Story #4736).** A run delivering a *single* Story
- *    executes **inline**, whatever its shape. Sub-agent isolation is
- *    load-bearing only for CONCURRENT dispatch — two workers sharing a
- *    checkout would race on worktrees and branch refs — and a one-Story run
- *    has no sibling to race. It therefore pays the spawn premium (a boot is
- *    a cache WRITE at full rate, where an inline continuation is a cache read
- *    at ~10%; ~$1.43/M vs ~$1.07/M on comparable bench work) for nothing.
- *    This is a fact about the run, not about the work, so the shape gate's
- *    `enabled` switch — which governs *shape derivation* — does not reach it.
- * 2. **Shape (Story #4722 AC-4/AC-5).** For a multi-Story run, the decision
- *    comes **from the Story body's own shape**, never from the `route::lite`
- *    label: a lite-shaped Story executes inline; everything else — a
- *    full-shaped body, a missing/unparseable body, or the gate disabled via
- *    `planning.complexityGate.enabled=false` — dispatches as a sub-agent,
- *    the conservative default.
- *
- * The label is read only to report hint consistency in `reasons`: with the
- * label absent (or its write failed) a lite-shaped Story still runs inline,
- * and with the label present on a full-shaped Story the shape wins.
+ * **`inline` names one indivisible resource: the router's own session.** Two
+ * Stories cannot both own it, so exactly one premise can grant it —
+ * **run topology (Story #4736)**: a run resolving a *single* Story executes
+ * inline whatever its shape, because sub-agent isolation is load-bearing only
+ * for CONCURRENT dispatch (two workers sharing a checkout race on worktrees and
+ * branch refs) and a one-Story run has no sibling to race. It therefore pays
+ * the spawn premium (a boot is a cache WRITE at full rate, where an inline
+ * continuation is a cache read at ~10%; ~$1.43/M vs ~$1.07/M on comparable
+ * bench work) for nothing. That is a fact about the run, not about the work, so
+ * the shape gate's `enabled` switch — which governs *shape derivation* — does
+ * not reach it.
+ *
+ * **Shape cannot grant it (Story #4829).** The shape read used to return
+ * `inline` for any lite-shaped body in a multi-Story run, inheriting no
+ * topology guard. Measured twice on 2026-07-29: a two-Story and a three-Story
+ * run came back `inline` for *every* Story while `stories-wave-tick.js`
+ * reported the whole set ready under a concurrency cap of five — a router
+ * following both signals literally runs several engines over one session and
+ * one checkout, the precise hazard the sub-agent path exists to prevent. Both
+ * runs were completed only by an operator overriding the verdict by hand, which
+ * is an invariant held by judgment rather than by code. So this function has
+ * exactly **one** `inline` exit, guarded by the topology premise; every path
+ * below it returns `subagent`, and the derived shape is carried on `route` for
+ * reporting only. A lite shape makes the work cheap — it does not conjure a
+ * second session for a sibling to run in.
+ *
+ * The label is read only to report hint consistency in `reasons`; it never
+ * routes on either premise (Story #4722 AC-4/AC-5).
  *
  * Inline execution removes model-side fan-out only — it changes **where** the
  * engine runs, never **what** runs. Every deterministic
@@ -901,7 +909,8 @@ function routeForReporting(body, opts) {
  *   selectSensitivePathClassesFn?: Function,
  * }} [args] `storyCount` is the number of Stories the invoking `/deliver` run
  *   resolved. Omitted (or not a positive integer) means "unknown run size",
- *   which falls through to the shape decision — never to an assumed 1.
+ *   which cannot be shown sibling-free and therefore dispatches as a sub-agent
+ *   — never an assumed 1.
  * @returns {{ mode: 'inline'|'subagent', reasons: string[], route: ReturnType<typeof deriveStoryShape>|null }}
  */
 export function resolveStoryDispatchMode({
@@ -920,6 +929,8 @@ export function resolveStoryDispatchMode({
     ? `the ${LITE_ROUTE_LABEL} label is present (hint only — the derived shape is the control signal)`
     : `the ${LITE_ROUTE_LABEL} label is absent (hint only — the derived shape is the control signal)`;
 
+  // The ONLY `inline` exit in this function, and the guard is the whole
+  // contract: an inline verdict must mean the engine can actually run inline.
   if (storyCount === 1) {
     return {
       mode: 'inline',
@@ -956,23 +967,17 @@ export function resolveStoryDispatchMode({
     };
   }
 
+  // Past the topology guard a sibling may be dispatched concurrently, so the
+  // router's session is not available to anyone. The shape is still derived and
+  // returned on `route` — ceremony and reporting read it — but it decides
+  // nothing here: both shapes dispatch as a sub-agent.
   const route = deriveStoryRouteFromBody(body, {
     injectedRules,
     selectSensitivePathClassesFn,
   });
-  if (route.route === 'lite') {
-    return {
-      mode: 'inline',
-      reasons: [
-        `lite-shaped Story — execute deliver-story inline; no story-worker or acceptance-critic sub-agent dispatch (close gates unchanged): ${route.reasons[0]}`,
-        hintNote,
-      ],
-      route,
-    };
-  }
-  return {
-    mode: 'subagent',
-    reasons: [`full-shaped Story — ${route.reasons[0]}`, hintNote],
-    route,
-  };
+  const shapeNote =
+    route.route === 'lite'
+      ? `lite-shaped Story in a multi-Story run — the shape is inline-eligible but the router's session is not: a concurrent sibling would have to share it, racing worktrees and branch refs; sub-agent dispatch (${route.reasons[0]})`
+      : `full-shaped Story — ${route.reasons[0]}`;
+  return { mode: 'subagent', reasons: [shapeNote, hintNote], route };
 }

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -317,21 +317,24 @@ export function buildStoriesEnvelope({
   const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
   return {
     kind: 'stories',
-    // `dispatchMode` (Story #4722): the resolver derives the per-Story
-    // execution mode from the fetched Story BODY's own shape (the shared
-    // shape function in `complexity-gate.js`) so `/deliver` reads one field —
-    // `inline` (lite-shaped: no story-worker / acceptance-critic sub-agent
-    // boots) or `subagent` (everything else, the conservative default). The
-    // `route::lite` label is a human-visible hint only, never the control
-    // signal: a lost label cannot misroute delivery. Model-side fan-out
-    // only; close gates are untouched.
+    // `dispatchMode` (Story #4722, #4736, #4829): the resolver reports the
+    // per-Story execution mode so `/deliver` reads one field — `inline` (run
+    // deliver-story in the router's own session: no story-worker /
+    // acceptance-critic sub-agent boots) or `subagent` (the conservative
+    // default). Model-side fan-out only; close gates are untouched.
     //
-    // `storyCount` (Story #4736) carries the run's topology into that same
-    // decision: a run resolving exactly ONE Story is inline whatever its
-    // shape, because the isolation a sub-agent buys only matters against a
-    // concurrently-dispatched sibling. It is the resolved set size — not the
-    // undelivered remainder — so the mode a caller reads for a given `--ids`
-    // list never changes as siblings land mid-run.
+    // `storyCount` is the premise that decides it, and it is this call site's
+    // load-bearing argument: `inline` names the router's ONE session, so it is
+    // granted only to a run resolving exactly ONE Story, which has no
+    // concurrent sibling to share that session with. Passing the resolved set
+    // size here is therefore what makes the envelope self-consistent with the
+    // ready set `stories-wave-tick.js` computes from the same `dag`: a set of
+    // more than one can never come back with a Story claiming the session
+    // (Story #4829 — it previously could, whenever the body was lite-shaped).
+    // It is the resolved set size, NOT the undelivered remainder, so the mode
+    // a caller reads for a given `--ids` list never changes as siblings land
+    // mid-run. The `route::lite` label is a human-visible hint only, never the
+    // control signal.
     stories: sorted.map(({ id, title, body, url, labels, state }) => ({
       id,
       title,

package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js

@@ -0,0 +1,222 @@
+/**
+ * review-providers/degraded-gates.js — the review's "a gate did not run"
+ * channel (Story #4839).
+ *
+ * ## The defect this closes
+ *
+ * Story #4699 correctly decided that a tool which **could not execute** is an
+ * operational degradation, not a code finding: it is routed to friction
+ * telemetry so severity tiers keep reflecting code findings only. What #4699
+ * did not add was any *other* channel, so the review's own verdict became
+ * unable to distinguish "lint ran and found nothing" from "lint never ran" —
+ * both rendered `✅ No findings` with an all-zero severity tally, and the close
+ * pipeline read the second as the first. A gate that reports success when it
+ * did not run is worse than no gate, because it is trusted.
+ *
+ * This module is that missing channel. A degradation travels **beside** the
+ * `Finding[]`, never inside it:
+ *
+ *   - it never becomes a `Finding`, so `countBySeverity` is untouched and no
+ *     execution failure can appear as a critical / high / medium (or even a
+ *     suggestion) — #4699's intent survives intact;
+ *   - it is rendered as its own section in the structured comment, and it
+ *     suppresses the false `✅ No findings` claim;
+ *   - it is carried on the `runCodeReview` envelope as `degraded` /
+ *     `degradations[]`, so the close pipeline sees it too.
+ *
+ * ## Report, not block — and why
+ *
+ * A degraded gate is reported loudly and does **not** halt the close. The close
+ * pipeline already runs the canonical `npm run lint` as a hard
+ * close-validation gate *before* the review phase; the review's scoped lint is
+ * a second, narrower read of the same surface. Failing a merge because a
+ * *secondary* read of an already-gated surface could not start would block
+ * delivery on an operational condition the hard gate has already covered. What
+ * was actually broken was the silence, so the fix is to make the silence
+ * impossible: every surface that reads the review outcome now states the
+ * degradation explicitly. Escalating to a block is a one-line change here if
+ * the operator posture ever needs it.
+ */
+
+/**
+ * @typedef {object} GateDegradation
+ * @property {string} tool     Emitter (e.g. `native-review-lint`).
+ * @property {string} gate     Gate that degraded (e.g. `scoped-lint`).
+ * @property {string} surface  Sub-surface that could not run (e.g. `markdownlint`).
+ * @property {string} reason   Machine-readable reason code.
+ */
+
+/**
+ * Pure: keep only well-formed degradation records. A misbehaving provider must
+ * not be able to corrupt the rendered comment or the envelope.
+ *
+ * @param {unknown} input
+ * @returns {GateDegradation[]}
+ */
+export function normalizeDegradations(input) {
+  if (!Array.isArray(input)) return [];
+  const out = [];
+  for (const d of input) {
+    if (!d || typeof d !== 'object') continue;
+    const surface = typeof d.surface === 'string' ? d.surface : null;
+    const reason = typeof d.reason === 'string' ? d.reason : null;
+    if (surface === null || reason === null) continue;
+    out.push({
+      tool: typeof d.tool === 'string' ? d.tool : 'unknown',
+      gate: typeof d.gate === 'string' ? d.gate : 'unknown',
+      surface,
+      reason,
+    });
+  }
+  return out;
+}
+
+/**
+ * Feature-detect a provider's degradation channel, mirroring how
+ * `getPromptMessages` is feature-detected. Providers predating this contract
+ * carry no `getDegradations`, so the empty array keeps their output byte-stable;
+ * a throw degrades to empty (observability must never fail a review).
+ *
+ * MUST be called **after** `runReview` — a provider records its degradations
+ * during the run.
+ *
+ * @param {{ getDegradations?: Function }} reviewProvider
+ * @param {{ warn?: Function }} [logger]
+ * @returns {Promise<GateDegradation[]>}
+ */
+export async function collectProviderDegradations(reviewProvider, logger) {
+  if (typeof reviewProvider?.getDegradations !== 'function') return [];
+  try {
+    return normalizeDegradations(await reviewProvider.getDegradations());
+  } catch (err) {
+    logger?.warn?.(
+      `[code-review] getDegradations threw; treating as none. ${
+        err?.message ?? err
+      }`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Pure: one-line operator-facing summary of the degraded gates, for progress
+ * output and comment tallies. Empty input renders `none` so the field is always
+ * present — a missing degradation line must never be read as "no degradation".
+ *
+ * @param {ReadonlyArray<GateDegradation>} degradations
+ * @returns {string}
+ */
+export function summarizeDegradations(degradations) {
+  const rows = normalizeDegradations(degradations);
+  if (rows.length === 0) return 'none';
+  return rows.map((d) => `${d.gate}/${d.surface} (${d.reason})`).join(', ');
+}
+
+/**
+ * Pure: the `{ degraded, degradations }` pair every outcome envelope carries, so
+ * a caller adds the channel by spreading one helper rather than restating the
+ * derivation (and cannot ship `degradations` without `degraded`).
+ *
+ * @param {unknown} degradations
+ * @returns {{ degraded: boolean, degradations: GateDegradation[] }}
+ */
+export function degradationEnvelope(degradations) {
+  const rows = normalizeDegradations(degradations);
+  return { degraded: rows.length > 0, degradations: rows };
+}
+
+/**
+ * Merge the degraded-gate records of every inline chain entry that carries the
+ * channel. A provider predating the contract contributes nothing; a throw is
+ * logged and skipped, because a chain must never lose a "this gate did not run"
+ * signal *or* fail a review over reporting one.
+ *
+ * @param {ReadonlyArray<{ name: string, provider: { getDegradations?: Function } }>} entries
+ * @param {{ warn?: Function }} [logger]
+ * @returns {Promise<GateDegradation[]>}
+ */
+export async function mergeChainDegradations(entries, logger) {
+  const merged = [];
+  for (const entry of entries) {
+    if (typeof entry.provider?.getDegradations !== 'function') continue;
+    try {
+      merged.push(
+        ...normalizeDegradations(await entry.provider.getDegradations()),
+      );
+    } catch (err) {
+      logger?.warn?.(
+        `[code-review] Inline provider "${entry.name}" getDegradations threw; skipping. ${
+          err?.message ?? err
+        }`,
+      );
+    }
+  }
+  return merged;
+}
+
+/**
+ * Pure: the header field naming how many gates did not run. Empty when the
+ * review was healthy, so a healthy body stays byte-identical to pre-#4839.
+ *
+ * @param {ReadonlyArray<GateDegradation>} degraded  Already normalized.
+ * @returns {string[]}
+ */
+export function renderDegradedHeaderLines(degraded) {
+  if (degraded.length === 0) return [];
+  return [`**Degraded gates**: ${degraded.length} (did not run)`];
+}
+
+/**
+ * Pure: the "nothing surfaced" block. This is the exact sentence the defect
+ * turned into a lie — with a degraded gate present, an all-zero tally is not a
+ * clean verdict and must not read like one.
+ *
+ * @param {ReadonlyArray<GateDegradation>} degraded  Already normalized.
+ * @returns {string[]}
+ */
+export function renderNoFindingsBlock(degraded) {
+  if (degraded.length === 0) {
+    return [
+      '### ✅ No findings',
+      '',
+      'No issues surfaced by the review provider.',
+    ];
+  }
+  return [
+    `### ⚠️ No findings — ${degraded.length} gate(s) did not run`,
+    '',
+    'The gates that ran surfaced no issues. This review does **not** vouch ' +
+      'for the degraded surface(s) listed above.',
+  ];
+}
+
+/**
+ * Pure: render the "Degraded Gates" section of the structured comment. Returns
+ * an empty array when nothing degraded, so a healthy review's body stays
+ * byte-identical to the pre-#4839 output.
+ *
+ * @param {ReadonlyArray<GateDegradation>} degradations
+ * @returns {string[]} markdown lines
+ */
+export function renderDegradedGatesSection(degradations) {
+  const rows = normalizeDegradations(degradations);
+  if (rows.length === 0) return [];
+  const lines = [
+    `### ⚠️ Degraded Gates (${rows.length})`,
+    '',
+    'The following review gate(s) **did not run**. Their surface is',
+    'unreviewed — an all-zero finding tally below does not vouch for it.',
+    '',
+  ];
+  for (const d of rows) {
+    lines.push(
+      `- \`${d.gate}\` → \`${d.surface}\` could not execute — ${d.reason} (emitter: \`${d.tool}\`).`,
+    );
+  }
+  lines.push('');
+  lines.push(
+    'Verify with the canonical `npm run lint` before trusting this review.',
+  );
+  lines.push('');
+  return lines;
+}

package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js

@@ -15,6 +15,13 @@
  * @typedef {import('./types.js').Severity} Severity
  */
 
+import {
+  normalizeDegradations,
+  renderDegradedGatesSection,
+  renderDegradedHeaderLines,
+  renderNoFindingsBlock,
+} from './degraded-gates.js';
+
 /**
  * Canonical severity ordering. The render output always lists the
  * severity-tier counts in this order and emits the per-finding sections
@@ -115,6 +122,12 @@ export function renderManualPromptsSection(messages) {
  * manual-prompt provider output; rendered as a trailing section when
  * non-empty.
  *
+ * Story #4839 — an optional `degradations` field names review gates that could
+ * not execute. They are **not** findings and never enter `countBySeverity`; they
+ * render as their own section and suppress the unqualified "no findings" claim,
+ * because a review that could not run a gate has not established that the
+ * gate's surface is clean.
+ *
  * @param {{
  *   ticketId: number,
  *   baseRef: string,
@@ -122,6 +135,7 @@ export function renderManualPromptsSection(messages) {
  *   findings: ReadonlyArray<Finding>,
  *   provider?: string,
  *   promptMessages?: ReadonlyArray<string>,
+ *   degradations?: ReadonlyArray<object>,
  * }} input
  * @returns {string}
  */
@@ -131,6 +145,7 @@ export function renderFindings(input) {
   const counts = countBySeverity(findings);
   const totalKnown =
     counts.critical + counts.high + counts.medium + counts.suggestion;
+  const degraded = normalizeDegradations(input.degradations);
 
   const providerLine = provider
     ? `**Provider**: \`${provider}\``
@@ -142,6 +157,7 @@ export function renderFindings(input) {
     `**Comparison**: \`${baseRef}\` … \`${headRef}\``,
     providerLine,
     `**Findings**: ${totalKnown}`,
+    ...renderDegradedHeaderLines(degraded),
     '',
     '### 📦 Severity Tier Counts',
     '',
@@ -150,12 +166,11 @@ export function renderFindings(input) {
       return `- ${meta.emoji} ${meta.label}: ${counts[sev]}`;
     }),
     '',
+    ...renderDegradedGatesSection(degraded),
   ];
 
   if (totalKnown === 0) {
-    lines.push('### ✅ No findings');
-    lines.push('');
-    lines.push('No issues surfaced by the review provider.');
+    lines.push(...renderNoFindingsBlock(degraded));
   } else {
     for (const sev of SEVERITY_ORDER) {
       const tierFindings = findings.filter((f) => f && f.severity === sev);