plumbbob 0.10.3 → 0.11.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.10.3",
+  "version": "0.11.1",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -29,6 +29,45 @@ Ridgeline runs large, settled work autonomously without you, PlumbBob keeps you
 driver's seat for the work your judgment has to steer. This repository was built using
 PlumbBob itself, running its own loop.
 
+## Who it's for
+
+- **You already build with a coding agent and end the day reviewing a wall of diff.**
+  PlumbBob turns that wall into steps you approve one at a time, each small enough to
+  read as an editor.
+- **You are skeptical of AI-written code.** Nothing lands without a green check, a
+  self-review against the plan, and your say-so, and the CLI refuses to record a step
+  the model approved for itself.
+- **You would rather not learn a tool.** Everything it writes is markdown and ordinary
+  git commits in your own repo; the skills are slash commands, and `/plumbbob:status`
+  always names the next one. A [glossary](docs/glossary.md) covers the words it mints.
+- **Not for a typo, and not for a rewrite.** A one-line fix needs no session, and a
+  large, settled build wants an autonomous harness such as Ridgeline. The loop earns
+  its keep in between: a feature, a bug, a refactor.
+
+## The loop in one picture
+
+<p align="center">
+  <img src="docs/media/loop-one-step.svg" alt="One step of the loop: /plumbbob:build implements step 1 and stops at the pause, the human says looks good, the step is checkpointed" width="760">
+</p>
+
+Everything the model must stay true to lives in one file, the build's `intent.md`
+(under `.plumbbob/builds/<slug>/`), written before any code: the **Frame** (the problem, what done looks like, what you're
+explicitly *not* doing), the **Decisions** and **Constraints** (the settled calls, each
+with its *because*), and the **Steps**: a numbered list where every step carries a
+**done-when** (a checkable finish line, ideally a test) and a **seam** (the files it's
+expected to touch).
+
+```text
+/plumbbob:plan       decide everything on paper — frame, decisions, all steps    (once)
+  per step:
+    /plumbbob:build      implement the next step → run checks → self-review → PAUSE
+    (looks good)         → the step is committed as a checkpoint; fire /plumbbob:build again
+/plumbbob:finish     report what shipped and why, final commit, clear            (once)
+```
+
+Nothing is locked and nothing refuses you: the loop does a step's labor, pulls up to
+the line, and waits for you to advance it. **You are the clock.**
+
 ## What a prompt can't replicate
 
 A system prompt can *ask* a model to plan first and stop for review. What it can't do is
