mandrel 2.38.0 → 2.40.0

package/.agents/scripts/generate-skills-index.js

@@ -8,6 +8,15 @@
 // generator output (ignoring the volatile `generatedAt` field) and exits
 // non-zero with a diff-style message if they diverge.
 //
+// Two indexes, never one (Story #5135). The shipped manifest above is a
+// committed payload file that `mandrel doctor` / `mandrel sync-agents`
+// compare byte-for-byte against the installed package, so consumer-authored
+// skills under the `.agents/local/skills/` zone MUST NOT be folded into it —
+// a merged index would read as payload drift in every consumer that authored
+// a skill, and those commands would refuse. Local skills are therefore
+// indexed into their own `.agents/local/skills/skills.index.json`, inside
+// the zone sync never prunes and drift never walks.
+//
 // CLI surface:
 //
 //   node generate-skills-index.js [--check] [--root <dir>] [--out <file>]
@@ -38,7 +47,18 @@ import { runAsCli } from './lib/cli-utils.js';
 import { formatGeneratedJson } from './lib/format-generated-json.js';
 import { Logger } from './lib/Logger.js';
 import { parseSkill } from './lib/skills/parse-skill.js';
-import { collectSkillFiles } from './lib/skills/walk-skill-files.js';
+import {
+  diffManifests,
+  INDEX_FILENAME,
+  indexPathFor,
+  readManifest,
+} from './lib/skills/skills-index.js';
+import {
+  collectLocalSkillFiles,
+  collectSkillFiles,
+  LOCAL_SKILLS_SEGMENTS,
+  PAYLOAD_SKILLS_SEGMENTS,
+} from './lib/skills/walk-skill-files.js';
 
 const GENERATOR_ID = 'generate-skills-index.js@1';
 
