mandrel 2.51.0 → 2.53.0

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -95,6 +95,40 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
   REVIEW_BLOCK_OVERRIDDEN: 'review-block-overridden',
 });
 
+/**
+ * The friction category one light-path refusal files under.
+ *
+ * `LIGHT_SCOPE_REJECTED` alone used to be the category for every refusal, and
+ * the retro composer aggregates, de-duplicates and labels on the category
+ * string ALONE — so an empty-diff refusal and a `public-api` sensitive-path
+ * refusal landed in one bucket and filed one "recurred 2 times across 2
+ * Stories" follow-up whose two occurrences had nothing in common but the
+ * category (issue #5237; consumer Beestera/swarm-os#2408). The roll-up's shape
+ * fingerprint could not separate them either: it hashes detail KEYS, and every
+ * refusal carries an identical key set.
+ *
+ * Encoding the refusal class in the category is what splits them, and it
+ * splits them in every consumer at once — bucket aggregation, the graduator's
+ * idempotency marker and the `friction::<category>` label all read this one
+ * string. N refusals of the SAME class still coalesce, which is the recurrence
+ * evidence the light ceilings are recalibrated from. New categories need no
+ * seeding: the graduator mints missing `friction::*` labels before filing.
+ *
+ * A class-less refusal keeps the bare category unchanged — that is the
+ * suitability gate, which refuses a prompt before any diff exists and so has
+ * no diff-derived class to carry.
+ *
+ * @param {string|null} [refusalClass] A
+ *   {@link module:lib/orchestration/light-suitability.LIGHT_REFUSAL_CLASSES}
+ *   value, or nullish for the unclassified refusal.
+ * @returns {string}
+ */
+export function lightScopeRejectedCategory(refusalClass) {
+  const suffix = typeof refusalClass === 'string' ? refusalClass.trim() : '';
+  const base = RUNTIME_FRICTION_CATEGORIES.LIGHT_SCOPE_REJECTED;
+  return suffix === '' ? base : `${base}-${suffix}`;
+}
+
 /** Cap on free-form reason text copied into a signal's `details`. */
 const REASON_PREVIEW_LIMIT = 500;
 

package/.agents/scripts/lib/observability/source-classifier.js

@@ -87,6 +87,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'bootstrap.js',
   'check-action-pinning.js',
   'check-arch-cycles.js',
+  'check-audit-attribution.js',
   'check-baseline-drift.js',
   'check-baseline-scope.js',
   'check-baselines.js',
@@ -98,6 +99,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-gherkin-corpus.js',
   'check-knip-entries.js',
   'check-lifecycle-lint.js',
+  'check-pinned-override-notes.js',
   'check-schema-references.js',
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',

package/.agents/scripts/lib/orchestration/epic-container.js

@@ -110,6 +110,33 @@ export function isEpicTicket(issue) {
   return normalizeLabels(issue?.labels).includes(TYPE_LABELS.EPIC);
 }
 
