mandrel 2.40.0 → 2.41.0

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

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

@@ -150,10 +150,14 @@ async function findExistingEpic({ provider, fingerprint }) {
  * `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>}
  */
-async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
+export async function mirrorSubIssueEdges({ provider, epicNumber, childIds }) {
   if (
     typeof provider?.getDependencyWriteContext !== 'function' ||
     typeof provider?.getTicket !== 'function'

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,7 +68,10 @@ import {
   renderHardConflictError,
 } from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
-import { createContainerEpic } from './epic-ops.js';
+import {
+  resolveContainerEpic,
+  resolveCrossPlanLinks,
+} from './cross-plan-links.js';
 import {
   enforceFanOutGate,
   surfaceSoftConflictFindings,
@@ -751,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,
@@ -850,8 +861,9 @@ export async function runPlanPersist({
   // 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 createContainerEpic({
+  const containerEpic = await resolveContainerEpic({
     provider,
+    adoptionTarget,
     epic,
     created,
     opts: { dryRun },

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,

package/.agents/scripts/lib/orchestration/ticket-validator.js

@@ -5,6 +5,7 @@ import { gitSpawn } from '../git-utils.js';
 
 import { Logger } from '../Logger.js';
 import { validateStoryFileAssumptions } from './file-assumptions.js';
+import { isExternalDependencyRef } from './plan-persist/external-deps.js';
 import { computeSpecBudgetFindings } from './spec-budget.js';
 import {
   assertStoryBodiesParse,
@@ -461,7 +462,13 @@ function indexTicketsBySlug(tickets) {
       }
       ticketBySlug.set(t.slug, t);
     }
-    slugAdjacency.set(t.slug, t.depends_on ?? []);
+    // External `#<id>` refs (Story #5155) name issues already on the tracker,
+    // not nodes in this run's graph — they cannot close a cycle back into a
+    // Story that does not exist yet, so they are not edges here.
+    slugAdjacency.set(
+      t.slug,
+      (t.depends_on ?? []).filter((d) => !isExternalDependencyRef(d)),
+    );
     if (t.type === 'story') stories.push(t);
   }
   return { ticketBySlug, stories, slugAdjacency };
@@ -568,6 +575,9 @@ function assertNoUnknownDeps({ tickets, ticketBySlug }) {
   const unknownDeps = [];
   for (const t of tickets) {
     for (const depSlug of t.depends_on ?? []) {
+      // An external `#<id>` ref is resolved against the tracker at persist
+      // (`assertExternalDependenciesResolvable`), never against this backlog.
+      if (isExternalDependencyRef(depSlug)) continue;
       if (!ticketBySlug.has(depSlug)) {
         unknownDeps.push({ slug: t.slug, title: t.title, dep: depSlug });
       }