plumbbob 0.8.17 → 0.9.1

package/dist/verbs/checkpoint.js

@@ -1,12 +1,14 @@
-// `plumbbob checkpoint [<n>] [-m <msg>]` — the executor-agnostic commit tick (D3).
-// It does NOT require a STEP file: the step is whatever you pass,
-// else the in-flight STEP, else the next undone step in intent. It gates on a green
-// check, then commits any pending work (or records the existing HEAD when the tree
-// is already clean — the human's commit skill may have committed first), records the
-// SHA, flips the intent checkbox to `[x]`, and clears any STEP/SEAM (which returns
-// the dashboard to the DESIGN boundary). The diff's author is irrelevant:
-// `/pb-build`, your hands, a vibe session, or another harness all checkpoint
-// the same way.
+// `plumbbob checkpoint [<n>] [-m <msg>]` — the commit tick that lands a step.
+// Executor-agnostic and author-blind: it reads the diff, not who wrote it, so a
+// `/plumbbob:build` run, your own hands, a vibe session, or another harness all
+// checkpoint identically. It does NOT require a STEP marker (the flat control
+// file recording the step in flight): the step is whatever you pass, else the
+// in-flight STEP, else the next undone step in intent.md. It evaluates the
+// approval latch, gates on a green check, commits any pending work (or records
+// the existing HEAD when the tree is already clean — the human's commit skill
+// may have committed first), records the SHA, flips the intent checkbox to
+// `[x]`, and clears the STEP/SEAM markers — returning the dashboard to the
+// DESIGN boundary.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
 import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