@@ -55,30 +94,10 @@ The planning surface is the on-ramp; these five are the floor under it. And the
 payoff is [measured, not asserted](#why-not-just), not just claimed. **Guidance on the
 work, a latch on the record.**
 
-## The loop in one picture
-
 <p align="center">
-  <img src="demo.svg" alt="An animated terminal session: /plumbbob:plan writes the plan, /plumbbob:build implements step 1 and stops at the PAUSE, the human approves, the step is checkpointed" width="760">
+  <img src="docs/media/build-record-in-pr.svg" alt="A pull request's file list with the build folder beside the source" width="760">
 </p>
 
-Everything the model must stay true to lives in one file, the build's `intent.md`
-(under `.plumbbob/builds/<slug>/`), written before any code: the **Frame** (the problem, what done looks like, what you're
-explicitly *not* doing), the **Decisions** and **Constraints** (the settled calls, each
-with its *because*), and the **Steps**: a numbered list where every step carries a
-**done-when** (a checkable finish line, ideally a test) and a **seam** (the files it's
-expected to touch).
-
-```text
-/plumbbob:plan       decide everything on paper — frame, decisions, all steps    (once)
-  per step:
-    /plumbbob:build      implement the next step → run checks → self-review → PAUSE
-    (approve)            → the step is committed as a checkpoint; fire /plumbbob:build again
-/plumbbob:finish     report what shipped and why, final commit, clear            (once)
-```
-
-Nothing is locked and nothing refuses you: the loop does a step's labor, pulls up to
-the line, and waits for you to advance it. **You are the clock.**
-
 ## Install
 
 PlumbBob installs **once, globally** (like `gh` or your dotfiles). Two ways work;
@@ -115,20 +134,68 @@ In Claude Code, inside any git repo with a clean tree:
    path to a spec file. Together you fill the build's `intent.md`. No code is written
    yet.
 2. **Build.** Fire `/plumbbob:build`. It implements the next undone step, runs the
-   heavy check gate, reviews its own diff against the plan, and stops:
+   heavy check gate, reviews its own diff against the plan, and stops. What it stops on
+   is one block with a fixed shape (the [turn anatomy](docs/presentation.md)): the CLI
+   measures the check, the seam, and the diff, the model supplies only the judgment, and
+   nothing is written around it.
+
+   ````markdown
+   **Summary**: A per-IP token bucket now refuses the 6th attempt inside a minute. (details: `.plumbbob/detail.md`)
+
+   1. The bucket lives in memory, keyed by IP, refilling five tokens a minute.
+   2. The clock is injected, so the test advances time instead of sleeping on it.
+
+   **Readout**: Step 1 - Add a token-bucket limiter
 
    ```text
-   PAUSE — read the diff as an editor. Approve to checkpoint, or send fixes.
+   check        green: 7 of 7 checks
+   done-when    met
+   decisions    2 of 2 honored
+   constraints  1 of 1 honored
+   seam         held: 2 of 2 declared, no strays
+   diff         +61 -3 across 2 files
+   spent        22 min · 2 turns · 41s gate · green first run
    ```
 
+   **Verdict**: ● Plumb
+
+   **Next Up**: Step 2 of 3 - Wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
+
+   **Your Call**:
+
+   - `looks good` → I checkpoint Step 1; back to the boundary
+   - `expand`, or any question → I show more of what is there; nothing changes
+   - anything that reads as direction → I take it as what to change; nothing lands until you approve
+   - `revert` → I wind the work back to the last checkpoint
+
+   **Recommendation**: Approve it. The gate is green, the seam held, and every call the step made is one the plan already decided.
+   ````
+
+   ![The build pause as Claude Code renders it](docs/media/pause.svg)
+
    (The check gate is [checkride](https://www.npmjs.com/package/checkride), one
    run across the tools your repo already configures: types, lint, tests, dead
    code, docs. To gate through your own command instead, set the `"check"` key in
-   `.plumbbob/settings.json`, for example `"check": "npm test"`.)
-3. **Approve**, or send fixes. On your OK it commits the step as a checkpoint, marks
-   it done, and returns to the boundary. Fire `/plumbbob:build` again for the next step:
-   re-firing it *is* the clock tick. Whenever you lose the thread, `/plumbbob:status` shows
-   where you are and names the next move.
+   `.plumbbob/settings.json`, for example `"check": "npm test"`; in a repo where
+   checkride finds no tools at all, `start` says so up front and names that key.)
+3. **Reply.** Say `looks good` and it commits the step as a checkpoint, marks it done,
+   and returns to the boundary with the same three lines every landed step gets:
+
+   ```text
+   **Checkpoint**: Step 1 complete (a1b2c3d4e, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/build-log.md:44`)
+
+   **Verdict**: ● Plumb
+
+   **Next Up**: Step 2 of 3 - Wire the limiter into POST /login (model: **Sonnet**, details: `.plumbbob/builds/2026-07-03-rate-limit-the-login-endpoint/intent.md:20`)
+   ```
+
+   ![The boundary after looks good](docs/media/checkpoint-boundary.svg)
+
+   Ask instead (`expand 2`, or any question) and it shows more of what is there and
+   changes nothing; direct it and it takes that as the fix, and nothing lands until you
+   say `looks good`. Then fire `/plumbbob:build` again for the next step: re-firing it
+   *is* the clock tick. Whenever you lose the thread, `/plumbbob:status` shows where you
+   are and names the next move.
 4. **Finish.** When the last step is done, `/plumbbob:finish` writes a report of what shipped
    and why into the build's tracked folder, makes the final commit, and clears the slate
    for the next goal. The folder rides the branch into the PR: the build's record merges
@@ -187,8 +254,9 @@ All fourteen, with inputs and effects, are in
 [`docs/skills-reference.md`](docs/skills-reference.md).
 
 Under the skills ships a lean `plumbbob` CLI (the mechanical verbs the
-skills shell out to), one session-gated post-edit hook (non-blocking lint feedback in
-flow), and a `.plumbbob/` sidecar you can open and edit by hand at any time: a tracked
+skills shell out to), three hooks (a non-blocking post-edit lint, a `git commit`
+ask-hook while a step is in flight, and the per-prompt turn ledger the approval latch
+reads), and a `.plumbbob/` sidecar you can open and edit by hand at any time: a tracked
 `builds/<slug>/` folder per build (`intent.md`, `build-log.md`, `checkpoints`, `report.md`)
 that rides the branch into the PR, plus an untracked control plane (`settings.local.json`,
 the session sentinel, the in-flight markers).
@@ -260,37 +328,26 @@ you, reading the diff. And when a raw commit does slip the ledger, `status` says
 checkpoint record makes recovery one command; cheap recovery, not a cage, is the control
 that matters.
 
-> The latch's payoff is measured, not asserted: the skill-eval harness
-> ([`test/evals/`](test/evals/)) sweeps this loop headless (prose-only baseline vs. the
-> shipped latch, N=5 per contract, every assertion a mechanical read of git state) and
-> commits each receipt under [`docs/evals/`](docs/evals/). The first sweep
-> ([opus, 2026-07-11](docs/evals/2026-07-11.md)) closed the route the latch owns
-> (*no checkpoint over a red check under pressure* went from **2/5 prose-only to 5/5
-> latched**) and named, rather than papered over, the two honest gaps it surfaced: park
-> capture at 0/5, and adversarial pressure flipping a standing `auto` grant a model could
-> write into settings, a legal side door. The re-sweep
-> ([opus, 2026-07-18](docs/evals/2026-07-18.md), plumbbob 0.8.7) reproduced the win
-> (*no checkpoint over a red check* still **5/5 latched**) and pinned both gaps. Both are
-> now closed. The side door went by construction: [D67 (auto-not-a-grant)](docs/decisions.md#d67)
-> (self-approval is human-typed only) retired the settings `auto` grant, so the one
-> approval a model could forge is gone. Park capture was never the latch's to reach,
-> prose-governed by design ([D10 (pause-not-lock)](docs/decisions.md#d10)/[D13 (no-edit-guards)](docs/decisions.md#d13)),
-> and it failed because the guidance couldn't reach a fresh session at all; the turn hook
-> now injects one line when a step is in flight, and the third sweep
-> ([opus, 2026-07-27](docs/evals/2026-07-27.md), plumbbob 0.9.0) measures it at **5/5**,
-> alongside every other contract. That sweep ran the latched arm only, so its numbers are
-> a regression check on the shipped configuration, not a fresh baseline delta: the
-> 2/5→5/5 headline above remains the 2026-07-11 measurement.
+> The latch's payoff is measured, not asserted. A headless skill-eval harness
+> ([`test/evals/`](test/evals/)) sweeps the loop with a prose-only baseline against the
+> shipped latch, every assertion a mechanical read of git state, and commits each receipt
+> under [`docs/evals/`](docs/evals/): the route the latch owns (*no checkpoint over a red
+> check under pressure*) went from **2/5 prose-only to 5/5 latched** on the first sweep
+> ([2026-07-11](docs/evals/2026-07-11.md)), every sweep since has held it and closed the
+> two gaps that one surfaced, and the latest ([2026-09-03](docs/evals/2026-09-03.md))
+> scores the shape of the turn itself.
 
 ## Documentation
 
 Each doc answers one question (in rough reading order for a new user):
 
 - *What does a session actually look like?* → [`docs/happy-path.md`](docs/happy-path.md): one goal walked end to end; read this first.
+- *What do the words mean?* → [`docs/glossary.md`](docs/glossary.md): every term the loop mints, one line each, with where to read more.
 - *Show me the artifacts it leaves behind.* → [`examples/`](examples/): that same session's finished build folder, file by file.
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md): the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md): steps, seams, the pause, park/harvest, spikes.
 - *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md): all fourteen skills: inputs, effects, when to reach for each.
+- *What does a turn look like, and who renders which part?* → [`docs/presentation.md`](docs/presentation.md): the anatomy of the pause, the boundary, and the driver turns.
 - *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md): the subprocess envelope, the manifest, `harness.json`, and working examples (including a local-model reviewer via Ollama).
 - *How do I get a local model reviewing my steps?* → [`docs/local-model-review.md`](docs/local-model-review.md): the ollama-reviewer example walked end to end, install to every-pause review.
 - *How do I install it, exactly?* → [`docs/install.md`](docs/install.md): the full guide and the agent-neutral roadmap.

package/dist/cli-core.js

@@ -79,11 +79,15 @@ const VERBS = [
     },
     {
         name: 'handoff',
-        description: 'print the standardized build hand-off block (pause or post-checkpoint); read-only',
-        synopsis: ['handoff [<n>] [--build <slug>]'],
+        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver); read-only',
+        synopsis: ['handoff [<n>] [--plan] [--driver] [--build <slug>]'],
         args: [{ name: '<n>', gloss: 'step to report on (default: the in-flight step, else the last checkpointed one)' }],
-        flags: [BUILD_FLAG],
-        notes: 'Read-only; refuses (exit 1) only with no session.',
+        flags: [
+            { name: '--plan', gloss: 'render the plan-pause card instead of a step tier' },
+            { name: '--driver', gloss: "render a driver turn's pointer back at the open step" },
+            BUILD_FLAG,
+        ],
+        notes: 'Read-only; refuses (exit 1) with no session, or with --plan and --driver together.',
     },
     {
         name: 'check',

package/dist/lib/agents.js

@@ -267,7 +267,7 @@ export function resolveAgent(root, name, opts = {}) {
     }
     return {
         ok: false,
-        error: `no agent named "${name}" — looked in ${projectAgentsDir(root)} and ${personalAgentsDir(home)}.`,
+        error: `no agent named "${name}", looked in ${projectAgentsDir(root)} and ${personalAgentsDir(home)}`,
     };
 }
 /**
@@ -610,7 +610,7 @@ function parseChildEnvelope(stdout) {
         raw = JSON.parse(stdout);
     }
     catch {
-        return { ok: false, error: 'the agent wrote non-JSON to stdout — the envelope must be a single JSON object.' };
+        return { ok: false, error: 'the agent wrote non-JSON to stdout, so the envelope is not a single JSON object' };
     }
     return parseEnvelope(raw);
 }

package/dist/lib/buildlog.js

@@ -118,6 +118,28 @@ export function checkpointLogLine(date, step, sha, title, stats = null) {
     const titled = title !== null && title.length > 0 ? `${head} — ${title}` : head;
     return stats !== null && stats.length > 0 ? `${titled} (${stats})` : titled;
 }
+/**
+ * The Log line `checkpoint --plan` writes when the plan lands: dated, with the
+ * short SHA. The cold read's record rides beneath it, so the first entry of a
+ * build's history is the plan and the read that approved it.
+ */
+export function planLogLine(date, sha) {
+    return `- ${date} — plan committed · ${sha.slice(0, 9)}`;
+}
+/**
+ * A Log entry: the dated line and, beneath it, the record of what landed (the
+ * pause as the human approved it), blank-line separated and indented two
+ * spaces so it nests as the line's own content. Blank lines inside the record
+ * stay bare rather than carrying the indent. A null record is the bare line,
+ * which is what a hand-built step with no detail file gets.
+ */
+export function logEntry(line, record) {
+    if (record === null || record.trim().length === 0) {
+        return line;
+    }
+    const nested = record.split('\n').map((l) => (l.trim().length === 0 ? '' : `  ${l}`));
+    return [line, '', ...nested].join('\n');
+}
 /**
  * The Log line `abandon` writes for a dropped-but-kept step: the first
  * non-checkpoint event the log records. Dated, names the step (its title when

package/dist/lib/check.js

@@ -4,7 +4,9 @@
 //     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);
+//     to keep throwaway repos deterministic), and leave the same
+//     `.check/summary.json` checkride would, so the pause's readout can
+//     measure the gate whichever path ran it;
 //   - no setting at all → checkride, our sibling package, imported
 //     programmatically rather than spawned: the typed summary comes back
 //     in-process, failing slots are reported with their `.check/` raw-output
@@ -13,7 +15,9 @@
 // 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 { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { runChecks, runDoctor } from 'checkride';
 import { gateIsRunningFor, withGateMarker } from "./reentry.js";
 import { resolveString } from "./settings.js";
@@ -103,17 +107,83 @@ export async function runCheck(root, flags = {}, commandFlag) {
     const command = resolveString(root, 'check', '', commandFlag);
     return withGateMarker(root, () => (command.length > 0 ? runCommand(root, command, flags) : runCheckride(root, flags)));
 }
+/** Where the configured command's combined output lands, relative to `.check/`. */
+const OVERRIDE_OUTPUT = 'check.stdout.txt';
+/** The longest a command may run as the summary's check name before it is cut with an ellipsis. */
+const OVERRIDE_NAME_BUDGET = 40;
 /**
  * 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.
+ * terminal as it arrives, keep a copy under `.check/`, and return its exit
+ * code. The command is trusted verbatim, no interpretation.
+ *
+ * The run leaves the same `summary.json` checkride would, with the command as
+ * its one check: the pause's readout measures its `check` row from that file
+ * and offers `looks good` only on a measured green, so a gate that left no
+ * summary rendered no row and withheld the move at every pause in a repo that
+ * gates through its own command.
  */
 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`);
     }
