mandrel 2.39.0 → 2.41.0

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

@@ -0,0 +1,324 @@
+/**
+ * epic-ops.js — create the optional container Epic for a plan-persist run.
+ *
+ * Story #5139. When `/mandrel-plan` authors more than two Stories it offers to
+ * group them under one container Epic. The Epic is **not** a work item: it
+ * holds a `## Goal` paragraph and a child checklist, carries `type::epic` and
+ * nothing else, and is never branched, implemented or delivered.
+ *
+ * Ordering matters — the Epic is created **after** the Stories, because its
+ * body embeds their issue numbers and its sub-issue edges need their database
+ * ids. A container that exists before its contents would have to be written
+ * twice.
+ *
+ * @module lib/orchestration/plan-persist/epic-ops
+ */
+
+import { createHash } from 'node:crypto';
+import { linkStoriesToEpic } from '../../../providers/github/sub-issue-add.js';
+import { Logger } from '../../Logger.js';
+import { LABEL_COLORS, TYPE_LABELS } from '../../label-constants.js';
+import { composeEpicBody } from '../epic-container.js';
+
+/**
+ * The Story count at or above which `/mandrel-plan` offers a container Epic.
+ *
+ * Three, i.e. "more than two" — at two Stories a pair of ids is as easy to
+ * carry as one, and the container earns nothing.
+ */
+export const EPIC_SUGGESTION_THRESHOLD = 3;
+
+/** Length of the truncated hex digest stamped into the Epic marker. */
+const EPIC_FINGERPRINT_LENGTH = 8;
+
+/** Marker prefix identifying a persist-authored Epic in an issue body. */
+const EPIC_FINGERPRINT_MARKER_PREFIX = 'mandrel-epic-fingerprint';
+
+/**
+ * Derive the Epic's resume identity from its title and the exact child set.
+ *
+ * Keyed on the children, not just the title: two runs that group *different*
+ * Stories are different containers even under the same title, and adopting
+ * one for the other would silently leave a cohort unlinked.
+ *
+ * Fields join on NUL, written as the `\u0000` escape and never as a raw byte
+ * — a literal NUL makes git classify the file binary and drop its diffs.
+ *
+ * @param {{ title: string, childIds: number[] }} opts
+ * @returns {string} Hex digest.
+ */
+function epicFingerprint({ title, childIds }) {
+  const ids = [...childIds].sort((a, b) => a - b).join(',');
+  return createHash('sha256')
+    .update(`${title}\u0000${ids}`)
+    .digest('hex')
+    .slice(0, EPIC_FINGERPRINT_LENGTH);
+}
+
+/**
+ * Render the invisible HTML-comment marker carrying the Epic's fingerprint.
+ *
+ * @param {string} fingerprint
+ * @returns {string}
+ */
+function epicFingerprintMarker(fingerprint) {
+  return `<!-- ${EPIC_FINGERPRINT_MARKER_PREFIX} ${fingerprint} -->`;
+}
+
+/**
+ * Ensure the `type::epic` label exists, **failing closed**.
+ *
+ * This is deliberately the opposite posture to the cohort and route labels
+ * (`ensurePersistLabel` in `story-ops.js`), which degrade to "create without
+ * the label" because they are cosmetic. `type::epic` is not cosmetic: it is
+ * the sole marker `isEpicTicket` reads, so an Epic created without it is not
+ * an Epic — it is a stray issue that `/mandrel-deliver` will hard-error on and
+ * no expansion will ever find. Skipping creation leaves the Stories, which
+ * are the part that matters, perfectly deliverable by id.
+ *
+ * @param {{ provider: object }} opts
+ * @returns {Promise<boolean>} Whether creation may proceed.
+ */
+async function ensureEpicLabel({ provider }) {
+  if (typeof provider?.ensureLabels !== 'function') return true;
+  try {
+    const result = await provider.ensureLabels([
+      {
+        name: TYPE_LABELS.EPIC,
+        color: LABEL_COLORS.TYPE,
+        description:
+          'Container-only grouping ticket — holds child Stories, carries no execution payload',
+      },
+    ]);
+    if (
+      Array.isArray(result?.missing) &&
+      result.missing.includes(TYPE_LABELS.EPIC)
+    ) {
+      Logger.warn(
+        `[plan-persist] "${TYPE_LABELS.EPIC}" could not be verified on the remote — ` +
+          'skipping the container Epic. The Stories are unaffected and deliver by id.',
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] "${TYPE_LABELS.EPIC}" label ensure failed (${err.message}) — ` +
+        'skipping the container Epic. The Stories are unaffected and deliver by id.',
+    );
+    return false;
+  }
+}
+
+/**
+ * Find an already-created Epic carrying this fingerprint, so a resumed
+ * persist adopts it instead of opening a second container.
+ *
+ * Non-fatal: a search failure returns `null` and the caller creates. A
+ * duplicate Epic is cosmetic; a crash mid-persist is not.
+ *
+ * @param {{ provider: object, fingerprint: string }} opts
+ * @returns {Promise<{ id: number, url?: string }|null>}
+ */
+async function findExistingEpic({ provider, fingerprint }) {
+  if (typeof provider?.listIssuesByLabel !== 'function') return null;
+  try {
+    const marker = epicFingerprintMarker(fingerprint);
+    const found = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+    const hit = (Array.isArray(found) ? found : []).find((issue) =>
+      String(issue?.body ?? '').includes(marker),
+    );
+    if (!hit) return null;
+    const id = Number(hit.number ?? hit.id);
+    if (!Number.isInteger(id) || id <= 0) return null;
+    return { id, url: hit.html_url ?? hit.url ?? undefined };
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] Epic resume lookup failed (${err.message}); creating a new container.`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Link the created Stories under the Epic as native sub-issue edges.
+ *
+ * Non-fatal by design — the body checklist is the durable mirror, and
+ * `getSubTickets` reads it as a first-class child source. A lost edge costs
+ * the GitHub UI's nesting, not the grouping itself.
+ *
+ * Exported since Story #5155 so the adoption path (`epic-adoption.js`) links
+ * children exactly the way creation does — one mirroring rule, not two that
+ * drift.
+ *
+ * @param {{ provider: object, epicNumber: number, childIds: number[] }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }|null>}
+ */
+export async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
+  if (
+    typeof provider?.getDependencyWriteContext !== 'function' ||
+    typeof provider?.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      '[plan-persist] provider exposes no getDependencyWriteContext/getTicket — ' +
+        'skipping native sub-issue edges. The Epic body checklist still lists every child.',
+    );
+    return null;
+  }
+
+  try {
+    const { gh, owner, repo } = provider.getDependencyWriteContext();
+    const summary = await linkStoriesToEpic({
+      epicNumber,
+      childIssueNumbers: childIds,
+      getTicket: (issueNumber) => provider.getTicket(issueNumber),
+      owner,
+      repo,
+      gh,
+    });
+    if (summary.failed > 0) {
+      Logger.warn(
+        `[plan-persist] ${summary.failed} sub-issue edge(s) could not be written. ` +
+          'The Epic body checklist still lists every child; add the links by hand ' +
+          'if you want them nested in the GitHub UI.',
+      );
+    } else {
+      Logger.info(
+        `[plan-persist] sub-issue edges: ${summary.added} added, ` +
+          `${summary.skipped} already present.`,
+      );
+    }
+    return summary;
+  } catch (err) {
+    Logger.warn(
+      `[plan-persist] native sub-issue mirroring failed (${err.message}) — ` +
+        'the Epic body checklist still lists every child.',
+    );
+    return null;
+  }
+}
+
+/**
+ * Create the container Epic for a persisted cohort.
+ *
+ * Returns `null` whenever no Epic was created — not requested, too few
+ * Stories, or the label could not be ensured. Callers treat `null` as the
+ * ordinary no-Epic outcome, never as a failure.
+ *
+ * **The Epic never receives an `agent::*` label.** Its labels are exactly
+ * `[type::epic]`. That absence is load-bearing: it keeps the container out
+ * of the bare `/mandrel-deliver` ready list and outside `lint-issue-body.js`,
+ * which scopes itself to `type::story`.
+ *
+ * @param {{
+ *   provider: object,
+ *   epic: { title: string, goal: string }|null,
+ *   created: Array<{ id: number, title: string }>,
+ *   opts?: { dryRun?: boolean, minStories?: number },
+ * }} args
+ * @returns {Promise<{
+ *   id: number,
+ *   title: string,
+ *   url?: string,
+ *   childIds: number[],
+ *   adopted: boolean,
+ *   edges: { added: number, skipped: number, failed: number }|null,
+ * }|null>}
+ */
+export async function createContainerEpic({
+  provider,
+  epic,
+  created,
+  opts = {},
+}) {
+  const { dryRun = false, minStories = EPIC_SUGGESTION_THRESHOLD } = opts;
+  if (!epic) return null;
+
+  const title = typeof epic.title === 'string' ? epic.title.trim() : '';
+  const goal = typeof epic.goal === 'string' ? epic.goal.trim() : '';
+  if (title === '' || goal === '') {
+    throw new Error(
+      '[plan-persist] A container Epic requires both a title and a goal.',
+    );
+  }
+
+  const childIds = (Array.isArray(created) ? created : [])
+    .map((s) => s.id)
+    .filter((id) => Number.isInteger(id) && id > 0);
+
+  // Dry-run reports the intended container write-free. `created` carries
+  // negative placeholder ids there, so `childIds` is empty by construction —
+  // report the count from `created` itself rather than from the filtered list.
+  if (dryRun) {
+    return {
+      id: -1,
+      title,
+      childIds: (Array.isArray(created) ? created : []).map((s) => s.id),
+      adopted: false,
+      edges: null,
+    };
+  }
+
+  if (childIds.length < minStories) {
+    Logger.info(
+      `[plan-persist] ${childIds.length} Story(ies) is below the ${minStories}-Story ` +
+        'Epic threshold — no container created.',
+    );
+    return null;
+  }
+
+  if (!(await ensureEpicLabel({ provider }))) return null;
+
+  const fingerprint = epicFingerprint({ title, childIds });
+  const existing = await findExistingEpic({ provider, fingerprint });
+  if (existing) {
+    Logger.info(
+      `[plan-persist] resuming: container Epic #${existing.id} already groups ` +
+        'this exact cohort — skipping create.',
+    );
+    const edges = await mirrorSubIssueEdges({
+      provider,
+      epicNumber: existing.id,
+      childIds,
+    });
+    return {
+      id: existing.id,
+      title,
+      url: existing.url,
+      childIds,
+      adopted: true,
+      edges,
+    };
+  }
+
+  const body = `${composeEpicBody({ goal, childIds })}\n${epicFingerprintMarker(fingerprint)}\n`;
+  const result = await provider.createIssue({
+    title,
+    body,
+    labels: [TYPE_LABELS.EPIC],
+  });
+
+  const epicNumber = result.number ?? result.id;
+  const edges = await mirrorSubIssueEdges({
+    provider,
+    epicNumber,
+    childIds,
+  });
+
+  Logger.info(
+    `[plan-persist] container Epic #${epicNumber} groups ${childIds.length} Story(ies): ` +
+      `deliver them all with /mandrel-deliver ${epicNumber}`,
+  );
+
+  return {
+    id: epicNumber,
+    title,
+    url: result.url,
+    childIds,
+    adopted: false,
+    edges,
+  };
+}

