mandrel 2.21.0 → 2.23.0

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -21,9 +21,11 @@ import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
 import { composeRoutedProposals } from './retro-proposals.js';
 import {
+  assessRollupOutcome,
   buildFollowUpsCommentBody,
   gatherRunFrictionSignals,
   resolveFollowUpRepos,
+  summarizeSignalCategories,
 } from './story-follow-ups.js';
 import { upsertStructuredComment } from './ticketing.js';
 
@@ -550,27 +552,35 @@ async function executeFollowUpRollup({
   provider,
   config,
   cwd,
+  graduateFn = graduateRetroProposals,
 }) {
   // Shared with the story-scoped gather (Story #4649): `storyId` + `details`
   // are what the composer's recovery-netting keys on, and two hand-rolled
   // copies of this loop are how they got dropped in the first place.
-  const signals = await gatherRunFrictionSignals(stories, config);
+  const { signals, window: frictionWindow } = await gatherRunFrictionSignals(
+    stories,
+    config,
+  );
   const repos = resolveFollowUpRepos(config);
   const primaryId = Number(stories[0]);
+  // Story #4850 — `runToken` and `anchorStoryIds` are INPUTS. This used to
+  // compose with the primary Story's numeric id standing in for the run and
+  // then rewrite the rendered title/body by regex over a `plan-run \d+`
+  // substring, which meant the composer's own wording could not be changed
+  // without silently breaking the patch. `anchorStoryIds` is what lets the
+  // composer tell a corpus confined to this run from one spanning the whole
+  // surviving window, so it never titles the latter as if it were the former.
   const proposals = composeRoutedProposals({
     anchorId: Number.isInteger(primaryId) ? primaryId : 1,
     anchorKind: 'run',
+    runToken: String(planRunId ?? ''),
+    anchorStoryIds: stories,
     frameworkRepo: repos.frameworkRepo,
     consumerRepo: repos.consumerRepo,
     signals,
     unresolvedBlockedEvents: [],
   });
-  // Patch titles to mention the plan-run token (anchorKind run uses numeric id).
-  for (const item of [...proposals.framework, ...proposals.consumer]) {
-    item.title = item.title.replace(/plan-run \d+/, `plan-run ${planRunId}`);
-    item.body = item.body.replace(/plan-run \d+/g, `plan-run ${planRunId}`);
-  }
-  const graduated = await graduateRetroProposals({
+  const graduated = await graduateFn({
     epicId: primaryId,
     provider,
     config,
@@ -582,6 +592,16 @@ async function executeFollowUpRollup({
     routedProposals: proposals,
     cwd,
   });
+  const categories = summarizeSignalCategories(signals);
+  const proposalCount = proposals.framework.length + proposals.consumer.length;
+  const outcome = assessRollupOutcome({
+    signalCount: signals.length,
+    proposalCount,
+    discardedCount: proposals.discarded.length,
+    filedCount: graduated.filed?.length ?? 0,
+    filingErrors: graduated.errors,
+    filingSkipped: graduated.skipped,
+  });
   if (Number.isInteger(primaryId) && primaryId > 0) {
     const body = buildFollowUpsCommentBody({
       storyId: primaryId,
@@ -591,6 +611,10 @@ async function executeFollowUpRollup({
       // render as a flagged claim ("0 signals across N Stories") rather than
       // as "nothing to follow up".
       storyCount: stories.length,
+      // Story #4828 — and the corpus is what lets a zero-proposal or
+      // zero-filed roll-up name what it saw instead of rendering as clean.
+      signalCount: signals.length,
+      categories,
     }).replace(
       `from Story #${primaryId}`,
       `from plan-run \`${planRunId}\` (primary Story #${primaryId})`,
@@ -602,6 +626,39 @@ async function executeFollowUpRollup({
     signalCount: signals.length,
     storyCount: stories.length,
     filed: graduated.filed?.length ?? 0,
+    // Story #4850 — the recurrence window the gather actually applied, and what
+    // it dropped. `signalCount` alone cannot distinguish "the window is bounded
+    // at 30 days and 40 rows aged out" from "nothing older exists", and an
+    // operator triaging a roll-up needs to know which corpus produced it.
+    frictionWindow,
+    // Story #4828 — everything below is what the roll-up saw and what became
+    // of it. The pre-#4828 result reported `signalCount` and `filed` and
+    // nothing in between, so nine signals routing into one proposal whose
+    // every filing attempt errored rendered as `{signalCount: 9, filed: 0,
+    // discarded: []}` — arithmetically consistent, and indistinguishable from
+    // a run with nothing to do.
+    proposalCount,
+    // The categories the corpus actually contained, so a zero-proposal
+    // roll-up names its own input rather than asserting emptiness.
+    categories,
+    filingErrors: Array.isArray(graduated.errors) ? graduated.errors : [],
+    filingSkipped: outcome.blockingSkipReasons,
+    // Signals in, nothing out — not even a below-threshold row.
+    zeroProposalSuspect: outcome.zeroProposals,
+    // Proposals cleared the threshold and the filer produced none of them.
+    unfiledProposalSuspect: outcome.unfiledProposals,
+    // Story #4824 — a roll-up that discards every candidate must still name
+    // what it discarded. Rendering that as "nothing to follow up" is how a
+    // defect recurring once per Story survived eighteen consecutive Stories.
+    // Surfaced on the step result so the CLI need not regex the comment body.
+    discarded: proposals.discarded.map((item) => ({
+      category: item.category,
+      occurrences: item.occurrences,
+      source: item.source,
+      storyCount: item.storyCount ?? null,
+      tools: item.tools ?? [],
+      fingerprint: item.fingerprint ?? null,
+    })),
     // Story #4578 — zero signals across a multi-Story run is a claim, not a
     // clean bill of health. Surfaced on the step result so the CLI can warn
     // the operator without re-deriving it from the comment prose.
@@ -698,6 +755,9 @@ async function executeSiblingCoherence({ planRunId, stories, provider }) {
  * @param {string} [args.cwd]
  * @param {{ gitSpawn: Function }} [args.git] - Injection seam for tests.
  * @param {typeof selectAudits} [args.selectAuditsFn] - Injection seam for tests.
+ * @param {typeof graduateRetroProposals} [args.graduateFn] - Injection seam so
+ *   the roll-up's reporting layer can be asserted against a filer that fails
+ *   (Story #4828) without spawning a real `gh`.
  * @returns {Promise<object>}
  */
 export async function runPlanRunEpilogue({
@@ -708,6 +768,7 @@ export async function runPlanRunEpilogue({
   cwd = process.cwd(),
   git = { gitSpawn },
   selectAuditsFn = selectAudits,
+  graduateFn = graduateRetroProposals,
 } = {}) {
   const plan = planRunEpilogue({ planRunId, stories });
   if (!plan.applicable) {
@@ -741,6 +802,7 @@ export async function runPlanRunEpilogue({
             provider,
             config,
             cwd,
+            graduateFn,
           }),
         );
       } else if (step.kind === 'sibling-coherence') {

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

@@ -28,8 +28,13 @@
  */
 
 import { parsePrNumberFromUrl } from '../../../github-url.js';
+import { degradationEnvelope } from '../../review-providers/degraded-gates.js';
 import { runStoryReviewCore } from '../../story-close/phases/review-core.js';
 import { postStructuredComment } from '../../ticketing/state.js';
+import {
+  buildOutcomeTally,
+  formatReviewOutcomeLines,
+} from './review-outcome.js';
 
 /**
  * Extract the numeric PR ID from a `gh pr create` URL. The CLI returns a
@@ -62,13 +67,11 @@ export function buildStoryReviewCrossRefBody({
   prNumber,
   commentUrl,
   severity,
+  degradations,
 }) {
-  const tally =
-    `critical:${severity.critical} · high:${severity.high} · ` +
-    `medium:${severity.medium} · suggestion:${severity.suggestion}`;
   return (
     `🔬 Story-scope code review posted on PR [#${prNumber}](${prUrl}): ` +
-    `[view findings](${commentUrl}) — ${tally}.`
+    `[view findings](${commentUrl}) — ${buildOutcomeTally({ severity, degradations })}.`
   );
 }
 
@@ -116,6 +119,7 @@ async function postStoryReviewCrossRef({
       prNumber,
       commentUrl,
       severity,
+      degradations: result.degradations,
     });
     try {
       await postStructuredComment(provider, storyId, 'notification', body);
@@ -174,6 +178,8 @@ async function postStoryReviewCrossRef({
  *   severity?: { critical: number, high: number, medium: number, suggestion: number },
  *   posted?: boolean,
  *   postedCommentId?: number|null,
+ *   degraded?: boolean,
+ *   degradations?: Array<object>,
  *   crossRefPosted?: boolean,
  *   localLensReview?: object,
  * }>}
@@ -222,10 +228,13 @@ export async function runStoryScopeReview({
     medium: 0,
     suggestion: 0,
   };
-  progress(
-    'REVIEW',
-    `Findings — critical:${sev.critical} high:${sev.high} medium:${sev.medium} suggestion:${sev.suggestion}. Posted to PR #${prNumber}: ${result.posted}.`,
-  );
+  const outcome = formatReviewOutcomeLines({
+    severity: sev,
+    degradations: result.degradations,
+    prNumber,
+    posted: result.posted,
+  });
+  for (const line of outcome) progress('REVIEW', line);
 
   const crossRefPosted = await postStoryReviewCrossRef({
     provider,
@@ -242,6 +251,7 @@ export async function runStoryScopeReview({
     severity: sev,
     posted: result.posted,
     postedCommentId: result.postedCommentId ?? null,
+    ...degradationEnvelope(result.degradations),
     crossRefPosted,
     localLensReview: result.localLensReview,
   };

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

@@ -0,0 +1,66 @@
+/**
+ * phases/review-outcome.js — operator-facing rendering of the Story-scope
+ * review outcome (Story #4839).
+ *
+ * The review phase used to report a severity tally and nothing else, which made
+ * "every gate ran and found nothing" and "a gate never ran" render identically.
+ * Both surfaces the operator actually reads — the close progress stream and the
+ * cross-reference comment on the Story — now state the degraded gates
+ * explicitly, and always state them (as `none` when healthy) so an absent line
+ * can never be mistaken for a clean gate.
+ *
+ * A degraded gate is **reported, not blocking**: the canonical `npm run lint`
+ * close-validation gate has already covered this diff before the review phase
+ * runs, so failing the merge on a secondary read of an already-gated surface
+ * would cost delivery without buying coverage. The rationale for that posture
+ * lives with the channel itself in
+ * [`review-providers/degraded-gates.js`](../../review-providers/degraded-gates.js).
+ */
+
+import { summarizeDegradations } from '../../review-providers/degraded-gates.js';
+
+/**
+ * Pure: the tally suffix shared by the progress line and the cross-reference
+ * comment — severity counts plus the degraded-gate state.
+ *
+ * @param {{ severity: { critical: number, high: number, medium: number, suggestion: number }, degradations?: unknown }} args
+ * @returns {string}
+ */
+export function buildOutcomeTally({ severity, degradations }) {
+  return (
+    `critical:${severity.critical} · high:${severity.high} · ` +
+    `medium:${severity.medium} · suggestion:${severity.suggestion} · ` +
+    `degraded gates: ${summarizeDegradations(degradations)}`
+  );
+}
+
+/**
+ * Pure: the progress lines announcing a completed review. Always one line
+ * naming the tally; a second, explicitly-worded line when a gate did not run so
+ * the degradation cannot be skimmed past.
+ *
+ * @param {{
+ *   severity: { critical: number, high: number, medium: number, suggestion: number },
+ *   degradations?: unknown,
+ *   prNumber: number,
+ *   posted: boolean,
+ * }} args
+ * @returns {string[]}
+ */
+export function formatReviewOutcomeLines({
+  severity,
+  degradations,
+  prNumber,
+  posted,
+}) {
+  const tally = buildOutcomeTally({ severity, degradations });
+  const lines = [`Findings — ${tally}. Posted to PR #${prNumber}: ${posted}.`];
+  if (summarizeDegradations(degradations) !== 'none') {
+    lines.push(
+      '⚠️ Review ran DEGRADED — the surface(s) above were not reviewed. The close ' +
+        'is not blocked (the canonical `npm run lint` close gate already covered ' +
+        'this diff), but this review does not vouch for them.',
+    );
+  }
+  return lines;
+}

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

@@ -38,6 +38,7 @@
 
 import { Logger } from '../../../Logger.js';
 import { runCodeReview } from '../../code-review.js';
+import { summarizeDegradations } from '../../review-providers/degraded-gates.js';
 import { emitBlockedCloseResult } from '../emit-blocked.js';
 import { runLocalLensReview } from './local-lens-review.js';
 import { runStoryReviewCore } from './review-core.js';
@@ -86,7 +87,10 @@ function buildCodeReviewBlockedExtra({ storyId, reviewResult }) {
 function formatReviewSummary(reviewResult) {
   const { high, medium, suggestion } = resolveSeverity(reviewResult);
   const posted = reviewResult?.posted ?? false;
-  return `Review complete — high=${high} medium=${medium} suggestion=${suggestion} (posted=${posted}).`;
+  // Story #4839 — `degraded` is always stated: an absent degradation line must
+  // never be the way an operator concludes that every gate ran.
+  const degraded = summarizeDegradations(reviewResult?.degradations);
+  return `Review complete — high=${high} medium=${medium} suggestion=${suggestion} degraded=${degraded} (posted=${posted}).`;
 }
 
 /**