plumbbob 0.8.18 → 0.9.1

package/dist/lib/orient.js

@@ -1,10 +1,12 @@
-// Orientation model for `status` (D8/D15): parse a live session into the
-// dashboard the human reads to know where they are and what to do next. Pure and
-// best-effort — it takes raw file contents (no fs), and a malformed doc degrades
-// to fewer fields rather than throwing. Functional/procedural, no classes, no
-// default export (C1).
+// The orientation model behind `status`: parse a live build session into the
+// where-am-I dashboard — title, phase, step list, last checkpoint, counts, and
+// one suggested next move. Pure and best-effort by design: it takes raw file
+// contents (no fs), and a malformed document degrades to fewer fields rather
+// than throwing.
 import { parseStepSeam } from "./intent.js";
-// The lines of a named `## Section`, from its heading to the next `## ` (or EOF).
+/**
+ * The lines of a named `## Section`, from its heading to the next `## ` (or EOF).
+ */
 function sectionLines(content, heading) {
     const lines = content.split('\n');
     const start = lines.findIndex((l) => l.trim() === heading);
@@ -17,6 +19,9 @@ function sectionLines(content, heading) {
     }
     return lines.slice(start + 1, end);
 }
+/**
+ * The build title — the first `# ` heading in intent.md, or null when absent.
+ */
 export function parseTitle(intent) {
     for (const line of intent.split('\n')) {
         const m = /^#\s+(.+?)\s*$/.exec(line);
@@ -26,9 +31,14 @@ export function parseTitle(intent) {
     }
     return null;
 }
-// Steps under `## Steps`: `N. [ |x] Title — **done when:** ...`. The title is the
-// text up to the first em dash; `planned` is true when the step's block carries a
-// `done when` criterion. Roadmap prose lives in its own section, never here (D6).
+/**
+ * Parse the steps under `## Steps`: `N. [ |x] Title — **done when:** ...`.
+ *
+ * The title is the text up to the first em dash; `planned` is true when the
+ * step's block carries a `done when` criterion. Only `## Steps` is machine-read
+ * as the build plan — narrative roadmap prose lives in its own section and
+ * never lands here.
+ */
 export function parseSteps(intent) {
     const lines = sectionLines(intent, '## Steps');
     const starts = [];
@@ -54,9 +64,12 @@ export function parseSteps(intent) {
         return { n: s.n, done: s.done, title: s.title, planned: /done when/i.test(block), doneWhen, model };
     });
 }
-// Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section — mechanical
-// bookkeeping for `checkpoint` so `status` reflects a checkpointed step. A no-op if
-// the step is absent or already done.
+/**
+ * Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section.
+ *
+ * Mechanical bookkeeping for `checkpoint`, so `status` reflects a checkpointed
+ * step. A no-op if the step is absent or already done.
+ */
 export function markStepDone(intent, n) {
     let inSteps = false;
     return intent
@@ -73,18 +86,31 @@ export function markStepDone(intent, n) {
     })
         .join('\n');
 }
-// Open questions still open: `- Q\d+:` openers that do not say "resolved". The
-// opener may carry a slug-at-birth gloss — `- Q2 (some-slug): ...` (D3) — which
-// the count reads through; sub-lines (`*plain:*`/`*lean:*`) never match.
+/**
+ * Count the questions still open: `- Q\d+:` openers under `## Open questions`
+ * that do not say "resolved".
+ *
+ * The opener may carry a slug-at-birth gloss — `- Q2 (some-slug): ...` — which
+ * the count reads through; sub-lines (`*plain:*`/`*lean:*`) never match.
+ */
 export function parseOpenQuestions(intent) {
     return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+(?: \([^)]+\))?:/.test(l.trim()) && !/resolved/i.test(l)).length;
 }
-// Open parked items: `- [ ]` lines under `## Park list` (the `park` verb's format).
-// A harvested item is flipped to `- [x]` by `/pb-harvest` and no longer counts; the
-// `(none yet)` placeholder and the blockquote instructions never match.
+/**
+ * Count the open parked items: `- [ ]` lines under `## Park list`.
+ *
+ * A parked item is a mid-build idea the `park` verb appends as a flat checklist
+ * line for later triage; `/plumbbob:harvest` flips a triaged one to `- [x]` and it
+ * stops counting. The `(none yet)` placeholder and the blockquote instructions
+ * never match.
+ */
 export function parseParked(buildLog) {
     return sectionLines(buildLog, '## Park list').filter((l) => /^-\s+\[ \]\s+\S/.test(l.trim())).length;
 }