@@ -103,8 +123,8 @@ function projectEntry(parsed) {
  * Build the manifest object (without `generatedAt`) by walking the tree
  * and projecting each parsed SKILL.md into an index entry.
  */
-export function buildManifestBody(repoRoot) {
-  const skillFiles = collectSkillFiles(repoRoot);
+export function buildManifestBody(repoRoot, collect = collectSkillFiles) {
+  const skillFiles = collect(repoRoot);
   const skills = skillFiles.map((absPath) =>
     projectEntry(parseSkill(absPath, { repoRoot })),
   );
@@ -118,8 +138,8 @@ export function buildManifestBody(repoRoot) {
  * Build the full manifest with `generatedAt`. `nowIso` is injected so
  * tests can pin the timestamp deterministically.
  */
-export function buildManifest(repoRoot, { nowIso } = {}) {
-  const body = buildManifestBody(repoRoot);
+export function buildManifest(repoRoot, { nowIso, collect } = {}) {
+  const body = buildManifestBody(repoRoot, collect);
   return {
     generatedAt: nowIso ?? new Date().toISOString(),
     generator: body.generator,
@@ -143,66 +163,147 @@ export function serializeManifest(manifest) {
 }
 
 /**
- * Read the on-disk manifest as a parsed object, or null when missing /
- * unparseable. The --check pipeline distinguishes "missing" (drift) from
- * "unparseable" (drift) via the returned `reason` channel.
+ * Resolve the manifest output path given (root, optional explicit
+ * override).
+ */
+function resolveOutPath(root, override) {
+  return override
+    ? path.resolve(override)
+    : indexPathFor(root, PAYLOAD_SKILLS_SEGMENTS);
+}
+
+/**
+ * Resolve the local-zone manifest path. Deliberately NOT overridable by
+ * `--out`: that flag redirects the payload manifest (tests stage fixture
+ * trees with it), and letting it also move the local manifest would let one
+ * invocation write both indexes to the same file.
+ */
+function resolveLocalOutPath(root) {
+  return indexPathFor(root, LOCAL_SKILLS_SEGMENTS);
+}
+
+/**
+ * Write one manifest through the project formatter so a regeneration on a
+ * clean tree leaves no format drift behind.
  */
-function readOnDiskManifest(outPath) {
-  if (!fs.existsSync(outPath)) {
-    return { manifest: null, reason: 'missing' };
+function writeManifest(manifest, outPath, root) {
+  const serialized = serializeManifest(manifest);
+  const opts = { cwd: root, filename: INDEX_FILENAME };
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(
+    outPath,
+    formatGeneratedJson(serialized, opts) ?? serialized,
+  );
+}
+
+/**
+ * Write (or reap) the local-zone manifest. A consumer who deletes their last
+ * local skill would otherwise be left with a stale index reporting skills
+ * that no longer exist, so an emptied zone removes the artifact rather than
+ * leaving it behind.
+ */
+function writeLocalManifest(localFresh, localOutPath, root) {
+  const rel = path.relative(root, localOutPath).split(path.sep).join('/');
+  if (localFresh === null) {
+    if (fs.existsSync(localOutPath)) {
+      fs.rmSync(localOutPath);
+      Logger.info(`removed ${rel} (no local skills remain)`);
+    }
+    return;
   }
-  let src;
-  try {
-    src = fs.readFileSync(outPath, 'utf8');
-  } catch (err) {
-    return { manifest: null, reason: `read-error: ${err.message}` };
+  writeManifest(localFresh, localOutPath, root);
+  Logger.info(`wrote ${rel} (${localFresh.skills.length} entries)`);
+}
+
+/**
+ * Compare the local-zone manifest against fresh generator output. Returns
+ * null when in sync (including the common case of no local skills and no
+ * artifact), or a diff-style message.
+ */
+function checkLocalManifest(localFresh, localOutPath) {
+  const exists = fs.existsSync(localOutPath);
+  if (localFresh === null) {
+    return exists
+      ? 'local skills.index.json drift detected: the local skills zone is ' +
+          'empty but .agents/local/skills/skills.index.json still exists — ' +
+          "run 'node .agents/scripts/generate-skills-index.js' to reap it"
+      : null;
   }
-  try {
-    return { manifest: JSON.parse(src), reason: null };
-  } catch (err) {
-    return { manifest: null, reason: `parse-error: ${err.message}` };
+  if (!exists) {
+    return (
+      'local skills.index.json drift detected: missing — run ' +
+      "'node .agents/scripts/generate-skills-index.js' to write it"
+    );
   }
+  const { manifest: disk } = readManifest(localOutPath);
+  return diffManifests(disk, localFresh, 'local skills.index.json');
 }
 
 /**
- * Compare two manifests ignoring `generatedAt`. Returns null when they
- * match, or a short diff-style message when they diverge.
+ * Build the local zone's manifest plan for this invocation: its output path,
+ * and a fresh manifest when the consumer has authored any local skill (null
+ * otherwise, which is the signal to reap a stale artifact).
+ *
+ * Split out of `run` so the payload path and the local path each read as one
+ * step there rather than interleaving.
+ *
+ * @param {string} root
+ * @param {Date} now
+ * @returns {{ localFresh: object | null, localOutPath: string }}
  */
-function diffManifestsIgnoringTimestamp(diskManifest, freshManifest) {
-  if (diskManifest === null) {
-    return 'on-disk manifest is missing or unreadable';
-  }
-  const a = { ...diskManifest };
-  const b = { ...freshManifest };
-  delete a.generatedAt;
-  delete b.generatedAt;
-  const sa = JSON.stringify(a);
-  const sb = JSON.stringify(b);
-  if (sa === sb) return null;
-  // Surface a structural summary rather than a full JSON dump.
-  const diskCount = Array.isArray(diskManifest.skills)
-    ? diskManifest.skills.length
-    : 'n/a';
-  const freshCount = Array.isArray(freshManifest.skills)
-    ? freshManifest.skills.length
-    : 'n/a';
-  const summary = [
-    'skills.index.json drift detected:',
-    `  on-disk entries:  ${diskCount}`,
-    `  generated entries: ${freshCount}`,
-    "  run 'node .agents/scripts/generate-skills-index.js' to refresh",
-  ].join('\n');
-  return summary;
+function buildLocalPlan(root, now) {
+  const localOutPath = resolveLocalOutPath(root);
+  const localFresh =
+    collectLocalSkillFiles(root).length > 0
+      ? buildManifest(root, {
+          nowIso: now.toISOString(),
+          collect: collectLocalSkillFiles,
+        })
+      : null;
+  return { localFresh, localOutPath };
 }
 
 /**
- * Resolve the manifest output path given (root, optional explicit
- * override).
+ * Render the freshness line's entry counts, naming the local zone only when
+ * one exists.
+ *
+ * @param {object} fresh
+ * @param {object | null} localFresh
+ * @returns {string}
  */
-function resolveOutPath(root, override) {
-  return override
-    ? path.resolve(override)
-    : path.join(root, '.agents', 'skills', 'skills.index.json');
+function describeCounts(fresh, localFresh) {
+  const base = `${fresh.skills.length} entries`;
+  return localFresh === null
+    ? base
+    : `${base}, ${localFresh.skills.length} local`;
+}
+
+/**
+ * `--check` mode: compare both manifests against fresh generator output and
+ * report the first drift found, payload first.
+ *
+ * Lives outside `run` so the entry point reads as "resolve inputs, then check
+ * or write" — and so the check path's branches are not charged to a function
+ * that also owns argument resolution.
+ *
+ * @param {{ outPath: string, fresh: object, localOutPath: string, localFresh: object | null }} plan
+ * @returns {{ status: number, output: string }}
+ */
+function checkBothManifests({ outPath, fresh, localOutPath, localFresh }) {
+  const { manifest: disk, reason } = readManifest(outPath);
+  if (disk === null) {
+    return { status: 1, output: `${INDEX_FILENAME} drift detected: ${reason}` };
+  }
+  const drift =
+    diffManifests(disk, fresh, INDEX_FILENAME) ??
+    checkLocalManifest(localFresh, localOutPath);
+  if (drift !== null) {
+    return { status: 1, output: drift };
+  }
+  Logger.info(
+    `${INDEX_FILENAME} is fresh (${describeCounts(fresh, localFresh)})`,
+  );
+  return { status: 0, output: '' };
 }
 
 /**
@@ -225,35 +326,17 @@ export function run({ argv = [], now = new Date(), repoRoot } = {}) {
     : (repoRoot ?? defaultRepoRoot());
   const outPath = resolveOutPath(root, parsed.out);
   const fresh = buildManifest(root, { nowIso: now.toISOString() });
+  const { localFresh, localOutPath } = buildLocalPlan(root, now);
 
   if (parsed.check) {
-    const { manifest: disk, reason } = readOnDiskManifest(outPath);
-    if (disk === null) {
-      return {
-        status: 1,
-        output: `skills.index.json drift detected: ${reason}`,
-      };
-    }
-    const diff = diffManifestsIgnoringTimestamp(disk, fresh);
-    if (diff === null) {
-      Logger.info(
-        `skills.index.json is fresh (${fresh.skills.length} entries)`,
-      );
-      return { status: 0, output: '' };
-    }
-    return { status: 1, output: diff };
+    return checkBothManifests({ outPath, fresh, localOutPath, localFresh });
   }
 
-  const serialized = serializeManifest(fresh);
-  const opts = { cwd: root, filename: 'skills.index.json' };
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(
-    outPath,
-    formatGeneratedJson(serialized, opts) ?? serialized,
-  );
+  writeManifest(fresh, outPath, root);
   Logger.info(
     `wrote ${path.relative(root, outPath).split(path.sep).join('/')} (${fresh.skills.length} entries)`,
   );
+  writeLocalManifest(localFresh, localOutPath, root);
   return { status: 0, output: '' };
 }
 

package/.agents/scripts/lib/audit-to-stories/epic-grouping-directive.js

@@ -0,0 +1,39 @@
+/**
+ * epic-grouping-directive.js — the container-Epic directive an audit sweep
+ * emits (Story #5139).
+ *
+ * Lives on its own because **both** `/audit-to-stories` output paths carry it:
+ * the `/mandrel-plan` seed one-pager (`seed-from-findings.js`) and the
+ * standalone Story-draft transcript (`audit-to-stories.js`). A sweep is the
+ * clearest case for a container — every Story shares a provenance and the
+ * operator almost always wants them delivered together — so the Epic is the
+ * **default** here, unlike the offer `/mandrel-plan` makes on an ad-hoc plan.
+ *
+ * It stays a directive in the text rather than an automatic write: the
+ * workflow's Phase 4 HITL stop is where an operator declines it.
+ *
+ * @module lib/audit-to-stories/epic-grouping-directive
+ */
+
+import { EPIC_SUGGESTION_THRESHOLD } from '../orchestration/plan-persist/epic-ops.js';
+
+/**
+ * Render the grouping directive for a proposed Story set.
+ *
+ * @param {unknown[]} groups The proposed Stories (only the count is read).
+ * @returns {string} Markdown paragraph(s).
+ */
+export function formatEpicGrouping(groups) {
+  const count = Array.isArray(groups) ? groups.length : 0;
+  if (count < EPIC_SUGGESTION_THRESHOLD) {
+    const noun = count === 1 ? 'Story' : 'Stories';
+    return `This sweep proposes ${count} ${noun} — below the ${EPIC_SUGGESTION_THRESHOLD}-Story threshold, so no container Epic is needed.`;
+  }
+  return [
+    `**Group these under a container Epic.** This sweep proposes ${count} Stories from one audit pass, which is exactly the case a container earns: they share a provenance and an operator will want to deliver them as a unit.`,
+    '',
+    'The Epic is a **pure container** — a title, a one-paragraph goal, and the child checklist. It must carry no finding, no path and no rationale that is not already in a child Story, or that information ends up somewhere no delivering agent reads.',
+    '',
+    'Decline it and file the Stories flat if the operator prefers.',
+  ].join('\n');
+}

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

@@ -0,0 +1,290 @@
+/**
+ * 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 dated `chore/audit-ledger-<YYYY-MM-DD>` branch, 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.
+ */
+
+import { gh as defaultGh } from '../gh-exec.js';
+import { gitSync } from '../git-utils.js';
+import { DEFAULT_LEDGER_PATH } from './ledger.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}
+ */
+function isoDate(now) {
+  const date = now instanceof Date ? now : new Date(now ?? Date.now());
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * 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.
+ * @param {string} [explicit]
+ * @returns {Promise<string>}
+ */
+async function resolveBaseBranch(explicit) {
+  if (typeof explicit === 'string' && explicit.length > 0) return explicit;
+  try {
+    const { resolveConfig } = await import('../config-resolver.js');
+    const branch = resolveConfig()?.project?.baseBranch;
+    if (typeof branch === 'string' && branch.length > 0) return branch;
+  } catch (_) {
+    // fall through to the default
+  }
+  return DEFAULT_BASE_BRANCH;
+}
+
+/**
+ * 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 below uses {@link runStep} instead, where a
+ * failure IS fatal.
+ * @param {(cwd: string, ...args: string[]) => string} git
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {string} trimmed stdout, or `''` when git failed.
+ */
+function probeGit(git, cwd, args) {
+  try {
+    const out = git(cwd, ...args);
+    return typeof out === 'string' ? out.trim() : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+/**
+ * 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>}
+ */
+async function runStep(name, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw new Error(
+      `--ledger-commit failed at step "${name}": ${error?.message ?? error}`,
+      { cause: error },
+    );
+  }
+}
+
+/**
+ * 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.
+ *
+ * @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.cwd]
+ * @param {(cwd: string, ...args: string[]) => string} [params.git]
+ * @returns {Promise<{ ledgerPath: string, baseBranch: string, changed: boolean,
+ *   hasOrigin: boolean, headBranch: string, onBaseBranch: boolean,
+ *   unpersisted: boolean }>}
+ */
+async function assessLedgerPersistence({
+  ledgerPath = DEFAULT_LEDGER_PATH,
+  baseBranch,
+  cwd = process.cwd(),
+  git = gitSync,
+} = {}) {
+  const base = await resolveBaseBranch(baseBranch);
+  const changed =
+    probeGit(git, cwd, ['status', '--porcelain', '--', ledgerPath]).length > 0;
+  const hasOrigin = probeGit(git, cwd, ['remote'])
+    .split('\n')
+    .map((line) => line.trim())
+    .includes('origin');
+  const headBranch = probeGit(git, cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const onBaseBranch = headBranch === base;
+
+  return {
+    ledgerPath,
+    baseBranch: base,
+    changed,
+    hasOrigin,
+    headBranch,
+    onBaseBranch,
+    unpersisted: changed && (!hasOrigin || !onBaseBranch),
+  };
+}
+
+/**
+ * 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}
+ */
+function unpersistedWarning(state) {
+  const cause = state.hasOrigin
+    ? `HEAD is on "${state.headBranch || '(detached)'}", not the base branch "${state.baseBranch}"`
+    : 'this checkout has no "origin" remote';
+  return `ledger not persisted: ${state.ledgerPath} changed but ${cause}, so this sweep's memory will be lost when the checkout goes away. Re-run with --ledger-commit to open a PR for it, or commit ${state.ledgerPath} by hand.`;
+}
+
+/**
+ * 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.
+ *
+ * @param {object} [params]
+ * @param {object|null} [params.ledger] — the plan's ledger summary, or null.
+ * @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 {string} [params.cwd]
+ * @param {(cwd: string, ...args: string[]) => string} [params.git]
+ * @param {{ warn: Function }} [params.logger]
+ * @returns {Promise<object|null>} the (possibly annotated) ledger summary.
+ */
+export async function resolveLedgerSummary({
+  ledger = null,
+  ledgerPath = DEFAULT_LEDGER_PATH,
+  dryRun,
+  ledgerCommit,
+  cwd,
+  git,
+  logger,
+} = {}) {
+  if (dryRun || ledgerCommit) return ledger;
+  const state = await assessLedgerPersistence({ ledgerPath, cwd, git });
+  if (!state.unpersisted) return ledger;
+  logger?.warn?.(unpersistedWarning(state));
+  return { ...(ledger ?? { path: ledgerPath }), unpersisted: true };
+}
+
+/**
+ * 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}
+ */
+function pullRequestBody(ledgerPath, date) {
+  return [
+    `Reconciles the cross-run audit ledger (\`${ledgerPath}\`) written by the`,
+    `unattended \`audit-to-stories --auto\` sweep on ${date}.`,
+    '',
+    'Ledger-only change — no source, workflow or documentation file is touched.',
+    'Merging it is what gives the next sweep a memory: without it the ledger',
+    'dies with the checkout and every later run re-proposes findings this one',
+    'already filed, and re-surfaces findings a human already rejected.',
+    '',
+    'Auto-merge is deliberately not requested: the ledger records machine-derived',
+    'lifecycle state, and a human glance before it lands is the point.',
+  ].join('\n');
+}
+
+/**
+ * Commit the changed ledger onto a dated branch and open a PR for it.
+ *
+ * Skipped — returning `{ committed: false }` with a `reason` — when the ledger
+ * did not change. 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.
+ *
+ * @param {object} [params]
+ * @param {string} [params.ledgerPath]
+ * @param {string} [params.baseBranch]
+ * @param {string} [params.cwd]
+ * @param {(cwd: string, ...args: string[]) => string} [params.git]
+ * @param {{ pr: { create: (flags: string[]) => Promise<unknown> } }} [params.gh]
+ * @param {Date|string|number} [params.now]
+ * @returns {Promise<{ committed: boolean, reason?: string, branch?: string,
+ *   subject?: string, baseBranch?: string, ledgerPath: string }>}
+ */
+export async function runLedgerCommit({
+  ledgerPath = DEFAULT_LEDGER_PATH,
+  baseBranch,
+  cwd = process.cwd(),
+  git = gitSync,
+  gh = defaultGh,
+  now,
+} = {}) {
+  const state = await assessLedgerPersistence({
+    ledgerPath,
+    baseBranch,
+    cwd,
+    git,
+  });
+  if (!state.changed) {
+    return { committed: false, reason: 'ledger-unchanged', ledgerPath };
+  }
+
+  const date = isoDate(now);
+  const branch = `chore/audit-ledger-${date}`;
+  const subject = `chore(audit): reconcile audit ledger ${date}`;
+
+  await runStep('create-branch', () => git(cwd, 'checkout', '-b', branch));
+  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.
+  await runStep('commit-ledger', () =>
+    git(cwd, 'commit', '-m', subject, '--', ledgerPath),
+  );
+  await runStep('push-branch', () =>
+    git(cwd, 'push', '--set-upstream', 'origin', branch),
+  );
+  await runStep('open-pull-request', () =>
+    gh.pr.create([
+      '--base',
+      state.baseBranch,
+      '--head',
+      branch,
+      '--title',
+      subject,
+      '--body',
+      pullRequestBody(ledgerPath, date),
+    ]),
+  );
+
+  return {
+    committed: true,
+    branch,
+    subject,
+    baseBranch: state.baseBranch,
+    ledgerPath,
+  };
+}