package/.agents/scripts/lib/orchestration/plan-persist/external-deps.js

@@ -0,0 +1,164 @@
+/**
+ * external-deps.js — `depends_on` entries that point outside this plan run.
+ *
+ * Story #5155. A `depends_on[]` entry has always been a **sibling slug**: a
+ * name resolvable only inside the `stories.json` being persisted. That makes
+ * every ordering edge intra-plan by construction, and leaves the cross-plan
+ * case — a new Story that must wait for an open Story from an earlier run —
+ * expressible only by hand-editing the issue body after persist.
+ *
+ * An entry of the form `#1234` is that missing case: an **external** blocker,
+ * already live on the tracker. The two forms are distinguished lexically and
+ * totally, so nothing has to guess:
+ *
+ *   - `some-slug` → a sibling, resolved against this run's slug map;
+ *   - `#1234`     → an existing issue, resolved against the tracker.
+ *
+ * External refs are excluded from sibling ordering and cycle detection. They
+ * cannot participate in either: a Story already open is not scheduled by this
+ * run, so it has no position in the topological sort, and it cannot close a
+ * cycle back into a Story that does not exist yet. Treating them as siblings
+ * is what would break — the unknown-slug guard would reject every one.
+ *
+ * They are validated strictly, and **before any create**: an unresolvable
+ * blocker that surfaced after the fact would leave a live Story gated on
+ * something that can never satisfy it, which the delivery engine reads as a
+ * permanent wedge rather than an error.
+ *
+ * @module lib/orchestration/plan-persist/external-deps
+ * @see Story #5155
+ */
+
+import { TYPE_LABELS } from '../../label-constants.js';
+
+/** A `depends_on` entry naming an existing issue: `#` followed by digits. */
+const EXTERNAL_REF_RE = /^#(\d+)$/;
+
+/**
+ * Is this `depends_on` entry an external issue reference?
+ *
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+export function isExternalDependencyRef(entry) {
+  return typeof entry === 'string' && EXTERNAL_REF_RE.test(entry.trim());
+}
+
+/**
+ * The issue number an external ref names, or `null` for a sibling slug.
+ *
+ * @param {unknown} entry
+ * @returns {number|null}
+ */
+export function externalDependencyId(entry) {
+  if (typeof entry !== 'string') return null;
+  const match = entry.trim().match(EXTERNAL_REF_RE);
+  if (!match) return null;
+  const id = Number.parseInt(match[1], 10);
+  return Number.isInteger(id) && id > 0 ? id : null;
+}
+
+/**
+ * Every distinct external id declared across a plan's Stories, in first-seen
+ * order.
+ *
+ * @param {Array<{ depends_on?: string[] }>} stories
+ * @returns {number[]}
+ */
+export function collectExternalDependencyIds(stories) {
+  const seen = new Set();
+  const out = [];
+  for (const story of Array.isArray(stories) ? stories : []) {
+    for (const entry of story?.depends_on ?? []) {
+      const id = externalDependencyId(entry);
+      if (id === null || seen.has(id)) continue;
+      seen.add(id);
+      out.push(id);
+    }
+  }
+  return out;
+}
+
+/**
+ * Normalize an issue's labels to plain strings.
+ *
+ * @param {unknown} raw
+ * @returns {string[]}
+ */
+function labelNames(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .filter((n) => typeof n === 'string');
+}
+
+/**
+ * Explain why one external blocker is unusable, or `null` when it is fine.
+ *
+ * @param {number} id
+ * @param {object|null} issue
+ * @returns {string|null}
+ */
+function rejectionReason(id, issue) {
+  if (!issue) return `#${id} does not exist`;
+  const state = String(issue.state ?? 'open').toLowerCase();
+  if (state !== 'open') {
+    return `#${id} is ${state} — a landed Story cannot gate new work, so the edge would never lift`;
+  }
+  const labels = labelNames(issue.labels);
+  if (labels.includes(TYPE_LABELS.EPIC)) {
+    return `#${id} is a container Epic — Epics are never delivered, so nothing would ever satisfy the edge`;
+  }
+  if (!labels.includes(TYPE_LABELS.STORY)) {
+    return `#${id} is not a ${TYPE_LABELS.STORY} — only a Story can be delivered and thereby unblock this one`;
+  }
+  return null;
+}
+
+/**
+ * Verify every external `depends_on` ref resolves to an open Story.
+ *
+ * Hard-errors listing **every** bad ref rather than the first, so an operator
+ * fixing a plan sees the whole set in one pass.
+ *
+ * @param {{ provider: object, stories: Array<{ slug: string, depends_on?: string[] }> }} args
+ * @returns {Promise<number[]>} The validated external ids (possibly empty).
+ * @throws {Error} When any ref is missing, closed, an Epic, or not a Story.
+ */
+export async function assertExternalDependenciesResolvable({
+  provider,
+  stories,
+}) {
+  const ids = collectExternalDependencyIds(stories);
+  if (ids.length === 0) return [];
+
+  if (typeof provider?.getTicket !== 'function') {
+    throw new Error(
+      '[plan-persist] provider exposes no getTicket — cannot verify the external ' +
+        `depends_on reference(s): ${ids.map((i) => `#${i}`).join(', ')}.`,
+    );
+  }
+
+  const problems = [];
+  for (const id of ids) {
+    let issue = null;
+    try {
+      issue = await provider.getTicket(id);
+    } catch (err) {
+      problems.push(`#${id} could not be read (${err?.message ?? err})`);
+      continue;
+    }
+    const reason = rejectionReason(id, issue);
+    if (reason) problems.push(reason);
+  }
+
+  if (problems.length > 0) {
+    throw new Error(
+      `[plan-persist] ${problems.length} external depends_on reference(s) cannot gate ` +
+        `this plan:\n  - ${problems.join('\n  - ')}\n\nEvery "#<id>" entry must name an ` +
+        `open ${TYPE_LABELS.STORY}. Drop the entry, or point it at a Story that is still open.`,
+    );
+  }
+
+  return ids;
+}

