mandrel 2.21.0 → 2.22.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,6 +552,7 @@ 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
@@ -570,7 +573,7 @@ async function executeFollowUpRollup({
     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 +585,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 +604,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 +619,34 @@ async function executeFollowUpRollup({
     signalCount: signals.length,
     storyCount: stories.length,
     filed: graduated.filed?.length ?? 0,
+    // 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 +743,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 +756,7 @@ export async function runPlanRunEpilogue({
   cwd = process.cwd(),
   git = { gitSpawn },
   selectAuditsFn = selectAudits,
+  graduateFn = graduateRetroProposals,
 } = {}) {
   const plan = planRunEpilogue({ planRunId, stories });
   if (!plan.applicable) {
@@ -741,6 +790,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}).`;
 }
 
 /**

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

@@ -9,11 +9,15 @@
  * @module lib/orchestration/story-follow-ups
  */
 
+import { signalsFile } from '../config/temp-paths.js';
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { DEFAULT_FRAMEWORK_REPO } from '../github/framework-repo.js';
 import { Logger } from '../Logger.js';
 import { normalizeGatheredSignal } from '../observability/runtime-friction.js';
-import { forEachLine } from '../observability/signals-writer.js';
+import {
+  forEachLine,
+  forEachSignalStreamLine,
+} from '../observability/signals-writer.js';
 import {
   composeRoutedProposals,
   deriveUnresolvedBlockedEvents,
@@ -83,8 +87,55 @@ export async function gatherStoryFrictionSignals(storyId, config) {
 }
 
 /**
- * Gather friction signals across every Story in a run, for the run-scoped
- * roll-up.
+ * Identity of one physical signal row, for de-duplication.
+ *
+ * `eventId` is minted by every producer (`diagnose-friction.js` and
+ * `runtime-friction.js` both `crypto.randomUUID()` it), so it is the primary
+ * key. A row predating the field falls back to its physical `file:line`,
+ * which is equally stable — the same row read through two passes over the
+ * same tree yields the same coordinates.
+ *
+ * @param {unknown} parsed
+ * @param {string} file
+ * @param {number} lineNumber
+ * @returns {string}
+ */
+function signalIdentity(parsed, file, lineNumber) {
+  const eventId =
+    parsed !== null &&
+    typeof parsed === 'object' &&
+    typeof (/** @type {Record<string, unknown>} */ (parsed).eventId) ===
+      'string'
+      ? /** @type {string} */ (
+          /** @type {Record<string, unknown>} */ (parsed).eventId
+        ).trim()
+      : '';
+  return eventId.length > 0 ? `event:${eventId}` : `row:${file}:${lineNumber}`;
+}
+
+/**
+ * Gather friction signals for the run-scoped roll-up, over the **whole
+ * surviving recurrence window** rather than the run's own Stories
+ * (Story #4824).
+ *
+ * The recurrence threshold in `retro-proposals.js` is ≥ 2 occurrences, and
+ * the window it was measured over was one run's Story ids. A defect that
+ * fires exactly **once per Story** — which is what a systemic framework
+ * defect looks like — therefore scored 1 on every Story and was discarded as
+ * a singleton, forever. Eighteen consecutive Stories filed nothing.
+ *
+ * So the gather reduces over every `signals.ndjson` still present under the
+ * configured temp root: `<tempRoot>/standalone/stories/story-<sid>/` and
+ * `<tempRoot>/run-<eid>/stories/story-<sid>/`. Temp-tree auto-purge
+ * shortening that window is acceptable — a short window under-counts, and
+ * therefore fails toward *not* filing, which is the safe direction.
+ *
+ * The run's own Stories are still gathered explicitly first. The discovery
+ * walk resolves through the identical path helpers, so it is provably a
+ * superset; the explicit pass makes "never fewer signals than before" a
+ * property of the code rather than of an argument about path resolution.
+ * {@link signalIdentity} de-duplicates the overlap, so one event can never be
+ * counted twice and inflate a singleton into a fabricated recurrence.
  *
  * Homed beside {@link gatherStoryFrictionSignals} on purpose: the two used to
  * be independent copies of the same loop in two modules, and they drifted in
@@ -94,17 +145,39 @@ export async function gatherStoryFrictionSignals(storyId, config) {
  * Unusable ids are skipped rather than throwing — a roll-up must not fail the
  * epilogue over one malformed entry.
  *
- * @param {Array<number|string>} storyIds
+ * @param {Array<number|string>} storyIds The run's own Stories.
  * @param {object} [config]
  * @returns {Promise<Array<{ category: string, source: 'framework'|'consumer', storyId: number, details: object }>>}
  */
 export async function gatherRunFrictionSignals(storyIds, config) {
   const signals = [];
+  const seen = new Set();
+  const take = (parsed, fallbackStoryId, identity) => {
+    if (seen.has(identity)) return;
+    seen.add(identity);
+    const signal = normalizeGatheredSignal(parsed, fallbackStoryId);
+    if (signal) signals.push(signal);
+  };
+
   for (const raw of Array.isArray(storyIds) ? storyIds : []) {
     const sid = Number(raw);
     if (!Number.isInteger(sid) || sid <= 0) continue;
-    signals.push(...(await gatherStoryFrictionSignals(sid, config)));
+    const file = signalsFile(null, sid, config);
+    await forEachLine(
+      null,
+      sid,
+      (parsed, lineNumber) =>
+        take(parsed, sid, signalIdentity(parsed, file, lineNumber)),
+      config,
+    );
   }
+
+  await forEachSignalStreamLine(
+    (parsed, { storyId, file, lineNumber }) =>
+      take(parsed, storyId, signalIdentity(parsed, file, lineNumber)),
+    config,
+  );
+
   return signals;
 }
 
@@ -151,14 +224,187 @@ function renderEmptyRollupLines(storyCount) {
   ];
 }
 
+/**
+ * Skip reasons that are a deliberate outcome rather than a broken loop. A
+ * roll-up whose every proposal was skipped for one of these filed nothing
+ * *on purpose*; anything else is the loop failing quietly.
+ */
+const BENIGN_SKIP_REASONS = new Set([
+  'already-filed',
+  'toggle-disabled',
+  'cross-repo-deferred',
+  'cap-reached',
+  'no-actionable-proposals',
+]);
+
+/**
+ * Summarize a category corpus for the "name what you saw" lines. Pure.
+ *
+ * @param {Array<{ category?: string }>} signals
+ * @returns {Array<{ category: string, occurrences: number }>}
+ */
+export function summarizeSignalCategories(signals) {
+  const counts = new Map();
+  for (const sig of Array.isArray(signals) ? signals : []) {
+    if (sig === null || typeof sig !== 'object') continue;
+    const category =
+      typeof sig.category === 'string' ? sig.category.trim() : '';
+    if (category.length === 0) continue;
+    counts.set(category, (counts.get(category) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([category, occurrences]) => ({ category, occurrences }))
+    .sort((a, b) => a.category.localeCompare(b.category));
+}
+
+/**
+ * Classify what a roll-up's own numbers say about it — the reporting-layer
+ * assertion Story #4828 adds. Pure, so the run epilogue's step result and the
+ * rendered comment cannot disagree about whether a roll-up succeeded.
+ *
+ * Two suspect shapes, both of which previously rendered as success:
+ *
+ *   - `zeroProposals` — signals were gathered and **nothing** came out, not
+ *     even a below-threshold row. That is the third instance of the failure
+ *     mode Story #4578 fixed for the zero-signal case and Story #4824 for the
+ *     all-discarded case: an all-empty routed result is silence, and a routing
+ *     regression is exactly what it looks like.
+ *   - `unfiledProposals` — proposals cleared the threshold and none were
+ *     filed for a reason that is not a deliberate one. This is what actually
+ *     happened in Story #4828: `gh issue create` rejected every call over an
+ *     absent label, the error landed in a bucket nobody rendered, and the
+ *     roll-up reported `filed: 0`.
+ *
+ * @param {object} args
+ * @param {number} args.signalCount
+ * @param {number} args.proposalCount   framework + consumer
+ * @param {number} args.discardedCount
+ * @param {number} args.filedCount
+ * @param {string[]} [args.filingErrors]
+ * @param {Array<{ reason?: string }>} [args.filingSkipped]
+ * @returns {{ zeroProposals: boolean, unfiledProposals: boolean, blockingSkipReasons: string[] }}
+ */
+export function assessRollupOutcome({
+  signalCount,
+  proposalCount,
+  discardedCount,
+  filedCount,
+  filingErrors = [],
+  filingSkipped = [],
+}) {
+  const blockingSkipReasons = [
+    ...new Set(
+      (Array.isArray(filingSkipped) ? filingSkipped : [])
+        .map((entry) => (typeof entry?.reason === 'string' ? entry.reason : ''))
+        .filter((reason) => reason && !BENIGN_SKIP_REASONS.has(reason)),
+    ),
+  ].sort();
+  const errors = Array.isArray(filingErrors) ? filingErrors : [];
+  return {
+    zeroProposals:
+      signalCount > 0 && proposalCount === 0 && discardedCount === 0,
+    unfiledProposals:
+      proposalCount > 0 &&
+      filedCount === 0 &&
+      (errors.length > 0 || blockingSkipReasons.length > 0),
+    blockingSkipReasons,
+  };
+}
+
+/**
+ * Render the "N signals in, zero proposals out" warning (Story #4828).
+ *
+ * @param {number} signalCount
+ * @param {Array<{ category: string, occurrences: number }>} categories
+ * @returns {string[]}
+ */
+function renderZeroProposalLines(signalCount, categories) {
+  const named =
+    categories.length > 0
+      ? categories.map((c) => `\`${c.category}\` ×${c.occurrences}`).join(', ')
+      : '_none — every gathered signal carried an unusable category_';
+  return [
+    `> ⚠️ **${signalCount} friction signals gathered, 0 proposals produced — a routing outcome, not a clean run.**`,
+    `> Categories seen: ${named}.`,
+    '> Nothing cleared the actionable threshold AND nothing was recorded below',
+    '> it, so every signal was netted out as recovered or dropped in routing.',
+    '> A regression in routing renders byte-identically to this, which is why',
+    '> the roll-up states it rather than rendering silence.',
+  ];
+}
+
+/**
+ * Render the "proposals cleared the threshold but none were filed" warning
+ * (Story #4828).
+ *
+ * @param {number} proposalCount
+ * @param {string[]} filingErrors
+ * @param {string[]} blockingSkipReasons
+ * @returns {string[]}
+ */
+function renderUnfiledProposalLines(
+  proposalCount,
+  filingErrors,
+  blockingSkipReasons,
+) {
+  const lines = [
+    `> ⚠️ **${proposalCount} actionable proposal(s) reached the filer and none were filed.**`,
+    '> Auto-file is on, so this is the feedback loop failing, not declining.',
+  ];
+  if (blockingSkipReasons.length > 0) {
+    lines.push(`> Skipped: ${blockingSkipReasons.join(', ')}.`);
+  }
+  for (const error of filingErrors) {
+    lines.push(`> ${error}`);
+  }
+  return lines;
+}
+
+/**
+ * Render one discarded (below-threshold) roll-up row (Story #4824).
+ *
+ * The pre-#4824 row was `` `category` ×N `` and nothing else. That is exactly
+ * how a defect firing once per Story stayed invisible for eighteen
+ * consecutive Stories: an operator reading "×1" cannot tell a one-off from a
+ * systemic defect whose window was too narrow to see it recur. The row now
+ * names the emitting tools, the bucket fingerprint, and the number of
+ * distinct Stories it spans — the cross-run count the widened recurrence
+ * window produces.
+ *
+ * Every added field is optional so a caller passing a hand-built proposals
+ * object (or an older persisted one) still renders.
+ *
+ * @param {{ category: string, occurrences: number, tools?: string[], fingerprint?: string, storyCount?: number }} item
+ * @returns {string}
+ */
+function renderDiscardedItem(item) {
+  const parts = [`\`${item.category}\` ×${item.occurrences}`];
+  if (Number.isInteger(item.storyCount) && item.storyCount > 0) {
+    const plural = item.storyCount === 1 ? 'Story' : 'Stories';
+    parts.push(`across ${item.storyCount} ${plural}`);
+  }
+  if (Array.isArray(item.tools) && item.tools.length > 0) {
+    parts.push(`via ${item.tools.map((t) => `\`${t}\``).join(', ')}`);
+  }
+  if (typeof item.fingerprint === 'string' && item.fingerprint.length > 0) {
+    parts.push(`fingerprint \`${item.fingerprint}\``);
+  }
+  return parts.join(' — ');
+}
+
 /**
  * @param {{
  *   storyId: number,
  *   proposals: object,
  *   graduated: object,
  *   storyCount?: number,
+ *   signalCount?: number,
+ *   categories?: Array<{ category: string, occurrences: number }>,
  * }} args - `storyCount` (default 1) is how many Stories the roll-up spans;
  *   it decides whether an empty result reads as quiet or as a flagged claim.
+ *   `signalCount` / `categories` (Story #4828) are what the roll-up actually
+ *   gathered, so a zero-proposal or zero-filed outcome can name its own
+ *   corpus instead of rendering as a clean run.
  * @returns {string}
  */
 export function buildFollowUpsCommentBody({
@@ -166,17 +412,37 @@ export function buildFollowUpsCommentBody({
   proposals,
   graduated,
   storyCount = 1,
+  signalCount = 0,
+  categories = [],
 }) {
   const filed = Array.isArray(graduated?.filed) ? graduated.filed : [];
   const framework = proposals?.framework ?? [];
   const consumer = proposals?.consumer ?? [];
   const discarded = proposals?.discarded ?? [];
+  const outcome = assessRollupOutcome({
+    signalCount,
+    proposalCount: framework.length + consumer.length,
+    discardedCount: discarded.length,
+    filedCount: filed.length,
+    filingErrors: graduated?.errors,
+    filingSkipped: graduated?.skipped,
+  });
   const lines = [
     '### follow-ups',
     '',
     `Actionable follow-ups captured from Story #${storyId} after merge.`,
     '',
   ];
+  if (outcome.unfiledProposals) {
+    lines.push(
+      ...renderUnfiledProposalLines(
+        framework.length + consumer.length,
+        Array.isArray(graduated?.errors) ? graduated.errors : [],
+        outcome.blockingSkipReasons,
+      ),
+      '',
+    );
+  }
   if (filed.length > 0) {
     lines.push('**Filed**');
     for (const item of filed) {
@@ -198,9 +464,9 @@ export function buildFollowUpsCommentBody({
     lines.push('');
   }
   if (discarded.length > 0) {
-    lines.push('**Single-occurrence (not filed)**');
+    lines.push('**Below threshold (not filed)**');
     for (const item of discarded) {
-      lines.push(`- ${item.source}: \`${item.category}\` ×${item.occurrences}`);
+      lines.push(`- ${item.source}: ${renderDiscardedItem(item)}`);
     }
     lines.push('');
   }
@@ -210,7 +476,14 @@ export function buildFollowUpsCommentBody({
     consumer.length === 0 &&
     discarded.length === 0
   ) {
-    lines.push(...renderEmptyRollupLines(storyCount));
+    // Story #4828 — "no proposals" has two readings, and only one of them is
+    // a quiet run. Signals gathered but nothing routed is the third instance
+    // of the silence Stories #4578 and #4824 each fixed once.
+    lines.push(
+      ...(outcome.zeroProposals
+        ? renderZeroProposalLines(signalCount, categories)
+        : renderEmptyRollupLines(storyCount)),
+    );
     lines.push('');
   }
   lines.push('```json');
@@ -219,9 +492,23 @@ export function buildFollowUpsCommentBody({
       {
         storyId,
         storyCount,
+        // Story #4828 — the corpus the roll-up actually read. Without it a
+        // reader cannot tell "0 proposals because nothing recurred" from
+        // "0 proposals because routing broke".
+        signalCount,
+        categories,
         framework: framework.map((i) => i.category),
         consumer: consumer.map((i) => i.category),
-        discarded: discarded.map((i) => i.category),
+        // Story #4824 — the machine-readable twin of the row above. A bare
+        // category list could not distinguish a genuine one-off from a
+        // recurrence the window was too narrow to see, so the count, the
+        // cross-Story span, and the shape fingerprint ride along.
+        discarded: discarded.map((i) => ({
+          category: i.category,
+          occurrences: i.occurrences,
+          storyCount: i.storyCount ?? null,
+          fingerprint: i.fingerprint ?? null,
+        })),
         filed: filed.map((i) => ({
           category: i.category,
           url: i.url ?? null,
@@ -234,7 +521,13 @@ export function buildFollowUpsCommentBody({
           filed.length === 0 &&
           framework.length === 0 &&
           consumer.length === 0 &&
-          discarded.length === 0,
+          discarded.length === 0 &&
+          signalCount === 0,
+        // Story #4828 — the two remaining shapes that used to render as
+        // success. Machine-readable twins of the warning prose above.
+        zeroProposalSuspect: outcome.zeroProposals,
+        unfiledProposalSuspect: outcome.unfiledProposals,
+        filingErrors: Array.isArray(graduated?.errors) ? graduated.errors : [],
       },
       null,
       2,
@@ -308,6 +601,8 @@ export async function captureStoryFollowUps({
       storyId: sid,
       proposals,
       graduated,
+      signalCount: signals.length,
+      categories: summarizeSignalCategories(signals),
     });
     await upsertStructuredComment(provider, sid, FOLLOW_UPS_COMMENT_TYPE, body);
     progress?.(