mandrel 2.39.0 → 2.40.0

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

@@ -7,6 +7,8 @@
  *   2. Rolls up friction follow-ups across every Story in the run and
  *      files/posts them on the primary Story.
  *   3. Checks sibling Spec/acceptance coherence across Story bodies.
+ *   4. Closes any container Epic whose children all landed (Story #5139) —
+ *      the only completion cascade v2 reintroduces.
  *
  * There is no inert planner-only path: `planRunEpilogue` enumerates steps
  * and `runPlanRunEpilogue` executes them. Single-Story runs skip the
@@ -19,6 +21,8 @@ import { selectAudits } from '../audit-suite/index.js';
 import { graduateRetroProposals } from '../feedback-loop/retro-proposals-graduator.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
+import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
+import { isEpicTicket, readEpicChildIds } from './epic-container.js';
 import { composeRoutedProposals } from './retro-proposals.js';
 import {
   assessRollupOutcome,
@@ -31,14 +35,130 @@ import { upsertStructuredComment } from './ticketing.js';
 
 /**
  * Canonical epilogue step kinds, in execution order.
- * @type {readonly ['audit-roster', 'follow-up-rollup', 'sibling-coherence']}
+ * @type {readonly ['audit-roster', 'follow-up-rollup', 'sibling-coherence', 'epic-close']}
  */
 export const RUN_EPILOGUE_STEP_KINDS = Object.freeze([
   'audit-roster',
   'follow-up-rollup',
   'sibling-coherence',
+  'epic-close',
 ]);
 
+/**
+ * Close a container Epic once every child Story has landed.
+ *
+ * This is the **only** completion cascade v2 reintroduces (Story #5139), and
+ * it is deliberately one-directional: closing the container, never touching a
+ * child's state, never reopening.
+ *
+ * The lookup runs child→parent by scanning open Epics, because linkage is
+ * parent→child only — a Story body carries no pointer back. That is the
+ * price of leaving Story bodies untouched, and it is cheap: open Epics are
+ * few, and the scan is scoped to Epics that actually contain one of this
+ * run's delivered Stories, so an unrelated Epic is never swept.
+ *
+ * Non-fatal throughout: the epilogue is a reporting tail, and a container
+ * left open costs tidiness, not correctness.
+ *
+ * @param {{ stories: string[], provider: object }} opts
+ * @returns {Promise<{ kind: string, closed: number[], pending: number[] }>}
+ */
+async function executeEpicClose({ stories, provider }) {
+  const result = { kind: 'epic-close', closed: [], pending: [] };
+  if (
+    typeof provider?.listIssuesByLabel !== 'function' ||
+    typeof provider?.updateTicket !== 'function'
+  ) {
+    return result;
+  }
+
+  const delivered = new Set(stories.map((id) => Number(id)));
+  let epics;
+  try {
+    epics = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[run-epilogue] Could not list open Epics (${err?.message ?? err}); skipping the Epic close.`,
+    );
+    return result;
+  }
+
+  for (const epic of Array.isArray(epics) ? epics : []) {
+    if (!isEpicTicket(epic)) continue;
+    const epicId = Number(epic?.number ?? epic?.id);
+    if (!Number.isInteger(epicId)) continue;
+
+    const childIds = readEpicChildIds(epic?.body);
+    if (childIds.length === 0) continue;
+    // Only Epics this run actually advanced. Sweeping every open Epic would
+    // make a delivery close containers it had nothing to do with.
+    if (!childIds.some((c) => delivered.has(c))) continue;
+
+    let allLanded = true;
+    for (const childId of childIds) {
+      try {
+        const child = await provider.getTicket(childId);
+        if (!isSatisfiedChild(child)) {
+          allLanded = false;
+          break;
+        }
+      } catch (err) {
+        Logger.warn(
+          `[run-epilogue] Epic #${epicId}: could not read child #${childId} ` +
+            `(${err?.message ?? err}) — leaving the Epic open.`,
+        );
+        allLanded = false;
+        break;
+      }
+    }
+
+    if (!allLanded) {
+      result.pending.push(epicId);
+      continue;
+    }
+
+    try {
+      await provider.updateTicket(epicId, {
+        state: 'closed',
+        state_reason: 'completed',
+      });
+      Logger.info(
+        `[run-epilogue] Closed container Epic #${epicId} — all ${childIds.length} child Story(ies) landed.`,
+      );
+      result.closed.push(epicId);
+    } catch (err) {
+      Logger.warn(
+        `[run-epilogue] Could not close Epic #${epicId} (${err?.message ?? err}).`,
+      );
+      result.pending.push(epicId);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * A child no longer holds its Epic open once it is closed or `agent::done`.
+ *
+ * Mirrors `isSatisfiedBlocker` in `lib/orchestration/resolve-stories.js`
+ * rather than importing it: that module is the delivery-resolution path and
+ * pulling it in here would drag the whole story-body parser into the
+ * epilogue for a two-line predicate.
+ *
+ * @param {{ state?: string, labels?: unknown }} issue
+ * @returns {boolean}
+ */
+function isSatisfiedChild(issue) {
+  if (String(issue?.state ?? '').toLowerCase() === 'closed') return true;
+  const labels = Array.isArray(issue?.labels)
+    ? issue.labels.map((l) => (typeof l === 'string' ? l : l?.name))
+    : [];
+  return labels.includes(AGENT_LABELS.DONE);
+}
+
 /**
  * @param {string|number|{ id?: string|number, slug?: string }} entry
  * @returns {string|null}
@@ -123,6 +243,11 @@ export function planRunEpilogue({ planRunId, stories } = {}) {
       description: `Sibling-coherence check across the ${ids.length} Story specs of run ${effectiveRunId}`,
       stories: ids,
     },
+    {
+      kind: 'epic-close',
+      description: `Close any container Epic whose children all landed in run ${effectiveRunId}`,
+      stories: ids,
+    },
   ];
 
   return {
@@ -825,6 +950,10 @@ export async function runPlanRunEpilogue({
             provider,
           }),
         );
+      } else if (step.kind === 'epic-close') {
+        results.push(
+          await executeEpicClose({ stories: plan.stories, provider }),
+        );
       }
     } catch (err) {
       const message = err?.message ?? String(err);

package/.agents/scripts/plan-persist.js

@@ -124,6 +124,8 @@ const CLI_OPTIONS = {
   'force-review': { type: 'boolean', default: false },
   'allow-over-budget': { type: 'boolean', default: false },
   'allow-large-fan-out': { type: 'boolean', default: false },
+  'epic-title': { type: 'string' },
+  'epic-goal': { type: 'string' },
 };
 
 const USAGE =
@@ -133,7 +135,8 @@ const USAGE =
   '[--source-tickets <ids>] [--no-close-superseded] ' +
   '[--route-downgrade-reason <text>] ' +
   '[--dry-run] [--chain-on-clean] [--force-review] ' +
-  '[--allow-over-budget] [--allow-large-fan-out]';
+  '[--allow-over-budget] [--allow-large-fan-out] ' +
+  '[--epic-title <text> --epic-goal <text>]';
 
 async function readOptional(filePath, { required }) {
   try {
@@ -196,6 +199,32 @@ async function loadArtifacts(paths) {
   };
 }
 
+/**
+ * Resolve the optional container-Epic request from the CLI flags.
+ *
+ * Both halves are required together: an Epic with a title and no goal is a
+ * container with nothing explaining the grouping, and a goal with no title
+ * cannot be opened at all. Supplying exactly one is a **usage error**, not a
+ * silent no-Epic run — the operator asked for a container and would otherwise
+ * never learn they did not get one.
+ *
+ * @param {object} values Parsed `parseArgs` values.
+ * @returns {{ title: string, goal: string }|null} `null` when no Epic was requested.
+ */
+export function resolveEpicRequest(values) {
+  const title = (values['epic-title'] ?? '').trim();
+  const goal = (values['epic-goal'] ?? '').trim();
+  if (title === '' && goal === '') return null;
+  if (title === '' || goal === '') {
+    throw new Error(
+      '[plan-persist] --epic-title and --epic-goal must be supplied together ' +
+        '(a container Epic needs both a name and a one-paragraph reason it ' +
+        'groups these Stories).',
+    );
+  }
+  return { title, goal };
+}
+
 /**
  * Assemble the `runPlanPersist` opts bag from parsed CLI values.
  *
@@ -224,6 +253,7 @@ export function buildPersistOptions(values, paths, planContextEnvelope) {
     sourceTicketIds: source.ids,
     sourceTicketOrigin: source.origin,
     routeDowngradeReason: values['route-downgrade-reason'] ?? null,
+    epic: resolveEpicRequest(values),
     // Default-on: `--no-close-superseded` is the explicit escape and always
     // wins over the (default `true`) `--close-superseded`.
     closeSuperseded:
@@ -468,6 +498,14 @@ runAsCli(import.meta.url, main, {
       ],
       ['--allow-over-budget', 'Permit a Spec over the context budget.'],
       ['--allow-large-fan-out', 'Permit a Story count above the fan-out gate.'],
+      [
+        '--epic-title <text>',
+        'Group the persisted Stories under a container Epic with this title (needs --epic-goal).',
+      ],
+      [
+        '--epic-goal <text>',
+        'The container Epic’s one-paragraph goal (needs --epic-title).',
+      ],
     ],
   },
 });

package/.agents/scripts/providers/github/sub-issue-add.js

@@ -0,0 +1,218 @@
+/**
+ * GitHub Provider — shared "link child issue to a parent" helper.
+ *
+ * Story #5139 — a container Epic holds its children as native GitHub
+ * sub-issue edges. The read side has existed since v1
+ * (`sub-issues.js` → `getNativeSubIssues`, and the three-strategy
+ * aggregator in `issues.js` → `getSubTickets`); this is the missing write.
+ *
+ * API surface used:
+ *   Read:  GET  /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
+ *   Write: POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
+ *          body: { "sub_issue_id": <integer db id of the CHILD issue> }
+ *
+ * **`sub_issue_id` is the child's database id, not its issue number.** They
+ * are different integers and both are plausible, so a mix-up does not throw
+ * — it silently links the wrong issue, or a nonexistent one. This mirrors
+ * `blocked-by-add.js`, whose `issue_id` carries the same trap.
+ *
+ * Contract (deliberately identical to `blocked-by-add.js`):
+ *   - **Idempotent** — reads existing edges first; only POSTs missing ones.
+ *   - **Non-fatal** — catches all errors per edge, warns, and continues.
+ *     The function never throws; failures are returned in the summary.
+ *     The Epic body's checklist is the durable mirror, so a lost edge
+ *     degrades discoverability rather than losing the child.
+ *   - **No-op on empty input.**
+ */
+
+import { Logger } from '../../lib/Logger.js';
+import { concurrentMap } from '../../lib/util/concurrent-map.js';
+import { paginateRest } from './request-helpers.js';
+
+/**
+ * Bounded concurrency for the sub-issue round-trips. Matches the
+ * dependency-edge writer's cap: modest enough for GitHub's secondary rate
+ * limits while collapsing wall-clock from `sum(round-trips)` toward
+ * `sum(round-trips) / concurrency`.
+ */
+const EDGE_CONCURRENCY = 5;
+
+/**
+ * Fetch the database ids of a parent's existing sub-issues, **paginated to
+ * exhaustion**.
+ *
+ * This read is the idempotency check: an edge it fails to see is re-POSTed.
+ * Reading only the first page would therefore make the writer non-idempotent
+ * past the page boundary — the same defect Story #5046 fixed in
+ * `blocked-by-add.js`.
+ *
+ * Returns `[]` on any error so the caller falls back to posting the full
+ * set. Worst case is a duplicate POST, which GitHub rejects harmlessly and
+ * the per-edge catch absorbs.
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number, paginate?: Function }} opts
+ * @returns {Promise<number[]>} Database ids of the parent's current children.
+ */
+async function fetchExistingSubIssueIds({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  paginate = paginateRest,
+}) {
+  try {
+    const data = await paginate(
+      gh,
+      `/repos/${owner}/${repo}/issues/${issueNumber}/sub_issues`,
+      { label: `[sub-issue-add] sub_issues #${issueNumber}` },
+    );
+    if (!Array.isArray(data)) return [];
+    return data.map((item) => item?.id).filter((id) => typeof id === 'number');
+  } catch (err) {
+    Logger.warn(
+      `[sub-issue-add] Could not fetch existing sub-issues for #${issueNumber}: ${err.message}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Link a set of child issues to one parent as native sub-issues.
+ *
+ * For each entry in `childInternalIds`, checks whether the edge already
+ * exists and POSTs only the missing ones. Every individual POST failure is
+ * caught, logged and counted — the function never throws.
+ *
+ * @param {{
+ *   gh: object,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   childInternalIds: number[],
+ *   paginate?: Function,
+ * }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }>}
+ */
+export async function addSubIssueEdges({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  childInternalIds,
+  paginate = paginateRest,
+}) {
+  const ids = Array.isArray(childInternalIds) ? childInternalIds : [];
+  if (ids.length === 0) return { added: 0, skipped: 0, failed: 0 };
+
+  const existing = await fetchExistingSubIssueIds({
+    gh,
+    owner,
+    repo,
+    issueNumber,
+    paginate,
+  });
+  const existingSet = new Set(existing);
+
+  // Partition up front so the skip count is deterministic regardless of the
+  // concurrent POST dispatch order.
+  const missing = ids.filter((id) => !existingSet.has(id));
+  const skipped = ids.length - missing.length;
+
+  const perEdge = await concurrentMap(
+    missing,
+    async (childId) => {
+      try {
+        await gh.api({
+          method: 'POST',
+          endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/sub_issues`,
+          body: { sub_issue_id: childId },
+        });
+        return { added: 1, failed: 0 };
+      } catch (err) {
+        Logger.warn(
+          `[sub-issue-add] Failed to link child(id=${childId}) under #${issueNumber}: ${err.message}`,
+        );
+        return { added: 0, failed: 1 };
+      }
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  let added = 0;
+  let failed = 0;
+  for (const r of perEdge) {
+    added += r.added;
+    failed += r.failed;
+  }
+
+  return { added, skipped, failed };
+}
+
+/**
+ * Link child Stories to a container Epic, resolving each child's **database
+ * id** from its issue number via the injected `getTicket` hook.
+ *
+ * Callers hold issue numbers (that is what `plan-persist` creates and what
+ * an operator types); the API wants database ids. Doing the translation here
+ * keeps that trap in one place instead of at every call site.
+ *
+ * Never throws: a child whose id cannot be resolved is counted as failed and
+ * the remaining edges still go out.
+ *
+ * @param {{
+ *   epicNumber: number,
+ *   childIssueNumbers: number[],
+ *   getTicket: (issueNumber: number) => Promise<{ internalId: number }>,
+ *   owner: string,
+ *   repo: string,
+ *   gh: object,
+ *   paginate?: Function,
+ * }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }>}
+ */
+export async function linkStoriesToEpic({
+  epicNumber,
+  childIssueNumbers,
+  getTicket,
+  owner,
+  repo,
+  gh,
+  paginate = paginateRest,
+}) {
+  const numbers = Array.isArray(childIssueNumbers) ? childIssueNumbers : [];
+  if (numbers.length === 0) return { added: 0, skipped: 0, failed: 0 };
+
+  let failed = 0;
+  const childInternalIds = [];
+
+  for (const childNumber of numbers) {
+    try {
+      const ticket = await getTicket(childNumber);
+      const internalId = ticket?.internalId;
+      if (typeof internalId !== 'number') {
+        Logger.warn(
+          `[sub-issue-add] Child #${childNumber} has no resolvable database id; skipping edge.`,
+        );
+        failed++;
+        continue;
+      }
+      childInternalIds.push(internalId);
+    } catch (err) {
+      Logger.warn(
+        `[sub-issue-add] Could not resolve child #${childNumber}: ${err.message}`,
+      );
+      failed++;
+    }
+  }
+
+  const summary = await addSubIssueEdges({
+    gh,
+    owner,
+    repo,
+    issueNumber: epicNumber,
+    childInternalIds,
+    paginate,
+  });
+
+  return { ...summary, failed: summary.failed + failed };
+}

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

@@ -39,6 +39,7 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import { expandEpicIds } from './lib/orchestration/epic-expansion.js';
 import {
   buildStoriesEnvelope,
   isSatisfiedBlocker,
@@ -71,7 +72,9 @@ real issue state.
 Options:
   --ids <csv>    Comma-separated Story issue numbers. Required. A token may be
                  a single id (4922) or an inclusive dash range (4922-4926);
-                 ranges expand in place and dedupe against the rest.
+                 ranges expand in place and dedupe against the rest. A
+                 container Epic id expands to its open child Stories, and may
+                 be mixed with Story ids.
   --pretty       Pretty-print the JSON envelope.
   --no-native    Skip the native blocked_by read (body edges only).
   --help         Show this help.
@@ -89,17 +92,54 @@ export function resolveStoriesProvider({
   return { provider: createProviderFn(config), config };
 }
 
+/**
+ * Read an Epic's native sub-issue children as issue numbers.
+ *
+ * Injected into `expandEpicIds` so the lib layer stays provider-agnostic,
+ * exactly as `paginate` is injected into `readNativeBlockedBy`. A provider
+ * without the GraphQL surface yields `[]`, and the Epic body's checklist
+ * carries the children on its own.
+ *
+ * @param {object} provider
+ * @returns {(epic: object) => Promise<number[]>}
+ */
+export function nativeChildReader(provider) {
+  return async (epic) => {
+    if (typeof provider?._getNativeSubIssues !== 'function') return [];
+    return provider._getNativeSubIssues(epic?.nodeId, epic?.number ?? epic?.id);
+  };
+}
+
 /**
  * Fetch every requested id and map it to a Story record, failing on the first
  * id that is not a deliverable Story.
  *
+ * Container Epics are expanded to their open child Stories **first**, so
+ * everything downstream sees a plain Story-id list (Story #5139). The
+ * expansion walk is sequential because it is id-by-id conditional; the Story
+ * fetch that follows stays under the bounded concurrency.
+ *
  * @param {object} provider
  * @param {number[]} ids
  * @returns {Promise<object[]>}
  */
 export async function fetchStories(provider, ids) {
-  return concurrentMap(
+  const { ids: resolvedIds, expansions } = await expandEpicIds({
     ids,
+    getTicket: (id) => provider.getTicket(id),
+    readNativeChildIds: nativeChildReader(provider),
+    warn: (m) => Logger.warn(m),
+  });
+
+  for (const { epicId, childIds } of expansions) {
+    Logger.info(
+      `[resolve-stories] Epic #${epicId} → ${childIds.length} open Story(ies): ` +
+        childIds.map((c) => `#${c}`).join(', '),
+    );
+  }
+
+  return concurrentMap(
+    resolvedIds,
     async (id) => {
       const issue = await provider.getTicket(id);
       if (!issue) {