mandrel 2.40.0 → 2.42.0

package/.agents/scripts/lib/orchestration/epic-candidates.js

@@ -0,0 +1,159 @@
+/**
+ * epic-candidates.js — rank the open container Epics a new plan could join.
+ *
+ * Story #5155. `plan-persist` has always been able to *create* a container
+ * Epic, and to re-adopt one whose fingerprint matches the exact cohort it is
+ * re-persisting. Neither helps the case this module exists for: a second plan,
+ * days later, adding work that belongs under the Epic a first plan opened. The
+ * fingerprint is keyed on the child set, so a different cohort never matches
+ * it — by design, since adopting the wrong container silently mis-files a run.
+ *
+ * So the join has to be a **decision**, not a hash collision: this module
+ * surfaces every open Epic with an overlap score, and the operator picks at
+ * Gate #3. The list is deliberately **complete rather than thresholded** — a
+ * low score is evidence for the operator to weigh, and hiding a candidate is
+ * how a plan silently opens its second container for one body of work.
+ *
+ * Scoring reuses `duplicate-search.js`'s tokenizer and Jaccard overlap rather
+ * than growing a second similarity notion in the codebase; like that module's,
+ * it is a triage signal and not a semantic search.
+ *
+ * @module lib/orchestration/epic-candidates
+ * @see Story #5155
+ */
+
+import { overlapScore, tokenize } from '../duplicate-search.js';
+import { Logger } from '../Logger.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { concurrentMap, FANOUT_CONCURRENCY } from '../util/concurrent-map.js';
+import { isEpicTicket, readEpicChildIds } from './epic-container.js';
+
+/**
+ * Build an issue URL for an Epic the provider returned without one.
+ *
+ * @param {number} id
+ * @param {{ owner?: string, repo?: string }} [opts]
+ * @returns {string}
+ */
+function buildEpicUrl(id, { owner, repo } = {}) {
+  if (owner && repo) return `https://github.com/${owner}/${repo}/issues/${id}`;
+  return `#${id}`;
+}
+
+/**
+ * Fetch the titles of an Epic's children, for scoring only.
+ *
+ * Child titles matter because a container's own title and goal are short and
+ * abstract ("Auth hardening", one paragraph), while the seed that should match
+ * it is concrete. The children are where the shared vocabulary actually lives.
+ *
+ * Entirely best-effort: no `getTicket`, an unreadable child, or a throw all
+ * degrade to fewer title tokens, never to a failed envelope. A candidate that
+ * scores low because its children could not be read is still *listed* — the
+ * operator sees every open Epic regardless.
+ *
+ * @param {{ childIds: number[], provider: object }} opts
+ * @returns {Promise<string>} Space-joined child titles ('' when none resolved).
+ */
+async function readChildTitles({ childIds, provider }) {
+  if (childIds.length === 0 || typeof provider?.getTicket !== 'function') {
+    return '';
+  }
+  const titles = await concurrentMap(
+    childIds,
+    async (id) => {
+      try {
+        const child = await provider.getTicket(id);
+        return typeof child?.title === 'string' ? child.title : '';
+      } catch {
+        return '';
+      }
+    },
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+  return titles.filter((t) => t !== '').join(' ');
+}
+
+/**
+ * Score one open Epic against the seed.
+ *
+ * @param {{ epic: object, seedTokens: Set<string>, provider: object, owner?: string, repo?: string }} opts
+ * @returns {Promise<{ id: number, title: string, url: string, score: number, childIds: number[] }|null>}
+ */
+async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
+  const id = Number(epic?.number ?? epic?.id);
+  if (!Number.isInteger(id) || id <= 0) return null;
+
+  const title = typeof epic?.title === 'string' ? epic.title : '';
+  const body = typeof epic?.body === 'string' ? epic.body : '';
+  const childIds = readEpicChildIds(body);
+  const childTitles = await readChildTitles({ childIds, provider });
+
+  // The fingerprint marker and checklist ids are machine noise; the tokenizer
+  // drops short and non-alphabetic tokens, so the corpus is effectively the
+  // title, the `## Goal` prose and the child titles.
+  const corpus = `${title}\n${body}\n${childTitles}`;
+  const score = overlapScore(seedTokens, tokenize(corpus));
+
+  return {
+    id,
+    title,
+    url: epic?.html_url ?? epic?.url ?? buildEpicUrl(id, { owner, repo }),
+    score: Number(score.toFixed(4)),
+    childIds,
+  };
+}
+
+/**
+ * Find every open container Epic, ranked by overlap with the seed.
+ *
+ * **Only open Epics are candidates.** A closed Epic is a completed body of
+ * work; joining one would reopen a container the epilogue deliberately closed,
+ * and silently re-scope a finished plan. The operator files a new Epic or
+ * reopens the old one by hand.
+ *
+ * Failures degrade to `[]` — like the duplicate search, this is a triage
+ * signal offered at a gate, and no plan should fail to be authored because
+ * the Epic listing was unavailable.
+ *
+ * @param {{
+ *   seed: string,
+ *   provider: object,
+ *   owner?: string,
+ *   repo?: string,
+ * }} args
+ * @returns {Promise<Array<{ id: number, title: string, url: string, score: number, childIds: number[] }>>}
+ */
+export async function findOpenEpicCandidates({ seed, provider, owner, repo }) {
+  if (typeof seed !== 'string' || seed.trim() === '') return [];
+  if (typeof provider?.listIssuesByLabel !== 'function') return [];
+
+  const seedTokens = tokenize(seed);
+  if (seedTokens.size === 0) return [];
+
+  let issues;
+  try {
+    issues = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[epic-candidates] open-Epic listing degraded to no candidates: ${err?.message ?? err}`,
+    );
+    return [];
+  }
+
+  const epics = (Array.isArray(issues) ? issues : []).filter(isEpicTicket);
+  const scored = await concurrentMap(
+    epics,
+    (epic) => scoreEpic({ epic, seedTokens, provider, owner, repo }),
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+
+  // Descending score, then ascending id: a stable order for two Epics that
+  // tie, so the same backlog always renders the same list.
+  return scored
+    .filter((c) => c !== null)
+    .sort((a, b) => b.score - a.score || a.id - b.id);
+}

package/.agents/scripts/lib/orchestration/epic-checklist.js

@@ -0,0 +1,103 @@
+/**
+ * epic-checklist.js — edit a live Epic body's child checklist in place.
+ *
+ * Story #5155. `epic-container.js` describes the *shape* of a container and
+ * renders one from scratch; this module is the other operation adoption needs
+ * — amending a body that already exists, written by someone else, possibly
+ * hand-edited since.
+ *
+ * The two are deliberately separate. Composing may assume everything about the
+ * text because it produced all of it; amending may assume almost nothing and
+ * must treat every line it did not come to change as untouchable: the `## Goal`
+ * prose, the fingerprint marker, the item order, and above all the **checked
+ * state** of existing rows. An operator who ticked `- [x] #41` is recording
+ * that the Story landed, and a re-render would silently discard it.
+ *
+ * So the edit is a surgical line insertion rather than a re-render.
+ *
+ * @module lib/orchestration/epic-checklist
+ * @see Story #5155
+ */
+
+import {
+  CHECKLIST_ITEM_LINE_RE,
+  CHILDREN_HEADING,
+  NO_CHILDREN_PLACEHOLDER,
+  normalizeChildIds,
+  readEpicChildIds,
+} from './epic-container.js';
+
+/**
+ * Index of the last `- [ ] #N` row in a body's lines, or -1.
+ *
+ * @param {string[]} lines
+ * @returns {number}
+ */
+function findLastChecklistIndex(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (CHECKLIST_ITEM_LINE_RE.test(lines[i])) return i;
+  }
+  return -1;
+}
+
+/**
+ * Where the new rows go, as a `[index, deleteCount]` splice target.
+ *
+ * Three placements, in priority order, each preserving a different thing:
+ * replacing the empty-container placeholder (which would otherwise stand above
+ * rows that contradict it), appending after the last existing row (which keeps
+ * original-then-appended order on read-back), or opening the section for a body
+ * that never had one.
+ *
+ * @param {string[]} lines
+ * @returns {[number, number]|null} `null` when there is no section to extend.
+ */
+function locateInsertion(lines) {
+  const placeholderAt = lines.findIndex(
+    (line) => line.trim() === NO_CHILDREN_PLACEHOLDER,
+  );
+  if (placeholderAt !== -1) return [placeholderAt, 1];
+
+  const lastItemAt = findLastChecklistIndex(lines);
+  if (lastItemAt !== -1) return [lastItemAt + 1, 0];
+
+  const headingAt = lines.findIndex((line) => line.trim() === CHILDREN_HEADING);
+  if (headingAt === -1) return null;
+  // Keep the blank line a composed body puts under the heading.
+  const blank = lines[headingAt + 1]?.trim() === '' ? 1 : 0;
+  return [headingAt + 1 + blank, 0];
+}
+
+/**
+ * Append child ids to an existing Epic body's checklist, idempotently.
+ *
+ * Idempotence is the load-bearing property: a resumed or re-run persist calls
+ * this again with the same cohort, and a second copy of every row would make
+ * the container claim children it does not have.
+ *
+ * @param {string} body The Epic's current body.
+ * @param {number[]} childIds Ids to add.
+ * @returns {string} The updated body (byte-identical when nothing was added).
+ */
+export function appendEpicChildIds(body, childIds) {
+  const text = typeof body === 'string' ? body : '';
+  const existing = new Set(readEpicChildIds(text));
+  const additions = normalizeChildIds(childIds).filter(
+    (id) => !existing.has(id),
+  );
+  if (additions.length === 0) return text;
+
+  const rows = additions.map((id) => `- [ ] #${id}`);
+  const lines = text.split('\n');
+  const target = locateInsertion(lines);
+
+  if (target === null) {
+    // A hand-written or foreign Epic with no checklist section. Add one rather
+    // than refusing: `isEpicTicket` already treats such a ticket as a real
+    // Epic, so the adoption must not be the one place that disagrees.
+    return `${text.replace(/\n+$/, '')}\n\n${CHILDREN_HEADING}\n\n${rows.join('\n')}\n`;
+  }
+
+  lines.splice(target[0], target[1], ...rows);
+  return lines.join('\n');
+}

package/.agents/scripts/lib/orchestration/epic-container.js

@@ -37,11 +37,27 @@ import { TYPE_LABELS } from '../label-constants.js';
  */
 const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+#(\d+)\s*$/gm;
 
+/**
+ * The same grammar, unanchored to a global cursor — for callers testing one
+ * line at a time. Kept beside its `/g` twin so the two cannot drift.
+ */
+export const CHECKLIST_ITEM_LINE_RE = /^-\s*\[[ xX]\]\s+#\d+\s*$/;
+
 /** Heading the container's one prose section renders under. */
 const GOAL_HEADING = '## Goal';
 
 /** Heading the child checklist renders under. */
-const CHILDREN_HEADING = '## Stories';
+export const CHILDREN_HEADING = '## Stories';
+
+/**
+ * Rendered in place of the checklist when a container has no children yet.
+ *
+ * Exported because {@link appendEpicChildIds} must *remove* it when the first
+ * child arrives: a container that lists a Story and still claims to be empty
+ * is a body that contradicts itself, and the two writers have to agree on the
+ * exact string to keep that from happening.
+ */
+export const NO_CHILDREN_PLACEHOLDER = '_No child Stories linked._';
 
 /**
  * Normalize an issue's labels to plain strings. GitHub hands labels back
@@ -95,7 +111,7 @@ export function composeEpicBody({ goal, childIds = [] } = {}) {
   const ids = normalizeChildIds(childIds);
   const lines = [GOAL_HEADING, '', text, '', CHILDREN_HEADING, ''];
   if (ids.length === 0) {
-    lines.push('_No child Stories linked._');
+    lines.push(NO_CHILDREN_PLACEHOLDER);
   } else {
     for (const id of ids) lines.push(`- [ ] #${id}`);
   }

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

@@ -34,7 +34,9 @@ import {
 import { concurrentMap, FANOUT_CONCURRENCY } from '../util/concurrent-map.js';
 import { buildComplexitySignals } from './complexity-gate.js';
 import { parseDeliverySlicingTable } from './consolidation-precondition.js';
+import { findDependencyCandidates } from './dependency-candidates.js';
 import { buildDocsDigest } from './docs-digest.js';
+import { findOpenEpicCandidates } from './epic-candidates.js';
 import { buildAuthoringContext } from './planning/authoring-context.js';
 import { buildDecomposerSystemPrompt } from './planning/decomposer-context.js';
 
@@ -849,11 +851,12 @@ 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).
+ * Gather the independent envelope inputs — the open-Story duplicate search,
+ * the folded authoring context, the inline docs digest, and (Story #5155) the
+ * open-Epic and cross-plan-dependency candidate lists — under bounded
+ * concurrency (Story #4952).
  *
- * None of the three reads a value the others produce, so the result is a pure
+ * None of them 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
@@ -875,6 +878,8 @@ async function searchStoryDuplicates({
  * @returns {Promise<{
  *   duplicates: Array<object>,
  *   authoring: object,
+ *   epicCandidates: Array<object>,
+ *   dependencyCandidates: Array<object>,
  *   docsContext: { mode: 'digest-inline', digest: string }|null,
  * }>}
  */
@@ -882,13 +887,20 @@ async function gatherEnvelopeInputs({
   seed,
   epicTitle,
   excludeIds = [],
+  predictedPaths = [],
   provider,
   config,
   settings,
   cwd,
 }) {
   const paths = settings?.paths ?? {};
-  const [duplicates, authoring, inlineDigest] = await concurrentMap(
+  const [
+    duplicates,
+    authoring,
+    inlineDigest,
+    epicCandidates,
+    dependencyCandidates,
+  ] = await concurrentMap(
     [
       () => searchStoryDuplicates({ seed, provider, config, excludeIds }),
       () =>
@@ -907,6 +919,25 @@ async function gatherEnvelopeInputs({
           docsContextFiles: settings?.docsContextFiles,
           docsRoot: paths.docsRoot,
         }),
+      // Story #5155 — the two cross-plan lookups. Both are advisory triage
+      // lists offered at Gate #3, independent of every other gather and of
+      // each other, so they join the same bounded fan-out rather than adding
+      // two more serial round-trips to the operator's wait.
+      () =>
+        findOpenEpicCandidates({
+          seed,
+          provider,
+          owner: config.github?.owner,
+          repo: config.github?.repo,
+        }),
+      () =>
+        findDependencyCandidates({
+          predictedPaths,
+          provider,
+          owner: config.github?.owner,
+          repo: config.github?.repo,
+          excludeIds,
+        }),
     ],
     (gather) => gather(),
     // The per-mode envelope gathers (Story #4952): the duplicate search, the
@@ -919,6 +950,8 @@ async function gatherEnvelopeInputs({
   return {
     duplicates,
     authoring,
+    epicCandidates,
+    dependencyCandidates,
     docsContext:
       inlineDigest == null
         ? null
@@ -949,20 +982,42 @@ async function buildSeedFileModeEnvelope({
     );
   }
 
-  // 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({
+  const limits = getLimits(config);
+  const heuristics = resolveRiskHeuristics(config);
+
+  // Hoisted above the gather (Story #5155): the dependency-candidate lookup
+  // intersects against `predictedPaths`, so the signals have to exist before
+  // the fan-out starts. `buildComplexitySignals` is synchronous and reads
+  // nothing the gather produces, so hoisting it changes cost, not output.
+  const complexitySignals = withAdvisorySignals(
+    buildComplexitySignals({
+      seedText: content,
+      config,
+      riskHeuristics: heuristics,
+      cwd,
+    }),
+    { config, cwd },
+  );
+
+  // Dup search, the authoring-context fold grounded in the seed prose, the
+  // inline docs digest and the two cross-plan candidate lists are independent
+  // — gathered concurrently (Story #4952, Story #5155).
+  const {
+    duplicates,
+    authoring,
+    docsContext,
+    epicCandidates,
+    dependencyCandidates,
+  } = await gatherEnvelopeInputs({
     seed: content,
     epicTitle: seedFilePath ?? 'seed',
+    predictedPaths: complexitySignals.predictedPaths,
     provider,
     config,
     settings,
     cwd,
   });
 
-  const limits = getLimits(config);
-  const heuristics = resolveRiskHeuristics(config);
-
   return {
     mode: modeLabel,
     seed: { path: seedFilePath ?? null, content },
@@ -972,16 +1027,10 @@ async function buildSeedFileModeEnvelope({
     // `deliverLightSuggestion` is the advisory plan-side routing handshake
     // (Story #4741 AC-6) and `uiSurface` the advisory /prototype offer —
     // neither is ever an automatic reroute.
-    complexitySignals: withAdvisorySignals(
-      buildComplexitySignals({
-        seedText: content,
-        config,
-        riskHeuristics: heuristics,
-        cwd,
-      }),
-      { config, cwd },
-    ),
+    complexitySignals,
     duplicates,
+    epicCandidates,
+    dependencyCandidates,
     docsContext,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,
@@ -1095,36 +1144,48 @@ async function buildTicketsModeEnvelope({
     .map((t) => `# ${t.title}\n\n${t.body}`)
     .join('\n\n---\n\n');
 
-  // 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({
+  const limits = getLimits(config);
+  const heuristics = resolveRiskHeuristics(config);
+
+  // Hoisted for the same reason as seed-file mode (Story #5155).
+  const complexitySignals = withAdvisorySignals(
+    buildComplexitySignals({
+      seedText: seed,
+      config,
+      riskHeuristics: heuristics,
+      cwd,
+    }),
+    { config, cwd },
+  );
+
+  // Same 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,
+    epicCandidates,
+    dependencyCandidates,
+  } = await gatherEnvelopeInputs({
     seed,
     epicTitle: sourceTickets[0]?.title ?? 'tickets',
     excludeIds: ticketIds,
+    predictedPaths: complexitySignals.predictedPaths,
     provider,
     config,
     settings,
     cwd,
   });
 
-  const limits = getLimits(config);
-  const heuristics = resolveRiskHeuristics(config);
-
   return {
     mode: 'tickets',
     sourceTickets,
     seed: { text: seed, path: null },
-    complexitySignals: withAdvisorySignals(
-      buildComplexitySignals({
-        seedText: seed,
-        config,
-        riskHeuristics: heuristics,
-        cwd,
-      }),
-      { config, cwd },
-    ),
+    complexitySignals,
     duplicates,
+    epicCandidates,
+    dependencyCandidates,
     docsContext,
     bddRunner: authoring.bddRunner,
     bddScenarios: authoring.bddScenarios,

package/.agents/scripts/lib/orchestration/plan-persist/cross-plan-links.js

@@ -0,0 +1,80 @@
+/**
+ * cross-plan-links.js — resolve every reference a plan makes to something
+ * outside itself, before anything is written.
+ *
+ * Story #5155. A plan can now point at two things it did not author: the
+ * container Epic it wants to join (`--epic <id>`) and the open Stories it must
+ * wait for (`depends_on: ["#<id>"]`). They are different features with
+ * different owners, but they share the one property that decides *when* they
+ * are checked, and that is what this module exists to express: both name live
+ * tracker state, so both are verified **before the first `createIssue`**, dry
+ * run included.
+ *
+ * The timing is the whole point. Either reference is free to fix while nothing
+ * has been written and expensive afterwards — an unresolvable blocker left on
+ * a live Story reads to the delivery engine as a permanent wedge rather than
+ * an error worth reporting, and a mistyped Epic id would leave the operator
+ * believing their Stories were filed somewhere they were not. Resolving them
+ * together, at one call site, is what keeps a later edit from quietly moving
+ * one of them after the creates.
+ *
+ * @module lib/orchestration/plan-persist/cross-plan-links
+ * @see Story #5155
+ */
+
+import { adoptContainerEpic, resolveAdoptionTarget } from './epic-adoption.js';
+import { createContainerEpic } from './epic-ops.js';
+import { assertExternalDependenciesResolvable } from './external-deps.js';
+
+/**
+ * Verify a plan's outward references and return the Epic it adopts.
+ *
+ * @param {{
+ *   provider: object,
+ *   stories: Array<{ slug: string, depends_on?: string[] }>,
+ *   epicId: number|null,
+ * }} args
+ * @returns {Promise<{ id: number, title: string, body: string }|null>}
+ *   The resolved adoption target, or `null` when none was requested.
+ * @throws {Error} When a `#<id>` blocker or the named Epic cannot be used.
+ */
+export async function resolveCrossPlanLinks({ provider, stories, epicId }) {
+  await assertExternalDependenciesResolvable({ provider, stories });
+  return resolveAdoptionTarget({ provider, epicId });
+}
+
+/**
+ * Resolve this run's container Epic — adopted or newly created.
+ *
+ * The one entry point `run-plan-persist` calls, so the engine holds a single
+ * statement rather than a branch it has to keep straight: which of the two
+ * paths applies is decided by whether an adoption target was resolved before
+ * the creates, and the two have opposite failure postures that are easy to
+ * apply to the wrong one when the choice is inlined at the call site.
+ *
+ * @param {{
+ *   provider: object,
+ *   adoptionTarget: { id: number, title: string, body: string }|null,
+ *   epic: { title: string, goal: string }|null,
+ *   created: Array<{ id: number }>,
+ *   opts?: { dryRun?: boolean },
+ * }} args
+ * @returns {Promise<object|null>} `null` when this run has no container.
+ */
+export async function resolveContainerEpic({
+  provider,
+  adoptionTarget,
+  epic,
+  created,
+  opts = {},
+}) {
+  if (adoptionTarget) {
+    return adoptContainerEpic({
+      provider,
+      target: adoptionTarget,
+      created,
+      opts,
+    });
+  }
+  return createContainerEpic({ provider, epic, created, opts });
+}