mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/findings/audit-ledger.js

@@ -1,31 +1,7 @@
 /**
- * lib/findings/audit-ledger.js — Cross-run audit findings ledger.
- *
- * Without a committed memory of what a prior sweep already saw, every
- * `/audit-to-stories` run re-litigates the whole backlog from zero: it cannot
- * tell a brand-new finding from one already filed, an intentionally-rejected
- * finding from an unseen one, or a genuine regression from routine churn. The
- * ledger is that memory. It is a small committed JSON file
- * (`baselines/audit-ledger.json`, the same envelope shape as the arch-cycles
- * baseline — `{ $schema, generatedAt, entries: [] }`) keyed by each finding's
- * shared-helper fingerprint plus a location-based `semanticKey` that survives a
- * reworded title.
- *
- * Each entry carries a lifecycle `status`:
- *   - `new`          — seen, not yet filed as an Issue.
- *   - `filed`        — an Issue was opened; re-detections are known, not new.
- *   - `fixed`        — the tracking Issue closed as completed.
- *   - `accepted-risk`— the tracking Issue closed as `not_planned`; the finding
- *                      is deliberately rejected and is SUPPRESSED on re-detect.
- *   - `regressed`    — a `fixed` finding re-appeared (closed-completed Issue,
- *                      finding detected again).
- *
- * `reconcileLedger` folds a fresh scan and the live Issue states onto the prior
- * ledger, returning the next ledger plus a per-finding classification whose
- * `action` (`propose` | `known` | `suppress` | `regressed`) tells the caller
- * whether to open a Story. Pure: filesystem access is confined to the tiny
- * {@link readLedger} / {@link writeLedger} helpers, which take an injectable
- * `fs` so tests never touch disk.
+ * lib/findings/audit-ledger.js — committed cross-run memory of audit
+ * findings, keyed by fingerprint and `semanticKey`. Status: `new` · `filed` ·
+ * `fixed` · `accepted-risk` (closed `not_planned`; suppressed) · `regressed`.
  */
 
 import nodeFs from 'node:fs';
@@ -36,11 +12,7 @@ export const DEFAULT_LEDGER_PATH = 'baselines/audit-ledger.json';
 const LEDGER_SCHEMA_URL =
   'https://mandrel.dev/baselines/audit-ledger.schema.json';
 
-// Entry lifecycle states — `new | filed | fixed | accepted-risk | regressed`.
-// The reconcile policy in `decideStatus` is the single source of truth.
-
 /**
- * Build an empty ledger envelope (arch-cycles-baseline shape).
  * @param {string} [now] — ISO timestamp to stamp.
  * @returns {{ $schema: string, generatedAt: string, entries: [] }}
  */
@@ -49,18 +21,9 @@ function createEmptyLedger(now = new Date().toISOString()) {
 }
 
 /**
- * Compute a finding's stable identity: its fingerprint (title-sensitive) and
- * its location-based semantic key (title-insensitive).
+ * `toCanonical` is injected: importing the audit adapter would close a cycle.
  *
- * The projection onto the canonical identity is the **caller's**, injected as
- * `toCanonical`. That is what lets this module live beside `route-finding.js`
- * in the shared findings layer: the audit pipeline's own adapter
- * (`lib/audit-to-stories/finding-adapter.js`) imports *from* here, so importing
- * it back would close a `findings → audit-to-stories → findings` cycle that
- * `check-arch-cycles` rightly refuses. A caller that already holds canonical
- * findings passes nothing.
- *
- * @param {object} finding — a parsed/stamped audit finding.
+ * @param {object} finding
  * @param {(finding: object) => object} [toCanonical]
  * @returns {{ fingerprint: string, semanticKey: string }}
  */
