mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/plan-critic-conditions.js

@@ -1,86 +1,47 @@
 /**
- * plan-critic-conditions.js — the pre-mortem critic's dispatch decision for
- * the `/mandrel-plan` critic CLI (Epic #4474 PR6, design §4; narrowed to one
- * arm by Story #5312).
- *
- * The critic is a fresh-context sub-agent dispatch, and the dispatch is
- * **conditional**: the dominant plan cost is turns × standing context, and an
- * unconditional critic pays a full sub-agent spawn even when it provably has
- * nothing to find. This module computes the decision deterministically so
- * the workflow never judges its own dispatch condition.
- *
- * One trigger survives: the **external-dependency probe** (Story #4700),
- * which finds an out-of-repo marker in the plan text — a scoped package the
- * plan names that no manifest declares, a cross-repo reference, an external
- * service prerequisite — so a plan-time discoverable blocker does not reach
- * delivery unquestioned (the swarm-os #757 shape). The probe is deliberately
- * **conservative**: it matches only explicit markers (npm scoped-package
- * specs, `github.com/<owner>/<repo>` URLs, prerequisite-keyword-anchored
- * endpoints), never NLP guesswork.
- *
- * Story #5312 deleted the two triggers that sat beside it — the ticket count
- * reaching half a `maxTickets` budget, and a `planning.riskHeuristics` phrase
- * matching the plan text — with the constants they read. The count trigger
- * was unreachable at the default N=1; the phrase list was empty in every
- * consumer that resolved it. The consolidation critic went with them: its
- * one deterministic input was a `## Delivery Slicing` table no Story carries.
- *
- * Under-firing risk (design PR6 note): the persist validators are unchanged
- * hard gates; every skip decision this module produces is logged to the
- * plan-metrics ledger (`appendCriticSkip`) by the caller so under-firing is
- * auditable.
- *
- * Pure, synchronous, no I/O. The single caller is `plan-critics-evaluate.js`,
- * driven by the `plan-critics.js` CLI the operator runs between Author and
- * Persist when they want the critic; the CLI owns reading the authored
- * artifacts and the resolved config.
+ * plan-critic-conditions.js — the pre-mortem critic's deterministic dispatch
+ * decision. A spawn is costly, so the critic fires only when the
+ * external-dependency probe finds an out-of-repo marker a plan-time review
+ * could catch. The probe is conservative: explicit markers only, never NLP.
+ * Skips are logged by the caller (`appendCriticSkip`) so under-firing is
+ * auditable. Pure, synchronous, no I/O.
  */
 
 /**
  * @typedef {Object} CriticDispatchDecision
  * @property {'pre-mortem'} critic
  * @property {boolean} dispatch
- * @property {string[]} reasons Why the critic fires — or why it is safe to
- *   skip. Never empty: a skip's reasons are the audit trail the
- *   plan-metrics ledger records.
+ * @property {string[]} reasons Never empty — a skip's reasons are its audit
+ *   trail.
  */
 
 /**
- * Explicit npm scoped-package marker: `@scope/name`. Requires the leading `@`
- * and an interior `/`, so bare GitHub handles (`@dsj1984`) and the
- * `@[USERNAME]` operator-handle placeholder never match.
+ * `@scope/name`: the interior `/` keeps bare handles and the `@[USERNAME]`
+ * placeholder from matching.
  */
 const SCOPED_PACKAGE_MARKER = /@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*/gi;
 
