mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js

@@ -1,18 +1,7 @@
 /**
- * lib/orchestration/plan-persist/audit-provenance.js — what an audit-seeded
- * plan leaves behind for the next sweep.
- *
- * The chained `/mandrel-plan` path files Stories from an audit seed, and until
- * Story #5307 those Stories were invisible to the sweep that proposed them:
- * they carried no `audit::*` label, so they were absent from the label-listed
- * corpus dedup indexes, and nothing recorded them in the cross-run ledger. The
- * provenance footers `carryProvenanceFooters` stamps could not cover for
- * either — with an index in play the exact lookup is answered from that pool
- * and never reaches the provider.
- *
- * Both halves ride the create loop in `story-ops.js` because that is the only
- * seam on this path that cannot be forgotten: there is no second required pass
- * here the way `--wire-edges` is one for the standalone filer.
+ * What an audit-seeded plan leaves for the next sweep: `audit::*` labels (the
+ * dedup corpus is label-listed, so footers alone are invisible to an indexed
+ * sweep) and cross-run ledger entries.
  */
 
 import {
@@ -29,11 +18,6 @@ import {
 import { Logger } from '../../Logger.js';
 
 /**
- * A fresh accumulator for one persist run's audit filings.
- *
- * The run collects into this and flushes once, so a plan that files N Stories
- * leaves one reviewable ledger diff rather than N.
- *
  * @param {string} [ledgerPath]
  * @returns {{ path: string, ledger: object|null, recorded: number, ambiguous: number }}
  */
@@ -47,20 +31,12 @@ function newAuditLedgerRecord(ledgerPath) {
 }
 
 /**
- * Merge the seed's `audit::*` labels into an audit-seeded Story's labels.
- *
- * Taken from the **seed union**, not from the attributed provenance source: a
- * label only scopes which issues the next sweep's corpus fetch returns, and
- * matching inside that corpus is by fingerprint and semantic key. A superset
- * corpus can therefore only ever find more, never less — so erring wide is the
- * safe direction, and it keeps lens-to-label knowledge in the audit filer that
- * owns it rather than re-deriving a dimension here (the junk-derivation trap
- * Story #4195 closed).
- *
- * A non-audit seed carries no such footer, so this is a no-op there.
+ * Labels come from the seed union, not per-Story attribution: a label only
+ * widens the next sweep's corpus (matching is by fingerprint), so erring
+ * wide is safe.
  *
- * @param {Array<object>} stories — the assembled Stories.
- * @param {string} [provenanceSource] — the seed this plan was authored from.
+ * @param {Array<object>} stories
+ * @param {string} [provenanceSource]
  * @returns {Array<object>}
  */
 export function withAuditLabels(stories, provenanceSource) {
@@ -73,19 +49,9 @@ export function withAuditLabels(stories, provenanceSource) {
 }
 
 /**
- * Record one just-created Story in the cross-run audit ledger.
- *
- * The identities are read back off the body this run assembled, so what is
- * recorded is exactly what was stamped — attribution already applied. A Story
- * from a non-audit plan carries no footers and records nothing, which is why
- * a `--seed` or `--tickets` run never touches the ledger file at all.
- *
- * **The union fallback is deliberately NOT recorded.** When the seed carried
- * footers but the plan attributed none per-Story, every sibling carries every
- * fingerprint; binding a finding to one of them would be a coin flip, and a
- * wrong binding is worse than none — the finding would be suppressed against an
- * Issue that never tracked it, or resurrected when an unrelated Story closed.
- * The audit path stamps `provenance` mechanically, so this is the exception.
+ * Identities are read off the stamped body. Union-carried (unattributed)
+ * footers are never recorded: every sibling carries them, and a wrong
+ * binding is worse than none.
  *
  * @param {{ story: object, id: number, ledgerRecord: object, attributed: boolean }} args
  */
@@ -112,12 +78,6 @@ function recordAuditFiling({ story, id, ledgerRecord, attributed }) {
 }
 
 /**
- * Persist the run's audit filings, once, after every Story exists.
- *
- * Writing per-Story would rewrite a committed baseline N times for one plan;
- * writing once keeps the diff to a single reviewable change. A run that
- * recorded nothing writes nothing.
- *
  * @param {object} ledgerRecord
  * @param {{ warn: Function }} logger
  */
@@ -138,27 +98,16 @@ function flushAuditLedger(ledgerRecord, logger) {
 }
 
 /**
- * Record everything one persist run filed, once, after every Story exists.
- *
- * Driven from the persist orchestrator rather than from inside the create loop:
- * the loop's job is to create issues, and this is the only other place that
- * always runs after it. Either seam is unforgettable — there is no second
- * required pass on this path the way `--wire-edges` is one for the standalone
- * filer — and keeping the side effect at the orchestration layer leaves the
- * create loop doing one thing.
- *
- * One write per plan, not per Story: the ledger is committed state, and N
- * rewrites of it for one plan is a diff nobody can review. A run that recorded
- * nothing — a non-audit plan, or one whose identities were all union-carried —
- * writes nothing at all.
+ * One ledger write per plan, not per Story — the ledger is committed state.
+ * A run that recorded nothing writes nothing.
  *
  * @param {object} params
- * @param {Array<object>} params.stories — the assembled Stories.
- * @param {Array<{ slug: string, id: number }>} params.created — persist receipts.
- * @param {Array<object>} params.tickets — the raw authored tickets.
+ * @param {Array<object>} params.stories
+ * @param {Array<{ slug: string, id: number }>} params.created
+ * @param {Array<object>} params.tickets
  * @param {string} [params.ledgerPath]
  * @param {{ warn: Function }} [params.logger]
- * @param {boolean} [params.dryRun] — a dry run records nothing at all.
+ * @param {boolean} [params.dryRun]
  * @returns {{ recorded: number, ambiguous: number }}
  */
 export function recordAuditFilings({
@@ -169,14 +118,10 @@ export function recordAuditFilings({
   logger,
   dryRun = false,
 }) {
-  // A dry run created no issue to record against, and must not touch committed
-  // state. Owned here rather than at the call site so the contract is testable.
   if (dryRun) return { recorded: 0, ambiguous: 0 };
   const record = newAuditLedgerRecord(ledgerPath);
   const idBySlug = new Map((created ?? []).map((c) => [c.slug, c.id]));
-  // Attribution is a property of what the plan AUTHORED, so it is read off the
-  // raw tickets rather than threaded through assembly: a Story that declared no
-  // `provenance` inherited the seed union, where ownership is a coin flip.
+  // Attribution is what the plan authored, so read it off the raw tickets.
   const attributedSlugs = new Set(
     (tickets ?? [])
       .filter((t) => t?.provenance !== undefined && t?.provenance !== null)

package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js

@@ -1,37 +1,10 @@
 /**
- * changes-repair.js — repair-before-judging for `changes[]` entries
- * (Story #5312).
- *
- * The `{ path, assumption }` object shape is a deterministic, mechanically
- * derivable formality. The validator already knew how to salvage a path from
- * a plain-string bullet (`suggestPathEntryFix`) — then rejected the plan
- * anyway and charged the author a full re-drafting round to paste that exact
- * object back. Story #5005 made the same call for the verify-tier suffix and
- * repaired it instead; the suffix is gone now, and the repair moves to the
- * one formality left: this module applies the inference the validator
- * trusts, so the dry-run rewrites and **reports** each repair rather than
- * refusing on it.
- *
- * Two shapes are repaired, on both authoring surfaces (a structured object
- * body's `changes[]` array and a serialized string body's `## Changes`
- * section):
- *
- *   - a **plain-string bullet** (`src/app.js`, `` `src/app.js` ``,
- *     `src/app.js — adds the route`) becomes `{ path, assumption }`, the
- *     assumption resolved by probing the base branch — a path present at
- *     base is a `refactors-existing`, an absent one a `creates`;
- *   - a **trailing parenthetical** on a path (`src/app.js (new)`,
- *     `` `src/app.js (creates)` — refactors-existing ``) is stripped; an
- *     authored assumption is kept, an absent one probed as above.
- *
- * A string nothing path-shaped can be salvaged from is left untouched and
- * still fails the body-shape validator — that is the one `changes[]` failure
- * only the author can resolve.
- *
- * It lives beside the validator rather than inside it because the validator's
- * job is to *judge*: mixing a mutating repair pass into a module of pure
- * collectors muddies both. `persist-helpers.js#validateTickets` calls this
- * first, then the validators.
+ * Repair-before-judging for `changes[]`, on both the structured array and a
+ * serialized `## Changes` section: a plain-string bullet becomes
+ * `{ path, assumption }` (probed at base: present → `refactors-existing`,
+ * absent → `creates`), and a trailing parenthetical on a path is stripped.
+ * Repairs are reported, not refused; an unsalvageable string is left for the
+ * validator. Kept apart from the validator, whose collectors are pure.
  *
  * @module lib/orchestration/plan-persist/changes-repair
  */
@@ -39,22 +12,16 @@
 import { matchBarePathToken } from '../../story-body/body-format-lints.js';
 import { FILE_ASSUMPTION_VALUES } from '../file-assumption-enum.js';
 
-/** The `## Changes` heading (either level the parser accepts). */
 const CHANGES_HEADING_RE = /^#{2,3}\s+Changes\s*$/i;
 
-/** Any heading — the end of the `## Changes` section. */
 const ANY_HEADING_RE = /^#{1,6}\s+\S/;
 
-/** A trailing `(…)` on a path token. */
 const TRAILING_PARENTHETICAL_RE = /\s*\([^)]*\)\s*$/;
 
-/** The humanized canonical bullet: `` `path` — assumption ``. */
+/** The canonical bullet: `` `path` — assumption ``. */
 const HUMANIZED_RE = /^`([^`]+)`\s+—\s+(\S+)$/;
 
 /**
- * Strip a trailing parenthetical from a path token, reporting whether one
- * was present.
- *
  * @param {string} raw
  * @returns {{ path: string, stripped: boolean }}
  */
@@ -64,16 +31,8 @@ function stripParenthetical(raw) {
 }
 
 /**
- * Salvage the path token from a plain-string bullet: drop a leading list
- * marker, take the segment before any humanized ` — ` tail, peel quotes and
- * backticks, strip a trailing parenthetical. Returns `null` when nothing
- * path-shaped survives.
- *
- * What counts as path-shaped is `matchBarePathToken` — the same grammar the
- * story-body parser admits a bare bullet under, imported rather than
- * restated (Story #5361). The repair pass scoring a narrower class than the
- * parser is what let a route-segment path be repaired on one surface and
- * refused on the other.
+ * Path-shaped means `matchBarePathToken` — the parser's own grammar, so the
+ * repair and the parser accept the same class.
  *
  * @param {string} raw
  * @returns {string|null}
@@ -93,9 +52,6 @@ function salvagePath(raw) {
 }
 
 /**
- * Resolve the assumption for a path with none authored: present at base →
- * `refactors-existing`, absent → `creates`.
- *
  * @param {string} path
  * @param {(path: string) => boolean} existsAtBase
  * @returns {'refactors-existing'|'creates'}
@@ -105,9 +61,7 @@ function probeAssumption(path, existsAtBase) {
 }
 
 /**
- * Repair one structured `changes[]` item. Returns the corrected entry and a
- * repair record, or `null` when the item needs no repair (or cannot be
- * repaired).
+ * `null` when the item needs no repair or cannot be repaired.
  *
  * @param {unknown} item
  * @param {(path: string) => boolean} existsAtBase
@@ -144,10 +98,6 @@ function repairStructuredItem(item, existsAtBase) {
 }
 
 /**
- * Repair one line of a serialized `## Changes` section. Returns the rewritten
- * line and a repair record, or `null` when the line is already canonical or
- * cannot be repaired.
- *
  * @param {string} line
  * @param {(path: string) => boolean} existsAtBase
  * @returns {{ line: string, repair: object }|null}
@@ -200,9 +150,7 @@ function repairSectionLine(line, existsAtBase) {
 }
 
 /**
- * Repair the `## Changes` section of a serialized body in place. Only lines
- * between the heading and the next heading are touched; the rest of the
- * body is byte-identical.
+ * Touches only the `## Changes` section; the rest stays byte-identical.
  *
  * @param {string} body
  * @param {(path: string) => boolean} existsAtBase
@@ -232,11 +180,9 @@ function repairSerializedBody(body, existsAtBase) {
 }
 
 /**
- * Repair the `changes[]` of one ticket, on whichever surface carries it.
- *
  * @param {object} ticket Mutated in place.
  * @param {(path: string) => boolean} existsAtBase
- * @returns {object[]} The repairs applied to this ticket.
+ * @returns {object[]}
  */
 function repairTicket(ticket, existsAtBase) {
   const body = ticket.body;
@@ -263,13 +209,6 @@ function repairTicket(ticket, existsAtBase) {
 }
 
 /**
- * Render one `changes[]` repair as the dry-run line the operator reads.
- *
- * The dry-run's repair list is mixed — an `acceptance[]` handle strip is
- * reported on it too — but the dispatch across kinds lives in
- * [`acceptance-handle-repair.js`](acceptance-handle-repair.js)`#renderRepair`,
- * which delegates here for this kind. Each producer owns its own line.
- *
  * @param {{ slug: string, from: string, path: string, assumption: string, reason: string }} repair
  * @returns {string}
  */
@@ -284,11 +223,8 @@ export function renderChangeRepair({ slug, from, path, assumption, reason }) {
 }
 
 /**
- * Rewrite every repairable `changes[]` entry across the draft, probing the
- * base branch for the assumption where none was authored. Mutates `tickets`
- * in place (the persist pipeline threads this same array on to assembly)
- * and returns the repairs, each tagged with the Story's slug. Total — a
- * non-array argument and non-Story tickets are no-ops.
+ * Mutates `tickets` in place — persist threads this same array on to
+ * assembly.
  *
  * @param {object[]} tickets
  * @param {{ existsAtBase: (path: string) => boolean }} args

package/.agents/scripts/lib/orchestration/plan-persist/cross-plan-links.js

@@ -1,25 +1,9 @@
 /**
- * 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.
+ * A plan's references to live tracker state (`--epic <id>`, `#<id>`
+ * blockers), verified together before the first create, dry run included —
+ * cheap to fix then, costly after.
  *
  * @module lib/orchestration/plan-persist/cross-plan-links
- * @see Story #5155
  */
 
 import { adoptContainerEpic, resolveAdoptionTarget } from './epic-adoption.js';
@@ -27,15 +11,12 @@ 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 }) {
@@ -44,13 +25,8 @@ export async function resolveCrossPlanLinks({ provider, stories, 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.
+ * Adopt the resolved target, else create. The two paths have opposite
+ * failure postures, so the choice lives here, not at the call site.
  *
  * @param {{
  *   provider: object,
@@ -59,7 +35,7 @@ export async function resolveCrossPlanLinks({ provider, stories, epicId }) {
  *   created: Array<{ id: number }>,
  *   opts?: { dryRun?: boolean },
  * }} args
- * @returns {Promise<object|null>} `null` when this run has no container.
+ * @returns {Promise<object|null>}
  */
 export async function resolveContainerEpic({
   provider,

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

@@ -1,25 +1,10 @@
 /**
- * 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.
+ * Join this run's Stories to an existing Epic the operator named (`--epic`).
+ * A bad target is a hard error raised before the first create — silently not
+ * adopting would misfile the plan. Once Stories exist, link failures only
+ * warn.
  *
  * @module lib/orchestration/plan-persist/epic-adoption
- * @see Story #5155
  */
 
 import { Logger } from '../../Logger.js';
@@ -29,14 +14,7 @@ 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.
+ * Called before any create. An absent `epicId` resolves to `null`.
  *
  * @param {{ provider: object, epicId: number|null }} opts
  * @returns {Promise<{ id: number, title: string, body: string }|null>}
@@ -91,11 +69,7 @@ export async function resolveAdoptionTarget({ provider, epicId }) {
 }
 
 /**
- * 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.
+ * Runs after the Stories exist — the linkage needs their real ids.
  *
  * @param {{
  *   provider: object,
@@ -122,9 +96,7 @@ export async function adoptContainerEpic({
 
   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.
+  // Dry-run ids are negative placeholders; report them as-is.
   if (dryRun) {
     return {
       id: target.id,
@@ -163,29 +135,11 @@ export async function adoptContainerEpic({
 }
 
 /**
- * Write the appended checklist back to the Epic body.
- *
- * **The body is re-read `fresh` immediately before the append.** `target.body`
- * was captured by `resolveAdoptionTarget` before the first Story was created,
- * which on a cohort of any size is many seconds and several writes ago. An
- * append computed against that snapshot and PATCHed wholesale silently drops
- * every checklist row another writer added in between — a concurrent persist
- * run adopting the same Epic, or an operator ticking a child off by hand. The
- * body is a full-document write, so a stale base is not a merge conflict; it
- * is a silent revert.
- *
- * This **narrows** the read-then-PATCH window; it does not close it. Nothing
- * here is atomic, and GitHub's issue API offers no compare-and-swap, so a
- * write landing between this read and this PATCH is still lost. Narrowing it
- * from "the whole create phase" to "one round-trip" is the available fix; a
- * real one needs an API that does not exist.
- *
- * The PATCH is skipped when the append changes nothing, so re-running an
- * adoption that already landed writes nothing at all.
- *
- * 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.
+ * The body is re-read fresh right before the append: the body PATCH is a
+ * whole-document write, so appending to the pre-create snapshot would
+ * silently revert rows another writer added since. This narrows the window
+ * to one round-trip; GitHub offers no compare-and-swap to close it. Skips the
+ * PATCH when nothing changes. Non-fatal.
  *
  * @param {{ provider: object, target: { id: number, body: string }, childIds: number[] }} opts
  * @returns {Promise<void>}
@@ -212,13 +166,8 @@ async function appendChecklist({ provider, target, childIds }) {
 }
 
 /**
- * Re-read the Epic's body, bypassing any provider cache.
- *
- * `{ fresh: true }` is the whole point: the adoption path already read this
- * issue once, so a cached read would hand back the very snapshot this function
- * exists to replace. Falls back to the snapshot when the re-read fails or the
- * provider has no `getTicket` — a stale base still appends the run's own
- * children, which beats not linking them.
+ * `{ fresh: true }` bypasses the cache that holds the stale snapshot. Falls
+ * back to the snapshot, which still links this run's children.
  *
  * @param {{ provider: object, target: { id: number, body: string } }} opts
  * @returns {Promise<string>}