mandrel 2.51.0 → 2.52.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/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

package/.agents/scripts/lib/orchestration/worktree-dirty.js

@@ -0,0 +1,80 @@
+/**
+ * lib/orchestration/worktree-dirty.js — "does this branch's checkout carry
+ * uncommitted changes?" (Story #5238).
+ *
+ * Its own module because the light path's diff backstop is otherwise a pure
+ * join over two committed-state git reads, and this is the one question there
+ * that needs a third read of a *working tree*. Keeping it here leaves
+ * {@link module:lib/orchestration/light-backstop} the thin join it claims to
+ * be, and gives the probe its own place to be tested against every way a git
+ * read can fail.
+ *
+ * @module lib/orchestration/worktree-dirty
+ */
+
+import { gitSpawn } from '../git-utils.js';
+import { parseWorktreePorcelain } from '../worktree/inspector.js';
+
+/**
+ * The stdout of a successful git read, or `null` when it cannot be trusted.
+ *
+ * @param {{ status?: number, stdout?: unknown }|null|undefined} result
+ * @returns {string|null}
+ */
+function readableStdout(result) {
+  if (result?.status !== 0) return null;
+  return typeof result.stdout === 'string' ? result.stdout : null;
+}
+
+/**
+ * Locate the checkout that has `branch` checked out, or `null` when no
+ * checkout does.
+ *
+ * `git worktree list --porcelain` enumerates **every** checkout including the
+ * main one, so a repository working on the branch directly (no separate
+ * worktree) is found by this same lookup rather than by a second fallback path.
+ *
+ * @param {{ branch: string, cwd: string, gitFn: typeof gitSpawn }} args
+ * @returns {string|null}
+ */
+function resolveBranchCheckout({ branch, cwd, gitFn }) {
+  const listed = readableStdout(gitFn(cwd, 'worktree', 'list', '--porcelain'));
+  if (listed === null) return null;
+  const match = parseWorktreePorcelain(listed).find(
+    (record) => record.branch === branch,
+  );
+  return match ? match.path : null;
+}
+
+/**
+ * Does the checkout holding `branch` have uncommitted changes?
+ *
+ * **Why the light path asks.** Its diff backstop measures `base...head`, which
+ * is committed state, so a run that implemented and did not commit measures an
+ * empty change set — and the refusal then told the agent its scope was
+ * unverifiable and to escalate, when the actual fix was `git commit`. Measured
+ * in the consumer: the refusal signal is stamped 12:14:06Z and the branch's
+ * only commit 12:15:19Z (issue #5237).
+ *
+ * Total, and deliberately asymmetric: every unreadable surface — a failed
+ * `worktree list`, a branch no checkout holds, a failed `status`, a throwing
+ * git — answers `false`. A probe that cannot see the tree must not be able to
+ * talk a refusal into friendlier guidance than the evidence supports.
+ *
+ * @param {{ branch: string, cwd?: string, gitFn?: typeof gitSpawn }} args
+ * @returns {boolean}
+ */
+export function hasUncommittedWork({
+  branch,
+  cwd = process.cwd(),
+  gitFn = gitSpawn,
+} = {}) {
+  try {
+    const checkout = resolveBranchCheckout({ branch, cwd, gitFn });
+    if (checkout === null) return false;
+    const status = readableStdout(gitFn(checkout, 'status', '--porcelain'));
+    return status !== null && status.trim() !== '';
+  } catch {
+    return false;
+  }
+}

package/.agents/workflows/helpers/deliver-light.md

@@ -153,13 +153,19 @@ answer).
    number that then rejects the change. They are **not** exempt from
    sensitive-path matching, which runs over the full change set.
 
-   Exit `3` (`blocked: true`) means the diff exceeds a light ceiling or touches a
-   sensitive-path class. STOP, flip `agent::blocked`, and **recycle the receipt**
-   through the envelope's `nextCommand` (`/mandrel-plan <storyId>`) — tickets mode
-   rewrites it into properly-planned Stories and closes it as superseded. Do not
-   land, and do not leave the receipt open with no successor: it already carries
-   the branch, the worktree, and the implementation, all of which are evidence
-   the plan should read.
+   **Commit before you run it.** The backstop measures **committed** state, so
+   a run that implemented but has not committed measures an empty diff and is
+   refused for a scope it never had. That refusal names the real fix — commit
+   on `story-<id>`, then re-run the backstop — and its `nextCommand` is that
+   re-run, not an escalation.
+
+   Exit `3` (`blocked: true`) otherwise means the diff exceeds a light ceiling or
+   touches a sensitive-path class. STOP, flip `agent::blocked`, and **recycle the
+   receipt** through the envelope's `nextCommand` (`/mandrel-plan <storyId>`) —
+   tickets mode rewrites it into properly-planned Stories and closes it as
+   superseded. Do not land, and do not leave the receipt open with no successor:
+   it already carries the branch, the worktree, and the implementation, all of
+   which are evidence the plan should read.
 
 5. **Close and land (same engine).** Exactly [`/mandrel-deliver`](../mandrel-deliver.md)'s close:
 

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.52.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.51.0...mandrel-v2.52.0) (2026-09-08)
+
+
+### Fixed
+
+* render deliver-light refusal reasons in retro follow-ups and file each backstop refusal class as its own friction category ([#5238](https://github.com/dsj1984/mandrel/issues/5238)) ([#5239](https://github.com/dsj1984/mandrel/issues/5239)) ([65ff0ff](https://github.com/dsj1984/mandrel/commit/65ff0ff4252ddc4fe34d4d8453159a80afae6223))
+
 ## [2.51.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.50.0...mandrel-v2.51.0) (2026-09-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.51.0",
+  "version": "2.52.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",