-/** Explicit cross-repo marker: a `github.com/<owner>/<repo>` URL. */
 const GITHUB_REPO_MARKER =
   /github\.com\/([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)/gi;
 
 /**
- * Explicit external-service prerequisite marker: a prerequisite keyword
- * followed, within the same clause, by an http(s) endpoint. The keyword gate
- * is what keeps casual documentation links from matching — only an endpoint
- * named as a precondition counts.
+ * A prerequisite keyword then an http(s) endpoint in the same clause; the
+ * keyword gate keeps casual doc links from matching.
  */
 const SERVICE_PREREQ_MARKER =
   /\b(?:requires?|required|prerequisite|provision(?:ed|ing)?|depends?\s+on|credentials?\s+for)\b[^.\n]*?\bhttps?:\/\/([a-z0-9][a-z0-9.-]*)/gi;
 
-/** Order-preserving de-duplication. */
 function uniquePreserveOrder(values) {
   return [...new Set(values)];
 }
 
-/** Quote each item for an evidence reason string. */
 function quoteList(values) {
   return values.map((v) => `"${v}"`).join(', ');
 }
 
 /**
- * Scoped packages named in the plan that no repo manifest declares.
- *
  * @param {string} planText
- * @param {string[]} knownPackages - Package specifiers the repo's own
- *   manifests declare (own name + dependency maps + workspace package names).
+ * @param {string[]} knownPackages - Specifiers the repo's own manifests declare.
  * @returns {string[]}
  */
 function matchExternalScopedPackages(planText, knownPackages) {
@@ -97,9 +58,8 @@ function matchExternalScopedPackages(planText, knownPackages) {
 }
 
 /**
- * `github.com/<owner>/<repo>` references outside the configured repo. When the
- * owner is unknown (no `github.owner` configured) the arm stays silent rather
- * than flag every URL as foreign.
+ * References outside the configured repo; silent when no owner is configured
+ * rather than flag every URL as foreign.
  *
  * @param {string} planText
  * @param {{ owner?: string|null, repo?: string|null }|null} ownerRepo
@@ -125,8 +85,6 @@ function matchCrossRepoRefs(planText, ownerRepo) {
 }
 
 /**
- * Endpoints named as prerequisites in the plan text.
- *
  * @param {string} planText
  * @returns {string[]}
  */
@@ -139,19 +97,12 @@ function matchExternalServicePrereqs(planText) {
 }
 
 /**
- * The external-dependency probe (Story #4700): a conservative, marker-only
- * scan of the draft plan text for artifacts outside the current repo that the
- * plan depends on. A match is the pre-mortem's dispatch condition; a no-match
- * plan skips the critic.
+ * Marker-only scan of the plan text for out-of-repo dependencies.
  *
  * @param {object} input
- * @param {string} [input.planText] - Concatenated plan text (tech spec +
- *   serialized tickets).
- * @param {string[]} [input.knownPackages] - Package specifiers the repo's own
- *   manifests declare, used to tell an external scoped package from a local one.
- * @param {{ owner?: string|null, repo?: string|null }|null} [input.ownerRepo] -
- *   The configured `github.owner`/`github.repo` a cross-repo reference is
- *   measured against.
+ * @param {string} [input.planText] - Tech spec + serialized tickets.
+ * @param {string[]} [input.knownPackages]
+ * @param {{ owner?: string|null, repo?: string|null }|null} [input.ownerRepo]
  * @returns {{ matched: boolean, reasons: string[] }}
  */
 export function evaluateExternalDependencyProbe({
@@ -188,18 +139,10 @@ export function evaluateExternalDependencyProbe({
 }
 
 /**
- * Decide the pre-mortem dispatch: an external-dependency probe match
- * (Story #4700) — the one deterministic trigger left after Story #5312.
- *
  * @param {object} input
- * @param {string} [input.planText] - Concatenated plan text the probe
- *   matches against (tech spec + serialized tickets).
- * @param {string[]} [input.knownPackages] - Package specifiers the repo's own
- *   manifests declare (own name + dependency maps + workspace package names),
- *   passed to the external-dependency probe.
- * @param {{ owner?: string|null, repo?: string|null }|null} [input.ownerRepo] -
- *   The configured `github.owner`/`github.repo`, passed to the
- *   external-dependency probe's cross-repo arm.
+ * @param {string} [input.planText]
+ * @param {string[]} [input.knownPackages]
+ * @param {{ owner?: string|null, repo?: string|null }|null} [input.ownerRepo]
  * @returns {CriticDispatchDecision}
  */
 export function evaluatePremortemDispatch({

package/.agents/scripts/lib/orchestration/plan-critics-evaluate.js

@@ -1,21 +1,7 @@
 /**
- * plan-critics-evaluate.js — shared critic-dispatch evaluation for the
- * collapsed /mandrel-plan flow (#4496 fix 6; pre-mortem only since Story #5312).
- *
- * One consumer: the `plan-critics.js` CLI, which the operator runs between
- * Author and Persist when they want the pre-mortem. The CLI loads the draft
- * artifacts, calls this module, prints the verdict as JSON, and records a
- * skip on the plan-metrics ledger; the workflow dispatches a fresh-context
- * critic sub-agent on a `dispatch: true` verdict and folds the findings into
- * a re-author round before persist.
- *
- * Story #4592 moved that evaluation here from `run-plan-persist.js`, which
- * ran it after authoring was finished and immediately before
- * `createStoryIssues` — the one point where a `dispatch: true` verdict has
- * no re-author loop to route to. Persist no longer evaluates critics; this
- * module has exactly one evaluation point.
- *
- * Pure evaluation: no file I/O, no GitHub calls, no ledger writes — the
+ * plan-critics-evaluate.js — the pre-mortem dispatch evaluation for the
+ * `plan-critics.js` CLI, run between Author and Persist so a
+ * `dispatch: true` verdict still has a re-author loop to route to. Pure: the
  * caller owns artifact loading and skip recording.
  *
  * @module lib/orchestration/plan-critics-evaluate
@@ -24,9 +10,6 @@
 import { evaluatePremortemDispatch } from './plan-critic-conditions.js';
 
 /**
- * Resolve the `{ owner, repo }` the external-dependency probe's cross-repo arm
- * (Story #4700) measures references against, from the canonical `github` block.
- *
  * @param {object} config
  * @returns {{ owner: string|null, repo: string|null }}
  */
@@ -38,23 +21,14 @@ function resolveOwnerRepo(config = {}) {
 }
 
 /**
- * Evaluate the pre-mortem critic's dispatch condition over the authored
- * planning artifacts: the external-dependency probe (Story #4700) matching an
- * out-of-repo marker — a scoped package absent from `knownPackages`, a
- * cross-repo `github.com/<owner>/<repo>` reference, or a named external
- * service prerequisite.
- *
  * @param {{
  *   techSpecContent: string,
  *   tickets?: Array<object>|null,
  *   config?: object,
  *   knownPackages?: string[],
  * }} args
- * @param {string[]} [args.knownPackages] - Package specifiers the repo's own
- *   manifests declare, forwarded to the pre-mortem external-dependency probe
- *   (Story #4700). The caller (the `plan-critics.js` CLI) owns the file I/O
- *   that gathers them; this module stays pure. Empty when unresolved, which
- *   only widens what the probe treats as external.
+ * @param {string[]} [args.knownPackages] - Specifiers the repo's manifests
+ *   declare; empty only widens what counts as external.
  * @returns {{
  *   premortem: { critic: string, dispatch: boolean, reasons: string[] },
  * }}

package/.agents/scripts/lib/orchestration/plan-metrics.js

@@ -1,57 +1,13 @@
 /**
- * plan-metrics.js — append-only plan-invocation ledger (Epic #4474, PR1).
+ * plan-metrics.js — append-only NDJSON ledger of plan CLI invocations
+ * (`{ v, cli, mode, epicId, startedAt, endedAt, durationMs, ok }`) plus
+ * `kind: 'critic-skip'` records. Readers key on `kind`, never on absent
+ * fields. Counts CLI invocations from the parent session, not turns.
  *
- * The `/mandrel-plan` collapse (#4474) is measured, not asserted: before any pipeline
- * phase is removed, every plan CLI invocation stamps an entry/exit record so
- * the current 12-phase baseline is captured on disk. Each record is one
- * newline-terminated JSON line appended to
- * `temp/run-<id>/plan-metrics.json` (per-Epic plan CLIs) or
- * `temp/standalone/plan-metrics.json` (Epic-less plan and healthcheck runs —
- * same standalone routing the friction ledger uses).
- *
- * Record shape (v1):
- *
- * ```json
- * { "v": 1, "cli": "plan-context", "mode": "emit",
- *   "epicId": 4474, "startedAt": "...", "endedAt": "...",
- *   "durationMs": 1234, "ok": true }
- * ```
- *
- * Critic-skip records (Epic #4474 PR6 — additive `kind` extension): the
- * conditional-critic layer logs every skip decision so under-firing is
- * auditable from the same stream:
- *
- * ```json
- * { "v": 1, "kind": "critic-skip", "cli": "plan-critics",
- *   "critic": "pre-mortem", "reasons": ["..."], "epicId": 4474,
- *   "at": "..." }
- * ```
- *
- * Records without a `kind` field are invocation records (the PR1 shape);
- * readers key on `kind`, never on the absence of other fields.
- *
- * Attribution note (#4474 PR1 risk register): these records count **CLI
- * invocations from the parent session's perspective**. Sub-agent sessions
- * spawned by the workflow do not write here; they are attributed separately
- * by the host's session accounting. Do not read `invocations` as "turns".
- *
- * Robustness contract (mirrors `lib/observability/signals-writer.js`):
- *   - **Best-effort writes.** A failed append is a missing metric, not a
- *     failed plan phase — fs errors are swallowed after a `Logger.warn`.
- *   - **No buffering / rotation.** The append tail (open → append one line →
- *     rotate at the byte cap → close) is owned by the shared
- *     `lib/observability/metrics-ledger.js` module (Story #4712); every
- *     appender here routes through it. The close-domain findings-yield
- *     entry point (Story #4699) lives there too, so the story-close review
- *     spine never imports this plan-domain module.
- *   - **Malformed-line tolerance on read.** The reader skips unparseable
- *     lines (counting them) instead of throwing, so a torn write can never
- *     wedge the analyzer.
- *
- * `plan-metrics.json` is intentionally NOT in
- * `lib/plan-phase-cleanup.js#PHASE_TEMP_BASENAMES`: the ledger must survive
- * phase cleanup so the whole plan run (spec → decompose → healthcheck) is
- * visible in one stream.
+ * Writes are best-effort (a failed append is a missing metric, never a failed
+ * phase) via the shared `metrics-ledger.js` tail; reads skip and count
+ * malformed lines. The file deliberately survives phase cleanup so a whole
+ * plan run is one stream.
  */
 
 import fs from 'node:fs/promises';
@@ -63,13 +19,10 @@ import {
   planMetricsPath,
 } from '../observability/metrics-ledger.js';
 
-/** Record kind for a logged critic skip decision (Epic #4474 PR6). */
 export const PLAN_METRICS_KIND_CRITIC_SKIP = 'critic-skip';
 
 /**
- * Append one invocation record to the ledger. Best-effort: returns `false`
- * (after a `Logger.warn`) instead of throwing on any fs failure, so metric
- * capture can never fail a plan phase.
+ * Append one invocation record. Best-effort: warns and returns `false`.
  *
  * @param {{
  *   cli: string,
@@ -126,12 +79,8 @@ export async function appendPlanMetric(entry, config, opts = {}) {
 }
 
 /**
- * Append one critic-skip audit record (Epic #4474 PR6). Every conditional
- * critic that decides NOT to dispatch logs the decision here — with the
- * deterministic reasons — so an under-firing critic layer (a distorted
- * plan sailing through) is auditable after the fact. Best-effort with the
- * same contract as `appendPlanMetric`: a failed append can never fail the
- * plan step.
+ * Append a critic-skip record with its reasons, so an under-firing critic
+ * layer is auditable. Best-effort like `appendPlanMetric`.
  *
  * @param {{
  *   critic: string,
@@ -181,10 +130,8 @@ export async function appendCriticSkip(entry, config, opts = {}) {
 }
 
 /**
- * Wrap one plan CLI invocation: stamp `startedAt`, run `fn`, stamp
- * `endedAt` + `ok`, append the record, and re-throw the original error on
- * failure. The metric write itself is best-effort and can never mask or
- * replace the wrapped function's outcome.
+ * Run `fn` and record the invocation; the metric write never masks `fn`'s
+ * outcome.
  *
  * @template T
  * @param {{ cli: string, mode: string, epicId?: number|null, config?: object }} meta
@@ -216,9 +163,7 @@ export async function recordPlanInvocation(meta, fn) {
 }
 
 /**
- * Read the active ledger generation. Missing file → `{ entries: [],
- * malformedLines: 0, missing: true }`. Malformed lines are skipped and
- * counted, never thrown.
+ * Read the active ledger generation; malformed lines are counted, not thrown.
  *
  * @param {number|null} epicId
  * @param {object} [config]
@@ -256,22 +201,18 @@ export async function readPlanMetrics(epicId, config) {
 }
 
 /**
- * Roll a read ledger up into the compact summary surfaced by the persist
- * summary. (Story #4545 deleted its second consumer, `analyze-execution.js`,
- * with the execution-analysis surface.) Returns `null` when there is nothing
- * to summarize (missing ledger or zero parseable entries).
- *
- * Critic-skip records (kind: 'critic-skip') are counted separately from
- * invocations — `criticSkips` totals them and `criticSkipsByCritic` breaks
- * them down, so the skip-audit trail is visible in the persist summary
- * without inflating the turns-per-plan proxy.
- *
- * Pass `opts.since` (an ISO-8601 instant) to scope the roll-up to one plan
- * run (Story #4541). The Epic-less ledger at `temp/standalone/` is shared by
- * every plan the repo has ever run, so an unfiltered summary reported
- * lifetime totals under a line the reader takes to describe the invocation
- * in front of them. Records are timestamped `startedAt` (invocations) or
- * `at` (critic skips); either at-or-after `since` is in scope.
+ * @param {object} entry
+ * @returns {string|null}
+ */
+function recordTimestamp(entry) {
+  const stamp = typeof entry?.kind === 'string' ? entry.at : entry?.startedAt;
+  return typeof stamp === 'string' ? stamp : null;
+}
+
+/**
+ * Roll a ledger up for the persist summary; `null` when empty. Critic skips
+ * are tallied apart from invocations. `opts.since` (ISO-8601) scopes to one
+ * run — the standalone ledger is shared by every plan ever run.
  *
  * @param {{ entries: object[], malformedLines?: number }} ledger
  * @param {{ since?: string|null }} [opts]
@@ -289,23 +230,10 @@ export async function readPlanMetrics(epicId, config) {
  *   malformedLines: number,
  * }|null}
  */
-/**
- * Timestamp a ledger record is ordered by: `startedAt` for invocation
- * records, `at` for kinded records (critic-skip, findings-yield).
- *
- * @param {object} entry
- * @returns {string|null}
- */
-function recordTimestamp(entry) {
-  const stamp = typeof entry?.kind === 'string' ? entry.at : entry?.startedAt;
-  return typeof stamp === 'string' ? stamp : null;
-}
-
 export function summarizePlanMetrics(ledger, opts = {}) {
   const all = ledger?.entries ?? [];
   const since = typeof opts.since === 'string' ? opts.since : null;
-  // ISO-8601 UTC strings sort lexicographically in time order, so a string
-  // compare is a correct (and allocation-free) instant compare here.
+  // ISO-8601 UTC strings compare correctly as strings.
   const entries =
     since === null
       ? all
@@ -333,9 +261,7 @@ export function summarizePlanMetrics(ledger, opts = {}) {
       continue;
     }
     if (typeof e.kind === 'string') {
-      // Any other kinded record (e.g. `findings-yield`, Story #4699) is not
-      // an invocation — readers key on `kind`, never on absent fields, so it
-      // must not inflate the invocation/failure tallies.
+      // Other kinded records (e.g. `findings-yield`) are not invocations.
       continue;
     }
     invocationEntries.push(e);
@@ -375,11 +301,6 @@ export function summarizePlanMetrics(ledger, opts = {}) {
 }
 
 /**
- * Render the one-line human summary (snapshot-tested). Example:
- *
- *   `plan-metrics: 3 invocation(s) (1 failed) across plan-context ×1,
- *    plan-critics ×1, plan-persist ×1 — span 12m 3s`
- *
  * @param {ReturnType<typeof summarizePlanMetrics>} summary
  * @returns {string}
  */
@@ -409,7 +330,7 @@ export function renderPlanMetricsSummaryLine(summary) {
 }
 
 /**
- * Compact duration formatter: `45s`, `12m 3s`, `2h 5m`.
+ * `45s`, `12m 3s`, `2h 5m`.
  *
  * @param {number} ms
  * @returns {string}

package/.agents/scripts/lib/orchestration/plan-navigation.js

@@ -1,19 +1,9 @@
 /**
- * plan-navigation.js — shared navigability helpers for the persist-side
- * draft reachability check (`plan-reachability.js`).
- *
- * Extracted from the retired `epic-plan-healthcheck.js` so the live
- * draft-ticket scan owns its own mechanics without pulling in the
- * deleted post-plan healthcheck CLI.
+ * plan-navigation.js — navigability helpers for `plan-reachability.js`.
  */
 
 /**
- * Resolve the navigation config that drives the reachability check.
- *
- * The check is opt-in: a consumer that has not configured
- * `planning.navigation.routeGlobs` gets a silent no-op. The nav-registry
- * token list is what a route-adding Story is expected to reference
- * somewhere in its body or `## Acceptance` section.
+ * Opt-in: no `planning.navigation.routeGlobs` means a silent no-op.
  *
  * @param {object} config Resolved `.agentrc.json`.
  * @returns {{ routeGlobs: string[], navRegistry: string[] }}
@@ -31,20 +21,15 @@ export function resolveNavConfig(config) {
 }
 
 /**
- * Translate a route glob (`pages/**`, `app/**\/route.ts`) into a RegExp that
- * matches a path string. Supports `**` (any depth, including `/`), `*` (any
- * run of non-separator chars), and `?` (single non-separator char). All other
- * characters are matched literally.
+ * `**` any depth, `*` any non-separator run, `?` one non-separator char;
+ * everything else literal.
  *
  * @param {string} glob
  * @returns {RegExp}
  */
 export function globToRegExp(glob) {
-  // Collapse adjacent `**` segments before compiling. `**/**` and `***` both
-  // mean "any depth", but compiling them literally emits adjacent `.*` runs
-  // (`.*/.*` / `.*.*`) that backtrack catastrophically on a long non-matching
-  // path. Collapsing to a single `**` preserves semantics and keeps the
-  // matcher linear (ReDoS hardening).
+  // Collapse `**/**` and `***` to `**`: adjacent `.*` runs backtrack
+  // catastrophically on long non-matching paths (ReDoS).
   const normalized = glob
     .replace(/\*\*(?:\/\*\*)+/g, '**')
     .replace(/\*{3,}/g, '**');
@@ -68,10 +53,8 @@ export function globToRegExp(glob) {
 }
 
 /**
- * Extract the candidate route-touching paths a Story declares. Reads the
- * `## Changes` block (the decompose-author emits one `{"path":...}` JSON
- * object per bullet) and falls back to any bare `` `path/like/this` ``
- * inline-code spans in the body.
+ * Paths a Story declares: `"path": "…"` change descriptors plus path-like
+ * inline code spans.
  *
  * @param {string} body
  * @returns {string[]}
@@ -79,11 +62,9 @@ export function globToRegExp(glob) {
 export function extractStoryPaths(body) {
   if (typeof body !== 'string' || body.length === 0) return [];
   const paths = new Set();
-  // `{"path":"pages/foo.tsx", ...}` change descriptors.
   for (const m of body.matchAll(/"path"\s*:\s*"([^"]+)"/g)) {
     paths.add(m[1]);
   }
-  // Inline-code spans that look like a path (contain a slash or a dotted ext).
   for (const m of body.matchAll(/`([^`]+)`/g)) {
     const token = m[1].trim();
     if (/[/.]/.test(token) && !token.includes(' ')) paths.add(token);

package/.agents/scripts/lib/orchestration/plan-persist/acceptance-handle-repair.js

@@ -1,24 +1,7 @@
 /**
- * acceptance-handle-repair.js — repair-before-judging for the `AC-<n>:`
- * presentation handle on authored acceptance items (Story #5323).
- *
- * The handle belongs to the body renderer, which numbers each checkbox from
- * its position in `acceptance[]` (`story-body.js`). An author planning from
- * an existing ticket reads that rendered body as a template and carries the
- * handle forward, so the persisted checkbox reads `- [ ] AC-1: AC-1: …`; a
- * lettered handle copied out of a hand-edited source (`AC-14a:`) misnumbers
- * the rest of the list against its own text.
- *
- * The correction is mechanical and total — strip the handle the renderer
- * will re-apply — so this module applies it and **reports** it, exactly as
- * `changes-repair.js` does for the `{ path, assumption }` formality. Charging
- * the author a re-draft round to paste back text the strip already produced
- * buys nothing.
- *
- * It lives beside the validator rather than inside it for the same reason
- * `changes-repair.js` does: the validator's job is to judge, and mixing a
- * mutating repair pass into a module of pure collectors muddies both.
- * `persist-helpers.js#validateTickets` calls this first, then the validators.
+ * Strip an authored `AC-<n>:` handle from acceptance items (the body renderer
+ * numbers checkboxes itself, so a carried handle doubles or misnumbers) and
+ * report each strip rather than refusing.
  *
  * @module lib/orchestration/plan-persist/acceptance-handle-repair
  */
@@ -27,13 +10,10 @@ import { stripAcceptanceHandle } from '../../story-body/story-body.js';
 import { renderChangeRepair } from './changes-repair.js';
 
 /**
- * Strip the handle off one surface's `acceptance[]`, recording each distinct
- * strip on `repairs`.
- *
- * @param {object} surface An object that may carry an `acceptance` array.
+ * @param {object} surface
  * @param {string} slug
- * @param {Set<string>} reported Items already reported for this ticket.
- * @param {object[]} repairs Accumulator, mutated.
+ * @param {Set<string>} reported
+ * @param {object[]} repairs Mutated.
  * @returns {void}
  */
 function repairSurface(surface, slug, reported, repairs) {
@@ -51,18 +31,9 @@ function repairSurface(surface, slug, reported, repairs) {
 }
 
 /**
- * Strip the presentation `AC-<n>:` handle off every authored `acceptance[]`
- * item, on both surfaces that can carry one: the ticket's top-level array
- * (the machine contract) and a structured body's.
- *
- * A serialized **string** body needs no pass of its own — `parse()` strips
- * the handle with the same grammar this does, so the two surfaces converge
- * on one list whichever carried the handle, and the contract sync (which
- * fails closed on a disagreement) sees them agree.
- *
- * Mutates `tickets` in place — the persist pipeline threads this same array
- * on to assembly. Total: a non-array argument and non-Story tickets are
- * no-ops.
+ * Covers the top-level array and a structured body; a string body needs no
+ * pass since `parse()` strips with the same grammar, so the fail-closed
+ * contract sync sees both agree. Mutates `tickets` in place.
  *
  * @param {object[]} tickets
  * @returns {Array<{ kind: 'acceptance-handle', slug: string, from: string, to: string }>}
@@ -74,8 +45,7 @@ export function normalizeAcceptanceHandles(tickets) {
       continue;
     }
     const slug = ticket.slug ?? ticket.title ?? '<unknown>';
-    // A ticket normally carries the same list on both surfaces, so report
-    // each distinct item once — the operator reads one correction, not two.
+    // Both surfaces usually carry the same list; report each item once.
     const reported = new Set();
     repairSurface(ticket, slug, reported, repairs);
     const body = ticket.body;
@@ -87,15 +57,8 @@ export function normalizeAcceptanceHandles(tickets) {
 }
 
 /**
- * Render one entry of the dry-run's mixed repair list.
- *
- * The list carries two kinds — a `changes[]` entry repaired by probing base,
- * and an `acceptance[]` item whose handle was normalised off — and both are
- * mechanical corrections the run applied on the author's behalf, so both
- * belong on the one list the operator reads. This module owns the dispatch
- * because it owns the newer kind: it renders its own line and delegates
- * every other kind to `changes-repair.js`, so neither producer has to know
- * the other's shape.
+ * Render one entry of the mixed repair list; non-handle kinds delegate to
+ * `changes-repair.js`.
  *
  * @param {{ kind?: string, slug: string, from: string, to?: string }} repair
  * @returns {string}