mandrel 2.59.0 → 2.61.0

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

@@ -1,15 +1,7 @@
 /**
- * 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.
+ * The optional container Epic: a goal plus a child checklist, never
+ * delivered. Created after the Stories, since it embeds their numbers and
+ * database ids.
  *
  * @module lib/orchestration/plan-persist/epic-ops
  */
@@ -21,32 +13,22 @@ 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.
- */
+/** Story count at which `/mandrel-plan` offers a container Epic. */
 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.
+ * Resume identity over title and the exact child set — a different cohort
+ * under the same title is a different container.
  *
  * 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.
+ * @returns {string}
  */
 function epicFingerprint({ title, childIds }) {
   const ids = [...childIds].sort((a, b) => a - b).join(',');
@@ -57,8 +39,6 @@ function epicFingerprint({ title, childIds }) {
 }
 
 /**
- * Render the invisible HTML-comment marker carrying the Epic's fingerprint.
- *
  * @param {string} fingerprint
  * @returns {string}
  */
@@ -67,15 +47,9 @@ function epicFingerprintMarker(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.
+ * Fails closed, unlike the cosmetic cohort label: `type::epic` is the sole
+ * Epic marker, so an Epic without it is a stray issue. Skipping leaves the
+ * Stories deliverable by id.
  *
  * @param {{ provider: object }} opts
  * @returns {Promise<boolean>} Whether creation may proceed.
@@ -113,11 +87,8 @@ async function ensureEpicLabel({ provider }) {
 }
 
 /**
- * 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.
+ * Non-fatal: a failed lookup returns `null` and the caller creates — a
+ * duplicate Epic is cosmetic, a mid-persist crash is not.
  *
  * @param {{ provider: object, fingerprint: string }} opts
  * @returns {Promise<{ id: number, url?: string }|null>}
@@ -134,9 +105,7 @@ async function findExistingEpic({ provider, fingerprint }) {
       String(issue?.body ?? '').includes(marker),
     );
     if (!hit) return null;
-    // The declared ticket shape: `id` is the issue number. The `number`-then-
-    // `id` fallback this replaced would have adopted the resumed container by
-    // database id — a number that exists, resolves to nothing, fails no guard.
+    // `id` is the issue number here; never fall back to a database id.
     const id = Number(hit.id);
     if (!Number.isInteger(id) || id <= 0) return null;
     return { id, url: hit.url ?? undefined };
@@ -149,11 +118,8 @@ async function findExistingEpic({ provider, fingerprint }) {
 }
 
 /**
- * Index a cohort's already-known database ids by issue number.
- *
- * A resumed run's adopted Stories carry no `internalId` — they were found by
- * listing, not created — so they are simply absent from the map and fall
- * through to the lookup. Absence means "not known here", never "has none".
+ * Known database ids by issue number. Adopted Stories are absent (they carry
+ * no `internalId`) and fall through to a lookup.
  *
  * @param {Array<{ id?: number, internalId?: number }>|undefined} created
  * @returns {Map<number, number>}
@@ -169,18 +135,9 @@ function internalIdsFrom(created) {
 }
 
 /**
- * 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.
- *
- * `created` is optional and carries the cohort's `createIssue` responses, so
- * the linker can skip the id lookup for every child this run made itself.
+ * Native sub-issue edges, shared with the adoption path. Non-fatal: the body
+ * checklist is the durable child source. `created` lets the linker skip the
+ * id lookup for children this run made.
  *
  * @param {{ provider: object, epicNumber: number, childIds: number[], created?: Array<{ id: number, internalId?: number }> }} opts
  * @returns {Promise<{ added: number, skipped: number, failed: number }|null>}
@@ -236,16 +193,8 @@ export async function mirrorSubIssueEdges({
 }
 
 /**
- * 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`.
+ * `null` is the ordinary no-Epic outcome, never a failure. Labels are exactly
+ * `[type::epic]` — no `agent::*`, which keeps it out of the deliver ready list.
  *
  * @param {{
  *   provider: object,
@@ -283,9 +232,7 @@ export async function createContainerEpic({
     .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.
+  // Dry-run ids are negative placeholders, so report from `created` itself.
   if (dryRun) {
     return {
       id: -1,
@@ -336,8 +283,6 @@ export async function createContainerEpic({
     labels: [TYPE_LABELS.EPIC],
   });
 
-  // `createIssue` declares both `id` and `number` and sets them to the same
-  // issue number; reading one of them is the whole contract.
   const epicNumber = result.id;
   const edges = await mirrorSubIssueEdges({
     provider,

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

@@ -1,42 +1,17 @@
 /**
- * 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.
+ * `depends_on` entries naming an existing issue (`#<id>`) rather than a
+ * sibling slug. They take no part in sibling ordering or cycle detection, and
+ * are validated before any create — an unresolvable blocker on a live Story
+ * reads to delivery as a permanent wedge, not 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}
  */
@@ -45,8 +20,6 @@ export function isExternalDependencyRef(entry) {
 }
 
 /**
- * The issue number an external ref names, or `null` for a sibling slug.
- *
  * @param {unknown} entry
  * @returns {number|null}
  */
@@ -59,9 +32,6 @@ export function externalDependencyId(entry) {
 }
 
 /**
- * Every distinct external id declared across a plan's Stories, in first-seen
- * order.
- *
  * @param {Array<{ depends_on?: string[] }>} stories
  * @returns {number[]}
  */
@@ -80,8 +50,6 @@ export function collectExternalDependencyIds(stories) {
 }
 
 /**
- * Normalize an issue's labels to plain strings.
- *
  * @param {unknown} raw
  * @returns {string[]}
  */
@@ -93,8 +61,6 @@ function labelNames(raw) {
 }
 
 /**
- * Explain why one external blocker is unusable, or `null` when it is fine.
- *
  * @param {number} id
  * @param {object|null} issue
  * @returns {string|null}
@@ -116,13 +82,10 @@ function rejectionReason(id, issue) {
 }
 
 /**
- * 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.
+ * Every external ref must be an open Story; the error lists every bad ref.
  *
  * @param {{ provider: object, stories: Array<{ slug: string, depends_on?: string[] }> }} args
- * @returns {Promise<number[]>} The validated external ids (possibly empty).
+ * @returns {Promise<number[]>}
  * @throws {Error} When any ref is missing, closed, an Epic, or not a Story.
  */
 export async function assertExternalDependenciesResolvable({

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

@@ -1,23 +1,5 @@
 /**
- * persist-helpers.js — pure helper surface for the flat Story `/mandrel-plan` persist.
- *
- * Exports:
- *   - `resolveBaseBranchRef(config)` — the one place the persist gates learn
- *     which branch name the operator configured.
- *
- * The ref the probes read is resolved per checkout (`resolveProbeRef`): the
- * local branch when it exists, else its `origin/` tracking ref (a PR
- * checkout on CI has no local `main`), else nothing — a shallow checkout
- * with no base at all skips the probes instead of reading every path as
- * absent.
- *   - `validateTickets(tickets, config, opts)` — normalises the authored
- *     `acceptance[]` handles and repairs the mechanical `changes[]`
- *     formalities against the base branch, then runs the cross-link,
- *     freshness, and task-body validators in one pass.
- *
- * Story #5312 deleted the fan-out probe that lived here: the delete
- * blast-radius count never refused a real plan, and the `git grep` it paid
- * for on every persist bought a warning nobody acted on.
+ * Base-branch resolution and the repair-then-validate pass for plan persist.
  *
  * @module lib/orchestration/plan-persist/persist-helpers
  */
@@ -29,20 +11,10 @@ import { normalizeAcceptanceHandles } from './acceptance-handle-repair.js';
 import { repairChangeEntries } from './changes-repair.js';
 
 /**
- * Resolve the ref the persist gates probe against.
- *
- * The canonical resolved config carries the base branch at
- * `project.baseBranch` (`lib/config-resolver.js` defaults it to `main`).
- * This helper used to read `config.baseBranch` — a key the resolver never
- * produces — so every freshness / file-assumption probe silently targeted
- * the literal `main` regardless of configuration. Benign in a repo whose
- * base branch *is* `main`; wrong for any consumer that configured something
- * else (Story #4541).
- *
- * The flat `config.baseBranch` fallback is retained for the legacy
- * `settings`-bag callers that pass `{ baseBranch, paths, planning }`.
+ * Reads `project.baseBranch` from resolved config; flat `baseBranch` serves
+ * legacy settings-bag callers.
  *
- * @param {object} [config] Resolved config, or a legacy settings bag.
+ * @param {object} [config]
  * @returns {string}
  */
 export function resolveBaseBranchRef(config) {
@@ -50,8 +22,6 @@ export function resolveBaseBranchRef(config) {
 }
 
 /**
- * Does `ref` name a commit in the repo at `cwd`?
- *
  * @param {string} ref
  * @param {string} cwd
  * @returns {boolean}
@@ -64,17 +34,9 @@ function refResolves(ref, cwd) {
 }
 
 /**
- * Resolve the configured base branch to a ref the footprint probes can read
- * in this checkout, or `null` when none exists.
- *
- * A developer checkout carries a local `main`; a CI pull-request checkout
- * (`actions/checkout` at the merge ref, detached) carries only
- * `origin/main`; a shallow smoke checkout carries neither. Probing the
- * bare branch name in the last two answers "absent" for every path, which
- * turns each bare-path repair into a `creates` and every declared path into
- * a stale reference. So: the local branch when it resolves, else its
- * `origin/` tracking ref when that does, else `null` — the caller then
- * skips the probes and says so, rather than reporting the tree as missing.
+ * Local branch, else `origin/<branch>` (a CI PR checkout has no local base),
+ * else `null` so the probes are skipped rather than reading every path as
+ * absent (a shallow checkout has neither).
  *
  * @param {{ baseBranch: string, cwd?: string }} opts
  * @returns {string|null}
@@ -86,10 +48,8 @@ function resolveProbeRef({ baseBranch, cwd }) {
 }
 
 /**
- * Default git probe: returns true when `path` exists at `ref` in the cwd repo.
- * `git cat-file -e <ref>:<path>` is the standard low-cost existence check —
- * the same probe the validator's own gates run, so the repair pass and the
- * gates cannot disagree about what is at base.
+ * The validator gates' own probe, so repair and gates agree on what is at
+ * base.
  *
  * @param {{ baseBranchRef: string, path: string, cwd?: string }} opts
  * @returns {boolean}
@@ -105,9 +65,7 @@ function defaultGitRunner({ baseBranchRef, path, cwd }) {
 }
 
 /**
- * The `existsAtBase` predicate the `changes[]` repair pass probes with. With
- * no base to read, a bare bullet is taken as the in-place edit it almost
- * always is.
+ * With no base to read, a bare bullet is taken as an in-place edit.
  *
  * @param {{ baseBranchRef: string|null, cwd?: string, gitRunner?: Function }} opts
  * @returns {(path: string) => boolean}
@@ -119,8 +77,6 @@ function makeExistsAtBase({ baseBranchRef, cwd, gitRunner }) {
 }
 
 /**
- * The one warning a checkout with no readable base leaves on the dry-run.
- *
  * @param {string} baseBranch
  * @param {string|null} baseBranchRef
  * @returns {string[]}
@@ -135,8 +91,6 @@ function probeSkipWarnings(baseBranch, baseBranchRef) {
 }
 
 /**
- * Attach non-enumerable bookkeeping to the validated array.
- *
  * @param {object[]} validated
  * @param {Record<string, unknown>} extras
  */
@@ -152,17 +106,11 @@ function defineHidden(validated, extras) {
 }
 
 /**
- * Repair the mechanical `changes[]` formalities, then validate.
- *
- * Repair before judging (Story #5312, the shape Story #5005 set for the
- * verify tier): a plain-string bullet or a trailing parenthetical is
- * rewritten into `{ path, assumption }` by probing the base branch, and
- * each rewrite is reported on the returned array's `repairs` so the dry-run
- * can print it. An entry nothing path-shaped can be salvaged from survives
- * untouched and still hard-errors in `validateTaskBodies`.
+ * Repair the mechanical `acceptance[]` / `changes[]` formalities (reported on
+ * `repairs`), then validate.
  *
  * @param {object[]} tickets Mutated in place.
- * @param {object} config Resolved config.
+ * @param {object} config
  * @param {{ cwd?: string, gitRunner?: Function }} [opts]
  * @returns {object[] & { findings: object[], errors: string[], warnings: string[], normalizations: object[], repairs: object[], probeRef: string|null }}
  */
@@ -182,9 +130,7 @@ export function validateTickets(tickets, config, opts = {}) {
   const validated = validateAndNormalizeTickets(tickets, {
     baseBranchRef: baseBranchRef ?? undefined,
     gitRunner: opts.gitRunner,
-    // Thread the repo cwd into the AC-freshness / file-assumption git
-    // probes (#4474 PR7) — without it they silently ran against
-    // process.cwd(), which is only the repo root by coincidence.
+    // Otherwise the probes run against process.cwd().
     cwd: opts.cwd,
   });
   validated.warnings.push(...probeSkipWarnings(baseBranch, baseBranchRef));

package/.agents/scripts/lib/orchestration/plan-persist/plan-context-source.js

@@ -1,12 +1,6 @@
 /**
- * plan-context-source.js — locate and read the `plan-context.js` envelope so
- * persist can derive the `/mandrel-plan --tickets` source ids from the run that
- * actually fetched them (Story #4554).
- *
- * This lives beside the persist ops rather than inside `plan-persist.js` so
- * the discovery + failure policy is directly testable: the CLI is a thin
- * `parseArgs` shell, and the interesting behaviour here is exactly the part
- * that decides whether a `--tickets` run can quietly lose its source set.
+ * Locate and read the `plan-context.js` envelope, from which persist derives
+ * the `--tickets` source ids.
  *
  * @module lib/orchestration/plan-persist/plan-context-source
  */
@@ -16,21 +10,13 @@ import path from 'node:path';
 
 import { Logger } from '../../Logger.js';
 
-/**
- * Filename the `/mandrel-plan` interrogate step writes its envelope to inside
- * `--plan-dir` (`plan-context.js --out <plan-dir>/plan-context.json`).
- */
 export const PLAN_CONTEXT_FILENAME = 'plan-context.json';
 
 /**
- * Decide where to look for the envelope.
- *
- * An explicit `--plan-context` path wins; otherwise the conventional file
- * inside `--plan-dir`. With neither, there is nothing to read — the caller
- * gets `null` and must warn (see `loadPlanContextEnvelope`).
+ * An explicit `--plan-context` wins over the file inside `--plan-dir`.
  *
- * @param {string|null|undefined} explicitPath `--plan-context`.
- * @param {string|null|undefined} planDir `--plan-dir`.
+ * @param {string|null|undefined} explicitPath
+ * @param {string|null|undefined} planDir
  * @returns {{ path: string, explicit: boolean }|null}
  */
 export function resolvePlanContextPath(explicitPath, planDir) {
@@ -46,36 +32,18 @@ export function resolvePlanContextPath(explicitPath, planDir) {
   return null;
 }
 
-/**
- * The advice printed whenever persist has no envelope to derive ids from.
- * Single-homed so the two no-envelope paths cannot drift apart.
- */
 const CAPTURE_HINT =
   'Re-run step 1 with `node .agents/scripts/plan-context.js … --out ' +
   '<plan-dir>/plan-context.json` and pass --plan-dir, or pass ' +
   '--source-tickets explicitly.';
 
 /**
- * Read the `plan-context.js` envelope.
- *
- * Failure policy — the point is that a `--tickets` run can never *quietly*
- * lose its source set, so every no-envelope path is audible:
- *
- * - **No path at all** (neither `--plan-dir` nor `--plan-context`): warn.
- *   Persist cannot tell a legitimate `--seed` run from a `--tickets` run
- *   whose envelope was never captured, so it says so rather than returning a
- *   silent `null`.
- * - **Explicit `--plan-context` missing**: throw. The operator named a file
- *   and meant it.
- * - **Auto-discovered file simply absent**: warn and degrade to
- *   `--source-tickets`. A `--seed` run legitimately has no envelope, so
- *   absence alone is not fatal.
- * - **Present but unparseable**: throw either way. A corrupt envelope is not
- *   the same as no envelope, and reading it as "no source tickets" is exactly
- *   the vacuous pass this module exists to prevent.
+ * A `--tickets` run must never quietly lose its source set: no path or an
+ * absent auto-discovered file warns (a `--seed` run legitimately has none);
+ * a missing explicit file or an unparseable envelope throws.
  *
  * @param {{ path: string, explicit: boolean }|null} planContext
- * @returns {Promise<object|null>} Parsed envelope, or null when absent.
+ * @returns {Promise<object|null>}
  */
 export async function loadPlanContextEnvelope(planContext) {
   if (!planContext) {