mandrel 2.24.0 → 2.26.0

package/.agents/scripts/lib/orchestration/plan-context.js

@@ -31,15 +31,13 @@ import {
   renderAcceptanceSpecSystemPrompt,
   renderTechSpecSystemPrompt,
 } from '../templates/spec-author-prompts.js';
-import { concurrentMap } from '../util/concurrent-map.js';
+import { concurrentMap, FANOUT_CONCURRENCY } from '../util/concurrent-map.js';
 import { buildComplexitySignals } from './complexity-gate.js';
 import { parseDeliverySlicingTable } from './consolidation-precondition.js';
 import { buildDocsDigest } from './docs-digest.js';
 import { buildAuthoringContext } from './planning/authoring-context.js';
 import { buildDecomposerSystemPrompt } from './planning/decomposer-context.js';
 
-/** Bounded concurrency for `--tickets` source-ticket hydration. */
-const SOURCE_TICKET_FETCH_CONCURRENCY = 4;
 /**
  * Envelope byte ceiling (regression guard for the design's named PR2 risk:
  * two envelopes → one bigger one). This is the **only** live bound on
@@ -229,7 +227,8 @@ export function renderStoriesTemplate({ complexitySignals = null } = {}) {
           'codes, security invariants, and load-bearing constraints with ' +
           'their why. Implementation choices belong to the deliverer unless ' +
           'load-bearing. No per-file behavior paragraphs, no current-state ' +
-          'narration. Keep it under ~250 words (soft advisory budget). ' +
+          'narration. Aim for ~250 words; an advisory warning fires past 350, ' +
+          'and it never fails the persist. ' +
           'Delete this field when acceptance[] carries the whole contract.',
         changes: buildTemplateChanges(complexitySignals),
         non_goals: [],
@@ -813,6 +812,84 @@ async function searchStoryDuplicates({
   }
 }
 
+/**
+ * Gather the three independent envelope inputs — the open-Story duplicate
+ * search, the folded authoring context, and the inline docs digest — under
+ * bounded concurrency (Story #4952).
+ *
+ * None of the three reads a value the others produce, so the result is a pure
+ * function of `seed` and the injected config: the assembled envelope is
+ * **byte-identical** to the serial build for the same inputs, whichever order
+ * the three happen to settle in. `concurrentMap` preserves input order, so the
+ * destructuring below is positional and stable.
+ *
+ * `docsContextFiles` is emptied for the `buildAuthoringContext` call: the
+ * per-plan digest-file path needs a plan id that does not exist yet — the
+ * inline digest gathered alongside it replaces that pointer.
+ *
+ * @param {{
+ *   seed: string,
+ *   epicTitle: string,
+ *   excludeIds?: Iterable<number|string>,
+ *   provider: object,
+ *   config: object,
+ *   settings: object,
+ *   cwd?: string,
+ * }} args
+ * @returns {Promise<{
+ *   duplicates: Array<object>,
+ *   authoring: object,
+ *   docsContext: { mode: 'digest-inline', digest: string }|null,
+ * }>}
+ */
+async function gatherEnvelopeInputs({
+  seed,
+  epicTitle,
+  excludeIds = [],
+  provider,
+  config,
+  settings,
+  cwd,
+}) {
+  const paths = settings?.paths ?? {};
+  const [duplicates, authoring, inlineDigest] = await concurrentMap(
+    [
+      () => searchStoryDuplicates({ seed, provider, config, excludeIds }),
+      () =>
+        buildAuthoringContext(
+          0,
+          /* provider (unused behind the prefetch seam) */ {},
+          { ...settings, docsContextFiles: [] },
+          {
+            epic: { id: 0, title: epicTitle, body: seed },
+            github: config.github ?? null,
+            cwd,
+          },
+        ),
+      () =>
+        buildDocsDigest({
+          docsContextFiles: settings?.docsContextFiles,
+          docsRoot: paths.docsRoot,
+        }),
+    ],
+    (gather) => gather(),
+    // The per-mode envelope gathers (Story #4952): the duplicate search, the
+    // authoring-context fold and the docs digest have no data dependency on
+    // one another, so their serialization was incidental and `/plan` paid it
+    // with the operator waiting at Gate #1.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+
+  return {
+    duplicates,
+    authoring,
+    docsContext:
+      inlineDigest == null
+        ? null
+        : { mode: 'digest-inline', digest: inlineDigest },
+  };
+}
+
 /**
  * Build the seed-file (ideation) envelope. No parent ticket
  * exists yet — creation moves to the persist half — so the open-Story
@@ -836,37 +913,17 @@ async function buildSeedFileModeEnvelope({
     );
   }
 
-  const duplicates = await searchStoryDuplicates({
+  // Dup search, the authoring-context fold grounded in the seed prose, and the
+  // inline docs digest are independent — gathered concurrently (Story #4952).
+  const { duplicates, authoring, docsContext } = await gatherEnvelopeInputs({
     seed: content,
+    epicTitle: seedFilePath ?? 'seed',
     provider,
     config,
+    settings,
+    cwd,
   });
 
-  // Fold the authoring-context builders grounded in the seed prose.
-  // `docsContextFiles` is emptied for this call: the per-plan digest-file
-  // path needs a plan id that does not exist yet — the inline digest
-  // below replaces it.
-  const authoring = await buildAuthoringContext(
-    0,
-    /* provider (unused behind the prefetch seam) */ {},
-    { ...settings, docsContextFiles: [] },
-    {
-      epic: { id: 0, title: seedFilePath ?? 'seed', body: content },
-      github: config.github ?? null,
-      cwd,
-    },
-  );
-
-  const paths = settings?.paths ?? {};
-  const inlineDigest = await buildDocsDigest({
-    docsContextFiles: settings?.docsContextFiles,
-    docsRoot: paths.docsRoot,
-  });
-  const docsContext =
-    inlineDigest == null
-      ? null
-      : { mode: 'digest-inline', digest: inlineDigest };
-
   const limits = getLimits(config);
   const heuristics = resolveRiskHeuristics(config);
 
