mandrel 2.60.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 the `story-plan-state` comment on every created Story — since
- *      Story #5343 the one comment persist posts, carrying the plan summary
- *   6. Flip every Story to `agent::ready` — the terminal step, so `ready`
- *      always implies "plan comments 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 plan comments were
- * written afterwards. Anything picking a Story up in that window — or after
- * a comment failure aborted the loop — found a ready Story carrying none of
- * the operator's delivery instructions. Creating unlabelled, writing the
- * comments, 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
  */
@@ -79,31 +49,15 @@ import { buildPlanSummaryCommentBody, buildWaveTable } from './summary.js';
 import { closeSupersededTickets } from './supersede-ops.js';
 import { assertNoWaveCollisions } from './wave-collision-gate.js';
 
-/** Structured-comment type for the per-plan Story comment. */
+/** Marker that makes a re-persist upsert the comment in place. */
 const STORY_PLAN_STATE_TYPE = 'story-plan-state';
 
 /**
- * Write the plan comment on a Story — the **one** comment persist posts per
- * Story (Story #5343).
- *
- * It carries the human plan summary: the created Story set, the delivery order
- * and the exact deliver command. That summary used to be a second
- * `plan-summary` comment on the primary Story only, which meant the operator's
- * instructions lived on a different marker from the rest — and on a different
- * ticket from four Stories out of five.
- *
- * **No machine payload (Story #5367).** The comment used to lead with a fenced
- * JSON checkpoint (a persist receipt: completion time, Story count, the
- * cohort). Nothing ever read it back — the one module that parsed it had no
- * production importer — so the payload and its readers are gone. The
- * `story-plan-state` marker stays: it is what makes a re-persist upsert this
- * comment in place instead of appending a second one.
+ * The one comment persist posts per Story, carrying the plan summary.
  *
  * @param {object} provider
  * @param {number} storyId
- * @param {string} summary Rendered plan-summary markdown. The comment exists
- *   to carry it, so an empty summary is a caller bug rather than a degenerate
- *   comment worth posting.
+ * @param {string} summary Must be non-empty.
  * @returns {Promise<void>}
  */
 export async function writePlanSummaryComment(provider, storyId, summary) {
@@ -120,20 +74,8 @@ export async function writePlanSummaryComment(provider, storyId, summary) {
 }
 
 /**
- * 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 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,11 +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 the
- * chained run loses nothing on stderr, as the chain's envelope merge keeps
- * it from losing anything on stdout (Story #5361).
- *
  * @param {string[]} warnings
  * @returns {void}
  */
@@ -215,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>}
  */
@@ -249,28 +175,11 @@ async function runSupersedePhase(args) {
 }
 
 /**
- * Render the plan-metrics line for the **posted** summary section,
- * 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>}
@@ -306,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 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 });
@@ -336,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[] }>}
@@ -373,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.
@@ -392,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
@@ -420,19 +303,9 @@ async function enforceReachability(reachability, config) {
 }
 
 /**
- * Write the per-Story plan comment — one comment per Story, carrying the plan
- * summary (Story #5343) — 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 comments 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* Story carries its plan comment before
- * the first `agent::ready` flip is issued, so `ready` still means "fully
- * persisted" and the operator's instructions are never missing from a ticket
- * something else may already be picking up. 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>}
@@ -441,19 +314,12 @@ async function persistStoryArtifacts({ provider, created, summaryBody }) {
   await concurrentMap(
     created,
     (story) => writePlanSummaryComment(provider, story.id, summaryBody),
-    // The per-Story comment 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.
     { concurrency: FANOUT_CONCURRENCY },
   );
   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>}
  */
@@ -469,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,
@@ -500,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 ` +
@@ -514,8 +373,6 @@ function logPersistEpilogue({
 }
 
 /**
- * Execute the flat Story persist end to end.
- *
  * @param {{
  *   provider: object,
  *   artifacts: {
@@ -558,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);
@@ -591,59 +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, warnings: supersedeWarnings } =
     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.
+      // Audit footers carried onto every Story that did not attribute its own
+      // `provenance`; empty for a `--tickets` run.
       provenanceSource: seedContent,
     });
 
-  // Story #5342: the source ids assembly assigned to the primary Story by
-  // default. They ride the same list every other dry-run warning does, so a
-  // default-assigned supersede is visible in the output the operator already
-  // reads rather than only in the tracker afterwards.
   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,
@@ -652,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,
   });
@@ -669,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,
@@ -700,9 +517,6 @@ 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,
   });
@@ -711,11 +525,8 @@ export async function runPlanPersist({
     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,
@@ -729,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 });
@@ -756,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]