mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/orchestration/story-follow-ups.js

@@ -464,6 +464,156 @@ function renderDiscardedItem(item) {
   return parts.join(' — ');
 }
 
+/**
+ * Normalize the two loosely-typed inputs into the four buckets every section
+ * renderer reads. Absorbs the optional-chain / nullish-coalesce cluster that
+ * otherwise all lands on `buildFollowUpsCommentBody` (Story #4926).
+ *
+ * @param {object|null|undefined} proposals
+ * @param {object|null|undefined} graduated
+ * @returns {{ filed: object[], framework: object[], consumer: object[],
+ *   discarded: object[], filingErrors: string[] }}
+ */
+function normalizeRollupBuckets(proposals, graduated) {
+  const asArray = (value) => (Array.isArray(value) ? value : []);
+  return {
+    filed: asArray(graduated?.filed),
+    framework: asArray(proposals?.framework),
+    consumer: asArray(proposals?.consumer),
+    discarded: asArray(proposals?.discarded),
+    filingErrors: asArray(graduated?.errors),
+  };
+}
+
+/**
+ * Render the "**Filed**" section, or nothing when no proposal was filed.
+ *
+ * @param {object[]} filed
+ * @returns {string[]}
+ */
+function renderFiledSection(filed) {
+  if (filed.length === 0) return [];
+  return [
+    '**Filed**',
+    ...filed.map(
+      (item) =>
+        `- ${item.source}: ${item.title}${item.url ? ` — ${item.url}` : ''}`,
+    ),
+    '',
+  ];
+}
+
+/**
+ * Render the "**Actionable (not auto-filed)**" fallback — the command stanzas
+ * an operator runs by hand when auto-filing produced nothing.
+ *
+ * @param {object[]} actionable framework + consumer, in that order
+ * @param {object[]} filed
+ * @returns {string[]}
+ */
+function renderActionableSection(actionable, filed) {
+  if (actionable.length === 0 || filed.length > 0) return [];
+  const lines = ['**Actionable (not auto-filed)**'];
+  for (const item of actionable) {
+    lines.push(`- ${item.source}: ${item.title}`, '', '```bash', item.command);
+    lines.push('```');
+  }
+  lines.push('');
+  return lines;
+}
+
+/**
+ * Render the "**Below threshold (not filed)**" section.
+ *
+ * @param {object[]} discarded
+ * @returns {string[]}
+ */
+function renderDiscardedSection(discarded) {
+  if (discarded.length === 0) return [];
+  return [
+    '**Below threshold (not filed)**',
+    ...discarded.map(
+      (item) => `- ${item.source}: ${renderDiscardedItem(item)}`,
+    ),
+    '',
+  ];
+}
+
+/**
+ * Render the all-empty branch. Story #4828 — "no proposals" has two readings,
+ * and only one of them is a quiet run. Signals gathered but nothing routed is
+ * the third instance of the silence Stories #4578 and #4824 each fixed once.
+ *
+ * @param {{ empty: boolean, outcome: {zeroProposals: boolean},
+ *   signalCount: number, categories: object[], storyCount: number }} args
+ * @returns {string[]}
+ */
+function renderEmptySection({
+  empty,
+  outcome,
+  signalCount,
+  categories,
+  storyCount,
+}) {
+  if (!empty) return [];
+  return [
+    ...(outcome.zeroProposals
+      ? renderZeroProposalLines(signalCount, categories)
+      : renderEmptyRollupLines(storyCount)),
+    '',
+  ];
+}
+
+/**
+ * Build the machine-readable twin of the rendered prose. Every suspect flag
+ * above has a field here so a caller never has to regex the body.
+ *
+ * @param {object} args
+ * @returns {object}
+ */
+function buildRollupPayload({
+  storyId,
+  storyCount,
+  signalCount,
+  categories,
+  buckets,
+  empty,
+  outcome,
+}) {
+  const { filed, framework, consumer, discarded, filingErrors } = buckets;
+  return {
+    storyId,
+    storyCount,
+    // Story #4828 — the corpus the roll-up actually read. Without it a
+    // reader cannot tell "0 proposals because nothing recurred" from
+    // "0 proposals because routing broke".
+    signalCount,
+    categories,
+    framework: framework.map((i) => i.category),
+    consumer: consumer.map((i) => i.category),
+    // Story #4824 — the machine-readable twin of the row above. A bare
+    // category list could not distinguish a genuine one-off from a
+    // recurrence the window was too narrow to see, so the count, the
+    // cross-Story span, and the shape fingerprint ride along.
+    discarded: discarded.map((i) => ({
+      category: i.category,
+      occurrences: i.occurrences,
+      storyCount: i.storyCount ?? null,
+      fingerprint: i.fingerprint ?? null,
+    })),
+    filed: filed.map((i) => ({ category: i.category, url: i.url ?? null })),
+    // Story #4578 — an empty roll-up over N>1 Stories is a claim worth
+    // flagging, not a success. Machine-readable twin of the warning
+    // prose so a caller need not regex the body.
+    emptyRollupSuspect: storyCount > 1 && empty && signalCount === 0,
+    // Story #4828 — the two remaining shapes that used to render as
+    // success. Machine-readable twins of the warning prose above.
+    zeroProposalSuspect: outcome.zeroProposals,
+    unfiledProposalSuspect: outcome.unfiledProposals,
+    filingErrors,
+  };
+}
+
 /**
  * @param {{
  *   storyId: number,
@@ -487,13 +637,14 @@ export function buildFollowUpsCommentBody({
   signalCount = 0,
   categories = [],
 }) {
-  const filed = Array.isArray(graduated?.filed) ? graduated.filed : [];
-  const framework = proposals?.framework ?? [];
-  const consumer = proposals?.consumer ?? [];
-  const discarded = proposals?.discarded ?? [];
+  const buckets = normalizeRollupBuckets(proposals, graduated);
+  const { filed, framework, consumer, discarded } = buckets;
+  const actionable = [...framework, ...consumer];
+  const empty =
+    filed.length === 0 && actionable.length === 0 && discarded.length === 0;
   const outcome = assessRollupOutcome({
     signalCount,
-    proposalCount: framework.length + consumer.length,
+    proposalCount: actionable.length,
     discardedCount: discarded.length,
     filedCount: filed.length,
     filingErrors: graduated?.errors,
@@ -504,103 +655,39 @@ export function buildFollowUpsCommentBody({
     '',
     `Actionable follow-ups captured from Story #${storyId} after merge.`,
     '',
+    ...(outcome.unfiledProposals
+      ? [
+          ...renderUnfiledProposalLines(
+            actionable.length,
+            buckets.filingErrors,
+            outcome.blockingSkipReasons,
+          ),
+          '',
+        ]
+      : []),
+    ...renderFiledSection(filed),
+    ...renderActionableSection(actionable, filed),
+    ...renderDiscardedSection(discarded),
+    ...renderEmptySection({
+      empty,
+      outcome,
+      signalCount,
+      categories,
+      storyCount,
+    }),
+    '```json',
   ];
-  if (outcome.unfiledProposals) {
-    lines.push(
-      ...renderUnfiledProposalLines(
-        framework.length + consumer.length,
-        Array.isArray(graduated?.errors) ? graduated.errors : [],
-        outcome.blockingSkipReasons,
-      ),
-      '',
-    );
-  }
-  if (filed.length > 0) {
-    lines.push('**Filed**');
-    for (const item of filed) {
-      lines.push(
-        `- ${item.source}: ${item.title}${item.url ? ` — ${item.url}` : ''}`,
-      );
-    }
-    lines.push('');
-  }
-  if (framework.length + consumer.length > 0 && filed.length === 0) {
-    lines.push('**Actionable (not auto-filed)**');
-    for (const item of [...framework, ...consumer]) {
-      lines.push(`- ${item.source}: ${item.title}`);
-      lines.push('');
-      lines.push('```bash');
-      lines.push(item.command);
-      lines.push('```');
-    }
-    lines.push('');
-  }
-  if (discarded.length > 0) {
-    lines.push('**Below threshold (not filed)**');
-    for (const item of discarded) {
-      lines.push(`- ${item.source}: ${renderDiscardedItem(item)}`);
-    }
-    lines.push('');
-  }
-  if (
-    filed.length === 0 &&
-    framework.length === 0 &&
-    consumer.length === 0 &&
-    discarded.length === 0
-  ) {
-    // Story #4828 — "no proposals" has two readings, and only one of them is
-    // a quiet run. Signals gathered but nothing routed is the third instance
-    // of the silence Stories #4578 and #4824 each fixed once.
-    lines.push(
-      ...(outcome.zeroProposals
-        ? renderZeroProposalLines(signalCount, categories)
-        : renderEmptyRollupLines(storyCount)),
-    );
-    lines.push('');
-  }
-  lines.push('```json');
   lines.push(
     JSON.stringify(
-      {
+      buildRollupPayload({
         storyId,
         storyCount,
-        // Story #4828 — the corpus the roll-up actually read. Without it a
-        // reader cannot tell "0 proposals because nothing recurred" from
-        // "0 proposals because routing broke".
         signalCount,
         categories,
-        framework: framework.map((i) => i.category),
-        consumer: consumer.map((i) => i.category),
-        // Story #4824 — the machine-readable twin of the row above. A bare
-        // category list could not distinguish a genuine one-off from a
-        // recurrence the window was too narrow to see, so the count, the
-        // cross-Story span, and the shape fingerprint ride along.
-        discarded: discarded.map((i) => ({
-          category: i.category,
-          occurrences: i.occurrences,
-          storyCount: i.storyCount ?? null,
-          fingerprint: i.fingerprint ?? null,
-        })),
-        filed: filed.map((i) => ({
-          category: i.category,
-          url: i.url ?? null,
-        })),
-        // Story #4578 — an empty roll-up over N>1 Stories is a claim worth
-        // flagging, not a success. Machine-readable twin of the warning
-        // prose so a caller need not regex the body.
-        emptyRollupSuspect:
-          storyCount > 1 &&
-          filed.length === 0 &&
-          framework.length === 0 &&
-          consumer.length === 0 &&
-          discarded.length === 0 &&
-          signalCount === 0,
-        // Story #4828 — the two remaining shapes that used to render as
-        // success. Machine-readable twins of the warning prose above.
-        zeroProposalSuspect: outcome.zeroProposals,
-        unfiledProposalSuspect: outcome.unfiledProposals,
-        filingErrors: Array.isArray(graduated?.errors) ? graduated.errors : [],
-      },
+        buckets,
+        empty,
+        outcome,
+      }),
       null,
       2,
     ),

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -816,6 +816,28 @@ export function renderFanOutRemedy(finding) {
   );
 }
 
+/**
+ * The finding kinds that are genuinely **cross-Story conflicts** — the SSOT
+ * for that question (Story #4907).
+ *
+ * Two readers need it and must not disagree: the validator, which renders
+ * these through {@link renderHardConflictError} when policy upgrades them to
+ * `errors[]`, and the persist soft-finding surface, which announces a
+ * conflict as a conflict and every other soft kind (`spec-word-budget`,
+ * `merge-candidate`, `unanchored-constant`, `missing-reason-to-exist`) as the
+ * advisory it is. A second copy of this list is how the two drift back apart,
+ * so it is defined exactly once and imported.
+ */
+export const CONFLICT_KINDS = Object.freeze(
+  new Set([
+    'shared-editor',
+    'implicit-cross-story-dep',
+    'cross-cutting-registries',
+    'fan-out-warning',
+    'missing-bdd-scaffold',
+  ]),
+);
+
 /**
  * Render a `'hard'`-severity conflict finding as a human-readable error
  * message. Used by the validator when policy flags upgrade a finding to

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -10,6 +10,7 @@ import {
   parseStoryBodyOrThrow,
 } from './story-body-gate.js';
 import {
+  CONFLICT_KINDS,
   computeConflictFindings,
   renderHardConflictError,
 } from './ticket-validator-conflicts.js';
@@ -666,25 +667,18 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
     policy: opts.conflictPolicy,
   });
   // Advisory `## Spec` word-budget pass (Story #4723) — soft findings only,
-  // surfaced as warnings here and via the persist soft-finding channel;
   // never promoted to `errors[]`, so an over-budget Spec cannot fail the
   // persist. Runs after `assertStoryBodiesParse`, so string bodies parse.
+  // This pass computes but does not report: the sole production caller always
+  // runs the persist soft-finding surface, which reports every soft kind
+  // uniformly. Warning here too made `spec-word-budget` the only kind logged
+  // twice per run (Story #4907).
   const specBudgetFindings = computeSpecBudgetFindings({ stories });
-  for (const finding of specBudgetFindings) {
-    Logger.warn(`[ticket-validator] spec-word-budget: ${finding.message}`);
-  }
   const findings = [
     ...sizingFindings,
     ...conflictFindings,
     ...specBudgetFindings,
   ];
-  const CONFLICT_KINDS = new Set([
-    'shared-editor',
-    'implicit-cross-story-dep',
-    'cross-cutting-registries',
-    'fan-out-warning',
-    'missing-bdd-scaffold',
-  ]);
   const errors = findings
     .filter((f) => f.severity === 'hard')
     .map((f) =>

package/.agents/scripts/lib/orchestration/ticketing/reads.js

@@ -180,7 +180,7 @@ export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;
  * authoritative entry — the label set is the actual race-detection signal).
  * Bounded to 1-9 digits to mirror the wave-marker safety margin.
  */
