mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/audit-to-stories/ledger-commit.js

@@ -1,31 +1,6 @@
 /**
- * lib/audit-to-stories/ledger-commit.js — persist the cross-run audit ledger.
- *
- * The `--auto` sweep's whole value is memory: `baselines/audit-ledger.json`
- * is what lets the next run tell a re-detection from a fresh finding and an
- * accepted risk from an unseen one. A scheduled sweep, though, typically runs
- * on an ephemeral checkout — a fresh clone that is deleted when the job ends —
- * so the ledger `--auto` writes is discarded and every later sweep starts from
- * an empty memory. The sweep is then permanently amnesiac, and the ledger's
- * suppression and regression signals never fire.
- *
- * This module closes that hole from both ends:
- *
- *   - {@link runLedgerCommit} (`--auto --ledger-commit`) commits the changed
- *     ledger onto a `chore/audit-ledger-<YYYY-MM-DD>-<shortsha>` branch cut
- *     from `origin/<base>`, pushes it, and opens a PR against
- *     `project.baseBranch` through the `gh` wrapper.
- *     Auto-merge is never requested: a ledger PR records machine-derived state
- *     a human should glance at, so landing it stays an operator decision.
- *   - {@link resolveLedgerSummary} answers the question the *unflagged* sweep
- *     needs — "would this ledger survive?" — so a run that cannot persist (no
- *     `origin`, or HEAD parked off the base branch) says so in its summary,
- *     and on stderr, instead of silently discarding the state.
- *
- * Both take injectable `git` / `gh` seams (`.agents/rules/test-seams.md`) so
- * the branch/commit/push/PR argv shape is assertable without a live remote.
- * The logic lives here rather than in `audit-to-stories.js` so the CLI file's
- * complexity budget does not absorb a git driver.
+ * Persist the cross-run audit ledger, which an ephemeral checkout would
+ * otherwise discard.
  */
 
 import { DEFAULT_LEDGER_PATH } from '../findings/audit-ledger.js';
@@ -33,12 +8,9 @@ import { gh as defaultGh } from '../gh-exec.js';
 import { gitSync } from '../git-utils.js';
 import { openLedgerPullRequest, probeGit } from './ledger-pr.js';
 
-/** Fallback base branch when config carries no `project.baseBranch`. */
 const DEFAULT_BASE_BRANCH = 'main';
 
 /**
- * Render the `YYYY-MM-DD` stamp both the branch name and the commit subject
- * carry, so one sweep produces one identifiable ledger branch per day.
  * @param {Date|string|number} [now]
  * @returns {string}
  */
@@ -48,9 +20,8 @@ function isoDate(now) {
 }
 
 /**
- * Resolve `project.baseBranch` defensively: an explicit value wins, then
- * config, then `main`. A failed config resolve must never break a sweep that
- * has already done its real work.
+ * Explicit, then config, then `main`; a failed config resolve must never break
+ * a sweep that has already done its work.
  * @param {string} [explicit]
  * @returns {Promise<string>}
  */
@@ -67,18 +38,12 @@ async function resolveBaseBranch(explicit) {
 }
 
 /**
- * Inspect whether the ledger changed and whether this checkout could persist
- * it at all. Module-local: the two exported entry points below are the whole
- * public surface, so a probe helper never becomes a second way in.
- *
- * `unpersisted` is the signal the unflagged `--auto` summary carries: the
- * sweep produced new memory, and this checkout has nowhere to put it — either
- * there is no `origin` to push to or HEAD is not on the base branch, so a
- * commit here would not reach the repository's shared state.
+ * `unpersisted`: the ledger changed but there is no `origin` or HEAD is off
+ * the base branch, so a commit here would not reach shared state.
  *
  * @param {object} [params]
- * @param {string} [params.ledgerPath] — defaults to `baselines/audit-ledger.json`.
- * @param {string} [params.baseBranch] — defaults to resolved `project.baseBranch`.
+ * @param {string} [params.ledgerPath]
+ * @param {string} [params.baseBranch]
  * @param {string} [params.cwd]
  * @param {(cwd: string, ...args: string[]) => string} [params.git]
  * @returns {Promise<{ ledgerPath: string, baseBranch: string, changed: boolean,
@@ -109,8 +74,7 @@ async function assessLedgerPersistence({
 }
 
 /**
- * Has the sweep actually written new memory? Scoped to the ledger pathspec, so
- * unrelated dirt in the checkout is never mistaken for it.
+ * Pathspec-scoped, so unrelated dirt never counts.
  * @param {(args: string[]) => string} probe
  * @param {string} ledgerPath
  * @returns {boolean}
@@ -120,8 +84,6 @@ function ledgerIsDirty(probe, ledgerPath) {
 }
 
 /**
- * Is there an `origin` to push to at all? The ephemeral-clone shape that makes
- * a sweep amnesiac usually has none.
  * @param {(args: string[]) => string} probe
  * @returns {boolean}
  */
