mandrel 2.24.0 → 2.25.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/watcher.js

@@ -132,6 +132,29 @@ export function normalizeCheckState(raw) {
  */
 export const extractPrNumber = parsePrNumberFromUrl;
 
+/**
+ * The `gh --repo` flag pair for an optional `owner/repo` target, or an empty
+ * argv fragment when the repository is inferred from the cwd's remote.
+ *
+ * `gh` resolves a *cross-repository* PR reference only through this flag — it
+ * has no `<owner/repo>#<number>` argument form, and a caller that builds one
+ * gets it parsed as a **branch name** instead (every `--repo` invocation of the
+ * watch CLI failed on that, reported as a misleading `gh-checks-failed`). Pure
+ * — one place builds the fragment so no port can forget it.
+ *
+ * Module-private on purpose: the three ports below are the only callers, and
+ * the flag is asserted through them (a real-spawn argv probe), never by
+ * importing this helper — an export existing solely for a test is dead in the
+ * `--production` reachability ratchet.
+ *
+ * @param {string|null|undefined} repo `owner/repo`, or nullish to infer.
+ * @returns {string[]}
+ */
+function ghRepoFlag(repo) {
+  const trimmed = String(repo ?? '').trim();
+  return trimmed.length > 0 ? ['--repo', trimmed] : [];
+}
+
 /**
  * Default `gh pr checks` spawn. Always invokes with `--required` so the
  * returned set is authoritative for branch-protection gating. The
@@ -139,7 +162,7 @@ export const extractPrNumber = parsePrNumberFromUrl;
  *
  * Exported so tests can stub.
  */
-function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrChecks({ prUrl, cwd, repo, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
     [
@@ -149,6 +172,7 @@ function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
       '--required',
       '--json',
       'name,state,bucket,workflow',
+      ...ghRepoFlag(repo),
     ],
     { cwd, encoding: 'utf-8', shell: false },
   );
@@ -164,10 +188,10 @@ function ghPrChecks({ prUrl, cwd, spawnFn = spawnSync }) {
  * can detect the BEHIND condition (PR head is behind its base branch)
  * AFTER every required check is green. Exported so tests can stub.
  */
-function ghPrView({ prUrl, cwd, spawnFn = spawnSync }) {
+function ghPrView({ prUrl, cwd, repo, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
-    ['pr', 'view', prUrl, '--json', 'mergeStateStatus'],
+    ['pr', 'view', prUrl, '--json', 'mergeStateStatus', ...ghRepoFlag(repo)],
     { cwd, encoding: 'utf-8', shell: false },
   );
   return {
@@ -202,12 +226,16 @@ function parseMergeStateStatus(stdout) {
  * loop to fast-forward the PR head with its base branch. Exported so
  * tests can stub and assert call counts.
  */
-function ghPrUpdateBranch({ prUrl, cwd, spawnFn = spawnSync }) {
-  const result = spawnFn('gh', ['pr', 'update-branch', prUrl], {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-  });
+function ghPrUpdateBranch({ prUrl, cwd, repo, spawnFn = spawnSync }) {
+  const result = spawnFn(
+    'gh',
+    ['pr', 'update-branch', prUrl, ...ghRepoFlag(repo)],
+    {
+      cwd,
+      encoding: 'utf-8',
+      shell: false,
+    },
+  );
   return {
     status: result.status ?? 1,
     stdout: result.stdout ?? '',
@@ -355,6 +383,7 @@ function defaultSleep(ms) {
  * @param {object} opts
  * @param {string} opts.prUrl
  * @param {string} opts.cwd
+ * @param {string|null} [opts.repo] `owner/repo` passed to `gh` as `--repo`.
  * @param {object} opts.outcomes  Initial `{ checkName: outcome }` map.
  * @param {number} opts.polls     Current poll counter (mutated in-place by caller).
  * @param {number} opts.maxPolls  Hard cap on total poll iterations.
@@ -367,6 +396,7 @@ function defaultSleep(ms) {
 export async function pollUntilTerminal({
   prUrl,
   cwd,
+  repo = null,
   outcomes,
   polls,
   maxPolls,
@@ -380,7 +410,7 @@ export async function pollUntilTerminal({
   while (!allTerminal(currentOutcomes) && currentPolls < maxPolls) {
     await sleepFn(pollIntervalMs);
     currentPolls += 1;
-    const probe = ghPrChecksFn({ prUrl, cwd });
+    const probe = ghPrChecksFn({ prUrl, cwd, repo });
     const entries = parseGhPrChecks(probe.stdout);
     if (entries.length === 0 && probe.status !== 0 && probe.status !== 8) {
       // Transient `gh` failure — log and continue. The outer
@@ -411,6 +441,9 @@ export async function pollUntilTerminal({
  * @param {object} opts
  * @param {string} opts.prUrl              PR URL or number (passed to `gh` verbatim).
  * @param {string} opts.cwd
+ * @param {string|null} [opts.repo]        `owner/repo` target, threaded to every
+ *   `gh` port as a real `--repo` flag (Story #4890). Nullish infers the
+ *   repository from the cwd's remote — the behaviour every in-repo caller wants.
  * @param {number} opts.maxPolls           Hard cap on total poll iterations per arm.
  * @param {number} opts.maxUpdates         Cap on `gh pr update-branch` recovery calls.
  * @param {number} [opts.maxResumes]       Story #4358: after the poll cap fires with
@@ -444,17 +477,19 @@ export async function pollUntilTerminal({
  *   terminal: boolean,
  *   green: boolean,
  *   stillRunning: boolean,
+ *   requiredChecksEmpty?: boolean,
  *   error?: string,
  * }>}
  *   `outcomes` is schema-valid (no `'pending'` — leftover pending is
  *   promoted to `'still-running'` when the cap and resume budget are both
  *   exhausted with no failed check). `stillRunning` is true in exactly
- *   that case (slow CI, not red). `error` is set only when the first
- *   probe could not resolve the required-check set.
+ *   that case (slow CI, not red). `requiredChecksEmpty` / `error` are set
+ *   only when the first probe resolved NO required-check names.
  */
 export async function watchPrToTerminal({
   prUrl,
   cwd,
+  repo = null,
   maxPolls,
   maxUpdates,
   maxResumes = 0,
@@ -469,15 +504,25 @@ export async function watchPrToTerminal({
   // First probe: resolve the required-check name set at runtime. Reuse a
   // caller-supplied probe (the listener already issued one to resolve the
   // required check names) so we never double-spend the first `gh` call.
-  const first = firstProbe ?? ghPrChecksFn({ prUrl, cwd });
+  const first = firstProbe ?? ghPrChecksFn({ prUrl, cwd, repo });
   // `gh` exits 8 when checks are still pending; this is expected and
   // does not indicate failure. Any other non-zero status with no
   // parseable JSON body is a genuine failure.
   const firstEntries = parseGhPrChecks(first.stdout);
-  if (firstEntries.length === 0 && first.status !== 0 && first.status !== 8) {
-    logger.warn?.(
-      `[Watcher] gh pr checks failed (status=${first.status}): ${first.stderr}`,
-    );
+  if (firstEntries.length === 0) {
+    // NO required-check name resolved. Never enter the poll loop on that:
+    // `allTerminal({})` is vacuously true, so the loop would exit on its
+    // first evaluation and report a terminal-but-not-green arm — a red
+    // verdict with no failing check in it (Story #4890). The name set is
+    // resolved exactly once per call, so converging on a context that
+    // attaches later means calling this function again; return the
+    // empty-set signal and let the caller's attach window re-resolve it.
+    const ghFaulted = first.status !== 0 && first.status !== 8;
+    if (ghFaulted) {
+      logger.warn?.(
+        `[Watcher] gh pr checks failed (status=${first.status}): ${first.stderr}`,
+      );
+    }
     return {
       outcomes: {},
       requiredChecks: [],
@@ -487,7 +532,12 @@ export async function watchPrToTerminal({
       terminal: false,
       green: false,
       stillRunning: false,
-      error: `gh-checks-failed:status=${first.status}`,
+      requiredChecksEmpty: true,
+      // `gh` overloads a non-zero exit for "no required check is attached
+      // right now" AND for a genuine fault, and its stderr prose is not a
+      // contract — so the status is reported and the *classification* is the
+      // caller's, made against a structural probe of the PR itself.
+      error: `gh-checks-${ghFaulted ? 'failed' : 'empty'}:status=${first.status}`,
     };
   }
 
@@ -512,6 +562,7 @@ export async function watchPrToTerminal({
       ({ outcomes, polls } = await pollUntilTerminal({
         prUrl,
         cwd,
+        repo,
         outcomes,
         polls,
         maxPolls,
@@ -529,7 +580,7 @@ export async function watchPrToTerminal({
       // indefinitely.
       if (!allTerminal(outcomes) || !allGreen(outcomes)) break;
       if (updatesApplied >= maxUpdates) break;
-      const view = ghPrViewFn({ prUrl, cwd });
+      const view = ghPrViewFn({ prUrl, cwd, repo });
       if (view.status !== 0) {
         logger.warn?.(
           `[Watcher] gh pr view failed (status=${view.status}): ${view.stderr}`,
@@ -538,7 +589,7 @@ export async function watchPrToTerminal({
       }
       const mergeStateStatus = parseMergeStateStatus(view.stdout);
       if (mergeStateStatus !== 'BEHIND') break;
-      const update = ghPrUpdateBranchFn({ prUrl, cwd });
+      const update = ghPrUpdateBranchFn({ prUrl, cwd, repo });
       if (update.status !== 0) {
         logger.warn?.(
           `[Watcher] gh pr update-branch failed (status=${update.status}): ${update.stderr}`,

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

@@ -23,7 +23,10 @@
 
 import { computeChangeSet } from './change-set.js';
 import { readNumstatRows, summarizeDiffMagnitude } from './diff-magnitude.js';
-import { handleBlockedBackstop } from './light-escalation.js';
+import {
+  handleBlockedBackstop,
+  preserveRefusedWork,
+} from './light-escalation.js';
 import { checkLightDiffBackstop } from './light-suitability.js';
 
 /** Exit code when the diff backstop blocked the land. */
@@ -66,16 +69,25 @@ function runDiffBackstop({
  * 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
+ * `/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.
+ *
  * @param {{
  *   storyId: number,
  *   runFn?: typeof 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.
  * @returns {Promise<{
  *   result: ReturnType<typeof checkLightDiffBackstop>,
  *   nextCommand: string|null,
+ *   preservation: ReturnType<typeof preserveRefusedWork>|null,
  *   exitCode: number,
  *   message: string,
  * }>}
@@ -84,6 +96,7 @@ export async function resolveBackstopOutcome({
   storyId,
   runFn = runDiffBackstop,
   handleBlockedFn = handleBlockedBackstop,
+  preserveFn = preserveRefusedWork,
   ...seams
 } = {}) {
   const result = runFn({ storyId, ...seams });
@@ -91,17 +104,21 @@ export async function resolveBackstopOutcome({
     return {
       result,
       nextCommand: null,
+      preservation: null,
       exitCode: 0,
       message: `[deliver-light] diff backstop clean for Story #${storyId}.`,
     };
   }
-  const nextCommand = await handleBlockedFn({ storyId, result });
+  const preservation = preserveFn({ storyId, cwd: seams.cwd });
+  const nextCommand = await handleBlockedFn({ storyId, result, preservation });
   return {
     result,
     nextCommand,
+    preservation,
     exitCode: EXIT_BACKSTOP_BLOCKED,
     message:
       `[deliver-light] diff backstop BLOCKED Story #${storyId}: ` +
-      `${result.reasons.join('; ')} — recycle the receipt with "${nextCommand}"`,
+      `${result.reasons.join('; ')} — ${preservation.detail}; ` +
+      `recycle the receipt with "${nextCommand}"`,
   };
 }

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

@@ -2,8 +2,8 @@
  * lib/orchestration/light-escalation.js — what the light path does when it
  * refuses a scope (Story #4856).
  *
- * Two behaviors, both previously missing, and both about a refusal rather than
- * a verdict — the verdicts live in
+ * 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
@@ -25,12 +25,20 @@
  *      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,
@@ -106,14 +114,16 @@ export async function recordGateRefusal({
  * @param {{
  *   storyId: number,
  *   result: object,
+ *   preservation?: ReturnType<typeof preserveRefusedWork>,
  *   recordFrictionFn?: typeof recordScopeFriction,
  * }} args `result` is a {@link module:lib/orchestration/light-suitability.checkLightDiffBackstop}
- *   verdict.
+ *   verdict; `preservation` is the {@link preserveRefusedWork} outcome.
  * @returns {Promise<string>} The recycle command.
  */
 export async function handleBlockedBackstop({
   storyId,
   result,
+  preservation,
   emitFn,
   recordFrictionFn = recordScopeFriction,
 } = {}) {
@@ -128,11 +138,80 @@ 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.
+      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.
  *

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

@@ -82,6 +82,72 @@ export const OVERRIDABLE_SHAPE_CODES = Object.freeze([
   SHAPE_CODES.DEPLOYABLE_SPAN,
 ]);
 
+/**
+ * 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
@@ -222,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,
@@ -246,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,
   };
 }
 
@@ -274,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.
@@ -317,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`,

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -451,6 +451,7 @@ export async function runPlanPersist({
     stories: rawStories = null,
     techSpecContent = null,
     planAcceptance = null,
+    planContextEnvelope = null,
   } = artifacts ?? {};
   const {
     forceReview = false,
@@ -538,6 +539,12 @@ export async function runPlanPersist({
     sharedSpec: techSpecContent,
     planAcceptance: planAcceptance ?? undefined,
     sourceTicketIds,
+    // The seed this plan was authored from is the provenance source: an audit
+    // sweep's Single-plan seed carries the `audit-fingerprints` /
+    // `audit-semantic-keys` footers, which assembly copies into every persisted
+    // Story body so the next sweep recognises what it already planned
+    // (Story #4877). Empty for a `--tickets` run, which is a no-op.
+    provenanceSource: planContextEnvelope?.seed?.content ?? '',
   });
 
   // Effective complexity route (Story #4722): the planner's authored lite

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -17,6 +17,7 @@
 
 import { createHash } from 'node:crypto';
 import { applyBlockedByDependencies } from '../../../providers/github/blocked-by-add.js';
+import { carryProvenanceFooters } from '../../findings/route-finding.js';
 import { Logger } from '../../Logger.js';
 import { AGENT_LABELS, TYPE_LABELS } from '../../label-constants.js';
 import {
@@ -392,7 +393,18 @@ function assembleOnePlanStory(ticket, opts) {
   });
   // Body first: the fingerprint is an identity over the *assembled* content,
   // so it cannot be computed until that content exists.
-  const body = serializeStoryBody({ ...folded, depends_on });
+  const serialized = serializeStoryBody({ ...folded, depends_on });
+  // Carry audit dedup provenance out of the seed this plan was authored from
+  // (Story #4877). The audit sweep's Single-plan path stamps the
+  // `audit-fingerprints` / `audit-semantic-keys` footers into the seed it hands
+  // `/plan`; without this the persisted Story carries no provenance and the
+  // next sweep re-files work it already planned. Mechanical on purpose — the
+  // authoring agent is not asked to notice HTML comments in a one-pager. A
+  // non-audit seed carries no footers, so this is a no-op there.
+  const { body } = carryProvenanceFooters({
+    from: opts.provenanceSource ?? '',
+    into: serialized,
+  });
   const fingerprint = planStoryFingerprint({ slug, title, body });
   return {
     story: {