mandrel 2.60.0 → 2.61.0

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

@@ -1,88 +1,44 @@
 /**
- * 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.
- *
- * **The container's lifecycle is derived, never labelled.** It still carries
- * no `agent::*` label — that absence is what keeps it out of the bare
- * `/mandrel-deliver` ready list and outside `lint-issue-body.js`. What it does
- * carry is a Projects v2 Status column, an owner while its children run, and
- * eventually a closed state, all computed from the children by
- * `epic-rollup.js` and written directly (Story #5205). Deriving rather than
- * labelling is the whole reason those two facts can coexist.
+ * epic-container.js — the one module describing a container Epic: a
+ * `type::epic` issue whose body is a `## Goal` paragraph and a `- [ ] #N`
+ * child checklist. Never delivered itself; `/mandrel-deliver <epicId>`
+ * expands it. Linkage is parent→child only (Story bodies are never touched),
+ * and its board state is derived by `epic-rollup.js`, never labelled.
+ * `plan-persist` writes and `resolve-stories` reads through here so the
+ * shapes cannot drift.
  *
  * @module lib/orchestration/epic-container
- * @see Story #5139
  */
 
 import { TYPE_LABELS } from '../label-constants.js';
 
 /**
- * The checklist grammar: a checklist row, and the **first** issue reference
- * anywhere on it. 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 rate-limit burst) the
- * children are still discoverable from the body alone.
- *
- * Deliberately the **loosest** of the three grammars that read this shape, and
- * looser than it was: it used to require the id to be the whole row
- * (`- [ ] #123`), which matched none of the annotated rows a hand-maintained
- * rollout tracker actually carries — `- [ ] Design sign-off (#1897): pending`,
- * `- [ ] 1.4 #1909 (Part B blocked)`. An Epic with 58 children presented three
- * to the rollup, which closed it with 23 still open (Story #5210).
- *
- * It is NOT in sync with `_getChecklistChildren` (`providers/github/issues.js`)
- * and no longer claims to be: that one is a general parent→child strategy for
- * any issue and still requires `#N` immediately after the checkbox. Reading a
- * superset here is safe in the direction that matters — a spurious id costs a
- * skipped non-Story child, while a missed id costs a container closed over open
- * work. The union with the native edges keeps both honest, and after #5210
- * nothing irreversible is decided on this grammar alone.
+ * A checklist row and the first `#N` anywhere on it — deliberately loose so
+ * annotated hand-maintained rows (`- [ ] Design (#N): pending`) count.
+ * Looser than `_getChecklistChildren` in `providers/github/issues.js` on
+ * purpose: a spurious id costs a skipped child, a missed id could close a
+ * container over open work.
  */
 const CHECKLIST_ITEM_RE = /^-\s*\[[ xX]\]\s+.*?#(\d+)\b/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; the pair
- * MUST accept the same line set, which `epic-container.test.js` pins.
+ * Single-line twin of {@link CHECKLIST_ITEM_RE}; the pair MUST accept the
+ * same lines (pinned by `epic-container.test.js`).
  */
 export const CHECKLIST_ITEM_LINE_RE = /^-\s*\[[ xX]\]\s+.*?#\d+\b/;
 
-/** 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.
+ * Empty-checklist placeholder; exported so {@link appendEpicChildIds} can
+ * remove it when the first child arrives.
  */
 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.
+ * Labels arrive as `{ name }` objects or bare strings.
  *
  * @param {unknown} raw
  * @returns {string[]}
