mandrel 2.59.0 → 2.61.0

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

@@ -1,39 +1,9 @@
 /**
- * run-plan-persist.js — flat Story persist for the v2 `/mandrel-plan` collapse
- * (Stage 3 — `docs/roadmap.md`).
- *
- * Ordered pipeline — hard gates refuse, everything else is a **warning** the
- * dry-run lists (Story #5312):
- *
- *   1. `changes[]` repair + ticket validator + file-assumption + DAG
- *   2. Draft reachability (named soft failure, exit 3)
- *   3. Same-wave collision refusal (`assertNoWaveCollisions`) + spec fold
- *   4. Create Story issues (`type::story` + sanitized authored labels —
- *      deliberately NOT `agent::ready`), resumably via a plan fingerprint
- *   5. Upsert `story-plan-state` on every created Story; upsert `plan-summary`
- *      on the primary Story
- *   6. Flip every Story to `agent::ready` — the terminal step, so `ready`
- *      always implies "checkpoints written"
- *   7. Comment on + close the superseded `--tickets` source issues
- *      (Story #4535) — bookkeeping only; never fails the run
- *   8. Temp cleanup at terminal success + a stale-plan-dir reap
- *
- * **Why `agent::ready` moved to the end (Story #4541).** Issues used to be
- * born `agent::ready` in the creating POST while the checkpoints were
- * written afterwards. Anything picking a Story up in that window — or after
- * a comment failure aborted the loop — read the checkpoint as `null`
- * (`story-plan-state.js` degrades missing/malformed to `null`). Creating
- * unlabelled, writing checkpoints, then flipping closes that race.
- *
- * **No authored risk artifact (Story #4542).** Persist neither requires nor
- * accepts a risk verdict, derives no envelope from one, and computes no
- * review routing. Review depth and the acceptance-critic mode are derived from
- * the diff at close time (`review-depth.js#deriveChangeLevel`); `--force-review`
- * is an explicit operator flag, recorded here as a receipt and never inferred.
- *
- * Hard cutover: no Epic parent, no reconciler, no `deliveryShape`, no
- * `--amend` tree cascades. Those surfaces die with Stages 4–5 for any
- * remaining epic-delivery readers.
+ * Flat Story persist. Hard gates refuse; everything else is a warning the
+ * dry-run lists. Order: validate → reachability → wave-collision gate →
+ * create (without `agent::ready`) → plan comment on every Story → flip to
+ * `agent::ready` last, so `ready` implies "plan comments written" → close
+ * superseded sources (never fails the run) → temp cleanup.
  *
  * @module lib/orchestration/plan-persist/run-plan-persist
  */
@@ -75,65 +45,37 @@ import {
   createStoryIssues,
   markStoriesReady,
 } from './story-ops.js';
-import {
-  buildPlanSummaryCommentBody,
-  buildWaveTable,
-  PLAN_SUMMARY_COMMENT_TYPE,
-} from './summary.js';
+import { buildPlanSummaryCommentBody, buildWaveTable } from './summary.js';
 import { closeSupersededTickets } from './supersede-ops.js';
 import { assertNoWaveCollisions } from './wave-collision-gate.js';
 
-/** Checkpoint schema version written on each Story's story-plan-state. */
-const PLAN_CHECKPOINT_SCHEMA_VERSION_V2 = 2;
-
-/** Structured-comment type for the per-plan Story checkpoint. */
+/** Marker that makes a re-persist upsert the comment in place. */
 const STORY_PLAN_STATE_TYPE = 'story-plan-state';
 
 /**
- * Write the `story-plan-state` checkpoint on a Story.
+ * The one comment persist posts per Story, carrying the plan summary.
  *
  * @param {object} provider
  * @param {number} storyId
- * @param {object} state
+ * @param {string} summary Must be non-empty.
+ * @returns {Promise<void>}
  */
