mandrel 2.24.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/reserved-test-ids.js

@@ -0,0 +1,77 @@
+/**
+ * lib/reserved-test-ids.js — the framework's one declaration of which
+ * Epic / Story ids are **synthetic** (Story #4892).
+ *
+ * The band `999000–999999` has been reserved for test fixtures since the
+ * post-test temp reaper shipped, but it lived as a private regexp inside
+ * `cleanup-repo-test-temp.js` (`/^epic-999\d{3}$/`) and nothing else could
+ * consult it. Two independent surfaces need the same rule, and spelling it
+ * twice is how they would drift:
+ *
+ *   1. **Write side.** A test that spawns a real CLI at the repository root
+ *      inherits the real state directory, so its fixture telemetry can land
+ *      in the operator's live `temp/` signals tree. The post-run guard in
+ *      `check-test-temp-hygiene.js` fails the run when a stream file owned by
+ *      a reserved id survives there.
+ *   2. **Read side.** The retro composer renders the distinct Stories a
+ *      friction bucket spans as recurrence evidence in a body that is filed
+ *      as a real GitHub issue. A reserved id is synthetic by construction, so
+ *      it can never be resolved to a real issue and must never be published
+ *      as evidence (issue #4870 named `#999999` as a contributing Story).
+ *
+ * Deliberately dependency-free: the write side is a CLI guard and the read
+ * side is a pure composer, so the shared rule must not drag config, fs, or
+ * git resolution into either.
+ */
+
+/** First id in the reserved test-fixture band. */
+const RESERVED_TEST_ID_MIN = 999000;
+
+/** Last id in the reserved test-fixture band. */
+const RESERVED_TEST_ID_MAX = 999999;
+
+/**
+ * Human-readable band, for guard failure messages that have to tell an
+ * operator which ids they may not use for real work.
+ */
+export const RESERVED_TEST_ID_BAND = `${RESERVED_TEST_ID_MIN}–${RESERVED_TEST_ID_MAX}`;
+
+/**
+ * Is `id` inside the reserved test-fixture band?
+ *
+ * Exact-band membership, because this is the predicate the temp reaper and
+ * the pollution guard share: both classify an on-disk directory that a test
+ * created, and over-reaching (treating every large id as reserved) would let
+ * one of them delete or condemn a directory the band never claimed.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isReservedTestId(id) {
+  return (
+    Number.isInteger(id) &&
+    id >= RESERVED_TEST_ID_MIN &&
+    id <= RESERVED_TEST_ID_MAX
+  );
+}
+
+/**
+ * May `id` be published as ticket evidence in operator-visible output?
+ *
+ * The floor is the reserved band, not the band itself: an id at or above
+ * `RESERVED_TEST_ID_MIN` is synthetic by construction (the framework reserves
+ * that space for fixtures, and no repository has minted that many issues), so
+ * nothing at or beyond the floor can be resolved to a real issue. A
+ * non-integer or non-positive id is not a ticket reference at all.
+ *
+ * This is a plausibility bound, not an existence probe: it is the strongest
+ * statement a caller with no ticket-provider access can make, and it is what
+ * keeps the invariant true at every call site instead of only where somebody
+ * remembered to wire a probe.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isPublishableTicketId(id) {
+  return Number.isInteger(id) && id > 0 && id < RESERVED_TEST_ID_MIN;
+}

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