plumbbob 0.12.1 → 0.13.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "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

@@ -140,12 +140,14 @@ In Claude Code, inside any git repo with a clean tree:
    nothing is written around it.
 
    ````markdown
+   **Now**: Step 1 of 3 - feat(limiter): add a token-bucket limiter
+
    **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 - feat(limiter): add a token-bucket limiter
+   **Readout**:
 
    ```text
    check        green: 7 of 7 checks
@@ -164,7 +166,7 @@ In Claude Code, inside any git repo with a clean tree:
    **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
+   - `expand`, or any question → I show more of what is there; nothing changes, and `show the pause` brings all of this back
    - 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
 
@@ -192,8 +194,10 @@ In Claude Code, inside any git repo with a clean tree:
    ![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
+   changes nothing. The answer closes on one line pointing back at the step, not on the
+   whole block again, since you have already read it; say `show the pause` to see the
+   block again. 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
@@ -254,9 +258,10 @@ 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), 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
+skills shell out to), four hooks (a non-blocking post-edit lint, a `git commit`
+ask-hook while a step is in flight, the per-prompt turn ledger the approval latch
+reads, and a check at each turn's end that the turn relayed the ending plumbbob
+printed), 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).

package/dist/cli-core.js

@@ -28,6 +28,7 @@ import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
 import { recover } from "./verbs/recover.js";
 import { agent } from "./verbs/agent.js";
+import { relay } from "./verbs/relay.js";
 import { turn } from "./verbs/turn.js";
 /** Shared across every verb that resolves through the active-build cursor. */
 const BUILD_FLAG = {
@@ -80,15 +81,16 @@ const VERBS = [
     },
     {
         name: 'handoff',
-        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver); read-only',
-        synopsis: ['handoff [<n>] [--plan] [--driver] [--build <slug>]'],
+        description: 'print the footer card that ends a turn (pause, boundary, plan, or driver), or a reminder for a pause already shown',
+        synopsis: ['handoff [<n>] [--full] [--plan] [--driver] [--build <slug>]'],
         args: [{ name: '<n>', gloss: 'step to report on (default: the in-flight step, else the last checkpointed one)' }],
         flags: [
+            { name: '--full', gloss: 'print the whole pause card even when that pause was already shown' },
             { 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.',
+        notes: 'Writes only the detail file (a blank line around each heading) and the PAUSE stamp; refuses (exit 1) with no session, or with --plan and --driver together.',
     },
     {
         name: 'check',
@@ -225,6 +227,13 @@ const VERBS = [
         tolerateUnknownFlags: true,
         notes: 'Reads the hook payload from stdin and always exits 0 — a broken hook must never wedge a prompt.',
     },
+    {
+        name: 'relay',
+        description: 'Stop hook machinery: check that the turn carried the ending it printed (not a user verb)',
+        synopsis: ['relay'],
+        tolerateUnknownFlags: true,
+        notes: "Reads the hook payload from stdin and always exits 0: a broken hook must never wedge a turn's end.",
+    },
 ];
 /**
  * Render the verb table for `plumbbob help`.
@@ -379,6 +388,8 @@ async function dispatch(verb, cwd, rest) {
             return agent(cwd, rest);
         case 'turn':
             return turn(cwd, rest);
+        case 'relay':
+            return relay(cwd, rest);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;

package/dist/lib/git.js

@@ -68,18 +68,30 @@ export function hasCommit(root) {
 export function isDirty(root) {
     return runGit(root, ['status', '--porcelain']).length > 0;
 }
+/**
+ * The body line that marks a plan commit made by hand (a `chore(plan)`
+ * harvest). A harvest lands between nearly every step, so counting it as
+ * out-of-band would trip the advisory on routine housekeeping and stop meaning
+ * anything within three steps. `status` and `handoff` both pass it to
+ * `commitsSince`, which is what keeps the two counts one quantity.
+ */
+export const PLAN_COMMIT_MARKER = '^plumbbob plan$';
 /**
  * The number of commits on HEAD not reachable from `sha`: `git rev-list
  * --count --first-parent <sha>..HEAD`.
  *
- * `status` reads this for its receipts line: one neutral note when commits
- * landed since the last checkpoint outside plumbbob's ledger (out-of-band
- * 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. `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.
+ * `status` and `handoff` both read this for their out-of-band count: one
+ * neutral note when commits landed since the last checkpoint outside
+ * plumbbob's ledger (out-of-band commits are surfaced, never blocked). Two
+ * mechanisms keep plumbbob's own commits out of that count. A commit any
+ * plumbbob verb makes is recorded in the ledger and becomes the anchor, so the
+ * range starts after it. A plan commit made by hand carries
+ * `PLAN_COMMIT_MARKER` on a line of its body, and both callers pass it as
+ * `excluding` so the range drops it. `--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. `excluding` is a commit-message pattern whose
+ * matches are left out of the count.
  *
  * 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

package/dist/lib/notice.js

@@ -11,7 +11,10 @@
 // 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 ending's last part. The formatters are pure string assembly, no fs, no
+// gate; `printEnding` is the one function here that writes, and every ending
+// a verb prints goes through it so the relay check knows what was said.
+import { writeRelay } from "./sidecar.js";
 /** 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. */
@@ -83,6 +86,17 @@ 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`;
 }
