mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/test-tiers.js

@@ -2,14 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import picomatch from 'picomatch';
 
-/**
- * Globs for slow / integration-style suites excluded from `test:quick`.
- *
- * Curated from `npm run test:profile` (Stories #2742 / #2744). Real-git
- * harnesses, binary-spawn CLI contracts, and other suites whose setup
- * dominates quick-tier feedback stay here; unit-guard / mock paths remain
- * in quick.
- */
+/** Slow suites (real git, binary spawns) excluded from `test:quick`. */
 export const INTEGRATION_INCLUDE = [
   'tests/**/*.integration.test.js',
   'tests/hook-chain-reflog-invariant.test.js',
@@ -24,85 +17,29 @@ export const INTEGRATION_INCLUDE = [
 const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
 
 /**
- * Globs for the `e2e` tier — real-binary suites under `tests/e2e/` that pack
- * this repository, install it into a temp consumer and drive the shipped
- * `mandrel` binary end to end.
- *
- * They are the most expensive files the repository owns by an order of
- * magnitude: one `npm pack` plus real `npm install` spawns per file, measured
- * (Story #5111) at ~7 s of system time and ~17 s of summed install wall clock
- * for `update-chain.integration.test.js` alone. Every one of those seconds was
- * charged to `npm test` — i.e. to every pre-push hook and every local
- * iteration — for a signal that only changes when the release-shaped install
- * path changes.
- *
- * So they get their own tier and leave every other one: `full` (`npm test`),
- * `quick` and `integration` all exclude them, and `npm run test:e2e` is how
- * they run. CI runs that tier as its own job on every PR, so the
- * release-shaped path keeps its per-PR signal.
- *
- * Deliberately not exported: a second reader of this list is a second place
- * for the tier definition to drift. `listTestFilesForTier('e2e', root)` is the
- * public answer to "which files are e2e", and the tests assert through it.
+ * Pack-and-install suites driving the shipped binary — too expensive for
+ * every pre-push, so only `test:e2e` (its own CI job) runs them. Not exported:
+ * `listTestFilesForTier('e2e', root)` is the one reader.
  */
 const E2E_INCLUDE = ['tests/e2e/**/*.test.js'];
 
 const matchesE2E = picomatch(E2E_INCLUDE, { dot: true });
 
-/** Tier names `parseTierArgv` accepts, in the order `--help` lists them. */
 const TIERS = ['full', 'quick', 'integration', 'e2e'];
 
 /**
- * `node --test` flags the runner forwards verbatim to the child.
- *
- * Everything else that looks like a flag is a mistake — a typo, a retired
- * option, or a flag meant for `npm` that landed after the `--` separator —
- * and `parseTierArgv` rejects it rather than passing it to `node --test`,
- * which reads an unknown `--flag` as a *file pattern* and silently runs a
- * suite that matches nothing while exiting 0.
+ * The only flags forwarded to `node --test`; any other `--flag` is rejected,
+ * since `node --test` reads it as a file pattern and exits 0 having run nothing.
  */
 const PASSTHROUGH_FLAGS = ['--test-name-pattern', '--test-only'];
 
-/**
- * Repo-relative roots the tier walker scans for test files (names ending in
- * `.test.js`).
- *
- * `tests` holds the framework's suite tree; `lib` holds the published CLI
- * (under `lib/cli` and `lib/migrations`) whose tests are colocated in
- * `__tests__` directories per the unit-tier convention in
- * `rules/testing-standards.md`. `.agents/scripts` holds the orchestration
- * engine; some of its modules colocate tests in `__tests__` directories the
- * same way (Story #4195). Without each root here, both the quick /
- * integration walk and the full-tier glob set miss the colocated tests,
- * leaving that coverage dark in `npm test`. The matching full-tier globs
- * live in the exported `FULL_TIER_GLOBS` — every full-tier runner
- * (`run-tests.js`, `run-coverage.js`) MUST consume that constant rather than
- * restate a glob literal, or a runner silently walks a narrower surface.
- */
+/** Roots scanned for `*.test.js`, including colocated `__tests__` trees. */
 const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
 
 /**
- * Glob targets for the `full` tier — one per walk root in `TEST_WALK_ROOTS`.
- * The `tests` glob is a flat recursive sweep; the `lib` and `.agents/scripts`
- * globs are scoped to `__tests__` subtrees so they only match colocated
- * tests, never the shipped source modules themselves.
- *
- * Exported because it is the **measured surface**: `run-coverage.js` — the
- * required CI job, and the run every coverage / CRAP baseline is scored from —
- * consumes it directly. Story #4922: the coverage runner used to restate
- * `tests/**` on its own, so the 47 colocated `__tests__` files ran under
- * `npm test` but were absent from the measured surface, leaving the coverage
- * and CRAP numbers computed over code the measuring run never executed.
- * Consume this constant; never restate a glob.
- *
- * Story #5111 made this a strict **superset** of the `full` runner tier: the
- * measured surface still includes `tests/e2e/**`, while `npm test` no longer
- * runs it. That asymmetry is deliberate and load-bearing. The e2e suites drive
- * the shipped binary through `bin/mandrel.js` and `lib/cli/update.js` in real
- * child processes, and c8's `NODE_V8_COVERAGE` is inherited by those children —
- * so dropping them from the measured run would deflate exactly the CLI files
- * they exist to exercise and red the coverage ratchet on code nobody touched.
- * Cheapening the pre-push loop must not cost the measurement its subject.
+ * The measured surface for coverage/CRAP; consume it, never restate a glob.
+ * A superset of the `full` tier: e2e children inherit `NODE_V8_COVERAGE` and
+ * are the only coverage of the CLI entry files.
  */
 export const FULL_TIER_GLOBS = [
   'tests/**/*.test.js',
@@ -132,10 +69,6 @@ function walkTestFiles(dir, prefix, fsLike) {
 }
 
 /**
- * Split the walked set into the `e2e` tier and the remainder every other tier
- * is drawn from, so an e2e file belongs to exactly one tier and `npm test`
- * never pays for it.
- *
  * @param {string[]} all
  * @returns {{ e2e: string[], rest: string[] }}
  */
@@ -146,9 +79,6 @@ function partitionE2E(all) {
 }
 
 /**
- * Split the non-e2e remainder into the slow `integration` tier and the `quick`
- * complement — the historical partition, unchanged.
- *
  * @param {string[]} rest
  * @param {'quick' | 'integration'} tier
  * @returns {string[]}
@@ -163,13 +93,8 @@ function splitBySpeed(rest, tier) {
 }
 
 /**
- * List repo-relative test file paths for a tier.
- *
- * `full` used to return {@link FULL_TIER_GLOBS} verbatim and let `node --test`
- * expand them. It enumerates files instead since Story #5111, because the one
- * thing a glob list cannot express is an exclusion: `node --test` has no
- * negative pattern, so "everything except `tests/e2e/**`" is only sayable as
- * a file set. The measured surface keeps the globs (see `FULL_TIER_GLOBS`).
+ * Repo-relative test files for a tier. Enumerated, not globbed: `node --test`
+ * has no negative pattern to exclude `tests/e2e/**`.
  *
  * @param {'full' | 'quick' | 'integration' | 'e2e'} tier
  * @param {string} repoRoot
@@ -191,15 +116,6 @@ export function listTestFilesForTier(tier, repoRoot, fsLike = fs) {
 }
 
 /**
- * Reject argv tokens that look like flags but are neither `--tier` (already
- * consumed) nor a sanctioned `node --test` pass-through.
- *
- * Silence was the old behaviour and the reason this exists: the runner
- * forwarded every unrecognized token verbatim, and `node --test` treats an
- * unknown `--flag` as another **file pattern**. A typo therefore produced a
- * run that matched nothing, printed a plausible-looking summary and exited 0 —
- * a green that proved nothing.
- *
  * @param {string[]} rest
  * @throws {Error} naming both the accepted tiers and the accepted flags.
  */

package/.agents/scripts/lib/ticket-body-sections.js

@@ -1,35 +1,12 @@
 /**
- * ticket-body-sections.js — marker-delimited managed sections of a
- * planning ticket body.
- *
- * Story #4324 retired the `context::tech-spec` / `context::acceptance-spec`
- * ticket classes: the planning ticket body is the single planning document.
- * The Tech Spec (opening with `## Delivery Slicing`, per #4316) and the
- * Acceptance Spec's AC-ID table (`## Acceptance Table`) land as **managed
- * sections**, delimited by invisible HTML comment markers so each writer
- * can update *only its own region* without rewriting the rest of the body.
- *
- * Section-scoped writes are the load-bearing contract (extending the
- * single-writer discipline #4303 established for the body trailer):
- *
- *   - The `/mandrel-plan` persist path upserts the `techSpec` and `acceptanceTable`
- *     regions.
- *   - The close-time acceptance reconciler
- *     (`acceptance-spec-reconciler.js`) reads and rewrites the
- *     `acceptanceTable` region only (verification dispositions).
- *
- * Everything outside a managed region is byte-preserved by every helper in
- * this module. Markers are chosen so GitHub renders nothing for them; the
- * human-visible headings (`## Delivery Slicing`, `## Acceptance Table`)
- * live INSIDE the regions as ordinary content.
- *
- * Pure ESM, no I/O.
+ * Marker-delimited managed sections of a planning ticket body. Each writer
+ * updates only its own region (persist: `techSpec` + `acceptanceTable`; the
+ * close reconciler: `acceptanceTable` only); every byte outside a region is
+ * preserved. Markers render as nothing on GitHub; visible headings live
+ * inside the regions. Pure, no I/O.
  */
 
 /**
- * Managed-region descriptors. `start`/`end` are the literal marker lines;
- * `label` is the human name used in log lines and error messages.
- *
  * @type {Readonly<Record<'techSpec'|'acceptanceTable', { start: string, end: string, label: string }>>}
  */
 export const TICKET_BODY_SECTIONS = Object.freeze({
@@ -45,19 +22,10 @@ export const TICKET_BODY_SECTIONS = Object.freeze({
   }),
 });
 
-/**
- * Canonical heading the acceptance-table region opens with. Distinct from
- * the ticket's ideation `## Acceptance Criteria` bullets (which remain the
- * SSOT for *what* the table verifies — the table anchors to those bullets).
- */
+/** Distinct from `## Acceptance Criteria`, which stays the SSOT it anchors to. */
 export const ACCEPTANCE_TABLE_HEADING = '## Acceptance Table';
 
-/**
- * Regex matching the Tech Spec's `## Delivery Slicing` heading, tolerating
- * the `Delivery ` qualifier and casing variants. Exported so it is the single
- * source of truth for this pattern — `consolidation-precondition.js` imports
- * it rather than carrying its own copy.
- */
+/** SSOT for the `## (Delivery) Slicing` heading, case-insensitive. */
 export const DELIVERY_SLICING_RE = /^##\s+(?:Delivery\s+)?Slicing\s*$/im;
 
 /**
@@ -75,10 +43,8 @@ function descriptor(kind) {
 }
 
 /**
- * Locate a managed region. Returns `null` when either marker is absent or
- * the end marker precedes the start marker (malformed body — treated as
- * absent so a writer re-appends a well-formed region rather than
- * corrupting the body further).
+ * `null` when a marker is missing or out of order: treated as absent so a
+ * writer re-appends a well-formed region instead of corrupting further.
  *
  * @param {string} body
  * @param {'techSpec'|'acceptanceTable'} kind
@@ -96,8 +62,6 @@ function locate(body, kind) {
 }
 
 /**
- * True when the body carries a well-formed managed region of `kind`.
- *
  * @param {string} body
  * @param {'techSpec'|'acceptanceTable'} kind
  * @returns {boolean}
@@ -107,14 +71,8 @@ export function hasTicketSection(body, kind) {
 }
 
 /**
- * Insert or replace a managed region, preserving every byte outside it.
- *
- * When the region exists, only the content between the markers is
- * replaced. When absent, the region is appended at the end of the body
- * (trailing whitespace normalised to a single blank-line separator). The
- * `techSpec` region is appended before an existing `acceptanceTable`
- * region so the rendered document keeps its canonical order
- * (ideation sections → Tech Spec → Acceptance Table).
+ * Insert or replace a managed region. An absent region is appended, except
+ * `techSpec`, which goes before an existing `acceptanceTable` to keep order.
  *
  * @param {string} body
  * @param {'techSpec'|'acceptanceTable'} kind
@@ -136,8 +94,6 @@ export function upsertTicketSection(body, kind, content) {
     );
   }
 
-  // Keep canonical order when appending: the Tech Spec region goes before
-  // an already-present acceptance-table region.
   if (kind === 'techSpec') {
     const acceptanceLoc = locate(safeBody, 'acceptanceTable');
     if (acceptanceLoc) {
@@ -156,9 +112,7 @@ export function upsertTicketSection(body, kind, content) {
 }
 
 /**
- * Remove a managed region (markers and content). Byte-preserving outside
- * the region; collapses the surrounding blank lines the writer added.
- * No-op when the region is absent.
+ * Remove a region and the blank lines the writer added around it.
  *
  * @param {string} body
  * @param {'techSpec'|'acceptanceTable'} kind
@@ -174,9 +128,7 @@ export function stripTicketSection(body, kind) {
 }
 
 /**
- * Re-plan / decompose detection: true when the ticket body carries folded
- * Tech Spec content — the managed region, or (defence in depth for a
- * hand-authored body) a bare `## Delivery Slicing` heading.
+ * Folded Tech Spec present: the region, or a hand-authored slicing heading.
  *
  * @param {string} body
  * @returns {boolean}
@@ -187,11 +139,7 @@ export function hasTechSpecContent(body) {
 }
 
 /**
- * `##` headings dropped from the delivery-hydrated Epic body. These are
- * ideation / authoring / close-machinery sections a story agent never acts
- * on: keeping them out of the per-Story prompt trims token cost without
- * losing any binding context (the Story carries its own inline
- * acceptance[] / verify[]).
+ * Ideation sections a delivering agent never acts on.
  *
  * @type {ReadonlySet<string>}
  */
@@ -202,21 +150,9 @@ const DELIVERY_DROP_HEADINGS = new Set([
 ]);
 
 /**
- * Slice a planning ticket body down to the sections a delivery story agent acts on.
- *
- * KEEP: the ticket title / preamble before the first `##`, `## Goal`,
- * `## Non-Goals`, `## User Stories`, the `techSpec` managed region, and —
- * fail-open — any unknown / operator-authored `##` section not in the drop
- * list. DROP: `## Context`, `## Scope`, `## Acceptance Criteria`, and the
- * `acceptanceTable` managed region.
- *
- * The `techSpec` region is located by its markers (not by heading
- * boundaries) so its inner `## Delivery Slicing` heading is preserved
- * verbatim and never mistaken for a plain droppable section. Plain `##`
- * sections outside the managed regions are sliced by heading boundaries.
- *
- * Fail-open is load-bearing: any heading not explicitly in the drop set is
- * kept, so operator-authored content is never silently lost.
+ * Slice a planning body to what a delivering agent acts on: drops the
+ * `acceptanceTable` region and the {@link DELIVERY_DROP_HEADINGS} sections.
+ * Fail-open — any other heading is kept so operator content is never lost.
  *
  * @param {string} body
  * @returns {string}
@@ -224,14 +160,10 @@ const DELIVERY_DROP_HEADINGS = new Set([
 export function sliceTicketBodyForDelivery(body) {
   if (typeof body !== 'string' || body.length === 0) return '';
 
-  // 1. Drop the acceptance-table managed region outright (authoring/close
-  //    machinery, never delivery context).
   let working = stripTicketSection(body, 'acceptanceTable');
 
-  // 2. Protect the techSpec managed region from heading-boundary slicing by
-  //    lifting it out behind an opaque placeholder, then restoring it after
-  //    the plain-section pass. Its inner `## Delivery Slicing` heading must
-  //    survive verbatim.
+  // Lift the techSpec region out behind a placeholder so heading slicing
+  // cannot touch its inner `##` headings.
   const techLoc = locate(working, 'techSpec');
   let techRegion = null;
   const PLACEHOLDER = '\u0000MANDREL_TECH_SPEC_PLACEHOLDER\u0000';
@@ -244,9 +176,6 @@ export function sliceTicketBodyForDelivery(body) {
       working.slice(techLoc.endIdx + end.length);
   }
 
-  // 3. Slice plain `##` sections by heading boundaries, dropping only the
-  //    known ideation/authoring headings. The preamble before the first
-  //    `##` (ticket title / lede) is always kept.
   const kept = [];
   let dropping = false;
   for (const line of working.split('\n')) {
@@ -262,12 +191,10 @@ export function sliceTicketBodyForDelivery(body) {
   }
   working = kept.join('\n');
 
-  // 4. Restore the techSpec region in place.
   if (techRegion !== null) {
     working = working.replace(PLACEHOLDER, () => techRegion);
   }
 
-  // 5. Normalise the blank-line runs left by the drops.
   return working
     .replace(/\n{3,}/g, '\n\n')
     .replace(/^\n+/, '')
@@ -275,10 +202,8 @@ export function sliceTicketBodyForDelivery(body) {
 }
 
 /**
- * Strip the retired machine-managed `## Planning Artifacts` checklist from
- * a planning ticket body (the section that linked the now-retired context tickets).
- * The slice ends at the next `## ` heading, a managed-region marker, or
- * EOF. Historical bodies without the section pass through untouched.
+ * Strip a `## Planning Artifacts` section, up to the next `## `, managed
+ * marker, or EOF.
  *
  * @param {string} body
  * @returns {string}

package/.agents/scripts/lib/transpile.js

@@ -26,19 +26,8 @@ function loadTypeScript() {
 let _tsVersion = null;
 
 /**
- * Resolve the `typescript` package version, used to stamp baselines so
- * consumers can detect transpiler drift. Returns `'0.0.0'` when the
- * dependency is unresolvable — callers treat that sentinel as "unknown
- * environment" and may refuse to persist a baseline that includes TS rows.
- *
- * **The version is read from the package manifest, never by evaluating the
- * compiler** (Story #5109) — see
- * [`dependency-version.js`](dependency-version.js) for how, and for what it
- * cost to do it the other way. The manifest returns the identical string, so
- * the stamp (and therefore every committed baseline envelope) is
- * byte-identical either way. The compiler itself is still loaded — lazily, by
- * `transpileIfNeeded` — the first time a `.ts`/`.tsx` input is actually
- * transpiled.
+ * `typescript` version for baseline stamps, read from the manifest (never by
+ * loading the compiler). `'0.0.0'` means unknown environment.
  *
  * @returns {string}
  */
@@ -54,32 +43,18 @@ function isTypeScriptPath(filePath) {
 }
 
 /**
- * Trailing `//# sourceMappingURL=…` comment `ts.transpileModule` appends
- * when `sourceMap: true` is requested. Stripping it makes the emitted code
- * byte-identical to the `sourceMap: false` emit, which is what keeps the
- * maintainability path — and every MI score in the committed baseline —
- * untouched by the CRAP path opting into a map.
+ * Stripped so a `sourceMap: true` emit is byte-identical to the plain one,
+ * keeping MI scores unaffected by the CRAP path's map.
  */
 const SOURCE_MAPPING_URL_RE = /\n?\/\/# sourceMappingURL=[^\n]*\n?$/;
 
 /**
- * Build a `transpiledLine → originalLine` resolver over a raw
- * `sourceMapText` payload, using Node's built-in `SourceMap` (no new
- * runtime dependency).
- *
- * `SourceMap#findEntry(line, column)` is 0-based and returns the mapping at
- * or before the requested position, so a bare `findEntry(line, 0)` can
- * silently answer with a *previous* line's mapping when the requested line
- * carries no mapping at column 0. The resolver therefore walks the columns
- * of the generated line and accepts only an entry that actually originates
- * on that generated line; a line with no mapping at all resolves to `null`
- * and the caller falls back to the un-remapped coordinate.
+ * Memoised `transpiledLine → originalLine` resolver. `findEntry` returns the
+ * mapping at or *before* a position, so columns are walked and only an entry
+ * on the same generated line is accepted; an unmapped line yields `null`.
  *
- * Results are memoised per generated line — a file's methods are looked up
- * once each, but the same line is often probed by several callers.
- *
- * @param {string} sourceMapText Raw JSON source map emitted by TypeScript.
- * @param {string} code The generated (transpiled) code the map describes.
+ * @param {string} sourceMapText
+ * @param {string} code
  * @returns {((line: number) => number|null)|null}
  */
 function buildLineMapper(sourceMapText, code) {
@@ -119,36 +94,9 @@ function buildLineMapper(sourceMapText, code) {
 }
 
 /**
- * Pre-transpile TypeScript or TSX sources to JavaScript that the
- * Esprima-based escomplex kernel can parse. Returns the input unchanged
- * for `.js` / `.mjs` / `.cjs` paths.
- *
- * Type annotations introduce no control flow, so the transpiled output
- * scores identically to the original TS for cyclomatic complexity,
- * Halstead volume, and the maintainability index. `.tsx` uses the
- * `react-jsx` emit so JSX expressions become function calls escomplex
- * can read; `.preserve` would leave JSX in the output and Esprima would
- * choke on it.
- *
- * On transpile failure the helper returns `null` — callers treat that
- * as "skip this file" rather than crashing the scan.
- *
- * **Line coordinates (Story #4775).** The transpile does not preserve line
- * numbers: interface elision and the injected JSX-runtime import shift the
- * emitted code relative to the original source. escomplex then reports each
- * method's `lineStart` in *transpiled* coordinates while istanbul's `fnMap`
- * is in *original source* coordinates — so a per-method coverage join keyed
- * on the raw `lineStart` cannot match. Callers that need to join against
- * coverage pass `{ withLineMap: true }` and receive
- * `{ code, mapLine }`, where `mapLine(transpiledLine)` returns the original
- * source line (or `null` when the line has no mapping).
- *
- * `withLineMap` is opt-in precisely so the maintainability path — which is
- * module-level and never joins coverage — keeps paying nothing for a map it
- * would not read, and keeps emitting byte-identical scores. A JavaScript
- * input is a passthrough in both modes: `mapLine` is `null` because the
- * coordinates already *are* original-source coordinates, so no remap is
- * needed and none is computed.
+ * TS/TSX → JS escomplex can parse (types add no control flow); JS passes
+ * through; `null` means skip. Transpiling shifts lines, so a coverage join
+ * opts into `{ withLineMap: true }` → `{ code, mapLine }` (`null` for JS).
  *
  * @param {string} filePath
  * @param {string} source
@@ -199,17 +147,10 @@ export function transpileIfNeeded(filePath, source, opts = {}) {
 }
 
 /**
- * Prepare a source file for scoring: read it, transpile TS/TSX with a
- * line map, and hand back the JavaScript escomplex will parse alongside the
- * transpiled → original-source line resolver the coverage join needs
- * (Story #4775).
- *
- * Failure is reported as `{error: 'read'}` or `{error: 'transpile'}` rather
- * than a bare null: CRAP drops the file either way, but the combined MI path
- * distinguishes them (a read failure drops the MI score, a transpile failure
- * scores it 0 — matching `calculateForFile`).
+ * Read + transpile with a line map. Read and transpile failures stay
+ * distinct: the MI path drops the score on `read` but scores 0 on `transpile`.
  *
- * @param {string} abs Absolute path of the source file.
+ * @param {string} abs
  * @param {{readFile?: (p: string) => string, transpile?: Function}} [deps]
  * @returns {{code: string, mapLine: ((line: number) => number|null)|null}
  *   | {error: 'read'|'transpile'}}

package/.agents/scripts/lib/util/concurrent-map.js

@@ -1,32 +1,13 @@
 /**
- * concurrentMap — bounded-concurrency async map.
- *
- * Semantics:
- *   - Preserves input order in the returned array (result[i] == mapper(items[i])).
- *   - Cap of at most `concurrency` `mapper` invocations in flight at a time.
- *   - First rejection wins: the returned promise rejects with the first thrown
- *     error. Later rejections from drain-through work are swallowed so the
- *     caller observes a single deterministic failure.
- *   - Drain-on-rejection: workers that are already mid-await finish naturally
- *     (we do not cancel). Only dispatch of *new* items stops after the first
- *     error. This matches fetch-style callers that have no cancellation token
- *     and would leak otherwise.
+ * concurrentMap — bounded-concurrency async map. Preserves input order; the
+ * first rejection wins and stops new dispatch, while in-flight work drains
+ * (no cancellation) and later rejections are swallowed.
  */
 
 /**
- * The one bound every independent-write fan-out over the GitHub API uses
- * (Story #4952 raised those loops off serial; Story #4961 made this the single
- * owner of the number they share). Imported by the `/mandrel-plan` context gathers,
- * the persist checkpoint fan-out, the `agent::ready` flips and the supersede
- * close loop, so re-tuning the policy is one edit rather than six.
- *
- * **Why bounded and not unbounded.** Every unit in those fan-outs is its own
- * API round-trip, so an unbounded map over an N-Story plan dispatches N writes
- * at once — and GitHub answers a burst with a secondary rate limit rather than
- * with throughput. The goal is overlapping unrelated waits, not saturating the
- * API, and four is enough to collapse the latency the serial loops paid while
- * staying well under the burst threshold. Callers whose ordering is
- * load-bearing (`createStoryIssues`) stay serial instead of importing this.
+ * The shared bound for independent GitHub-write fan-outs. Unbounded bursts
+ * earn a secondary rate limit, not throughput; four overlaps the waits while
+ * staying under it. Order-sensitive callers stay serial instead.
  */
 export const FANOUT_CONCURRENCY = 4;
 

package/.agents/scripts/lib/util/parse-id-list.js

@@ -1,51 +1,25 @@
 /**
- * parse-id-list — expand a Story-id list that may contain dash ranges.
- *
- * Operators name a contiguous span of Stories the way they read one — as a
- * range: `/mandrel-deliver 4922 - 4926`. Enumerating it by hand is the kind of
- * transcription step that silently drops or invents an id, so the range is a
- * first-class shape of every delivery id list rather than something the host
- * expands from prose.
- *
- * Accepted tokens, comma-separated:
- *   - a single id, with an optional `#` — `4922`, `#4922`
- *   - an inclusive range — `4922-4926`, `4922 - 4926`, `#4922-#4926`
- *     (hyphen-minus, en dash, or em dash; whitespace around it is fine)
- *
- * Everything else is a hard error, never a silent drop: a wrong id list
- * co-dispatches against the wrong graph, so it must fail where it is typed.
- * Two range-specific guards exist for the same reason — a backwards range is
- * refused rather than expanded to nothing, and a span above `MAX_RANGE_SPAN`
- * is refused rather than resolving thousands of issues off a typo.
+ * parse-id-list — expand a Story-id list that may contain dash ranges
+ * (an id with optional `#` prefix, or `A - B`, en/em dash accepted). Anything else is a
+ * hard error, never a silent drop: a wrong list dispatches against the wrong
+ * graph. Backwards ranges and spans above the cap are refused too.
  */
 
-/**
- * Inclusive-span ceiling for a single range token. Generous against any real
- * plan run (a handful of Stories) and tight enough that `1-4926` is caught as
- * the typo it is rather than fanning out into a live resolution sweep.
- *
- * Deliberately module-private: the cap is a published contract
- * (`helpers/deliver-reference.md` § Ranges), so a test that imported it could
- * not notice the number silently moving out from under the doc.
- */
+// Catches `1-4926` as the typo it is. Module-private because the number is a
+// published contract (`helpers/deliver-reference.md` § Ranges).
 const MAX_RANGE_SPAN = 50;
 
-/** Hyphen-minus, en dash, em dash — whichever the operator's keyboard emits. */
 const DASH = '[-–—]';
 const SINGLE_RE = /^#?(\d+)$/;
 const RANGE_RE = new RegExp(`^#?(\\d+)\\s*${DASH}\\s*#?(\\d+)$`);
 
 /**
- * Parse a comma-separated Story-id list, expanding any `A-B` range token.
- *
- * Absent or empty input is not an error here — it yields an empty list, and
- * the caller decides whether that is a usage error (`--ids`) or a legitimate
- * empty set (`--done`).
+ * Empty input yields `[]`; the caller decides whether that is an error.
  *
  * @param {string|undefined|null} raw
  * @param {object} [options]
  * @param {string} [options.flag] Flag name, for the error message.
- * @param {string} [options.prefix] Message prefix, for the caller's log tag.
+ * @param {string} [options.prefix] Message prefix.
  * @param {number} [options.maxSpan] Inclusive-span ceiling per range token.
  * @returns {{ ids: number[]|null, error: string|null }}
  */

package/.agents/scripts/lib/util/poll-loop.js

@@ -1,25 +1,9 @@
 /**
- * pollUntil — run `fn` on an interval until `predicate(result)` is truthy,
- * the optional `signal` aborts, or `timeoutMs` elapses.
- *
- * Returns the first `fn` result that satisfies `predicate`. If the signal
- * aborts first, resolves to `undefined`. If the timeout elapses, throws.
- *
- * Errors thrown by `fn` are logged via `logger.warn` (if provided) and
- * treated as a non-match — the loop continues until predicate, abort, or
- * timeout. This mirrors the hand-rolled wait loops we replaced, where a
- * single transient fetch error should not terminate the poll.
- *
- * `sleep` is exported as the cancellable delay primitive used internally;
- * callers that already have their own cadence (e.g. a continuous ticker)
- * can import it directly.
- *
- * `sleepFn` is the inter-tick delay seam (Story #4873). A caller that already
- * owns a delay seam of its own — the close-and-land merge wait, whose suite
- * must never actually sleep out a 30s poll interval — passes it here so
- * adopting this primitive does not cost it that seam. It is called as
- * `sleepFn(intervalMs, signal)`; a one-argument stub simply ignores the
- * signal, and the default is the cancellable {@link sleep} below.
+ * pollUntil — run `fn` every `intervalMs` until `predicate(result)` holds
+ * (returns it), `signal` aborts (`undefined`), or `timeoutMs` elapses
+ * (throws). A throwing `fn` is logged and treated as a non-match, so one
+ * transient error never ends the poll. `sleepFn(ms, signal)` lets a caller
+ * keep its own delay seam.
  */
 
 /**
@@ -74,13 +58,9 @@ export async function pollUntil(opts) {
 }
 
 /**
- * Cancellable sleep. Resolves after `ms` or immediately when `signal` aborts.
- *
- * The timer is intentionally NOT `unref`'d — unref'd timers caused Node 22's
- * test runner to cancel subtests that awaited `sleep` with `cancelledByParent`
- * / "Promise resolution is still pending but the event loop has already
- * resolved". Callers that need a clean shutdown should abort the `signal`
- * instead of relying on unref.
+ * Resolves after `ms` or on abort. Deliberately not `unref`'d: Node 22's test
+ * runner cancels subtests awaiting an unref'd timer. Abort the signal for a
+ * clean shutdown instead.
  *
  * @param {number} ms
  * @param {AbortSignal} [signal]