mandrel 2.38.0 → 2.40.0

package/.agents/scripts/lib/label-constants.js

@@ -74,8 +74,26 @@ export function isValidTransition(fromState, toState) {
   return allowed.includes(toState);
 }
 
+/**
+ * Ticket-type axis.
+ *
+ * `STORY` is the only type carrying an execution payload — it is what
+ * `/mandrel-deliver` branches, implements and lands.
+ *
+ * `EPIC` (Story #5139) is a **pure container**: a grouping ticket that holds
+ * a `## Goal` paragraph and a child checklist and nothing else. It is never
+ * branched, never implemented, and never carries an `agent::*` label — that
+ * absence is what keeps it out of the bare `/mandrel-deliver` ready list and
+ * outside `lint-issue-body.js`, which is `type::story`-scoped.
+ *
+ * This is deliberately NOT a revival of the v1 Epic tier. Linkage runs
+ * parent→child only (the Epic body's checklist plus native sub-issue edges),
+ * so Story bodies stay untouched and the `Epic: #N` footer stays retired and
+ * refused. See ADR `20260905-container-epic` in `docs/decisions.md`.
+ */
 export const TYPE_LABELS = {
   STORY: 'type::story',
+  EPIC: 'type::epic',
 };
 
 export const STATUS_LABELS = {

package/.agents/scripts/lib/label-taxonomy.js

@@ -20,14 +20,27 @@ import {
   TYPE_LABELS,
 } from './label-constants.js';
 
+/**
+ * The ticket-type axis. Both rows share one colour, so they are derived from
+ * `[name, description]` pairs rather than restated as full literals — Story
+ * #5139 added `type::epic` here, and the derived form absorbs it without
+ * growing the file's structural weight.
+ *
+ * @type {Array<{ name: string, color: string, description: string }>}
+ */
+const TYPE_LABEL_ROWS = [
+  [TYPE_LABELS.STORY, 'Story work item'],
+  [TYPE_LABELS.EPIC, 'Container-only grouping ticket for child Stories'],
+].map(([name, description]) => ({
+  name,
+  color: LABEL_COLORS.TYPE,
+  description,
+}));
+
 /** @type {Array<{ name: string, color: string, description: string }>} */
 export const LABEL_TAXONOMY = [
   // Type
-  {
-    name: TYPE_LABELS.STORY,
-    color: LABEL_COLORS.TYPE,
-    description: 'Story work item',
-  },
+  ...TYPE_LABEL_ROWS,
 
   // Agent State
   {

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

@@ -0,0 +1,186 @@
+/**
+ * epic-container.js — the one module describing a container Epic.
+ *
+ * An Epic here is a **pure container**: a `type::epic` issue whose body is a
+ * short `## Goal` paragraph and a `- [ ] #N` child checklist, and nothing
+ * else. It carries no `## Spec`, no `acceptance[]` / `verify[]`, and no
+ * `agent::*` label. It is never branched, never implemented and never
+ * delivered — `/mandrel-deliver <epicId>` expands it to its open children and
+ * delivers those.
+ *
+ * **Linkage is parent→child only.** The Epic holds every edge; Story bodies
+ * are never touched. That is the whole reason this can exist without
+ * reversing ADR `20260726-v2-story-collapse`: the `Epic: #N` footer stays
+ * retired and every refusal that reads it still fires, so each Story remains
+ * independently deliverable and the delivery engine stays Story-only.
+ *
+ * Both consumers — `plan-persist` (which writes an Epic) and
+ * `resolve-stories` (which expands one) — import from here so the written
+ * shape and the read shape cannot drift apart.
+ *
+ * @module lib/orchestration/epic-container
+ * @see Story #5139
+ */
+
+import { TYPE_LABELS } from '../label-constants.js';
+
+/**
+ * The checklist grammar. `getSubTickets` (`providers/github/issues.js`)
+ * already parses this exact form as its strategy-2 child source, so the
+ * checklist is a durable mirror of the native sub-issue edges rather than a
+ * second, competing representation: when the sub-issues API is unavailable
+ * — an older GHES, a revoked scope, a partial write — the children are still
+ * discoverable from the body alone.
+ *
+ * Kept in sync with `_getChecklistChildren` deliberately; a divergence here
+ * would strand children the writer believes it linked.
+ */
+const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+#(\d+)\s*$/gm;
+
+/** Heading the container's one prose section renders under. */
+const GOAL_HEADING = '## Goal';
+
+/** Heading the child checklist renders under. */
+const CHILDREN_HEADING = '## Stories';
+
+/**
+ * Normalize an issue's labels to plain strings. GitHub hands labels back
+ * either as objects (`{ name }`) or, once mapped, as bare strings; callers
+ * should not have to care which shape they hold.
+ *
+ * @param {unknown} raw
+ * @returns {string[]}
+ */
+function normalizeLabels(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .filter((n) => typeof n === 'string' && n.length > 0);
+}
+
+/**
+ * Is this issue a container Epic?
+ *
+ * Reads the `type::epic` label and nothing else — the label is the
+ * authoritative marker. Body shape is deliberately NOT part of the test: a
+ * hand-edited Epic whose checklist an operator reordered or annotated is
+ * still an Epic, and treating it otherwise would silently reclassify it as
+ * an ordinary non-Story and hard-error the delivery.
+ *
+ * @param {{ labels?: unknown }} issue
+ * @returns {boolean}
+ */
+export function isEpicTicket(issue) {
+  return normalizeLabels(issue?.labels).includes(TYPE_LABELS.EPIC);
+}
+
+/**
+ * Render a container Epic's body.
+ *
+ * The output is intentionally minimal — a goal paragraph and a checklist.
+ * The Epic must carry **no information a child does not already carry**: it
+ * is a container, so anything unique living here would be a fact with no
+ * home in the tickets that actually get executed, invisible to every agent
+ * delivering them.
+ *
+ * @param {{ goal: string, childIds?: number[] }} opts
+ * @returns {string} Canonical Epic body markdown.
+ */
+export function composeEpicBody({ goal, childIds = [] } = {}) {
+  const text = typeof goal === 'string' ? goal.trim() : '';
+  if (text === '') {
+    throw new Error('[epic-container] composeEpicBody requires a goal.');
+  }
+
+  const ids = normalizeChildIds(childIds);
+  const lines = [GOAL_HEADING, '', text, '', CHILDREN_HEADING, ''];
+  if (ids.length === 0) {
+    lines.push('_No child Stories linked._');
+  } else {
+    for (const id of ids) lines.push(`- [ ] #${id}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Coerce a child-id list to positive integers, deduped, order-preserving.
+ *
+ * @param {unknown} raw
+ * @returns {number[]}
+ */
+export function normalizeChildIds(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const entry of raw) {
+    const id = Number(entry);
+    if (!Number.isInteger(id) || id <= 0) continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * Read the child issue numbers an Epic body declares.
+ *
+ * Body-only, by design: this is the fallback that works with nothing but the
+ * issue text. Callers that can reach the API should union this with the
+ * native sub-issue edges (`readEpicChildIdsFrom`), because an operator can
+ * link a child in the GitHub UI without touching the checklist.
+ *
+ * @param {string|null|undefined} body
+ * @returns {number[]}
+ */
+export function readEpicChildIds(body) {
+  if (typeof body !== 'string' || body === '') return [];
+  // `matchAll` on a /g regex starts from lastIndex; the literal is
+  // module-scoped, so reset it rather than leaking state across calls.
+  CHECKLIST_ITEM_RE.lastIndex = 0;
+  return normalizeChildIds(
+    [...body.matchAll(CHECKLIST_ITEM_RE)].map((m) => Number.parseInt(m[1], 10)),
+  );
+}
+
+/**
+ * Resolve an Epic's children from **both** sources — the body checklist and
+ * the native sub-issue edges — as one deduped list.
+ *
+ * The two are unioned rather than ranked because each can hold a child the
+ * other misses: the API is authoritative for links made in the GitHub UI,
+ * and the checklist survives an API that is unavailable or was never
+ * written. A child present in either is a child.
+ *
+ * `readNativeChildIds` is injected and may be absent or throw; a failure
+ * degrades to the checklist rather than propagating, since a body-derived
+ * child list is a strictly better answer than an error.
+ *
+ * @param {{
+ *   epic: { number?: number, id?: number, body?: string, nodeId?: string },
+ *   readNativeChildIds?: (epic: object) => Promise<number[]>,
+ *   onWarn?: (message: string) => void,
+ * }} opts
+ * @returns {Promise<number[]>}
+ */
+export async function readEpicChildIdsFrom({
+  epic,
+  readNativeChildIds,
+  onWarn,
+} = {}) {
+  const fromBody = readEpicChildIds(epic?.body);
+  if (typeof readNativeChildIds !== 'function') return fromBody;
+
+  let native = [];
+  try {
+    native = normalizeChildIds(await readNativeChildIds(epic));
+  } catch (err) {
+    const id = epic?.number ?? epic?.id ?? '?';
+    onWarn?.(
+      `[epic-container] native sub-issue read failed for Epic #${id} ` +
+        `(${err?.message ?? String(err)}); using the body checklist alone.`,
+    );
+  }
+
+  return normalizeChildIds([...native, ...fromBody]);
+}

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