plumbbob 0.8.18 → 0.9.1

package/dist/verbs/finish.js

@@ -1,17 +1,27 @@
-// `plumbbob finish` (D9/D68) — the close-out: append the checkpoint SHAs to the
-// report, make the final commit, and clear the control state. The build folder is
-// NOT deleted — it IS the archive now (D29): tracked, it merges with the branch and
-// shows up in the PR, so nothing is copied into a local-only `archive/` (that
-// helper retired with this step). No refuse-without-report gate — guidance offers
-// the artifact, it does not wall the exit (D9). Git footprint stays additive (C5):
-// one forward commit under the Conventional `chore(<scope>): finish` subject, its
-// `plumbbob finish` identifier riding the body marker (D68).
+// `plumbbob finish` — the close-out. It appends the checkpoint SHAs and per-step
+// stats to report.md, makes the final commit, and clears the control state (the
+// untracked session and step markers under `.plumbbob/`). The build folder is NOT
+// deleted — the tracked `.plumbbob/builds/<slug>/` folder IS the archive: it
+// merges with the branch and shows up in the PR, so nothing is copied into a
+// separate local archive. A missing report never blocks the exit — guidance
+// offers the artifact, it does not wall the door. The git footprint stays
+// additive: one forward commit under the Conventional `chore(<scope>): finish`
+// subject, with the `plumbbob finish` identifier riding a marker line at the head
+// of the body so `git log --grep plumbbob` still finds it.
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
 import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 import { parseBuildScope } from "../lib/intent.js";
+/**
+ * Close out the active build: report tail, final commit, control-state cleanup.
+ *
+ * Requires an active session (the `.plumbbob/STATE` sentinel). When report.md
+ * exists it gains a `## Checkpoints` SHA list and a `## Stats` table first; when
+ * it doesn't, finish notes the absence and proceeds — the exit is never gated on
+ * a report.
+ */
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -25,46 +35,56 @@ export function finish(cwd, args = []) {
     }
     else {
         process.stderr.write('plumbbob: note — no report.md found; finishing without one ' +
-            '(/pb-finish normally writes the report first). No gate (D9).\n');
+            '(/plumbbob:finish normally writes the report first). No gate (D9).\n');
     }
-    // The final commit (D34): stage the report just written plus the build folder's
-    // tail (the last step's checkpoint line lands one commit late, D37) and commit it
-    // under the greppable `finish` subject. `--allow-empty` (via `commit`) still marks
-    // the narrative endpoint when the tree is already clean, or under `--local`, where
-    // the whole sidecar is excluded and there is nothing tracked to stage.
+    // The final commit: stage the report just written plus the build folder's tail —
+    // a step's commit sweeps its own bookkeeping along with the work, so the last
+    // step's `checkpoints` line lands one commit late and finish absorbs it — and
+    // commit under the `finish` subject. `--allow-empty` (via `commit`) still marks
+    // the narrative endpoint when the tree is already clean, or under `--local`,
+    // where the whole sidecar is git-excluded and there is nothing tracked to stage.
     if (isDirty(root)) {
         stageAll(root);
     }
     const sha = commit(root, subject(root, slug), withMarker('plumbbob finish', bodyArg(args) ?? undefined));
-    // Clear the control state: the in-flight markers first, then the session sentinel
-    // last (so "no session" flips exactly at the end). Deleting STATE also drops the
-    // cursor (D28) — cursor and session share the one file now, so a single delete does
-    // both. The tracked artifacts stay in place — only the ephemera go.
+    // Clear the control state: the in-flight markers first, then the session
+    // sentinel last (so "no session" flips exactly at the end). Deleting STATE also
+    // drops the active-build cursor — cursor and session share that one file, so a
+    // single delete does both. The tracked artifacts stay in place — only the
+    // ephemera go.
     rmSync(seamPath(root, slug), { force: true });
     rmSync(stepPath(root, slug), { force: true });
     rmSync(spikePath(root, slug), { force: true });
