plumbbob 0.8.18 → 0.9.1

package/dist/lib/templates.js

@@ -1,15 +1,26 @@
 // Scaffold templates live at `<pkg-root>/templates/*.md` and carry `{{PLACEHOLDER}}`
-// tokens the verbs fill in. `start` stamps intent.md / build-log.md; `spike` stamps
-// spike-report.md. Shared here so both resolve the template dir the same way (relative
-// to the compiled module URL) and substitute with one mechanism. Pure/procedural,
-// node-builtins-only (C1/C2).
+// tokens the verbs fill in: `start` stamps intent.md and build-log.md, `spike` stamps
+// spike-report.md. Shared here so every verb resolves the template dir the same way
+// (relative to the compiled module URL) and substitutes with one mechanism. Pure and
+// procedural, node builtins only.
 import { fileURLToPath } from 'node:url';
 import { readFileSync } from 'node:fs';
+/**
+ * Read a template by filename from the package's `templates/` directory.
+ *
+ * Resolved relative to the compiled module URL, so the same relative hop works
+ * from `src/lib/` and `dist/lib/` alike — the templates ship with the package,
+ * never with the consumer's repo.
+ */
 export function readTemplate(name) {
     return readFileSync(fileURLToPath(new URL(`../../templates/${name}`, import.meta.url)), 'utf8');
 }
