plumbbob 0.9.5 → 0.10.0

package/.claude-plugin/plugin.json

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

@@ -10,20 +10,20 @@
   <a href="https://robmclarty.github.io/plumbbob/api.html">API reference</a>
 </p>
 
-PlumbBob is a Claude Code plugin — thirteen skills and a small CLI — that runs
+PlumbBob is a Claude Code plugin (thirteen skills and a small CLI) that runs
 LLM-assisted coding as a loop you control. You and the model settle the plan in a file
 *before* any code; then the model builds one small step at a time and **stops after
 each one**, waiting for you to read the diff and approve it before anything is
-committed. It's built for the small-to-medium work that fills most days — a feature, a
-bug, a refactor — where a fully autonomous build is overkill but freestyle prompting
+committed. It's built for the small-to-medium work that fills most days (a feature, a
+bug, a refactor) where a fully autonomous build is overkill but freestyle prompting
 leaves you dragged behind the model, reacting instead of deciding.
 
 > Establish *plumb* before you build. The LLM is a hand, not a head.
 
 Its one law is **vibe to execute, never vibe to decide**: the human owns every
 decision, the LLM owns the labor, and the boundary between them is a **pause you
-advance**, not a wall that refuses you. The *why* behind that — attention as the scarce
-resource — is in [`docs/attention-first-development.md`](docs/attention-first-development.md).
+advance**, not a wall that refuses you. The *why* behind that (attention as the scarce
+resource) is in [`docs/attention-first-development.md`](docs/attention-first-development.md).
 PlumbBob is the layer below [Ridgeline](https://github.com/robmclarty/ridgeline): where
 Ridgeline runs large, settled work autonomously without you, PlumbBob keeps you in the
 driver's seat for the work your judgment has to steer. This repository was built using
@@ -32,24 +32,24 @@ PlumbBob itself, running its own loop.
 ## 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
-**hold the line when the model doesn't** — and that mechanical half is what PlumbBob adds
+**hold the line when the model doesn't**, and that mechanical half is what PlumbBob adds
 under the skills. Five deterministic edges, enforced by the CLI and git rather than by the
 model's goodwill:
 
 - **A gate that refuses red.** `checkpoint` won't record a step while the check gate is
-  red, and `start` refuses a dirty tree — the [checkride](https://www.npmjs.com/package/checkride)
+  red, and `start` refuses a dirty tree: the [checkride](https://www.npmjs.com/package/checkride)
   run (types, lint, tests, dead code, docs) has to pass before a step lands.
 - **One SHA per verified step.** Every approved step is its own git commit against a
-  recorded baseline — a ledger of checkpoints, not one undifferentiated diff at the end.
+  recorded baseline: a ledger of checkpoints, not one undifferentiated diff at the end.
 - **A preservation-aware revert.** `/plumbbob:revert` resets exactly to a recorded checkpoint
   SHA while keeping your plan and notes intact, and restores *only* SHAs the loop wrote.
-- **A build record that rides the PR.** The tracked `builds/<slug>/` folder — intent, log,
-  checkpoints, report — merges into `main` with the branch instead of dying with the
+- **A build record that rides the PR.** The tracked `builds/<slug>/` folder (intent, log,
+  checkpoints, report) merges into `main` with the branch instead of dying with the
   worktree; the archive never destroys.
 - **The approval latch.** `checkpoint` refuses to land a step until the harness records a
-  human turn since that step began ([D64–D66](docs/decisions.md#d64), the approval-latch
-  family — the ledger-plane enforcement), so the model can't self-commit past you — the
-  refusal *is* the pause.
+  human turn since that step began ([D64 (approval-latch)](docs/decisions.md#d64)–[D66
+  (oob-commits-surfaced)](docs/decisions.md#d66), the ledger-plane enforcement), so the
+  model can't self-commit past you: the refusal *is* the pause.
 
 The planning surface is the on-ramp; these five are the floor under it. And the latch's
 payoff is [measured, not asserted](#why-not-just), not just claimed. **Guidance on the
@@ -64,7 +64,7 @@ work, a latch on the record.**
 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
+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).
 
@@ -76,16 +76,16 @@ expected to touch).
 /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
+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. There are two ways;
+PlumbBob installs **once, globally** (like `gh` or your dotfiles). Two ways work;
 pick one (both register a Claude Code plugin named `plumbbob`, so running both
 collides).
 
-**Marketplace plugin** — Claude Code installs the published `plumbbob` package for you
+**Marketplace plugin**: Claude Code installs the published `plumbbob` package for you
 (skills, hook, and the CLI on PATH), so you run no `npm i -g` and no `init`:
 
 ```text
@@ -93,7 +93,7 @@ collides).
 /plugin install plumbbob@robmclarty
 ```
 
-**npm global + `init`** — installs the CLI, then links the skills and hook into Claude
+**npm global + `init`**: installs the CLI, then links the skills and hook into Claude
 Code in place:
 
 ```sh
@@ -102,15 +102,15 @@ plumbbob init          # link it into Claude Code; --uninstall to undo
 ```
 
 Restart Claude Code (or `/reload-plugins`) to activate, then run `plumbbob doctor`
-(or `/plumbbob:doctor` in-session) to confirm the wiring. The full guide — namespacing,
-per-project sessions, the agent-neutral roadmap — is in
+(or `/plumbbob:doctor` in-session) to confirm the wiring. The full guide (namespacing,
+per-project sessions, the agent-neutral roadmap) is in
 [`docs/install.md`](docs/install.md).
 
 ## Your first session
 
 In Claude Code, inside any git repo with a clean tree:
 
-1. **Plan.** Fire `/plumbbob:plan` and give it whatever you have — nothing (it interviews
+1. **Plan.** Fire `/plumbbob:plan` and give it whatever you have: nothing (it interviews
    you), a rough line (`/plumbbob:plan rate-limit POST /login, 5/min/IP, return 429`), or a
    path to a spec file. Together you fill the build's `intent.md`. No code is written
    yet.
@@ -121,17 +121,17 @@ In Claude Code, inside any git repo with a clean tree:
    PAUSE — read the diff as an editor. Approve to checkpoint, or send fixes.
    ```
 
-   (The check gate is [checkride](https://www.npmjs.com/package/checkride) — one
+   (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`, e.g. `"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 —
+   `.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.
 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
+   for the next goal. The folder rides the branch into the PR: the build's record merges
    into `main` instead of dying with the worktree.
 
 A mid-build "ooh, what if…" never derails the step: `/plumbbob:park` captures it to a list
@@ -141,23 +141,23 @@ end, with the real output at every stage, is in
 
 ## The skills
 
-You drive the whole loop from your IDE with `/plumbbob:*` skills — no step numbers to
+You drive the whole loop from your IDE with `/plumbbob:*` skills: no step numbers to
 remember, no raw CLI to type. Every skill is `disable-model-invocation`, so *you* fire
 every move, and `/plumbbob:status` always names your next one. (Claude Code namespaces
 them under the plugin, so the command is `/plumbbob:plan`. The bare `/plan` reaches it
-too — but only where nothing else owns that name, and four of the thirteen share one with
+too, but only where nothing else owns that name, and four of the thirteen share one with
 a Claude Code built-in, so these docs write the full form.)
 
-**The happy path** — the three moves every session makes; many sessions need
+**The happy path**: the three moves every session makes; many sessions need
 nothing else:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
-| `/plumbbob:plan` | plan the whole goal — open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
-| `/plumbbob:build` | implement the next planned step, then verify it to the pause — `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then pauses |
-| `/plumbbob:finish` | finish up — write the report, make the final commit, clear for a fresh goal |
+| `/plumbbob:plan` | plan the whole goal: open the session and author intent's Frame, Decisions, Constraints, **and all Steps** |
+| `/plumbbob:build` | implement the next planned step, then verify it to the pause: `--auto` self-approves and chains to done; a range like `1-3` self-approves through step 3, then pauses |
+| `/plumbbob:finish` | finish up: write the report, make the final commit, clear for a fresh goal |
 
-**Plan-shaping moves** — optional, for when the plan needs work mid-flight:
+**Plan-shaping moves**: optional, for when the plan needs work mid-flight:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
@@ -165,17 +165,17 @@ nothing else:
 | `/plumbbob:refine` | attack the frame for holes, or repair a drifted plan |
 | `/plumbbob:spike` | throwaway worktree experiment for a fork the plan can't settle |
 
-**Helpers** — orient, verify, recover, diagnose:
+**Helpers**: orient, verify, recover, diagnose:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
-| `/plumbbob:status` | orient — where you are, the next step's done-when and seam, and the next move |
-| `/plumbbob:verify` | the tick, standalone — check → self-review → validate → **PAUSE** → checkpoint, for a diff `/plumbbob:build` didn't write |
-| `/plumbbob:revert` | rewind — `git reset --hard` to a recorded checkpoint |
+| `/plumbbob:status` | orient: where you are, the next step's done-when and seam, and the next move |
+| `/plumbbob:verify` | the tick, standalone: check → self-review → validate → **PAUSE** → checkpoint, for a diff `/plumbbob:build` didn't write |
+| `/plumbbob:revert` | rewind: `git reset --hard` to a recorded checkpoint |
 | `/plumbbob:recover` | reconcile the session's own state when the dashboard looks wrong |
 | `/plumbbob:doctor` | check the install from inside a session |
 
-**Capture** — the park/harvest loop for mid-build ideas:
+**Capture**: the park/harvest loop for mid-build ideas:
 
 | Skill <img alt="" width="110" height="1"> | Does |
 |------------------------------------|------|
@@ -187,27 +187,27 @@ All thirteen, with inputs and effects, are in
 
 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
+flow), 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).
 
-**`/plumbbob:build` is the default engine, not the only one.** It's one executor — the
-loop doesn't care who writes the code. Implement a step by hand — or vibe it in
-another session, or in another harness entirely — and run `/plumbbob:verify` instead:
+**`/plumbbob:build` is the default engine, not the only one.** It's one executor: the
+loop doesn't care who writes the code. Implement a step by hand (or vibe it in
+another session, or in another harness entirely) and run `/plumbbob:verify` instead:
 same checks, same pause, same checkpoint. It reads the *diff, not the author*.
 
 **Bring your own agents.** Because the executor is author-blind, you can plug your
 own in. A **user-authored agent** is any executable that speaks one small JSON
 envelope; drop it under `.plumbbob/agents/`, bind it to a step's `before`, `build`,
 or `after` slot in the build's `harness.json`, and PlumbBob runs it through the same
-pause — with **no way for it to advance the loop** (checkride still gates, you're
+pause, with **no way for it to advance the loop** (checkride still gates, you're
 still the clock). The full contract for authors, with a copy-paste example, is in
 [`docs/agents.md`](docs/agents.md).
 
 ## Why "PlumbBob"
 
-The name is the method. A plumb bob is a weight on a string — gravity pulls it into a
+The name is the method. A plumb bob is a weight on a string; gravity pulls it into a
 perfectly straight vertical line, the builder's oldest reference for *true*: the fixed
 mark you hold the work against so it never drifts out of square. PlumbBob hangs your
 **intent** as that line and keeps every step aligned to it, so the build stays plumb
@@ -217,90 +217,91 @@ with what you decided instead of wandering off behind the model.
 
 The questions a skeptic should ask, answered straight.
 
-**…use plan mode?** Plan mode is the same instinct — decide before executing —
+**…use plan mode?** Plan mode is the same instinct (decide before executing),
 scoped to one session. The plan lives in the chat, so it fades with the context
 window, and the approval gates the *start* of the work, not each increment of it.
 PlumbBob puts the plan in a file in your repo that survives compaction, restarts,
-and next week; moves the approval to **every step** — each checked, reviewed
-against the plan, and committed as its own checkpoint, so a wrong turn costs one
+and next week; moves the approval to **every step** (each checked, reviewed
+against the plan, and committed as its own checkpoint), so a wrong turn costs one
 step, not the afternoon; and records the *whys* alongside the decisions, so the
 archive can still answer "what did we decide, and why" long after the session is
-gone. The two compose fine: plan mode — or anything else — can produce a step's
+gone. The two compose fine: plan mode (or anything else) can produce a step's
 diff, and `/plumbbob:verify` reads it like any other.
 
 **…use git and a TODO file?** That's the honest skeleton, and if your discipline
 holds by willpower alone, it may be all you need. What the CLI adds is the
-[mechanical half of the discipline](#what-a-prompt-cant-replicate) — the five edges up
-top — so willpower is spent only at the pause. The one not on that list: a status
+[mechanical half of the discipline](#what-a-prompt-cant-replicate) (the five edges up
+top), so willpower is spent only at the pause. The one not on that list: a status
 dashboard re-injected into every skill, so the model re-orients on each move without you
 re-explaining the state.
 
-**…wait for a vendor to ship this natively?** They're converging on it — plan
-modes, spec kits, native checkpoints — and that convergence is evidence *for* the
+**…wait for a vendor to ship this natively?** They're converging on it (plan
+modes, spec kits, native checkpoints), and that convergence is evidence *for* the
 premise. PlumbBob is deliberately thin against that future: the artifacts are
 plain markdown and ordinary git commits in your own repo, the CLI is lean
 (node builtins plus one deliberate dependency), and nothing locks you in. The
-investment is small — thirteen
-skills over a plain-markdown sidecar, learnable in an afternoon — and what you're
+investment is small (thirteen
+skills over a plain-markdown sidecar, learnable in an afternoon), and what you're
 actually learning is the method: decisions before code, one verified step at a
 time, capture instead of chase. That transfers to whatever tool wins. If
 something better ships, you walk away with your archives and your habits intact.
 
-**…admit the pause is unenforceable?** On the **work** plane, yes — on purpose
+**…admit the pause is unenforceable?** On the **work** plane, yes, on purpose
 ([D10 (pause-not-lock)](docs/decisions.md#d10)/[D13 (no-edit-guards)](docs/decisions.md#d13) in
 [`docs/decisions.md`](docs/decisions.md)): a hard lock on every edit buys ritual, not
 control, because a determined model routes around it and a denial mid-thought leaves no
 legal move. But the **record** is a different plane, and there the tick *is* latched
-([D64–D66](docs/decisions.md#d64), the approval-latch family): `checkpoint` refuses to land a step until the harness
-records a human turn since that step began, so the agent cannot self-commit past you —
+([D64 (approval-latch)](docs/decisions.md#d64)–[D66 (oob-commits-surfaced)](docs/decisions.md#d66)): `checkpoint` refuses to land a step until the harness
+records a human turn since that step began, so the agent cannot self-commit past you:
 the refusal simply *is* the pause. It extends the [deterministic edges above](#what-a-prompt-cant-replicate)
 to the one boundary the product is named after, while leaving human what must be human:
 you, reading the diff. And when a raw commit does slip the ledger, `status` says so and the
-checkpoint record makes recovery one command — cheap recovery, not a cage, is the control
+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
+> ([`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
+> ([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
+> ([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)) —
+> 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
+> 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.
 
 ## 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.
-- *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 thirteen skills: inputs, effects, when to reach for each.
-- *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.
-- *What does the CLI underneath do?* → [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, exit code, and the `.plumbbob/` sidecar.
-- *What are these untracked files, and why is it touching my `.git`?* → [`docs/state-and-git.md`](docs/state-and-git.md) — the state files, the `info/exclude` mechanism, and the objections answered.
-- *Something's broken.* → [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.
-- *Why is it built this way?* → [`docs/decisions.md`](docs/decisions.md) — the `D#` / `C#` design-decision key the source cites.
-- *How does it hang together inside?* → [`docs/architecture.md`](docs/architecture.md) — the layers and planes, for contributors (in progress).
-- *Why does this exist at all?* → [`docs/attention-first-development.md`](docs/attention-first-development.md) — the philosophy: attention as the scarce resource.
-- *What does it run on my machine?* → [`SECURITY.md`](SECURITY.md) — execution surface and how to report a vulnerability.
-- *How do I contribute?* → [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, conventions, and how to submit changes.
+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.
+- *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 thirteen skills: inputs, effects, when to reach for each.
+- *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.
+- *What does the CLI underneath do?* → [`docs/cli-reference.md`](docs/cli-reference.md): every verb, flag, exit code, and the `.plumbbob/` sidecar.
+- *What are these untracked files, and why is it touching my `.git`?* → [`docs/state-and-git.md`](docs/state-and-git.md): the state files, the `info/exclude` mechanism, and the objections answered.
+- *Something's broken.* → [`docs/troubleshooting.md`](docs/troubleshooting.md): fixes for the common snags.
+- *Why is it built this way?* → [`docs/decisions.md`](docs/decisions.md): the `D#` / `C#` design-decision key the source cites.
+- *How does it hang together inside?* → [`docs/architecture.md`](docs/architecture.md): the layers and planes, for contributors (in progress).
+- *Why does this exist at all?* → [`docs/attention-first-development.md`](docs/attention-first-development.md): the philosophy: attention as the scarce resource.
+- *Why does AI-written prose get worse over time?* → [`docs/generation-loss.md`](docs/generation-loss.md): the copy-of-a-copy problem, and why anchor texts are written by hand.
+- *What does it run on my machine?* → [`SECURITY.md`](SECURITY.md): execution surface and how to report a vulnerability.
+- *How do I contribute?* → [`CONTRIBUTING.md`](CONTRIBUTING.md): setup, conventions, and how to submit changes.
 
 ## License
 

package/dist/cli-core.js

@@ -1,12 +1,12 @@
-// plumbbob CLI core — argv dispatch and the help table, separated from the bin
+// plumbbob CLI core: argv dispatch and the help table, separated from the bin
 // entry (cli.ts) so the routing/help logic is unit-testable in-process without
 // the top-level process.exit. Node builtins plus a deliberate few dependencies
 // (currently checkride alone, via check.ts). Functional/procedural: no classes,
 // no `this`, no default export.
 //
 // The deciding/executing boundary is a pause, not a lock, so there is nothing
-// to defend in the dispatcher — every verb runs the same whether a human or the
-// model triggers it. There is no human-only `mode` escape hatch and no
+// to defend in the dispatcher; every verb runs the same whether a human or the
+// model triggers it. No human-only `mode` escape hatch exists and no
 // CLAUDECODE in-session refusal; what keeps the human the decider is the pause
 // at the step boundary (the skills), not a refusal here.
 import { readFileSync } from 'node:fs';
@@ -38,7 +38,7 @@ const BUILD_FLAG = {
  *
  * One table drives three things: the top-level verb table, per-verb `--help`,
  * and the unknown-flag refusal in `run`. Keeping it as data rather than inline
- * writes is the deliberate exception to the write-at-the-call-site convention —
+ * writes is the deliberate exception to the write-at-the-call-site convention;
  * a synopsis has to be readable by the validator, not just printable.
  */
 const VERBS = [
@@ -255,7 +255,7 @@ export function verbSpec(name) {
     return VERBS.find((v) => v.name === name) ?? null;
 }
 /**
- * Every verb name, in table order — the contract tests iterate this.
+ * Every verb name, in table order: the contract tests iterate this.
  */
 export function verbNames() {
     return VERBS.map((v) => v.name);
@@ -363,8 +363,8 @@ async function dispatch(verb, cwd, rest) {
  * report and exit 1, so the bin entry only ever exits with the code returned
  * here.
  *
- * `cwd` is the repo the verbs act on. It defaults to the process's — the only
- * thing the bin entry ever wants — and is a parameter solely so a test can name
+ * `cwd` is the repo the verbs act on. It defaults to the process's (the only
+ * thing the bin entry ever wants) and is a parameter solely so a test can name
  * a fixture. Screening argv does not help when the argv is *valid*: `checkpoint
  * -m --help` reads `--help` as the subject, exactly as it should, and then
  * commits. Whose repo it commits is decided here, and a default is not a choice
@@ -374,7 +374,7 @@ export async function run(argv, cwd = process.cwd()) {
     const verb = argv[0] ?? 'help';
     const rest = argv.slice(1);
     if (verb === 'help' || verb === '--help' || verb === '-h') {
-        // `plumbbob help <verb>` is the same page as `plumbbob <verb> --help` —
+        // `plumbbob help <verb>` is the same page as `plumbbob <verb> --help`;
         // both spellings get typed, so both work.
         const topic = rest.find((a) => !a.startsWith('-'));
         if (topic === undefined) {

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// plumbbob CLI entry — the published bin. All routing and the help table live in
+// plumbbob CLI entry: the published bin. All routing and the help table live in
 // cli-core.ts (unit-tested in-process); this file is only the executable shell:
 // it wires argv to the dispatcher and turns the returned code into the exit code.
 // Keeping the single process.exit here is what lets cli-core.ts be imported by a

package/dist/lib/agents.js

@@ -1,11 +1,11 @@
 // The agent contract. A user-authored agent is anything executable that speaks a
-// versioned JSON envelope — a JSON manifest on disk (`agent.json`), JSON on the
-// child's stdin, JSON on its stdout, prose on its stderr — so the doorway is
+// versioned JSON envelope (a JSON manifest on disk (`agent.json`), JSON on the
+// child's stdin, JSON on its stdout, prose on its stderr) so the doorway is
 // runtime-agnostic: any language, any framework, one subprocess boundary. This
 // module is the contract's validator, resolver, and runner: it type-narrows the
 // on-disk manifest and the output envelope a child returns (refusing a contract
 // major-version mismatch with an upgrade hint rather than guessing at a shape
-// that is only stable within a major — additions are a minor bump, removals or
+// that is only stable within a major: additions are a minor bump, removals or
 // renames a major), it walks the agent tiers to resolve an agent by name, it
 // composes the step context a child reads on stdin, and it spawns the child.
 // The validators are pure; the resolver reads `agent.json` files off disk with
@@ -28,7 +28,7 @@ export const CONTRACT_VERSION = 1;
  * The three lifecycle slots an agent may bind to: `before` (context in),
  * `build` (the diff), `after` (advisory review).
  *
- * Exactly these, never a fourth — "a salient point in the middle" is judgment
+ * Exactly these, never a fourth; "a salient point in the middle" is judgment
  * the host model handles in prose, not a declarative slot.
  */
 export const SLOTS = ['before', 'build', 'after'];
@@ -122,7 +122,7 @@ export function parseEnvelope(raw) {
  * True when a string names one of the three slots.
  *
  * Exported for the `agent run` verb's `--mode` refusal: a mode the manifest
- * doesn't declare is refused loud — the user who typed it asked for that slot
+ * doesn't declare is refused loud; the user who typed it asked for that slot
  * specifically.
  */
 export function isSlot(value) {
@@ -169,7 +169,7 @@ function parseSlots(value) {
 /**
  * Narrow the envelope's optional `parked[]` (absent = none).
  *
- * Present, it must be an array of non-blank strings — each becomes a park line
+ * Present, it must be an array of non-blank strings: each becomes a park line
  * the CLI lands through the park verb. A malformed list is refused rather than
  * silently dropped: losing a parked concern is a quiet data loss. Returns the
  * trimmed lines or an error string.
@@ -219,13 +219,13 @@ function envelopeFail(error) {
     return { ok: false, error };
 }
 /**
- * The project agents tier — `.plumbbob/agents/` under the repo root.
+ * The project agents tier: `.plumbbob/agents/` under the repo root.
  */
 export function projectAgentsDir(root) {
     return join(root, '.plumbbob', 'agents');
 }
 /**
- * The personal agents tier — `~/.plumbbob/agents/`, the user's own library.
+ * The personal agents tier: `~/.plumbbob/agents/`, the user's own library.
  */
 export function personalAgentsDir(home) {
     return join(home, '.plumbbob', 'agents');
@@ -246,7 +246,7 @@ function agentsHome(home) {
  * A `flagPath` (from `--agent <path>`) points straight at an agent directory
  * and takes top priority. A tier "hits" when it holds an `agent.json`: a
  * malformed one there is surfaced as an error (project still shadows
- * personal), never silently skipped in favor of a different agent — an
+ * personal), never silently skipped in favor of a different agent; an
  * explicit ask fails loud. Returns the not-found error only when no tier holds
  * a manifest at all.
  */
@@ -273,7 +273,7 @@ export function resolveAgent(root, name, opts = {}) {
 /**
  * Every resolvable agent across both tiers, sorted by name.
  *
- * Project shadows personal: a name defined in both resolves — and lists — from
+ * Project shadows personal: a name defined in both resolves (and lists) from
  * project. Each entry carries its origin and resolution; a malformed manifest
  * lands as an errored resolution rather than crashing the walk.
  */
@@ -325,7 +325,7 @@ export function formatAgentList(listings) {
  * Returns null when the directory holds no manifest (a tier miss, so
  * resolution falls through), an errored resolution when the manifest is
  * present but unreadable/malformed, else the resolved agent. A missing file
- * (ENOENT throw) is the miss signal — one read, no TOCTOU race.
+ * (ENOENT throw) is the miss signal: one read, no TOCTOU race.
  */
 function loadAgentDir(dir, origin) {
     const file = join(dir, 'agent.json');
@@ -367,10 +367,10 @@ function agentDirNames(dir) {
 /**
  * Compose the StepContext for one step.
  *
- * The strict seam parse is the only refusal path — a missing step or
+ * The strict seam parse is the only refusal path: a missing step or
  * unparseable seam gates git behavior, so it fails loud; everything else is
  * best-effort and lands whatever it can, returning `warnings` (skipped-bullet
- * lines) for the caller to print on stderr rather than writing there itself —
+ * lines) for the caller to print on stderr rather than writing there itself;
  * this module stays pure, the verb does the IO.
  */
 export function composeStepContext(params) {
@@ -410,7 +410,7 @@ function skipWarnings(heading, skipped) {
  * Validate a parsed harness.json.
  *
  * Contract first (a major mismatch gets the same upgrade hint as the manifest
- * and envelope). Structure is strict — a `steps` that is not an object, a
+ * and envelope). Structure is strict: a `steps` that is not an object, a
  * non-numeric step key, or a step entry that is not an object is the author's
  * error and is refused loud. Slot *contents* stay lenient: a slot value may be
  * one name or a list, and blanks/non-strings drop rather than refuse, because
@@ -445,9 +445,9 @@ function parseHarness(raw) {
 /**
  * Read and validate a harness.json at `path`.
  *
- * The caller builds the path from the build folder — this module stays
+ * The caller builds the path from the build folder; this module stays
  * ignorant of the sidecar layout, taking the full path. Returns null when the
- * file is absent (a build with no bound agents — a clean no-op); an errored
+ * file is absent (a build with no bound agents: a clean no-op); an errored
  * parse when present-but-broken (invalid JSON or a malformed structure the
  * author must fix); else the validated bindings. Shared so every reader
  * (`agent run`, `status`) parses the harness the same way.
@@ -474,7 +474,7 @@ export function readHarnessFile(path) {
  *
  * Accepts a harness `defaults` block, a per-step entry, or the settings-level
  * defaults. A slot value may be a single agent name or a list; blanks and
- * non-strings drop. Only the three real slots are read — `note` and any
+ * non-strings drop. Only the three real slots are read; `note` and any
  * stranger key are ignored here. A slot present but naming no valid agent
  * still counts as bound-to-nothing (an explicit override to none), so callers
  * get clean replace semantics up the ladder.
@@ -493,7 +493,7 @@ export function parseSlotBindings(raw) {
  * The agents bound to one slot for one step, merged down the bindings ladder.
  *
  * A per-step slot entry overrides the harness `defaults`, which override the
- * settings-level defaults — the first level that names the slot wins, replace
+ * settings-level defaults: the first level that names the slot wins, replace
  * not append, the same most-specific-wins shape as the settings ladder. The
  * `--agent` flag and an explicit name sit above all of this, but the verb
  * takes the single-agent path for those and never reaches here. Returns []
@@ -511,7 +511,7 @@ export function resolveSlotAgents(params) {
     return [];
 }
 /**
- * Coerce a slot value — one agent name or a list — to a trimmed name list,
+ * Coerce a slot value (one agent name or a list) to a trimmed name list,
  * dropping blanks and non-strings.
  */
 function asNameList(value) {
@@ -519,7 +519,7 @@ function asNameList(value) {
     return items.filter((v) => typeof v === 'string' && v.trim().length > 0).map((v) => v.trim());
 }
 /**
- * True when a value is a plain JSON object — not null, not an array.
+ * True when a value is a plain JSON object: not null, not an array.
  */
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -532,13 +532,13 @@ function isObject(value) {
  * directory rides in `PLUMBBOB_AGENT_DIR` so a root-cwd agent can still reach
  * its files. The composed StepContext is delivered as JSON on stdin. Stdout is
  * piped and captured (the envelope); stderr is inherited so the child's prose
- * streams live to the terminal — production (narrating) never collides with
+ * streams live to the terminal: production (narrating) never collides with
  * consumption (one structured result at the pause). A SIGINT while the child
- * runs kills it and reports `interrupted` rather than orphaning it — the human
+ * runs kills it and reports `interrupted` rather than orphaning it; the human
  * is present, Ctrl-C works. A positive `timeoutSeconds` arms a kill timer
  * (0 = off; a timeout is the user's explicit opt-in). Async `spawn`, not
  * `spawnSync`, so the parent stays live to interrupt gracefully. Never
- * rejects — every failure mode is a resolved `AgentRunResult`.
+ * rejects: every failure mode is a resolved `AgentRunResult`.
  */
 export function runAgent(params) {
     return new Promise((resolve) => {
@@ -576,7 +576,7 @@ export function runAgent(params) {
         child.stdout.on('data', (chunk) => {
             stdout += chunk.toString();
         });
-        // A shell that never launched (e.g. `sh` itself missing) — distinct from a
+        // A shell that never launched (for example `sh` itself missing): distinct from a
         // command that ran and exited non-zero, which arrives on `close`.
         child.on('error', (err) => {
             finish({ ok: false, reason: 'spawn', error: err.message });
@@ -599,9 +599,9 @@ export function runAgent(params) {
 /**
  * Parse the child's captured stdout into a validated envelope.
  *
- * JSON first (a non-JSON stdout is out of contract — the envelope must be one
+ * JSON first (a non-JSON stdout is out of contract: the envelope must be one
  * JSON object), then the envelope validator, which carries the
- * contract-mismatch hint. Kept private — `runAgent` is the only caller and the
+ * contract-mismatch hint. Kept private; `runAgent` is the only caller and the
  * verb reads the union, not this.
  */
 function parseChildEnvelope(stdout) {