mandrel 2.60.0 → 2.61.0

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

@@ -1,27 +1,8 @@
 /**
- * lib/orchestration/light-backstop.js — the light path's diff-backstop pass
- * (Story #4856).
- *
- * The backstop is invariant 3 of the light path: after implementation the
- * **actual** change set is re-checked, because the diff — not the prompt — is
- * the real scope signal. This module owns that pass end to end so
- * `deliver-light.js` stays the thin CLI shell it claims to be: it reads the two
- * git surfaces, applies
- * {@link module:lib/orchestration/light-suitability.checkLightDiffBackstop},
- * and resolves what a refusal means.
- *
- * ## Two git surfaces, each used for what it reports reliably
- *
- *   - `--name-only`, via the one canonical `computeChangeSet` enumerator, gives
- *     the clean full file list. Sensitive-path derivation and
- *     implementation-file counting both read it, so the backstop and every
- *     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.
+ * lib/orchestration/light-backstop.js — the light path's diff backstop: the
+ * actual diff, not the prompt, is the real scope signal. Files come from the
+ * canonical `computeChangeSet`, line counts from numstat; both read committed
+ * state, so an empty diff is disambiguated by `hasUncommittedWork`.
  *
  * @module lib/orchestration/light-backstop
  */
@@ -43,8 +24,6 @@ import { hasUncommittedWork } from './worktree-dirty.js';
 const EXIT_BACKSTOP_BLOCKED = 3;
 
 /**
- * Run the diff backstop against a Story branch's actual change set.
- *
  * @param {{
  *   storyId: number,
  *   baseRef?: string,
@@ -76,9 +55,7 @@ function runDiffBackstop({
     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.
+    // Only an enumerated-empty diff can be explained by uncommitted work.
     uncommittedWork:
       Array.isArray(files) && files.length === 0
         ? dirtyProbeFn({ branch: headRef, cwd, gitFn })
@@ -87,8 +64,6 @@ function runDiffBackstop({
 }
 
 /**
- * Is this refusal the one that is NOT about scope?
- *
  * @param {{ refusalClass?: string|null }} result
  * @returns {boolean}
  */
@@ -97,12 +72,8 @@ function isUncommittedRefusal(result) {
 }
 
 /**
- * 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.
+ * `null` preservation means the uncommitted-work refusal, which never pushes
+ * (it would falsely report uncommitted work as safe on `origin`).
  *
  * @param {{
  *   storyId: number,
@@ -119,25 +90,16 @@ function describeBlockedTail({ storyId, preservation, 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
- * exit code, and the log line.
- *
- * A refusal also **preserves** the work before it reports (Story #4875): the
- * implementation is finished and the recycle command hands the receipt to
- * `/mandrel-plan`, so leaving it on an untracked local branch that routine cleanup may
- * reap is not an acceptable end state. Preservation is best-effort and its
- * outcome is reported either way — a failed push degrades the message, never
- * the verdict or the exit code.
+ * Resolve the backstop into verdict, next command, exit code and log line.
+ * A scope refusal first preserves the finished work on `origin`;
+ * a failed push degrades the message, never the verdict.
  *
  * @param {{
  *   storyId: number,
  *   runFn?: typeof runDiffBackstop,
  *   handleBlockedFn?: typeof handleBlockedBackstop,
  *   preserveFn?: typeof preserveRefusedWork,
- * }} args Any further keys (`baseRef`, `cwd`, `computeFn`, `readRowsFn`,
- *   `dirtyProbeFn`, `gitFn`, `injectedRules`) forward to the backstop run, so
- *   the git-surface join is drivable through this one entry point.
+ * }} args Further keys forward to the backstop run.
  * @returns {Promise<{
  *   result: ReturnType<typeof checkLightDiffBackstop>,
  *   nextCommand: string|null,

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

@@ -1,39 +1,12 @@
 /**
  * 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 `/mandrel-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 `/mandrel-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.
+ * refuses a scope (verdicts live in `light-suitability`): recycle the
+ * receipt through `/mandrel-plan <id>` (which supersedes it) rather than
+ * orphaning it, record the refusal as friction so ceilings can be
+ * recalibrated from evidence, and publish the refused branch so cleanup
+ * cannot delete the only copy. The receipt is created before the backstop
+ * because its id drives the lease, branch, labels and commit subjects.
+ * Telemetry failure never changes a verdict.
  *
  * @module lib/orchestration/light-escalation
  */
@@ -47,8 +20,6 @@ import {
 import { LIGHT_REFUSAL_CLASSES } from './light-suitability.js';
 
 /**
- * The `/mandrel-plan` invocation that owns a Story the light path could not land.
- *
  * @param {number} storyId
  * @returns {string}
  */
@@ -57,12 +28,8 @@ function buildRecycleCommand(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).
+ * Uncommitted work is not a scope refusal: re-run the backstop after
+ * committing rather than recycling a fine receipt.
  *
  * @param {number} storyId
  * @returns {string}
@@ -72,15 +39,9 @@ function buildRerunBackstopCommand(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 escalating 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.
+ * `--amends` (with or without a leading `#`) as an issue number, else `null`. The only
+ * Story a gate-stage refusal can be attributed to (no receipt exists yet);
+ * never fabricate one.
  *
  * @param {unknown} amends
  * @returns {number|null}
@@ -93,9 +54,6 @@ function normalizeAmendsId(amends) {
 }
 
 /**
- * Record a suitability-gate refusal (`escalate-plan`) as friction, attributed
- * to the `--amends` target when there is one.
- *
  * @param {{
  *   gate: object,
  *   amends?: unknown,
@@ -122,19 +80,14 @@ export async function recordGateRefusal({
 }
 
 /**
- * Handle a blocked diff backstop: record the refusal as friction and return the
- * `/mandrel-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.
+ * Record a blocked backstop as friction and return the next command.
  *
  * @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.
+ * }} args
  * @returns {Promise<string>} The recycle command.
  */
 export async function handleBlockedBackstop({
@@ -157,9 +110,7 @@ export async function handleBlockedBackstop({
       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.
+      // Unpreserved work is a worse event; the roll-up must tell them apart.
       preserved: preservation?.preserved ?? null,
       refusalClass,
     },
@@ -170,24 +121,9 @@ export async function handleBlockedBackstop({
 }
 
 /**
- * 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 `/mandrel-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.
+ * Push a refused run's branch to `origin` (no PR, no merge): a branch with
+ * no remote ref is what cleanup sweeps treat as disposable. Total and
+ * idempotent; a push failure is reported, never thrown.
  *
  * @param {{
  *   storyId: number,
@@ -235,10 +171,7 @@ export function preserveRefusedWork({
 }
 
 /**
- * Record a light-path scope rejection as friction.
- *
- * Total: never throws, and returns `false` rather than propagating when the
- * signals surface is unavailable.
+ * Never throws; `false` when the signals surface is unavailable.
  *
  * @param {{
  *   storyId?: number|null,
@@ -247,9 +180,8 @@ export function preserveRefusedWork({
  *   reasons?: string[],
  *   details?: object,
  *   emitFn?: typeof emitRuntimeFriction,
- * }} 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.
+ * }} args `category` defaults to the unclassified bucket (gate refusals
+ *   precede any diff).
  * @returns {Promise<boolean>}
  */
 async function recordScopeFriction({