mandrel 2.59.0 → 2.61.0

package/.agents/scripts/quality-preview.js

@@ -1,35 +1,9 @@
 #!/usr/bin/env node
 /**
- * .agents/scripts/quality-preview.js — Per-file MI/CRAP delta preview.
- *
- * Runs the maintainability + CRAP gates in-process via the per-kind
- * preview runners under `lib/baselines/preview-gates.js`, then merges
- * their structured envelopes into a single per-file delta table
- * contributors can read while the diff is still warm. Designed for
- * three callers:
- *
- *   1. `npm run quality:preview`   — interactive operator, pretty table.
- *   2. `npm run quality:watch`     — chokidar wrapper re-emits on save.
- *   3. `.husky/pre-commit`         — block the commit on threshold violations.
- *
- * The pre-commit hook passes `--staged` and nothing else — the index is
- * already the exact delta the operator is about to commit, and
- * `tests/pre-commit-hook.test.js` pins that `--changed-since` stays off it.
- * (This docblock previously claimed the hook passed `--changed-since HEAD`,
- * describing a wiring the hook has not used for some time; the stale prose
- * sent at least one bug report at the wrong flag — Story #5131.)
- *
- * `--staged` is merge-aware: while a merge is in progress the index is read
- * against `MERGE_HEAD` rather than `HEAD`, so a base-sync merge commit is
- * scored for the merging branch's own work and its conflict resolutions, not
- * for everything the base branch landed. See `resolveMergeHead` in
- * `lib/changed-files.js`.
- *
- * The CLI exits 0 when both envelopes report zero violations and the script
- * could not surface a regression. Any violation in either envelope, or any
- * non-zero gate exit, propagates as a non-zero exit code so git/husky/CI
- * surface the failure. The merge logic is exported as `mergeEnvelopes` for
- * unit testing without spawning the gate scripts.
+ * quality-preview.js — per-file MI/CRAP delta preview; exits non-zero on any
+ * violation. The pre-commit hook passes only `--staged`. During a merge,
+ * `--staged` reads the index against `MERGE_HEAD` so a base-sync commit is
+ * scored for the branch's own work, not everything the base landed.
  */
 
 import path from 'node:path';
@@ -40,8 +14,7 @@ import {
 } from './lib/baselines/preview-gates.js';
 import { resolveMergeHead } from './lib/changed-files.js';
 import { respondToHelp } from './lib/cli-usage.js';
-import { getQuality, resolveConfig } from './lib/config-resolver.js';
-import { resolveCyclomaticPolicy } from './lib/cyclomatic-ceiling.js';
+import { CODING_GUARDRAILS } from './lib/config/quality.js';
 
 const USAGE = {
   invocation:
@@ -61,26 +34,12 @@ const USAGE = {
   ],
 };
 
-/**
- * Framework default for `delivery.quality.codingGuardrails.cyclomaticFlag`,
- * used only when a caller drives `mergeEnvelopes` / `renderTable` without a
- * resolved config in hand (tests, and the pure-function surface). `runCli`
- * always passes the resolved value.
- */
-const DEFAULT_CYCLOMATIC_FLAG = 8;
+const DEFAULT_CYCLOMATIC_FLAG = CODING_GUARDRAILS.cyclomaticFlag;
 
 /**
- * Parse `--changed-since <ref>` from argv. Defaults to `HEAD` when the flag is
- * present without a value. Returns `null` when the flag is absent so callers
- * can fall through to the gate scripts' own diff defaults.
- *
- * **Last occurrence wins** (Story #4603). `npm run <alias> -- --changed-since <base>`
- * appends the operator's flag *after* any flag baked into the npm script, so a
- * first-wins scan silently discarded the operator's base and compared against
- * the script's hardcoded one instead — reporting a false green for a branch the
- * gate had never actually scored. Last-wins matches the convention every
- * mainstream CLI parser follows for repeated scalar flags, and makes the
- * npm-alias passthrough behave the way its callers already assume.
+ * `--changed-since <ref>` (bare flag → `HEAD`, absent → `null`). Last
+ * occurrence wins so `npm run <alias> -- --changed-since <base>` overrides a
+ * flag baked into the npm script.
  *
  * @param {string[]} argv
  * @returns {string | null}
@@ -96,10 +55,6 @@ export function parseChangedSinceArg(argv) {
 }
 
 /**
- * Detect `--json` (machine-readable mode). When set, the merged envelope is
- * written to stdout as JSON instead of the human-readable table; the exit code
- * still reflects gate health so CI runners can fail fast.
- *
  * @param {string[]} argv
  * @returns {boolean}
  */