@@ -133,9 +95,7 @@ function hasOriginRemote(probe) {
 }
 
 /**
- * The branch HEAD is on, or `''` when the checkout is detached or has no
- * commits — both of which read as "not the base branch", which is the answer
- * the callers need.
+ * `''` when detached or commitless — both read as "not the base branch".
  * @param {(args: string[]) => string} probe
  * @returns {string}
  */
@@ -144,8 +104,6 @@ function headBranchOf(probe) {
 }
 
 /**
- * Warn that the reconciled ledger has nowhere to go. Names the file, because
- * "state will be lost" is unactionable without knowing which state.
  * @param {{ ledgerPath: string, baseBranch: string, hasOrigin: boolean, headBranch: string }} state
  * @returns {string}
  */
@@ -157,19 +115,14 @@ function unpersistedWarning(state) {
 }
 
 /**
- * Resolve the `--auto` summary's `ledger` field, annotating it with
- * `unpersisted: true` (and warning on stderr) when the sweep produced memory
- * this checkout cannot keep.
- *
- * The whole decision lives here rather than in the CLI so `runAuto` stays a
- * straight-line assembly of its summary: `dryRun` and `ledgerCommit` are
- * passed through raw and branched on once, in one place.
+ * Marks the summary `unpersisted: true` (and warns) when the checkout cannot
+ * keep the new memory.
  *
  * @param {object} [params]
- * @param {object|null} [params.ledger] — the plan's ledger summary, or null.
+ * @param {object|null} [params.ledger]
  * @param {string} [params.ledgerPath]
- * @param {boolean} [params.dryRun] — nothing was written, so nothing is at risk.
- * @param {boolean} [params.ledgerCommit] — a PR is about to persist it.
+ * @param {boolean} [params.dryRun]
+ * @param {boolean} [params.ledgerCommit]
  * @param {string} [params.cwd]
  * @param {(cwd: string, ...args: string[]) => string} [params.git]
  * @param {{ warn: Function }} [params.logger]
@@ -192,13 +145,8 @@ export async function resolveLedgerSummary({
 }
 
 /**
- * Commit the changed ledger onto a unique branch cut from the remote base and
- * open a PR for it.
- *
- * Assesses the checkout, then hands the whole write sequence to
- * {@link openLedgerPullRequest}. Every git/`gh` failure is fatal and names its
- * step; the caller runs this *after* printing the run summary, so a broken
- * remote never costs the operator the sweep's findings.
+ * Failures are fatal and name their step; callers run this after printing the
+ * run summary so a broken remote never costs the sweep's findings.
  *
  * @param {object} [params]
  * @param {string} [params.ledgerPath]

package/.agents/scripts/lib/audit-to-stories/ledger-pr.js

@@ -1,22 +1,11 @@
 /**
- * lib/audit-to-stories/ledger-pr.js — everything the ledger PR is made of.
- *
- * The mechanical half of `--ledger-commit`: how the branch is named, when the
- * checkout is refused, the commit sequence itself, the push, and the PR body.
- * `ledger-commit.js` next door keeps only the two entry points and the
- * persistence assessment they share, so the run sequence there reads as a
- * sequence rather than as a git driver.
- *
- * Every refusal in this module happens **before** its first write, so a refused
- * run cannot have left a branch or a commit behind. The git and `gh` seams are
- * injected (`.agents/rules/test-seams.md`), so the whole retry matrix is
- * assertable without a live remote.
+ * The `--ledger-commit` write sequence. Every refusal precedes the first
+ * write.
  */
 
 /**
- * Run a read-only git probe that must never throw: a checkout with no commits
- * (or no repository at all) is a legitimate answer of "nothing to report", not
- * a crash. The write path uses `runStep` instead, where a failure IS fatal.
+ * Read-only git probe that never throws; a checkout with no commits is an
+ * answer, not a crash. Writes use `runStep`, where failure is fatal.
  *
  * @param {(cwd: string, ...args: string[]) => string} git
  * @param {string} cwd
@@ -33,9 +22,6 @@ export function probeGit(git, cwd, args) {
 }
 
 /**
- * Does a ref resolve in this checkout? Read-only, and never fatal — an absent
- * ref is the answer, not an error.
- *
  * @param {(cwd: string, ...args: string[]) => string} git
  * @param {string} cwd
  * @param {string} ref
@@ -48,14 +34,9 @@ function refExists(git, cwd, ref) {
 }
 
 /**
- * The short sha the branch name carries.
- *
- * Dating the branch alone was not enough to make a retry safe: a second run on
- * the same day found `chore/audit-ledger-<date>` already present and failed at
- * `create-branch`, so the *first* failure (usually a push) permanently poisoned
- * every retry that day. Qualifying the name with the base commit makes it
- * unique across bases while staying **deterministic** for the same base — which
- * is exactly what lets a retry recognise its own half-finished branch.
+ * Qualifies the branch name so it is unique across bases (a same-day retry
+ * must not collide) yet deterministic per base (so a retry recognises its own
+ * half-finished branch).
  *
  * @param {(cwd: string, ...args: string[]) => string} git
  * @param {string} cwd
@@ -71,14 +52,8 @@ function shortSha(git, cwd, baseRef) {
 }
 
 /**
- * Resolve the ledger branch for this run, and whether it is a **resume**.
- *
- * A ledger branch that exists locally and has never been pushed is the wreckage
- * of a failed run, not a landed one: its commit is already made, so the work
- * left is the push and the PR. Recognising it is what turns a failed push plus
- * its retry into exactly one PR instead of a stranded branch and a run
- * reporting `ledger-unchanged` — which is what the ledger file honestly is once
- * its change has been committed onto that branch.
+ * A local, never-pushed ledger branch is a failed run's commit: resume at the
+ * push, so a failed push plus its retry yields exactly one PR.
  *
  * @param {{ git: Function, cwd: string, base: string, date: string }} params
  * @returns {{ branch: string, resuming: boolean }}
@@ -94,14 +69,8 @@ function resolveLedgerBranch({ git, cwd, base, date }) {
 }
 
 /**
- * Refuse, naming the step, when the checkout cannot legitimately produce a
- * ledger PR. Both refusals happen **before** any write, so a refused run leaves
- * no branch and no commit behind.
- *
- * HEAD parked off the base branch is the one an unattended sweep actually
- * meets: a job that has already checked out a feature branch would otherwise
- * cut its ledger branch from that branch's tip and open a PR carrying every
- * unrelated commit on it.
+ * Refuses before any write. HEAD off the base branch would cut the ledger
+ * branch from a feature tip and carry its unrelated commits into the PR.
  *
  * @param {{ hasOrigin: boolean, onBaseBranch: boolean, headBranch: string,
  *   baseBranch: string }} state
@@ -125,10 +94,6 @@ function assertCommittable(state, branch) {
 }
 
 /**
- * Extract the PR URL `gh pr create` prints, so the caller can name it in the
- * run summary. A wrapper that returns something else yields `null` rather than
- * a fabricated link.
- *
  * @param {unknown} result
  * @returns {string|null}
  */
