plumbbob 0.11.0 → 0.11.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "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/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/orient.js

@@ -311,7 +311,7 @@ function classifyRecapRow(name, value) {
                 test(/^bent\b/, 'failing') ??
                 test(/^drift\b/, 'drift'));
         case 'seam':
-            return test(/^held\b/, 'true') ?? test(/^strayed\b/, 'failing') ?? test(/^drift\b/, 'drift');
+            return test(/^held\b/, 'true') ?? test(/^strayed\b/, 'advisory') ?? test(/^drift\b/, 'drift');
     }
 }
 /**
@@ -381,6 +381,13 @@ const NOT_STANDING = { glyph: '✗', state: 'Not standing' };
  * drift beats a live failure beats an advisory beats plumb, and each rung
  * names the one component that earned it. The advisory rung runs in a fixed
  * order, the seam stray first.
+ *
+ * A strayed seam is an advisory, never a failure: a path outside the seam
+ * says either that the work wandered or that the line was drawn too tight,
+ * and truing the diff fixes neither. At the pause the measured seam row
+ * carries the stray; at the boundary the tree is clean, the row has vanished,
+ * and the stat the checkpoint bumped carries it instead. Both name it
+ * `seam strayed`, so the rung does not change between the two.
  */
 export function foldVerdict(rows, stats) {
     for (const name of RECAP_ROW_NAMES) {
@@ -394,11 +401,17 @@ export function foldVerdict(rows, stats) {
             return { ladder: OUT_OF_PLUMB, worst: `${name} ${row.word}` };
         }
     }
+    for (const name of RECAP_ROW_NAMES) {
+        const row = rows[name];
+        if (row !== undefined && row.verdict === 'advisory') {
+            return { ladder: A_HAIR_OFF, worst: `${name} ${row.word}` };
+        }
+    }
     if (stats.driftWarnings > 0) {
         // First of the advisory rung, and uncounted: the stat bumps once per
         // checkpoint rather than once per stray path, and this is the one advisory
         // that asks a question of the plan rather than of the work.
-        return { ladder: A_HAIR_OFF, worst: 'staged outside the seam' };
+        return { ladder: A_HAIR_OFF, worst: 'seam strayed' };
     }
     if (stats.redChecks > 0) {
         return { ladder: A_HAIR_OFF, worst: `${stats.redChecks} red run${stats.redChecks === 1 ? '' : 's'} before green` };
@@ -469,10 +482,12 @@ export function summaryCheckRow(summary) {
  * (the row then vanishes, or the model's attested row stands).
  *
  * Green sizes the declared seam: how many of its tokens the diff actually
- * touched, and that nothing landed outside them. Red states the size of the
- * problem and lets the paths themselves be the evidence: one stray is the `→`
- * pointer, and several break onto `- ` lines. `paths` are work-plane changes,
- * artifacts already filtered by the caller.
+ * touched, and that nothing landed outside them. A stray states the size of
+ * the problem and lets the paths themselves be the evidence: one stray is the
+ * `→` pointer, and several break onto `- ` lines. It is an advisory, not a
+ * failure (the seam is awareness, not a lock), so the fold puts it on the
+ * third rung, never the second. `paths` are work-plane changes, artifacts
+ * already filtered by the caller.
  */
 export function seamRowFromDiff(paths, seam) {
     if (seam.length === 0 || paths.length === 0) {
@@ -486,8 +501,8 @@ export function seamRowFromDiff(paths, seam) {
     const evidence = `strayed: ${outside.length} path${outside.length === 1 ? '' : 's'} outside the seam`;
     const only = outside[0];
     return outside.length === 1 && only !== undefined
-        ? { verdict: 'failing', word: 'strayed', evidence, pointer: only }
-        : { verdict: 'failing', word: 'strayed', evidence, items: outside };
+        ? { verdict: 'advisory', word: 'strayed', evidence, pointer: only }
+        : { verdict: 'advisory', word: 'strayed', evidence, items: outside };
 }
 /**
  * Sum numstat entries into the diff row's three counts.
@@ -687,6 +702,36 @@ export function parseSummary(detail) {
     }
     return { lead, highlights };
 }
+/**
+ * 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
+ * the section's prose as written, trimmed; empty when the model wrote only the
+ * title. The build-log's Log carries these beneath the step's record, so an
+ * older step's "expand" reads the ledger rather than a commit.
+ */
+export function parseSections(detail) {
+    const lines = detail.split('\n');
+    const sections = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = /^##\s+(\d+)\s+(\S.*?)\s*$/.exec(lines[i] ?? '');
+        if (m === null) {
+            continue;
+        }
+        let end = lines.findIndex((l, j) => j > i && l.startsWith('## '));
+        if (end === -1) {
+            end = lines.length;
+        }
+        sections.push({
+            n: Number(m[1]),
+            title: m[2] ?? '',
+            body: lines
+                .slice(i + 1, end)
+                .join('\n')
+                .trim(),
+        });
+    }
+    return sections;
+}
 /**
  * The `## Recommendation` section of `.plumbbob/detail.md`: the one or two
  * plain sentences a decision turn ends on, or null when the model wrote none.

package/dist/lib/sidecar.js

@@ -322,10 +322,10 @@ export function clearHandoff(root, slug) {
 // --- The detail plane: `.plumbbob/detail.md`, one flat per-session file holding
 // the in-flight step's full detail. The model overwrites it before every pause
 // (the recap first, then numbered sections matching the highlights); checkpoint
-// folds it into the commit body and then clears it, so the durable archive is
-// the commit and no stale detail piles up. Flat like STATE/TURN, not per-build:
-// a session drives one build at a time, and a past step's expansion reads the
-// commit, never this file. ---
+// records it beneath the step's dated line in the build-log's Log and then
+// clears it, so the durable archive is the tracked ledger and no stale detail
+// piles up. Flat like STATE/TURN, not per-build: a session drives one build at
+// a time, and a past step's expansion reads the ledger, never this file. ---
 /**
  * detail.md: the in-flight step's full detail, at the flat sidecar root.
  */
@@ -333,8 +333,8 @@ export function detailPath(root) {
     return join(root, DIRNAME, 'detail.md');
 }
 /**
- * Clear detail.md once checkpoint has folded it into the commit body; absent is
- * a no-op.
+ * Clear detail.md once checkpoint has recorded it in the Log; absent is a
+ * no-op.
  *
  * The rmSync lives here with the sidecar's other deletions, the same home
  * clearHandoff and clearTick keep.

package/dist/verbs/checkpoint.js

@@ -10,6 +10,7 @@
 // `[x]`, and clears the STEP/SEAM markers: returning the dashboard to the
 // DESIGN boundary.
 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 { runCheck } from "../lib/check.js";
@@ -18,10 +19,10 @@ import { checkLatch } from "../lib/latch.js";
 import { markStepDone, parseSteps } from "../lib/orient.js";
 import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
-import { appendToSection, checkpointLogLine } from "../lib/buildlog.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 { boundaryEnding } from "./handoff.js";
+import { boundaryEnding, planRecord, stepRecord } from "./handoff.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
  *
@@ -80,6 +81,13 @@ export async function checkpoint(cwd, args) {
             : notice({ fact: 'checkpoint refused', detail: ['the check is red'], remedy: 'fix it, then run it again' }));
         return 1;
     }
+    // The step's record, as the pause showed it: measured now, before the work
+    // is staged, since the seam and diff rows read the working tree the way the
+    // pause did. It lands in the build-log's Log beneath the dated line (the
+    // tracked ledger is the archive, and it rides the branch where a commit body
+    // would not survive the squash); the commit body keeps its marker and the
+    // lead prose only.
+    const record = stepRecord(root, activeBuild(root), step, readDetail(root) ?? '');
     let sha;
     // The drift advisory is read off the index (staged, before the commit clears
     // it) but printed inside the ending below, where the fixed order puts it: the
@@ -88,18 +96,17 @@ export async function checkpoint(cwd, args) {
     if (isDirty(root)) {
         stageAll(root);
         drift = scopeDriftNotice(root, step);
-        const lead = bodyResult.body ?? fallbackBody(root, step);
-        const body = withMarker(`plumbbob step ${step}`, foldDetail(lead, readDetail(root)));
+        const body = withMarker(`plumbbob step ${step}`, bodyResult.body ?? fallbackBody(root, step));
         sha = commit(root, messageArg(args) ?? subjectForStep(root, step), body);
-        clearDetail(root); // the detail is folded into the commit now; clear it so no stale detail rides into the next step.
     }
     else {
         sha = headSha(root);
     }
+    clearDetail(root); // the detail is recorded in the Log below; clear it so no stale detail rides into the next step.
     appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
     const flipNotice = flipIntent(root, step);
     stampStepStat(root, undefined, step, 'landedAt', new Date().toISOString());
-    logCheckpoint(root, step, sha);
+    const pointer = logCheckpoint(root, step, sha, record);
     // The step landed: the build-log's ☐/☑ mirror flips and its Current-step line
     // returns to the boundary, re-read from the intent.md `flipIntent` just wrote.
     // The artifact-plane whitelist keeps this build-log write from ever reading as
@@ -115,7 +122,7 @@ export async function checkpoint(cwd, args) {
     // 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: [sha.slice(0, 9)] }),
+        lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
         verdict: landed.verdict,
         advisories: [drift, flipNotice],
         pointer: landed.pointer,
@@ -156,13 +163,17 @@ function checkpointPlan(root, args) {
     const staged = stagePath(root, buildFolder(root));
     const sha = commit(root, planSubject(root), withMarker('plumbbob plan', bodyResult.body ?? undefined));
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
+    // The cold read that approved the plan is the Log's first entry, beneath a
+    // dated plan line; the detail file is then spent, the same as at a step.
+    const pointer = logPlan(root, sha, planRecord(readDetail(root) ?? ''));
+    clearDetail(root);
     // Landing the plan consumes `start`'s entry stamp: a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
     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: [sha.slice(0, 9)] }),
+        lead: transition({ label: 'Plan', fact: 'committed', detail: leadDetail(sha, pointer) }),
         advisories: staged
             ? []
             : [
@@ -214,7 +225,9 @@ function resolveStep(root, args) {
  * step's seam, or '' when it held.
  *
  * Guidance, not a gate: the checkpoint captures the drift and says so, and the
- * bumped stat puts a `staged outside the seam` rung under the Verdict. The seam
+ * bumped stat puts a `seam strayed` rung under the Verdict, the same rung the
+ * pause's measured seam row gave it, since the row vanishes once the tree is
+ * committed and the stat is what carries the stray past that point. The seam
  * (the step's edit grant: exact paths or `dir/` prefixes) comes from the
  * in-flight SEAM file when a build is live, else the step's declared seam in
  * intent.md. Plumbbob's own artifact plane is whitelisted inside `scopeDrift`,
@@ -278,25 +291,51 @@ function flipIntent(root, step) {
     }
 }
 /**
- * Append a dated line to the build-log's `## Log` section.
+ * The lead line's trailing parenthetical: the short SHA, and where the Log
+ * entry landed when one did, as the same `details:` clause Next Up carries.
+ */
+function leadDetail(sha, pointer) {
+    return pointer === null ? [sha.slice(0, 9)] : [sha.slice(0, 9), `details: \`${pointer}\``];
+}
+/**
+ * Append the step's entry to the build-log's `## Log` section: the dated line,
+ * and beneath it the record of the pause when the model wrote one.
  *
  * The build's history accrues at each checkpoint instead of being reconstructed
  * at finish; the step's title is lifted from intent.md when still present.
  * Best-effort: a missing or odd build-log never blocks a checkpoint; the
- * `checkpoints` SHA is the source of truth.
+ * `checkpoints` SHA is the source of truth. Returns where the line landed, as
+ * `path:line` from the repo root, or null when nothing was written.
+ */
+function logCheckpoint(root, step, sha, record) {
+    const date = new Date().toISOString().slice(0, 10);
+    return appendLog(root, checkpointLogLine(date, step, sha, titleForStep(root, step), statsSuffix(root, step)), record);
+}
+/**
+ * Append the plan's entry to the Log: a dated `plan committed` line, and
+ * beneath it the cold read that approved the plan when the model wrote one.
  */
-function logCheckpoint(root, step, sha) {
+function logPlan(root, sha, record) {
+    return appendLog(root, planLogLine(new Date().toISOString().slice(0, 10), sha), record);
+}
+/**
+ * Write one Log entry and say where its dated line landed (`path:line` from
+ * the repo root), or null when the section is missing or the write failed.
+ */
+function appendLog(root, line, record) {
     try {
         const path = buildLogPath(root);
-        const date = new Date().toISOString().slice(0, 10);
-        const line = checkpointLogLine(date, step, sha, titleForStep(root, step), statsSuffix(root, step));
-        const updated = appendToSection(readFileSync(path, 'utf8'), 'Log', line);
-        if (updated !== null) {
-            writeFileSync(path, updated);
+        const updated = appendToSection(readFileSync(path, 'utf8'), 'Log', logEntry(line, record));
+        if (updated === null) {
+            return null;
         }
+        writeFileSync(path, updated);
+        const at = updated.split('\n').lastIndexOf(line);
+        return at === -1 ? null : `${relative(root, path)}:${at + 1}`;
     }
     catch {
         // best-effort ledger; never fail a checkpoint over the build-log.
+        return null;
     }
 }
 /**
@@ -408,8 +447,8 @@ function fallbackBody(root, step) {
  * is absent or empty.
  *
  * The model overwrites it before every pause; checkpoint reads it once here for
- * the fold, and the caller clears it afterward. A missing or blank file folds
- * nothing.
+ * the Log's record, and the caller clears it afterward. A missing or blank file
+ * records nothing.
  */
 function readDetail(root) {
     try {
@@ -420,18 +459,6 @@ function readDetail(root) {
         return null;
     }
 }
-/**
- * Fold the detail beneath the lead prose for the commit body.
- *
- * The lead (an explicit `--body`, else the deterministic fallback) leads and the
- * detail file's content follows, joined by a blank line so git keeps them as
- * separate paragraphs. Either part may be absent; an all-empty fold returns
- * undefined so `withMarker` leaves just the marker line.
- */
-function foldDetail(lead, detail) {
-    const parts = [lead, detail].filter((part) => part !== undefined && part !== null && part.length > 0);
-    return parts.length > 0 ? parts.join('\n\n') : undefined;
-}
 /**
  * The step's done-when line from intent.md, or null when absent or unreadable.
  */

package/dist/verbs/handoff.js

@@ -35,7 +35,7 @@ import { commitsSince, diffNumstat, diffPatch, findRepoRoot } from "../lib/git.j
 import { blocks } from "../lib/notice.js";
 import { isArtifactPath, parseStepSeam } from "../lib/intent.js";
 import { checkpointsPath, detailPath, hasSession, inSpike, intentPath, readStats, readTurn, resolveBuild, seamPath, stepPath, tickPath, } from "../lib/sidecar.js";
-import { countDiff, diffRowValue, foldVerdict, lastLedgerSha, parseConstraintCount, parseLastCheckpoint, parseRecap, parseRecommendation, parseSteps, parseSummary, recapLines, seamRowFromDiff, spentRowValue, summaryCheckRow, } from "../lib/orient.js";
+import { countDiff, diffRowValue, foldVerdict, lastLedgerSha, parseConstraintCount, parseLastCheckpoint, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, recapLines, seamRowFromDiff, spentRowValue, summaryCheckRow, } from "../lib/orient.js";
 // The inline-diff threshold (docs/presentation.md): at 20 changed lines or
 // fewer the patch rides the turn; at 21 it stays in the working tree behind
 // the counted diff row.
@@ -171,6 +171,80 @@ export function boundaryEnding(root, slug, step) {
         pointer: nextUpLine(nextUp, steps.length, relative(root, intentPath(root, slug))),
     };
 }
+/**
+ * The step's record for the build-log's Log: the pause as the human approved
+ * it, with the full story behind each highlight beneath. The Summary and its
+ * highlights, the Readout fence, the Verdict, the recommendation, then the
+ * numbered sections' bodies, blank-line separated and unindented; the caller
+ * nests it under the Log's dated line.
+ *
+ * Measured, not recalled: the check, seam, and diff rows are read the same way
+ * the pause read them, so this has to be built before the work is staged (the
+ * seam and diff rows read the working tree). Null when the detail file carries
+ * nothing to record, so a hand-built step with no detail gets the bare dated
+ * line it always did.
+ */
+export function stepRecord(root, slug, step, detail) {
+    const summary = parseSummary(detail);
+    const recommendation = parseRecommendation(detail);
+    const sections = parseSections(detail);
+    if (summary === null && recommendation === null && sections.length === 0 && parseRecap(detail) === null) {
+        // Nothing on the wire's shape: a blank file records nothing, and anything
+        // else the model wrote is kept verbatim rather than lost with the file.
+        const raw = detail.trim();
+        return raw.length === 0 ? null : raw;
+    }
+    const intent = readOr(intentPath(root, slug));
+    const { rows, work, summary: check } = measured(root, slug, intent, detail, step);
+    const { ladder, worst } = foldVerdict(rows, accruedStats(root, slug, step));
+    const readout = recapLines(rows, {
+        diff: diffRowValue(countDiff(work), false),
+        spent: spentRowValue(spentInputs(root, slug, step, check)),
+        constraints: parseConstraintCount(intent),
+    });
+    const parts = [];
+    if (summary !== null) {
+        parts.push(recordSummary(summary));
+    }
+    if (readout.length > 0) {
+        parts.push([readoutLabel(step, parseSteps(intent)), '', ...fence('text', readout)].join('\n'));
+    }
+    parts.push(verdictLine(ladder, worst));
+    return [...withRecommendation(parts, recommendation), ...sectionBlocks(sections)].join('\n\n');
+}
+/**
+ * The plan's record for the Log: the cold read's recommendation and the
+ * findings behind it. Nothing is measured at the plan pause, so no Readout and
+ * no Verdict ride here. Null when the detail file carries neither.
+ */
+export function planRecord(detail) {
+    const recommendation = parseRecommendation(detail);
+    const sections = parseSections(detail);
+    if (recommendation === null && sections.length === 0) {
+        return null;
+    }
+    return [...withRecommendation([], recommendation), ...sectionBlocks(sections)].join('\n\n');
+}
+/**
+ * The record's opening block: the Summary lead without the `(details: …)`
+ * bracket, since the record is where the detail now lives, then the
+ * highlights under their own handles.
+ */
+function recordSummary(summary) {
+    const lead = `**Summary**: ${summary.lead}`;
+    if (summary.highlights.length === 0) {
+        return lead;
+    }
+    return [lead, '', ...summary.highlights.map((h) => `${h.n}. ${h.title}`)].join('\n');
+}
+/**
+ * The full story behind each highlight, one block per section: the handle in
+ * bold, the title, then the body as the model wrote it. A section with no body
+ * is just its line.
+ */
+function sectionBlocks(sections) {
+    return sections.map((s) => (s.body.length === 0 ? `**${s.n}.** ${s.title}` : `**${s.n}.** ${s.title}\n\n${s.body}`));
+}
 /**
  * The driver turn's pointer: back at the step still open, at the spike raised
  * over it, or forward from the boundary when the step has already exited.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Attention-first build process: 14 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",

package/skills/build/SKILL.md

@@ -173,8 +173,9 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
    sentence, closed by a period, then the reason as a capitalized sentence or two. The lead
    and the recommendation are flowing prose and handoff unwraps both to the renderer's
    width, so never hard-wrap them; handoff also prepends the bold `**Recommendation**:`
-   label, which you never type. `checkpoint` folds this file into the commit body and then
-   truncates it, so the detail lands in the durable commit rather than piling up on disk.
+   label, which you never type. `checkpoint` records this file beneath the step's dated
+   line in the build-log's `## Log` and then truncates it, so the detail lands in the
+   tracked ledger rather than piling up on disk.
 
    *Paste the turn.* Run `plumbbob handoff` and paste its output whole, verbatim, at top
    level, trailing blank line included, then end the turn. Never nest it inside a fence of
@@ -192,7 +193,7 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
 
    *Then read the reply as an ask or a direction.* A message that **asks** ("expand 2",
    "what does that mean?", "why did the seam row flag that?") is an expand: answer it from the detail file, from
-   `git diff`, or from `git show`, never from recall, then run `plumbbob handoff` again and
+   `git diff`, or from the build-log's `## Log` for an older step, never from recall, then run `plumbbob handoff` again and
    paste it. The step is still in flight, so it renders the same pause, and the Your Call
    block stays the CLI's to render rather than yours to retype. A message that **directs**
    is needs-work: take it as what to change, and nothing lands until the human says

package/skills/plan/SKILL.md

@@ -145,13 +145,16 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
    heredoc) when the rationale is worth carrying; skip it for a small plan. Do this
    only on the human's approval; the plan is their convergence.
    - **The plan pause is a decision turn.** Present the framed plan for the human's call,
-     then relay `plumbbob handoff --plan`'s plan-pause card: the CLI renders the your-call
-     block with the two moves that apply before anything is recorded (the decision tier of
-     the [turn anatomy](https://github.com/robmclarty/plumbbob/blob/main/docs/presentation.md)),
+     then give it the cold read (**§ The cold read**), write the result into
+     `.plumbbob/detail.md`, and relay `plumbbob handoff --plan`'s block whole: the CLI
+     renders the your-call block with the moves that apply before anything is recorded and
+     prints your recommendation last (the decision tier of the
+     [turn anatomy](https://github.com/robmclarty/plumbbob/blob/main/docs/presentation.md)),
      so the moves are relayed, never hand-composed. *looks good* marks the plan decided and
-     starts `/plumbbob:build` at the first undone step; *needs work* sends you back to sharpen
-     it, which is cheap now, before any code. The revert move vanishes there on its own:
-     nothing has landed to wind back.
+     starts `/plumbbob:build` at the first undone step; a message that asks (`expand 2`, or
+     any question) is answered from the detail file or `intent.md` and changes nothing; a
+     message that directs is what to sharpen, cheap now, before any code. The revert move
+     vanishes there on its own: nothing has landed to wind back.
    - **The plan commit is latched too.** Once the turn ledger exists, `checkpoint
      --plan` refuses to land in the same turn `start` stamped it: present the plan,
      **end the turn**, and the human's approving message is the tick that lets it
@@ -179,6 +182,48 @@ an agent can follow with `/plumbbob:build`. The argument only seeds how you get
 7. **Offer to stress-test it.** Suggest `/plumbbob:refine` to attack the frame for holes (or
    to repair the plan as it drifts). Optional, the human's call.
 
+## The cold read
+
+The plan pause ends on your recommendation, and the recommendation is an estimate made
+with fresh eyes, not a re-reading of your own plan. Before you relay the card, give the
+framed plan one bounded adversarial pass under a fixed lens, the pass `/plumbbob:refine`'s
+attack mode makes, but without its writing: surface, never append. Edit nothing, add no
+Open questions, and keep it to one screen of reading. The lens:
+
+- an ambiguity a builder would have to guess through;
+- an edge case or a hidden assumption no Decision settles;
+- a collision with the existing code (read the files the seams name);
+- a done-when no test or check can measure, or a seam that names a file that does not
+  exist or misses one that must change;
+- a step too large to review in one pass, or a Decision with no *because*.
+
+Write what you found into `.plumbbob/detail.md`, overwriting whatever a past session
+left, the findings first and the recommendation last:
+
+```markdown
+# Detail · Plan · <the title>
+
+## 1 <the first hole: one sentence, naming where it sits in intent.md>
+<what it is, and what closing it would take>
+
+## 2 ...
+
+## Recommendation
+
+<The move.> <The reason, one or two sentences.>
+```
+
+The recommendation takes one of two shapes. A sound plan gets `Approve it.` and what the
+read checked and found sound. A plan with a hole gets `Sharpen <the one worst hole> first.`
+and why it matters; when the read found more than one, say how many sit behind `expand`
+and name `/plumbbob:refine` as the move that writes them up as Open questions, with their
+plain and lean sub-lines, for the human to settle. Three findings at most; the rest is
+refine's. `plumbbob handoff --plan` prints the label and your recommendation as the turn's
+last text, "expand 2" opens `## 2`, and `checkpoint --plan` records the read beneath the
+plan's line in the build-log's `## Log`, the build's first entry. The cold read is the tip of refine: it makes the
+full attack discoverable at the moment it would pay, and lets a sound plan skip it. Refine
+is where the real adversary looks; this is an estimate, and it says so by staying short.
+
 ## The interview (mode 1)
 
 Make it easy and non-intrusive:

package/skills/verify/SKILL.md

@@ -109,8 +109,8 @@ this skill verifies it the same way: **it reads the diff, not the author**
    width, so never hard-wrap them; handoff also prepends the bold `**Recommendation**:`
    label, which you never type. This is the **one** file `/plumbbob:verify` writes, and it
    is turn presentation, never the diff under review; the author-blind contract below still
-   holds. `checkpoint` folds this file into the commit body and then truncates it (the
-   detail plane in the
+   holds. `checkpoint` records this file beneath the step's dated line in the build-log's
+   `## Log` and then truncates it (the detail plane in the
    [turn anatomy](https://github.com/robmclarty/plumbbob/blob/main/docs/presentation.md)).
 
    *Paste the turn.* Run `plumbbob handoff` and paste its output whole, verbatim, at top
@@ -130,7 +130,7 @@ this skill verifies it the same way: **it reads the diff, not the author**
 
    *Then read the reply as an ask or a direction.* A message that **asks** ("expand 2",
    "what does that mean?", "why did the seam row flag that?") is an expand: answer it from the detail file, from
-   `git diff`, or from `git show`, never from recall, then run `plumbbob handoff` again and
+   `git diff`, or from the build-log's `## Log` for an older step, never from recall, then run `plumbbob handoff` again and
    paste it. The step is still in flight, so it renders the same pause, and the Your Call
    block stays the CLI's to render rather than yours to retype. A message that **directs**
    is needs-work: take it as what to change, and nothing lands until the human says

package/templates/build-log.md

@@ -51,9 +51,10 @@ Harvest results this boundary:
 
 ## Log
 
-*(The build's history, oldest first. `plumbbob checkpoint` appends a dated line here
-every time a step lands (via `/plumbbob:build` or `/plumbbob:verify`), so this
-fills in as you go, not at the end. Add your own decision/event lines too: this is what
+*(The build's history, oldest first. `plumbbob checkpoint` appends an entry here
+every time a step lands (via `/plumbbob:build` or `/plumbbob:verify`): the dated line,
+and beneath it the pause as you approved it, so this fills in as you go, not at the
+end, and an older step's detail is a scroll away. Add your own decision/event lines too: this is what
 you point at to say "I did that: the LLM helped, but those were my calls."
 `/plumbbob:finish` reads this for the report; `plumbbob finish` commits it with the build
 folder, so it rides the branch into the PR.)*