@@ -108,10 +63,8 @@ export function parseJsonFlag(argv) {
 }
 
 /**
- * Detect `--staged` (pre-commit mode). Used by `.husky/pre-commit` to
- * scope both MI and CRAP preview gates to `git diff --name-only --cached`
- * so only index (staged) paths are scored. When present, `--staged` takes
- * precedence over `--changed-since`.
+ * `--staged` scores only index paths and takes precedence over
+ * `--changed-since`.
  *
  * @param {string[]} argv
  * @returns {boolean}
@@ -121,9 +74,6 @@ export function parseStagedFlag(argv) {
 }
 
 /**
- * Coerce a caller-supplied flag ceiling to a usable number, falling back to
- * the framework default for anything non-finite.
- *
  * @param {unknown} value
  * @returns {number}
  */
@@ -133,17 +83,11 @@ function normalizeFlag(value) {
 }
 
 /**
- * Fold one CRAP violation into its per-file aggregate row. Mutates `row`.
- *
- * Split out of `mergeEnvelopes` (Story #4923): threading the resolved
- * `cyclomaticFlag` through pushed that function from c=12 — exactly at the
- * must-fix ceiling — to c=13, and the same Story starts *enforcing* that
- * ceiling. Recording its own breach in `baselines/cyclomatic.json` would have
- * been the first re-spend of the slack the Story reclaims.
+ * Fold one CRAP violation into its per-file row (mutates `row`).
  *
  * @param {{ worstCrapDelta: number, newOverCeilingMethods: number }} row
  * @param {{ crap?: number, ceiling?: number, baseline?: number, cyclomatic?: number, kind?: string }} v
- * @param {number} flag resolved `codingGuardrails.cyclomaticFlag`
+ * @param {number} flag
  * @returns {void}
  */
 function foldCrapViolation(row, v, flag) {
@@ -162,27 +106,9 @@ function foldCrapViolation(row, v, flag) {
 }
 
 /**
- * Merge an MI envelope (from `runMaintainabilityPreview`) and a CRAP
- * envelope (from `runCrapPreview`) into a per-file delta map. Pure —
- * no I/O, no spawn. Tests pin the math without invoking the runners.
- *
- * Output rows are keyed by file (forward-slash relative path) and carry:
- *   - `miDrop`: maintainability score drop from baseline (0 when unchanged or
- *     improved). Higher = worse.
- *   - `worstCrapDelta`: largest CRAP regression delta among the file's
- *     methods (max of `crap - baseline` for matched-baseline rows, `crap`
- *     for new-method rows). 0 when the file has no CRAP violations.
- *   - `newOverCeilingMethods`: count of new-method violations (kind:'new')
- *     scoring above the flag ceiling. The CRAP envelope's `cyclomatic` field
- *     is the per-method `c` reading.
- *
- * `cyclomaticFlag` is the resolved
- * `delivery.quality.codingGuardrails.cyclomaticFlag` (Story #4923). It used to
- * be the literal `8` written into this function and into the column header, so
- * a consumer that tuned the knob saw its own value validated by the schema,
- * defaulted by the bootstrap, resolved by `lib/config/quality.js` — and then
- * ignored here. The parameter defaults to the framework default so a caller
- * with no config in hand still gets the historical reading.
+ * Merge MI and CRAP envelopes into per-file rows: `miDrop` (higher = worse),
+ * `worstCrapDelta` (vs baseline, or vs ceiling for new methods), and
+ * `newOverCeilingMethods` (new methods with cyclomatic above the flag).
  *
  * @param {{ violations?: Array<{ file: string, drop?: number }> } | null} miEnvelope
  * @param {{ violations?: Array<{
@@ -249,14 +175,12 @@ export function mergeEnvelopes(
         (crapEnvelope?.summary?.newViolations ?? 0),
     },
     cyclomaticFlag: flag,
-    // Story #5313: advisories ride the merge but never the exit code.
+    // Advisories ride the merge but never the exit code.
     advisories: advisoriesOf(crapEnvelope),
   };
 }
 
 /**
- * The cyclomatic advisories a CRAP envelope carries (Story #5313), or none.
- *
  * @param {{ cyclomaticAdvisories?: unknown } | null | undefined} crapEnvelope
  * @returns {Array<{ file: string, method: string, startLine: number, cyclomatic: number }>}
  */
@@ -266,10 +190,6 @@ function advisoriesOf(crapEnvelope) {
 }
 
 /**
- * Print the advisories block when there is one (Story #5313). Split out of
- * `emitReport` so that function's branching stays inside its committed
- * cyclomatic budget.
- *
  * @param {Array<object>} advisories
  * @param {{ write: (s: string) => void }} stdout
  * @returns {void}
@@ -280,11 +200,6 @@ function writeAdvisories(advisories, stdout) {
 }
 
 /**
- * Render the cyclomatic advisories block (Story #5313), or `null` when the
- * scan carried none. One line per method at or over the ceiling; the block
- * says outright that it is advisory so a reader does not hunt for the exit
- * code it did not change.
- *
  * @param {Array<{ file: string, method: string, startLine: number, cyclomatic: number }>} advisories
  * @returns {string|null}
  */
@@ -300,14 +215,8 @@ export function renderAdvisories(advisories) {
 }
 
 /**
- * Render the named diagnostics a gate envelope carries, or `null` when it
- * carries none (Story #4866).
- *
- * A diagnostic is what a gate emits *instead of* per-method verdicts when it
- * has established that no verdict it could produce would be meaningful — an
- * incomparable baseline, or a comparison basis whose drifted-row ratio proves
- * the two sides disagree on line coordinates. It must reach the operator
- * verbatim: the gate exits 0, so silence would read as a clean run.
+ * Gate diagnostics (emitted instead of verdicts when none would be
+ * meaningful). Surfaced verbatim: the gate exits 0, so silence reads as clean.
  *
  * @param {Array<{ envelope: { diagnostics?: Array<{name: string, message: string}> } | null }>} results
  * @returns {string | null}
@@ -323,18 +232,8 @@ export function renderDiagnostics(results) {
 }
 
 /**
- * Compute the CLI exit code from a merge result + per-gate exit codes. Pure.
- *
- * The exit code is non-zero (1) whenever:
- *   - either gate returned a non-zero exit code (real violations or runtime
- *     failure), OR
- *   - the merged envelope reports any violation rows at all.
- *
- * Both signals are combined so a transient gate failure (e.g. JSON write
- * error) still surfaces even if the violations array happens to be empty.
- *
- * Advisories (`merged.advisories`, Story #5313) are deliberately not read
- * here: a method at cyclomatic 12 or above is reported and exits 0.
+ * 1 on any gate failure or violation (a gate failure counts even with no rows);
+ * advisories never affect it.
  *
  * @param {{ rows: Array<unknown>, totals: { miRegressions: number, crapViolations: number } }} merged
  * @param {number} miExit
@@ -350,28 +249,7 @@ export function computeExitCode(merged, miExit, crapExit) {
 }
 
 /**
- * Render the per-file delta table. Columns:
- *   "file", "MI delta", "worst CRAP delta", "new-method count over c=<flag>".
- *
- * The last header used to hardcode `c=8`, which quietly lied to any consumer
- * that had tuned `codingGuardrails.cyclomaticFlag`. It now names the value the
- * count was actually taken against, read off the merge result — through the
- * same `normalizeFlag` the merge itself uses, rather than the second, hand-
- * inlined copy of that coercion this function used to carry.
- *
- * Pure — accepts pre-computed merge rows and returns a multi-line string. The
- * table renders even on a clean diff so operators see the "no drift" signal.
- *
- * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number }, cyclomaticFlag?: number }} merged
- * @returns {string}
- */
-/**
- * The table's body: one row per regressed file, or the single placeholder
- * line that keeps the "no drift" signal visible on a clean diff.
- *
- * Split out of `renderTable` so that function keeps a flat shape — the
- * empty-vs-populated branch and the row loop together carried it above the
- * per-method CRAP contract the pre-push preview enforces.
+ * Placeholder row on a clean diff keeps the "no drift" signal visible.
  *
  * @param {Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>} rows
  * @returns {string[]}
@@ -384,6 +262,10 @@ function tableBodyLines(rows) {
   );
 }
 
+/**
+ * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number }, cyclomaticFlag?: number }} merged
+ * @returns {string}
+ */
 export function renderTable(merged) {
   const flag = normalizeFlag(merged?.cyclomaticFlag);
   const header = [
@@ -402,39 +284,7 @@ export function renderTable(merged) {
 }
 
 /**
- * Resolve `codingGuardrails.cyclomaticFlag` for the tree at `cwd`
- * (Story #4923), falling back to the framework default when the config cannot
- * be resolved at all.
- *
- * Best-effort by design: `quality:preview` is a developer-facing report, and a
- * run in a tree with no readable `.agentrc.json` should still render its table
- * rather than abort. Extracted from `runCli` rather than inlined so the CLI
- * body stays under the cyclomatic must-fix ceiling this same Story starts
- * enforcing — a gate whose own delivery breaches it is not a gate.
- *
- * @param {{ cwd: string, stderr: { write: (s: string) => void } }} args
- * @returns {number}
- */
-function resolveCyclomaticFlag({ cwd, stderr }) {
-  try {
-    return resolveCyclomaticPolicy(getQuality(resolveConfig({ cwd }))).flag;
-  } catch (err) {
-    stderr.write(
-      `[quality:preview] config resolution failed, using cyclomaticFlag=${DEFAULT_CYCLOMATIC_FLAG}: ${err?.message ?? err}\n`,
-    );
-    return DEFAULT_CYCLOMATIC_FLAG;
-  }
-}
-
-/**
- * Invoke one preview runner, degrading a thrown failure into the same
- * `{ exitCode: 1, envelope: null }` shape a real gate failure produces.
- *
- * Both runners degraded identically before, in two hand-copied `catch`
- * arms; folding them into one helper removes the copy and keeps `runCli` a
- * pipeline rather than a pair of inlined error handlers. The emitted message
- * is byte-identical to the arm it replaces — `label` supplies the `MI` /
- * `CRAP` prefix.
+ * A thrown runner degrades to the `{ exitCode: 1, envelope: null }` shape.
  *
  * @param {(args: object) => Promise<{exitCode: number, envelope: object|null}>} runner
  * @param {{cwd: string, staged: boolean, changedSinceRef: string|null}} args
@@ -452,19 +302,9 @@ function runGateSafely(runner, args, label, stderr) {
 }
 
 /**
- * Render the scope header line.
- *
- * Story #5131 — when `--staged` runs during a merge the scope is re-based to
- * `MERGE_HEAD`, and the header says so. Without that line the operator sees a
- * table whose row count does not match `git diff --cached` with no way to tell
- * the narrowing was deliberate.
- *
- * The merge state is resolved here rather than read back off a gate envelope's
- * `summary.diffRef`: that field means "the ref this scope was resolved
- * against" for every scope kind, so anything that populates it — a future
- * scope mode, a test stub — would render a merge banner over a repo that is
- * not merging. Resolving it after the `!staged` early return also keeps the
- * probe off the `--changed-since` path, which has no use for it.
+ * Scope header; names a `MERGE_HEAD` re-base so the narrowed row count reads as
+ * deliberate. Merge state is probed here, not read off an envelope's `diffRef`
+ * (which every scope kind populates).
  *
  * @param {{ staged: boolean, ref: string|null, cwd: string }} args
  * @returns {string}
@@ -481,13 +321,7 @@ function stagedScopeLine({ staged, ref, cwd }) {
 }
 
 /**
- * Write the run's report — the `--json` envelope, or the human-readable
- * table plus any gate diagnostics and the non-zero-exit summary.
- *
- * Split out of `runCli` (Story #5109): the rendering half carried five of
- * that function's decision points, which put it over the per-method CRAP
- * contract the pre-push preview enforces. Output bytes are unchanged in both
- * modes. The exit code stays with the caller — this function only reports.
+ * Write the `--json` envelope or the table + diagnostics; reports only.
  *
  * @param {{
  *   json: boolean,
@@ -545,10 +379,6 @@ function emitReport({
 }
 
 /**
- * Top-level CLI entry: invoke both per-kind preview runners, merge, render,
- * and exit with the right code. Exposed as `runCli` so tests can drive the
- * full pipeline through injected runner stubs.
- *
  * @param {{
  *   argv?: string[],
  *   cwd?: string,
@@ -571,19 +401,9 @@ export async function runCli({
   const staged = parseStagedFlag(argv);
   const ref = staged ? null : (parseChangedSinceArg(argv) ?? 'HEAD');
 
-  // Story #5109 — the two gates run **one after the other**, not under a
-  // `Promise.all`. Each scores its batch with its own `runOnPool` budget
-  // sized to `os.availableParallelism()`, so overlapping them oversubscribed
-  // the host by 2x and stacked two escomplex heaps: a 58-file preview peaked
-  // at 1.0-1.2 GB RSS for 3.9 s of CPU. Serialising them bounds the preview
-  // to one `availableParallelism` of workers and one heap at a time. The two
-  // runners share no state and neither reads the other's envelope, so the
-  // emitted envelopes — and therefore the merged table and the exit code —
-  // are identical either way; only the peak cost differs.
-  //
-  // Each runner gets its own options literal rather than one shared object,
-  // so serialising them cannot introduce a coupling the concurrent form
-  // did not have.
+  // Serial, not Promise.all: each runner sizes its own pool to
+  // availableParallelism, so overlapping them oversubscribes 2x and stacks
+  // two escomplex heaps (>1 GB RSS).
   const miResult = await runGateSafely(
     runMi,
     { cwd, staged, changedSinceRef: ref },
@@ -597,12 +417,8 @@ export async function runCli({
     stderr,
   );
 
-  // Story #4923 — the over-ceiling column counts against the *resolved*
-  // `codingGuardrails.cyclomaticFlag`, not the literal that used to be written
-  // into `mergeEnvelopes` and the column header.
-  const cyclomaticFlag = resolveCyclomaticFlag({ cwd, stderr });
   const merged = mergeEnvelopes(miResult.envelope, crapResult.envelope, {
-    cyclomaticFlag,
+    cyclomaticFlag: DEFAULT_CYCLOMATIC_FLAG,
   });
 
   emitReport({
@@ -624,7 +440,6 @@ export async function runCli({
 }
 
 // cli-opt-out: Windows-aware main-guard with leading-slash drive-letter normalisation; mirrors quality-watch.js so the diagnostic surface stays consistent across the gate suite.
-// Only run main when invoked directly — keep the module importable from tests.
 const isDirect = (() => {
   try {
     const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';

package/.agents/scripts/resolve-doc-tiers.js

@@ -1,20 +1,7 @@
 /**
- * CLI: resolve the repository's documentation read-tiers (Story #4438).
- *
- * Thin wrapper over `lib/doc-tiers.js#resolveDocTiers` that prints the tier
- * map — `{ tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand } }`,
- * every entry `{ path, bytes }` — as JSON. Consumed by the `audit-documentation`
- * lens (read-tier severity weighting), the `check-context-budget.js` ratchet,
- * and operators inspecting the always-loaded closure.
- *
- * Flags:
- *   --json   emit the tier map as JSON to stdout (default rendering is also
- *            JSON; the flag is accepted for parity with the sibling ratchets
- *            and future non-JSON renderings).
- *   --root <path>  resolve tiers against an explicit repo root (default: the
- *                  resolved PROJECT_ROOT).
- *
- * Exit code is always 0 on success — this is a reporter, not a gate.
+ * CLI: print the documentation read-tier map
+ * (`{ tiers: { alwaysLoaded, mandatoryRead, digestVisible, onDemand } }`,
+ * entries `{ path, bytes }`) as JSON. A reporter, not a gate: exits 0.
  */
 
 import process from 'node:process';
@@ -23,8 +10,6 @@ import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { resolveDocTiers } from './lib/doc-tiers.js';
 
 /**
- * Parse argv for `--root <path>` and `--json`.
- *
  * @param {string[]} argv
  * @returns {{ rootPath: string | null, json: boolean }}
  */
@@ -47,14 +32,6 @@ export function parseArgv(argv = []) {
 }
 
 /**
- * Top-level CLI entry. Exported so tests can drive it against a fixture root
- * with an injected sink and config.
- *
- * The optional final `deps` parameter is the module's injectable seam
- * (`.agents/rules/test-seams.md` rules 1-2): every entry defaults to the real
- * implementation, so the CLI path below — and any production caller — needs no
- * configuration change.
- *
  * @param {{
  *   argv?: string[],
  *   config?: object,

package/.agents/scripts/resolve-stories.js

@@ -1,29 +1,12 @@
 #!/usr/bin/env node
 
 /**
- * resolve-stories.js — resolve a list of Story ids into the
- * `{ stories, dag, done }` envelope `/mandrel-deliver` sequences from.
- *
- * This is the ONE resolution step for multi-Story delivery. `/mandrel-deliver` takes
- * only Story ids; the graph is discovered here, from live state, rather than
- * hand-transcribed by the host or implied by a batch label.
- *
- * What it resolves, per Story:
- *   - the issue itself, fetched with **state=all** so an already-landed
- *     sibling is present rather than silently dropped;
- *   - its dependency edges: the union of the body's `---` footer
- *     (`blocked by #N`, footer-scoped and strict — prose mentioning a blocker
- *     elsewhere in the body declares nothing) and native GitHub `blocked_by`
- *     edges, read to exhaustion and failing loud rather than degrading to
- *     "no edges";
- *   - its declared file footprint, as plain path strings, so the scheduler's
- *     co-dispatch overlap guard has something to work with.
- *
- * And across the set: every dependency id — inside the requested set or
- * foreign to it — is checked against live issue state, and a blocker that is
- * closed or `agent::done` lands in `done[]`. That is what makes "deliver
- * Stories across plan runs and over time" work: a Story whose blocker merged
- * weeks ago in a different run is simply ready.
+ * resolve-stories.js — resolve Story ids into the `{ stories, dag, done }`
+ * envelope `/mandrel-deliver` sequences from, discovering the graph from live
+ * state: footer `blocked by #N` edges union native `blocked_by` edges (read to
+ * exhaustion, failing loud), plus each Story's footprint for the overlap
+ * guard. Every blocker, in-set or foreign, is checked live, so one that landed
+ * in an earlier run lands in `done[]`.
  *
  * Usage:
  *   node .agents/scripts/resolve-stories.js --ids 101,102
@@ -55,22 +38,15 @@ import { paginateRest } from './providers/github/request-helpers.js';
 
 export {
   buildStoriesEnvelope,
-  // Re-exported, not redefined (Story #5280). The reader now lives in
-  // `epic-container.js` beside the shape it reads, so the expansion path and
-  // the rollup share one definition — the pair whose divergence makes an Epic
-  // expandable but unclosable. The name stays exported here because two test
-  // modules import it from this entrypoint.
+  // Re-exported, not redefined: expansion and the Epic rollup must share one
+  // reader or an Epic becomes expandable but unclosable.
   nativeChildReader,
   parseIds,
   readNativeBlockedBy,
   toStoryRecord,
 };
 
-/**
- * Bounded concurrency for the per-issue round-trips. Matches the edge-writer's
- * cap: modest enough for GitHub's secondary rate limits, while collapsing
- * wall-clock from sum(round-trips) toward sum/concurrency.
- */
+/** Modest enough for GitHub's secondary rate limits. */
 const FETCH_CONCURRENCY = 5;
 
 const HELP = `\
@@ -111,13 +87,8 @@ export function resolveStoriesProvider({
 }
 
 /**
- * Fetch every requested id and map it to a Story record, failing on the first
- * id that is not a deliverable Story.
- *
- * Container Epics are expanded to their open child Stories **first**, so
- * everything downstream sees a plain Story-id list (Story #5139). The
- * expansion walk is sequential because it is id-by-id conditional; the Story
- * fetch that follows stays under the bounded concurrency.
+ * Container Epics expand to their open child Stories first; fails on the
+ * first id that is not a deliverable Story.
  *
  * @param {object} provider
  * @param {number[]} ids
@@ -153,12 +124,7 @@ export async function fetchStories(provider, ids, { allowUnlabelled } = {}) {
 }
 
 /**
- * Read native blocked_by edges for every Story in the set.
- *
- * `paginate` is injected rather than imported inside the lib layer so
- * `readNativeBlockedBy` stays provider-agnostic and unit-testable; production
- * passes `paginateRest`, which walks every page (the read used to stop at the
- * first, silently truncating a Story's gates — Story #5046).
+ * `paginate` must walk every page; stopping at one silently drops gates.
  *
  * @returns {Promise<Map<number, number[]>>}
  */
@@ -189,14 +155,8 @@ export async function readNativeEdges({
 }
 
 /**
- * Resolve dependency ids that are NOT in the requested set against live issue
- * state. A foreign blocker that already landed must enter `done[]`, or the
- * scheduler withholds its dependent forever — the exact wedge that made
- * cross-run delivery impossible.
- *
- * A foreign id that cannot be read is left OUT of `done[]`: unknown means
- * "still gating", which withholds the dependent rather than dispatching it
- * against a possibly-unlanded blocker.
+ * A landed foreign blocker must enter `done[]` or its dependent waits forever;
+ * an unreadable one stays out (unknown means still gating).
  *
  * @returns {Promise<number[]>}
  */
@@ -227,11 +187,6 @@ export async function resolveForeignDone({ provider, dag, inSetIds }) {
 }
 
 /**
- * Resolve the requested ids into the `{ stories, dag, done }` envelope and
- * write it to `stdout`. The flow core behind `main` — provider, config, and
- * stdout are injected so the whole path is unit-testable without a live
- * GitHub round-trip. Exported for testing.
- *
  * @param {{ ids: string, native?: boolean, pretty?: boolean,
  *   allowUnlabelled?: boolean }} args
  * @param {{ provider: object, config: object, stdout?: { write(s: string): void } }} deps
@@ -277,9 +232,6 @@ export async function runResolveStories(
 }
 
 /**
- * Project the parsed flags onto the flow core's options object, so `main` reads
- * as parse → help → run and the flag-name spellings live in one place.
- *
  * @param {Record<string, unknown>} values
  * @returns {{ ids: string, native: boolean, pretty: boolean, allowUnlabelled: boolean }}
  */
@@ -301,9 +253,7 @@ async function main() {
       'allow-unlabelled': { type: 'boolean', default: false },
       help: { type: 'boolean', default: false },
     },
-    // The documented opt-out is `--no-native`; without allowNegative,
-    // parseArgs rejects it as an unknown option and the CLI has no working
-    // way to skip the dependencies API.
+    // Required for `--no-native` to parse.
     allowNegative: true,
     allowPositionals: false,
   });
@@ -317,8 +267,7 @@ async function main() {
     throw new Error('[resolve-stories] --ids <n,n,...> is required');
   }
 
-  // stdout is a JSON stream — keep human-readable output on stderr so a
-  // headless caller can pipe this straight into stories-wave-tick.js.
+  // stdout is a JSON stream.
   routeAllOutputToStderr();
 
   return runResolveStories(toRunOptions(values), resolveStoriesProvider());

package/.agents/scripts/resync-status-column.js

@@ -2,26 +2,10 @@
 /* node:coverage ignore file */
 
 /**
- * resync-status-column.js — re-assert the GitHub Projects v2 Status
- * column for a ticket after auto-merge has fired (Story #2845).
- *
- * The `/single-story-deliver` and `/mandrel-deliver` workflow docs call
- * this CLI after Step 5 confirms `state: "MERGED"` so the orchestrator
- * wins the race against the GitHub built-in `Pull request merged`
- * workflow, which would otherwise overwrite Status to whatever value
- * the bot's rule prescribes (typically `In Progress`) ~minutes after
- * the merge lands.
- *
- * Story #2876 — the helper polls the live Status after the initial
- * mutation and re-fires on drift. The one-shot mutation routinely
- * lost the race (reproduced on Story #2871 / PR #2872); the bounded
- * poll loop hardens the defense-in-depth so consumers who haven't
- * disabled the conflicting bot workflows still get a deterministic
- * outcome.
- *
- * Idempotent: re-running on a ticket whose Status already matches the
- * derived target returns the same `synced` envelope and issues the
- * same single GraphQL mutation.
+ * resync-status-column.js — re-assert a ticket's Projects v2 Status after
+ * merge, beating GitHub's built-in "Pull request merged" workflow that
+ * overwrites it minutes later. A one-shot write loses that race, so the live
+ * Status is polled and re-fired on drift. Idempotent.
  *
  * Usage:
  *   node .agents/scripts/resync-status-column.js --ticket <id>
@@ -84,9 +68,7 @@ export function parseArgv(argv) {
 }
 
 /**
- * Pure input-validation extracted so it can be tested without spawning
- * a subprocess. Returns `{ ticketId, pollAttempts, pollDelayMs, errors }`
- * — `errors` is empty on success.
+ * `errors` is empty on success.
  *
  * @param {Record<string, unknown>} values
  */
@@ -136,8 +118,7 @@ export function buildReassertOptions({
   };
   if (pollAttempts !== undefined) opts.pollAttempts = pollAttempts;
   if (pollDelayMs !== undefined) opts.pollDelayMs = pollDelayMs;
-  // Story #4252 — forward the resolved config so ColumnSync's on-disk
-  // board-metadata cache lands under the project's configured tempRoot.
+  // So the board-metadata cache lands under the configured tempRoot.
   if (config !== undefined) opts.config = config;
   return opts;
 }