+/**
+ * Resolve the GraphQL node id an Epic's native sub-issue read addresses it by.
+ *
+ * Both casings are accepted because the field name depends on which provider
+ * method produced the object, and neither caller can tell from the value it
+ * holds: `getTicket` (and every other single-issue read) runs through
+ * `issueToTicket`, which renames `node_id` to `nodeId`, while
+ * `listIssuesByLabel` returns the REST payload **verbatim** — six consumers
+ * read its raw shape, so mapping it there would be a far wider change than
+ * the two reads that actually need the id.
+ *
+ * Returns `null` when neither name carries one. That is the load-bearing
+ * half: an absent id reaches GraphQL as `$id: ID!` = `undefined`, which the
+ * API rejects and `classifyGithubError` calls `permanent` — so the gateway
+ * rethrows with no retry and no feature-disabled fallback, and the caller
+ * degrades to the body checklist while reporting a hard API failure it never
+ * really had. Callers skip the read on a `null` instead, the same clean
+ * no-op `providers/github/board-add.js` makes with `reason: 'no-node-id'`.
+ *
+ * @param {{ nodeId?: unknown, node_id?: unknown }} epic
+ * @returns {string|null}
+ */
+export function resolveEpicNodeId(epic) {
+  const nodeId = epic?.nodeId ?? epic?.node_id;
+  return typeof nodeId === 'string' && nodeId !== '' ? nodeId : null;
+}
+
 /**
  * Render a container Epic's body.
  *

package/.agents/scripts/lib/orchestration/epic-rollup.js

@@ -45,7 +45,11 @@
 import { Logger } from '../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
 import { ColumnSync, LABEL_TO_COLUMN } from './column-sync.js';
-import { isEpicTicket, readEpicChildIdsFrom } from './epic-container.js';
+import {
+  isEpicTicket,
+  readEpicChildIdsFrom,
+  resolveEpicNodeId,
+} from './epic-container.js';
 import { resolveOperatorFromCandidates } from './lease-guard-shared.js';
 import { deriveParentState } from './ticketing/bulk.js';
 
@@ -68,15 +72,22 @@ const IN_FLIGHT_STATES = new Set([
  * borrow four lines would invert the dependency direction for no gain. What
  * matters is that the *reader* handed to `readEpicChildIdsFrom` behaves the
  * same on both paths, which is what keeps an Epic from being expandable but
- * unclosable.
+ * unclosable. The shared `resolveEpicNodeId` is what makes "the same" true of
+ * the id itself: the Epics reaching this reader come from
+ * `listIssuesByLabel`, whose raw REST payload carries `node_id`, while the
+ * expansion path's come from `getTicket`, whose mapped ticket carries
+ * `nodeId`.
  *
  * @param {object} provider
  * @returns {(epic: object) => Promise<number[]>}
  */
 function nativeChildReader(provider) {
   return async (epic) => {
-    if (typeof provider?._getNativeSubIssues !== 'function') return [];
-    return provider._getNativeSubIssues(epic?.nodeId, epic?.number ?? epic?.id);
+    const nodeId = resolveEpicNodeId(epic);
+    if (nodeId === null) return [];
+    return (
+      provider?._getNativeSubIssues?.(nodeId, epic?.number ?? epic?.id) ?? []
+    );
   };
 }
 

package/.agents/scripts/lib/orchestration/light-backstop.js

@@ -18,16 +18,26 @@
  *     other consumer are looking at the same change set.
  *   - `--numstat` gives per-file line counts, the only surface carrying them.
  *
+ * Both read committed state, which is why a third read exists
+ * ({@link module:lib/orchestration/worktree-dirty.hasUncommittedWork}): an
+ * empty diff is ambiguous between "no work" and "work not committed yet", and
+ * only one of those is about scope.
+ *
  * @module lib/orchestration/light-backstop
  */
 
+import { gitSpawn } from '../git-utils.js';
 import { computeChangeSet } from './change-set.js';
 import { readNumstatRows, summarizeDiffMagnitude } from './diff-magnitude.js';
 import {
   handleBlockedBackstop,
   preserveRefusedWork,
 } from './light-escalation.js';
-import { checkLightDiffBackstop } from './light-suitability.js';
+import {
+  checkLightDiffBackstop,
+  LIGHT_REFUSAL_CLASSES,
+} from './light-suitability.js';
+import { hasUncommittedWork } from './worktree-dirty.js';
 
 /** Exit code when the diff backstop blocked the land. */
 const EXIT_BACKSTOP_BLOCKED = 3;
@@ -41,6 +51,8 @@ const EXIT_BACKSTOP_BLOCKED = 3;
  *   cwd?: string,
  *   computeFn?: typeof computeChangeSet,
  *   readRowsFn?: typeof readNumstatRows,
+ *   dirtyProbeFn?: typeof hasUncommittedWork,
+ *   gitFn?: typeof gitSpawn,
  *   injectedRules?: object,
  * }} args
  * @returns {ReturnType<typeof checkLightDiffBackstop>}