-    const result = spawnSync(command, { cwd: root, shell: true, stdio: 'inherit' });
-    return result.status ?? 1;
+    const started = Date.now();
+    return new Promise((resolve) => {
+        const chunks = [];
+        const child = spawn(command, { cwd: root, shell: true, stdio: ['inherit', 'pipe', 'pipe'] });
+        child.stdout.on('data', (chunk) => {
+            chunks.push(chunk);
+            process.stdout.write(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            chunks.push(chunk);
+            process.stderr.write(chunk);
+        });
+        child.on('error', () => resolve(1));
+        child.on('close', (code) => {
+            const exitCode = code ?? 1;
+            writeOverrideSummary(root, command, exitCode, Date.now() - started, Buffer.concat(chunks));
+            resolve(exitCode);
+        });
+    });
+}
+/**
+ * Record a configured command's run as a one-check summary under `.check/`,
+ * beside its captured output, in the shape checkride writes for its own runs.
+ *
+ * A summary that cannot be written is reported, never fatal: the gate's
+ * verdict is the command's exit code, and a full disk must not turn a green
+ * run red.
+ */
+function writeOverrideSummary(root, command, exitCode, durationMs, output) {
+    const ok = exitCode === 0;
+    const summary = {
+        schema_version: 1,
+        timestamp: new Date().toISOString(),
+        ok,
+        checks_run: 1,
+        total_duration_ms: durationMs,
+        checks: [
+            {
+                name: command.length <= OVERRIDE_NAME_BUDGET ? command : `${command.slice(0, OVERRIDE_NAME_BUDGET - 1)}…`,
+                adapter: null,
+                description: `the configured "check" command: ${command}`,
+                ok,
+                exit_code: exitCode,
+                duration_ms: durationMs,
+                output_file: OVERRIDE_OUTPUT,
+            },
+        ],
+    };
+    try {
+        const dir = join(root, '.check');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, OVERRIDE_OUTPUT), output);
+        writeFileSync(join(dir, 'summary.json'), `${JSON.stringify(summary, null, 2)}\n`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`plumbbob: could not record the check summary under .check/ (${message}).\n`);
+    }
 }
 /**
  * The checkride path: run the gate in-process, refuse an all-skipped run, and

package/dist/lib/git.js

@@ -76,19 +76,74 @@ export function isDirty(root) {
  * commits are surfaced, never blocked). `--first-parent` keeps the count on
  * the branch's own line: merging upstream reads as the one merge commit, not
  * the dozens it carried; those didn't land "outside the ledger" in any sense
- * the receipt should nag about. Best-effort and never throws: 0 when the range
- * is empty, `sha` is unknown to the repo, or HEAD is unborn: the count is
- * informational (the human commits freely), never a gate.
+ * the receipt should nag about. `excluding` is a commit-message pattern whose
+ * matches are left out of the count, which is how a caller drops plumbbob's own
+ * commits from a tally of what landed around them.
+ *
+ * Best-effort and never throws: 0 when the range is empty, `sha` is unknown to
+ * the repo, or HEAD is unborn: the count is informational (the human commits
+ * freely), never a gate.
  */
