mandrel 2.23.0 → 2.25.0

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

@@ -0,0 +1,248 @@
+/**
+ * lib/orchestration/light-escalation.js — what the light path does when it
+ * refuses a scope (Story #4856).
+ *
+ * Three behaviors, each previously missing, and each about a refusal rather
+ * than a verdict — the verdicts live in
+ * {@link module:lib/orchestration/light-suitability}:
+ *
+ *   1. **Recycling the receipt.** A blocked diff backstop used to tell the
+ *      operator to "escalate to `/plan`", which authored a brand-new Story and
+ *      left the receipt open with no successor — orphaning its branch, its
+ *      worktree, and a finished implementation. Naming the receipt as `/plan`'s
+ *      *input* recycles it instead: tickets mode already fetches a ticket,
+ *      rewrites it into properly-planned Stories, and closes the source as
+ *      superseded.
+ *
+ *      Deferring receipt creation until after the backstop would be the other
+ *      fix, and is deliberately not taken: the issue id is load-bearing in
+ *      `single-story-init.js` (the assignee lease, the `story-<id>` branch, the
+ *      label state machine) and in the `(refs #<id>)` commit subject.
+ *
+ *   2. **Telemetering the refusal.** Neither light-path rejection emitted any
+ *      signal, so an over-tight ceiling could only reach the framework as
+ *      anecdote — which is exactly how the `maxFiles: 4` defect surfaced. The
+ *      roll-up aggregates by category, so recording these makes the ceilings
+ *      recalibratable from evidence.
+ *
+ *   3. **Preserving the refused work** ({@link preserveRefusedWork}, Story
+ *      #4875). A refusal used to leave a finished implementation on a local
+ *      `story-<id>` branch with no remote ref — the one shape routine branch
+ *      and worktree cleanup is entitled to delete. The branch is published to
+ *      `origin` (no PR, no merge) so the recycle command has something to
+ *      recycle.
+ *
+ * Telemetry is best-effort by construction: a signals-write failure must never
+ * change a gate's verdict.
+ *
+ * @module lib/orchestration/light-escalation
+ */
+
+import { getStoryBranch, gitSpawn } from '../git-utils.js';
+import {
+  emitRuntimeFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from '../observability/runtime-friction.js';
+
+/**
+ * The `/plan` invocation that owns a Story the light path could not land.
+ *
+ * @param {number} storyId
+ * @returns {string}
+ */
+function buildRecycleCommand(storyId) {
+  return `/plan ${storyId}`;
+}
+
+/**
+ * Coerce an `--amends` argument (`#123` or `123`) into a positive integer issue
+ * number, or `null` when absent/malformed.
+ *
+ * This is the only Story context a **gate-stage** rejection can legitimately
+ * claim: the signals stream is keyed on a Story id, and an `ask-operator` gate
+ * has authored no receipt yet — deliberately, since not creating one is the
+ * point of that outcome. A bare prompt's rejection therefore has no stream to
+ * land in, and attributing it to a fabricated id would be worse than recording
+ * nothing.
+ *
+ * @param {unknown} amends
+ * @returns {number|null}
+ */
+function normalizeAmendsId(amends) {
+  const match = /^#?(\d+)$/.exec(String(amends ?? '').trim());
+  if (!match) return null;
+  const n = Number.parseInt(match[1], 10);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/**
+ * Record a suitability-gate refusal (`ask-operator`) as friction, attributed to
+ * the `--amends` target when there is one.
+ *
+ * @param {{
+ *   gate: object,
+ *   amends?: unknown,
+ *   recordFrictionFn?: typeof recordScopeFriction,
+ * }} args
+ * @returns {Promise<boolean>}
+ */
+export async function recordGateRefusal({
+  gate,
+  amends,
+  emitFn,
+  recordFrictionFn = recordScopeFriction,
+} = {}) {
+  return recordFrictionFn({
+    emitFn,
+    storyId: normalizeAmendsId(amends),
+    surface: 'suitability-gate',
+    reasons: gate?.outcome?.reasons ?? [],
+    details: {
+      action: gate?.action ?? null,
+      code: gate?.suitability?.shape?.code ?? null,
+    },
+  });
+}
+
+/**
+ * Handle a blocked diff backstop: record the refusal as friction and return the
+ * `/plan` invocation that recycles the receipt.
+ *
+ * Lives here rather than in the CLI so the shell stays a shell — the backstop
+ * mode's job is to branch and print, not to decide what a refusal means.
+ *
+ * @param {{
+ *   storyId: number,
+ *   result: object,
+ *   preservation?: ReturnType<typeof preserveRefusedWork>,
+ *   recordFrictionFn?: typeof recordScopeFriction,
+ * }} args `result` is a {@link module:lib/orchestration/light-suitability.checkLightDiffBackstop}
+ *   verdict; `preservation` is the {@link preserveRefusedWork} outcome.
+ * @returns {Promise<string>} The recycle command.
+ */
+export async function handleBlockedBackstop({
+  storyId,
+  result,
+  preservation,
+  emitFn,
+  recordFrictionFn = recordScopeFriction,
+} = {}) {
+  await recordFrictionFn({
+    emitFn,
+    storyId,
+    surface: 'diff-backstop',
+    reasons: result?.reasons ?? [],
+    details: {
+      fileCount: result?.fileCount ?? null,
+      implFiles: result?.magnitude?.implFiles ?? null,
+      implLines: result?.magnitude?.implLines ?? null,
+      ceilings: result?.ceilings ?? null,
+      classes: result?.classes ?? [],
+      // A refusal whose work was NOT preserved is a different (worse) event
+      // than one whose branch reached origin — the roll-up must be able to
+      // tell them apart.
+      preserved: preservation?.preserved ?? null,
+    },
+  });
+  return buildRecycleCommand(storyId);
+}
+
+/**
+ * Publish a refused light run's branch to `origin` so the finished work is
+ * recoverable (Story #4875).
+ *
+ * A blocked backstop refuses the *land*, not the *work*: the implementation is
+ * complete and the recycle command hands the receipt to `/plan`, which will
+ * want it. Before this, that work existed only as a local `story-<id>` branch
+ * with no remote ref — an untracked branch is exactly what the routine merged-
+ * branch sweeps and worktree reaping treat as disposable, so the only copy of a
+ * finished implementation sat one cleanup away from deletion.
+ *
+ * Pushing is deliberately **not** a landing: the branch gets a remote ref, no
+ * PR is opened, and nothing merges. Total by construction — a push failure
+ * (offline, no write access, no such branch) is reported and never changes the
+ * refusal verdict, because a preservation attempt must not be able to turn a
+ * blocked backstop into a crash.
+ *
+ * Idempotent: re-running against an already-pushed branch is an up-to-date
+ * no-op.
+ *
+ * @param {{
+ *   storyId: number,
+ *   cwd?: string,
+ *   gitFn?: typeof gitSpawn,
+ * }} args
+ * @returns {{
+ *   preserved: boolean,
+ *   branch: string,
+ *   remoteRef: string|null,
+ *   detail: string,
+ * }}
+ */
+export function preserveRefusedWork({
+  storyId,
+  cwd = process.cwd(),
+  gitFn = gitSpawn,
+} = {}) {
+  const branch = getStoryBranch(storyId);
+  const unpreserved = (detail) => ({
+    preserved: false,
+    branch,
+    remoteRef: null,
+    detail,
+  });
+  let result;
+  try {
+    result = gitFn(cwd, 'push', '--set-upstream', 'origin', branch);
+  } catch (err) {
+    return unpreserved(
+      `could not publish ${branch}: ${err?.message ?? err} — the finished work is LOCAL ONLY; push it before any branch cleanup runs`,
+    );
+  }
+  if (result?.status !== 0) {
+    return unpreserved(
+      `could not publish ${branch}: ${result?.stderr || 'git push failed'} — the finished work is LOCAL ONLY; push it before any branch cleanup runs`,
+    );
+  }
+  return {
+    preserved: true,
+    branch,
+    remoteRef: `origin/${branch}`,
+    detail: `refused work preserved on origin/${branch} — the branch is no longer the only copy, and no PR was opened`,
+  };
+}
+
+/**
+ * Record a light-path scope rejection as friction.
+ *
+ * Total: never throws, and returns `false` rather than propagating when the
+ * signals surface is unavailable.
+ *
+ * @param {{
+ *   storyId?: number|null,
+ *   surface: string,
+ *   reasons?: string[],
+ *   details?: object,
+ *   emitFn?: typeof emitRuntimeFriction,
+ * }} args
+ * @returns {Promise<boolean>}
+ */
+async function recordScopeFriction({
+  storyId,
+  surface,
+  reasons = [],
+  details = {},
+  emitFn,
+} = {}) {
+  const emit = emitFn ?? emitRuntimeFriction;
+  try {
+    return await emit({
+      storyId,
+      category: RUNTIME_FRICTION_CATEGORIES.LIGHT_SCOPE_REJECTED,
+      tool: 'deliver-light',
+      details: { surface, reasons, ...details },
+    });
+  } catch {
+    return false;
+  }
+}

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

@@ -36,9 +36,13 @@
  *      Under `--yes` (unattended) it fails closed to recommending `/plan`.
  *   3. **Diff-derived backstop ({@link checkLightDiffBackstop}).** After
  *      implementation the **actual** change set is re-checked with
- *      {@link module:lib/orchestration/review-depth.deriveChangeLevel} plus a
- *      file-count ceiling — the diff is the real scope signal — and an
- *      over-ceiling diff is blocked rather than landed silently.
+ *      {@link module:lib/orchestration/review-depth.deriveChangeLevel} plus the
+ *      implementation-only magnitude ceilings of {@link LIGHT_DIFF_CEILINGS} —
+ *      the diff is the real scope signal — and an over-ceiling diff is blocked
+ *      rather than landed silently. Story #4856 moved this from a `maxFiles: 4`
+ *      cardinality ceiling to changed lines over implementation files, and made
+ *      a block **recycle** its receipt Story through `/plan` tickets mode
+ *      instead of orphaning it.
  *   4. **Minimal receipt Story ({@link buildReceiptStoryTicket}).** A
  *      `type::story` ticket is authored inline so `refs #`, history, telemetry,
  *      and the `agent::executing -> agent::done` state machine survive.
@@ -79,35 +83,135 @@ export const OVERRIDABLE_SHAPE_CODES = Object.freeze([
 ]);
 
 /**
- * File-count ceiling for the **actual landed** change set the diff backstop
- * ({@link checkLightDiffBackstop}) enforces. This is the light path's **only**
- * cardinality ceiling, and deliberately so (Story #4764): the predicted
- * footprint is a declaration — a guess, and a gameable one — so the gate that
- * counts must be the one reading ground truth. A genuinely-light change stays
- * small; conservative by construction, since a ceiling an operator could widen
- * past what a single session safely absorbs is a ceiling that fails silently.
- * A framework constant, not a knob.
+ * Detect the **un-waivable** risk rules a predicted footprint trips —
+ * `sensitive-path` and `migration-span`, the complement of
+ * {@link OVERRIDABLE_SHAPE_CODES} — **independent of which rule the shape
+ * decision happened to record** (Story #4875).
+ *
+ * No re-slicing, shrinking, or operator answer satisfies one: a footprint
+ * intersecting a sensitive-path class routes `full` however small the change,
+ * and the diff backstop refuses the same footprint again at the end. But
+ * {@link deriveStoryShape} reports only the **first** rule a shape trips and
+ * evaluates the ceiling rules first, so a prompt tripping both `change-kinds`
+ * and `sensitive-path` is reported as a size objection — which reads as
+ * appealable, is waivable by an attended operator, and sends the work all the
+ * way to an implementation the backstop then refuses.
+ *
+ * The recovery is that the shape decision attaches the built effort shape to
+ * every footprint it can judge at all, and that shape carries the risk facts
+ * (`sensitiveClasses`, `migrationSpan`) whether or not a risk rule fired.
+ * Reading them here surfaces the objection first-hit reporting hides — the
+ * difference between a wasted session and a redirected one.
+ *
+ * Pure and total.
+ *
+ * @param {{ shape?: { sensitiveClasses?: unknown, migrationSpan?: unknown } }} [decision]
+ *   A {@link deriveStoryShape} return value.
+ * @returns {{
+ *   present: boolean,
+ *   code: string|null,
+ *   classes: string[],
+ *   reason: string|null,
+ * }}
+ */
+function deriveUnwaivableRisk(decision) {
+  const shape = decision?.shape ?? null;
+  const classes = Array.isArray(shape?.sensitiveClasses)
+    ? shape.sensitiveClasses.filter(
+        (c) => typeof c === 'string' && c.trim() !== '',
+      )
+    : [];
+  if (classes.length > 0) {
+    return {
+      present: true,
+      code: SHAPE_CODES.SENSITIVE_PATH,
+      classes,
+      reason:
+        `un-waivable: the predicted footprint intersects sensitive-path ` +
+        `class(es) ${classes.join(', ')} — this is risk, not size, so no ` +
+        `re-slicing, shrinking, or operator override satisfies it and the ` +
+        `diff backstop would refuse the same footprint after the work is ` +
+        `finished; take this to /plan now`,
+    };
+  }
+  if (shape?.migrationSpan === true) {
+    return {
+      present: true,
+      code: SHAPE_CODES.MIGRATION_SPAN,
+      classes: [],
+      reason:
+        `un-waivable: the predicted footprint pairs a migration with its ` +
+        `consumers — this is risk, not size, so no re-slicing or operator ` +
+        `override satisfies it; take this to /plan now`,
+    };
+  }
+  return { present: false, code: null, classes: [], reason: null };
+}
+
+/**
+ * Ceilings for the **actual landed** change set the diff backstop
+ * ({@link checkLightDiffBackstop}) enforces, measured on the change's
+ * implementation half (Story #4856 — see
+ * {@link module:lib/orchestration/diff-magnitude} for the measured case and the
+ * companion-class boundary).
+ *
+ * The backstop reads ground truth, so it is where size is genuinely enforced;
+ * the prediction gate above it is a declaration and stays coarse (Story #4764).
+ * What changed is the **axis**: this used to be `maxFiles: 4`, a cardinality
+ * ceiling that rejected 79% of this repository's real merged work while passing
+ * a three-file 323-line rewrite.
+ *
+ *   - `maxImplLines` — additions plus deletions across implementation files.
+ *                      Simulated over 41 merges, 1000 admits 83% of real work
+ *                      and rejects exactly the genuinely large changes.
+ *   - `maxImplFiles` — implementation files touched, a *sprawl* tripwire rather
+ *                      than a size gate. Set to `DEFAULT_DIFF_WIDTH.softFiles`
+ *                      so the light path and `review-depth.js` stop holding two
+ *                      different definitions of a narrow diff.
+ *
+ * Framework constants, not knobs: a ceiling an operator could widen past what a
+ * single session safely absorbs is a ceiling that fails silently.
  */
 export const LIGHT_DIFF_CEILINGS = Object.freeze({
-  maxFiles: 4,
+  maxImplLines: 1000,
+  maxImplFiles: 15,
 });
 
 /**
- * Coerce a candidate `maxFiles` ceiling into a positive integer, falling back
- * to the framework default for anything malformed — a stray `0`, `-1`, or `NaN`
- * must never widen (or zero out) the light diff ceiling.
+ * Coerce a candidate ceiling into a positive integer, falling back to the
+ * framework default for anything malformed — a stray `0`, `-1`, or `NaN` must
+ * never widen (or zero out) a light diff ceiling.
  *
  * @param {unknown} value
  * @param {number} fallback
  * @returns {number}
  */
-function normalizeMaxFiles(value, fallback) {
+function normalizeCeiling(value, fallback) {
   if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
     return fallback;
   }
   return Math.floor(value);
 }
 
+/**
+ * Resolve the effective diff ceilings from a caller-supplied partial override.
+ *
+ * @param {{ maxImplLines?: unknown, maxImplFiles?: unknown }} [ceilings]
+ * @returns {{ maxImplLines: number, maxImplFiles: number }}
+ */
+function resolveDiffCeilings(ceilings) {
+  return {
+    maxImplLines: normalizeCeiling(
+      ceilings?.maxImplLines,
+      LIGHT_DIFF_CEILINGS.maxImplLines,
+    ),
+    maxImplFiles: normalizeCeiling(
+      ceilings?.maxImplFiles,
+      LIGHT_DIFF_CEILINGS.maxImplFiles,
+    ),
+  };
+}
+
 /**
  * Resolve the model's trivial-vs-standard verdict, held to the same ledgering
  * contract the planner's authored verdict is
@@ -184,9 +288,12 @@ export function resolveLedgeredVerdict({ route, reason } = {}) {
  *   route: 'lite'|'full',
  *   shape: ReturnType<typeof deriveStoryShape>,
  *   ledger: ReturnType<typeof resolveLedgeredVerdict>,
+ *   unwaivable: ReturnType<typeof deriveUnwaivableRisk>,
  *   ceilings: typeof STORY_SHAPE_CEILINGS,
  *   reasons: string[],
- * }}
+ * }} `unwaivable` names an absolute risk rule the predicted footprint trips
+ *   even when the recorded `shape.code` is a size prediction (Story #4875), so
+ *   the operator learns at prediction time that no override can help.
  */
 export function deriveLightSuitability({
   predictedChanges,
@@ -208,14 +315,24 @@ export function deriveLightSuitability({
     injectedRules,
     selectSensitivePathClassesFn,
   });
-  const suitable = shape.route === 'lite' && ledger.route === 'lite';
+  const unwaivable = deriveUnwaivableRisk(shape);
+  // A tripped risk rule is decisive on its own: the shape decision may have
+  // recorded an earlier ceiling rule, but a sensitive footprint can never be
+  // lite, so the conjunction must not be able to read `suitable` from a shape
+  // whose recorded code was waived downstream.
+  const suitable =
+    shape.route === 'lite' && ledger.route === 'lite' && !unwaivable.present;
+  const reasons = [`shape: ${shape.reasons[0]}`];
+  if (unwaivable.present) reasons.push(unwaivable.reason);
+  reasons.push(`verdict: ${ledger.note}`);
   return {
     suitable,
     route: suitable ? 'lite' : 'full',
     shape,
     ledger,
+    unwaivable,
     ceilings: STORY_SHAPE_CEILINGS,
-    reasons: [`shape: ${shape.reasons[0]}`, `verdict: ${ledger.note}`],
+    reasons,
   };
 }
 
@@ -236,8 +353,11 @@ export function deriveLightSuitability({
  *      terminal). Checked here as well as at the CLI, so the pure core carries
  *      the guarantee rather than the shell.
  *   3. **The objection is a size prediction** — a code in
- *      {@link OVERRIDABLE_SHAPE_CODES}. Sensitivity and migration span are
- *      risk and stay absolute however small the change.
+ *      {@link OVERRIDABLE_SHAPE_CODES}, **and** the footprint trips no
+ *      un-waivable risk rule ({@link deriveUnwaivableRisk}, Story #4875).
+ *      Sensitivity and migration
+ *      span are risk and stay absolute however small the change — including
+ *      when an earlier ceiling rule is the one the shape recorded.
  *   4. **The ledgered verdict is already `lite`.** The override substitutes for
  *      the *shape* half of the conjunction only; an unaudited "trust me, it's
  *      small" buys nothing it did not buy before.
@@ -279,6 +399,22 @@ export function resolveOperatorOverride({
   }
 
   const code = suitability?.shape?.code ?? null;
+  // Checked BEFORE the overridable-code test on purpose (Story #4875): when a
+  // footprint trips both a ceiling rule and a risk rule, the shape records the
+  // ceiling rule, which IS overridable — so testing the recorded code alone
+  // would apply the override and send un-landable work to the backstop.
+  const unwaivable = suitability?.unwaivable;
+  if (unwaivable?.present === true) {
+    return refuse(
+      `operator override refused — the predicted footprint also trips the ` +
+        `un-waivable "${unwaivable.code}" rule${
+          unwaivable.classes.length > 0
+            ? ` (${unwaivable.classes.join(', ')})`
+            : ''
+        }; waiving the size prediction cannot make this land light, and the ` +
+        `diff backstop would refuse the finished work. Escalate to /plan.`,
+    );
+  }
   if (!OVERRIDABLE_SHAPE_CODES.includes(code)) {
     return refuse(
       `operator override refused — "${code ?? 'unknown'}" is not an overridable size prediction (overridable: ${OVERRIDABLE_SHAPE_CODES.join(', ')}); risk rules and unknown footprints are non-negotiable`,
@@ -389,11 +525,23 @@ export function resolveLightGateOutcome({
 }
 
 /**
- * Diff-derived backstop (Story #4740 AC-4): re-check the **actual** change set
- * after implementation, because the diff — not the prompt — is the real scope
- * signal. Blocks (rather than landing) when the diff intersects a sensitive-
- * path class, exceeds the file-count ceiling, or cannot be classified. A clean
- * result is the only path that lands light.
+ * Diff-derived backstop (Story #4740 AC-4, re-based on magnitude by Story
+ * #4856): re-check the **actual** change set after implementation, because the
+ * diff — not the prompt — is the real scope signal. Blocks (rather than landing)
+ * when the diff intersects a sensitive-path class, exceeds an implementation
+ * ceiling, or cannot be measured. A clean result is the only path that lands
+ * light.
+ *
+ * Two inputs, two different scopes, and the difference is load-bearing:
+ *
+ *   - `changedFiles` is the **full** change set, companions included, and is
+ *     what sensitive-path derivation reads. Exempting a companion from the
+ *     *count* must never exempt it from *risk* — a test file under a registered
+ *     sensitive class still blocks.
+ *   - `magnitude` is the implementation-only summary from
+ *     {@link module:lib/orchestration/diff-magnitude.summarizeDiffMagnitude}.
+ *     `null` means the magnitude could not be measured, which blocks: absence
+ *     of evidence is not evidence the diff is small.
  *
  * Reuses close's own {@link module:lib/orchestration/review-depth.deriveChangeLevel}
  * — one taxonomy, applied to the predicted shape at the gate and the actual
@@ -403,7 +551,8 @@ export function resolveLightGateOutcome({
  *
  * @param {{
  *   changedFiles?: unknown,
- *   ceilings?: { maxFiles?: number },
+ *   magnitude?: { implFiles?: number, implLines?: number }|null,
+ *   ceilings?: { maxImplLines?: number, maxImplFiles?: number },
  *   injectedRules?: object,
  *   selectSensitivePathClassesFn?: Function,
  * }} [args]
@@ -412,20 +561,19 @@ export function resolveLightGateOutcome({
  *   level: 'low'|'high'|null,
  *   classes: string[],
  *   fileCount: number|null,
- *   ceilings: { maxFiles: number },
+ *   magnitude: { implFiles: number, implLines: number }|null,
+ *   ceilings: { maxImplLines: number, maxImplFiles: number },
  *   reasons: string[],
  * }}
  */
 export function checkLightDiffBackstop({
   changedFiles,
+  magnitude,
   ceilings,
   injectedRules,
   selectSensitivePathClassesFn,
 } = {}) {
-  const maxFiles = normalizeMaxFiles(
-    ceilings?.maxFiles,
-    LIGHT_DIFF_CEILINGS.maxFiles,
-  );
+  const resolved = resolveDiffCeilings(ceilings);
   const files = Array.isArray(changedFiles)
     ? changedFiles.filter((f) => typeof f === 'string' && f.trim() !== '')
     : null;
@@ -436,7 +584,8 @@ export function checkLightDiffBackstop({
       level: null,
       classes: [],
       fileCount: files === null ? null : 0,
-      ceilings: { maxFiles },
+      magnitude: null,
+      ceilings: resolved,
       reasons: [
         'actual change set is unknown or empty — cannot verify the diff is light; escalate to /plan',
       ],
@@ -448,23 +597,12 @@ export function checkLightDiffBackstop({
     injectedRules,
     selectSensitivePathClassesFn,
   });
+  const measured = normalizeMagnitude(magnitude);
 
-  const reasons = [];
-  if (classes.length > 0) {
-    reasons.push(
-      `diff intersects sensitive-path class(es) ${classes.join(', ')} — escalate to /plan (do not land light)`,
-    );
-  }
-  if (files.length > maxFiles) {
-    reasons.push(
-      `diff touches ${files.length} file(s) (> maxFiles ${maxFiles}) — escalate to /plan (do not land light)`,
-    );
-  }
-  if (level !== 'low' && classes.length === 0) {
-    reasons.push(
-      'sensitive-path classification unavailable — cannot verify the diff is non-sensitive; escalate to /plan',
-    );
-  }
+  const reasons = [
+    ...describeSensitivity({ level, classes }),
+    ...describeMagnitude(measured, resolved),
+  ];
 
   const blocked = reasons.length > 0;
   return {
@@ -472,15 +610,80 @@ export function checkLightDiffBackstop({
     level,
     classes,
     fileCount: files.length,
-    ceilings: { maxFiles },
+    magnitude: measured,
+    ceilings: resolved,
     reasons: blocked
       ? reasons
       : [
-          `diff is light: ${files.length} file(s) ≤ ${maxFiles}, no sensitive-path class — safe to land`,
+          `diff is light: ${measured.implLines} implementation line(s) ≤ ${resolved.maxImplLines} ` +
+            `across ${measured.implFiles} implementation file(s) ≤ ${resolved.maxImplFiles} ` +
+            `(${files.length} file(s) total, companions exempt), no sensitive-path class — safe to land`,
         ],
   };
 }
 
+/**
+ * Coerce a magnitude summary into non-negative integer counts, or `null` when
+ * it was not measurable. Pure.
+ *
+ * @param {unknown} magnitude
+ * @returns {{ implFiles: number, implLines: number }|null}
+ */
+function normalizeMagnitude(magnitude) {
+  const implFiles = magnitude?.implFiles;
+  const implLines = magnitude?.implLines;
+  if (!Number.isFinite(implFiles) || !Number.isFinite(implLines)) return null;
+  if (implFiles < 0 || implLines < 0) return null;
+  return { implFiles: Math.floor(implFiles), implLines: Math.floor(implLines) };
+}
+
+/**
+ * Sensitivity objections, over the **full** change set. Pure.
+ *
+ * @param {{ level: 'low'|'high'|null, classes: string[] }} derived
+ * @returns {string[]}
+ */
+function describeSensitivity({ level, classes }) {
+  if (classes.length > 0) {
+    return [
+      `diff intersects sensitive-path class(es) ${classes.join(', ')} — escalate to /plan (do not land light)`,
+    ];
+  }
+  if (level !== 'low') {
+    return [
+      'sensitive-path classification unavailable — cannot verify the diff is non-sensitive; escalate to /plan',
+    ];
+  }
+  return [];
+}
+
+/**
+ * Magnitude objections, over the implementation half only. Pure.
+ *
+ * @param {{ implFiles: number, implLines: number }|null} measured
+ * @param {{ maxImplLines: number, maxImplFiles: number }} ceilings
+ * @returns {string[]}
+ */
+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 /plan',
+    ];
+  }
+  const reasons = [];
+  if (measured.implLines > ceilings.maxImplLines) {
+    reasons.push(
+      `diff changes ${measured.implLines} implementation line(s) (> maxImplLines ${ceilings.maxImplLines}) — escalate to /plan (do not land light)`,
+    );
+  }
+  if (measured.implFiles > ceilings.maxImplFiles) {
+    reasons.push(
+      `diff spans ${measured.implFiles} implementation file(s) (> maxImplFiles ${ceilings.maxImplFiles}) — escalate to /plan (do not land light)`,
+    );
+  }
+  return reasons;
+}
+
 /** Cap on a receipt slug's length — keep the branch/id readable. */
 const RECEIPT_SLUG_MAX = 48;