mandrel 2.39.0 → 2.41.0

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

@@ -0,0 +1,148 @@
+/**
+ * epic-expansion.js — turn a container-Epic id into the open Story ids under it.
+ *
+ * Split out of `resolve-stories.js` (Story #5139): Epic expansion is a
+ * distinct concern from Story resolution — it runs strictly *before* it and
+ * hands it an ordinary id list — and folding it into that already-dense module
+ * cost 4.19 maintainability points for no cohesion gain.
+ *
+ * @module lib/orchestration/epic-expansion
+ */
+
+import { TYPE_LABELS } from '../label-constants.js';
+import { isEpicTicket, readEpicChildIdsFrom } from './epic-container.js';
+import { isSatisfiedBlocker } from './resolve-stories.js';
+
+/**
+ * Does this issue carry the Story type label?
+ *
+ * @param {{ labels?: unknown }} issue
+ * @returns {boolean}
+ */
+function isStoryTicket(issue) {
+  const raw = issue?.labels;
+  if (!Array.isArray(raw)) return false;
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .includes(TYPE_LABELS.STORY);
+}
+
+/**
+ * Expand any container-Epic id in the requested set to its open child
+ * Stories, leaving every other id untouched.
+ *
+ * `/mandrel-deliver <epicId>` means "deliver everything under this Epic". The
+ * expansion happens **here, before resolution**, so everything downstream —
+ * the DAG, the ready set, the wave tick, the close tail — sees an ordinary
+ * list of Story ids and needs no Epic concept at all. That is the whole
+ * reason the Epic can exist without touching the delivery engine.
+ *
+ * Expansion is **per id**, so Epic and Story ids may be mixed freely in one
+ * invocation and the result is the deduped union in first-seen order.
+ *
+ * Two filters apply to children, and they are deliberately quieter than the
+ * treatment of a *named* id:
+ *
+ *   - **A closed / `agent::done` child is dropped.** Delivering an Epic means
+ *     delivering what is left of it. A dependent's edge onto a landed sibling
+ *     still resolves: the sibling becomes a *foreign* blocker, and foreign
+ *     blockers are checked against live state and enter `done[]`.
+ *   - **A child that is not a `type::story` is dropped with a warning.** A
+ *     named non-Story is an error because the operator asserted it was
+ *     deliverable; a linked one is the Epic's assertion, and someone attaching
+ *     a stray issue in the GitHub UI must not wedge the whole run.
+ *
+ * An Epic that expands to nothing is an **error**, not an empty success: a
+ * silent empty envelope would report a clean no-op for a delivery the
+ * operator asked for and never got.
+ *
+ * @param {{
+ *   ids: number[],
+ *   getTicket: (id: number) => Promise<object|null>,
+ *   readNativeChildIds?: (epic: object) => Promise<number[]>,
+ *   warn?: (msg: string) => void,
+ * }} opts
+ * @returns {Promise<{ ids: number[], expansions: Array<{ epicId: number, childIds: number[] }> }>}
+ */
+export async function expandEpicIds({
+  ids,
+  getTicket,
+  readNativeChildIds,
+  warn,
+}) {
+  const out = [];
+  const seen = new Set();
+  const expansions = [];
+
+  const push = (id) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push(id);
+  };
+
+  for (const id of ids) {
+    const issue = await getTicket(id);
+    if (!issue) {
+      throw new Error(`[resolve-stories] Issue #${id} was not found.`);
+    }
+    if (!isEpicTicket(issue)) {
+      push(id);
+      continue;
+    }
+
+    const childIds = await readEpicChildIdsFrom({
+      epic: issue,
+      readNativeChildIds,
+      onWarn: warn,
+    });
+    if (childIds.length === 0) {
+      throw new Error(
+        `[resolve-stories] Epic #${id} lists no child Stories. An Epic is a container: ` +
+          `link its Stories (a "- [ ] #N" checklist line or a GitHub sub-issue) ` +
+          `or deliver the Story ids directly.`,
+      );
+    }
+
+    const open = [];
+    for (const childId of childIds) {
+      let child;
+      try {
+        child = await getTicket(childId);
+      } catch (err) {
+        warn?.(
+          `[resolve-stories] Epic #${id}: could not read child #${childId} ` +
+            `(${err?.message ?? err}) — skipping it.`,
+        );
+        continue;
+      }
+      if (!child) {
+        warn?.(
+          `[resolve-stories] Epic #${id}: child #${childId} was not found — skipping it.`,
+        );
+        continue;
+      }
+      if (!isStoryTicket(child)) {
+        warn?.(
+          `[resolve-stories] Epic #${id}: child #${childId} is not a ${TYPE_LABELS.STORY} ` +
+            `— skipping it. Only Stories are deliverable.`,
+        );
+        continue;
+      }
+      if (isSatisfiedBlocker(child)) continue;
+      open.push(childId);
+    }
+
+    if (open.length === 0) {
+      throw new Error(
+        `[resolve-stories] Epic #${id} has ${childIds.length} child Story(ies), ` +
+          `but none are still open — every one is closed or agent::done. ` +
+          `There is nothing left to deliver.`,
+      );
+    }
+
+    expansions.push({ epicId: id, childIds: open });
+    for (const childId of open) push(childId);
+  }
+
+  return { ids: out, expansions };
+}

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 });
+}

