mandrel 2.58.0 → 2.60.0

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -101,22 +101,37 @@ import { classifyStory, storyIdOf } from './ready-set.js';
  * Ids outside the probed set are ignored: they are not part of this run and
  * must not consume its cap.
  *
+ * The second arm is also reported on its own, as `unlabelled`. A claimed id
+ * that still reads `agent::ready` is in flight either because its init is
+ * still running or because the spawn that claimed it never started one, and
+ * those two are indistinguishable here — but only the second pins the id in
+ * the caller's ledger forever. Live state cannot tell them apart; the operator
+ * can, so the fact is surfaced rather than acted on (Story #5363).
+ *
  * @param {Array<{id?: number, number?: number, labels?: string[], state?: string}>} storyRecords
  * @param {Iterable<number>} [dispatched] Ids the host has spawned.
- * @returns {Set<number>} In-flight Story ids.
+ * @returns {{inFlight: Set<number>, unlabelled: Set<number>}} In-flight Story
+ *   ids, and the subset of them claimed by the caller that live state still
+ *   reports as `agent::ready`.
  */
 function deriveInFlightIds(storyRecords, dispatched = []) {
   const claimed = new Set(dispatched);
-  const inFlight = new Set();
+  // Bucketed by live class rather than tested twice. The admission rule is
+  // unchanged; it is only that the `ready` bucket IS the claimed-but-unlabelled
+  // set, since `ready` is the one class the rule admits on the caller's claim.
+  const byClass = { executing: new Set(), ready: new Set() };
   for (const rec of storyRecords) {
     const id = storyIdOf(rec);
     if (id === null) continue;
     const cls = classifyStory(rec);
     if (cls === 'executing' || (claimed.has(id) && cls === 'ready')) {
-      inFlight.add(id);
+      byClass[cls].add(id);
     }
   }
-  return inFlight;
+  return {
+    inFlight: new Set([...byClass.executing, ...byClass.ready]),
+    unlabelled: byClass.ready,
+  };
 }
 
 /**
@@ -251,6 +266,7 @@ export function createProbeContext({
  *   doneIds: Set<number>,
  *   inFlight: number,
  *   blockedIds: number[],
+ *   stalledDispatch: number[],
  *   foreignHeld: Array<{id: number, holder: string}>
  * }>}
  */
@@ -294,7 +310,10 @@ export async function probeLiveState({
   // They are consumed in-process by `planReadySet` and never serialized into
   // the beat envelope, which stays a list of ids.
   const bodyById = new Map(stories.map((s) => [s.id, s.body ?? '']));
-  const inFlightIds = deriveInFlightIds(stories, dispatched);
+  const { inFlight: inFlightIds, unlabelled } = deriveInFlightIds(
+    stories,
+    dispatched,
+  );
   // A Story another operator's lease holds occupies a (global) dispatch slot
   // just like an in-flight one: fold it into the in-flight set so it is both
   // withheld (via the projected label) and excluded from a false wedge, but
@@ -322,6 +341,13 @@ export async function probeLiveState({
     doneIds: new Set(envelope.done),
     inFlight: inFlightIds.size,
     blockedIds: deriveBlockedIds(stories),
+    // Claimed by the caller, still labelled `agent::ready`: a live init window
+    // or a spawn that never reached one. Reported, never released here. A
+    // foreign lease is its own withhold reason and outranks the claim, so it
+    // is subtracted — one Story must not carry two recoveries.
+    stalledDispatch: [...unlabelled]
+      .filter((id) => !foreignHeld.has(id))
+      .sort((a, b) => a - b),
     foreignHeld: [...foreignHeld].map(([id, holder]) => ({ id, holder })),
   };
 }

package/.agents/scripts/merge-baseline.js

@@ -36,9 +36,8 @@
  *
  * ## Not every `baselines/*.json` is an envelope
  *
- * That glob also matches arch-cycles, cyclomatic, dead-exports, audit-ledger,
- * context-budget and workflow-citations — files with their own shapes and no
- * row identity. Anything whose `$schema` is not a known per-kind envelope is
+ * That glob also matches arch-cycles, cyclomatic, dead-exports, audit-ledger
+ * and context-budget — files with their own shapes and no row identity. Anything whose `$schema` is not a known per-kind envelope is
  * handed straight back to `git merge-file`, so registering the driver cannot
  * change their behaviour.
  */
@@ -164,8 +163,8 @@ function delegateToGit(basePath, oursPath, theirsPath) {
  *     `git merge-file` even though `.gitattributes` routes them here, so the
  *     attribute promised a row merge the driver never performed.
  *
- * Anything else — arch-cycles, audit-ledger, context-budget,
- * workflow-citations — resolves `null` and is handed back to git unchanged.
+ * Anything else — arch-cycles, audit-ledger, context-budget — resolves `null`
+ * and is handed back to git unchanged.
  *
  * @param {unknown} ours
  * @param {unknown} theirs

package/.agents/scripts/plan-context.js

@@ -24,21 +24,22 @@
  *                             scratch (Story #4741). Envelope carries `amends`.
  *
  * Flags:
- *   --out <path>     Write the envelope to <path> (parent dirs created).
- *                    `/mandrel-plan` points this at `<plan-dir>/plan-context.json`,
- *                    which is where `plan-persist.js` auto-discovers the
- *                    `--tickets` source ids from (Story #4554). Without a
- *                    captured envelope persist cannot know a `--tickets` run
- *                    happened, and superseding degrades to the
- *                    `--source-tickets` flag. With --out, stdout carries a
- *                    compact digest naming the artifact instead of the full
- *                    envelope (Story #4708 script-output contract).
- *   --pretty         Pretty-print the JSON envelope (no-op with --out).
+ *   --out <path>     Override where the envelope is written (parent dirs
+ *                    created). **Optional since Story #5342** — with no
+ *                    `--out` the envelope lands at
+ *                    `<tempRoot>/plan-<slug>/plan-context.json`, the plan
+ *                    directory `/mandrel-plan` would have named by hand, and
+ *                    `stories.template.json` lands beside it. That is where
+ *                    `plan-persist.js` auto-discovers the `--tickets` source
+ *                    ids from (Story #4554); without a captured envelope
+ *                    persist cannot know a `--tickets` run happened, and
+ *                    superseding degrades to the `--source-tickets` flag.
+ *   --pretty         Pretty-print the written JSON envelope.
  *
  * stdout is reserved for a single JSON payload (Story #2278 discipline) —
- * the envelope, or the digest when --out captures it:
- * `routeAllOutputToStderr()` runs before any pipeline code so the stream
- * is unconditionally parseable by `JSON.parse`.
+ * the compact digest naming the written artifacts (Story #4708
+ * script-output contract): `routeAllOutputToStderr()` runs before any
+ * pipeline code so the stream is unconditionally parseable by `JSON.parse`.
  *
  * Exit codes:
  *   0 — envelope emitted.
@@ -54,6 +55,8 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import {
+  getPaths,
+  PROJECT_ROOT,
   resolveConfig,
   validateOrchestrationConfig,
 } from './lib/config-resolver.js';
@@ -66,6 +69,77 @@ import {
 import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { createProvider } from './lib/provider-factory.js';
 
+/** Longest slug segment a default plan directory carries. */
+const PLAN_SLUG_MAX_LENGTH = 48;
+
+/**
+ * Reduce free text to the hyphen-case segment a plan directory is named by.
+ *
+ * Deliberately lossy: the slug is a human-readable handle on a temp
+ * directory, not an identity — two runs from the same seed land in the same
+ * directory and the second overwrites the first, which is the idempotent
+ * behaviour the operator already got from typing the same `--out` twice.
+ *
+ * @param {string} raw
+ * @returns {string} A non-empty hyphen-case slug (`plan` when nothing survives).
+ */
+export function slugifyPlanLabel(raw) {
+  const slug = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, PLAN_SLUG_MAX_LENGTH)
+    .replace(/-+$/, '');
+  return slug === '' ? 'plan' : slug;
+}
+
+/**
+ * Resolve where the envelope is written when the operator passed no `--out`
+ * (Story #5342).
+ *
+ * `--out` was mandatory in practice and optional in the CLI: persist
+ * auto-discovers the envelope and the `stories.template.json` beside it from
+ * the plan directory, so a run without it silently lost superseding and the
+ * authoring skeleton. The path it always pointed at is derivable — the
+ * configured `tempRoot`, a `plan-<slug>` directory named for what is being
+ * planned — so the CLI derives it rather than asking.
+ *
+ * Exported for tests: this is the join where a missing flag stops costing
+ * the plan its source ids.
+ *
+ * @param {object} args
+ * @param {string} args.mode One of `seed` | `seed-file` | `tickets` | `amends`.
+ * @param {string} [args.seedText]
+ * @param {string} [args.seedFilePath]
+ * @param {number[]} [args.ticketIds]
+ * @param {number} [args.amendsId]
+ * @param {object} [args.config] Resolved config (for `project.paths.tempRoot`).
+ * @param {string} [args.cwd]
+ * @returns {string} Absolute path to the envelope file.
+ */
+export function resolveDefaultOutPath({
+  mode,
+  seedText,
+  seedFilePath,
+  ticketIds,
+  amendsId,
+  config,
+  cwd = PROJECT_ROOT,
+}) {
+  const byMode = {
+    amends: () => `amends-${amendsId}`,
+    tickets: () => `tickets-${(ticketIds ?? []).join('-')}`,
+    'seed-file': () => path.parse(String(seedFilePath ?? '')).name,
+  };
+  const label = (byMode[mode] ?? (() => String(seedText ?? '')))();
+  return path.resolve(
+    cwd,
+    getPaths(config).tempRoot,
+    `plan-${slugifyPlanLabel(label)}`,
+    'plan-context.json',
+  );
+}
+
 /**
  * Parse a comma-/space-separated ticket id list into positive integers.
  *
@@ -109,8 +183,10 @@ export function parseAmendsId(raw) {
 }
 
 /**
- * Build the envelope and write it to `stdout` as a single JSON line
- * (or pretty-printed with --pretty). Exported for tests.
+ * Build the envelope, write it (plus the `stories.template.json` skeleton)
+ * to `outPath` — or to the derived default when none was passed
+ * (Story #5342) — and print the compact digest on stdout. Exported for
+ * tests.
  *
  * @param {object} args
  * @returns {Promise<object>} the emitted envelope.
@@ -145,14 +221,26 @@ export async function emitPlanContext({
   const json = pretty
     ? JSON.stringify(envelope, null, 2)
     : JSON.stringify(envelope);
-  if (outPath) {
+  const resolvedOut =
+    outPath ??
+    resolveDefaultOutPath({
+      mode,
+      seedText,
+      seedFilePath,
+      ticketIds,
+      amendsId,
+      config,
+      cwd: cwd ?? undefined,
+    });
+  {
     // Script-output contract (Story #4708, AC-5): the full envelope is a
     // ~40KB artifact that would ride resident in the transcript for every
-    // later turn. When it is captured to disk anyway, stdout carries a
-    // compact digest naming the artifact instead of the payload itself.
-    await writeEnvelopeFile(outPath, json);
-    await writeStoriesTemplateFile(outPath, envelope);
-    const resolved = path.resolve(outPath);
+    // later turn. It is always captured to disk (Story #5342 derives the
+    // path when `--out` is absent), so stdout carries a compact digest
+    // naming the artifacts instead of the payload itself.
+    await writeEnvelopeFile(resolvedOut, json);
+    await writeStoriesTemplateFile(resolvedOut, envelope);
+    const resolved = path.resolve(resolvedOut);
     const digest = {
       digest: 'plan-context',
       mode: envelope.mode,
@@ -182,8 +270,6 @@ export async function emitPlanContext({
       amends: envelope.amends ? { id: envelope.amends.id } : null,
     };
     stdout.write(`${JSON.stringify(digest)}\n`);
-  } else {
-    stdout.write(`${json}\n`);
   }
   return envelope;
 }
@@ -216,8 +302,8 @@ async function writeEnvelopeFile(outPath, json) {
  * Emit the ready-to-fill Story authoring template next to the captured
  * envelope (Story #4707 — one-shot authoring). The planner copies it to
  * `stories.json` and fills the placeholders; no step of the authoring path
- * requires reading `story-body.js` source. Written whenever `--out` is
- * passed, and throwing on failure for the same reason the envelope write
+ * requires reading `story-body.js` source. Written on every run (Story
+ * #5342), and throwing on failure for the same reason the envelope write
  * does: a silently missing template re-opens the format-discovery loop it
  * exists to close. The envelope's advisory `complexitySignals` are threaded
  * through so the skeleton's `changes[]` arrive pre-resolved to
@@ -346,14 +432,17 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/plan-context.js (--seed "<text>" | --seed-file <path> | --tickets <ids> | --amends <id>) [--out <path>] [--pretty]',
     summary:
-      'Build the /mandrel-plan authoring-context envelope on stdout. Exactly one entry form must be supplied.',
+      'Build the /mandrel-plan authoring-context envelope. Writes it (and stories.template.json) under <tempRoot>/plan-<slug>/ and prints the digest on stdout. Exactly one entry form must be supplied.',
     flags: [
       ['--seed "<text>"', 'Inline seed prose.'],
       ['--seed-file <path>', 'Seed document to read.'],
       ['--tickets <ids>', 'Comma-separated existing ticket ids to re-plan.'],
       ['--amends <id>', 'Amend the Spec of an existing Story.'],
-      ['--out <path>', 'Write the envelope to a file instead of stdout.'],
-      ['--pretty', 'Pretty-print the JSON envelope.'],
+      [
+        '--out <path>',
+        'Override the derived <tempRoot>/plan-<slug>/plan-context.json path.',
+      ],
+      ['--pretty', 'Pretty-print the written JSON envelope.'],
     ],
   },
 });

package/.agents/scripts/plan-persist.js

@@ -10,8 +10,8 @@
  *   changes[] repair → ticket validator / DAG → reachability →
  *   split-policy partition → fold Spec into each Story body →
  *   createIssue(s) with type::story, resumably by plan fingerprint (NOT
- *   agent::ready) → story-plan-state on every Story;
- *   plan-summary on the primary → flip every Story to agent::ready →
+ *   agent::ready) → one `story-plan-state` comment (the plan summary) on
+ *   every Story → flip every Story to agent::ready →
  *   comment + close superseded source tickets → temp cleanup + stale reap.
  *
  * Story #4542 retired the authored risk verdict: persist neither requires nor
@@ -29,7 +29,6 @@
  *   --plan-context <file>     Optional explicit path to the `plan-context.js`
  *                             envelope. Its `sourceTickets[]` is what makes
  *                             `--tickets` superseding work without a flag
- *   --plan-acceptance <file>  Optional JSON string[] for partition coverage
  *   --source-tickets <ids>    Explicit OVERRIDE of the envelope-derived source
  *                             ids, for hand-driven runs. Each id must be
  *                             claimed by exactly one Story's `supersedes[]`;
@@ -37,20 +36,16 @@
  *   --no-close-superseded     Keep the source tickets open (no comment, no
  *                             close) — for a genuinely partial supersede
  *   --dry-run                 Assemble + validate without GitHub writes
- *   --chain-on-clean          Fast path (Story #4741; any plan since Story
- *                             #5312): run the write-free dry-run first, and
- *                             when it passes clean chain straight into the
- *                             real persist in the SAME invocation, collapsing
- *                             the two operator round-trips into one. A
- *                             dry-run failure stops before any createIssue.
- *                             Ignored when `--dry-run` is also set
  *   --force-review            Operator-forced review stop before persist lands
  *
- * Run `--dry-run` first. It exercises every gate — the changes[] repair, the
- * validator, DAG, reachability, split/supersede partition, Spec fold —
- * write-free, and lists every warning (a footprint probe that disagrees with
- * the base branch, an open question in a body) so an authoring mistake
- * surfaces before a single issue exists.
+ * **Persist is one command (Story #5342).** Without `--dry-run` the CLI runs
+ * the write-free dry-run first — the
+ * changes[] repair, the validator, DAG, reachability, split/supersede
+ * partition, Spec fold — and, when the gate list comes back clean, chains
+ * straight into the real persist in the SAME invocation. A dry-run failure
+ * stops before any `createIssue`, and the run lists every warning (a
+ * footprint probe that disagrees with the base branch, an empty `verify[]`,
+ * an open question in a body) either way. `--dry-run` still creates nothing.
  *
  * stdout is reserved for the JSON result (Story #2278 discipline, extended to
  * this CLI by Story #4541): `routeAllOutputToStderr()` runs before any
@@ -83,12 +78,11 @@ import {
 } from './lib/orchestration/plan-persist/plan-context-source.js';
 import {
   runPlanPersist,
-  writeCheckpointV2,
+  writePlanSummaryComment,
 } from './lib/orchestration/plan-persist/run-plan-persist.js';
 import {
   buildPlanSummaryCommentBody,
   buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
 } from './lib/orchestration/plan-persist/summary.js';
 import { resolveSourceTicketIds } from './lib/orchestration/plan-persist/supersede-ops.js';
 import { createProvider } from './lib/provider-factory.js';
@@ -96,9 +90,8 @@ import { createProvider } from './lib/provider-factory.js';
 export {
   buildPlanSummaryCommentBody,
   buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
   runPlanPersist,
-  writeCheckpointV2,
+  writePlanSummaryComment,
 };
 
 const CLI_OPTIONS = {
@@ -106,12 +99,10 @@ const CLI_OPTIONS = {
   'tech-spec': { type: 'string' },
   'plan-dir': { type: 'string' },
   'plan-context': { type: 'string' },
-  'plan-acceptance': { type: 'string' },
   'source-tickets': { type: 'string' },
   'close-superseded': { type: 'boolean', default: true },
   'no-close-superseded': { type: 'boolean', default: false },
   'dry-run': { type: 'boolean', default: false },
-  'chain-on-clean': { type: 'boolean', default: false },
   'force-review': { type: 'boolean', default: false },
   'epic-title': { type: 'string' },
   'epic-goal': { type: 'string' },
@@ -121,9 +112,8 @@ const CLI_OPTIONS = {
 const USAGE =
   'Usage: plan-persist.js --stories <file> ' +
   '[--tech-spec <file>] [--plan-dir <dir>] [--plan-context <file>] ' +
-  '[--plan-acceptance <file>] ' +
   '[--source-tickets <ids>] [--no-close-superseded] ' +
-  '[--dry-run] [--chain-on-clean] [--force-review] ' +
+  '[--dry-run] [--force-review] ' +
   '[--epic-title <text> --epic-goal <text> | --epic <id>]';
 
 async function readOptional(filePath, { required }) {
@@ -159,9 +149,6 @@ export function resolveInputPaths(values) {
     techSpecPath: values['tech-spec']
       ? path.resolve(values['tech-spec'])
       : null,
-    planAcceptancePath: values['plan-acceptance']
-      ? path.resolve(values['plan-acceptance'])
-      : null,
     planDir,
     planContextPath: resolvePlanContextPath(values['plan-context'], planDir),
   };
@@ -172,9 +159,6 @@ async function loadArtifacts(paths) {
   const techSpecContent = paths.techSpecPath
     ? await readOptional(paths.techSpecPath, { required: true })
     : null;
-  const planAcceptance = paths.planAcceptancePath
-    ? await readJsonFile(paths.planAcceptancePath, 'plan-acceptance')
-    : null;
   const planContextEnvelope = await loadPlanContextEnvelope(
     paths.planContextPath,
   );
@@ -182,7 +166,6 @@ async function loadArtifacts(paths) {
   return {
     stories,
     techSpecContent,
-    planAcceptance,
     planContextEnvelope,
   };
 }
@@ -330,8 +313,9 @@ async function runPersistInvocation({
 }
 
 /**
- * Fast path (Story #4741 AC-1/AC-3; widened to any plan by Story #5312):
- * chain a clean dry-run into the real persist in ONE operator invocation.
+ * The default persist path (Story #4741 AC-1/AC-3; widened to any plan by
+ * Story #5312; made the default by Story #5342): chain a clean dry-run into
+ * the real persist in ONE operator invocation.
  *
  * Two passes over the **same** loaded artifacts:
  *
@@ -344,6 +328,14 @@ async function runPersistInvocation({
  *      to gate this step went with the plan-side lite claim: a clean dry-run
  *      is the review the chain exists to fold.
  *
+ * The caller reads the **second** pass's envelope, so the first pass's
+ * evidence has to be carried onto it (Story #5361). The repair pass mutates
+ * the loaded tickets in place, which is what makes replaying the identical
+ * artifacts possible at all — and it is also why pass 2 recomputes an empty
+ * `repairs[]`: by then there is nothing left to repair. The evidence is
+ * preserved rather than re-derived, because re-running the repair pass would
+ * report repairs the persisting pass did not make.
+ *
  * Exported for tests — this is where the round-trip collapse lives, so a
  * regression here silently re-opens the second operator round-trip (or
  * worse, persists a plan the dry-run never gated).
@@ -376,6 +368,14 @@ export async function runPersistChain({
     metricsSince,
     dryRun: false,
   });
+  persistResult.repairs = mergeEvidence(
+    dryResult.repairs,
+    persistResult.repairs,
+  );
+  persistResult.warnings = mergeEvidence(
+    dryResult.warnings,
+    persistResult.warnings,
+  );
   persistResult.chain = {
     attempted: true,
     persisted: true,
@@ -384,6 +384,51 @@ export async function runPersistChain({
   return persistResult;
 }
 
+/**
+ * Union two evidence lists, dry-run first, dropping an entry the second pass
+ * reported identically. Order is the operator's reading order; the dedupe is
+ * by rendered content because a repair is a plain record and a warning is a
+ * string, so two passes that noticed the same thing noticed it byte-for-byte.
+ *
+ * @param {unknown} first
+ * @param {unknown} second
+ * @returns {unknown[]}
+ */
+function mergeEvidence(first, second) {
+  const merged = [];
+  const seen = new Set();
+  for (const entry of [
+    ...(Array.isArray(first) ? first : []),
+    ...(Array.isArray(second) ? second : []),
+  ]) {
+    const key = JSON.stringify(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(entry);
+  }
+  return merged;
+}
+
+/**
+ * Decide whether this invocation persists after its gates, or only validates.
+ *
+ * Story #5342: chaining is the default, not a flag. Every invocation that is
+ * not an explicit `--dry-run` runs the gate list and then persists what it
+ * passed, so the two operator round-trips collapse without anyone having to
+ * remember an opt-in. Story #5361 removed the no-op alias Story #5342 had
+ * kept for existing call-sites, rather than accepting and ignoring it: a flag
+ * that cannot change an outcome is a shim, and `parseArgs` refuses an unknown
+ * option, so passing it now fails loudly instead of reading as honoured.
+ *
+ * Exported for tests: this one predicate is what makes the CLI one command.
+ *
+ * @param {object} values Parsed `parseArgs` values.
+ * @returns {boolean} `true` to run the gates and then persist.
+ */
+export function shouldChainPersist(values) {
+  return values?.['dry-run'] !== true;
+}
+
 /**
  * Attach the plan-metrics roll-up for **this** invocation.
  *
@@ -450,10 +495,7 @@ async function main() {
   const paths = resolveInputPaths(values);
   const artifacts = await loadArtifacts(paths);
 
-  // `--chain-on-clean` collapses the dry-run + persist operator round-trips
-  // (Story #4741). `--dry-run` always wins — an explicit dry-run never writes.
-  const useChain =
-    values['chain-on-clean'] === true && values['dry-run'] !== true;
+  const useChain = shouldChainPersist(values);
 
   let result;
   try {
@@ -492,7 +534,7 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/plan-persist.js --stories <file> [--tech-spec <file>] [--dry-run] [options]',
     summary:
-      'Validate an authored plan and persist it as GitHub Stories. Prints the result envelope as JSON on stdout.',
+      'Validate an authored plan and persist it as GitHub Stories in one invocation (pass --dry-run to validate only). Prints the result envelope as JSON on stdout.',
     flags: [
       ['--stories <file>', 'Authored stories.json (required).'],
       ['--tech-spec <file>', 'Optional companion techspec.md.'],
@@ -501,10 +543,8 @@ runAsCli(import.meta.url, main, {
         '--plan-context <file>',
         'The plan-context envelope this draft was authored against.',
       ],
-      ['--plan-acceptance <file>', 'Acceptance artifact to attach.'],
       ['--source-tickets <ids>', 'Ticket ids this plan supersedes.'],
       ['--dry-run', 'Validate and report; create nothing.'],
-      ['--chain-on-clean', 'Persist immediately when the dry run is clean.'],
       ['--no-close-superseded', 'Leave superseded source tickets open.'],
       [
         '--force-review',

package/.agents/scripts/plan-run-epilogue.js

@@ -25,6 +25,8 @@ import { expandIdList } from './lib/util/parse-id-list.js';
 const CLI_OPTIONS = {
   stories: { type: 'string' },
   cwd: { type: 'string' },
+  /** Story #5343 — opt-in; see `run-epilogue.js` RUN_EPILOGUE_STEP_KINDS. */
+  'audit-roster': { type: 'boolean', default: false },
 };
 
 /**
@@ -51,15 +53,10 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     options: CLI_OPTIONS,
     strict: false,
   });
-  const hasStoriesFlag =
-    typeof values.stories === 'string' && values.stories.trim().length > 0;
-  if (!hasStoriesFlag) {
+  if (typeof values.stories !== 'string' || !values.stories.trim()) {
     throw new Error('Usage: node plan-run-epilogue.js --stories 1,2,3');
   }
-  const cwd =
-    typeof values.cwd === 'string' && values.cwd.trim()
-      ? values.cwd.trim()
-      : process.cwd();
+  const cwd = values.cwd?.trim() || process.cwd();
   const config = resolveConfigImpl({ cwd });
   const provider = createProviderImpl(config);
 
@@ -87,6 +84,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     provider,
     config,
     cwd,
+    auditRoster: values['audit-roster'] === true,
   });
   warnOnUnresolvedBase(result, logger);
   warnOnEmptyRollup(result, logger);
@@ -99,6 +97,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 
 /**
  * Surface an unresolvable combined landed diff as a loud operator warning.
+ * Only reachable under `--audit-roster`: a default run enumerates no roster.
  *
  * The roster's changed-file set is the input the host walks its audit lenses
  * against; a silent absence would read as "nothing changed" and the lens walk
@@ -167,7 +166,7 @@ function warnOnEmptyRollup(result, logger = Logger) {
 await runAsCli(import.meta.url, main, {
   usage: {
     invocation:
-      'node .agents/scripts/plan-run-epilogue.js --stories <id,id,...> [--cwd <path>]',
+      'node .agents/scripts/plan-run-epilogue.js --stories <id,id,...> [--cwd <path>] [--audit-roster]',
     summary:
       'Close out a delivery run: roll up the delivered Stories’ signals and report the run’s loop health.',
     flags: [
@@ -176,6 +175,10 @@ await runAsCli(import.meta.url, main, {
         'Comma-separated delivered Story ids, singles or A-B ranges (required).',
       ],
       ['--cwd <path>', 'Repository root (default: process cwd).'],
+      [
+        '--audit-roster',
+        'Also select the cross-Story audit lens roster and post plan-run-audit-roster (off by default; the host then walks every listed lens).',
+      ],
     ],
   },
 });

package/.agents/scripts/pr-watch-with-update.js

@@ -458,12 +458,19 @@ async function evaluateGreenWatch({
   }
   const headSha = headShaFn({ prRef, cwd });
   const { verdict, reason } = classifyGreenVerdict({ digest, headSha });
-  if (verdict === 'fix-at-source') {
+  if (verdict === 'fix-at-source' || verdict === 'rerun-permitted') {
+    // Story #5343 — `rerun-permitted` is the one same-SHA green the rule
+    // admits: `file-ci-gap.js` recorded a proven `capacity` /
+    // `unreproducible-tier` verdict for THIS head, so there is no fix at
+    // source to make. Retiring the digest spends the allowance with it, which
+    // is what makes it exactly one: a second red writes a fresh digest that
+    // carries none.
     retireDigestFn({ storyId, tempRoot, cwd });
     const reArm = await reArmFn({ cwd, prNumber });
     const reArmed = Boolean(reArm?.enabled);
     logger.info?.(
-      `[pr-watch] green on a NEW head SHA (${reason}) — fix at source; digest retired, ` +
+      `[pr-watch] ${verdict === 'rerun-permitted' ? 'green admitted on the SAME head SHA' : 'green on a NEW head SHA'} ` +
+        `(${reason}) — digest retired, ` +
         `auto-merge ${reArmed ? 're-armed' : `NOT re-armed (${reArm?.reason ?? 'unknown'})`}.`,
     );
     return { verdict, reason, exitCode: 0, headSha, reArmed };