mandrel 2.24.0 → 2.26.0

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,
   };
 }

package/.agents/scripts/lib/orchestration/planning/memory-pool-advisory.js

@@ -0,0 +1,231 @@
+/**
+ * memory-pool-advisory.js — the `/plan` Phase 0 memory-hygiene advisory.
+ *
+ * Replaces the retired memory-freshness pre-flight (Story #2557 / #4414) in
+ * the same slot, fixing both of that design's defects:
+ *
+ *   1. **Correct pool resolution.** The retired `resolveMemoryDir` built
+ *      `~/.claude/projects/<github.repo>/memory/`, but harness project
+ *      directories are **cwd-slugs** — the absolute cwd with every `/` and `.`
+ *      replaced by `-` — so the old path never resolved in any consumer and
+ *      the scan was a silent no-op everywhere.
+ *   2. **A named consumer.** The retired scanner emitted a per-entry staleness
+ *      verdict nothing read. This emits one advisory the `/plan` spine
+ *      surfaces at Gate #1, recommending `/memory-consolidate`.
+ *
+ * It also drops the semantic that made the old scanner unfixable: it renders
+ * **no per-entry verdict at all**. A memory citing a closed issue is a
+ * delivery retrospective whose subject is that issue — not a stale entry — and
+ * only the attended `/memory-consolidate` pass, reading content, can tell the
+ * difference. This module counts and stats; it never judges an entry.
+ *
+ * Detection is filesystem-only — no child processes, no `gh` probes, no
+ * network. Every failure path fails soft to "no pool, no recommendation": the
+ * advisory can degrade the nudge, never a plan.
+ *
+ * Test seams: `cwd`, `env`, `fsImpl` (node:fs-compatible `statSync` /
+ * `readdirSync` / `readFileSync`), `now`, and the two thresholds.
+ *
+ * `buildMemoryPoolAdvisory` is the **only** export: the helpers below have no
+ * caller outside this module, and exporting one solely for a test would add a
+ * row to the `dead-exports-production` ratchet (the `buildUiSurfaceSignal`
+ * precedent). Tests reach every branch through the seams above — do not
+ * "fix" the missing exports.
+ */
+
+import * as defaultFs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/** Recommend a consolidation pass once the stamp is this old. */
+const STALE_AFTER_DAYS = 30;
+
+/** Recommend a consolidation pass once the pool holds more entries than this. */
+const ENTRY_COUNT_CEILING = 100;
+
+/** Stamp file written by `/memory-consolidate` after its operator gate. */
+const STAMP_FILENAME = '.consolidation-stamp.json';
+
+/** The index file is not itself a memory entry. */
+const INDEX_FILENAME = 'MEMORY.md';
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Slugify an absolute path the way the harness names its per-project
+ * directories: every `/` and `.` becomes `-`. Verified against real
+ * directories in `~/.claude/projects/` — a plain checkout and a worktree both
+ * round-trip exactly.
+ *
+ * @param {string} absPath
+ * @returns {string}
+ */
+function slugifyProjectPath(absPath) {
+  return String(absPath ?? '').replace(/[/.]/g, '-');
+}
+
+/**
+ * Resolve the memory pool directory for a working directory.
+ *
+ * `MANDREL_MEMORY_DIR` wins outright (operator override and test seam);
+ * otherwise `~/.claude/projects/<cwd-slug>/memory/`.
+ *
+ * @param {{ cwd?: string, env?: Record<string,string|undefined>, homedir?: string }} [opts]
+ * @returns {string|null} absolute pool path, or `null` when unresolvable
+ */
+function resolveMemoryPoolDir({ cwd, env = process.env, homedir } = {}) {
+  const override = env?.MANDREL_MEMORY_DIR;
+  if (typeof override === 'string' && override.length > 0) return override;
+
+  const base = typeof cwd === 'string' && cwd.length > 0 ? cwd : null;
+  if (!base) return null;
+
+  const home =
+    typeof homedir === 'string' && homedir.length > 0 ? homedir : os.homedir();
+  if (!home) return null;
+
+  return path.join(
+    home,
+    '.claude',
+    'projects',
+    slugifyProjectPath(base),
+    'memory',
+  );
+}
+
+/**
+ * Read the consolidation stamp, returning its ISO timestamp or `null`.
+ * A missing, unreadable, unparseable, or malformed stamp is indistinguishable
+ * from "never consolidated" — all four mean the same thing to the advisory.
+ *
+ * @returns {string|null}
+ */
+function readStamp({ poolDir, fsImpl }) {
+  try {
+    const raw = fsImpl.readFileSync(path.join(poolDir, STAMP_FILENAME), 'utf8');
+    const parsed = JSON.parse(raw);
+    const value = parsed?.lastConsolidatedAt;
+    if (typeof value !== 'string' || value.length === 0) return null;
+    return Number.isNaN(Date.parse(value)) ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count memory entries — `.md` files other than the index.
+ *
+ * @returns {number|null} `null` when the directory cannot be listed
+ */
+function countEntries({ poolDir, fsImpl }) {
+  try {
+    return fsImpl
+      .readdirSync(poolDir)
+      .filter((name) => name.endsWith('.md') && name !== INDEX_FILENAME).length;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the `memoryPoolAdvisory` envelope field.
+ *
+ * Advisory only — it carries **no routing authority**, mirroring
+ * `deliverLightSuggestion`. The `/plan` spine surfaces `recommend` at Gate #1;
+ * nothing auto-runs, and nothing here mutates the operator's memory store.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] — defaults to `process.cwd()`
+ * @param {Record<string,string|undefined>} [opts.env]
+ * @param {object} [opts.fsImpl] — node:fs-compatible seam
+ * @param {string} [opts.homedir]
+ * @param {Date|string|number} [opts.now]
+ * @param {number} [opts.staleAfterDays]
+ * @param {number} [opts.entryCountCeiling]
+ * @returns {{ present: boolean, entryCount: number, lastConsolidatedAt: string|null,
+ *            recommend: boolean, reasons: string[] }}
+ */
+export function buildMemoryPoolAdvisory({
+  cwd = process.cwd(),
+  env = process.env,
+  fsImpl = defaultFs,
+  homedir,
+  now = new Date(),
+  staleAfterDays = STALE_AFTER_DAYS,
+  entryCountCeiling = ENTRY_COUNT_CEILING,
+} = {}) {
+  const absent = (reason) => ({
+    present: false,
+    entryCount: 0,
+    lastConsolidatedAt: null,
+    recommend: false,
+    reasons: [reason],
+  });
+
+  const poolDir = resolveMemoryPoolDir({ cwd, env, homedir });
+  if (!poolDir) {
+    return absent(
+      'no memory pool could be resolved for this working directory',
+    );
+  }
+
+  let isDir = false;
+  try {
+    isDir = fsImpl.statSync(poolDir).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) {
+    return absent(`no memory pool at ${poolDir} — nothing to consolidate`);
+  }
+
+  const entryCount = countEntries({ poolDir, fsImpl });
+  if (entryCount === null) {
+    return absent(`memory pool at ${poolDir} could not be listed`);
+  }
+
+  const lastConsolidatedAt = readStamp({ poolDir, fsImpl });
+  const reasons = [];
+
+  // An empty pool has nothing to consolidate, whatever the stamp says.
+  if (entryCount === 0) {
+    return {
+      present: true,
+      entryCount: 0,
+      lastConsolidatedAt,
+      recommend: false,
+      reasons: ['memory pool is empty — nothing to consolidate'],
+    };
+  }
+
+  if (lastConsolidatedAt === null) {
+    reasons.push(
+      'no consolidation stamp — this pool has never been consolidated',
+    );
+  } else {
+    const ageDays =
+      (new Date(now).getTime() - Date.parse(lastConsolidatedAt)) / MS_PER_DAY;
+    if (ageDays > staleAfterDays) {
+      reasons.push(
+        `last consolidated ${Math.floor(ageDays)} days ago (over the ${staleAfterDays}-day threshold)`,
+      );
+    }
+  }
+
+  if (entryCount > entryCountCeiling) {
+    reasons.push(
+      `${entryCount} entries (over the ${entryCountCeiling}-entry threshold)`,
+    );
+  }
+
+  return {
+    present: true,
+    entryCount,
+    lastConsolidatedAt,
+    recommend: reasons.length > 0,
+    reasons:
+      reasons.length > 0
+        ? reasons
+        : ['memory pool is within both freshness thresholds'],
+  };
+}

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

@@ -34,6 +34,7 @@ import {
   extractChangePaths,
   parse as parseStoryBody,
 } from '../story-body/story-body.js';
+import { expandIdList } from '../util/parse-id-list.js';
 import { resolveStoryDispatchMode } from './complexity-gate.js';
 
 /** Labels/state that mean a blocker no longer gates its dependents. */
@@ -355,29 +356,29 @@ export function buildStoriesEnvelope({
 }
 
 /**
- * Parse and validate the `--ids` list.
+ * Parse and validate the `--ids` list, expanding any `A-B` dash range.
+ *
+ * A contiguous span is how an operator names a plan run — `/deliver 4922 -
+ * 4926` — so the range is expanded here rather than transcribed by the host.
+ * `stories-wave-tick.js --stories` reads through this same function, which is
+ * what keeps the sequencing set identical to the resolved one.
  *
  * @param {string|undefined} raw
+ * @param {string} [flag] Flag name, for the error message.
  * @returns {number[]}
  */
-export function parseIds(raw) {
-  const ids = String(raw ?? '')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean)
-    .map((s) => {
-      const n = Number.parseInt(s, 10);
-      if (!Number.isInteger(n) || n <= 0 || String(n) !== s) {
-        throw new Error(
-          `[resolve-stories] --ids must be a comma-separated list of positive issue numbers (got "${s}").`,
-        );
-      }
-      return n;
-    });
+export function parseIds(raw, flag = '--ids') {
+  const { ids, error } = expandIdList(raw, {
+    flag,
+    prefix: '[resolve-stories] ',
+  });
+  if (error) {
+    throw new Error(error);
+  }
   if (ids.length === 0) {
     throw new Error(
-      '[resolve-stories] --ids is required: node resolve-stories.js --ids 101,102',
+      `[resolve-stories] ${flag} is required: node resolve-stories.js --ids 101,102 (or a range: --ids 101-104)`,
     );
   }
-  return [...new Set(ids)];
+  return ids;
 }

package/.agents/scripts/lib/orchestration/run-epilogue.js

@@ -494,6 +494,18 @@ async function executeAuditRoster({
       ? selectedAudits.map((lens) => `- \`${lens}\``)
       : ['- _(none — docs-only or no matching change-set lenses)_']),
     '',
+    // Story #4949 — the roster used to name the lenses and say nothing about
+    // how to dispatch them, which made a serial walk (and a nested
+    // coordinator) fully compliant with it. The lenses are read-only and share
+    // no write paths, so they are the textbook independent fan-out; naming the
+    // shape here is what turns that from an option into the instruction.
+    '**Dispatch shape (MUST): flat, parallel, one turn.** Spawn one ' +
+      '`auditor` sub-agent per lens listed above and issue every one of those ' +
+      'spawns in a SINGLE turn — no nested fan-out, no serial walk. A ' +
+      'coordinator sub-agent that re-dispatches the lenses is the failure ' +
+      'this line exists to prevent: a grandchild routes its findings to the ' +
+      'wrong parent or loses them outright.',
+    '',
     '```json',
     JSON.stringify(
       {