@@ -73,8 +36,7 @@ function findingIdentity(finding, toCanonical) {
 }
 
 /**
- * Read the ledger from disk. Returns an empty ledger when the file is absent
- * or unparseable — a missing memory is an empty memory, never a hard error.
+ * An absent or unparseable file reads as an empty ledger, never an error.
  * @param {string} filePath
  * @param {{ fs?: typeof import('node:fs') }} [deps]
  * @returns {{ $schema?: string, generatedAt?: string, entries: object[] }}
@@ -92,8 +54,6 @@ export function readLedger(filePath, { fs } = {}) {
 }
 
 /**
- * Persist the ledger to disk with a stable 2-space indent and a trailing
- * newline (so the committed file diffs cleanly).
  * @param {string} filePath
  * @param {object} ledger
  * @param {{ fs?: typeof import('node:fs'), path?: typeof import('node:path') }} [deps]
@@ -107,7 +67,6 @@ export function writeLedger(filePath, ledger, { fs, path } = {}) {
 }
 
 /**
- * Index a ledger's entries by fingerprint and by semanticKey for O(1) lookup.
  * @param {{ entries?: object[] }} ledger
  */
 function indexLedger(ledger) {
@@ -121,9 +80,7 @@ function indexLedger(ledger) {
 }
 
 /**
- * Resolve the effective Issue state for a finding: an explicit override in
- * `issueStates` (keyed by fingerprint then semanticKey) wins over whatever the
- * prior ledger entry recorded.
+ * An `issueStates` override beats the recorded Issue.
  * @param {{ fingerprint: string, semanticKey: string }} id
  * @param {object|null} existing
  * @param {Record<string, { state?: string, stateReason?: string|null, number?: number }>} issueStates
@@ -141,9 +98,6 @@ function resolveIssueState(id, existing, issueStates) {
 }
 
 /**
- * The four verdicts the policy can reach, spelled once. Deduping them keeps
- * `decideStatus` readable as the decision table it is, rather than eight
- * near-identical object literals.
  * @type {Record<string, { status: string, action: string }>}
  */
 const VERDICT = Object.freeze({
@@ -154,31 +108,20 @@ const VERDICT = Object.freeze({
 });
 
 /**
- * Decide the finding's next status + action from its prior ledger state and
- * the live Issue state. This is the whole reconciliation policy in one place.
+ * The whole reconciliation policy.
  * @param {object|null} existing — prior ledger entry (or null when unseen).
  * @param {{ state: string, stateReason: string|null }|null} issue
  * @returns {{ status: string, action: 'propose'|'known'|'suppress'|'regressed' }}
  */
 function decideStatus(existing, issue) {
-  // A closed Issue is the strongest signal — its close reason drives the
-  // verdict, and it is read FIRST so a recorded `filed` can never outrank it.
+  // A closed Issue outranks any recorded status.
   if (issue && issue.state === 'closed') {
     return issue.stateReason === 'not_planned'
       ? VERDICT.suppress
-      : // Closed as completed (or unspecified) but the finding is in this scan
-        // → it came back. That is a regression, not a fresh proposal.
-        VERDICT.regressed;
+      : VERDICT.regressed;
   }
 
-  // An OPEN tracking Issue means the finding has been filed, whatever the prior
-  // entry said — including when there is no prior entry at all. Until Story
-  // #5305 nothing in the package ever assigned `filed`, so this fell through to
-  // `new`/`propose` on every run and the `filed` arm below was unreachable in
-  // production: the ledger suppressed nothing, and only the GitHub-search dedup
-  // stopped a sweep re-filing what it had already filed. Reading it before the
-  // `!existing` guard is what makes a record pass correct on its FIRST run
-  // rather than its second.
+  // An open Issue means filed even with no prior entry.
   const unseen = issue?.state === 'open' ? VERDICT.filed : VERDICT.propose;
   if (!existing) return unseen;
 
@@ -187,9 +130,7 @@ function decideStatus(existing, issue) {
       return VERDICT.suppress;
     case 'filed':
       return VERDICT.filed;
-    // Recorded fixed, yet detected again with no closed-Issue evidence → treat
-    // as a regression the operator should look at. An open Issue does not
-    // soften that: the finding came back either way.
+    // Recorded fixed yet detected again: a regression, open Issue or not.
     case 'fixed':
       return VERDICT.regressed;
     case 'regressed':
@@ -200,17 +141,15 @@ function decideStatus(existing, issue) {
 }
 
 /**
- * Fold a fresh scan and the live Issue states onto the prior ledger.
+ * Fold a scan and live Issue states onto the prior ledger; untouched entries
+ * are preserved.
  *
  * @param {object} params
- * @param {{ entries?: object[] }} [params.ledger] — prior ledger (default empty).
- * @param {Array<object>} params.findings — parsed/stamped audit findings from this scan.
+ * @param {{ entries?: object[] }} [params.ledger]
+ * @param {Array<object>} params.findings
  * @param {Record<string, { state?: string, stateReason?: string|null, number?: number }>} [params.issueStates]
- *   Live Issue state keyed by fingerprint (or semanticKey). Optional — when a
- *   prior entry already records the Issue, that is used.
- * @param {string} [params.now] — ISO timestamp for firstSeen/lastSeen stamping.
- * @param {(finding: object) => object} [params.toCanonical] — projection onto
- *   the canonical identity; omit when `findings` are already canonical.
+ * @param {string} [params.now]
+ * @param {(finding: object) => object} [params.toCanonical]
  * @returns {{
  *   ledger: { $schema: string, generatedAt: string, entries: object[] },
  *   classifications: Array<{ fingerprint: string, semanticKey: string, status: string, action: string, issue: object|null }>,
@@ -228,7 +167,6 @@ export function reconcileLedger({
   }
 
   const { byFingerprint, bySemanticKey } = indexLedger(ledger);
-  // Preserve any prior entries NOT touched by this scan (their memory survives).
   const nextByFingerprint = new Map(byFingerprint);
   const classifications = [];
 
@@ -263,8 +201,7 @@ export function reconcileLedger({
       lastSeen: now,
     };
 
-    // Re-key under the fresh fingerprint; drop the old entry if it was matched
-    // by semanticKey under a now-drifted fingerprint (reworded finding).
+    // Re-key a reworded finding matched by semanticKey.
     if (existing?.fingerprint && existing.fingerprint !== id.fingerprint) {
       nextByFingerprint.delete(existing.fingerprint);
     }
@@ -290,24 +227,13 @@ export function reconcileLedger({
 }
 
 /**
- * Record a set of already-known identities as filed against one Issue.
- *
- * The finding-shaped {@link reconcileLedger} cannot serve this caller:
- * `plan-persist` never sees findings. It holds the provenance identities it
- * stamped on a Story body — fingerprints and semantic keys, as strings — plus
- * the issue number it just created. That is enough to record the filing, and
- * demanding a finding it does not have would be the reason the recommended
- * planning path never reached this ledger at all.
- *
- * An identity already carrying a **closed** Issue is left exactly as it is: a
- * finding whose tracking Issue was closed `not_planned` is `accepted-risk` and
- * must stay suppressed, and one closed as completed is a `regressed` the
- * operator still needs to see. A fresh filing never overwrites either verdict.
+ * Record identity strings (`plan-persist` has no findings) as filed. An
+ * identity whose Issue is closed is skipped, so its verdict survives.
  *
  * @param {object} params
- * @param {{ entries?: object[] }} [params.ledger] — prior ledger (default empty).
+ * @param {{ entries?: object[] }} [params.ledger]
  * @param {Array<{ fingerprint: string, semanticKey?: string, title?: string, dimension?: string, primaryFile?: string }>} params.identities
- * @param {{ number: number }} params.issue — the Issue these identities were filed as.
+ * @param {{ number: number }} params.issue
  * @param {string} [params.now]
  * @returns {{ ledger: object, recorded: number, skipped: number }}
  */

package/.agents/scripts/lib/findings/classify-finding.js

@@ -1,32 +1,14 @@
 /**
- * lib/findings/classify-finding.js — Finding classification + label routing.
- *
- * A "finding" here is an exploratory-QA ledger item (see
- * `.agents/schemas/qa-ledger.schema.json`, Epic #3686). Each item carries a
- * `class` drawn from a closed enum. `classifyFinding(finding)` resolves that
- * class and routes it to the GitHub label set Triage applies when promoting
- * the item to a follow-up ticket.
- *
- * Pure function: no network I/O. The class → label routing table is the
- * single source of truth for which labels a given finding class maps to;
- * label *names* are pulled from `lib/label-constants.js` so renames land in
- * one place rather than as string literals here.
- *
- * Rejection (not silent defaulting) is the contract: a finding whose class is
- * absent, empty, or outside the enum throws rather than falling back to a
- * default class. A misclassified finding routed to the wrong labels is worse
- * than a loud failure the operator can fix.
+ * lib/findings/classify-finding.js — resolve a QA ledger item's `class` and
+ * route it to the labels Triage applies on promotion. An absent or unknown
+ * class throws rather than defaulting: a mis-routed finding is worse than a
+ * loud failure.
  */
 
 import { META_LABELS } from '../label-constants.js';
 import { normalizeSeverity, SEVERITIES } from './severity.js';
 
-/**
- * Focus-axis labels (Story #3721). These scope a finding to the area of the
- * framework it concerns. They are not in `label-constants.js` because the
- * focus axis is consumer-extensible; the routing table below is the only
- * in-tree consumer, so the literals are defined here and referenced by symbol.
- */
+/** Not in `label-constants.js`: the focus axis is consumer-extensible. */
 export const FOCUS_LABELS = {
   PRODUCT: 'focus::product',
   ENVIRONMENT: 'focus::environment',
@@ -35,11 +17,7 @@ export const FOCUS_LABELS = {
   ENHANCEMENT: 'focus::enhancement',
 };
 
-/**
- * The closed set of finding classes, mirroring the `class` enum in
- * `.agents/schemas/qa-ledger.schema.json`. Exported so callers can validate
- * against the same source of truth.
- */
+/** Mirrors the `class` enum in `.agents/schemas/qa-ledger.schema.json`. */
 export const FINDING_CLASSES = Object.freeze([
   'product-bug',
   'environment-setup',
@@ -49,9 +27,8 @@ export const FINDING_CLASSES = Object.freeze([
 ]);
 
 /**
- * Class → label-set routing table. Each class maps to exactly one label set.
- * `tooling-dx` is the framework-gap path: it carries `meta::framework-gap` so
- * the `/mandrel-plan` Phase 0 feedback fetcher surfaces it to the planner.
+ * `tooling-dx` carries `meta::framework-gap` so `/mandrel-plan` Phase 0
+ * surfaces it.
  */
 const CLASS_TO_LABELS = Object.freeze({
   'product-bug': [FOCUS_LABELS.PRODUCT],
@@ -61,19 +38,11 @@ const CLASS_TO_LABELS = Object.freeze({
   enhancement: [FOCUS_LABELS.ENHANCEMENT, META_LABELS.CONSUMER_IMPROVEMENT],
 });
 
-/**
- * The closed set of severity values a finding can carry, re-exported from the
- * canonical {@link ./severity.js} source of truth (Story #3816) so this module
- * does not re-declare its own list. Ordered highest → lowest:
- * `critical | high | medium | low | info`.
- */
 export { SEVERITIES };
 
 /**
- * Tokens that, when present in a finding's `area`, `labels`, or explicit
- * `security` flag, mark it as security-relevant. The security signal is
- * orthogonal to the class → label mapping: a `product-bug` and a `tooling-dx`
- * finding can both be security-relevant, so this never alters the class route.
+ * Tokens in `area`/`labels` marking a finding security-relevant. Orthogonal
+ * to the class route.
  */
 const SECURITY_TOKENS = Object.freeze([
   'security',
@@ -92,13 +61,6 @@ const SECURITY_TOKENS = Object.freeze([
 ]);
 
 /**
- * Resolve a finding's severity to one of {@link SEVERITIES} via the shared
- * canonical normaliser. An absent, empty, or unrecognised severity resolves to
- * the canonical floor (`info`). Case- and whitespace-insensitive. Delegating to
- * {@link normalizeSeverity} keeps this path bit-for-bit identical to the
- * `promote-finding` path, so the same finding fingerprints the same regardless
- * of which path produced its severity (Story #3816).
- *
  * @param {object} finding
  * @returns {string} one of {@link SEVERITIES}
  */
@@ -107,10 +69,6 @@ function resolveSeverity(finding) {
 }
 
 /**
- * Detect whether a finding is security-relevant. True when the finding sets an
- * explicit truthy `security` flag, OR when any of its `area` / `labels`
- * carries a known security token. Pure string inspection — no network I/O.
- *
  * @param {object} finding
  * @returns {boolean}
  */
@@ -132,8 +90,6 @@ function resolveSecuritySignal(finding) {
 }
 
 /**
- * Resolve the raw `class` field of a finding to a known, non-empty class.
- *
  * @param {object} finding
  * @returns {string} one of {@link FINDING_CLASSES}
  * @throws {TypeError} when `finding` is not an object
@@ -159,24 +115,13 @@ function resolveClass(finding) {
 }
 
 /**
- * Classify a finding into exactly one class, route it to its label set, and
- * carry a severity value plus a security signal alongside.
- *
- * The class → label routing is unchanged: every class still maps to exactly
- * the same label set it always did. `severity` and `security` are additive
- * signal fields the caller can act on (e.g. escalate a high-severity security
- * finding) — they never alter the label set, so no existing class-to-label
- * mapping is dropped.
+ * Classify a finding and route it to its label set. `severity` and `security`
+ * are additive signals; they never alter the labels.
  *
- * @param {object} finding — a ledger item carrying a `class` field, and
- *   optionally `severity` and a `security` flag / security-relevant `area` /
- *   `labels`.
+ * @param {object} finding — a ledger item carrying a `class` field.
  * @returns {{ class: string, labels: string[], severity: string, security: boolean }}
- *   the resolved class, the ordered GitHub labels Triage should apply, the
- *   resolved severity (one of {@link SEVERITIES}; `info` when absent), and
- *   whether the finding is security-relevant.
  * @throws {TypeError|RangeError} on a non-object finding or an
- *   unknown/empty class (never silently defaults).
+ *   unknown/empty class.
  */
 export function classifyFinding(finding) {
   const findingClass = resolveClass(finding);

package/.agents/scripts/lib/findings/promote-finding.js

@@ -1,66 +1,24 @@
 /**
- * lib/findings/promote-finding.js — Promote clustered ledger items to tickets.
- *
- * The `f1-shared-qa-core` promotion step (Epic #3798, Feature #3803). It is the
- * tail of the exploratory-QA Triage path: once an operator has dispositioned a
- * session's ledger items (see `.agents/schemas/qa-ledger.schema.json` and
- * `lib/qa/qa-session.js`), the still-untriaged backlog is clustered and each
- * cluster is promoted to a follow-up ticket — a single Story (via `/mandrel-plan`)
- * for a tight, one-deliverable cluster, or a multi-Story plan-seed (via `/mandrel-plan --seed`) for
- * a broad cluster that spans multiple coverage surfaces. Each contributing
- * ledger item then has the resulting `routedTo` issue link written back onto it
- * so a resume run sees the item as filed rather than re-promoting it.
- *
- * Routing **reuses the shared findings/route logic** — `routeFinding` from
- * `route-finding.js`, the single dedup/route implementation `audit-to-stories`
- * and `qa-explore` already share. It does NOT call `audit-to-stories`: that
- * workflow parses `audit-*-results.md` markdown and is a different intake path.
- * Here a cluster is adapted onto the canonical finding identity, routed against
- * existing Issues, and only a `new` decision opens a fresh ticket; an
- * `update-existing` / `duplicate` / `regression-of-closed` decision links back
- * to the matched Issue without creating a duplicate.
- *
- * Pure orchestration: **no network I/O lives here.** Every GitHub side-effect
- * (issue search, ticket creation) flows through INJECTED PORTS so the unit test
- * runs with no network. Production wires the ports to the GitHub provider /
- * `/mandrel-plan` / `/mandrel-plan` surfaces; tests pass in-memory stubs.
+ * lib/findings/promote-finding.js — promote clustered untriaged QA ledger
+ * items to a Story or plan-seed via `routeFinding`, stamping `routedTo` on
+ * each item so a resume does not re-promote. Ports are injected.
  */
 
 import { fingerprintFinding, routeFinding } from './route-finding.js';
 import { highestSeverity as highestSeverityOf } from './severity.js';
 
-/** Triaged dispositions, mirrored from the `disposition` enum in the schema. */
 const TRIAGED_DISPOSITIONS = Object.freeze(['file', 'defer', 'dismiss']);
 
-/**
- * The two promotion targets a cluster routes to.
- *
- * `PLAN_SEED` promotes a broad cluster by seeding a multi-Story `/mandrel-plan`
- * run (`/mandrel-plan --seed`). Its persisted wire token is the legacy string
- * `'epic'`: archived qa-ledger records (and the distributed
- * `qa-ledger.schema.json` `routedTo.kind` enum) still carry `'epic'`, so
- * the value is kept read-compatible while the write-side constant name is
- * modernised.
- */
+/** `PLAN_SEED` stays `'epic'` on the wire: archived ledgers and the schema enum carry it. */
 export const PROMOTION_TARGETS = Object.freeze({
   STORY: 'story',
   PLAN_SEED: 'epic',
 });
 
-/**
- * A cluster of more than this many distinct coverage surfaces is broad enough
- * to warrant a plan-seed (`/mandrel-plan --seed`) rather than a single Story
- * (`/mandrel-plan`). One or two surfaces is a tight, single-deliverable cluster.
- */
+/** More distinct coverage surfaces than this → plan-seed instead of a Story. */
 const EPIC_COVERAGE_THRESHOLD = 2;
 
 /**
- * True when a ledger item has NOT yet been promoted — i.e. it is part of the
- * rolling backlog. An item is untriaged when its `disposition` is not one of
- * the canonical triaged values, OR it is explicitly dispositioned `file` but
- * has not yet been routed (`routedTo` absent). A `defer` / `dismiss` item, or
- * an already-`routedTo` item, is skipped.
- *
  * @param {{ disposition?: unknown, routedTo?: unknown }} item
  * @returns {boolean}
  */
@@ -69,20 +27,12 @@ export function isPromotable(item) {
   if (item.routedTo) return false;
   const disposition = item.disposition;
   if (disposition === 'defer' || disposition === 'dismiss') return false;
-  // `file` items are promotable; anything not in the triaged set (pending,
-  // untriaged, null, absent) is the rolling backlog and also promotable.
   if (disposition === 'file') return true;
   return !TRIAGED_DISPOSITIONS.includes(disposition);
 }
 
 /**
- * Stable cluster key for a ledger item: its `class`. Items sharing a class
- * describe the same kind of signal (a product bug, a tooling-DX gap, …) and
- * merge into one follow-up ticket. A class whose items span many distinct
- * coverage surfaces is broad enough to promote to a plan-seed (see
- * {@link targetForCluster}); a class confined to one or two surfaces is a
- * single-deliverable Story. Coverage is therefore a *secondary* signal that
- * sizes the cluster rather than splitting it.
+ * Coverage sizes a cluster; it never splits one.
  *
  * @param {{ class?: string }} item
  * @returns {string}
@@ -94,27 +44,15 @@ function clusterKeyFor(item) {
 }
 
 /**
- * The highest severity present across a cluster's items, resolved through the
- * shared canonical {@link ./severity.js} vocabulary (Story #3816). This module
- * no longer declares its own severity rank table — the ordering lives in one
- * place so a cluster severity and a `classify-finding` severity for the same
- * input are identical, keeping the `fingerprintFinding` identity stable.
- *
  * @param {Array<{ severity?: string }>} items
- * @returns {string} one of the canonical severities.
+ * @returns {string}
  */
 function highestSeverity(items) {
   return highestSeverityOf(items.map((item) => item?.severity));
 }
 
 /**
- * Cluster the promotable (untriaged / unrouted) ledger items by coverage
- * surface + class. Returns one cluster per distinct key, each carrying the
- * contributing items, the distinct coverage surfaces it spans, the highest
- * severity in the merge, and a synthesized title. Deterministic: clusters and
- * their items preserve first-seen order.
- *
- * @param {Array<object>} items — ledger items (the full session ledger).
+ * @param {Array<object>} items
  * @returns {Array<{
  *   key: string,
  *   class: string,
@@ -166,11 +104,6 @@ export function clusterLedgerItems(items) {
 }
 
 /**
- * Decide a cluster's promotion target. A cluster that spans more than
- * {@link EPIC_COVERAGE_THRESHOLD} distinct coverage surfaces is broad enough to
- * warrant a plan-seed (`/mandrel-plan --seed`); otherwise it is a single-deliverable
- * Story (`/mandrel-plan`).
- *
  * @param {{ coverages: string[] }} cluster
  * @returns {'story'|'epic'}
  */
@@ -184,10 +117,8 @@ export function targetForCluster(cluster) {
 }
 
 /**
- * Adapt a cluster onto the canonical finding identity that `routeFinding`
- * fingerprints over (`title`, `area`, `primaryFile`, `severity`, `labels`).
- * The coverage surface stands in for `area`; the class becomes a label so two
- * clusters with the same title but different classes fingerprint distinctly.
+ * The class is a label so same-titled clusters of different classes
+ * fingerprint distinctly.
  *
  * @param {{ title: string, coverages: string[], class: string, severity: string }} cluster
  * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string[] }}
@@ -203,13 +134,7 @@ function clusterToFinding(cluster) {
 }
 
 /**
- * Build the `routedTo` link the schema stamps onto a promoted ledger item.
- *
- * The `routedTo.url` field is `minLength: 1` in `qa-ledger.schema.json`,
- * and the search/create port contract requires a
- * routed issue to carry its canonical URL. So rather than silently stamp an
- * empty string (which would persist a schema-invalid ledger item), this guards
- * the url and throws when it is absent or blank (Story #3816, AC #4).
+ * `routedTo.url` is `minLength: 1` in the schema, so an empty url throws.
  *
  * @param {{ number: number, url?: string }} issue
  * @param {'story'|'epic'|'issue'} kind
@@ -233,35 +158,15 @@ function routedToLink(issue, kind) {
 }
 
 /**
- * Promote the clustered untriaged ledger items into Stories / plan-seeds via the
- * shared findings/route logic, then write the resulting `routedTo` issue link
- * back onto each contributing ledger item.
- *
- * For each cluster:
- *   1. Adapt the cluster onto the canonical finding shape and route it with the
- *      shared `routeFinding` against existing Issues (via the injected search
- *      port). This dedups against work already filed.
- *   2. On a `new` decision, open the follow-up ticket through the injected
- *      `createStory` (`/mandrel-plan`) or `createPlanSeed` (`/mandrel-plan --seed`) port,
- *      chosen by {@link targetForCluster}. On any other decision, link back to
- *      the matched Issue rather than creating a duplicate.
- *   3. Stamp the resolved `routedTo` link onto every contributing ledger item
- *      (mutating the item objects in place, so a `qa-session` append persists
- *      the link).
- *
- * All GitHub side-effects flow through the injected ports — there is no network
- * I/O in this module, so the unit test runs offline.
+ * On `new`, create via the target's port; otherwise link to the matched
+ * Issue. Items are mutated in place so a `qa-session` append persists the link.
  *
- * @param {Array<object>} ledgerItems — the full session ledger.
+ * @param {Array<object>} ledgerItems
  * @param {object} ports
  * @param {(sha: string) => Promise<Array<{ number: number, state: string, body?: string }>>} [ports.searchIssues]
- *   Fingerprint-keyed lookup over open+closed issues, forwarded to `routeFinding`.
  * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.searchCandidates]
- *   Optional semantic candidate search, forwarded to `routeFinding`.
  * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createStory
- *   Opens a single Story (`/mandrel-plan`) for a tight cluster.
  * @param {(cluster: object) => Promise<{ number: number, url?: string }>} ports.createPlanSeed
- *   Opens a plan-seed (`/mandrel-plan --seed`) run for a broad cluster.
  * @returns {Promise<{
  *   promotions: Array<{
  *     clusterKey: string,
@@ -312,8 +217,6 @@ export async function promoteFindings(ledgerItems, ports = {}) {
       issue = await createPort(cluster);
       created = true;
     } else {
-      // Already filed (open match, duplicate, or regression of a closed
-      // ticket) — link back to the matched Issue instead of duplicating.
       issue = {
         number: route.matchedIssue.number,
         url: route.matchedIssue.url,
@@ -323,7 +226,6 @@ export async function promoteFindings(ledgerItems, ports = {}) {
     const kind = created ? target : 'issue';
     const link = routedToLink(issue, kind);
 
-    // Write the routedTo link back onto each contributing ledger item.
     for (const item of cluster.items) {
       item.routedTo = { ...link };
     }