@@ -51,6 +63,8 @@ function runDiffBackstop({
   cwd = process.cwd(),
   computeFn = computeChangeSet,
   readRowsFn = readNumstatRows,
+  dirtyProbeFn = hasUncommittedWork,
+  gitFn = gitSpawn,
   injectedRules,
 } = {}) {
   const headRef = `story-${storyId}`;
@@ -61,9 +75,49 @@ function runDiffBackstop({
     changedFiles: files,
     magnitude,
     injectedRules,
+    storyBranch: headRef,
+    // Only an ENUMERATED-empty diff can be explained by uncommitted work, so
+    // the probe's two git calls are spent only where they can change what the
+    // refusal tells the agent to do.
+    uncommittedWork:
+      Array.isArray(files) && files.length === 0
+        ? dirtyProbeFn({ branch: headRef, cwd, gitFn })
+        : false,
   });
 }
 
+/**
+ * Is this refusal the one that is NOT about scope?
+ *
+ * @param {{ refusalClass?: string|null }} result
+ * @returns {boolean}
+ */
+function isUncommittedRefusal(result) {
+  return result.refusalClass === LIGHT_REFUSAL_CLASSES.UNCOMMITTED_WORK;
+}
+
+/**
+ * Close the refusal log line: what became of the work, and what to run next.
+ *
+ * A `null` preservation is the uncommitted-work refusal by construction — that
+ * is the one path that does not push, because there is nothing a push could
+ * preserve: it would publish a branch at its base and then report uncommitted
+ * work as safe on `origin`, which is the opposite of true.
+ *
+ * @param {{
+ *   storyId: number,
+ *   preservation: { detail: string }|null,
+ *   nextCommand: string,
+ * }} args
+ * @returns {string}
+ */
+function describeBlockedTail({ storyId, preservation, nextCommand }) {
+  return preservation === null
+    ? `nothing is committed yet, so there is no work to preserve; ` +
+        `commit on story-${storyId}, then re-run: "${nextCommand}"`
+    : `${preservation.detail}; recycle the receipt with "${nextCommand}"`;
+}
+
 /**
  * Resolve the backstop pass into everything the CLI needs to print and exit
  * with: the verdict, the recycle command on a refusal (`null` when clean), the
@@ -82,8 +136,8 @@ function runDiffBackstop({
  *   handleBlockedFn?: typeof handleBlockedBackstop,
  *   preserveFn?: typeof preserveRefusedWork,
  * }} args Any further keys (`baseRef`, `cwd`, `computeFn`, `readRowsFn`,
- *   `injectedRules`) forward to the backstop run, so the git-surface join is
- *   drivable through this one entry point.
+ *   `dirtyProbeFn`, `gitFn`, `injectedRules`) forward to the backstop run, so
+ *   the git-surface join is drivable through this one entry point.
  * @returns {Promise<{
  *   result: ReturnType<typeof checkLightDiffBackstop>,
  *   nextCommand: string|null,
@@ -109,7 +163,9 @@ export async function resolveBackstopOutcome({
       message: `[deliver-light] diff backstop clean for Story #${storyId}.`,
     };
   }
-  const preservation = preserveFn({ storyId, cwd: seams.cwd });
+  const preservation = isUncommittedRefusal(result)
+    ? null
+    : preserveFn({ storyId, cwd: seams.cwd });
   const nextCommand = await handleBlockedFn({ storyId, result, preservation });
   return {
     result,
@@ -118,7 +174,7 @@ export async function resolveBackstopOutcome({
     exitCode: EXIT_BACKSTOP_BLOCKED,
     message:
       `[deliver-light] diff backstop BLOCKED Story #${storyId}: ` +
-      `${result.reasons.join('; ')} — ${preservation.detail}; ` +
-      `recycle the receipt with "${nextCommand}"`,
+      `${result.reasons.join('; ')} — ` +
+      describeBlockedTail({ storyId, preservation, nextCommand }),
   };
 }

package/.agents/scripts/lib/orchestration/light-escalation.js

@@ -41,8 +41,10 @@
 import { getStoryBranch, gitSpawn } from '../git-utils.js';
 import {
   emitRuntimeFriction,
+  lightScopeRejectedCategory,
   RUNTIME_FRICTION_CATEGORIES,
 } from '../observability/runtime-friction.js';
+import { LIGHT_REFUSAL_CLASSES } from './light-suitability.js';
 
 /**
  * The `/mandrel-plan` invocation that owns a Story the light path could not land.
@@ -54,6 +56,21 @@ function buildRecycleCommand(storyId) {
   return `/mandrel-plan ${storyId}`;
 }
 
+/**
+ * The command that re-runs the backstop once the work is committed.
+ *
+ * The one refusal that is NOT about scope gets its own next step: an empty diff
+ * over a dirty worktree means the backstop ran before the commit, and handing
+ * that run to `/mandrel-plan` recycles a receipt whose implementation is fine
+ * — the wrong door, dressed as an escalation (issue #5237).
+ *
+ * @param {number} storyId
+ * @returns {string}
+ */
+function buildRerunBackstopCommand(storyId) {
+  return `node .agents/scripts/deliver-light.js --backstop --story ${storyId}`;
+}
+
 /**
  * Coerce an `--amends` argument (`#123` or `123`) into a positive integer issue
  * number, or `null` when absent/malformed.
@@ -127,10 +144,12 @@ export async function handleBlockedBackstop({
   emitFn,
   recordFrictionFn = recordScopeFriction,
 } = {}) {
+  const refusalClass = result?.refusalClass ?? null;
   await recordFrictionFn({
     emitFn,
     storyId,
     surface: 'diff-backstop',
+    category: lightScopeRejectedCategory(refusalClass),
     reasons: result?.reasons ?? [],
     details: {
       fileCount: result?.fileCount ?? null,
@@ -142,9 +161,12 @@ export async function handleBlockedBackstop({
       // than one whose branch reached origin — the roll-up must be able to
       // tell them apart.
       preserved: preservation?.preserved ?? null,
+      refusalClass,
     },
   });
-  return buildRecycleCommand(storyId);
+  return refusalClass === LIGHT_REFUSAL_CLASSES.UNCOMMITTED_WORK
+    ? buildRerunBackstopCommand(storyId)
+    : buildRecycleCommand(storyId);
 }
 
 /**
@@ -221,15 +243,19 @@ export function preserveRefusedWork({
  * @param {{
  *   storyId?: number|null,
  *   surface: string,
+ *   category?: string,
  *   reasons?: string[],
  *   details?: object,
  *   emitFn?: typeof emitRuntimeFriction,
- * }} args
+ * }} args `category` defaults to the unclassified light-refusal bucket, which
+ *   is what the suitability gate emits: it refuses a prompt before any diff
+ *   exists, so it carries no refusal class to encode.
  * @returns {Promise<boolean>}
  */
 async function recordScopeFriction({
   storyId,
   surface,
+  category = RUNTIME_FRICTION_CATEGORIES.LIGHT_SCOPE_REJECTED,
   reasons = [],
   details = {},
   emitFn,
@@ -238,7 +264,7 @@ async function recordScopeFriction({
   try {
     return await emit({
       storyId,
-      category: RUNTIME_FRICTION_CATEGORIES.LIGHT_SCOPE_REJECTED,
+      category,
       tool: 'deliver-light',
       details: { surface, reasons, ...details },
     });

package/.agents/scripts/lib/orchestration/light-suitability.js

@@ -524,6 +524,52 @@ export function resolveLightGateOutcome({
   };
 }
 
+/**
+ * The refusal classes a blocked diff backstop can carry — the machine-readable
+ * half of a verdict whose `reasons[]` are prose (Story #5238).
+ *
+ * One value per blocked verdict, and the reason it exists is downstream: the
+ * refusal's friction category is derived from it
+ * ({@link module:lib/observability/runtime-friction.lightScopeRejectedCategory}),
+ * and the category is the ONLY key the retro composer separates buckets on.
+ * Under one bare category an empty-diff refusal and a `public-api` refusal
+ * aggregated into a single "recurred 2 times" follow-up with nothing in common
+ * (issue #5237) — the roll-up's shape fingerprint could not tell them apart
+ * either, because it hashes detail keys and every refusal carries the same set.
+ *
+ * Kept coarse on purpose: a class must be stable enough that N refusals of one
+ * cause still coalesce into the recurrence evidence the ceilings are
+ * recalibrated from.
+ *
+ * @typedef {{ reason: string, refusalClass: string }} Objection
+ */
+export const LIGHT_REFUSAL_CLASSES = Object.freeze({
+  /** The diff could not be enumerated, or enumerated to nothing. */
+  CHANGE_SET_UNKNOWN: 'change-set-unknown',
+  /** Enumerated-empty, but the worktree carries uncommitted changes. */
+  UNCOMMITTED_WORK: 'uncommitted-work',
+  /** The change set intersects a registered sensitive-path class. */
+  SENSITIVE_PATH: 'sensitive-path',
+  /** Sensitivity could not be classified, so non-sensitivity is unproven. */
+  SENSITIVITY_UNKNOWN: 'sensitivity-unknown',
+  /** The implementation magnitude could not be measured. */
+  MAGNITUDE_UNKNOWN: 'magnitude-unknown',
+  /** Measured magnitude exceeded a light ceiling. */
+  OVER_CEILING: 'over-ceiling',
+});
+
+/**
+ * Name the branch a commit-first refusal tells the agent to commit on, with a
+ * generic stand-in when the caller supplied none. Pure.
+ *
+ * @param {unknown} storyBranch
+ * @returns {string}
+ */
+function describeStoryBranch(storyBranch) {
+  const name = typeof storyBranch === 'string' ? storyBranch.trim() : '';
+  return name === '' ? 'the Story branch' : name;
+}
+
 /**
  * Diff-derived backstop (Story #4740 AC-4, re-based on magnitude by Story
  * #4856): re-check the **actual** change set after implementation, because the
@@ -555,7 +601,14 @@ export function resolveLightGateOutcome({
  *   ceilings?: { maxImplLines?: number, maxImplFiles?: number },
  *   injectedRules?: object,
  *   selectSensitivePathClassesFn?: Function,
- * }} [args]
+ *   storyBranch?: string,
+ *   uncommittedWork?: boolean,
+ * }} [args] `uncommittedWork` is the caller's dirty-worktree probe result: the
+ *   backstop reads COMMITTED state, so an implemented-but-uncommitted run
+ *   measures an empty diff, and the door for that is `git commit` — not an
+ *   escalation. It only ever refines an enumerated-empty verdict's guidance;
+ *   the verdict itself still blocks. `storyBranch` names the branch that
+ *   guidance points at.
  * @returns {{
  *   blocked: boolean,
  *   level: 'low'|'high'|null,
@@ -563,8 +616,10 @@ export function resolveLightGateOutcome({
  *   fileCount: number|null,
  *   magnitude: { implFiles: number, implLines: number }|null,
  *   ceilings: { maxImplLines: number, maxImplFiles: number },
+ *   refusalClass: string|null,
  *   reasons: string[],
- * }}
+ * }} `refusalClass` is `null` on a clean verdict and exactly one
+ *   {@link LIGHT_REFUSAL_CLASSES} value on every blocked one.
  */
 export function checkLightDiffBackstop({
   changedFiles,
@@ -572,6 +627,8 @@ export function checkLightDiffBackstop({
   ceilings,
   injectedRules,
   selectSensitivePathClassesFn,
+  storyBranch,
+  uncommittedWork = false,
 } = {}) {
   const resolved = resolveDiffCeilings(ceilings);
   const files = Array.isArray(changedFiles)
@@ -579,6 +636,12 @@ export function checkLightDiffBackstop({
     : null;
 
   if (files === null || files.length === 0) {
+    // An ENUMERATED-empty diff over a dirty worktree is a different event from
+    // an unverifiable one, and blocking is right for both — but only one of
+    // them is about scope. The caller's probe distinguishes them; `files ===
+    // null` never can, because a `git diff` that failed outright is exactly
+    // the case where nothing about the change is known.
+    const uncommitted = files !== null && uncommittedWork === true;
     return {
       blocked: true,
       level: null,
@@ -586,8 +649,13 @@ export function checkLightDiffBackstop({
       fileCount: files === null ? null : 0,
       magnitude: null,
       ceilings: resolved,
+      refusalClass: uncommitted
+        ? LIGHT_REFUSAL_CLASSES.UNCOMMITTED_WORK
+        : LIGHT_REFUSAL_CLASSES.CHANGE_SET_UNKNOWN,
       reasons: [
-        'actual change set is unknown or empty — cannot verify the diff is light; escalate to /mandrel-plan',
+        uncommitted
+          ? `the change set is empty but the worktree has uncommitted changes — commit them on ${describeStoryBranch(storyBranch)}, then re-run the backstop; nothing here is over-scope, so do NOT escalate to /mandrel-plan`
+          : 'actual change set is unknown or empty — cannot verify the diff is light; escalate to /mandrel-plan',
       ],
     };
   }
@@ -599,12 +667,12 @@ export function checkLightDiffBackstop({
   });
   const measured = normalizeMagnitude(magnitude);
 
-  const reasons = [
+  const objections = [
     ...describeSensitivity({ level, classes }),
     ...describeMagnitude(measured, resolved),
   ];
 
-  const blocked = reasons.length > 0;
+  const blocked = objections.length > 0;
   return {
     blocked,
     level,
@@ -612,8 +680,13 @@ export function checkLightDiffBackstop({
     fileCount: files.length,
     magnitude: measured,
     ceilings: resolved,
+    // Objection ORDER is the class precedence: sensitivity is derived before
+    // magnitude, so a diff that is both sensitive and over-ceiling files as a
+    // sensitive-path refusal. That is the right way round — the ceiling is
+    // recalibratable, the sensitive path is not.
+    refusalClass: blocked ? objections[0].refusalClass : null,
     reasons: blocked
-      ? reasons
+      ? objections.map((objection) => objection.reason)
       : [
           `diff is light: ${measured.implLines} implementation line(s) ≤ ${resolved.maxImplLines} ` +
             `across ${measured.implFiles} implementation file(s) ≤ ${resolved.maxImplFiles} ` +
@@ -641,17 +714,24 @@ function normalizeMagnitude(magnitude) {
  * Sensitivity objections, over the **full** change set. Pure.
  *
  * @param {{ level: 'low'|'high'|null, classes: string[] }} derived
- * @returns {string[]}
+ * @returns {Objection[]}
  */
 function describeSensitivity({ level, classes }) {
   if (classes.length > 0) {
     return [
-      `diff intersects sensitive-path class(es) ${classes.join(', ')} — escalate to /mandrel-plan (do not land light)`,
+      {
+        refusalClass: LIGHT_REFUSAL_CLASSES.SENSITIVE_PATH,
+        reason: `diff intersects sensitive-path class(es) ${classes.join(', ')} — escalate to /mandrel-plan (do not land light)`,
+      },
     ];
   }
   if (level !== 'low') {
     return [
-      'sensitive-path classification unavailable — cannot verify the diff is non-sensitive; escalate to /mandrel-plan',
+      {
+        refusalClass: LIGHT_REFUSAL_CLASSES.SENSITIVITY_UNKNOWN,
+        reason:
+          'sensitive-path classification unavailable — cannot verify the diff is non-sensitive; escalate to /mandrel-plan',
+      },
     ];
   }
   return [];
@@ -662,26 +742,32 @@ function describeSensitivity({ level, classes }) {
  *
  * @param {{ implFiles: number, implLines: number }|null} measured
  * @param {{ maxImplLines: number, maxImplFiles: number }} ceilings
- * @returns {string[]}
+ * @returns {Objection[]}
  */
 function describeMagnitude(measured, ceilings) {
   if (measured === null) {
     return [
-      'change magnitude could not be measured (unreadable or unparseable numstat) — cannot verify the diff is light; escalate to /mandrel-plan',
+      {
+        refusalClass: LIGHT_REFUSAL_CLASSES.MAGNITUDE_UNKNOWN,
+        reason:
+          'change magnitude could not be measured (unreadable or unparseable numstat) — cannot verify the diff is light; escalate to /mandrel-plan',
+      },
     ];
   }
-  const reasons = [];
+  const objections = [];
   if (measured.implLines > ceilings.maxImplLines) {
-    reasons.push(
-      `diff changes ${measured.implLines} implementation line(s) (> maxImplLines ${ceilings.maxImplLines}) — escalate to /mandrel-plan (do not land light)`,
-    );
+    objections.push({
+      refusalClass: LIGHT_REFUSAL_CLASSES.OVER_CEILING,
+      reason: `diff changes ${measured.implLines} implementation line(s) (> maxImplLines ${ceilings.maxImplLines}) — escalate to /mandrel-plan (do not land light)`,
+    });
   }
   if (measured.implFiles > ceilings.maxImplFiles) {
-    reasons.push(
-      `diff spans ${measured.implFiles} implementation file(s) (> maxImplFiles ${ceilings.maxImplFiles}) — escalate to /mandrel-plan (do not land light)`,
-    );
+    objections.push({
+      refusalClass: LIGHT_REFUSAL_CLASSES.OVER_CEILING,
+      reason: `diff spans ${measured.implFiles} implementation file(s) (> maxImplFiles ${ceilings.maxImplFiles}) — escalate to /mandrel-plan (do not land light)`,
+    });
   }
-  return reasons;
+  return objections;
 }
 
 /** Cap on a receipt slug's length — keep the branch/id readable. */

package/.agents/scripts/lib/orchestration/retro-proposals.js

@@ -305,6 +305,39 @@ function fingerprintBucket(category, tools, detailKeys) {
     .slice(0, 8);
 }
 
+/**
+ * Every reason text one signal's `details` carries, read from BOTH shapes the
+ * emitters actually write.
+ *
+ * Two keys because two emitter conventions, and the divergence was silent: the
+ * degradation emitters write a singular `details.reason` string, while the
+ * light path's refusal emitter (`light-escalation.recordScopeFriction`) writes
+ * `details.reasons` — an **array**, because one backstop verdict can object on
+ * sensitivity and magnitude in the same pass. Reading only the singular key is
+ * why every `light-scope-rejected` follow-up rendered with no `Reason:` line
+ * at all (issue #5237), which defeated Story #4837's whole intent for that
+ * emitter: the filed issue named a count and a category, and the refusal text
+ * that would have told a reader which ceiling fired stayed in the ledger.
+ *
+ * Non-string members are skipped rather than coerced — `String(value)` would
+ * put `[object Object]` in a live issue body.
+ *
+ * @param {object} details
+ * @returns {string[]}
+ */
+function collectReasons(details) {
+  const out = [];
+  const single = asString(details.reason);
+  if (single.length > 0) out.push(single);
+  if (Array.isArray(details.reasons)) {
+    for (const raw of details.reasons) {
+      const text = asString(raw);
+      if (text.length > 0) out.push(text);
+    }
+  }
+  return out;
+}
+
 /**
  * Widen a bucket's first-to-last window to include one instant. A row with no
  * usable `ts` widens nothing — it is counted in `total` but cannot date the
@@ -391,8 +424,9 @@ function aggregateByCategory(signals) {
       // over keys, deliberately) is untouched by them.
       const surface = asString(sig.details.surface);
       if (surface.length > 0) entry.surfaces.add(surface);
-      const reason = asString(sig.details.reason);
-      if (reason.length > 0) entry.reasons.add(reason);
+      for (const reason of collectReasons(sig.details)) {
+        entry.reasons.add(reason);
+      }
     }
     // An id that cannot be resolved to a real issue is tracked separately
     // rather than dropped: it must never be counted or printed as recurrence