+/**
+ * The last `step N <sha>` line in the checkpoints ledger, or null when no step
+ * has landed yet.
+ */
 export function parseLastCheckpoint(checkpoints) {
     let last = null;
     for (const line of checkpoints.split('\n')) {
@@ -95,12 +121,15 @@ export function parseLastCheckpoint(checkpoints) {
     }
     return last;
 }
-// The SHA of the last ledger line of ANY kind — baseline, plan, or step. This is
-// the reconciliation anchor for the out-of-band count (D66): a commit that lands
-// after the plan but before the first step checkpoint is exactly the window the
-// receipt exists for, so anchoring on step lines alone would leave it invisible.
-// `parseLastCheckpoint` stays step-only — it feeds the "last checkpoint step N"
-// display, where baseline/plan would be noise.
+/**
+ * The SHA of the last ledger line of ANY kind — baseline, plan, or step.
+ *
+ * This is the reconciliation anchor for the out-of-band commit count: a commit
+ * that lands after the plan but before the first step checkpoint is exactly the
+ * window the reconciliation line exists for, so anchoring on step lines alone
+ * would leave it invisible. `parseLastCheckpoint` stays step-only — it feeds
+ * the "last checkpoint step N" display, where baseline/plan would be noise.
+ */
 export function lastLedgerSha(checkpoints) {
     let last = null;
     for (const line of checkpoints.split('\n')) {
@@ -111,32 +140,39 @@ export function lastLedgerSha(checkpoints) {
     }
     return last;
 }
-// The single primary next move (D15). It suggests; the dashboard prints the full
-// list + counts so the human can always override. The phase is derived: a spike
-// in progress and an in-flight step each have one obvious next move; otherwise you
-// are at the boundary and the move follows from the steps.
+/**
+ * The single primary next move the dashboard suggests.
+ *
+ * It suggests; the dashboard prints the full list + counts so the human can
+ * always override. The phase is derived: a spike in progress and an in-flight
+ * step each have one obvious next move; otherwise you are at the boundary and
+ * the move follows from the steps.
+ */
 function nextMove(spiking, steps, inFlight, parked) {
     if (spiking) {
         return 'close the spike — `plumbbob spike done`';
     }
     if (inFlight !== null) {
-        return `finish step ${inFlight} — \`/pb-verify\` (or keep editing, then \`/pb-verify\`)`;
+        return `finish step ${inFlight} — \`/plumbbob:verify\` (or keep editing, then \`/plumbbob:verify\`)`;
     }
     // At the boundary (DESIGN): the move follows from the steps.
     const nextUndone = steps.find((s) => !s.done);
     if (nextUndone === undefined) {
         if (steps.length === 0) {
-            return 'plan the first step — `/pb-step`';
+            return 'plan the first step — `/plumbbob:step`';
         }
         // Batch-default: the steps were planned up front, so finishing them usually
-        // means "finish up" — but `/pb-step` can still add an increment if reality grew.
-        const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/pb-harvest\`; then ` : '';
-        return `${harvest}finish up — \`/pb-finish\` (or \`/pb-step\` to add another increment)`;
+        // means "finish up" — but `/plumbbob:step` can still add an increment if reality grew.
+        const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/plumbbob:harvest\`; then ` : '';
+        return `${harvest}finish up — \`/plumbbob:finish\` (or \`/plumbbob:step\` to add another increment)`;
     }
     return nextUndone.planned
-        ? `build step ${nextUndone.n} — \`/pb-build\` (or \`/pb-step\` to revise it first)`
-        : `plan step ${nextUndone.n} — \`/pb-step\``;
+        ? `build step ${nextUndone.n} — \`/plumbbob:build\` (or \`/plumbbob:step\` to revise it first)`
+        : `plan step ${nextUndone.n} — \`/plumbbob:step\``;
 }
+/**
+ * Assemble the full orientation from a build's raw documents and marker state.
+ */
 export function orient(input) {
     const steps = parseSteps(input.intent);
     const parked = parseParked(input.buildLog);
@@ -157,6 +193,9 @@ export function orient(input) {
         outOfBand: input.outOfBand,
     };
 }
+/**
+ * Render an Orientation as the plain-text dashboard `status` prints.
+ */
 export function formatOrientation(o) {
     const doneCount = o.steps.filter((s) => s.done).length;
     const nextUndone = o.steps.find((s) => !s.done);
@@ -167,7 +206,7 @@ export function formatOrientation(o) {
         if (s !== nextUndone) {
             return head;
         }
-        // Surface the next step's detail so the human can review it (and `/pb-step`-
+        // Surface the next step's detail so the human can review it (and `/plumbbob:step`-
         // revise) before building. Only what's present — a rough step shows neither.
         const detail = [];
         if (o.nextDoneWhen !== null) {
@@ -184,9 +223,9 @@ export function formatOrientation(o) {
     const stepsBlock = o.steps.length === 0 ? '  (no steps planned yet)' : `  steps  ${doneCount}/${o.steps.length} done\n${stepLines.join('\n')}`;
     const cp = o.lastCheckpoint;
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
-    // A neutral reconciliation note (D66), only when there is something to reconcile:
-    // commits landed since the last checkpoint that plumbbob's ledger didn't record.
-    // Informational — the human commits freely (repo D3/C5), so this never gates.
+    // A neutral reconciliation note, only when there is something to reconcile:
+    // commits landed since the last checkpoint that plumbbob's ledger didn't
+    // record. Informational — the human commits freely, so this never gates.
     const receipts = o.outOfBand > 0
         ? [`${o.outOfBand} commit${o.outOfBand === 1 ? '' : 's'} since the last checkpoint landed outside plumbbob's ledger.`]
         : [];

package/dist/lib/plugins.js

@@ -1,14 +1,17 @@
 // Detect a marketplace-installed plumbbob plugin from Claude Code's plugin state.
-// Used to keep the skills-dir install (`plumbbob init`) from colliding with a
-// marketplace install: two plugins both named `plumbbob` fight over the
-// `/plumbbob:*` namespace and the skills can drop to flat names (`/pb-status`).
-// Read-only, node builtins only (C1/C2): a missing / unreadable / malformed file
-// means "none installed".
+// Keeps the skills-dir install (`plumbbob init`) from colliding with a marketplace
+// install: two plugins both named `plumbbob` fight over the `/plumbbob:*` namespace
+// and the skills can drop to flat names (`/status`). Read-only, node builtins
+// only: a missing, unreadable, or malformed file means "none installed".
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-// Marketplace plugin ids for plumbbob recorded in installed_plugins.json
-// (e.g. "plumbbob@robmclarty"). Empty when none, or the file is absent/unreadable.
-// `plumbbob@<marketplace>` matches; `plumbbob-spike@x` and the like do not.
+/**
+ * Marketplace plugin ids for plumbbob recorded in installed_plugins.json.
+ *
+ * Ids look like "plumbbob@robmclarty": a bare `plumbbob` or a
+ * `plumbbob@<marketplace>` id matches; `plumbbob-spike@x` and the like do not.
+ * Empty when none are installed, or the file is absent, unreadable, or malformed.
+ */
 export function marketplacePlumbbob(home) {
     try {
         const raw = readFileSync(join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8');

package/dist/lib/settings.js

@@ -1,29 +1,42 @@
-// The settings ladder (D27): a resolved setting comes from, in priority order,
+// The settings ladder: a resolved setting comes from, in priority order,
 //   1. a CLI flag           — passed in by the verb (undefined when absent)
-//   2. settings.local.json  — untracked personal overlay + per-worktree cursor
+//   2. settings.local.json  — untracked personal overlay, per-worktree
 //   3. settings.json        — tracked project defaults
 //   4. a built-in default   — supplied by the caller
 // The first defined rung wins. Both files are optional JSON; a missing or
 // malformed file contributes nothing rather than throwing, so a broken personal
-// overlay can never wedge the tool. Functional/procedural, node builtins (C1/C2).
+// overlay can never wedge the tool. Functional and procedural, node builtins only.
 //
-// Known keys: `check` (string — the heavy gate, tracked in settings.json) and
-// `auto` (boolean — a personal preference, so it belongs in settings.local.json).
-// Since D67 `auto` is NOT a checkpoint grant: the latch no longer reads it to allow
-// a land (a model can write this file, and a grant it can forge is no grant), only to
-// note it at the pause; self-approval comes from the human's literal `/pb-build --auto`
-// or a range. The per-worktree active-build cursor is NOT here — it lives in the STATE
-// file (see sidecar.ts), so this overlay stays purely human-owned and the tool never
-// rewrites it.
+// Known keys: `check` (string — the command for the heavy verify gate, a project
+// default in settings.json) and `auto` (boolean — a personal preference, so it
+// belongs in settings.local.json). `auto` is NOT a checkpoint grant: the approval
+// latch never reads it to allow a land — a model can write this file, and a grant
+// it can forge is no grant — only to name it at the pause when set; self-approval
+// comes solely from the human's literal `/build --auto` or a typed step range.
+// The per-worktree active-build cursor is NOT here — it lives in the STATE file
+// (see sidecar.ts), which keeps this overlay a human-authored file rather than
+// tool-managed state.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-const DIRNAME = '.plumbbob';
+const DIRNAME = '.plumbbob'; // the sidecar folder name at the repo root
+/**
+ * The tracked project-defaults file: `.plumbbob/settings.json`.
+ */
 export function settingsPath(root) {
     return join(root, DIRNAME, 'settings.json');
 }
+/**
+ * The untracked personal overlay: `.plumbbob/settings.local.json`.
+ */
 export function localSettingsPath(root) {
     return join(root, DIRNAME, 'settings.local.json');
 }
+/**
+ * Read one settings file as a plain object.
+ *
+ * A missing, malformed, or non-object file yields {} — an empty rung that
+ * contributes nothing rather than wedging the tool.
+ */
 function readSettings(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, 'utf8'));
@@ -33,8 +46,12 @@ function readSettings(path) {
         return {};
     }
 }
-// The raw ladder: flag → local overlay → project defaults → undefined. The typed
-// helpers below apply the built-in default and reject wrong-typed rungs.
+/**
+ * The raw ladder: flag → local overlay → project defaults → undefined.
+ *
+ * The typed helpers below apply the built-in default and reject wrong-typed
+ * rungs.
+ */
 function resolveSetting(root, key, flag) {
     if (flag !== undefined)
         return flag;
@@ -43,40 +60,56 @@ function resolveSetting(root, key, flag) {
         return local;
     return readSettings(settingsPath(root))[key];
 }
-// Resolve a string setting (e.g. `check`). A missing rung, or one holding a
-// non-string / blank value, yields the caller's fallback rather than gating on
-// garbage.
+/**
+ * Resolve a string setting (e.g. `check`).
+ *
+ * A missing rung, or one holding a non-string / blank value, yields the
+ * caller's fallback rather than gating on garbage.
+ */
 export function resolveString(root, key, fallback, flag) {
     const value = resolveSetting(root, key, flag);
     return typeof value === 'string' && value.trim().length > 0 ? value : fallback;
 }
-// Resolve a boolean setting (e.g. `auto`). A missing or non-boolean rung yields
-// the caller's fallback.
+/**
+ * Resolve a boolean setting (e.g. `auto`). A missing or non-boolean rung
+ * yields the caller's fallback.
+ */
 export function resolveBoolean(root, key, fallback, flag) {
     const value = resolveSetting(root, key, flag);
     return typeof value === 'boolean' ? value : fallback;
 }
-// Resolve a non-negative integer setting (e.g. `agentTimeout`, D51). A missing
-// rung, or one holding a non-finite / negative / non-integer number, yields the
-// caller's fallback rather than a garbage timeout — 0 means "no timeout", so a
-// broken value must never silently become one.
+/**
+ * Resolve a non-negative integer setting (e.g. `agentTimeout`).
+ *
+ * A missing rung, or one holding a non-finite / negative / non-integer number,
+ * yields the caller's fallback rather than a garbage timeout — 0 means "no
+ * timeout", so a broken value must never silently become one.
+ */
 export function resolveNumber(root, key, fallback, flag) {
     const value = resolveSetting(root, key, flag);
     return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : fallback;
 }
-// Resolve an object-valued setting (e.g. the `agents` slot-binding defaults, D57)
-// across the same ladder. The first defined, object-typed rung wins; a missing
-// rung, or one holding a non-object / array / scalar, yields {} rather than
-// garbage — mirrors the string/boolean/number resolvers above. No flag rung: the
-// caller (`agent run`) merges these under the per-build harness, not over a flag.
+/**
+ * Resolve an object-valued setting (e.g. the `agents` slot-binding defaults)
+ * across the same ladder.
+ *
+ * The first defined, object-typed rung wins; a missing rung, or one holding a
+ * non-object / array / scalar, yields {} rather than garbage — mirrors the
+ * string/boolean/number resolvers above. No flag rung: the caller (`agent
+ * run`) merges these under the per-build harness bindings, not over a flag.
+ */
 export function resolveRecord(root, key) {
     const value = resolveSetting(root, key, undefined);
     return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {};
 }
-// Merge one key into settings.local.json, preserving the other keys and creating
-// the file when absent. Pretty-printed so the overlay stays hand-editable. A
-// malformed existing file contributes nothing (readSettings yields {}) and is
-// overwritten with a clean object rather than throwing.
+/**
+ * Merge one key into settings.local.json, preserving the other keys and
+ * creating the file when absent.
+ *
+ * Pretty-printed so the overlay stays hand-editable. A malformed existing file
+ * contributes nothing (readSettings yields {}) and is overwritten with a clean
+ * object rather than throwing.
+ */
 export function setLocalSetting(root, key, value) {
     const path = localSettingsPath(root);
     mkdirSync(dirname(path), { recursive: true });