-export const CLAIM_TYPE_PATTERN = /^claim-([0-9]{1,9})$/;
+const CLAIM_TYPE_PATTERN = /^claim-([0-9]{1,9})$/;
 
 /**
  * Lifecycle-listener marker pattern (Story #2239 / #2241 / #2242). The
@@ -189,7 +189,7 @@ export const CLAIM_TYPE_PATTERN = /^claim-([0-9]{1,9})$/;
  * `lifecycle-epic-unblocked`). Treated as a generic prefix so future
  * listener-owned events can mint new markers without touching this enum.
  */
-export const LIFECYCLE_TYPE_PATTERN = /^lifecycle-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const LIFECYCLE_TYPE_PATTERN = /^lifecycle-[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 /**
  * @param {string} type
@@ -273,7 +273,7 @@ export function structuredCommentMarker(type, attrs = null) {
  * cannot leak across boundaries. Tests reset via the exported
  * `_resetStructuredCommentCache()` seam.
  */
-export const _structuredCommentCache = new WeakMap();
+const _structuredCommentCache = new WeakMap();
 
 /**
  * Build a well-formed ticket snapshot for a Story that has zero child
@@ -359,7 +359,7 @@ export function structuredCommentCacheKey(ticketId, type, attrs) {
  *   - Scoped per-provider via WeakMap so test fakes never share state
  *     with the real GitHubProvider.
  */
-export const _rawCommentsCache = new WeakMap();
+const _rawCommentsCache = new WeakMap();
 
 /**
  * Lookup (or lazily create) the per-provider raw-comments cache.

package/.agents/scripts/lib/story-adjacency.js

@@ -7,10 +7,10 @@
  * records into the `Map<storyId, number[]>` adjacency the kernel consumes.
  * This module is now the one home for that step; the live consumer is:
  *
- *   - `lib/wave-runner/ready-set.js` (`selectReadySet`, the path-agnostic
+ *   - `lib/wave-runner/ready-set.js` (`planReadySet`, the path-agnostic
  *     continuous scheduler the `stories-wave-tick.js` adapter dispatches through)
  *   - `stories-wave-tick.js` (for cycle detection, before delegating
- *     selection to `selectReadySet`)
+ *     selection to `planReadySet`)
  *
  * (Pre-v2: `epic-runner/phases/build-wave-dag.js` and `dispatch-pipeline.js`
  * also called here; both entry seams were deleted.)
@@ -44,7 +44,7 @@ import { parseBlockedBy } from './dependency-parser.js';
  * @param {object} [opts]
  * @param {boolean} [opts.dropForeign=false] When `false` (the v2 default,
  *   matching the `/deliver` path — `stories-wave-tick.js` and the
- *   `selectReadySet` core), the operator-DAG contract is preserved: a
+ *   `planReadySet` core), the operator-DAG contract is preserved: a
  *   dependency on an id absent from the input is treated as not-yet-done
  *   and withholds the dependent until it completes. When `true` (the
  *   pre-v2 Epic-scoped-wrapper semantics), edges pointing at ids outside

package/.agents/scripts/lib/test-runner-contract.js

@@ -0,0 +1,134 @@
+/**
+ * The contract every test-running entrypoint shares: the `node --test` flag
+ * set, and the per-tier preflight.
+ *
+ * ## Why this is a module and not two literals (Story #4936)
+ *
+ * The repository has two full-tier runners — `run-tests.js` (`npm test`) and
+ * `run-coverage.js` (`npm run test:coverage`, the *required* CI job). When
+ * they disagree about a `node --test` flag, they disagree about whether a
+ * test can execute at all: `--experimental-test-module-mocks` decides whether
+ * `t.mock.module` works, so a divergence makes a suite pass under one runner
+ * and fail under the other with no source defect. `FULL_TIER_GLOBS` in
+ * [`test-tiers.js`](test-tiers.js) already solved the sibling problem for
+ * *which files* run; this module is the same fix for *how they are run*.
+ * Both runners import from here; neither restates a literal.
+ *
+ * ## The preflight is invoked, never hooked
+ *
+ * `.npmrc` sets `ignore-scripts=true` as deliberate defence against malicious
+ * postinstall hooks (CWE-1357). That setting is correct and stays — but it
+ * suppresses every `pre*` / `post*` lifecycle script for `npm run` as well as
+ * for installs, so a `pretest` entry in `package.json` never fires. The
+ * repository carried `pretest`, `pretest:quick` and `pretest:integration`
+ * entries that therefore ran for no tier at all, and Story #4922 worked
+ * around it for the coverage tier alone by having CI name `pretest:coverage`
+ * explicitly. `runTierPreflight` closes the gap for every tier by moving the
+ * invocation into the runners, where it executes under `npm test`,
+ * `npm run test:coverage`, and a bare `node .agents/scripts/run-tests.js`
+ * alike — no lifecycle hook involved.
+ */
+
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+/** Minimum and maximum bounds for `--test-concurrency`. */
+export const TEST_CONCURRENCY_MIN = 1;
+export const TEST_CONCURRENCY_MAX = 16;
+
+/**
+ * Resolve the `--test-concurrency` value for the current host.
+ *
+ * Uses `os.availableParallelism()` (Node ≥18.14 / ≥20.0) clamped to the
+ * range `[TEST_CONCURRENCY_MIN, TEST_CONCURRENCY_MAX]`. The `parallelism`
+ * parameter is injected in tests so the clamping logic is verifiable
+ * without touching the OS.
+ *
+ * @param {number} [parallelism] - defaults to `os.availableParallelism()`
+ * @returns {number}
+ */
+export function resolveTestConcurrency(
+  parallelism = os.availableParallelism(),
+) {
+  return Math.min(
+    TEST_CONCURRENCY_MAX,
+    Math.max(TEST_CONCURRENCY_MIN, parallelism),
+  );
+}
+
+/**
+ * Fixed `node --test` flags applied to every spawn of every runner.
+ *
+ * `--test-concurrency` is derived at startup from the host's available
+ * parallelism so the value suits the machine running the suite rather than
+ * being pinned to the historical constant of 8.
+ *
+ * This is the **single** declaration. A flag added here reaches both runners;
+ * a flag added to one runner's argv builder instead is caught by the
+ * flag-set equality assertion in `tests/scripts/run-coverage.test.js`.
+ */
+export const TEST_RUNNER_FLAGS = Object.freeze([
+  '--experimental-test-module-mocks',
+  '--test',
+  `--test-concurrency=${resolveTestConcurrency()}`,
+]);
+
+/**
+ * Preflight scripts per tier, repo-relative. These are the definitions that
+ * used to live in `package.json` as inert `pretest*` entries.
+ *
+ * `full` carries the skills validator on top of the state-probe wrapper
+ * because the full tier is the release-shaped run (and the surface the
+ * coverage tier measures); `quick` and `integration` run the state probe
+ * only, matching the tiers' historical `pretest:quick` / `pretest:integration`
+ * definitions. The coverage runner runs the full tier, so it shares `full`.
+ *
+ * Deliberately not exported: a second importer would be a second place to
+ * read the tier→preflight mapping from, and tests assert the mapping through
+ * the spawns `runTierPreflight` actually issues — which is the thing that
+ * has to be true.
+ */
+const TIER_PREFLIGHT_SCRIPTS = Object.freeze({
+  full: Object.freeze([
+    '.agents/scripts/test-wrapper.js',
+    '.agents/scripts/validate-skills.js',
+  ]),
+  quick: Object.freeze(['.agents/scripts/test-wrapper.js']),
+  integration: Object.freeze(['.agents/scripts/test-wrapper.js']),
+});
+
+/**
+ * Run the preflight for a tier, in order, stopping at the first failure.
+ *
+ * Mirrors npm's own `pre<script>` semantics — a failed preflight aborts
+ * before the test runner is spawned and propagates its exit code (the
+ * wrapper reserves 2 for "preflight refused") — except that it actually
+ * executes, which the npm hook does not under `ignore-scripts=true`.
+ *
+ * @param {object} [opts]
+ * @param {'full' | 'quick' | 'integration'} [opts.tier]
+ * @param {string} [opts.repoRoot] Absolute repository root.
+ * @param {typeof spawnSync} [opts.spawn] Injected in tests.
+ * @param {string} [opts.execPath] Node binary to spawn; injected in tests.
+ * @returns {number} 0 when every preflight script passed, else the first
+ *   non-zero exit code.
+ */
+export function runTierPreflight({
+  tier = 'full',
+  repoRoot = process.cwd(),
+  spawn = spawnSync,
+  execPath = process.execPath,
+} = {}) {
+  for (const script of TIER_PREFLIGHT_SCRIPTS[tier] ?? []) {
+    const run = spawn(execPath, [path.join(repoRoot, script)], {
+      cwd: repoRoot,
+      stdio: 'inherit',
+    });
+    if (run.error) throw run.error;
+    const status = run.status ?? 1;
+    if (status !== 0) return status;
+  }
+  return 0;
+}

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

@@ -35,7 +35,9 @@ const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
  * 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 `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.
  */
 const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
 
@@ -44,8 +46,15 @@ const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
  * 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 the full tier has two runners, not one: `run-tests.js`
+ * (via `listTestFilesForTier`) and `run-coverage.js`. 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.
  */
-const FULL_TIER_GLOBS = [
+export const FULL_TIER_GLOBS = [
   'tests/**/*.test.js',
   'lib/**/__tests__/**/*.test.js',
   '.agents/scripts/**/__tests__/**/*.test.js',

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

@@ -13,6 +13,23 @@
  *     and would leak otherwise.
  */
 
+/**
+ * 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 `/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.
+ */
+export const FANOUT_CONCURRENCY = 4;
+
 /**
  * @template T, R
  * @param {ReadonlyArray<T>} items