@@ -139,8 +104,6 @@ function pullRequestUrl(result) {
 }
 
 /**
- * Wrap one write step so a git or `gh` failure surfaces as a fatal error that
- * names the step that broke. Accepts sync and async steps alike.
  * @param {string} name
  * @param {() => unknown} fn
  * @returns {Promise<unknown>}
@@ -157,8 +120,6 @@ async function runStep(name, fn) {
 }
 
 /**
- * Compose the ledger PR body. Kept separate so the step sequence below reads
- * as a sequence and not as a string-building exercise.
  * @param {string} ledgerPath
  * @param {string} date
  * @returns {string}
@@ -179,10 +140,6 @@ function pullRequestBody(ledgerPath, date) {
 }
 
 /**
- * Cut the ledger branch from `origin/<base>` and commit the ledger onto it —
- * or, when `resuming`, simply check out the branch a failed run already
- * committed onto, because those steps have already succeeded.
- *
  * @param {object} ctx
  * @returns {Promise<void>}
  */
@@ -196,7 +153,6 @@ async function commitLedgerOnto({
   resuming = false,
 }) {
   if (resuming) {
-    // The commit already exists on that branch; all it is missing is a push.
     await runStep('resume-branch', () => git(cwd, 'checkout', branch));
     return;
   }
@@ -205,18 +161,14 @@ async function commitLedgerOnto({
     git(cwd, 'checkout', '-b', branch, `origin/${base}`),
   );
   await runStep('stage-ledger', () => git(cwd, 'add', '--', ledgerPath));
-  // The `-- <path>` pathspec is what keeps the commit ledger-only even when
-  // the sweep's checkout carries unrelated dirt.
+  // The pathspec keeps the commit ledger-only in a dirty checkout.
   await runStep('commit-ledger', () =>
     git(cwd, 'commit', '-m', subject, '--', ledgerPath),
   );
 }
 
 /**
- * Push the ledger branch and open its PR, returning the PR URL.
- *
- * Auto-merge is never requested: the ledger records machine-derived lifecycle
- * state a human should glance at, so landing it stays an operator decision.
+ * Never requests auto-merge: landing the ledger stays an operator decision.
  *
  * @param {object} ctx
  * @returns {Promise<string|null>}
@@ -251,12 +203,8 @@ async function pushAndOpenPullRequest({
 }
 
 /**
- * Put the checkout back on the branch the run started on.
- *
- * Best-effort by design, and called from a `finally`: on the failure path
- * especially — where the next thing the operator runs is the retry — leaving
- * them parked on a half-finished ledger branch is its own defect, but a failure
- * to restore must never mask the failure that caused it.
+ * Best-effort, from a `finally`: a failed restore must never mask the failure
+ * that caused it.
  *
  * @param {{ git: Function, cwd: string, startBranch: string, branch: string }} params
  */
@@ -265,28 +213,12 @@ function restoreBranch({ git, cwd, startBranch, branch }) {
   try {
     git(cwd, 'checkout', startBranch);
   } catch (_) {
-    // Deliberately swallowed — see the contract above.
+    // Deliberately swallowed.
   }
 }
 
 /**
- * Run the whole `--ledger-commit` write sequence against an assessed checkout:
- * refuse or skip, cut (or resume) the branch, push, open the PR, and put the
- * checkout back where it started.
- *
- * **Re-runnable**, which is the property an unattended sweep needs. The two
- * ways a retry used to misbehave are both closed here:
- *
- *   - The branch name is qualified by the base commit, so a same-day retry no
- *     longer collides with the branch a failed run left behind.
- *   - A ledger already committed on an **unpushed** ledger branch resumes at
- *     the push rather than reporting `ledger-unchanged` (the ledger file is
- *     clean — it is committed, just not pushed) and abandoning the work.
- *     Across a failed push and its retry that yields exactly one PR.
- *
- * The branch the run started on is restored in a `finally`, so a failure
- * anywhere in the sequence — and success alike — leaves the operator's checkout
- * where they left it rather than parked on a ledger branch.
+ * Re-runnable; always restores the starting branch.
  *
  * @param {{ state: object, ledgerPath: string, cwd: string, git: Function,
  *   gh: object, date: string }} params

package/.agents/scripts/lib/audit-to-stories/ledger-record.js

@@ -1,24 +1,6 @@
 /**
- * lib/audit-to-stories/ledger-record.js — record what a run actually filed.
- *
- * The cross-run ledger can only suppress an already-filed finding if something
- * tells it the finding was filed. Until Story #5305 nothing did: the reconcile
- * ran *during* the scan, before any Issue existed, and its `issueStates` were
- * derived from `matchedIssues` — the Issues dedup FOUND. A group classified
- * `create` has none, so a freshly opened Issue contributed nothing and its
- * entry persisted as `status: "new", issue: null` forever. On a host where
- * GitHub-search dedup works that is invisible; on one where it cannot run,
- * nothing suppresses anything and every sweep re-files everything.
- *
- * The missing input is the `groupKey → issueNumber` map, which exists only
- * after the Issues are opened. `--wire-edges` already takes exactly that map
- * and is already a required pass, which is why the record rides along with it
- * rather than arriving as a second command an operator must remember.
- *
- * Nothing here reaches the network: the caller hands over the map it already
- * holds, and the only I/O is the ledger read/write this module delegates to
- * `ledger.js`. That is what lets the record run BEFORE the provider is loaded,
- * so a host whose provider cannot be constructed still records what it filed.
+ * Record what a run filed onto the ledger so the next run suppresses it even
+ * without search dedup. No network: runs before the provider loads.
  */
 
 import {
@@ -33,27 +15,13 @@ import {
 } from './finding-adapter.js';
 
 /**
- * Project the opened-issue map onto the `{ fingerprint → issueState }` shape
- * `reconcileLedger` reads, and collect the findings those groups carry.
- *
- * Only groups present in the map contribute. A group the map does not mention
- * was not opened — deduped, ledger-suppressed, or simply skipped — and
- * inventing an Issue state for it is how a finding gets suppressed against an
- * Issue that does not exist.
- *
- * Every recorded state is `open`: the map names Issues this run just created,
- * and a just-created Issue is open. A later close is learned from the live
- * lookup on the next run, where it outranks this record (`decideStatus` reads
- * the closed-Issue branch first).
+ * Only mapped groups contribute; inventing a state for an unopened group would
+ * suppress a finding against an Issue that does not exist. Every state is
+ * `open` — a later close is learned live next run and outranks this record.
  *
  * @param {object} params
  * @param {Array<object>} params.groups — the `create`-eligible groups.
  * @param {Record<string, number>} params.issueByGroupKey — group key → issue number.
- * Module-internal: `recordFiledIssues` is the only production entrypoint, and
- * exporting this for tests alone trips the CI-only `dead-exports:production`
- * gate. It is covered through `recordFiledIssues`, which is the seam that
- * actually ships.
- *
  * @returns {{ findings: Array<object>, issueStates: Record<string, { state: string, number: number }>, groupsRecorded: number }}
  */
 function issueStatesFromIssueMap({ groups, issueByGroupKey }) {
@@ -78,18 +46,14 @@ function issueStatesFromIssueMap({ groups, issueByGroupKey }) {
 }
 
 /**
- * Fold the just-opened Issues onto the committed ledger.
- *
- * Only the mapped groups' findings are passed to `reconcileLedger`, so every
- * other entry survives untouched — `reconcileLedger` copies the prior index
- * forward and rewrites only what this scan hands it.
+ * Other ledger entries survive untouched: `reconcileLedger` rewrites only the
+ * findings it is handed.
  *
  * @param {object} params
  * @param {string} [params.ledgerPath]
  * @param {Array<object>} params.groups — the `create`-eligible groups.
  * @param {Record<string, number>} params.issueByGroupKey
- * @param {boolean} [params.write=true] — `false` computes the record without
- *   persisting it, which is what `--dry-run` needs.
+ * @param {boolean} [params.write=true] — `false` for `--dry-run`.
  * @param {{ readLedgerImpl?: Function, writeLedgerImpl?: Function }} [seams]
  * @returns {{ path: string, written: boolean, groupsRecorded: number, findingsRecorded: number, filed: number }}
  */
@@ -109,10 +73,8 @@ export function recordFiledIssues(
     issueStates,
     toCanonical: toCanonicalFinding,
   });
-  // Nothing to record means nothing to write. The ledger is committed consumer
-  // state and `--ledger-commit` opens a PR only when it changed, so rewriting
-  // it with a fresh `generatedAt` and no new memory would manufacture a diff
-  // that says nothing.
+  // No findings → no write: a fresh `generatedAt` alone would make
+  // `--ledger-commit` open an empty PR.
   const wrote = Boolean(write) && findings.length > 0;
   if (wrote) writeLedgerImpl(path, next);