@@ -17,6 +19,12 @@ import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
+/**
+ * Land a step: latch, check gate, commit, record, return to the boundary.
+ *
+ * Exit 1 on any refusal — no session, no resolvable step, a latched tick, or a
+ * red/broken check; each refusal says what unblocks it.
+ */
 export async function checkpoint(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -31,8 +39,9 @@ export async function checkpoint(cwd, args) {
         process.stderr.write('plumbbob: no step to checkpoint — pass a number, or plan a step in intent.md first.\n');
         return 1;
     }
-    // The approval latch (D64) precedes the check gate (C4): the tick may not land
-    // without a human turn since entry, a grant, or a dormant ledger. The refusal
+    // The approval latch runs before the check gate — cheap first. The tick may
+    // not land without a human turn since the step was entered, a one-turn grant
+    // the human typed, or a dormant ledger. A refusal is not an error: the
     // message is the pause affordance — exit 1 and hand the turn back.
     const latch = checkLatch(root, step);
     if (!latch.allow) {
@@ -42,8 +51,9 @@ export async function checkpoint(cwd, args) {
     const gate = await runCheck(root);
     if (gate !== 0) {
         if (gate === 1) {
-            // The dogfood receipt (research/07 Build 2b): red attempts before green
-            // are a per-step count. Harness breakage (2) is not a red check.
+            // Red attempts before green accrue as a per-step stat, surfaced in the
+            // build-log receipt and the finish report. Harness breakage (exit 2) is
+            // not a red check.
             bumpStepStat(root, undefined, step, 'redChecks');
         }
         process.stderr.write(gate === 2
@@ -65,28 +75,33 @@ export async function checkpoint(cwd, args) {
     flipIntent(root, step);
     stampStepStat(root, undefined, step, 'landedAt', new Date().toISOString());
     logCheckpoint(root, step, sha);
-    // The step landed: the build-log's mirror flips to ☑ and Current step returns to
-    // the boundary (D69), re-read from the intent.md `flipIntent` just wrote. The
-    // artifact-plane whitelist keeps this build-log write from ever reading as drift.
+    // The step landed: the build-log's ☐/☑ mirror flips and its Current-step line
+    // returns to the boundary, re-read from the intent.md `flipIntent` just wrote.
+    // The artifact-plane whitelist keeps this build-log write from ever reading as
+    // scope drift.
     syncBuildLogState(root, activeBuild(root), AT_BOUNDARY);
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
-    clearHandoff(root); // the agent-run ledger is step-scoped (D47) — clear it with the markers.
-    clearTick(root); // the entry stamp (D64) is spent — the next `build <n>` re-stamps.
+    clearHandoff(root); // the agent-run handoff ledger is step-scoped — clear it with the markers.
+    clearTick(root); // the step's entry stamp is spent — the next `build <n>` re-stamps.
     process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. Back at the boundary.\n`);
     return 0;
 }
-// The plan-approval commit (D36): stage only the active build's artifact folder and
-// commit it as `chore(<scope>): plan` (D68), then record a `plan <sha>` line. Giving
-// the plan its own commit keeps the first step's diff from absorbing the scaffold, so
-// `git log` reads baseline → plan → steps. No check gate (there is no code work to
-// verify yet), no intent flip, no step markers — the plan lives entirely in DESIGN.
-// An optional `--body` (stdin heredoc, D68) rides after the `plumbbob plan` marker;
-// the folder is whitelisted artifact plane, so there is no scope-drift to warn about.
+/**
+ * The plan-approval commit: stage only the build's artifact folder, commit it as
+ * `chore(<scope>): plan`, and record a `plan <sha>` line.
+ *
+ * Giving the plan its own commit keeps the first step's diff from absorbing the
+ * scaffold, so `git log` reads baseline → plan → steps. No check gate (there is
+ * no code work to verify yet), no intent flip, no step markers — the plan lives
+ * entirely in DESIGN. An optional `--body` (stdin heredoc) rides after the
+ * `plumbbob plan` marker line; the folder is whitelisted artifact plane, so
+ * there is no scope drift to warn about.
+ */
 function checkpointPlan(root, args) {
-    // The latch (D64) covers the plan commit too, keyed on the TICK that `start`
-    // stamped: the plan pause is a pause. No step number — a range grant does not
-    // speak to a plan.
+    // The latch covers the plan commit too, keyed on the TICK that `start`
+    // stamped: the plan pause is a real pause. No step number — a step-range
+    // grant does not speak to a plan.
     const latch = checkLatch(root, null);
     if (!latch.allow) {
         process.stderr.write(latch.message);
@@ -95,22 +110,29 @@ function checkpointPlan(root, args) {
     stagePath(root, buildFolder(root));
     const sha = commit(root, planSubject(root), withMarker('plumbbob plan', bodyArg(args) ?? undefined));
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
-    // The plan landing consumes `start`'s entry stamp (D64): a later hand-built diff
+    // Landing the plan consumes `start`'s entry stamp: a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
     clearTick(root);
     process.stdout.write(`plumbbob: plan committed — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`);
     return 0;
 }
-// The plan commit's CLI-owned subject (D68): `chore(<scope>): plan`, the scope
-// resolved through the build-default fallback chain (a bare `chore: plan` when
-// none resolves). The `plumbbob plan` identifier rides the body marker, not the
-// subject.
+/**
+ * Compose the plan commit's CLI-owned subject: `chore(<scope>): plan`.
+ *
+ * The scope resolves through the build-default fallback chain — a bare
+ * `chore: plan` when none resolves. The `plumbbob plan` identifier rides the
+ * body marker line, never the subject.
+ */
 function planSubject(root) {
     return conventionalSubject({ type: 'chore', scope: buildDefaultScope(root), description: 'plan' });
 }
-// Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
-// intent.md. Returns null when none can be determined. A `-m` value is a message,
-// never a step — `checkpoint -m "2"` must not read as step 2.
+/**
+ * Resolve the step being checkpointed, or null when none can be determined.
+ *
+ * Explicit arg > in-flight STEP file > first undone step in intent.md. A `-m`
+ * value is a message, never a step — `checkpoint -m "2"` must not read as
+ * step 2.
+ */
 function resolveStep(root, args) {
     const explicit = args.filter((_, i) => args[i - 1] !== '-m').find((a) => /^\d+$/.test(a));
     if (explicit !== undefined) {
@@ -127,24 +149,33 @@ function resolveStep(root, args) {
         return null;
     }
 }
-// Guidance, not a gate (the enforce→guide pivot): warn when the staged tree reaches
-// beyond the step's seam, then commit anyway. The seam comes from the in-flight SEAM
-// file when a build is live, else the step's declared seam in intent.md. Plumbbob's
-// own artifact plane is whitelisted (`scopeDrift`), so the `[x]` flip and build-log
-// line this very checkpoint stages never read as drift. No seam ⇒ no warning.
+/**
+ * Warn — never refuse — when the staged tree reaches beyond the step's seam.
+ *
+ * Guidance, not a gate: the checkpoint captures the drift and says so. The seam
+ * (the step's edit grant — exact paths or `dir/` prefixes) comes from the
+ * in-flight SEAM file when a build is live, else the step's declared seam in
+ * intent.md. Plumbbob's own artifact plane is whitelisted inside `scopeDrift`,
+ * so the `[x]` flip and build-log line this very checkpoint stages never read
+ * as drift. No seam means no warning.
+ */
 function warnScopeDrift(root, step) {
     const seam = seamTokens(root, step);
     const outside = scopeDrift(stagedPaths(root), seam);
     if (outside.length > 0) {
-        bumpStepStat(root, undefined, step, 'driftWarnings'); // the dogfood receipt (research/07 2b)
+        bumpStepStat(root, undefined, step, 'driftWarnings'); // accrues into the build-log's stats receipt
         process.stderr.write(`plumbbob: heads-up — staged paths outside step ${step}'s seam: ${outside.join(', ')}. ` +
-            `The checkpoint captures them; if that's real scope drift, the plan may need a \`/pb-step\` revision.\n`);
+            `The checkpoint captures them; if that's real scope drift, the plan may need a \`/plumbbob:step\` revision.\n`);
     }
 }
-// The seam tokens for the in-flight step: the normalized SEAM file `build` wrote
-// (authoritative while a build is live), falling back to the step's declared seam
-// parsed from intent.md. Empty when neither resolves — the caller then skips the
-// warning rather than flagging the whole tree.
+/**
+ * The seam tokens governing the in-flight step.
+ *
+ * The normalized SEAM file `build` wrote is authoritative while a build is
+ * live; fall back to the step's declared seam parsed from intent.md. Empty when
+ * neither resolves — the caller then skips the drift warning rather than
+ * flagging the whole tree.
+ */
 function seamTokens(root, step) {
     try {
         const fromFile = readFileSync(seamPath(root), 'utf8')
@@ -160,21 +191,30 @@ function seamTokens(root, step) {
     }
     return seamForStep(root, step);
 }
+/**
+ * Flip the step's checkbox in intent.md to `[x]`.
+ *
+ * Best-effort bookkeeping — the checkpoint SHA is the source of truth — but the
+ * dashboard reads intent.md, so a swallowed failure here would make orientation
+ * lie; the catch warns and asks for a hand flip instead.
+ */
 function flipIntent(root, step) {
     try {
         writeFileSync(intentPath(root), markStepDone(readFileSync(intentPath(root), 'utf8'), step));
     }
     catch {
-        // Best-effort bookkeeping — the checkpoint SHA is the source of truth — but the
-        // dashboard reads intent.md, so a swallowed failure here makes orientation lie.
         process.stderr.write(`plumbbob: heads-up — could not flip step ${step} to [x] in intent.md; ` +
             `the checkpoint is recorded, but the dashboard will still show step ${step} as next. Flip it by hand.\n`);
     }
 }
-// Append a dated line to the build-log's `## Log` so the build's history accrues at
-// each checkpoint instead of being reconstructed at finish. The step's title is lifted
-// from intent.md when still present. Best-effort: a missing/odd build-log never blocks
-// a checkpoint — the `checkpoints` SHA is the source of truth.
+/**
+ * Append a dated line to the build-log's `## Log` section.
+ *
+ * The build's history accrues at each checkpoint instead of being reconstructed
+ * at finish; the step's title is lifted from intent.md when still present.
+ * Best-effort: a missing or odd build-log never blocks a checkpoint — the
+ * `checkpoints` SHA is the source of truth.
+ */
 function logCheckpoint(root, step, sha) {
     try {
         const path = buildLogPath(root);
@@ -189,9 +229,13 @@ function logCheckpoint(root, step, sha) {
         // best-effort ledger; never fail a checkpoint over the build-log.
     }
 }
-// The compact receipt riding the Log line (research/07 Build 2b): only what
-// accrued — a clean first-try step gets no suffix at all. Wall-clock needs both
-// stamps (a hand-built step never ran `build <n>`, so it has no startedAt).
+/**
+ * The compact stats receipt riding the Log line, or null when nothing accrued.
+ *
+ * Only what happened is shown — a clean first-try step gets no suffix at all.
+ * Wall-clock needs both stamps: a hand-built step never ran `build <n>`, so it
+ * has no startedAt.
+ */
 function statsSuffix(root, step) {
     const stats = readStats(root)[String(step)];
     if (stats === undefined)
@@ -210,14 +254,17 @@ function statsSuffix(root, step) {
     }
     return parts.length > 0 ? parts.join(', ') : null;
 }
-// The CLI-owned, deterministic commit subject (D68): a Conventional `type(scope):
-// description`. The type and wording come from the step's title — an author-written
-// prefix (`fix(parser): …`) is honoured verbatim, a bare title defaults to `feat`.
-// The scope falls back through the chain (D3): the title's own `(scope)` wins
-// (handled inside `subjectFromTitle`), else `buildDefaultScope`. A titleless step
-// falls back to `chore(<scope>): checkpoint`. The `plumbbob`/`step N` identifiers
-// ride the body marker, not the subject; a `-m` override or `--body` prose is a
-// separate concern.
+/**
+ * Compose the step's CLI-owned, deterministic Conventional Commit subject.
+ *
+ * The type and wording come from the step's title: an author-written prefix
+ * (`fix(parser): …`) is honoured verbatim, a bare prose title defaults to
+ * `feat`. The title's own `(scope)` wins (handled inside `subjectFromTitle`),
+ * else the build-default scope. A titleless step falls back to
+ * `chore(<scope>): checkpoint`. The `plumbbob`/`step N` identifiers ride the
+ * body marker line, not the subject; a `-m` override or `--body` prose is a
+ * separate concern.
+ */
 function subjectForStep(root, step) {
     const scope = buildDefaultScope(root);
     const title = titleForStep(root, step);
@@ -225,10 +272,13 @@ function subjectForStep(root, step) {
         ? subjectFromTitle(title, 'feat', scope)
         : conventionalSubject({ type: 'chore', scope, description: 'checkpoint' });
 }
-// The build-default Conventional scope (D3/D4): the `**Scope:**` header field in
-// intent.md when authored and filled, else the build slug (D68's original rung,
-// now the penultimate one), else null — a bare subject (C2 back-compat: a build
-// with neither field behaves exactly as before D4).
+/**
+ * The build-default Conventional scope, or null for a bare subject.
+ *
+ * The `**Scope:**` header field in intent.md wins when authored and filled;
+ * else the build slug with its date prefix stripped; else null — a build with
+ * neither field keeps producing bare subjects.
+ */
 function buildDefaultScope(root) {
     try {
         const fromHeader = parseBuildScope(readFileSync(intentPath(root), 'utf8'));
@@ -241,6 +291,9 @@ function buildDefaultScope(root) {
     }
     return buildScope(activeBuild(root));
 }
+/**
+ * The step's title from intent.md, or null when absent or unreadable.
+ */
 function titleForStep(root, step) {
     try {
         return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => s.n === step)?.title ?? null;
@@ -249,16 +302,22 @@ function titleForStep(root, step) {
         return null;
     }
 }
+/**
+ * The `-m <msg>` subject override, or null when the flag is absent.
+ */
 function messageArg(args) {
     const i = args.indexOf('-m');
     return i !== -1 && i + 1 < args.length ? (args[i + 1] ?? null) : null;
 }
-// `--body` reads the commit body from stdin (the single-quoted heredoc of D34),
-// so the skill can compose proportional prose the CLI never could. Returns null
-// when the flag is absent or stdin is empty — either way the deterministic
-// fallback body takes over. Reading fd 0 blocks until EOF, which the heredoc
-// supplies; a read error (no stdin attached) degrades to the fallback, and an
-// interactive TTY — which would never send EOF — skips the read instead of hanging.
+/**
+ * Read the `--body` commit body from stdin, or null when absent or empty.
+ *
+ * The stdin heredoc lets a skill compose proportional prose the CLI never
+ * could; null either way hands over to the deterministic fallback body. Reading
+ * fd 0 blocks until EOF, which the heredoc supplies; a read error (no stdin
+ * attached) degrades to the fallback, and an interactive TTY — which would
+ * never send EOF — skips the read instead of hanging.
+ */
 function bodyArg(args) {
     if (!args.includes('--body') || process.stdin.isTTY === true) {
         return null;
@@ -271,10 +330,14 @@ function bodyArg(args) {
         return null;
     }
 }
-// The deterministic checkpoint body (D35): the step's done-when, its seam, and the
-// staged diffstat — so a hand-built or vibed checkpoint still gets informative
-// history without a model turn. Each part is best-effort; a missing piece is
-// simply omitted, and an empty result leaves the commit body blank.
+/**
+ * The deterministic fallback commit body: the step's done-when, its seam, and
+ * the staged diffstat.
+ *
+ * A hand-built or vibed checkpoint still gets informative history without a
+ * model turn. Each part is best-effort; a missing piece is simply omitted, and
+ * an empty result leaves the commit body blank.
+ */
 function fallbackBody(root, step) {
     const parts = [];
     const doneWhen = doneWhenForStep(root, step);
@@ -291,6 +354,9 @@ function fallbackBody(root, step) {
     }
     return parts.length > 0 ? parts.join('\n\n') : undefined;
 }
+/**
+ * The step's done-when line from intent.md, or null when absent or unreadable.
+ */
 function doneWhenForStep(root, step) {
     try {
         return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => s.n === step)?.doneWhen ?? null;
@@ -299,6 +365,9 @@ function doneWhenForStep(root, step) {
         return null;
     }
 }
+/**
+ * The step's declared seam from intent.md, or empty when missing or malformed.
+ */
 function seamForStep(root, step) {
     try {
         const parsed = parseStepSeam(readFileSync(intentPath(root), 'utf8'), step);
@@ -308,6 +377,9 @@ function seamForStep(root, step) {
         return [];
     }
 }
+/**
+ * The staged diffstat, or '' when git refuses.
+ */
 function safeStagedStat(root) {
     try {
         return stagedStat(root);
@@ -316,6 +388,9 @@ function safeStagedStat(root) {
         return '';
     }
 }
+/**
+ * The in-flight step number from the STEP file, or null when absent or garbled.
+ */
 function readStep(root) {
     try {
         const raw = readFileSync(stepPath(root), 'utf8').trim();