mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -24,6 +24,10 @@ import {
   parse as parseStoryBody,
   serialize as serializeStoryBody,
 } from '../../story-body/story-body.js';
+import {
+  concurrentMap,
+  FANOUT_CONCURRENCY,
+} from '../../util/concurrent-map.js';
 import { assertSpecWithinBudget } from '../spec-spill.js';
 import { assertAcceptancePartition } from '../split-policy-validator.js';
 import {
@@ -795,6 +799,14 @@ async function ensurePersistLabel({
  * (see `ensureCohortLabel`). `/deliver` never reads it — delivery stays
  * ids-only over live state (Story #4540's actual point).
  *
+ * **The create loop stays serial and dependency-ordered** — deliberately, and
+ * unlike every other per-Story loop on this path (Story #4952). It is not an
+ * independent fan-out: `renderStoryBodyForCreate(story, idBySlug)` resolves a
+ * Story's `depends_on` slugs to the real issue ids its siblings were just
+ * minted with, and `idBySlug` is filled *in loop order* by the POSTs
+ * themselves. Running it concurrently would render `#undefined` dependency
+ * refs for any Story whose dependency had not yet returned an id.
+ *
  * **Sibling order is mirrored into native GitHub `blocked_by` edges** once
  * every id is known (Story #4544), so plan-created order stops depending on
  * prose. That pass is non-fatal — see `mirrorNativeDependencyEdges`.
@@ -960,6 +972,16 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
  * Fails closed: an un-flipped Story is invisible to `/deliver`, which is the
  * safe direction — the operator is told exactly which ids need the label.
  *
+ * **Collect failures, never fast-fail** (preserved verbatim under the
+ * Story #4952 concurrency conversion). Every Story is attempted even when an
+ * earlier one's PATCH rejects, because the whole value of the closing error is
+ * naming the *complete* set of ids that still need the label by hand. The
+ * mapper below therefore absorbs its own rejection into a per-Story outcome
+ * rather than letting `concurrentMap`'s first-rejection-wins policy abandon
+ * the remaining flips. `concurrentMap` preserves input order, so `readied[]`
+ * and the reported failures come back in `created[]` order exactly as the
+ * serial loop produced them.
+ *
  * @param {object} args
  * @param {object} args.provider
  * @param {Array<{ id: number, slug: string }>} args.created
@@ -972,18 +994,32 @@ export async function markStoriesReady({ provider, created }) {
         'Stories to agent::ready.',
     );
   }
-  const readied = [];
-  const failed = [];
-  for (const story of created) {
-    try {
-      await provider.updateTicket(story.id, {
-        labels: { add: [AGENT_LABELS.READY] },
-      });
-      readied.push(story.id);
-    } catch (err) {
-      failed.push(`#${story.id} (${story.slug}): ${err.message}`);
-    }
-  }
+  const outcomes = await concurrentMap(
+    created,
+    async (story) => {
+      try {
+        await provider.updateTicket(story.id, {
+          labels: { add: [AGENT_LABELS.READY] },
+        });
+        return { id: story.id, failure: null };
+      } catch (err) {
+        return {
+          id: story.id,
+          failure: `#${story.id} (${story.slug}): ${err.message}`,
+        };
+      }
+    },
+    // The terminal per-Story `agent::ready` PATCHes (Story #4952): each flip
+    // is an independent single-issue write, so the loop was serial only by
+    // construction. A latency fix, not a throughput one.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+  const readied = outcomes
+    .filter((outcome) => outcome.failure === null)
+    .map((outcome) => outcome.id);
+  const failed = outcomes
+    .filter((outcome) => outcome.failure !== null)
+    .map((outcome) => outcome.failure);
   if (failed.length > 0) {
     throw new Error(
       `[plan-persist] ${failed.length} Story(ies) were created with their ` +

package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js

@@ -36,6 +36,10 @@
  */
 
 import { Logger } from '../../Logger.js';
+import {
+  concurrentMap,
+  FANOUT_CONCURRENCY,
+} from '../../util/concurrent-map.js';
 import { upsertStructuredComment } from '../ticketing.js';
 
 /** Structured-comment type marking a source issue as superseded. */
@@ -440,41 +444,94 @@ export async function closeSupersededTickets({
   const createdBySlug = new Map(
     (created ?? []).map((story) => [story.slug, story]),
   );
-
-  const report = emptyReport({ enabled: true, dryRun });
-
-  for (const story of stories ?? []) {
-    const createdStory = createdBySlug.get(story.slug);
-    for (const { id, note } of story.supersedes ?? []) {
+  const units = collectSupersedeUnits(stories, createdBySlug);
+
+  // Story #4952 — one bounded fan-out across distinct source tickets. The
+  // mapper inherits `closeOneSupersededTicket`'s never-throw contract (and
+  // resolves the two pre-write outcomes itself), so `concurrentMap`'s
+  // first-rejection-wins policy can never fire and no unit is abandoned
+  // because a sibling failed. Input order is preserved, so the report arrays
+  // below read exactly as the serial nested loop wrote them.
+  const outcomes = await concurrentMap(
+    units,
+    ({ id, note, createdStory }) => {
       if (!createdStory) {
-        report.skipped.push({ ticket: id, reason: 'story-not-created' });
-        continue;
-      }
-      if (dryRun) {
-        report.planned.push({ ticket: id, storySlug: createdStory.slug });
-        continue;
+        return { outcome: 'skipped', reason: 'story-not-created' };
       }
-      const result = await closeOneSupersededTicket({
+      if (dryRun) return { outcome: 'planned' };
+      return closeOneSupersededTicket({
         provider,
         id,
         note,
         story: createdStory,
         sourceTicketIds: sources,
       });
-      if (result.outcome === 'closed') {
-        report.closed.push(id);
-      } else if (result.outcome === 'skipped') {
-        report.skipped.push({ ticket: id, reason: result.reason });
-      } else {
-        report.failed.push({ ticket: id, reason: result.reason });
-      }
-    }
-  }
+    },
+    // The per-source-ticket close (Story #4952) fans out across **distinct**
+    // tickets — `assertSupersedePartition` has already failed the run closed
+    // if two Stories claim the same id, so no two units in flight can touch
+    // the same issue. Within one unit the probe → comment → close sequence
+    // stays strictly ordered: commenting on an issue the probe reported
+    // closed, or closing one the comment never landed on, is the whole
+    // failure mode this phase is careful about.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+
+  const report = emptyReport({ enabled: true, dryRun });
+  outcomes.forEach((result, index) => {
+    recordSupersedeOutcome(report, units[index], result);
+  });
 
   logSupersedeReport(report);
   return report;
 }
 
+/**
+ * Flatten the per-Story `supersedes[]` maps into one list of close units, in
+ * the nested iteration order the report arrays are expected to follow.
+ *
+ * @param {Array<{ slug: string, supersedes?: Array<{ id: number, note: string|null }> }>|undefined} stories
+ * @param {Map<string, { slug: string, id: number, title: string }>} createdBySlug
+ * @returns {Array<{ id: number, note: string|null, createdStory: object|undefined }>}
+ */
+function collectSupersedeUnits(stories, createdBySlug) {
+  const units = [];
+  for (const story of stories ?? []) {
+    const createdStory = createdBySlug.get(story.slug);
+    for (const { id, note } of story.supersedes ?? []) {
+      units.push({ id, note, createdStory });
+    }
+  }
+  return units;
+}
+
+/**
+ * File one unit's outcome onto the report.
+ *
+ * @param {SupersedeReport} report
+ * @param {{ id: number, createdStory: object|undefined }} unit
+ * @param {{ outcome: string, reason?: string }} result
+ * @returns {void}
+ */
+function recordSupersedeOutcome(report, unit, result) {
+  if (result.outcome === 'closed') {
+    report.closed.push(unit.id);
+    return;
+  }
+  if (result.outcome === 'planned') {
+    report.planned.push({
+      ticket: unit.id,
+      storySlug: unit.createdStory.slug,
+    });
+    return;
+  }
+  if (result.outcome === 'skipped') {
+    report.skipped.push({ ticket: unit.id, reason: result.reason });
+    return;
+  }
+  report.failed.push({ ticket: unit.id, reason: result.reason });
+}
+
 /**
  * Surface the supersede outcome on the console so a partial failure is
  * visible without reading the JSON envelope.

package/.agents/scripts/lib/orchestration/plan-text-hygiene.js

@@ -18,7 +18,9 @@
  *
  *   - **dangling-citation** — a sentence referencing a document section
  *     (`§`, "design note", "review doc") with no repo-relative path and no
- *     `#<digits>` issue anchor in the same sentence.
+ *     `#<digits>` issue anchor in the same sentence. An anchor written
+ *     inside a code span counts — the conventional markdown form (Story
+ *     #4906).
  *   - **open-question** — interrogative-to-operator phrasing ("Flag if",
  *     "TBD", "confirm with the operator", a trailing `?`) in Goal/Spec
  *     prose outside code spans. Bodies record decisions; unresolved
@@ -73,28 +75,55 @@ const OPEN_QUESTION_MARKERS = [
  */
 
 /**
- * Strip fenced code blocks and inline code spans so code content (shell
- * snippets, grep patterns, JSON) never trips a prose heuristic.
+ * Private-use sentinel standing in for one extracted inline code span.
+ * It carries no citation marker, no anchor and no sentence boundary, so it
+ * is inert for every marker heuristic while recording where the span sat.
+ */
+const CODE_SLOT_PATTERN = /\uE000(\d+)\uE001/g;
+
+/**
+ * Replace fenced code blocks with a space and each inline code span with a
+ * positional slot, so code content (shell snippets, grep patterns, JSON)
+ * never trips a prose heuristic yet stays recoverable for the anchor check.
  *
  * @param {string} text
- * @returns {string}
+ * @returns {{ slotted: string, spans: string[] }}
  */
-function stripCodeSpans(text) {
-  return text.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`\n]*`/g, ' ');
+function slotCodeSpans(text) {
+  const spans = [];
+  const slotted = text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, (span) => {
+      spans.push(span.slice(1, -1));
+      return `\uE000${spans.length - 1}\uE001`;
+    });
+  return { slotted, spans };
 }
 
 /**
  * Split prose into sentence-ish units. Newlines are boundaries too, so a
- * bullet list yields one unit per bullet.
+ * bullet list yields one unit per bullet. Each unit carries two views of
+ * the same sentence: `prose`, with code content removed, which every
+ * marker heuristic reads; and `anchorText`, with inline code content
+ * restored, so a citation anchored inside a code span is still visible to
+ * the anchor check. Restoring only ever adds anchors — markers are matched
+ * against `prose` alone, exactly as before.
  *
  * @param {string} text
- * @returns {string[]}
+ * @returns {Array<{ prose: string, anchorText: string }>}
  */
 function splitSentences(text) {
-  return text
+  const { slotted, spans } = slotCodeSpans(text);
+  return slotted
     .split(/(?<=[.!?])\s+|\n+/)
-    .map((s) => s.trim())
-    .filter(Boolean);
+    .map((unit) => ({
+      prose: unit.replace(CODE_SLOT_PATTERN, ' ').trim(),
+      anchorText: unit.replace(
+        CODE_SLOT_PATTERN,
+        (_slot, index) => ` ${spans[Number(index)]} `,
+      ),
+    }))
+    .filter((unit) => unit.prose.length > 0);
 }
 
 /**
@@ -112,18 +141,21 @@ function excerpt(text) {
 
 /**
  * dangling-citation: a citation-marker sentence with no locating anchor.
+ * The marker is matched against the sentence's code-stripped prose; the
+ * anchor against its code-restored text, so a path or issue reference
+ * written in a code span — the conventional markdown form — counts.
  *
- * @param {string} prose - Code-stripped body prose.
+ * @param {string} prose - Raw body prose.
  * @param {string} slug
  * @returns {TextHygieneFinding[]}
  */
 function findDanglingCitations(prose, slug) {
   const findings = [];
-  for (const sentence of splitSentences(prose)) {
+  for (const { prose: sentence, anchorText } of splitSentences(prose)) {
     const cites = CITATION_MARKERS.some((m) => m.test(sentence));
     if (!cites) continue;
     const anchored =
-      ISSUE_ANCHOR.test(sentence) || REPO_PATH_ANCHOR.test(sentence);
+      ISSUE_ANCHOR.test(anchorText) || REPO_PATH_ANCHOR.test(anchorText);
     if (anchored) continue;
     findings.push({
       kind: 'dangling-citation',
@@ -142,13 +174,13 @@ function findDanglingCitations(prose, slug) {
  * open-question: operator-directed phrasing (or a trailing `?`) in prose a
  * non-interactive sub-agent executes.
  *
- * @param {string} prose - Code-stripped Goal/Spec prose.
+ * @param {string} prose - Raw Goal/Spec prose.
  * @param {string} slug
  * @returns {TextHygieneFinding[]}
  */
 function findOpenQuestions(prose, slug) {
   const findings = [];
-  for (const sentence of splitSentences(prose)) {
+  for (const { prose: sentence } of splitSentences(prose)) {
     const marked =
       OPEN_QUESTION_MARKERS.some((m) => m.test(sentence)) ||
       sentence.endsWith('?');
@@ -217,12 +249,11 @@ export function evaluateTextHygiene({ draftStories = null } = {}) {
     }
     const goal = typeof body.goal === 'string' ? body.goal : '';
     const spec = typeof body.spec === 'string' ? body.spec : '';
-    const bodyProse = stripCodeSpans(
-      typeof story.body === 'string' ? story.body : [goal, spec].join('\n'),
-    );
+    const bodyProse =
+      typeof story.body === 'string' ? story.body : [goal, spec].join('\n');
     findings.push(
       ...findDanglingCitations(bodyProse, slug),
-      ...findOpenQuestions(stripCodeSpans([goal, spec].join('\n')), slug),
+      ...findOpenQuestions([goal, spec].join('\n'), slug),
       ...findSlicingMass(body, slug),
     );
   }

package/.agents/scripts/lib/orchestration/planning/authoring-context.js

@@ -7,7 +7,6 @@
  * the provider call needed to load the Epic.
  */
 
-import * as os from 'node:os';
 import path from 'node:path';
 import {
   resolveFeatureRoots,
@@ -15,39 +14,15 @@ import {
 } from '../../bdd-runner-detect.js';
 import { scanBddScenarios } from '../../bdd-scenario-scanner.js';
 import { getPaths, PROJECT_ROOT } from '../../config-resolver.js';
-import { scanMemoryFreshness } from '../../feedback-loop/memory-freshness.js';
 import { fetchPriorFeedback } from '../../feedback-loop/prior-feedback-fetcher.js';
 import { Logger } from '../../Logger.js';
 import { hasTicketSection } from '../../ticket-body-sections.js';
+import {
+  concurrentMap,
+  FANOUT_CONCURRENCY,
+} from '../../util/concurrent-map.js';
 import { ensureDocsDigest } from '../docs-digest.js';
-
-/**
- * Resolve the per-project memory directory used by the memory-freshness
- * pre-flight (Story #2557 / Epic #2547).
- *
- * Resolution order:
- *   1. `MANDREL_MEMORY_DIR` environment variable (test seam and operator
- *      override).
- *   2. `~/.claude/projects/<repo>/memory/` — the standard Claude Code
- *      memory substrate path, scoped by the configured GitHub repo so each
- *      consumer project gets its own memory pool.
- *   3. `null` when neither is resolvable. The scanner tolerates a missing
- *      `memoryDir` and surfaces a single `errors[]` entry.
- *
- * @param {{ github?: { owner?: string, repo?: string }|null }} opts
- * @returns {string|null}
- */
-function resolveMemoryDir({ github } = {}) {
-  if (
-    typeof process.env.MANDREL_MEMORY_DIR === 'string' &&
-    process.env.MANDREL_MEMORY_DIR.length > 0
-  ) {
-    return process.env.MANDREL_MEMORY_DIR;
-  }
-  const repo = github?.repo;
-  if (typeof repo !== 'string' || repo.length === 0) return null;
-  return path.join(os.homedir(), '.claude', 'projects', repo, 'memory');
-}
+import { buildMemoryPoolAdvisory } from './memory-pool-advisory.js';
 
 /**
  * Build the digest-first `docsContext` envelope field (Story #4433 — hard
@@ -95,6 +70,24 @@ async function buildPlanningDocsContext({ seedIssueId, settings, cwd }) {
   return { mode: 'digest', digestPath: relPath };
 }
 
+/**
+ * Story #2637 — index existing BDD scenarios so the Acceptance Engineer step
+ * can annotate planned ACs with matches from the project's `.feature` files.
+ * Empty array when the project has not adopted BDD; the scanner is
+ * best-effort and never throws on filesystem errors.
+ *
+ * @returns {Array<object>}
+ */
+function scanBddScenariosBestEffort() {
+  try {
+    const featureRoots = resolveFeatureRoots({ cwd: PROJECT_ROOT });
+    return scanBddScenarios({ featureRoots });
+  } catch (err) {
+    Logger.warn(`[plan-context] BDD scenario scan skipped: ${err.message}`);
+    return [];
+  }
+}
+
 /**
  * Build the authoring context the host LLM (or the
  * `/plan` author step) needs to write the Tech Spec.
@@ -130,51 +123,54 @@ export async function buildAuthoringContext(
 
   const { cwd = PROJECT_ROOT } = opts;
 
-  const docsContext = await buildPlanningDocsContext({
-    seedIssueId: epic.id,
-    settings,
-    cwd,
-  });
-
-  // Story #2094 Task #2103 — verify the project's BDD runner pending-tag
-  // support so the acceptance-spec body can record either the verified tag
-  // (features-first ordering) or "fallback: dependencies-first ordering"
-  // when no supported runner is present.
-  const bddRunner = await verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT });
-
-  // Story #2637 — index existing BDD scenarios so the Acceptance Engineer
-  // step can annotate planned ACs with matches from the project's
-  // `.feature` files. Empty array when the project has not adopted BDD;
-  // the scanner is best-effort and never throws on filesystem errors.
-  let bddScenarios = [];
-  try {
-    const featureRoots = resolveFeatureRoots({ cwd: PROJECT_ROOT });
-    bddScenarios = scanBddScenarios({ featureRoots });
-  } catch (err) {
-    Logger.warn(`[plan-context] BDD scenario scan skipped: ${err.message}`);
-  }
-
-  // Story #2557 — memory-freshness pre-flight runs BEFORE the prior-feedback
-  // fetch so the planner sees a deduplicated, currently-actionable memory
-  // store. The scanner is best-effort: missing memory dir or gh-CLI failures
-  // land in `memoryFreshness.errors[]` and never throw.
   const githubCfg = opts.github ?? null;
-  const memoryDir = resolveMemoryDir({ github: githubCfg });
-  const memoryFreshness = await scanMemoryFreshness({
-    memoryDir,
-    owner: githubCfg?.owner,
-    repo: githubCfg?.repo,
-    projectRoot: PROJECT_ROOT,
-  });
 
-  // Story #2554 — surface open meta feedback issues to the planner so retro
-  // signals are routed into durable substrates rather than lost in chat.
-  // The fetcher is best-effort: missing owner/repo or gh-CLI failures land
-  // in `errors[]` and never throw.
-  const priorFeedback = await fetchPriorFeedback({
-    owner: githubCfg?.owner,
-    repo: githubCfg?.repo,
-  });
+  // Story #4952 — these five gathers share no data, so they run under bounded
+  // concurrency instead of five sequential awaits on the interactive `/plan`
+  // path. `concurrentMap` preserves input order, so the destructuring is
+  // positional and the produced context is identical to the serial build:
+  //
+  //   1. the digest-first `docsContext` pointer (Story #4433);
+  //   2. Story #2094 Task #2103 — the project's BDD runner pending-tag
+  //      support, so the acceptance-spec body records either the verified tag
+  //      (features-first ordering) or "fallback: dependencies-first ordering"
+  //      when no supported runner is present;
+  //   3. the best-effort `.feature` scenario index;
+  //   4. Story #4919 — the memory-pool advisory that replaced the retired
+  //      memory-freshness pre-flight (#2557 / #4414) in the same slot. The
+  //      scanner marked an entry stale when a cited issue was closed, but the
+  //      memory corpus is delivery retrospectives whose subject IS a delivered
+  //      Story — and its directory (`~/.claude/projects/<repo>/memory/`) never
+  //      resolved, because harness project dirs are cwd-slugs. This renders no
+  //      per-entry verdict at all: it stats and counts, and the `/plan` spine
+  //      surfaces `recommend` at Gate #1. Filesystem-only and total;
+  //   5. Story #2554 — open meta feedback issues, so retro signals are routed
+  //      into durable substrates rather than lost in chat. Best-effort:
+  //      missing owner/repo or gh-CLI failures land in `errors[]`, never throw.
+  const [
+    docsContext,
+    bddRunner,
+    bddScenarios,
+    memoryPoolAdvisory,
+    priorFeedback,
+  ] = await concurrentMap(
+    [
+      () => buildPlanningDocsContext({ seedIssueId: epic.id, settings, cwd }),
+      () => verifyBddRunnerPendingTag({ cwd: PROJECT_ROOT }),
+      () => scanBddScenariosBestEffort(),
+      () => buildMemoryPoolAdvisory({ cwd: PROJECT_ROOT }),
+      () =>
+        fetchPriorFeedback({
+          owner: githubCfg?.owner,
+          repo: githubCfg?.repo,
+        }),
+    ],
+    (gather) => gather(),
+    // The independent context gathers (Story #4952): a handful of local
+    // probes plus one `gh` read, so this rides the shared fan-out bound
+    // rather than declaring its own.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
 
   // Story #4811 — the codebase snapshot (#2634), its authoring grounding
   // (#4139 F10) and the spec-freshness helpers behind it are retired. The
@@ -211,7 +207,7 @@ export async function buildAuthoringContext(
     docsContext,
     bddRunner,
     bddScenarios,
-    memoryFreshness,
+    memoryPoolAdvisory,
     priorFeedback,
   };
 }