+/**
+ * Print an ending to stdout and record it in RELAY, for the Stop check that
+ * the turn closed on it.
+ *
+ * Stdout first, and the record never throws: a failed write leaves the
+ * printed ending and the verb's exit code exactly as they would have been.
+ */
+export function printEnding(root, relay) {
+    process.stdout.write(relay.text);
+    writeRelay(root, relay);
+}
 /**
  * The head, its trailing parenthetical, and the remedy line beneath, assembled.
  *

package/dist/lib/orient.js

@@ -903,6 +903,45 @@ export function parseSummary(detail) {
     }
     return { lead, highlights };
 }
+/**
+ * `.plumbbob/detail.md` with a blank line around every heading, and everything
+ * else as written.
+ *
+ * A model copying the detail template can run a heading straight into its body
+ * or its predecessor, and markdownlint's MD022 fails that file wherever
+ * `.plumbbob/` is linted, which turns a downstream checkpoint red. Heading lines
+ * inside a fenced block are content, not headings, so a fence is left whole.
+ * Pure and idempotent: text that already has its blank lines comes back byte for
+ * byte, so a caller can compare the result to the input to learn whether
+ * anything needed fixing.
+ */
+export function normalizeDetailHeadings(detail) {
+    const out = [];
+    let fence = null;
+    let afterHeading = false;
+    for (const line of detail.split('\n')) {
+        if (fence !== null) {
+            const close = /^ {0,3}(`{3,}|~{3,})\s*$/.exec(line)?.[1];
+            if (close !== undefined && close.startsWith(fence.char) && close.length >= fence.length) {
+                fence = null;
+            }
+            out.push(line);
+            continue;
+        }
+        const heading = /^ {0,3}#{1,6}(\s|$)/.test(line);
+        const prior = out[out.length - 1];
+        if ((heading || afterHeading) && line.trim() !== '' && prior !== undefined && prior.trim() !== '') {
+            out.push('');
+        }
+        const open = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (open !== undefined) {
+            fence = { char: open.charAt(0), length: open.length };
+        }
+        out.push(line);
+        afterHeading = heading;
+    }
+    return out.join('\n');
+}
 /**
  * The `## <n>` sections of `.plumbbob/detail.md` with their bodies: the full
  * story behind each highlight, in the order the model wrote them. The body is
@@ -989,7 +1028,10 @@ export function formatOrientation(o) {
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
     // 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.
+    // record. A commit a plumbbob verb makes starts the range, and a hand-made
+    // plan commit drops out on its `plumbbob plan` body marker, so the count is
+    // the same one `handoff` folds into its Verdict. 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/sidecar.js

@@ -213,6 +213,21 @@ export function stepPath(root, slug) {
 export function clearStep(root, slug) {
     rmSync(stepPath(root, slug), { force: true });
 }
+/**
+ * PAUSE: the stamp of the step pause `handoff` last rendered whole, the step
+ * number and a hash of what the card showed. While a later render matches it,
+ * handoff prints the one-line reminder instead of the card.
+ */
+export function pausePath(root, slug) {
+    return join(artifactDir(root, slug), 'PAUSE');
+}
+/**
+ * Remove the PAUSE stamp: a checkpoint, a revert, or an abandon ends the pause
+ * it recorded, so the next pause renders whole. Absent is a no-op.
+ */
+export function clearPause(root, slug) {
+    rmSync(pausePath(root, slug), { force: true });
+}
 /**
  * The build's `checkpoints` ledger: the recorded SHAs of landed plan and step
  * commits, one line each.
@@ -536,6 +551,131 @@ export function readTurn(root) {
         return null;
     }
 }
+// --- The relay record: `.plumbbob/RELAY`, the ending the CLI printed last, so a
+// Stop hook can check that the turn closed on it. The verb that prints an
+// ending records it here: it knows what it printed, where a hook scraping
+// stdout would have to guess which command ran. Flat like TURN, because the
+// turn it is checked against is the session's, not a build's. A later ending
+// overwrites an earlier one, so a turn is judged by the last thing it printed. ---
+// The tiers of docs/presentation.md, which decide how a turn has to carry an
+// ending: a decision ending closes the turn, an orientation ending appears in
+// it, and a driver ending is recorded only so that the last ending wins.
+const RELAY_TIERS = ['decision', 'orientation', 'driver'];
+// Which ending printed: handoff's six forms first, then one per transition. It
+// is what the check's reason names when the ending went missing.
+const RELAY_RENDERS = [
+    'card',
+    'reminder',
+    'plan',
+    'boundary',
+    'pointer',
+    'driver',
+    'checkpoint',
+    'plan-commit',
+    'park',
+    'revert',
+    'abandon',
+    'spike-open',
+    'spike-report',
+    'spike-done',
+    'use',
+    'order',
+    'finish',
+    'start',
+];
+/**
+ * RELAY: the ending the CLI printed last, at the flat sidecar root.
+ */
+export function relayPath(root) {
+    return join(root, DIRNAME, 'RELAY');
+}
+/**
+ * Record an ending in RELAY, stamped with the current TURN: a header of
+ * `key value` lines, a blank line, then the text exactly as it printed.
+ *
+ * Written only while TURN holds a count, the same dormancy `stampTick` keeps: a
+ * host with no turn hook has no turn to check the ending against. Best-effort
+ * by contract, since the ending has already reached stdout and a failed record
+ * must not change it or the exit code.
+ */
+export function writeRelay(root, relay) {
+    const turn = readTurn(root);
+    if (turn === null)
+        return;
+    // A hold the check already spent on this turn survives the ending the retry
+    // reprints, or a turn whose retry missed again would be held a second time.
+    const held = readRelay(root)?.held === turn ? { held: turn } : {};
+    try {
+        writeFileSync(relayPath(root), formatRelay({ ...relay, turn, ...held }));
+    }
+    catch {
+        // A read-only tree or a directory in the way: the ending already printed.
+    }
+}
+/**
+ * Stamp the record with the turn the check held open over it, so the check
+ * holds at most once per turn. False when the stamp could not be written, and
+ * the check then holds nothing, since a hold it cannot count could repeat.
+ */
+export function holdRelay(root, record) {
+    try {
+        writeFileSync(relayPath(root), formatRelay({ ...record, held: record.turn }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A record as RELAY stores it: the header's `key value` lines, a blank line, then the text. */
+function formatRelay(record) {
+    const header = [`turn ${record.turn}`, `tier ${record.tier}`, `render ${record.render}`];
+    if (record.command !== undefined)
+        header.push(`command ${record.command}`);
+    if (record.held !== undefined)
+        header.push(`held ${record.held}`);
+    return `${header.join('\n')}\n\n${record.text}`;
+}
+/**
+ * The recorded ending, or null when RELAY is absent or its header does not
+ * parse: a record the check cannot read is no record.
+ */
+export function readRelay(root) {
+    let raw;
+    try {
+        raw = readFileSync(relayPath(root), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const split = raw.indexOf('\n\n');
+    if (split === -1)
+        return null;
+    const fields = new Map();
+    for (const line of raw.slice(0, split).split('\n')) {
+        const space = line.indexOf(' ');
+        if (space > 0)
+            fields.set(line.slice(0, space), line.slice(space + 1));
+    }
+    const turn = count(fields.get('turn'));
+    const tier = RELAY_TIERS.find((t) => t === fields.get('tier'));
+    const render = RELAY_RENDERS.find((r) => r === fields.get('render'));
+    if (turn === null || tier === undefined || render === undefined)
+        return null;
+    const command = fields.get('command');
+    const held = count(fields.get('held'));
+    return {
+        turn,
+        tier,
+        render,
+        ...(command === undefined ? {} : { command }),
+        ...(held === null ? {} : { held }),
+        text: raw.slice(split + 2),
+    };
+}
+/** A header field read as a bare count, or null when it is absent or anything else. */
+function count(field) {
+    return field !== undefined && /^\d+$/.test(field) ? Number(field) : null;
+}
 /**
  * Walk up from `cwd` to the nearest ancestor with an active session (a
  * `.plumbbob/STATE` file), or null when there is none.
@@ -600,16 +740,22 @@ export function excludeControl(root) {
         `${DIRNAME}/TURN`,
         `${DIRNAME}/GRANT`,
         // The in-flight step's detail file: flat per-session control the model
-        // overwrites before every pause. checkpoint folds it into the commit body
-        // and then clears it, so its archive is the commit, never a tracked path;
-        // excluding it keeps stageAll from ever sweeping it into a step commit.
+        // overwrites before every pause. checkpoint records it in the build-log's
+        // Log and then clears it, so its archive is the tracked ledger, never this
+        // path; excluding it keeps stageAll from ever sweeping it into a step commit.
         `${DIRNAME}/detail.md`,
+        // The ending the CLI printed last, for the Stop check: per-worktree
+        // control, rewritten by every ending, and never a step commit's to carry.
+        `${DIRNAME}/RELAY`,
         `${DIRNAME}/builds/*/STEP`,
         `${DIRNAME}/builds/*/SEAM`,
         `${DIRNAME}/builds/*/SPIKE`,
         // The entry stamp is in-flight control like STEP/SEAM: checkpoint's
         // stageAll must never sweep it into a step commit.
         `${DIRNAME}/builds/*/TICK`,
+        // The pause stamp is in-flight control too: what handoff last showed, so
+        // a repeat prints the reminder. It must never ride a step commit.
+        `${DIRNAME}/builds/*/PAUSE`,
         // The agent-run handoff ledger is step-scoped in-flight state, not a
         // tracked artifact: it must never ride a step commit into the PR.
         `${DIRNAME}/builds/*/handoff.json`,

package/dist/verbs/abandon.js

@@ -1,11 +1,11 @@
 // `plumbbob abandon`: the third exit from an in-flight step. Checkpoint lands
 // the step and revert destroys the work; abandon drops the attempt but keeps the
 // working-tree diff exactly where it is. Its only writes are the in-flight
-// control markers it clears (STEP, SEAM, TICK, and the step-scoped handoff
-// ledger), a build-log line, and the stats receipt: it touches neither the
-// working tree nor git nor the intent checkbox, so the step stays planned and
-// re-buildable with its diff still in the tree for the human to keep, rework, or
-// commit by hand.
+// control markers it clears (STEP, SEAM, TICK, the PAUSE stamp, and the
+// step-scoped handoff ledger), a build-log line, and the stats receipt: it
+// touches neither the working tree nor git nor the intent checkbox, so the step
+// stays planned and re-buildable with its diff still in the tree for the human
+// to keep, rework, or commit by hand.
 //
 // A step exit is a boundary crossing, so abandon honors the same approval latch
 // as checkpoint. That is not decoration: abandon clears the entry stamp the
@@ -15,11 +15,11 @@
 // control-state clears; abandon itself never calls the raw fs deleters.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { bumpStepStat, buildLogPath, clearHandoff, clearSeam, clearStep, clearTick, hasSession, intentPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
+import { bumpStepStat, buildLogPath, clearHandoff, clearPause, clearSeam, clearStep, clearTick, hasSession, intentPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { checkLatch } from "../lib/latch.js";
 import { abandonLogLine, appendToSection } from "../lib/buildlog.js";
 import { parseSteps } from "../lib/orient.js";
-import { ending, notice, transition } from "../lib/notice.js";
+import { ending, notice, printEnding, transition } from "../lib/notice.js";
 import { driverPointer } from "./handoff.js";
 /**
  * Drop the in-flight step while keeping its work: latch, clear the markers,
@@ -55,18 +55,23 @@ export function abandon(cwd, args) {
     clearSeam(root, slug);
     clearTick(root, slug);
     clearHandoff(root, slug);
+    clearPause(root, slug);
     bumpStepStat(root, slug, step, 'abandons');
     logAbandon(root, slug, step);
     // A step exit: with the step back at `[ ]` and its markers gone, the pointer
     // aims forward from the boundary, at the very step just dropped.
-    process.stdout.write(ending({
-        lead: transition({
-            label: 'Abandoned',
-            fact: `Step ${step}`,
-            detail: ['work kept in the tree', 'the step stays planned'],
+    printEnding(root, {
+        tier: 'driver',
+        render: 'abandon',
+        text: ending({
+            lead: transition({
+                label: 'Abandoned',
+                fact: `Step ${step}`,
+                detail: ['work kept in the tree', 'the step stays planned'],
+            }),
+            pointer: driverPointer(root, slug),
         }),
-        pointer: driverPointer(root, slug),
-    }));
+    });
     return 0;
 }
 /**

package/dist/verbs/checkpoint.js

@@ -12,7 +12,7 @@
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearTick, detailPath, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearPause, clearTick, detailPath, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { readCommitBody } from "../lib/commitbody.js";
 import { checkLatch } from "../lib/latch.js";
@@ -21,7 +21,7 @@ import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine, logEntry, planLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
-import { advisory, ending, notice, transition } from "../lib/notice.js";
+import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
 import { boundaryEnding, planRecord, stepRecord } from "./handoff.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
@@ -116,17 +116,22 @@ export async function checkpoint(cwd, args) {
     rmSync(stepPath(root), { force: true });
     clearHandoff(root); // the agent-run handoff ledger is step-scoped; clear it with the markers.
     clearTick(root); // the step's entry stamp is spent; the next `build <n>` re-stamps.
+    clearPause(root); // the pause it stamped is over; the next step's pause renders whole.
     // The whole ending, one block: the lead line, the Verdict folded over what
     // just landed, the advisories this checkpoint alone can state, and the
     // pointer. Read after the flip and the ledger append, so the fold and the
     // pointer both see the boundary the human is standing at.
     const landed = boundaryEnding(root, activeBuild(root), step);
-    process.stdout.write(ending({
-        lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
-        verdict: landed.verdict,
-        advisories: [drift, flipNotice],
-        pointer: landed.pointer,
-    }));
+    printEnding(root, {
+        tier: 'orientation',
+        render: 'checkpoint',
+        text: ending({
+            lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
+            verdict: landed.verdict,
+            advisories: [drift, flipNotice],
+            pointer: landed.pointer,
+        }),
+    });
     return 0;
 }
 /**
@@ -172,19 +177,23 @@ function checkpointPlan(root, args) {
     clearTick(root);
     // No Verdict: the plan commit measures nothing. The pointer aims at the step
     // the build starts on, which is what `handoff` renders from a null step.
-    process.stdout.write(ending({
-        lead: transition({ label: 'Plan', fact: 'committed', detail: leadDetail(sha, pointer) }),
-        advisories: staged
-            ? []
-            : [
-                advisory({
-                    fact: 'the plan rides the commit message',
-                    detail: ['record-only', '.plumbbob/ is gitignored, so the files stay untracked'],
-                    remedy: 'unignore .plumbbob/builds/ to keep the record in the tree',
-                }),
-            ],
-        pointer: boundaryEnding(root, activeBuild(root), null).pointer,
-    }));
+    printEnding(root, {
+        tier: 'orientation',
+        render: 'plan-commit',
+        text: ending({
+            lead: transition({ label: 'Plan', fact: 'committed', detail: leadDetail(sha, pointer) }),
+            advisories: staged
+                ? []
+                : [
+                    advisory({
+                        fact: 'the plan rides the commit message',
+                        detail: ['record-only', '.plumbbob/ is gitignored, so the files stay untracked'],
+                        remedy: 'unignore .plumbbob/builds/ to keep the record in the tree',
+                    }),
+                ],
+            pointer: boundaryEnding(root, activeBuild(root), null).pointer,
+        }),
+    });
     return 0;
 }
 /**

package/dist/verbs/doctor.js

@@ -2,9 +2,9 @@
 //
 // 1. The global plugin link (read-only). After `plumbbob init`, plumbbob lives as a
 //    symlink at ~/.claude/skills/plumbbob pointing at the installed package; Claude
-//    Code loads it in place as a plugin (skills `/plumbbob:*`, the post-edit hook from
+//    Code loads it in place as a plugin (skills `/plumbbob:*`, the hooks from
 //    hooks.json). doctor verifies the link resolves to a package carrying the manifest,
-//    the skills, and the hook, and names the fix for anything missing. The failure
+//    the skills, and the hooks, and names the fix for anything missing. The failure
 //    class it exists for is SILENT (a `/plumbbob:status` that opens an empty dashboard
 //    because the plugin never linked).
 //
@@ -80,7 +80,7 @@ function linkedPackage(link) {
     }
 }
 /**
- * The link-install checks: manifest, skill set, and post-edit hook, each with its fix.
+ * The link-install checks: manifest, skill set, and hooks, each with its fix.
  *
  * `shipped` is the canonical skill list read from the package itself; an installed
  * count below it means a stale or partial link, and every fix is the same re-link.
@@ -96,10 +96,29 @@ function buildChecks(link, pkg, shipped) {
             ? { ok: true, label: `skills present (${installed.length}) — load as /plumbbob:*` }
             : { ok: false, label: `skills incomplete (${installed.length}/${shipped.length})`, fix: 're-link: plumbbob init' },
         existsSync(join(pkg, 'hooks', 'hooks.json'))
-            ? { ok: true, label: 'post-edit hook present (hooks/hooks.json, auto-registers)' }
+            ? { ok: true, label: hooksLabel(wiredEvents(join(pkg, 'hooks', 'hooks.json'))) }
             : { ok: false, label: 'hook missing (hooks/hooks.json)', fix: 're-link: plumbbob init' },
     ];
 }
+/**
+ * The hooks line's label: every event the package wires, so a link that
+ * predates a hook reads as one at a glance. A file whose events cannot be read
+ * still counts as present, the way the line read before it named any.
+ */
+function hooksLabel(events) {
+    const named = events.length === 0 ? '' : `: ${events.join(', ')}`;
+    return `hooks present (hooks/hooks.json${named}; auto-registers)`;
+}
+/** The events a hooks.json wires, in file order, or none when it does not parse. */
+function wiredEvents(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed.hooks === 'object' && parsed.hooks !== null ? Object.keys(parsed.hooks) : [];
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * The plugin-link diagnostic: how plumbbob is installed into Claude Code, as checks.
  *