@@ -892,7 +949,7 @@ async function buildSeedFileModeEnvelope({
     docsContext,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,
-    memoryFreshness: authoring.memoryFreshness,
+    memoryPoolAdvisory: authoring.memoryPoolAdvisory,
     priorFeedback: authoring.priorFeedback,
     ticketSchema: TICKET_SCHEMA_DESCRIPTOR,
     maxTickets: limits.maxTickets,
@@ -975,7 +1032,8 @@ async function fetchSourceTickets(ticketIds, provider) {
         state: ticket.state ?? undefined,
       };
     },
-    { concurrency: SOURCE_TICKET_FETCH_CONCURRENCY },
+    // `--tickets` source-ticket hydration: one independent read per id.
+    { concurrency: FANOUT_CONCURRENCY },
   );
 }
 
@@ -1001,37 +1059,18 @@ async function buildTicketsModeEnvelope({
     .map((t) => `# ${t.title}\n\n${t.body}`)
     .join('\n\n---\n\n');
 
-  const duplicates = await searchStoryDuplicates({
+  // Same three independent gathers as seed-file mode, concurrent under the
+  // same bound (Story #4952); only the source-ticket hydration above is a
+  // genuine data dependency, because `seed` is derived from it.
+  const { duplicates, authoring, docsContext } = await gatherEnvelopeInputs({
     seed,
+    epicTitle: sourceTickets[0]?.title ?? 'tickets',
+    excludeIds: ticketIds,
     provider,
     config,
-    excludeIds: ticketIds,
-  });
-
-  const authoring = await buildAuthoringContext(
-    0,
-    {},
-    { ...settings, docsContextFiles: [] },
-    {
-      epic: {
-        id: 0,
-        title: sourceTickets[0]?.title ?? 'tickets',
-        body: seed,
-      },
-      github: config.github ?? null,
-      cwd,
-    },
-  );
-
-  const paths = settings?.paths ?? {};
-  const inlineDigest = await buildDocsDigest({
-    docsContextFiles: settings?.docsContextFiles,
-    docsRoot: paths.docsRoot,
+    settings,
+    cwd,
   });
-  const docsContext =
-    inlineDigest == null
-      ? null
-      : { mode: 'digest-inline', digest: inlineDigest };
 
   const limits = getLimits(config);
   const heuristics = resolveRiskHeuristics(config);
@@ -1053,7 +1092,7 @@ async function buildTicketsModeEnvelope({
     docsContext,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,
-    memoryFreshness: authoring.memoryFreshness,
+    memoryPoolAdvisory: authoring.memoryPoolAdvisory,
     priorFeedback: authoring.priorFeedback,
     ticketSchema: TICKET_SCHEMA_DESCRIPTOR,
     maxTickets: limits.maxTickets,
@@ -1147,12 +1186,26 @@ async function buildAmendmentModeEnvelope({
 
   const heuristics = resolveRiskHeuristics(config);
   const limits = getLimits(config);
-  const duplicates = await searchStoryDuplicates({
-    seed: priorBody,
-    provider,
-    config,
-    excludeIds: [amendsId],
-  });
+  // Story #4952 — this builder's independent-gather set has exactly one
+  // member. `provider.getTicket` above is a hard data dependency (the prior
+  // body IS the seed), and the mode deliberately carries no authoring-context
+  // fold and no docs digest — the prior artifacts are the grounding. It still
+  // goes through the same bounded gather as the other two builders so one file
+  // does not carry two ways of gathering independent envelope inputs.
+  const [duplicates] = await concurrentMap(
+    [
+      () =>
+        searchStoryDuplicates({
+          seed: priorBody,
+          provider,
+          config,
+          excludeIds: [amendsId],
+        }),
+    ],
+    (gather) => gather(),
+    // Same independent-gather fan-out as the seed-mode envelope above.
+    { concurrency: FANOUT_CONCURRENCY },
+  );
 
   return {
     mode: 'amends',

package/.agents/scripts/lib/orchestration/plan-persist/fan-out-gate.js

@@ -7,6 +7,7 @@
 
 import { Logger } from '../../Logger.js';
 import {
+  CONFLICT_KINDS,
   renderFanOutEvidence,
   renderFanOutRemedy,
   renderHardConflictError,
@@ -54,6 +55,15 @@ export function enforceFanOutGate(
 }
 
 /**
+ * Report every soft finding the validator produced, each under its own kind.
+ *
+ * Only the {@link CONFLICT_KINDS} are cross-Story conflicts. The advisory
+ * kinds — `spec-word-budget` and the sizing findings — are single-Story
+ * nudges, and announcing them as conflicts overstated them and taught readers
+ * to discount the whole channel (Story #4907). `fan-out-warning` is excluded
+ * throughout: {@link enforceFanOutGate} owns it and has already either thrown
+ * or logged the override.
+ *
  * @param {object[]} findings
  * @param {string} [tag]
  */
@@ -62,10 +72,26 @@ export function surfaceSoftConflictFindings(findings, tag = 'plan-persist') {
     (f) => f?.severity === 'soft' && f?.kind !== 'fan-out-warning',
   );
   if (soft.length === 0) return;
-  Logger.warn(
-    `[${tag}] ${soft.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
-  );
-  for (const finding of soft) {
-    Logger.warn(`[${tag}] soft conflict: ${renderHardConflictError(finding)}`);
+  const conflicts = soft.filter((f) => CONFLICT_KINDS.has(f?.kind));
+  const advisories = soft.filter((f) => !CONFLICT_KINDS.has(f?.kind));
+  if (conflicts.length > 0) {
+    Logger.warn(
+      `[${tag}] ${conflicts.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
+    );
+    for (const finding of conflicts) {
+      Logger.warn(
+        `[${tag}] soft conflict: ${renderHardConflictError(finding)}`,
+      );
+    }
+  }
+  if (advisories.length > 0) {
+    Logger.warn(
+      `[${tag}] ${advisories.length} advisory finding(s) — the persist proceeds:`,
+    );
+    for (const finding of advisories) {
+      Logger.warn(
+        `[${tag}] advisory (${finding.kind}): ${renderHardConflictError(finding)}`,
+      );
+    }
   }
 }