-// Replace every `{{KEY}}` with its value. Generic over the placeholder set so a new
-// template can add tokens (spike-report's `{{VIA}}`/`{{DATE}}`) without touching this.
+/**
+ * Replace every `{{KEY}}` in the template with its value from `subs`.
+ *
+ * Generic over the placeholder set so a new template can add tokens
+ * (spike-report's `{{VIA}}`/`{{DATE}}`) without touching this.
+ */
 export function stampTemplate(template, subs) {
     let out = template;
     for (const [key, value] of Object.entries(subs)) {

package/dist/verbs/agent.js

@@ -1,12 +1,17 @@
-// `plumbbob agent <subcommand>` — the doorway to user-authored agents (D39/D41).
-// `agent list` walks the two tiers and prints each resolvable agent. `agent run
-// <name> [--step N] [--mode before|build|after]` (D60) composes the StepContext,
+// `plumbbob agent <subcommand>` — the doorway to user-authored agents: anything
+// executable that speaks the JSON envelope contract (JSON in on stdin, JSON out
+// on stdout, prose streamed on stderr). `agent list` walks the two agent tiers —
+// the repo's tracked `.plumbbob/agents/<name>/`, then the personal
+// `~/.plumbbob/agents/<name>/` — and prints each resolvable agent. `agent run
+// <name> [--step N] [--mode before|build|after]` composes the StepContext,
 // spawns the manifest command, streams its stderr live, captures and validates
 // the child's envelope, re-emits it on this verb's own stdout (machine) with the
-// human summary on stderr (D46/D47), lands `parked[]` through the build-log (D44),
-// and appends the envelope to the step-scoped handoff ledger (D47). There is no
-// code path here to checkpoint, flip a step, or chain agents — the identity
-// invariant (C6) holds by construction. A thin read-write shell: resolution,
+// human summary on stderr, lands `parked[]` through the build-log, and appends
+// the envelope to the handoff ledger (`builds/<slug>/handoff.json` — untracked,
+// step-scoped, cleared at checkpoint) so later runs can thread it back in.
+// There is deliberately no code path here to checkpoint, flip a step, or chain
+// agents — the subprocess boundary keeps the human as the clock by
+// construction, not by policy. A thin read-write shell: resolution,
 // composition, and spawn mechanics live in lib/agents.ts.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -15,6 +20,9 @@ import { SLOTS, composeStepContext, formatAgentList, isSlot, listAgents, parseSl
 import { appendToSection } from "../lib/buildlog.js";
 import { resolveBoolean, resolveNumber, resolveRecord } from "../lib/settings.js";
 import { appendHandoff, buildFolder, buildLogPath, hasSession, intentPath, resolveBuild, stepPath } from "../lib/sidecar.js";
+/**
+ * Dispatch `plumbbob agent list|run`, refusing an unknown subcommand with a hint.
+ */
 export async function agent(cwd, args = []) {
     const [sub, ...rest] = args;
     if (sub === 'list')
@@ -26,6 +34,9 @@ export async function agent(cwd, args = []) {
     process.stderr.write(`${message}\n`);
     return 1;
 }
+/**
+ * Print every resolvable agent across the project and personal tiers.
+ */
 function list(cwd, _args) {
     const root = findRepoRoot(cwd);
     if (root === null) {
@@ -35,10 +46,15 @@ function list(cwd, _args) {
     process.stdout.write(`${formatAgentList(listAgents(root))}\n`);
     return 0;
 }
-// `agent run`: with a name (or `--agent` flag) run exactly that agent, failing
-// loud on a miss (D54); with no name run the step's harness-bound agents for the
-// requested slot (D42). Either way this composes the StepContext, spawns, and
-// applies side effects — never advancing the loop.
+/**
+ * Run one named agent, or a slot's harness-bound agents, against the step in flight.
+ *
+ * With a name (or `--agent` flag) it runs exactly that agent, failing loud on a
+ * miss — the user who typed the name asked for it specifically. With no name it
+ * runs whatever the build's harness.json binds to the requested slot. Either
+ * way it composes the StepContext, spawns, and applies side effects — never
+ * advancing the loop.
+ */
 async function run(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -62,8 +78,8 @@ async function run(cwd, args) {
         process.stderr.write('plumbbob: --agent needs an agent name too, for the run label. Try: plumbbob agent run reviewer --agent ./path --step 3.\n');
         return 1;
     }
-    // Explicit ask (a name, above the bindings — D57): run exactly it, fail loud on
-    // a miss. No name: resolve the harness bindings for the slot and run them.
+    // An explicit name outranks every binding: run exactly it, fail loud on a
+    // miss. No name: resolve the harness bindings for the slot and run them.
     if (parsed.name !== undefined) {
         return runOne(root, slug, step, {
             name: parsed.name,
@@ -74,6 +90,16 @@ async function run(cwd, args) {
     }
     return runBound(root, slug, step, parsed.mode);
 }
+/**
+ * One agent's full run: resolve it, pick its slot, compose the StepContext, spawn, report.
+ *
+ * `ambient` marks a harness-bound run whose resolution or slot mismatch
+ * degrades to a warning so a batch keeps going — a binding is ambient
+ * configuration the loop must survive without; an explicit ask
+ * (`ambient: false`) fails loud on the same miss. A run that actually starts
+ * and fails (non-zero exit, timeout, …) is a hard failure either way — the
+ * softening covers a *missing* agent, never a broken one.
+ */
 async function runOne(root, slug, step, spec) {
     const resolution = resolveAgent(root, spec.name, spec.flagPath !== undefined ? { flagPath: spec.flagPath } : {});
     if (!resolution.ok) {
@@ -99,15 +125,18 @@ async function runOne(root, slug, step, spec) {
         step,
         mode,
         settings: {
-            // The frozen envelope still reports settings `auto` to agents (doorway freeze —
-            // no envelope changes). Note it is no longer a checkpoint grant (D67): the latch
-            // stopped reading it, so a `true` here informs an agent, it does not self-approve.
+            // The envelope reports the `auto` setting to agents as information only.
+            // The checkpoint latch never reads it — a model can write a settings
+            // file, so a standing `auto` cannot be a self-approval grant; approval
+            // comes only from what the human literally typed. A `true` here informs
+            // an agent, it does not self-approve.
             auto: resolveBoolean(root, 'auto', false),
             agentTimeout: resolveNumber(root, 'agentTimeout', 0),
-            // Hand this agent its own config block over the frozen envelope `settings`
-            // field (D5/D6): settings.json → agentConfig[name], with the local overlay
-            // shadowing the project rung whole (D7 — no deep merge), and {} when neither
-            // defines it. No new envelope field, no new verb — the config just rides here.
+            // Hand this agent its own config block over the envelope's existing
+            // `settings` field — no new envelope field, no new verb; the config just
+            // rides here. Resolution: settings.json's agentConfig[name], with the
+            // untracked personal overlay (settings.local.json) replacing the project
+            // entry whole — no deep merge — and {} when neither defines it.
             agent: resolveRecord(root, 'agentConfig')[spec.name] ?? {},
         },
     });
@@ -127,11 +156,16 @@ async function runOne(root, slug, step, spec) {
     });
     return report(root, slug, spec.name, mode, step, result);
 }
-// No name given: run the harness-bound agents for the requested slot (D42). The
-// bindings merge the ladder — per-step over harness defaults over settings-level
-// defaults (D57). A missing bound agent degrades to a warning (D54); an absent
-// harness, or one that binds nothing to this slot, is a clean no-op. Each bound
-// agent runs in turn; the batch exits 1 if any agent that actually ran failed.
+/**
+ * No name given: run the agents the build's harness.json binds to the requested slot.
+ *
+ * Bindings merge as a ladder — the per-step harness entry beats the harness
+ * `defaults`, which beat the settings-level `agents` key; the first level that
+ * names the slot wins, replace not append. A missing bound agent degrades to a
+ * warning; an absent harness, or one that binds nothing to this slot, is a
+ * clean no-op. Each bound agent runs in turn; the batch exits 1 if any agent
+ * that actually ran failed.
+ */
 async function runBound(root, slug, step, modeFlag) {
     if (modeFlag === undefined) {
         process.stderr.write('plumbbob: agent run needs an agent name, or --mode <slot> to run the step\'s bound agents.\n');
@@ -165,18 +199,25 @@ async function runBound(root, slug, step, modeFlag) {
     }
     return worst;
 }
-// Emit the loud error or the soft warning by whether this run was an explicit ask
-// (name/flag) or an ambient harness binding (D54/D54), and return the matching
-// code — a hard miss stops with 1, a degraded one warns and returns 0 so a batch
-// of bound agents carries on.
+/**
+ * Emit the loud error or the soft warning by whether this run was an explicit
+ * ask (name/flag) or an ambient harness binding, and return the matching code.
+ *
+ * A hard miss stops with 1; a degraded one warns and returns 0 so a batch of
+ * bound agents carries on.
+ */
 function degrade(ambient, hard, soft) {
     process.stderr.write(`${ambient ? soft : hard}\n`);
     return ambient ? 0 : 1;
 }
-// Split `run`'s argv (with `--build` already stripped by resolveBuild) into the
-// agent name and the value flags. A value flag missing its value, or `--step`
-// given a non-number, is a loud error (returned as a string) rather than a silent
-// default. Unknown `--flags` are ignored — the point is the named agent.
+/**
+ * Split `run`'s argv (with `--build` already stripped by resolveBuild) into the
+ * agent name and the value flags.
+ *
+ * A value flag missing its value, or `--step` given a non-number, is a loud
+ * error (returned as a string) rather than a silent default. Unknown `--flags`
+ * are ignored — the point is the named agent.
+ */
 function parseRunArgs(args) {
     const positionals = [];
     let step;
@@ -209,11 +250,15 @@ function parseRunArgs(args) {
     }
     return { name: positionals[0], step, mode, flagPath };
 }
-// Resolve the slot the agent runs in. An explicit `--mode` must name a real slot
-// AND one the manifest declares — an undeclared slot is refused loud (D54). With
-// no `--mode`, a single-slot agent uses its only slot; a multi-slot agent must be
-// told which one (step 5's harness bindings pick the slot from the lifecycle
-// point; a bare `run` cannot guess).
+/**
+ * Resolve the slot the agent runs in.
+ *
+ * An explicit `--mode` must name a real slot AND one the manifest declares —
+ * an undeclared slot is refused loud, because the user asked for that exact
+ * run. With no `--mode`, a single-slot agent uses its only slot; a multi-slot
+ * agent must be told which one (harness bindings pick the slot from the
+ * lifecycle point; a bare `run` cannot guess).
+ */
 function resolveMode(flag, manifest) {
     if (flag !== undefined) {
         if (!isSlot(flag))
@@ -233,13 +278,16 @@ function resolveMode(flag, manifest) {
         error: `plumbbob: agent "${manifest.name}" declares multiple slots (${manifest.slots.join(', ')}) — pass --mode <slot>.`,
     };
 }
-// Map the run outcome to reporting and side effects (D46). A failed run — non-zero
-// exit, out-of-contract stdout, timeout, interrupt, or a shell that never
-// started — reports on stderr and stops with NO side effects (the envelope of a
-// failed child is not authoritative). A clean run lands `parked[]` (D44), records
-// the envelope in the handoff ledger (D47), prints the human summary on stderr,
-// and re-emits the machine envelope on stdout — nothing else, ever (the stream
-// discipline: stdout carries the envelope alone).
+/**
+ * Map the run outcome to reporting and side effects.
+ *
+ * A failed run — non-zero exit, out-of-contract stdout, timeout, interrupt, or a
+ * shell that never started — reports on stderr and stops with NO side effects:
+ * the envelope of a failed child is not authoritative. A clean run lands
+ * `parked[]`, records the envelope in the handoff ledger, prints the human
+ * summary on stderr, and re-emits the machine envelope on stdout — nothing else,
+ * ever (the stream discipline: stdout carries the envelope alone).
+ */
 function report(root, slug, name, mode, step, result) {
     if (!result.ok) {
         process.stderr.write(`${failureLine(name, result)}\n`);
@@ -252,6 +300,9 @@ function report(root, slug, name, mode, step, result) {
     process.stdout.write(`${JSON.stringify(envelope)}\n`);
     return 0;
 }
+/**
+ * One stderr line naming exactly how a failed run failed.
+ */
 function failureLine(name, result) {
     switch (result.reason) {
         case 'exit':
@@ -266,9 +317,13 @@ function failureLine(name, result) {
             return `plumbbob: could not spawn agent "${name}" — ${result.error}`;
     }
 }
-// Land each parked concern through the build-log's Park list (D44 — the agent
-// never writes .plumbbob/ itself). A build-log with no "## Park list" section, or
-// no build-log at all, warns once rather than losing the lines silently.
+/**
+ * Land each parked concern through the build-log's Park list.
+ *
+ * The agent never writes .plumbbob/ itself — parked lines only reach the
+ * build-log through this verb. A build-log with no "## Park list" section, or no
+ * build-log at all, warns once rather than losing the lines silently.
+ */
 function applyParked(root, slug, parked) {
     if (parked.length === 0)
         return;
@@ -292,10 +347,13 @@ function applyParked(root, slug, parked) {
     }
     writeFileSync(path, content);
 }
-// The human-facing summary on stderr (D47): a headline plus, for a halt, the
-// route the skills name (D52) — `blocked` unblocks and re-runs, `drift` sends the
-// plan to /pb-refine. The machine envelope on stdout carries the same status for
-// the calling skill; this is the terminal read.
+/**
+ * The human-facing summary printed on stderr.
+ *
+ * A headline plus, for a halt, the route out — `blocked` unblocks and re-runs,
+ * `drift` sends the plan to /plumbbob:refine. The machine envelope on stdout carries
+ * the same status for the calling skill; this stderr copy is the terminal read.
+ */
 function humanSummary(name, mode, envelope) {
     const head = `plumbbob: agent "${name}" (${mode}) — ${envelope.status}: ${envelope.summary}\n`;
     const notes = envelope.notes.length > 0 ? `  notes: ${envelope.notes}\n` : '';
@@ -303,12 +361,15 @@ function humanSummary(name, mode, envelope) {
         return `${head}  blocked — the agent couldn't finish; unblock and re-run.\n${notes}`;
     }
     if (envelope.status === 'drift') {
-        return `${head}  drift — the plan no longer matches reality; /pb-refine before continuing.\n${notes}`;
+        return `${head}  drift — the plan no longer matches reality; /plumbbob:refine before continuing.\n${notes}`;
     }
     return head;
 }
-// The in-flight step for this build (the STEP marker `build` wrote), or null when
-// none is set — the caller then requires an explicit `--step`.
+/**
+ * The in-flight step for this build (the STEP marker `build` wrote), or null.
+ *
+ * With no marker set, the caller requires an explicit `--step`.
+ */
 function readStep(root, slug) {
     try {
         const raw = readFileSync(stepPath(root, slug), 'utf8').trim();

package/dist/verbs/build.js

@@ -1,12 +1,23 @@
-// `plumbbob build <n>` — read step n's seam from intent.md, write the normalized
-// SEAM + STEP. The STEP file is the in-flight signal (the dashboard derives the
-// BUILD phase from it); it never checkpoints (only `checkpoint` commits).
+// `plumbbob build <n>` — enter a step: read step n's seam from intent.md and
+// write the normalized SEAM + STEP control files (flat, untracked, per-build).
+// The seam is the step's edit grant — the exact paths and `dir/` prefixes the
+// step expects to touch, for orientation, never a lock. The STEP file is the
+// in-flight signal (the dashboard derives the BUILD phase from it); this verb
+// never checkpoints — only `checkpoint` commits.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTick, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
 import { parseSteps } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
+/**
+ * Enter step n — or the next undone step — and write its SEAM/STEP markers.
+ *
+ * Refuses a missing session, a malformed step argument, an `N-M` range (a
+ * `/plumbbob:build` skill feature, not a CLI one), and a seam that fails to parse.
+ * On entry it stamps the turn ledger and the step's start time, and re-renders
+ * the build-log's Current step line.
+ */
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -15,11 +26,11 @@ export function build(cwd, args) {
     }
     const { build: slug, rest } = resolveBuild(root, args);
     const raw = rest.find((a) => !a.startsWith('--'));
-    // A step range like `1-3` is a `/pb-build` skill affordance (auto-approve
+    // A step range like `1-3` is a `/plumbbob:build` skill affordance (auto-approve
     // through the range, then pause), not a CLI capability — the CLI records one
     // in-flight step at a time. Name it rather than bounce off the generic usage.
     if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
-        process.stderr.write(`plumbbob: build takes one step number; \`${raw}\` step ranges are a \`/pb-build\` feature (auto-approve through the range, then pause). Try \`plumbbob build ${raw.split('-')[0]}\`.\n`);
+        process.stderr.write(`plumbbob: build takes one step number; \`${raw}\` step ranges are a \`/plumbbob:build\` feature (auto-approve through the range, then pause). Try \`plumbbob build ${raw.split('-')[0]}\`.\n`);
         return 1;
     }
     // An explicit arg that isn't a positive integer is a usage error — caught before
@@ -31,13 +42,13 @@ export function build(cwd, args) {
     const intent = readFileSync(intentPath(root, slug), 'utf8');
     // No argument ⇒ enter the next undone step in intent.md (the same idiom
     // `checkpoint` uses), so a bare `plumbbob build` advances the loop without the
-    // skill re-deriving the step in prose. Every step checkpointed ⇒ a `/pb-step`
+    // skill re-deriving the step in prose. Every step checkpointed ⇒ a `/plumbbob:step`
     // nudge, not a silent no-op.
     let step;
     if (raw === undefined) {
         const nextUndone = parseSteps(intent).find((s) => !s.done);
         if (nextUndone === undefined) {
-            process.stderr.write('plumbbob: no undone step to build — every planned step is checkpointed. `/pb-step` to add an increment, or `/pb-finish`.\n');
+            process.stderr.write('plumbbob: no undone step to build — every planned step is checkpointed. `/plumbbob:step` to add an increment, or `/plumbbob:finish`.\n');
             return 1;
         }
         step = nextUndone.n;
@@ -52,12 +63,16 @@ export function build(cwd, args) {
     }
     writeFileSync(seamPath(root, slug), `${parsed.seam.join('\n')}\n`);
     writeFileSync(stepPath(root, slug), `${step}\n`);
-    stampTick(root, slug); // the entry stamp (D64): TICK = TURN; skipped when the ledger is dormant.
-    // The wall-clock receipt starts here (research/07 Build 2b): checkpoint stamps
-    // landedAt, and the pair becomes the step's duration in the finish report.
+    // Stamp the turn ledger on entry (TICK = TURN): the checkpoint latch demands
+    // a human turn after this point before the step may land. Skipped when the
+    // ledger is dormant — a host with no hooks grows no TURN/TICK files.
+    stampTick(root, slug);
+    // The wall-clock receipt starts here: checkpoint stamps landedAt, and the
+    // pair becomes the step's duration in the finish report.
     stampStepStat(root, slug, step, 'startedAt', new Date().toISOString());
-    // The build-log's top half now shows this step in flight (D69): Current step +
-    // the ☐/☑ mirror, re-rendered from intent.md. Best-effort — never blocks the build.
+    // The build-log's top half is CLI-owned so it never lies: show this step in
+    // flight — Current step plus the ☐/☑ mirror, re-rendered from intent.md.
+    // Best-effort — a missing or hand-edited build-log never blocks the build.
     const title = parseSteps(intent).find((s) => s.n === step)?.title ?? null;
     syncBuildLogState(root, slug, stepLabel(step, title));
     const picked = raw === undefined ? ' (next undone)' : '';

package/dist/verbs/check.js

@@ -1,14 +1,24 @@
-// `plumbbob check` — run the heavy gate (D16/D24/D32) and report, with NO state
-// change. The read-only half of the verify tick: `/pb-verify` runs this before the
-// pause so the human approves on a known-green check. Exits with the check's own
-// code (0 = green, 1 = red, 2 = the gate itself broke).
+// `plumbbob check` — run the heavy gate and report, with NO state change. This
+// is the read-only half of the verify tick: `/plumbbob:verify` runs it before the
+// pause so the human approves on a known-green check. The gate itself lives in
+// lib/check.ts: checkride (our sibling check-runner package) by default, or a
+// spawn command named by the `check` setting — resolved through the settings
+// ladder (flag → local overlay → tracked settings.json → default) — for repos
+// that gate through something else. Exits with the check's own code (0 = green,
+// 1 = red, 2 = the gate itself broke).
 //
 // Narrowing flags for the iteration loop (`check --bail --only types,lint`) map
-// straight onto checkride's RunFlags (D32). Only this verb takes them — the
+// straight onto checkride's run flags. Only this verb takes them — the
 // checkpoint gate is always full-fat.
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
+/**
+ * Run the heavy check gate for the active session and print the verdict line.
+ *
+ * Refuses without a session; otherwise returns the gate's own exit code so a
+ * caller can branch on green (0), red (1), or a broken gate (2) directly.
+ */
 export async function check(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -19,8 +29,12 @@ export async function check(cwd, args = []) {
     process.stdout.write(verdictLine(code));
     return code;
 }
-// argv → CheckFlags: bare booleans plus comma-separated slot lists. Unknown
-// args are ignored rather than refused — the gate itself is the point.
+/**
+ * Map argv onto checkride's flags: bare booleans plus comma-separated slot lists.
+ *
+ * Unknown args are ignored rather than refused — running the gate is the point,
+ * not flag hygiene.
+ */
 function parseFlags(args) {
     return {
         ...(args.includes('--bail') ? { bail: true } : {}),
@@ -31,6 +45,12 @@ function parseFlags(args) {
         ...slotList(args, '--include'),
     };
 }
+/**
+ * Read one `--only a,b`-style flag into its slot-list entry.
+ *
+ * Returns {} when the flag is absent, valueless, or followed by another flag,
+ * so the spread in parseFlags simply contributes nothing.
+ */
 function slotList(args, flag) {
     const i = args.indexOf(flag);
     const value = i >= 0 ? args[i + 1] : undefined;
@@ -42,6 +62,12 @@ function slotList(args, flag) {
         .filter((s) => s.length > 0);
     return names.length > 0 ? { [flag.slice(2)]: names } : {};
 }
+/**
+ * The one-line human verdict for a check exit code.
+ *
+ * A broken gate (exit 2) reports distinctly from red — a misconfigured harness
+ * must never read as broken code, though both block a checkpoint.
+ */
 function verdictLine(code) {
     if (code === 0)
         return '\nplumbbob: check green.\n';