package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js

@@ -68,6 +68,10 @@ import {
   renderHardConflictError,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
+import {
+  resolveContainerEpic,
+  resolveCrossPlanLinks,
+} from './cross-plan-links.js';
 import {
   enforceFanOutGate,
   surfaceSoftConflictFindings,
@@ -711,6 +715,10 @@ export async function runPlanPersist({
     closeSuperseded = true,
     routeDowngradeReason = null,
     injectedRules = undefined,
+    // Story #5139 — the optional container Epic. `null` (the default) is the
+    // ordinary shape: no Epic is created unless `/mandrel-plan` offered one
+    // above the threshold and the operator confirmed it.
+    epic = null,
   } = opts;
 
   // Boundary for the plan-metrics summary below: everything this invocation
@@ -746,6 +754,14 @@ export async function runPlanPersist({
   });
   await enforceReachability(reachability, config);
 
+  // Story #5155 — the plan's outward references (`--epic <id>`, and any
+  // `#<id>` blocker) resolve BEFORE the first create, dry run included.
+  const adoptionTarget = await resolveCrossPlanLinks({
+    provider,
+    stories: rawStories,
+    epicId: opts.adoptEpicId ?? null,
+  });
+
   // Split policy + inline Spec fold (over-budget Specs fail closed — no docs/).
   const { stories } = assemblePlanStories(rawStories, {
     sharedSpec: techSpecContent,
@@ -840,6 +856,19 @@ export async function runPlanPersist({
     });
   }
 
+  // Story #5139 — the container Epic is created LAST among the writes: its
+  // body embeds the child issue numbers and its sub-issue edges need their
+  // database ids, neither of which exists until the Stories are live. It is
+  // never load-bearing, so a failure here degrades to "no container" and the
+  // Stories still deliver by id.
+  const containerEpic = await resolveContainerEpic({
+    provider,
+    adoptionTarget,
+    epic,
+    created,
+    opts: { dryRun },
+  });
+
   const supersede = await runSupersedePhase({
     provider,
     stories,
@@ -866,5 +895,6 @@ export async function runPlanPersist({
     freshness,
     waveTable,
     supersede,
+    epic: containerEpic,
   };
 }

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -34,6 +34,10 @@ import {
 } from '../../util/concurrent-map.js';
 import { assertSpecWithinBudget } from '../spec-spill.js';
 import { assertAcceptancePartition } from '../split-policy-validator.js';
+import {
+  externalDependencyId,
+  isExternalDependencyRef,
+} from './external-deps.js';
 import {
   assertSupersedePartition,
   normalizeSupersedes,
@@ -557,7 +561,9 @@ function orderStoriesByDependencies(stories) {
   const list = Array.isArray(stories) ? stories : [];
   const known = new Set(list.map((story) => story.slug));
   for (const story of list) {
-    const unknown = story.depends_on.filter((slug) => !known.has(slug));
+    const unknown = story.depends_on.filter(
+      (slug) => !isExternalDependencyRef(slug) && !known.has(slug),
+    );
     if (unknown.length > 0) {
       throw new Error(
         `[plan-persist] Story "${story.slug}" depends on unknown sibling(s): ${unknown.join(', ')}`,
@@ -568,8 +574,13 @@ function orderStoriesByDependencies(stories) {
   const scheduled = new Set();
   const pending = [...list];
   while (pending.length > 0) {
+    // External refs gate delivery, never creation order: the blocker is
+    // already live, so it can never become "scheduled" in this run and would
+    // otherwise wedge the sort into a false cycle (Story #5155).
     const index = pending.findIndex((story) =>
-      story.depends_on.every((slug) => scheduled.has(slug)),
+      story.depends_on
+        .filter((slug) => !isExternalDependencyRef(slug))
+        .every((slug) => scheduled.has(slug)),
     );
     if (index === -1) {
       throw new Error(
@@ -720,8 +731,8 @@ function warnOnDivergentSameTitleStory(story, idsByTitle) {
  * @returns {string}
  */
 function renderStoryBodyForCreate(story, idBySlug) {
-  const dependencyRefs = story.depends_on.map(
-    (slug) => `#${idBySlug.get(slug)}`,
+  const dependencyRefs = story.depends_on.map((slug) =>
+    isExternalDependencyRef(slug) ? slug.trim() : `#${idBySlug.get(slug)}`,
   );
   let base = story.body;
   if (dependencyRefs.length > 0) {
@@ -798,12 +809,22 @@ async function mirrorNativeDependencyEdges({ provider, stories, idBySlug }) {
 
   try {
     const { gh, owner, repo } = provider.getDependencyWriteContext();
+    // `applyBlockedByDependencies` resolves every entry through this one map,
+    // so an external `#<id>` ref only needs an identity entry to be mirrored
+    // by the same code path as a sibling (Story #5155).
+    const slugToIssueNumber = Object.fromEntries(idBySlug);
+    for (const story of stories) {
+      for (const entry of story.depends_on) {
+        const externalId = externalDependencyId(entry);
+        if (externalId !== null) slugToIssueNumber[entry.trim()] = externalId;
+      }
+    }
     const summary = await applyBlockedByDependencies({
       stories: stories.map((story) => ({
         slug: story.slug,
         dependsOn: story.depends_on,
       })),
-      slugToIssueNumber: Object.fromEntries(idBySlug),
+      slugToIssueNumber,
       getTicket: (issueNumber) => provider.getTicket(issueNumber),
       owner,
       repo,