-    // The latch's per-build entry stamp and the one-turn grant go with the session
-    // (D64/D65): a grant is one-turn by construction, but the session's last tick is
-    // the last time it was rewritten — left behind, a stale `auto` could self-approve
-    // the next session's first landing.
+    // The checkpoint latch's per-build entry stamp and the one-turn self-approval
+    // grant go with the session: a grant lives one turn by construction, but only
+    // because every tick rewrites it — the session's last tick was the last rewrite,
+    // so left behind, a stale `auto` could self-approve the next session's first
+    // landing.
     clearTick(root, slug);
     setGrant(root, null);
     rmSync(join(sidecarDir(root), 'STATE'), { force: true });
     const where = slug === null ? '.plumbbob/' : `.plumbbob/builds/${slug}/`;
     process.stdout.write(`plumbbob: finished — ${sha.slice(0, 9)}. ${where} rides your branch into the PR. ` +
-        'Run `/pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
+        'Run `/plumbbob:plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
     return 0;
 }
-// The CLI-owned final-commit subject (D68): `chore(<scope>): finish`, the scope
-// resolved through the same build-default fallback chain as plan/step subjects
-// (D3/D4): the `**Scope:**` header field, else the build slug, else bare (e.g.
-// `--local`). The `plumbbob finish` identifier rides the body marker, not the
-// subject.
+/**
+ * The CLI-owned final-commit subject: `chore(<scope>): finish`.
+ *
+ * The scope resolves through the same build-default fallback chain as the plan
+ * and step subjects: the intent.md `**Scope:**` header field, else the build
+ * slug, else bare (e.g. `--local`). The `plumbbob finish` identifier rides the
+ * body marker, not the subject.
+ */
 function subject(root, slug) {
     return conventionalSubject({ type: 'chore', scope: buildDefaultScope(root, slug), description: 'finish' });
 }
