plumbbob 0.8.17 → 0.9.1

package/dist/lib/buildlog.js

@@ -1,13 +1,18 @@
-// Mutations to the active build-log.md — the human-facing ledger. `park` appends to
-// its Park list; `checkpoint` appends to its Log so the build's history accrues
-// line-by-line *as it happens* rather than being reconstructed at finish (D-history).
-// `build`/`checkpoint`/`revert` keep its `## Steps` mirror and `**Current step:**`
-// line in sync with intent.md (D69), so the ledger's top half tracks reality without
-// a model turn. Pure string transforms (no fs, no classes — C1/C2); callers own the
-// IO so these stay trivially testable.
-// Append `line` after the last non-blank line of the `## <heading>` section — i.e.
-// just before the next `## ` heading or EOF. Returns null when the section is absent
-// so the caller can report rather than silently corrupt the doc.
+// Mutations to the active build-log.md — the human-facing ledger inside the
+// build's tracked `builds/<slug>/` folder. `park` appends to its Park list;
+// `checkpoint` appends to its Log so the build's history accrues line-by-line
+// *as it happens* rather than being reconstructed at finish. The `## Steps`
+// mirror and `**Current step:**` line are CLI-owned: `build`, `checkpoint`,
+// and `revert` re-render them from intent.md so the ledger's top half tracks
+// reality without a model turn. Pure string transforms — no fs, no classes;
+// callers own the IO so these stay trivially testable.
+/**
+ * Append `line` after the last non-blank line of the `## <heading>` section —
+ * i.e. just before the next `## ` heading or EOF.
+ *
+ * Returns null when the section is absent so the caller can report rather than
+ * silently corrupt the doc.
+ */
 export function appendToSection(content, heading, line) {
     const lines = content.split('\n');
     const headingIdx = lines.findIndex((l) => l.trim() === `## ${heading}`);
@@ -27,10 +32,14 @@ export function appendToSection(content, heading, line) {
     lines.splice(insertAt, 0, line);
     return lines.join('\n');
 }
-// Replace the `**Current step:**` line with `**Current step:** <label>` — `build`
-// sets it to `<n> — <title>` when a step opens; `checkpoint`/`revert` reset it to
-// `none (at the boundary)`. Returns null when the line is absent so the caller skips
-// rather than corrupting the doc (C3).
+/**
+ * Replace the `**Current step:**` line with `**Current step:** <label>` —
+ * `build` sets it to `<n> — <title>` when a step opens; `checkpoint`/`revert`
+ * reset it to `none (at the boundary)`.
+ *
+ * Returns null when the line is absent so the caller skips rather than
+ * corrupting the doc.
+ */
 export function setCurrentStep(content, label) {
     const lines = content.split('\n');
     const idx = lines.findIndex((l) => /^\*\*Current step:\*\*/.test(l.trim()));
@@ -40,12 +49,17 @@ export function setCurrentStep(content, label) {
     lines[idx] = `**Current step:** ${label}`;
     return lines.join('\n');
 }
-// Regenerate the `## Steps` mirror from intent.md's parsed steps — one
-// `- ☑/☐ N. <title>` line each, in order. Only the mirror's own `- ☑/☐` list lines
-// are owned; the italic instructions paragraph (and any other prose) is preserved,
-// and exactly one blank line separates it from the list. Returns null when the
-// section is absent (C3). With no steps the mirror renders empty — the plan is not
-// authored yet — rather than inventing a placeholder.
+/**
+ * Regenerate the `## Steps` mirror from intent.md's parsed steps — one
+ * `- ☑/☐ N. <title>` line each, in order.
+ *
+ * Only the mirror's own `- ☑/☐` list lines are owned; the italic instructions
+ * paragraph (and any other prose) is preserved, and exactly one blank line
+ * separates it from the list. Returns null when the section is absent so the
+ * caller skips rather than corrupting the doc. With no steps the mirror
+ * renders empty — the plan is not authored yet — rather than inventing a
+ * placeholder.
+ */
 export function syncStepsSection(content, steps) {
     const lines = content.split('\n');
     const headingIdx = lines.findIndex((l) => l.trim() === '## Steps');
@@ -56,9 +70,9 @@ export function syncStepsSection(content, steps) {
     if (end === -1) {
         end = lines.length;
     }
-    // The section body minus the mirror list lines, with trailing blanks trimmed, is
-    // the prose to preserve (the instructions paragraph). Rebuild: prose, one blank,
-    // the fresh list, one blank before the next heading.
+    // The section body minus the mirror list lines, with trailing blanks trimmed,
+    // is the prose to preserve (the instructions paragraph). Rebuild: prose, one
+    // blank, the fresh list, one blank before the next heading.
     const prose = lines.slice(headingIdx + 1, end).filter((l) => !isMirrorLine(l));
     while (prose.length > 0 && (prose.at(-1) ?? '').trim() === '') {
         prose.pop();
@@ -67,16 +81,22 @@ export function syncStepsSection(content, steps) {
     const body = [...prose, ...(prose.length > 0 ? [''] : []), ...list, ''];
     return [...lines.slice(0, headingIdx + 1), ...body, ...lines.slice(end)].join('\n');
 }
-// A mirror list line the CLI owns: `- ☑ …` / `- ☐ …`. The template's initial
-// `- ☐ 1. <step>` placeholder matches, so the first sync replaces it in place.
+/**
+ * A mirror list line the CLI owns: `- ☑ …` / `- ☐ …`. The template's initial
+ * `- ☐ 1. <step>` placeholder matches, so the first sync replaces it in place.
+ */
 function isMirrorLine(line) {
     return /^-\s+[☑☐]/.test(line);
 }
-// The Log line `checkpoint` writes for a landed step: dated, names the step (its
-// title when intent.md still carries it), and carries the short SHA. One line of the
-// build's history — `/pb-finish` reads these instead of re-narrating the build.
-// `stats` is the optional compact receipt (research/07 2b), e.g. `2 red, 34m` —
-// null when nothing accrued, so a clean first-try step reads exactly as before.
+/**
+ * The Log line `checkpoint` writes for a landed step: dated, names the step
+ * (its title when intent.md still carries it), and carries the short SHA.
+ *
+ * One line of the build's history — `/plumbbob:finish` reads these instead of
+ * re-narrating the build. `stats` is the optional compact receipt of what the
+ * step cost (e.g. `2 red, 34m`) — null when nothing accrued, so a clean
+ * first-try step reads as a bare line.
+ */
 export function checkpointLogLine(date, step, sha, title, stats = null) {
     const head = `- ${date} — step ${step} checkpointed · ${sha.slice(0, 9)}`;
     const titled = title !== null && title.length > 0 ? `${head} — ${title}` : head;

package/dist/lib/buildlogsync.js

@@ -1,24 +1,33 @@
 // Keep the build-log's top half — the `**Current step:**` line and the `## Steps`
-// mirror — in sync with intent.md (D69). `build` sets the current-step label when a
-// step opens; `checkpoint` and `revert` reset it to the boundary; all three re-render
-// the mirror from intent.md's parsed steps so it tracks reality without a model turn.
-// The write is best-effort (a missing or hand-edited build-log never fails a verb —
-// the checkpoints ledger and intent.md stay the source of truth), matching how
-// `checkpoint`'s Log append already behaves.
+// mirror — in sync with intent.md, the build's plan document. The build-log is the
+// human-facing ledger in the build's tracked `builds/<slug>/` folder; its top half
+// is CLI-owned so it never lies: `build` sets the current-step label when a step
+// opens, `checkpoint` and `revert` reset it to the boundary, and all three
+// re-render the mirror from intent.md's parsed steps so it tracks reality without
+// a model turn. The write is best-effort (a missing or hand-edited build-log never
+// fails a verb — the checkpoints ledger and intent.md stay the source of truth),
+// matching how `checkpoint`'s Log append behaves.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { buildLogPath, intentPath } from "./sidecar.js";
 import { parseSteps } from "./orient.js";
 import { setCurrentStep, syncStepsSection } from "./buildlog.js";
+/** The Current-step label for no step in flight — the loop is at the step boundary. */
 export const AT_BOUNDARY = 'none (at the boundary)';
-// The current-step label for an open step: `<n> — <title>`, or a bare `<n>` when the
-// step carries no title. `build` passes this; the boundary verbs pass AT_BOUNDARY.
+/**
+ * The current-step label for an open step: `<n> — <title>`, or a bare `<n>`
+ * when the step carries no title. `build` passes this; the boundary verbs pass
+ * AT_BOUNDARY.
+ */
 export function stepLabel(n, title) {
     return title !== null && title.trim().length > 0 ? `${n} — ${title.trim()}` : String(n);
 }
-// Rewrite the active build's build-log top half: set the Current step line to `label`
-// and re-render the `## Steps` mirror from intent.md. Each transform is skipped when
-// its target is absent (null), and the whole thing swallows any IO error — the ledger
-// must never block the verb.
+/**
+ * Rewrite the active build's build-log top half: set the Current step line to
+ * `label` and re-render the `## Steps` mirror from intent.md.
+ *
+ * Each transform is skipped when its target is absent (null), and the whole
+ * thing swallows any IO error — the ledger must never block the verb.
+ */
 export function syncBuildLogState(root, slug, label) {
     try {
         const path = buildLogPath(root, slug);

package/dist/lib/check.js

@@ -1,19 +1,30 @@
-// The heavy check (D16/D24/D32): the full gate that `verify` and `checkpoint`
-// refuse to advance past while red. Two paths through one seam:
-//   - a `check` setting resolved through the ladder (flag → settings.local.json
-//     → settings.json, D27) is a shell command → spawn it exactly as before, so
-//     any repo can gate through anything (tests point it at `true`/`false`, D14);
+// The heavy check: the full quality gate that `verify` and `checkpoint` refuse
+// to advance past while red. Two paths through one seam:
+//   - a `check` setting resolved through the settings ladder (CLI flag →
+//     settings.local.json, the untracked personal overlay → settings.json, the
+//     tracked project defaults) is a shell command → spawn it verbatim, so any
+//     repo can gate through anything (test fixtures point it at `true`/`false`
+//     to keep throwaway repos deterministic);
 //   - no setting at all → checkride, our sibling package, imported
-//     programmatically (D32): the typed summary comes back in-process, failing
-//     slots are reported with their `.check/` raw-output pointers, and an
-//     all-slots-skipped run REFUSES rather than green-lighting a repo checkride
-//     can't see (a vacuous pass is not a pass).
+//     programmatically rather than spawned: the typed summary comes back
+//     in-process, failing slots are reported with their `.check/` raw-output
+//     pointers, and an all-slots-skipped run REFUSES rather than green-lighting
+//     a repo checkride can't see (a vacuous pass is not a pass).
 // Checkride's stream discipline holds: human progress goes to stderr. Exit 0 is
 // green, 1 is red, 2 means the harness itself broke — reported distinctly,
 // because a misconfigured gate must not read as broken code (both still block).
 import { spawnSync } from 'node:child_process';
 import { runChecks, runDoctor } from 'checkride';
 import { resolveString } from "./settings.js";
+/**
+ * Probe whether the check gate would have anything to run in `root`.
+ *
+ * A configured `check` command answers yes on its own; otherwise checkride's
+ * doctor detection runs in-process — the same pass `plumbbob doctor` reports
+ * as a table. `start` reads this to surface "nothing to check" at plan time,
+ * while the human is still deciding, instead of at the first refused
+ * checkpoint.
+ */
 export async function detectGate(root) {
     const command = resolveString(root, 'check', '');
     if (command.length > 0)
@@ -30,28 +41,36 @@ export async function detectGate(root) {
         return { configured: null, detected: true };
     }
 }
-// Checkride's always-on repo checks: the adapters its doctor reports even for
-// an EMPTY directory — the built-in `links` slot, the pnpm-audit security
-// scan, the publint/attw package-shape probes, and (checkride 0.5.0's
-// publish bundle) the built-in pack/smoke/snippets slots, which resolve on any
-// package with no tool config of their own. They exercise the repo's plumbing
-// or its shipped artifact, not its code — a gate made only of these green-lights
-// every checkpoint while the human believes their work is being checked. Coupled
-// to checkride's built-in set by construction; the check.test.ts and
-// doctor.test.ts probes pin the coupling.
+/**
+ * Checkride's always-on repo checks: the adapters its doctor reports even for
+ * an EMPTY directory — the built-in `links` slot, the pnpm-audit security
+ * scan, the publint/attw package-shape probes, and the built-in
+ * pack/smoke/snippets publish-bundle slots, which resolve on any package with
+ * no tool config of their own. They exercise the repo's plumbing or its
+ * shipped artifact, not its code — a gate made only of these green-lights
+ * every checkpoint while the human believes their work is being checked.
+ * Coupled to checkride's built-in set by construction; the check.test.ts and
+ * doctor.test.ts probes pin the coupling.
+ */
 const ALWAYS_ON_ADAPTERS = ['links', 'pnpm-audit', 'publint', 'attw', 'pack', 'smoke', 'snippets'];
-// The detection rule, shared by `start`'s probe and doctor's callout: some tool
-// slot beyond the always-on family has an adapter — i.e. checkride can see the
-// CODE (a tsconfig, a test runner, a linter…), not just the repo.
+/**
+ * The detection rule, shared by `start`'s probe and doctor's callout: some
+ * tool slot beyond the always-on family has an adapter — i.e. checkride can
+ * see the CODE (a tsconfig, a test runner, a linter…), not just the repo.
+ */
 export function gateDetectsTools(checks) {
     return checks.some((c) => c.category === 'tool' &&
         c.adapter !== null &&
         c.adapter !== undefined &&
         !ALWAYS_ON_ADAPTERS.includes(c.adapter));
 }
-// Runs the gate in `root` and returns the exit code (0 green, 1 red, 2 harness
-// error). `commandFlag` is the optional CLI override at the top of the settings
-// ladder; a resolved command means the spawn path, no setting means checkride.
+/**
+ * Run the gate in `root` and return the exit code (0 green, 1 red, 2 harness
+ * error).
+ *
+ * `commandFlag` is the optional CLI override at the top of the settings
+ * ladder; a resolved command means the spawn path, no setting means checkride.
+ */
 export async function runCheck(root, flags = {}, commandFlag) {
     const command = resolveString(root, 'check', '', commandFlag);
     if (command.length > 0) {
@@ -59,8 +78,11 @@ export async function runCheck(root, flags = {}, commandFlag) {
     }
     return runCheckride(root, flags);
 }
-// The spawn override, byte-for-byte the pre-D32 behavior: stream the command's
-// own output to the terminal and return its exit code.
+/**
+ * The spawn override: stream the configured command's own output to the
+ * terminal and return its exit code — the command is trusted verbatim, no
+ * interpretation.
+ */
 function runCommand(root, command, flags) {
     if (hasFlags(flags)) {
         process.stderr.write(`plumbbob: check flags only narrow the checkride gate — ignored for the configured command '${command}'.\n`);
@@ -68,6 +90,10 @@ function runCommand(root, command, flags) {
     const result = spawnSync(command, { cwd: root, shell: true, stdio: 'inherit' });
     return result.status ?? 1;
 }
+/**
+ * The checkride path: run the gate in-process, refuse an all-skipped run, and
+ * name the failing slots on red.
+ */
 async function runCheckride(root, flags) {
     let summary;
     let exitCode;
@@ -85,8 +111,9 @@ async function runCheckride(root, flags) {
         exitCode = result.exitCode;
     }
     catch (err) {
-        // The harness broke, not the code (D32): a malformed checkride.config.json
-        // or the like. Checkride's own CLI maps this to exit 2; so do we.
+        // The harness broke, not the code: a malformed checkride.config.json or
+        // the like. Checkride's own CLI maps this to exit 2; so do we — a
+        // misconfigured gate must report distinctly from red.
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`plumbbob: the check gate itself failed — ${message}\n` +
             `  Fix checkride.config.json, or set the "check" key in .plumbbob/settings.json to gate through another command.\n`);
@@ -94,9 +121,9 @@ async function runCheckride(root, flags) {
     }
     if (summary.checks.every((c) => c.skipped === true || c.name === 'links')) {
         // Zero-config checkride skips slots with no detected tool; a repo it can't
-        // see must refuse, not vacuously green-light the checkpoint (D32). The
-        // built-in `links` slot is always-on (empty detect list), so it alone
-        // proves nothing about the code — a links-only run is still vacuous.
+        // see must refuse, not vacuously green-light the checkpoint. The built-in
+        // `links` slot is always-on (empty detect list), so it alone proves
+        // nothing about the code — a links-only run is still vacuous.
         process.stderr.write('plumbbob: checkride found nothing to check in this repo — refusing to call that green.\n' +
             '  Add tool configs (tsconfig, vitest, …) or a checkride.config.json custom check,\n' +
             '  or set the "check" key in .plumbbob/settings.json to gate through another command.\n');
@@ -107,10 +134,13 @@ async function runCheckride(root, flags) {
     }
     return exitCode;
 }
-// Name the failing slots and where their raw diagnostics landed, so the agent
-// (pb-verify) reads the tool's own JSON instead of scraping scrollback. The
-// summary is the canonical pointer — `output_file` is the adapter's preferred
-// name, but non-JSON output falls back to `.check/<slot>.stdout.txt`.
+/**
+ * Name the failing slots and where their raw diagnostics landed, so the agent
+ * (verify) reads the tool's own JSON instead of scraping scrollback.
+ *
+ * The summary is the canonical pointer — `output_file` is the adapter's
+ * preferred name, but non-JSON output falls back to `.check/<slot>.stdout.txt`.
+ */
 function reportFailingSlots(summary) {
     const failing = summary.checks.filter((c) => !c.ok);
     const lines = failing.map((c) => {
@@ -120,6 +150,10 @@ function reportFailingSlots(summary) {
     });
     process.stderr.write(`plumbbob: failing slots:\n${lines.join('\n')}\n  Full report: .check/summary.json\n`);
 }
+/**
+ * True when any narrowing flag was passed — the trigger for the spawn path's
+ * flags-are-ignored warning.
+ */
 function hasFlags(flags) {
     return (flags.bail === true ||
         flags.changed === true ||

package/dist/lib/commitmsg.js

@@ -1,23 +1,31 @@
-// Conventional-Commit subject assembly (D68). Plumbbob's commit subjects read as
+// Conventional-Commit subject assembly. Plumbbob's commit subjects read as
 // `type(scope): description` — real feat/fix/chore types and a real parenthesised
 // scope — so `git log` speaks the same grammar as the rest of the branch. The
-// `plumbbob`/`step N` identifiers that used to prefix the subject (the old D34
-// shape) now ride a marker line at the head of the body, which `withMarker`
-// prepends — so `git log --grep plumbbob` still finds every plumbbob commit.
-// Functional/procedural, node-builtins-only (C1/C2), no gate: these only shape a
-// string the CLI is about to commit.
-// The Conventional-Commit type vocabulary plumbbob recognises as a leading prefix
-// on a step title. Anchoring on this closed set keeps a prose title like
-// `Note: rewire the cache` from being misread as a `Note` type — only these words,
-// immediately followed by an optional `(scope)`, an optional `!`, and a colon,
-// count as an author-supplied prefix.
+// `plumbbob`/`step N` identifiers ride a marker line at the head of the body,
+// which `withMarker` prepends — so `git log --grep plumbbob` finds every plumbbob
+// commit. Functional and procedural, node builtins only, no gate: these only
+// shape a string the CLI is about to commit.
+/**
+ * The Conventional-Commit type vocabulary plumbbob recognises as a leading
+ * prefix on a step title.
+ *
+ * Anchoring on this closed set keeps a prose title like `Note: rewire the
+ * cache` from being misread as a `Note` type — only these words, immediately
+ * followed by an optional `(scope)`, an optional `!`, and a colon, count as an
+ * author-supplied prefix.
+ */
 const TYPES = ['feat', 'fix', 'chore', 'docs', 'refactor', 'test', 'perf', 'build', 'ci', 'style', 'revert'];
+// One anchored pattern for the whole prefix: type, optional (scope), optional
+// breaking !, colon, then the description.
 const PREFIX = new RegExp(`^(${TYPES.join('|')})(?:\\(([^)]+)\\))?(!)?:\\s+(.+)$`);
-// Split an optional Conventional prefix off a step title. `feat(escape-hatch): add
-// the flag` → { type:'feat', scope:'escape-hatch', breaking:false, description:'add
-// the flag' }. A title with no recognised prefix comes back whole as the
-// description with a null type/scope — the caller then defaults the type and fills
-// the scope from the build.
+/**
+ * Split an optional Conventional prefix off a step title.
+ *
+ * `feat(escape-hatch): add the flag` → { type:'feat', scope:'escape-hatch',
+ * breaking:false, description:'add the flag' }. A title with no recognised
+ * prefix comes back whole as the description with a null type/scope — the
+ * caller then defaults the type and fills the scope from the build.
+ */
 export function parseConventionalTitle(title) {
     const m = PREFIX.exec(title.trim());
     if (m === null) {
@@ -25,20 +33,26 @@ export function parseConventionalTitle(title) {
     }
     return { type: m[1] ?? null, scope: m[2] ?? null, breaking: m[3] === '!', description: (m[4] ?? '').trim() };
 }
-// Assemble a `type(scope)!: description` subject, omitting the `(scope)` segment
-// when there is no scope (Conventional Commits allow a bare `type: description`)
-// and the `!` when the change is not breaking.
+/**
+ * Assemble a `type(scope)!: description` subject, omitting the `(scope)`
+ * segment when there is no scope (Conventional Commits allow a bare
+ * `type: description`) and the `!` when the change is not breaking.
+ */
 export function conventionalSubject(parts) {
     const scope = parts.scope ? `(${parts.scope})` : '';
     const bang = parts.breaking ? '!' : '';
     return `${parts.type}${scope}${bang}: ${parts.description}`;
 }
-// A Conventional subject from a step title, filling gaps from the build. An
-// author-written prefix (`fix(parser): …`) is honoured verbatim — its type, scope,
-// breaking marker, and exact wording all win. A bare prose title defaults to
-// `defaultType` and the build `scope`, and gets its sentence-case opener
-// de-capitalised (`Add the flag` → `add the flag`) to match Conventional style —
-// while an all-caps acronym start (`API`, `OAuth`) is left alone.
+/**
+ * A Conventional subject from a step title, filling gaps from the build.
+ *
+ * An author-written prefix (`fix(parser): …`) is honoured verbatim — its type,
+ * scope, breaking marker, and exact wording all win. A bare prose title
+ * defaults to `defaultType` and the build `scope`, and gets its sentence-case
+ * opener de-capitalised (`Add the flag` → `add the flag`) to match
+ * Conventional style — while an all-caps acronym start (`API`, `OAuth`) is
+ * left alone.
+ */
 export function subjectFromTitle(title, defaultType, scope) {
     const parsed = parseConventionalTitle(title);
     if (parsed.type !== null) {
@@ -51,17 +65,24 @@ export function subjectFromTitle(title, defaultType, scope) {
     }
     return conventionalSubject({ type: defaultType, scope, description: lowerFirst(parsed.description) });
 }
-// Prepend a marker line (`plumbbob step 1`, `plumbbob plan`, `plumbbob finish`) to
-// an optional body, separated by a blank line so git keeps them as distinct
-// paragraphs. Always returns at least the marker, so every plumbbob commit carries
-// the greppable identifier in its body even when the prose is empty.
+/**
+ * Prepend a marker line (`plumbbob step 1`, `plumbbob plan`, `plumbbob
+ * finish`) to an optional body, separated by a blank line so git keeps them as
+ * distinct paragraphs.
+ *
+ * Always returns at least the marker, so every plumbbob commit carries the
+ * greppable identifier in its body even when the prose is empty.
+ */
 export function withMarker(marker, body) {
     const rest = body?.trim();
     return rest !== undefined && rest.length > 0 ? `${marker}\n\n${rest}` : marker;
 }
-// De-capitalise a sentence-case opener but leave an acronym/proper all-caps start
-// (`API`, `OAuth`) intact: lowercase the first character only when it is uppercase
-// and the second character is not (so `Add` → `add`, but `API` stays `API`).
+/**
+ * De-capitalise a sentence-case opener but leave an acronym/proper all-caps
+ * start (`API`, `OAuth`) intact: lowercase the first character only when it is
+ * uppercase and the second character is not (so `Add` → `add`, but `API` stays
+ * `API`).
+ */
 function lowerFirst(text) {
     const a = text[0] ?? '';
     const b = text[1] ?? '';