@@ -95,13 +51,8 @@ function normalizeLabels(raw) {
 }
 
 /**
- * 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.
+ * The `type::epic` label alone decides; body shape must not, or a
+ * hand-edited Epic would be reclassified and hard-error delivery.
  *
  * @param {{ labels?: unknown }} issue
  * @returns {boolean}
@@ -111,28 +62,9 @@ export function isEpicTicket(issue) {
 }
 
 /**
- * Resolve the GraphQL node id an Epic's native sub-issue read addresses it by.
- *
- * Both casings are accepted because the field name depends on which provider
- * method produced the object, and neither caller can tell from the value it
- * holds: `getTicket` (and every other single-issue read) runs through
- * `issueToTicket`, which renames `node_id` to `nodeId`, while
- * `listIssuesByLabel` returns the REST payload **verbatim** — six consumers
- * read its raw shape, so mapping it there would be a far wider change than
- * the two reads that actually need the id.
- *
- * Returns `null` when neither name carries one. That is the load-bearing
- * half: an absent id reaches GraphQL as `$id: ID!` = `undefined`, which the
- * API rejects and `classifyGithubError` calls `permanent` — so the gateway
- * rethrows with no retry and no feature-disabled fallback, and the caller
- * degrades to the body checklist while reporting a hard API failure it never
- * really had. Callers skip the read on a `null` instead, the same clean
- * no-op `providers/github/board-add.js` makes with `reason: 'no-node-id'`.
- *
- * Module-private since the reader that consumes it moved here: `nativeChildReader`
- * below is the only production caller, and exporting a helper nothing outside
- * imports fails the production dead-export gate. Its behaviour is pinned
- * through that reader.
+ * GraphQL node id: `nodeId` on mapped tickets, `node_id` on raw REST
+ * payloads. `null` when absent — callers must skip the read, since an
+ * undefined `ID!` is classified `permanent` and reported as a hard failure.
  *
  * @param {{ nodeId?: unknown, node_id?: unknown }} epic
  * @returns {string|null}
@@ -143,26 +75,9 @@ function resolveEpicNodeId(epic) {
 }
 
 /**
- * Read an Epic's native sub-issue children as issue numbers.
- *
- * The **one** definition, injected into `readEpicChildIdsFrom` by both the
- * delivery expansion (`resolve-stories.js`) and the rollup
- * (`epic-rollup.js`). It lived in each of them as a private copy, and the two
- * copies are exactly the pair that must not drift: if the expansion sees a
- * child the rollup does not, an Epic becomes expandable but permanently
- * unclosable — the Story #5210 failure, arrived at from the other direction.
- * Sharing the reader makes that class of divergence unrepresentable.
- *
- * It lives *here*, in the module that already describes what a container Epic
- * is, rather than in either consumer: `resolve-stories.js` is a CLI entrypoint
- * and importing one from the lib layer would invert the dependency direction.
- * The provider is a parameter, so this module stays provider-agnostic.
- *
- * `resolveEpicNodeId` is what makes the two callers agree on the *id* as well
- * as the reader: an Epic reached through a mapped read carries `nodeId`, one
- * read raw from REST carries `node_id`, and neither caller can tell from the
- * value it holds. A missing id yields `[]` rather than an `undefined` reaching
- * GraphQL as a rejected `ID!`.
+ * The single native sub-issue reader shared by delivery expansion and the
+ * rollup: if they diverged, an Epic could be expandable but never closable.
+ * Missing node id yields `[]`.
  *
  * @param {object} provider
  * @returns {(epic: object) => Promise<number[]>}
@@ -171,30 +86,18 @@ export function nativeChildReader(provider) {
   return async (epic) => {
     const nodeId = resolveEpicNodeId(epic);
     if (nodeId === null) return [];
-    // The declared port first, the legacy private alias second: both forward
-    // to the same gateway on the live provider, and the fallback is what keeps
-    // test doubles written against the older name working.
+    // Legacy private alias kept for older test doubles.
     const read =
       provider?.getNativeSubIssues ?? provider?._getNativeSubIssues ?? null;
     if (typeof read !== 'function') return [];
-    // Diagnostics-only second argument, and the one place the two shapes are
-    // still read together on purpose: this module is the declared bridge
-    // between them (see `resolveEpicNodeId` above), and the expression is
-    // correct under both — a raw REST issue names the issue number `number`,
-    // a mapped ticket names it `id`. Every *consumer* module now receives one
-    // declared shape and reads the field directly.
+    // Diagnostics only: REST names the number `number`, mapped tickets `id`.
     return (await read.call(provider, nodeId, epic?.number ?? epic?.id)) ?? [];
   };
 }
 
 /**
- * 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.
+ * Render a container Epic's body. It must carry nothing its children do
+ * not, or that fact would be invisible to the agents delivering them.
  *
  * @param {{ goal: string, childIds?: number[] }} opts
  * @returns {string} Canonical Epic body markdown.
@@ -216,7 +119,7 @@ export function composeEpicBody({ goal, childIds = [] } = {}) {
 }
 
 /**
- * Coerce a child-id list to positive integers, deduped, order-preserving.
+ * Positive integers, deduped, order-preserving.
  *
  * @param {unknown} raw
  * @returns {number[]}
@@ -236,20 +139,15 @@ export function normalizeChildIds(raw) {
 }
 
 /**
- * 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.
+ * Child ids from the body checklist alone; API-capable callers should use
+ * {@link readEpicChildIdsFrom}, since UI links bypass 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.
+  // Module-scoped /g regex: reset lastIndex so state does not leak.
   CHECKLIST_ITEM_RE.lastIndex = 0;
   return normalizeChildIds(
     [...body.matchAll(CHECKLIST_ITEM_RE)].map((m) => Number.parseInt(m[1], 10)),
@@ -257,38 +155,14 @@ export function readEpicChildIds(body) {
 }
 
 /**
- * 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.
- *
- * **The degrade is reported, not hidden.** The result carries
- * `nativeReadFailed`, because a truncated list and a genuinely small Epic are
- * otherwise indistinguishable downstream — and one caller
- * (`epic-rollup.js`) decides an irreversible close on the difference. A caller
- * that only needs "who are the children" reads `ids` and ignores the flag;
- * a caller about to do something it cannot undo MUST NOT.
- *
- * `nativeReadFailed` is false when no reader was injected: a caller that
- * supplied none never asked for authority and is not degraded relative to what
- * it requested.
- *
- * **`bodyOnlyIds` names the ids the union owes to the checklist alone.** The
- * two sources are not equally trustworthy about a *single* id: a native edge
- * is a link the backend holds, so an id it returns names a real issue, while a
- * checklist row is hand-editable prose and can cite an issue that was deleted,
- * transferred, or simply mistyped. Callers that must decide what an
- * unresolvable id means need to know which source vouched for it — a native id
- * that will not resolve is a failed read, a body-only one is a typo. Empty
- * when the native read failed or never ran: with no authoritative source to
- * contrast against, nothing is "body-only" in the sense that matters.
+ * Union of body checklist and native sub-issue edges; each can hold a child
+ * the other misses. A native read failure degrades to the checklist but sets
+ * `nativeReadFailed` — a caller about to do something irreversible (close)
+ * MUST honour it. It is false when no reader was injected.
+ *
+ * `bodyOnlyIds` are ids only the hand-editable checklist vouches for: an
+ * unresolvable one is a typo, while an unresolvable native id is a failed
+ * read. Empty when the native read failed or never ran.
  *
  * @param {{
  *   epic: { number?: number, id?: number, body?: string, nodeId?: string },

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

@@ -1,10 +1,6 @@
 /**
- * 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.
+ * epic-expansion.js — turn a container-Epic id into the open Story ids under
+ * it; runs strictly before Story resolution.
  *
  * @module lib/orchestration/epic-expansion
  */
@@ -14,8 +10,6 @@ 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}
  */
@@ -28,11 +22,8 @@ function isStoryTicket(issue) {
 }
 
 /**
- * The error for an Epic that yielded no children.
- *
- * The two empty cases have different remedies, so they get different messages:
- * an operator told to go link Stories that are already linked will do the wrong
- * thing for what was really a transient API failure (Story #5210).
+ * A degraded read and a truly empty Epic need different remedies, so they
+ * get different messages.
  *
  * @param {number} id
  * @param {boolean} nativeReadFailed
@@ -54,33 +45,12 @@ function noChildrenError(id, nativeReadFailed) {
 }
 
 /**
- * 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.
+ * Expand container-Epic ids to their open child Stories (deduped, first-seen
+ * order; other ids pass through), so everything downstream sees only Story
+ * ids. Closed/done children are dropped (dependents treat them as satisfied
+ * foreign blockers); non-Story children are dropped with a warning, since a
+ * stray link must not wedge the run. Expanding to nothing is an error, never
+ * a silent no-op.
  *
  * @param {{
  *   ids: number[],