-// See checkpoint.ts's twin of this helper (same fallback, this verb's own `slug`
-// resolution instead of the active-build cursor).
+/**
+ * Resolve the commit scope: the intent.md `**Scope:**` header, else the slug.
+ *
+ * Twin of checkpoint.ts's helper — same fallback chain, but with this verb's own
+ * `slug` resolution instead of the active-build cursor.
+ */
 function buildDefaultScope(root, slug) {
     try {
         const fromHeader = parseBuildScope(readFileSync(intentPath(root, slug), 'utf8'));
@@ -77,12 +97,17 @@ function buildDefaultScope(root, slug) {
     }
     return buildScope(slug);
 }
-// `--body` reads the final-commit body from stdin (the single-quoted heredoc of
-// D34), so the pb-finish skill can compose a proportional close-out message. Returns
-// null when the flag is absent or stdin is empty — the commit then carries subject
-// only. Reading fd 0 blocks until EOF, which the heredoc supplies; a read error (no
-// stdin attached) degrades to null, and an interactive TTY — which would never send
-// EOF — skips the read instead of hanging (twin of checkpoint.ts's guard).
+/**
+ * Read the `--body` final-commit body from stdin, or null.
+ *
+ * The body arrives as a single-quoted stdin heredoc — the CLI owns every commit
+ * subject, but the finish skill composes a proportional close-out body this
+ * way. Returns null when the flag is absent or stdin is empty; the commit then
+ * carries subject only. Reading fd 0 blocks until EOF, which the heredoc
+ * supplies; a read error (no stdin attached) degrades to null, and an
+ * interactive TTY — which would never send EOF — skips the read instead of
+ * hanging (twin of checkpoint.ts's guard).
+ */
 function bodyArg(args) {
     if (!args.includes('--body') || process.stdin.isTTY === true) {
         return null;
@@ -95,10 +120,14 @@ function bodyArg(args) {
         return null;
     }
 }
-// Roll the per-step receipts (research/07 Build 2b) into report.md as a `## Stats`
-// table — one row per step plus totals, so "is the loop worth it?" is a table,
-// not a feeling. Silently skipped when nothing accrued (an old build, a build
-// with no red/revert/drift and no `build <n>` stamps has nothing to say).
+/**
+ * Roll the per-step receipts into report.md as a `## Stats` table.
+ *
+ * One row per step plus totals — red checks, drift warnings, reverts,
+ * wall-clock — so "is the loop worth it?" is a table, not a feeling. Silently
+ * skipped when nothing accrued (a build with no red/revert/drift and no
+ * `build <n>` stamps has nothing to say).
+ */
 function appendStats(root, slug) {
     const stats = readStats(root, slug);
     const steps = Object.keys(stats)
@@ -129,6 +158,10 @@ function appendStats(root, slug) {
         '',
     ].join('\n'));
 }
+/**
+ * Milliseconds from a step's entry stamp to its landing stamp, or null when
+ * either timestamp is missing or malformed.
+ */
 function wallClockMs(s) {
     if (s.startedAt === undefined || s.landedAt === undefined) {
         return null;
@@ -136,17 +169,25 @@ function wallClockMs(s) {
     const ms = Date.parse(s.landedAt) - Date.parse(s.startedAt);
     return Number.isFinite(ms) && ms >= 0 ? ms : null;
 }
-// `—` when unknown (a hand-built step never ran `build <n>`, so it has no
-// startedAt), `<1m` under a minute, whole minutes otherwise.
+/**
+ * Format a wall-clock duration for the stats table.
+ *
+ * `—` when unknown (a hand-built step never ran `build <n>`, so it has no
+ * startedAt), `<1m` under a minute, whole minutes otherwise.
+ */
 function formatWall(ms) {
     if (ms === null) {
         return '—';
     }
     return ms < 60_000 ? '<1m' : `${Math.round(ms / 60_000)}m`;
 }
-// Append the recorded checkpoints (baseline + each `step n <sha>`) to report.md as a
-// `## Checkpoints` section, so the report — which now rides the branch into the PR —
-// lists the SHAs. Best-effort: an unreadable checkpoints file yields an empty list.
+/**
+ * Append the recorded checkpoints (baseline + each `step n <sha>`) to report.md
+ * as a `## Checkpoints` section.
+ *
+ * The report rides the branch into the PR, so it carries the SHAs with it.
+ * Best-effort: an unreadable checkpoints file yields an empty list.
+ */
 function appendCheckpointShas(root, slug) {
     let raw = '';
     try {

package/dist/verbs/handoff.js

@@ -1,15 +1,24 @@
-// `plumbbob handoff` — print the standardized build hand-off block (D67): the
+// `plumbbob handoff` — print the standardized build hand-off block: the
 // "state / choice / what's next" the human sees at each step boundary. Read-only,
 // no state change. It derives the moment from the session — a step in flight ⇒ the
 // pause block (built → looks-good/needs-work → next), none ⇒ the post-checkpoint
 // boundary block — and renders the next undone step plus its advisory `- model:`
-// recommendation straight from intent.md. This block lived as prose in pb-build's
-// SKILL.md; owning it here keeps the skill from drifting out of sync with `status`,
-// which renders the same next-step detail (both read `parseSteps`).
+// recommendation straight from intent.md, the build's plan document. Owning the
+// block here, rather than as prose in the build skill, keeps the skill from
+// drifting out of sync with `status`, which renders the same next-step detail
+// (both read `parseSteps`).
 import { readFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { checkpointsPath, hasSession, intentPath, resolveBuild, stepPath } from "../lib/sidecar.js";
 import { parseLastCheckpoint, parseSteps } from "../lib/orient.js";
+/**
+ * Print the hand-off block for the resolved build; return the exit code.
+ *
+ * Requires an active session (the STATE sentinel under `.plumbbob/`). Which
+ * moment to render is derived, not passed: a step in flight yields the pause
+ * block, none yields the boundary block, and a fresh session with nothing to
+ * report yields only the forward pointer.
+ */
 export function handoff(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -40,9 +49,12 @@ export function handoff(cwd, args = []) {
     process.stdout.write(`${block}\n`);
     return 0;
 }
-// The pause block: the step is built and awaiting approval. The opener is neutral
-// (the CLI cannot vouch for the diff), pointing at the diff and self-review the
-// skill shows above it.
+/**
+ * The pause block: the step is built and awaiting approval.
+ *
+ * The opener is neutral (the CLI cannot vouch for the diff), pointing at the
+ * diff and self-review the skill shows above it.
+ */
 function pauseBlock(step, title, nextUp) {
     return [
         `Step ${step}${paren(title)} is built. Review the diff and self-review above, then:`,
@@ -52,38 +64,57 @@ function pauseBlock(step, title, nextUp) {
         nextUpLine(nextUp),
     ].join('\n');
 }
-// The boundary block: the checkpoint has landed and the loop is back at the
-// step boundary, pointing at what to build next.
+/**
+ * The boundary block: the checkpoint has landed and the loop is back at the
+ * step boundary, pointing at what to build next.
+ */
 function boundaryBlock(step, title, nextUp) {
     return [`Step ${step}${paren(title)} checkpointed — back at the boundary.`, '', nextUpLine(nextUp)].join('\n');
 }
-// The forward pointer, shared by both blocks: the next undone step, its title, and
-// its advisory `- model:` recommendation (as just the model token for the `/model`
-// call — the full rationale lives on the `status` dashboard). No next step ⇒ the
-// finish/step nudge instead.
+/**
+ * The forward pointer, shared by both blocks: the next undone step, its title,
+ * and its advisory `- model:` recommendation.
+ *
+ * The recommendation renders as just the model token for the `/model` call —
+ * the full rationale lives on the `status` dashboard. No next step ⇒ the
+ * finish/step nudge instead.
+ */
 function nextUpLine(nextUp) {
     if (nextUp === undefined) {
-        return 'No planned steps remain — /pb-step to add an increment, or /pb-finish.';
+        return 'No planned steps remain — /plumbbob:step to add an increment, or /plumbbob:finish.';
     }
     const head = `Next up: step ${nextUp.n}${paren(nextUp.title)}`;
     const token = modelToken(nextUp.model);
-    return token === null ? `${head} — /pb-build to start it.` : `${head} · model: ${token} — /model ${token} then /pb-build.`;
+    return token === null ? `${head} — /plumbbob:build to start it.` : `${head} · model: ${token} — /model ${token} then /plumbbob:build.`;
 }
-// A step's title in parentheses, or nothing when the title is empty.
+/**
+ * A step's title in parentheses, or nothing when the title is empty.
+ */
 function paren(title) {
     return title !== null && title.length > 0 ? ` (${title})` : '';
 }
+/**
+ * The title of step `n` from the parsed steps, or null when the step is
+ * unknown or untitled.
+ */
 function titleOf(steps, n) {
     return steps.find((s) => s.n === n)?.title ?? null;
 }
-// The model token from a `- model:` recommendation — the first word, so a
-// `model: opus — <rationale>` line yields `opus` for the `/model` call. Null when
-// there is no recommendation, or it degraded to whitespace (folding the null model
-// into the same guard keeps both branches live).
+/**
+ * The model token from a `- model:` recommendation — the first word, so a
+ * `model: opus — <rationale>` line yields `opus` for the `/model` call.
+ *
+ * Null when there is no recommendation, or it degraded to whitespace (folding
+ * the null model into the same guard keeps both branches live).
+ */
 function modelToken(model) {
     const first = model?.trim().split(/\s+/)[0];
     return first !== undefined && first.length > 0 ? first : null;
 }
+/**
+ * Read a file as UTF-8, or return '' when it is missing or unreadable — an
+ * absent sidecar file reads as empty rather than throwing.
+ */
 function readOr(path) {
     try {
         return readFileSync(path, 'utf8');
@@ -92,6 +123,11 @@ function readOr(path) {
         return '';
     }
 }
+/**
+ * The in-flight step number from the STEP marker — the flat one-line file in
+ * the build folder that records which step is open. Null when no step is in
+ * flight or the file holds anything but a bare number.
+ */
 function readStep(path) {
     try {
         const raw = readFileSync(path, 'utf8').trim();

package/dist/verbs/init.js

@@ -2,14 +2,14 @@
 // in-place skills-directory plugin. It symlinks the installed package into
 // ~/.claude/skills/plumbbob, where Claude Code discovers it as `plumbbob@skills-dir`
 // — the skills load namespaced (`/plumbbob:*`) and the post-edit hook auto-registers
-// from hooks/hooks.json. This is the deliberate non-marketplace install path — kept
-// first-class, not deprecated: it serves an `npm i -g` global, local dev, and clients
-// predating plugins, and keeps plumbbob usable as a standalone CLI (and, later, under
-// other agents) rather than Claude-marketplace-only. The marketplace plugin is the
+// from hooks/hooks.json. This non-marketplace install path is first-class by design:
+// it serves an `npm i -g` global, local dev, and clients predating plugins, and it
+// keeps plumbbob usable as a standalone CLI outside any one host rather than
+// Claude-marketplace-only. The marketplace plugin is the
 // co-equal self-contained alternative (it ships skills AND the `plumbbob` CLI on PATH
 // via bin/, so it needs neither `npm i -g` nor `init`). The two are mutually
 // exclusive: both register a plugin named `plumbbob`, and a double-install collides
-// over the /plumbbob:* namespace (skills can drop to flat `/pb-status` names). So init
+// over the /plumbbob:* namespace (skills can drop to flat `/status` names). So init
 // REFUSES when a marketplace plumbbob is already installed — `--force` overrides
 // (the dev-install path uses it). Global-only by design: install scope is NOT session
 // scope — sessions stay per-project via `plumbbob start`. Idempotent + reversible
@@ -19,17 +19,28 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { marketplacePlumbbob } from "../lib/plugins.js";
-// The installed package root (parent of .claude-plugin/, skills/, hooks/, dist/),
-// off this module's URL — the global install when run as the published bin, the
-// checkout in dev. No trailing slash, so it compares clean against a readlink.
+/**
+ * The installed package root — parent of .claude-plugin/, skills/, hooks/, dist/.
+ *
+ * Derived from this module's URL: the global install when run as the published
+ * bin, the checkout in dev. No trailing slash, so it compares clean against a
+ * readlink.
+ */
 function packageRoot() {
     return fileURLToPath(new URL('../../', import.meta.url)).replace(/\/+$/, '');
 }
+/**
+ * The symlink location Claude Code scans for skills-directory plugins.
+ */
 function linkPath(home) {
     return join(home, '.claude', 'skills', 'plumbbob');
 }
-// lstat-based existence: true even for a broken symlink (existsSync follows the
-// link and would miss one whose target moved).
+/**
+ * Whether anything exists at `path`, including a broken symlink.
+ *
+ * lstat-based: existsSync follows the link and would miss one whose target
+ * moved.
+ */
 function present(path) {
     try {
         lstatSync(path);
@@ -39,7 +50,9 @@ function present(path) {
         return false;
     }
 }
-// The symlink's target (no trailing slash), or null if `path` is not a symlink.
+/**
+ * The symlink's target (no trailing slash), or null if `path` is not a symlink.
+ */
 function symlinkTarget(path) {
     try {
         return lstatSync(path).isSymbolicLink() ? readlinkSync(path).replace(/\/+$/, '') : null;
@@ -48,6 +61,14 @@ function symlinkTarget(path) {
         return null;
     }
 }
+/**
+ * Link the installed package into ~/.claude/skills/plumbbob, or `--uninstall` it.
+ *
+ * Refuses when a marketplace plumbbob plugin is already installed — two plugins
+ * named `plumbbob` collide over the /plumbbob:* namespace — unless `--force`.
+ * Repoints a stale link from an earlier install location; already-linked is a
+ * clean exit 0.
+ */
 export function init(args) {
     const home = process.env.HOME ?? homedir();
     const link = linkPath(home);
@@ -59,7 +80,7 @@ export function init(args) {
     if (market.length > 0 && !args.includes('--force')) {
         process.stderr.write(`plumbbob: a marketplace plumbbob plugin is already installed (${market.join(', ')}).\n` +
             'plumbbob: it already provides the skills (`/plumbbob:*`) and the `plumbbob` CLI on PATH (the plugin bin/) — no `plumbbob init` needed.\n' +
-            `plumbbob: linking ${link} would register a SECOND plugin named \`plumbbob\`; the two collide over the /plumbbob:* namespace and skills can drop to flat names (\`/pb-status\`).\n` +
+            `plumbbob: linking ${link} would register a SECOND plugin named \`plumbbob\`; the two collide over the /plumbbob:* namespace and skills can drop to flat names (\`/status\`).\n` +
             'plumbbob: to use the skills-dir link instead, first remove the marketplace one (`/plugin uninstall plumbbob@<marketplace>`), or re-run with `--force` if you know what you are doing.\n');
         return 1;
     }
@@ -82,6 +103,10 @@ export function init(args) {
         'plumbbob: nothing else under ~ is touched and settings.json is left alone. Sessions are per-project — run `plumbbob start "<goal>"` in any repo, then `plumbbob doctor` to verify.\n');
     return 0;
 }
+/**
+ * Remove the skills-directory link, leaving anything that is not a plumbbob
+ * symlink untouched.
+ */
 function uninstall(link) {
     if (!present(link)) {
         process.stdout.write(`plumbbob: nothing to uninstall — no link at ${link}.\n`);

package/dist/verbs/park.js

@@ -1,10 +1,21 @@
-// `plumbbob park "<text>"` — the dumb capture path: append one raw line under
-// the build-log's Park list. No model turn, no composition (that is /pb-park's job).
-// Capture is not a transition, so it runs in any context (terminal or in-session).
+// `plumbbob park "<text>"` — the raw capture path for a thought you don't want
+// to chase mid-step: append one flat line under the "## Park list" section of
+// build-log.md (the build's human-facing ledger). Capture stays dumb by design —
+// a grep-readable append, no markdown parsing, no model turn (wording the line
+// well is /plumbbob:park's job); triage waits for a step boundary, via harvest.
+// Capture is not a state transition, so it runs in any context (terminal or
+// in-session).
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession, buildLogPath } from "../lib/sidecar.js";
 import { appendToSection } from "../lib/buildlog.js";
+/**
+ * Append the given text as one unchecked `- [ ]` line to the build-log's Park list.
+ *
+ * All non-flag args join into a single line. Refuses when there is no active
+ * session, when the text is empty, or when build-log.md lacks a "## Park list"
+ * section — a park line must never vanish silently.
+ */
 export function park(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {

package/dist/verbs/revert.js

@@ -1,12 +1,14 @@
 // `plumbbob revert [--to n]` — git reset --hard to a checkpoint SHA (the most
 // recent step, or `--to n`, with the baseline as fallback), then remove untracked
-// files under the SEAM only. The artifact plane (`.plumbbob/builds/<slug>/`) is now
-// TRACKED (D26), so a bare reset WOULD discard park lines and intent edits — or, when
-// reverting to a baseline that predates the build folder, delete the folder wholesale.
-// So revert snapshots the sidecar to temp and restores it as uncommitted changes
-// after the reset (D26), keeping C4/never-destroy intact across both cases. The
-// untracked cleanup additionally whitelists the artifact plane, so no seam pattern
-// can ever sweep away a build's own files.
+// files under the SEAM only (the seam is the in-flight step's flat list of
+// granted edit paths). The artifact plane — the tracked `.plumbbob/builds/<slug>/`
+// folder holding intent, build-log, checkpoints, and park lines — would not
+// survive a bare reset: it would discard park lines and intent edits, or, when
+// reverting to a baseline that predates the build folder, delete the folder
+// wholesale. So revert snapshots the sidecar to temp and restores it as
+// uncommitted changes after the reset — a rewind must never destroy recorded
+// work, in either case. The untracked cleanup additionally whitelists the
+// artifact plane, so no seam pattern can ever sweep away a build's own files.
 //
 // Plumbbob also installs its driver skills INTO the repo (.claude/skills/<driver>/
 // for a self-contained install), so a blunt reset would discard an out-of-seam
@@ -21,6 +23,15 @@ import { findRepoRoot, resetHard, untrackedPaths } from "../lib/git.js";
 import { bumpStepStat, checkpointsPath, hasSession, resolveBuild, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
 import { isArtifactPath, matchesSeam } from "../lib/intent.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
+/**
+ * Rewind to a recorded checkpoint and return the build to the boundary.
+ *
+ * Requires an active session (the `.plumbbob/STATE` sentinel). Resolves the
+ * target SHA from the checkpoints ledger (latest step, `--to n`, or the
+ * baseline), resets hard while preserving plumbbob-owned paths, removes
+ * untracked files inside the seam, clears the in-flight STEP/SEAM markers, and
+ * re-renders the build-log. Exit 1 with a hint on any refusal.
+ */
 export function revert(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -54,9 +65,9 @@ export function revert(cwd, args) {
     // ignored files alone, so they must be removed explicitly afterward).
     const seam = readSeamTokens(root, slug);
     const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam) && !isArtifactPath(p));
-    // The dogfood receipt (research/07 2b): a revert against an in-flight step is a
-    // datapoint — read the marker before it goes, bump after the reset (the sidecar
-    // is preserved through it, so the write survives).
+    // A revert against an in-flight step is a datapoint the finish report's stats
+    // table wants — read the STEP marker before it goes, bump the counter after
+    // the reset (the sidecar is preserved through it, so the write survives).
     const inFlight = readInFlightStep(root, slug);
     resetPreserving(root, sha, plumbbobOwnedPaths(root));
     for (const rel of toRemove) {
@@ -67,19 +78,26 @@ export function revert(cwd, args) {
     if (inFlight !== null) {
         bumpStepStat(root, slug, inFlight, 'reverts');
     }
-    // The step is abandoned: the build-log returns to the boundary and its mirror
-    // re-renders from the preserved intent.md (D69) — revert keeps intent edits (D26),
-    // so intent's checkboxes stay the truth to reflect. Best-effort, like the rest.
+    // The step is abandoned: the build-log's Current-step line returns to the
+    // boundary and its Steps mirror re-renders from the preserved intent.md —
+    // revert keeps intent edits, so intent's checkboxes stay the truth to reflect.
+    // Best-effort, like every build-log write.
     syncBuildLogState(root, slug, AT_BOUNDARY);
     process.stdout.write(`plumbbob: reverted to ${sha.slice(0, 9)} — back at the boundary. Park lines and intent edits were preserved.\n`);
     return 0;
 }
-// The repo paths that belong to plumbbob, not to the work being reverted: the
-// sidecar (already git-excluded, listed so revert is robust even where `.plumbbob/`
-// was tracked by mistake) and each installed driver skill under .claude/skills/.
-// Skill names come from plumbbob's own bundled `skills/` dir — the same source
-// `setup` copies from — so only plumbbob's own skills are protected, never the
-// user's. Only paths that currently exist are returned.
+/**
+ * The repo paths that belong to plumbbob, not to the work being reverted.
+ *
+ * They are the sidecar (already git-excluded, listed so revert is robust even
+ * where `.plumbbob/` was tracked by mistake) and each installed driver skill
+ * under .claude/skills/, named from plumbbob's own bundled `skills/` dir.
+ *
+ * The match is by name alone, and since the skills dropped their `pb-` prefix
+ * those names are ordinary words — a user's own `.claude/skills/plan/` is
+ * carried across the reset too. That errs toward keeping work (C4), so it is
+ * the safe direction to be wrong in. Only paths that currently exist are returned.
+ */
 function plumbbobOwnedPaths(root) {
     const paths = [sidecarDir(root)];
     try {
@@ -92,9 +110,13 @@ function plumbbobOwnedPaths(root) {
     }
     return paths.filter((p) => existsSync(p));
 }
-// `git reset --hard <sha>` is repo-wide, so paths that must survive it are copied
-// to a temp snapshot first, then copied back over whatever the reset produced.
-// Restoring on top (no pre-delete) keeps the live sidecar safe if a copy throws.
+/**
+ * `git reset --hard <sha>` with the given paths carried across it.
+ *
+ * The reset is repo-wide, so paths that must survive it are copied to a temp
+ * snapshot first, then copied back over whatever the reset produced. Restoring
+ * on top (no pre-delete) keeps the live sidecar safe if a copy throws.
+ */
 function resetPreserving(root, sha, preserve) {
     const snap = mkdtempSync(join(tmpdir(), 'plumbbob-revert-'));
     try {
@@ -106,6 +128,10 @@ function resetPreserving(root, sha, preserve) {
         rmSync(snap, { force: true, recursive: true });
     }
 }
+/**
+ * Parse `--to <n>`: the step number, null when the flag is absent, or
+ * 'invalid' when the flag lacks a numeric argument.
+ */
 function parseTo(args) {
     const idx = args.indexOf('--to');
     if (idx === -1) {
@@ -117,6 +143,12 @@ function parseTo(args) {
     }
     return Number(raw);
 }
+/**
+ * Parse the build's CHECKPOINTS record into a baseline sha and per-step shas.
+ *
+ * A missing or unreadable file yields an empty record — the caller then refuses
+ * with its own message rather than crashing here.
+ */
 function readCheckpoints(root, slug) {
     let content = '';
     try {
@@ -140,6 +172,11 @@ function readCheckpoints(root, slug) {
     }
     return { baseline, steps };
 }
+/**
+ * Read the in-flight step's seam — its edit-grant paths, one per line.
+ *
+ * A missing or unreadable SEAM contributes nothing: no tokens, never an error.
+ */
 function readSeamTokens(root, slug) {
     try {
         return readFileSync(seamPath(root, slug), 'utf8')
@@ -151,8 +188,11 @@ function readSeamTokens(root, slug) {
         return [];
     }
 }
-// The in-flight STEP number, or null when none — read for the revert receipt
-// before the marker is cleared.
+/**
+ * The in-flight STEP number, or null when none.
+ *
+ * Read for the revert receipt before the marker is cleared.
+ */
 function readInFlightStep(root, slug) {
     try {
         const raw = readFileSync(stepPath(root, slug), 'utf8').trim();