-export async function writeCheckpointV2(provider, storyId, state) {
+export async function writePlanSummaryComment(provider, storyId, summary) {
   if (!Number.isInteger(storyId)) {
-    throw new TypeError('writeCheckpointV2 requires a numeric storyId');
+    throw new TypeError('writePlanSummaryComment requires a numeric storyId');
+  }
+  const body = summary?.trim();
+  if (!body) {
+    throw new TypeError(
+      'writePlanSummaryComment requires a non-empty plan summary',
+    );
   }
-  const body = [
-    '### story-plan-state',
-    '',
-    '```json',
-    JSON.stringify(
-      {
-        version: PLAN_CHECKPOINT_SCHEMA_VERSION_V2,
-        storyId,
-        ...state,
-      },
-      null,
-      2,
-    ),
-    '```',
-  ].join('\n');
   await upsertStructuredComment(provider, storyId, STORY_PLAN_STATE_TYPE, body);
-  return state;
 }
 
 /**
- * Enforce the ticket validator's hard errors and collect its warnings.
- *
- * Since Story #5312 the only hard refusal the validator batches into
- * `errors[]` is a `deletes` naming a path absent at base; every other
- * footprint probe — a `creates` / `refactors-existing` mismatch, a goal,
- * acceptance or verify path absent at base — lands on `warnings[]`, which
- * the dry-run prints and the persist proceeds past. The `changes[]` repairs
- * the helper applied are reported alongside so the operator sees what was
- * rewritten.
- *
- * The returned freshness counts feed the posted `plan-summary`'s freshness
- * line: every warning is a reference the base branch disagreed with, so it
- * counts as `stale` there rather than the comment reading "clean" on a run
- * that had something to say.
+ * Throw on validator hard errors; return warnings (with applied `changes[]`
+ * repairs) and freshness counts for the summary.
  *
  * @returns {{ warnings: string[], freshness: { stale: number, ambiguous: number } }}
  */
@@ -156,10 +98,8 @@ function enforceTicketValidation(validated) {
 }
 
 /**
- * Freshness counts for the posted plan summary. Every validator warning is
- * a reference the base branch disagreed with — `stale` when a base ref was
- * actually read, `ambiguous` when none resolved in this checkout and the
- * probes were skipped, since nothing was verified either way.
+ * Every validator warning counts `stale` when a base ref was read, else
+ * `ambiguous` (the probes were skipped, nothing was verified).
  *
  * @param {string|null} probeRef
  * @param {string[]} warnings
@@ -170,18 +110,13 @@ function freshnessCounts(probeRef, warnings) {
   return { stale: warnings.length, ambiguous: 0 };
 }
 
-/** How each text-hygiene finding kind names itself on the warning list. */
 const TEXT_HYGIENE_LABELS = {
   'open-question': 'open question in body',
   'pinned-identifier': 'pinned identifier in acceptance[]',
 };
 
 /**
- * The advisory text-hygiene lints over the draft (Story #5312, #5323) — an
- * operator-directed question persisted into a Story a non-interactive
- * sub-agent executes, and an acceptance item pinning an internal symbol the
- * advisory `changes[]` may reshape. Warnings the dry-run lists, never
- * refusals.
+ * Advisory text-hygiene lints (warnings, never refusals).
  *
  * @param {object[]} rawStories
  * @returns {string[]}
@@ -196,10 +131,6 @@ function collectTextHygieneWarnings(rawStories) {
 }
 
 /**
- * Print every warning the run collected under one heading. The dry-run is
- * where an operator reads these; the persist prints the same list so a
- * `--chain-on-clean` run loses nothing.
- *
  * @param {string[]} warnings
  * @returns {void}
  */
@@ -214,12 +145,8 @@ function logWarnings(warnings) {
 }
 
 /**
- * Run the supersede close phase behind a belt-and-braces guard.
- *
- * `closeSupersededTickets` already swallows per-ticket failures, but this
- * phase runs *after* `createIssue`, so an unexpected throw anywhere in it
- * would leave the run half-done with Stories already live. Degrade to a
- * reported failure instead.
+ * Runs after the Stories are live, so an unexpected throw degrades to a
+ * reported failure rather than a half-done run.
  *
  * @returns {Promise<import('./supersede-ops.js').SupersedeReport>}
  */
@@ -248,28 +175,11 @@ async function runSupersedePhase(args) {
 }
 
 /**
- * Render the plan-metrics line for the **posted** `plan-summary` comment,
- * scoped to this invocation.
- *
- * The ordering hazard this closes: the ledger record for the current run is
- * appended by `recordPlanInvocation`'s `finally`, which by construction only
- * fires once `runPlanPersist` has *resolved* — long after this comment body
- * is composed. A plain `since`-filtered ledger read therefore summarized
- * every run except the one being summarized, and on an otherwise-quiet
- * ledger it rendered "plan-metrics: no invocations recorded" onto the very
- * comment reporting the run. (The stdout envelope was always correct: its
- * `attachPlanMetrics` read runs after the wrapper returns.)
- *
- * **The `finally` stays where it is.** It is what guarantees a persist that
- * throws is still recorded, so moving the append earlier — or moving this
- * read later, past the GitHub writes it feeds — would trade a cosmetic bug
- * for a real one. Instead of racing it, fold in a synthetic record standing
- * for the in-flight invocation. It is the same record the wrapper is about to
- * write, minus a final duration; it cannot double-count, because the real one
- * does not exist yet at this point in the pipeline.
- *
- * `ok: true` is honest here: this line is only ever composed on the success
- * path, after `createStoryIssues` has returned.
+ * Plan-metrics line for the posted summary, scoped to this invocation. The
+ * run's own ledger record is appended by the wrapper's `finally` (which must
+ * stay there so a throwing persist is still recorded) only after this
+ * resolves, so fold in a synthetic in-flight record; it cannot double-count.
+ * `ok: true` holds because this runs only on the success path.
  *
  * @param {{ config: object, since: string, startedAt: string, mode: string }} args
  * @returns {Promise<string|null>}
@@ -305,20 +215,13 @@ async function renderRunScopedPlanMetricsLine({
 }
 
 /**
- * Re-run the cross-Story conflict passes over the assembled bodies
- * (Story #5045).
- *
- * `validateTickets` runs before assembly, over the raw payload, so until now
- * plan-time conflict analysis judged an artifact that is not the one persist
- * writes — and the passes that scan `body.acceptance` / `body.verify` were
- * inert on the canonical top-level authoring shape as a result. Findings the
- * raw pass already reported are dropped so the same collision is not
- * announced twice per run; the rest are returned for the plan-summary
- * comment, which is where these findings stop being a stderr line nobody
- * keeps. Every finding is advisory (Story #5312).
+ * Re-run the conflict passes over the assembled bodies — the artifact persist
+ * actually writes (the body-scanning passes are inert on the raw payload).
+ * Only findings the raw pass did not already report are surfaced; all are
+ * advisory.
  *
  * @param {{ stories: object[], rawFindings: object[] }} args
- * @returns {object[]} The assembled-pass findings, for the summary comment.
+ * @returns {object[]}
  */
 function analyzeAssembledStories({ stories, rawFindings }) {
   const findings = computeAssembledConflictFindings({ stories });
@@ -335,23 +238,9 @@ function analyzeAssembledStories({ stories, rawFindings }) {
 }
 
 /**
- * Reap abandoned `plan-*` directories under the temp root (Story #4541).
- *
- * Terminal-success cleanup only ever removed the *current* run's `planDir`,
- * so every plan that failed a gate, was abandoned mid-authoring, or ran
- * `--dry-run` left its directory behind forever. This sweeps the stragglers
- * on each persist.
- *
- * Story #4794 folded the age-floored reap into the shared temp-retention
- * engine — `planDirs` is one of its declared classes, so the plan path and
- * the delivery path now converge on one classifier and one staleness floor
- * (`delivery.tempRetention.staleDays`, still 7 days by default) instead of
- * this module owning a private constant. Behaviour is unchanged: only
- * `plan-*` directories are considered, the age test is the directory's own
- * mtime, and the current run's `planDir` is excluded.
- *
- * Best-effort throughout: this is hygiene, never a reason to fail a run that
- * has already created Stories.
+ * Reap abandoned `plan-*` directories (failed, abandoned, or dry-run plans)
+ * via the shared temp-retention staleness floor, excluding this run's.
+ * Best-effort hygiene.
  *
  * @param {{ config?: object, keepDir?: string|null, now?: number }} args
  * @returns {Promise<{ reaped: string[] }>}
@@ -372,11 +261,6 @@ export async function reapStalePlanDirs({
 }
 
 /**
- * Fail closed on a payload that cannot be persisted. Extracted from
- * `runPlanPersist` (Story #4926) so the entry point carries the flow, not the
- * guards. The reviewability budget that used to sit beside this check went
- * with Story #5312 — a plan is as many Stories as the split policy yields.
- *
  * @param {unknown} rawStories
  * @returns {void}
  * @throws {Error} On an empty payload.
@@ -391,7 +275,7 @@ function assertPersistablePlan(rawStories) {
 }
 
 /**
- * Enforce the draft-reachability critic: orphans throw, a skip is ledgered.
+ * Orphans throw; a skip is ledgered.
  *
  * @param {{ status: string, reasons: string[], orphans?: object[] }} reachability
  * @param {object} config
@@ -419,63 +303,23 @@ async function enforceReachability(reachability, config) {
 }
 
 /**
- * Write the per-Story checkpoint, upsert the plan-summary comment, and flip
- * every created Story to `agent::ready`. Terminal ordering is load-bearing:
- * `agent::ready` lands last so it can honestly mean "fully persisted"
- * (Story #4541). A dry run performs none of it.
- *
- * **The checkpoints fan out; the phase boundary does not** (Story #4952). The
- * per-Story upserts are independent of one another and run under bounded
- * concurrency, but the `await` on that whole fan-out is what keeps the
- * Story #4541 invariant intact: *every* checkpoint is on its ticket before the
- * first `agent::ready` flip is issued, so `ready` still means "fully
- * persisted" and a `/mandrel-deliver` that picks a Story up cannot read a null
- * checkpoint. Concurrency inside the phase is safe; overlapping the phases is
- * the race this ordering exists to close.
+ * Plan comments fan out concurrently, but the whole fan-out is awaited before
+ * the first `agent::ready` flip, so `ready` always means "fully persisted".
+ * Never overlap the two phases.
  *
  * @param {object} args
  * @returns {Promise<void>}
  */
-async function persistStoryArtifacts({
-  provider,
-  created,
-  primary,
-  summaryBody,
-}) {
-  const cohort = created.map((createdStory) => ({
-    slug: createdStory.slug,
-    id: createdStory.id,
-  }));
+async function persistStoryArtifacts({ provider, created, summaryBody }) {
   await concurrentMap(
     created,
-    (story) =>
-      writeCheckpointV2(provider, story.id, {
-        persist: {
-          completedAt: new Date().toISOString(),
-          storyCount: created.length,
-          primaryStoryId: primary.id,
-          stories: cohort,
-        },
-      }),
-    // The per-Story checkpoint upserts (Story #4952): each targets a
-    // different issue and reads nothing another writes, so this loop was
-    // serial only by construction — but see {@link persistStoryArtifacts}
-    // for the phase ordering that is *not* incidental.
+    (story) => writePlanSummaryComment(provider, story.id, summaryBody),
     { concurrency: FANOUT_CONCURRENCY },
   );
-  await upsertStructuredComment(
-    provider,
-    primary.id,
-    PLAN_SUMMARY_COMMENT_TYPE,
-    summaryBody,
-  );
   await markStoriesReady({ provider, created });
 }
 
 /**
- * Remove this run's plan directory on terminal success, then sweep the
- * abandoned ones terminal-success cleanup can never reach (Story #4541).
- *
  * @param {{ config: object, planDir: string|null, skipCleanup: boolean }} args
  * @returns {Promise<void>}
  */
@@ -491,9 +335,6 @@ async function cleanupPlanDirs({ config, planDir, skipCleanup }) {
 }
 
 /**
- * Log the operator-facing persist epilogue: adoption, the ready primary, the
- * deliver command, and the cohort grouping label.
- *
  * @param {{
  *   created: object[],
  *   primary: object,
@@ -522,11 +363,7 @@ function logPersistEpilogue({
   Logger.info(
     `[plan-persist] Deliver with: /mandrel-deliver ${created.map((s2) => s2.id).join(' ')}`,
   );
-  // Metadata only — a GitHub filter for the cohort this run authored, never
-  // a delivery-resolution input (/mandrel-deliver stays ids-only, Story #4540).
-  // Gated on the ensure result: the label ensure degrades non-fatally, and
-  // advertising a filter GitHub just refused to create is worse than saying
-  // nothing (Story #5201). The derived id survives in the result envelope.
+  // Never advertise a filter for a label the ensure failed to create.
   if (planRunLabelApplied) {
     Logger.info(
       `[plan-persist] Cohort grouping label: ${planRunLabel} — filter with ` +
@@ -536,8 +373,6 @@ function logPersistEpilogue({
 }
 
 /**
- * Execute the flat Story persist end to end.
- *
  * @param {{
  *   provider: object,
  *   artifacts: {
@@ -580,16 +415,11 @@ export async function runPlanPersist({
     sourceTicketIds = [],
     sourceTicketOrigin = 'none',
     closeSuperseded = true,
-    // Story #5139 — the optional container Epic. `null` (the default) is the
-    // ordinary shape: no Epic is created unless `/mandrel-plan` offered one
-    // above the threshold and the operator confirmed it.
+    // Optional container Epic; only set when the operator confirmed one.
     epic = null,
   } = opts;
 
-  // Boundary for the plan-metrics summary below: everything this invocation
-  // appends to the ledger is stamped at or after this instant, so filtering
-  // on it scopes the counts to *this* run rather than every plan ever run
-  // through the shared standalone ledger (Story #4541).
+  // Scopes the plan-metrics summary to this run's ledger entries.
   const runStartedAt = opts.metricsSince ?? new Date().toISOString();
 
   assertPersistablePlan(rawStories);
@@ -613,51 +443,38 @@ export async function runPlanPersist({
   });
   await enforceReachability(reachability, config);
 
-  // Story #5155 — the plan's outward references (`--epic <id>`, and any
-  // `#<id>` blocker) resolve BEFORE the first create, dry run included.
+  // Outward references (`--epic <id>`, `#<id>` blockers) resolve before the
+  // first create, dry run included.
   const adoptionTarget = await resolveCrossPlanLinks({
     provider,
     stories: rawStories,
     epicId: opts.adoptEpicId ?? null,
   });
 
-  // Inline Spec fold (Specs stay inline, never under docs/).
   const seedContent = planContextEnvelope?.seed?.content ?? '';
-  const { stories: assembled } = assemblePlanStories(rawStories, {
-    sharedSpec: techSpecContent,
-    sourceTicketIds,
-    // The seed this plan was authored from: an audit sweep's Single-plan seed
-    // carries the `audit-fingerprints` / `audit-semantic-keys` footers, and
-    // assembly copies them into the persisted Story bodies so the next sweep
-    // recognises what it already planned (Story #4877). Since Story #5045 this
-    // is the **fallback** — it is carried onto every Story that did not
-    // attribute its own `provenance`, which keeps an un-attributed plan exactly
-    // as recall-safe as it was. Empty for a `--tickets` run, a no-op there.
-    provenanceSource: seedContent,
-  });
+  const { stories: assembled, warnings: supersedeWarnings } =
+    assemblePlanStories(rawStories, {
+      sharedSpec: techSpecContent,
+      sourceTicketIds,
+      // Audit footers carried onto every Story that did not attribute its own
+      // `provenance`; empty for a `--tickets` run.
+      provenanceSource: seedContent,
+    });
+
+  warnings.push(...supersedeWarnings);
+  logWarnings(supersedeWarnings);
 
-  // Stamp the `audit::*` labels the dedup corpus is listed by. Without them a
-  // Story this path files is absent from the pool an indexed sweep matches
-  // against, and an indexed run answers exact lookups from that pool without
-  // ever reaching the provider — so the provenance footers alone leave it
-  // invisible (Story #5307). A non-audit seed carries none: a no-op there.
+  // The dedup corpus is listed by `audit::*` label; footers alone leave the
+  // Story invisible to an indexed sweep.
   const stories = withAuditLabels(assembled, seedContent);
 
-  // Story #5045: the cross-Story conflict passes re-run over the assembled,
-  // footer-stamped bodies — the artifact persist actually writes — before any
-  // GitHub call, so a policy upgrade still refuses the plan pre-creation.
   const assembledConflicts = analyzeAssembledStories({
     stories,
     rawFindings: validated.findings,
   });
 
-  // Story #5332 — the split gate, ahead of the first create. `buildWaveTable`
-  // needs only `{slug, title, depends_on}` and the prediction needs only the
-  // assembled bodies, so both can run before anything is written; they used
-  // to sit *after* creation, which is why the collision table could only ever
-  // be a receipt for a plan already live. The same computed value is handed
-  // to the summary rendering below rather than recomputed, so the refusal and
-  // the receipt can never disagree.
+  // The split gate runs before the first create; the same values feed the
+  // summary so the refusal and the receipt cannot disagree.
   const waveTable = buildWaveTable(
     stories.map((s) => ({
       slug: s.slug,
@@ -666,12 +483,8 @@ export async function runPlanPersist({
     })),
   );
 
-  // Story #5265: the table says which Stories share an order; the dispatcher
-  // decides which of those actually run together. Run its own predicate over
-  // the assembled bodies — the exact artifact the tick will read back off
-  // GitHub — so an N>1 draft it would serialize is refused here, and the
-  // summary comment names the serialisation instead of promising parallelism
-  // the next tick refuses. One enumeration feeds both.
+  // The dispatcher's own predicate over the assembled bodies, so a draft it
+  // would serialize is refused here rather than promised as parallel.
   const waveCollisions = assertNoWaveCollisions(waveTable, stories, {
     tempRoot: getPaths(config).tempRoot,
   });
@@ -683,20 +496,10 @@ export async function runPlanPersist({
       opts: { dryRun },
     });
 
-  // What this run filed, recorded where the next audit sweep reads it
-  // (Story #5307). A dry run created nothing, and the call knows it.
   recordAuditFilings({ stories, created, tickets: rawStories, dryRun });
 
   const primary = created[0];
 
-  // Story #4541: `readPlanMetrics` is declared `(epicId, config)` but was
-  // called with `config` first, so the ledger path resolver received the
-  // config object as an `epicId` and threw its guard on every single run —
-  // a throw this try/catch then swallowed into a silently absent summary.
-  // v2 persist is always Epic-less, hence the explicit `null`. The `since`
-  // filter keeps the counts about this invocation, and the in-flight record
-  // is folded in because the wrapper has not written it yet — see
-  // `renderRunScopedPlanMetricsLine`.
   const planMetricsLine = await renderRunScopedPlanMetricsLine({
     config,
     since: runStartedAt,
@@ -714,27 +517,16 @@ export async function runPlanPersist({
     mode: 'stories',
     planMetricsLine,
     stories: created,
-    // Story #5045: the wave table promises what can run in parallel; the
-    // collisions the conflict passes found belong on the same surface, or the
-    // promise is the only half anyone reads.
     conflictFindings: assembledConflicts,
     waveCollisions,
   });
 
   if (!dryRun) {
-    await persistStoryArtifacts({
-      provider,
-      created,
-      primary,
-      summaryBody,
-    });
+    await persistStoryArtifacts({ provider, created, summaryBody });
   }
 
-  // Story #5139 — the container Epic is created LAST among the writes: its
-  // body embeds the child issue numbers and its sub-issue edges need their
-  // database ids, neither of which exists until the Stories are live. It is
-  // never load-bearing, so a failure here degrades to "no container" and the
-  // Stories still deliver by id.
+  // Last among the writes: the Epic needs the children's numbers and database
+  // ids. Never load-bearing — a failure degrades to "no container".
   const containerEpic = await resolveContainerEpic({
     provider,
     adoptionTarget,
@@ -748,16 +540,12 @@ export async function runPlanPersist({
     stories,
     created,
     sourceTicketIds,
-    // Story #5280 — closing a source ticket is a child state change, so the
-    // phase re-derives the container above it. It needs the config the rollup
-    // reads its board and operator handle from.
+    // Closing a source ticket re-derives its container Epic's rollup.
     config,
     dryRun,
     closeSuperseded,
   });
-  // Record which channel the ids came from so a run that superseded nothing
-  // says *why* (`none` = neither the envelope nor --source-tickets carried
-  // any) rather than reading as a clean no-op — Story #4554.
+  // Lets a run that superseded nothing say why.
   supersede.sourceTicketOrigin = sourceTicketOrigin;
 
   await cleanupPlanDirs({ config, planDir, skipCleanup });
@@ -775,15 +563,9 @@ export async function runPlanPersist({
     forceReview,
     reachability,
     freshness,
-    // Story #5312: what the run rewrote and what it noticed. The dry-run is
-    // the review surface now that the footprint probes warn instead of
-    // refusing, so the list rides the result envelope, not just stderr.
     warnings,
     repairs: validated.repairs ?? [],
     waveTable,
-    // Story #5265 AC-2/AC-4: both halves of what persist concluded but used
-    // to keep to itself — the `refactors-existing` declarations it rewrote,
-    // and the same-order pairs the dispatcher will serialize.
     assumptionNormalizations: validated.normalizations ?? [],
     waveCollisions,
     supersede,

package/.agents/scripts/lib/orchestration/plan-persist/soft-findings.js

@@ -1,13 +1,6 @@
 /**
  * Soft-finding reporting for plan-persist.
  *
- * Story #5312 retired the fan-out gate that shared this file: the delete
- * blast-radius probe never refused a real plan, and its `--allow-large-fan-out`
- * override was a flag nobody typed. What remains is the one surface that
- * announces every advisory finding the validator produced, each under its
- * own kind, so the operator reads a conflict as a conflict and a nudge as a
- * nudge (Story #4907).
- *
  * @module lib/orchestration/plan-persist/soft-findings
  */
 
@@ -18,11 +11,8 @@ import {
 } from '../ticket-validator-conflicts.js';
 
 /**
- * Report every soft finding the validator produced, each under its own kind.
- *
- * Only the {@link CONFLICT_KINDS} are cross-Story conflicts. Any other soft
- * kind is a single-Story nudge, and announcing it as a conflict overstated it
- * and taught readers to discount the whole channel.
+ * Only {@link CONFLICT_KINDS} are reported as conflicts; other soft kinds are
+ * single-Story advisories, so the channel is not overstated.
  *
  * @param {object[]} findings
  * @param {string} [tag]