mandrel 2.39.0 → 2.41.0

package/.agents/scripts/lib/orchestration/dependency-candidates.js

@@ -0,0 +1,139 @@
+/**
+ * dependency-candidates.js — open Stories a newly planned Story may need to
+ * wait for.
+ *
+ * Story #5155. `depends_on[]` has always ordered *siblings within one plan*.
+ * Nothing surfaced the other ordering that actually bites: a Story authored
+ * today that edits a file an already-open Story from an earlier plan is going
+ * to rewrite. Delivered concurrently, the second lands on a base the first
+ * just changed — and the planner had no way to see it coming, because the
+ * duplicate search asks "is this the same Story?" (title/body similarity),
+ * never "does this Story touch what I am about to touch?".
+ *
+ * Overlap here is therefore computed on **declared footprints**, not prose:
+ * the seed's `predictedPaths` against each open Story's parsed `changes[]`,
+ * via the same `storyFootprint` the wave runner uses to withhold colliding
+ * Stories at dispatch. That is deliberate — the planner sees the collision the
+ * runtime would later enforce, one layer earlier and while it is still cheap
+ * to order around.
+ *
+ * The result is **advisory**: an overlap is a prompt to consider an edge, not
+ * proof one is needed. Two Stories can touch a shared barrel file with no real
+ * ordering between them; only the operator knows.
+ *
+ * @module lib/orchestration/dependency-candidates
+ * @see Story #5155
+ */
+
+import { Logger } from '../Logger.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { parse as parseStoryBody } from '../story-body/story-body.js';
+import { storyFootprint } from '../wave-runner/footprint.js';
+
+/**
+ * Build an issue URL for a Story the provider returned without one.
+ *
+ * @param {number} id
+ * @param {{ owner?: string, repo?: string }} [opts]
+ * @returns {string}
+ */
+function buildStoryUrl(id, { owner, repo } = {}) {
+  if (owner && repo) return `https://github.com/${owner}/${repo}/issues/${id}`;
+  return `#${id}`;
+}
+
+/**
+ * Read one open Story's declared footprint.
+ *
+ * Total by construction: an unparseable body yields an empty footprint, which
+ * intersects with nothing and drops the Story from the candidate list. A
+ * hand-written Story with no `## Changes` section is exactly that case, and it
+ * is the right outcome — there is no declared footprint to collide with.
+ *
+ * @param {object} issue
+ * @returns {Set<string>}
+ */
+function footprintOf(issue) {
+  const body = typeof issue?.body === 'string' ? issue.body : '';
+  if (body === '') return new Set();
+  try {
+    return storyFootprint(parseStoryBody(body).body);
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Find open Stories whose declared footprint intersects the seed's predicted
+ * paths.
+ *
+ * Returns `[]` **without contacting the provider** when the seed named no
+ * paths: with nothing to intersect, every candidate would score empty, and the
+ * round-trip would buy nothing. That short-circuit is load-bearing for the
+ * common one-line seed, which mentions no file at all.
+ *
+ * @param {{
+ *   predictedPaths: string[],
+ *   provider: object,
+ *   owner?: string,
+ *   repo?: string,
+ *   excludeIds?: Iterable<number|string>,
+ * }} args
+ * @returns {Promise<Array<{ id: number, title: string, url: string, state: string, overlappingPaths: string[] }>>}
+ */
+export async function findDependencyCandidates({
+  predictedPaths,
+  provider,
+  owner,
+  repo,
+  excludeIds = [],
+}) {
+  const wanted = (Array.isArray(predictedPaths) ? predictedPaths : []).filter(
+    (p) => typeof p === 'string' && p.trim() !== '',
+  );
+  if (wanted.length === 0) return [];
+  if (typeof provider?.listIssuesByLabel !== 'function') return [];
+
+  const excluded = new Set(
+    [...excludeIds].map((id) => Number(id)).filter((n) => Number.isFinite(n)),
+  );
+
+  let issues;
+  try {
+    issues = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.STORY,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[dependency-candidates] open-Story listing degraded to no candidates: ${err?.message ?? err}`,
+    );
+    return [];
+  }
+
+  const out = [];
+  for (const issue of Array.isArray(issues) ? issues : []) {
+    const id = Number(issue?.number ?? issue?.id);
+    if (!Number.isInteger(id) || id <= 0 || excluded.has(id)) continue;
+
+    const footprint = footprintOf(issue);
+    if (footprint.size === 0) continue;
+
+    const overlappingPaths = wanted.filter((p) => footprint.has(p));
+    if (overlappingPaths.length === 0) continue;
+
+    out.push({
+      id,
+      title: typeof issue?.title === 'string' ? issue.title : '',
+      url: issue?.html_url ?? issue?.url ?? buildStoryUrl(id, { owner, repo }),
+      state: typeof issue?.state === 'string' ? issue.state : 'open',
+      overlappingPaths,
+    });
+  }
+
+  // Most-entangled first, then ascending id for a stable render.
+  return out.sort(
+    (a, b) =>
+      b.overlappingPaths.length - a.overlappingPaths.length || a.id - b.id,
+  );
+}

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

@@ -0,0 +1,159 @@
+/**
+ * epic-candidates.js — rank the open container Epics a new plan could join.
+ *
+ * Story #5155. `plan-persist` has always been able to *create* a container
+ * Epic, and to re-adopt one whose fingerprint matches the exact cohort it is
+ * re-persisting. Neither helps the case this module exists for: a second plan,
+ * days later, adding work that belongs under the Epic a first plan opened. The
+ * fingerprint is keyed on the child set, so a different cohort never matches
+ * it — by design, since adopting the wrong container silently mis-files a run.
+ *
+ * So the join has to be a **decision**, not a hash collision: this module
+ * surfaces every open Epic with an overlap score, and the operator picks at
+ * Gate #3. The list is deliberately **complete rather than thresholded** — a
+ * low score is evidence for the operator to weigh, and hiding a candidate is
+ * how a plan silently opens its second container for one body of work.
+ *
+ * Scoring reuses `duplicate-search.js`'s tokenizer and Jaccard overlap rather
+ * than growing a second similarity notion in the codebase; like that module's,
+ * it is a triage signal and not a semantic search.
+ *
+ * @module lib/orchestration/epic-candidates
+ * @see Story #5155
+ */
+
+import { overlapScore, tokenize } from '../duplicate-search.js';
+import { Logger } from '../Logger.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { concurrentMap, FANOUT_CONCURRENCY } from '../util/concurrent-map.js';
+import { isEpicTicket, readEpicChildIds } from './epic-container.js';
+
+/**
+ * Build an issue URL for an Epic the provider returned without one.
+ *
+ * @param {number} id
+ * @param {{ owner?: string, repo?: string }} [opts]
+ * @returns {string}
+ */
+function buildEpicUrl(id, { owner, repo } = {}) {
+  if (owner && repo) return `https://github.com/${owner}/${repo}/issues/${id}`;
+  return `#${id}`;
+}
+
+/**
+ * Fetch the titles of an Epic's children, for scoring only.
+ *
+ * Child titles matter because a container's own title and goal are short and
+ * abstract ("Auth hardening", one paragraph), while the seed that should match
+ * it is concrete. The children are where the shared vocabulary actually lives.
+ *
+ * Entirely best-effort: no `getTicket`, an unreadable child, or a throw all
+ * degrade to fewer title tokens, never to a failed envelope. A candidate that
+ * scores low because its children could not be read is still *listed* — the
+ * operator sees every open Epic regardless.
+ *
+ * @param {{ childIds: number[], provider: object }} opts
+ * @returns {Promise<string>} Space-joined child titles ('' when none resolved).
+ */
+async function readChildTitles({ childIds, provider }) {
+  if (childIds.length === 0 || typeof provider?.getTicket !== 'function') {
+    return '';
+  }
+  const titles = await concurrentMap(
+    childIds,
+    async (id) => {
+      try {
+        const child = await provider.getTicket(id);
+        return typeof child?.title === 'string' ? child.title : '';
+      } catch {
+        return '';
+      }
+    },
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+  return titles.filter((t) => t !== '').join(' ');
+}
+
+/**
+ * Score one open Epic against the seed.
+ *
+ * @param {{ epic: object, seedTokens: Set<string>, provider: object, owner?: string, repo?: string }} opts
+ * @returns {Promise<{ id: number, title: string, url: string, score: number, childIds: number[] }|null>}
+ */
+async function scoreEpic({ epic, seedTokens, provider, owner, repo }) {
+  const id = Number(epic?.number ?? epic?.id);
+  if (!Number.isInteger(id) || id <= 0) return null;
+
+  const title = typeof epic?.title === 'string' ? epic.title : '';
+  const body = typeof epic?.body === 'string' ? epic.body : '';
+  const childIds = readEpicChildIds(body);
+  const childTitles = await readChildTitles({ childIds, provider });
+
+  // The fingerprint marker and checklist ids are machine noise; the tokenizer
+  // drops short and non-alphabetic tokens, so the corpus is effectively the
+  // title, the `## Goal` prose and the child titles.
+  const corpus = `${title}\n${body}\n${childTitles}`;
+  const score = overlapScore(seedTokens, tokenize(corpus));
+
+  return {
+    id,
+    title,
+    url: epic?.html_url ?? epic?.url ?? buildEpicUrl(id, { owner, repo }),
+    score: Number(score.toFixed(4)),
+    childIds,
+  };
+}
+
+/**
+ * Find every open container Epic, ranked by overlap with the seed.
+ *
+ * **Only open Epics are candidates.** A closed Epic is a completed body of
+ * work; joining one would reopen a container the epilogue deliberately closed,
+ * and silently re-scope a finished plan. The operator files a new Epic or
+ * reopens the old one by hand.
+ *
+ * Failures degrade to `[]` — like the duplicate search, this is a triage
+ * signal offered at a gate, and no plan should fail to be authored because
+ * the Epic listing was unavailable.
+ *
+ * @param {{
+ *   seed: string,
+ *   provider: object,
+ *   owner?: string,
+ *   repo?: string,
+ * }} args
+ * @returns {Promise<Array<{ id: number, title: string, url: string, score: number, childIds: number[] }>>}
+ */
+export async function findOpenEpicCandidates({ seed, provider, owner, repo }) {
+  if (typeof seed !== 'string' || seed.trim() === '') return [];
+  if (typeof provider?.listIssuesByLabel !== 'function') return [];
+
+  const seedTokens = tokenize(seed);
+  if (seedTokens.size === 0) return [];
+
+  let issues;
+  try {
+    issues = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.EPIC,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[epic-candidates] open-Epic listing degraded to no candidates: ${err?.message ?? err}`,
+    );
+    return [];
+  }
+
+  const epics = (Array.isArray(issues) ? issues : []).filter(isEpicTicket);
+  const scored = await concurrentMap(
+    epics,
+    (epic) => scoreEpic({ epic, seedTokens, provider, owner, repo }),
+    { concurrency: FANOUT_CONCURRENCY },
+  );
+
+  // Descending score, then ascending id: a stable order for two Epics that
+  // tie, so the same backlog always renders the same list.
+  return scored
+    .filter((c) => c !== null)
+    .sort((a, b) => b.score - a.score || a.id - b.id);
+}

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

@@ -0,0 +1,103 @@
+/**
+ * epic-checklist.js — edit a live Epic body's child checklist in place.
+ *
+ * Story #5155. `epic-container.js` describes the *shape* of a container and
+ * renders one from scratch; this module is the other operation adoption needs
+ * — amending a body that already exists, written by someone else, possibly
+ * hand-edited since.
+ *
+ * The two are deliberately separate. Composing may assume everything about the
+ * text because it produced all of it; amending may assume almost nothing and
+ * must treat every line it did not come to change as untouchable: the `## Goal`
+ * prose, the fingerprint marker, the item order, and above all the **checked
+ * state** of existing rows. An operator who ticked `- [x] #41` is recording
+ * that the Story landed, and a re-render would silently discard it.
+ *
+ * So the edit is a surgical line insertion rather than a re-render.
+ *
+ * @module lib/orchestration/epic-checklist
+ * @see Story #5155
+ */
+
+import {
+  CHECKLIST_ITEM_LINE_RE,
+  CHILDREN_HEADING,
+  NO_CHILDREN_PLACEHOLDER,
+  normalizeChildIds,
+  readEpicChildIds,
+} from './epic-container.js';
+
+/**
+ * Index of the last `- [ ] #N` row in a body's lines, or -1.
+ *
+ * @param {string[]} lines
+ * @returns {number}
+ */
+function findLastChecklistIndex(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (CHECKLIST_ITEM_LINE_RE.test(lines[i])) return i;
+  }
+  return -1;
+}
+
+/**
+ * Where the new rows go, as a `[index, deleteCount]` splice target.
+ *
+ * Three placements, in priority order, each preserving a different thing:
+ * replacing the empty-container placeholder (which would otherwise stand above
+ * rows that contradict it), appending after the last existing row (which keeps
+ * original-then-appended order on read-back), or opening the section for a body
+ * that never had one.
+ *
+ * @param {string[]} lines
+ * @returns {[number, number]|null} `null` when there is no section to extend.
+ */
+function locateInsertion(lines) {
+  const placeholderAt = lines.findIndex(
+    (line) => line.trim() === NO_CHILDREN_PLACEHOLDER,
+  );
+  if (placeholderAt !== -1) return [placeholderAt, 1];
+
+  const lastItemAt = findLastChecklistIndex(lines);
+  if (lastItemAt !== -1) return [lastItemAt + 1, 0];
+
+  const headingAt = lines.findIndex((line) => line.trim() === CHILDREN_HEADING);
+  if (headingAt === -1) return null;
+  // Keep the blank line a composed body puts under the heading.
+  const blank = lines[headingAt + 1]?.trim() === '' ? 1 : 0;
+  return [headingAt + 1 + blank, 0];
+}
+
+/**
+ * Append child ids to an existing Epic body's checklist, idempotently.
+ *
+ * Idempotence is the load-bearing property: a resumed or re-run persist calls
+ * this again with the same cohort, and a second copy of every row would make
+ * the container claim children it does not have.
+ *
+ * @param {string} body The Epic's current body.
+ * @param {number[]} childIds Ids to add.
+ * @returns {string} The updated body (byte-identical when nothing was added).
+ */
+export function appendEpicChildIds(body, childIds) {
+  const text = typeof body === 'string' ? body : '';
+  const existing = new Set(readEpicChildIds(text));
+  const additions = normalizeChildIds(childIds).filter(
+    (id) => !existing.has(id),
+  );
+  if (additions.length === 0) return text;
+
+  const rows = additions.map((id) => `- [ ] #${id}`);
+  const lines = text.split('\n');
+  const target = locateInsertion(lines);
+
+  if (target === null) {
+    // A hand-written or foreign Epic with no checklist section. Add one rather
+    // than refusing: `isEpicTicket` already treats such a ticket as a real
+    // Epic, so the adoption must not be the one place that disagrees.
+    return `${text.replace(/\n+$/, '')}\n\n${CHILDREN_HEADING}\n\n${rows.join('\n')}\n`;
+  }
+
+  lines.splice(target[0], target[1], ...rows);
+  return lines.join('\n');
+}

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

@@ -0,0 +1,202 @@
+/**
+ * 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;
+
+/**
+ * The same grammar, unanchored to a global cursor — for callers testing one
+ * line at a time. Kept beside its `/g` twin so the two cannot drift.
+ */
+export const CHECKLIST_ITEM_LINE_RE = /^-\s*\[[ xX]\]\s+#\d+\s*$/;
+
+/** Heading the container's one prose section renders under. */
+const GOAL_HEADING = '## Goal';
+
+/** Heading the child checklist renders under. */
+export const CHILDREN_HEADING = '## Stories';
+
+/**
+ * Rendered in place of the checklist when a container has no children yet.
+ *
+ * Exported because {@link appendEpicChildIds} must *remove* it when the first
+ * child arrives: a container that lists a Story and still claims to be empty
+ * is a body that contradicts itself, and the two writers have to agree on the
+ * exact string to keep that from happening.
+ */
+export const NO_CHILDREN_PLACEHOLDER = '_No child Stories linked._';
+
+/**
+ * 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_CHILDREN_PLACEHOLDER);
+  } 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]);
+}