package/.agents/scripts/lib/orchestration/plan-persist/epic-adoption.js

@@ -0,0 +1,192 @@
+/**
+ * epic-adoption.js — join the Stories of this persist run to an Epic that
+ * already exists.
+ *
+ * Story #5155. `epic-ops.js` opens a *new* container and, on a resumed run,
+ * re-adopts the one carrying its exact fingerprint. This module covers the
+ * case neither does: an operator pointing a fresh plan at an Epic an earlier
+ * plan opened, with a different cohort and no fingerprint in common.
+ *
+ * **The posture is deliberately stricter than creation's.** Creation degrades
+ * — an unensurable label just skips the container, because the Stories are the
+ * part that matters and a missing Epic costs only tidiness. Adoption cannot
+ * degrade the same way: the operator named a specific id, so silently not
+ * adopting it would leave them believing their Stories were filed somewhere
+ * they were not. A bad target is therefore a **hard error, raised before the
+ * first Story is created** (dry run included), when nothing has been written
+ * and the fix is free. Once the Stories exist, the posture flips to creation's
+ * — a failed checklist write or sub-issue edge warns, because by then refusing
+ * would strand live Stories over a cosmetic link.
+ *
+ * @module lib/orchestration/plan-persist/epic-adoption
+ * @see Story #5155
+ */
+
+import { Logger } from '../../Logger.js';
+import { TYPE_LABELS } from '../../label-constants.js';
+import { appendEpicChildIds } from '../epic-checklist.js';
+import { isEpicTicket } from '../epic-container.js';
+import { mirrorSubIssueEdges } from './epic-ops.js';
+
+/**
+ * Resolve and validate the Epic an operator asked to adopt.
+ *
+ * Called **before any create**, so every refusal below costs the operator a
+ * re-run of a command that wrote nothing.
+ *
+ * A null/absent `epicId` is the ordinary "no adoption requested" case and
+ * resolves to `null` — only a *supplied* id can be wrong, and every wrong one
+ * throws.
+ *
+ * @param {{ provider: object, epicId: number|null }} opts
+ * @returns {Promise<{ id: number, title: string, body: string }|null>}
+ * @throws {Error} When a supplied id is missing, closed, or not a container Epic.
+ */
+export async function resolveAdoptionTarget({ provider, epicId }) {
+  if (epicId === null || epicId === undefined) return null;
+  const id = Number(epicId);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(
+      `[plan-persist] --epic expects a positive issue id (got "${epicId}").`,
+    );
+  }
+  if (typeof provider?.getTicket !== 'function') {
+    throw new Error(
+      '[plan-persist] provider exposes no getTicket — cannot verify the Epic to adopt.',
+    );
+  }
+
+  let issue;
+  try {
+    issue = await provider.getTicket(id);
+  } catch (err) {
+    throw new Error(
+      `[plan-persist] --epic #${id} could not be read (${err?.message ?? err}). ` +
+        'Adoption needs an existing open container Epic.',
+    );
+  }
+  if (!issue) {
+    throw new Error(`[plan-persist] --epic #${id} does not exist.`);
+  }
+
+  const state = String(issue.state ?? 'open').toLowerCase();
+  if (state !== 'open') {
+    throw new Error(
+      `[plan-persist] --epic #${id} is ${state}. A closed Epic is a finished body of ` +
+        'work and is never reopened by a plan — open a new container, or reopen it by hand first.',
+    );
+  }
+  if (!isEpicTicket(issue)) {
+    throw new Error(
+      `[plan-persist] --epic #${id} does not carry "${TYPE_LABELS.EPIC}" — it is not a ` +
+        'container Epic. Adopting an ordinary Story would file this plan under a work item.',
+    );
+  }
+
+  return {
+    id,
+    title: typeof issue.title === 'string' ? issue.title : '',
+    body: typeof issue.body === 'string' ? issue.body : '',
+  };
+}
+
+/**
+ * Link this run's Stories into an already-resolved Epic.
+ *
+ * Runs **after** the Stories exist, because both halves of the linkage need
+ * their real ids: the checklist embeds issue numbers and the sub-issue edges
+ * need database ids.
+ *
+ * @param {{
+ *   provider: object,
+ *   target: { id: number, title: string, body: string },
+ *   created: Array<{ id: number }>,
+ *   opts?: { dryRun?: boolean },
+ * }} args
+ * @returns {Promise<{
+ *   id: number,
+ *   title: string,
+ *   childIds: number[],
+ *   adopted: true,
+ *   edges: { added: number, skipped: number, failed: number }|null,
+ * }|null>}
+ */
+export async function adoptContainerEpic({
+  provider,
+  target,
+  created,
+  opts = {},
+}) {
+  const { dryRun = false } = opts;
+  if (!target) return null;
+
+  const all = Array.isArray(created) ? created : [];
+
+  // Dry run reports the intent write-free. `created` carries negative
+  // placeholder ids there, so report them as-is rather than filtering to the
+  // positives and claiming an empty adoption.
+  if (dryRun) {
+    return {
+      id: target.id,
+      title: target.title,
+      childIds: all.map((s) => s.id),
+      adopted: true,
+      edges: null,
+    };
+  }
+
+  const childIds = all
+    .map((s) => s.id)
+    .filter((id) => Number.isInteger(id) && id > 0);
+  if (childIds.length === 0) return null;
+
+  await appendChecklist({ provider, target, childIds });
+  const edges = await mirrorSubIssueEdges({
+    provider,
+    epicNumber: target.id,
+    childIds,
+  });
+
+  Logger.info(
+    `[plan-persist] adopted container Epic #${target.id} — it now groups ` +
+      `${childIds.length} more Story(ies): /mandrel-deliver ${target.id}`,
+  );
+
+  return {
+    id: target.id,
+    title: target.title,
+    childIds,
+    adopted: true,
+    edges,
+  };
+}
+
+/**
+ * Write the appended checklist back to the Epic body.
+ *
+ * Non-fatal: the Stories are already live, and the native sub-issue edges
+ * written next are the other half of the linkage. Losing the checklist costs
+ * the body-only fallback path, not the grouping.
+ *
+ * @param {{ provider: object, target: { id: number, body: string }, childIds: number[] }} opts
+ * @returns {Promise<void>}
+ */
+async function appendChecklist({ provider, target, childIds }) {
+  if (typeof provider?.updateTicket !== 'function') {
+    Logger.warn(
+      '[plan-persist] provider exposes no updateTicket — the adopted Epic body was not ' +
+        'updated. The native sub-issue edges still record the grouping.',
+    );
+    return;
+  }
+  const next = appendEpicChildIds(target.body, childIds);
+  if (next === target.body) return;
+  try {
+    await provider.updateTicket(target.id, { body: next });
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] could not update Epic #${target.id}'s checklist ` +
+        `(${err?.message ?? err}). The native sub-issue edges still record the grouping.`,
+    );
+  }
+}