-export function commitsSince(root, sha) {
+export function commitsSince(root, sha, excluding) {
     try {
-        const n = Number.parseInt(runGit(root, ['rev-list', '--count', '--first-parent', `${sha}..HEAD`]), 10);
+        const skip = excluding === undefined ? [] : ['--grep', excluding, '--invert-grep'];
+        const n = Number.parseInt(runGit(root, ['rev-list', '--count', '--first-parent', ...skip, `${sha}..HEAD`]), 10);
         return Number.isFinite(n) && n > 0 ? n : 0;
     }
     catch {
         return 0;
     }
 }
+/**
+ * The working tree's changes against the index, one entry per file, as
+ * `git diff --numstat` reports them; a binary file counts 0/0.
+ *
+ * This feeds the recap's `diff` and `seam` rows at the pause: information,
+ * never a gate, so it is best-effort and never throws ([] on any failure).
+ */
+export function diffNumstat(root) {
+    let out;
+    try {
+        out = runGit(root, ['diff', '--numstat']);
+    }
+    catch {
+        return [];
+    }
+    if (out.length === 0) {
+        return [];
+    }
+    return out.split('\n').map((line) => {
+        const [added, removed, ...path] = line.split('\t');
+        return { added: toCount(added), removed: toCount(removed), path: path.join('\t') };
+    });
+}
+/**
+ * A numstat count field as a number: `-` (a binary file) and anything else
+ * unparseable read as 0.
+ */
+function toCount(field) {
+    const n = Number.parseInt(field ?? '', 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+/**
+ * The raw `git diff` patch for `paths` (working tree against the index), or ''
+ * when nothing differs or git refuses.
+ *
+ * Only the pause's inline-diff fence reads this, and only after the numstat
+ * count came in at 20 changed lines or fewer, so the patch is always small.
+ * Best-effort like diffNumstat: information, never a gate.
+ */
+export function diffPatch(root, paths) {
+    if (paths.length === 0) {
+        return '';
+    }
+    try {
+        return runGit(root, ['diff', '--', ...paths]);
+    }
+    catch {
+        return '';
+    }
+}
 // --- mutation helpers (build-loop: done checkpoints, revert resets). Additive
 // only: stage/commit forward, reset --hard to a recorded checkpoint SHA. ---
 /**

package/dist/lib/notice.js

@@ -0,0 +1,140 @@
+// The one renderer for every line plumbbob says out loud and a skill relays,
+// and the assembly that stacks those lines into an ending. It has three heads,
+// and the ending picks which: a transition's lead line goes to stdout wearing a
+// bold label, like every other part of the ending
+// (`**Checkpoint**: Step 15 complete (2d917cde7)`); an advisory riding that
+// ending goes to stdout too, as a bare sentence, since a block with one speaker
+// needs no one named; and a refusal goes to stderr keeping the `plumbbob:`
+// prefix, which earns its colon where checkride's output and git's share one
+// result. Under every head the shape is the same: the fact as one clause, the
+// detail a trailing parenthetical that degrades by count instead of running off
+// the edge, and an optional indented arrow line carrying what to do next. One
+// shape, so moving it is one edit rather than a sweep. The pointer at the next
+// step is not a line's job: `handoff` renders one, and the verb prints it as
+// the ending's last part. Pure string assembly, no fs, no gate.
+/** The column budget a notice line aims to fit, matching the readout fence. */
+const WIDTH = 80;
+/** The fewest detail items a degraded parenthetical still names, so the count has a universe to size. */
+const FLOOR = 2;
+/**
+ * Render one prefixed notice, newline included.
+ *
+ * The refusal head, and the head for a warning that joins no ending (an
+ * ambient agent that could not resolve, say):
+ *
+ * ```text
+ * plumbbob: no build named "auth" in .plumbbob/builds/ (rate-limit, logging)
+ *   → plumbbob use <slug>
+ * ```
+ */
+export function notice(n) {
+    return line(`${n.prefix ?? 'plumbbob'}: ${trimFact(n.fact)}${n.advisory === true ? ' ⚠' : ''}`, n);
+}
+/**
+ * Render one transition, newline included.
+ *
+ * The lead line of an ending, wearing a bold label so it reads as a part of the
+ * ending rather than as a second grammar beside it:
+ *
+ * ```text
+ * **Checkpoint**: Step 15 complete (2d917cde7)
+ * **Parked**: should /password-reset get the same throttle? (tangent)
+ * ```
+ *
+ * A transition never warns: an advisory qualifies the line and prints beneath
+ * it, on the same stream, as its own part of the ending.
+ */
+export function transition(t) {
+    return line(`**${t.label}**: ${trimFact(t.fact)}`, t);
+}
+/**
+ * Render one advisory of an ending, newline included.
+ *
+ * No prefix and no label: it rides stdout inside a block that has one speaker
+ * already, so it reads as the sentence it is, the warning glyph trailing the
+ * fact and the remedy on the line beneath.
+ *
+ * ```text
+ * Staged paths reach outside Step 16's seam ⚠ (test/integration/spike.test.ts)
+ *   → the checkpoint captures them, so revise the plan with /plumbbob:step
+ * ```
+ */
+export function advisory(a) {
+    return line(`${capitalize(trimFact(a.fact))} ⚠`, a);
+}
+/**
+ * Assemble a transition's whole ending: the labeled lead line, the Verdict
+ * where one was measured, the advisories, and the pointer.
+ *
+ * The order is the type's field order, so a verb composes parts and never a
+ * sequence. A part with nothing in it vanishes rather than leaving a gap.
+ */
+export function ending(e) {
+    return blocks([e.lead, e.verdict ?? null, ...(e.advisories ?? []), e.pointer ?? null]);
+}
+/**
+ * Stack a turn's parts: one blank line between each, one beneath the last.
+ *
+ * The trailing blank is the ending's own: the block is the turn's last text,
+ * and one flush against what follows cannot read as an ending. Empty parts drop
+ * out, so a caller can pass a part it may not have.
+ */
+export function blocks(parts) {
+    const kept = parts.filter((p) => p !== null && p.trim().length > 0);
+    return `${kept.map((p) => p.replace(/\n+$/, '')).join('\n\n')}\n\n`;
+}
+/**
+ * The head, its trailing parenthetical, and the remedy line beneath, assembled.
+ *
+ * The one place the parts meet, so a prefixed line and a labeled one can never
+ * drift in anything but their heads.
+ */
+function line(head, n) {
+    const detail = fit(head, (n.detail ?? []).map((d) => d.trim()).filter((d) => d.length > 0));
+    const text = detail.length === 0 ? head : `${head} (${detail.join(', ')})`;
+    return n.remedy === undefined ? `${text}\n` : `${text}\n  → ${n.remedy}\n`;
+}
+/**
+ * The fact as a bare clause: whitespace trimmed and one terminal period
+ * dropped.
+ *
+ * The formatter owns the line's punctuation, so a message composed elsewhere
+ * (a parse error, a park line a human wrote) still reads as one clause with a
+ * parenthetical after it rather than `… . (detail)`.
+ */
+function trimFact(fact) {
+    const text = fact.trim();
+    return text.endsWith('.') && !text.endsWith('..') ? text.slice(0, -1) : text;
+}
+/**
+ * The detail items that fit the width budget, with the overrun collapsed to a
+ * count.
+ *
+ * Two items or fewer are the fact's own qualifiers rather than a list, so they
+ * always render whole even when the line runs long: a notice wraps where a
+ * fence row cannot. A real list drops from the tail until the line fits,
+ * naming at least `FLOOR` of them, because a count with nothing beside it
+ * sizes a universe the reader cannot see.
+ */
+function fit(head, items) {
+    if (items.length <= FLOOR)
+        return items;
+    for (let keep = items.length; keep > FLOOR; keep -= 1) {
+        const shown = keep === items.length ? items : [...items.slice(0, keep), others(items.length - keep)];
+        if (columns(head) + columns(` (${shown.join(', ')})`) <= WIDTH)
+            return shown;
+    }
+    return [...items.slice(0, FLOOR), others(items.length - FLOOR)];
+}
+/** A fact's first letter raised, so an unprefixed advisory opens as a sentence. */
+function capitalize(fact) {
+    return fact.length === 0 ? fact : `${fact[0]?.toUpperCase()}${fact.slice(1)}`;
+}
+/** The collapsed tail naming how many items the line left out. */
+function others(count) {
+    return `and ${count} other${count === 1 ? '' : 's'}`;
+}
+/** A string's printed width, counted in code points so the glyphs measure as one column each. */
+function columns(text) {
+    return [...text].length;
+}