plumbbob 0.9.5 → 0.10.0

package/node_modules/checkride/templates/shared/styles/Repo/Drift.yml

@@ -0,0 +1,41 @@
+# The lexical fingerprints of model-generated prose: vocabulary that runs at
+# many times its human base rate in machine-written text (`delve` is the
+# canonical case), and the stock frames readers have learned to skim past.
+# Model output feeds the next session's context, so every fingerprint that
+# lands becomes the example the next generation copies — this rule breaks that
+# loop while the copy count is still one.
+#
+# The list is deliberately short and high-precision: words a careful writer
+# almost never reaches for, so a hit is close to proof of provenance. Words
+# that are merely overused (`robust`, `crucial`, `comprehensive`) stay off it —
+# flagging those turns the rule into noise. Add your own repo's tells as they
+# emerge; cut anything you would defend in your own voice.
+#
+# Case classes instead of `ignorecase`, because the last token — the
+# `It's not just X — it's Y` frame — is anchored to its sentence-initial
+# capital, and one flag governs every token in the rule.
+extends: existence
+message: "'%s' is a fingerprint of generated prose — say the plain thing instead."
+level: error
+ignorecase: false
+# The tokens are full regexes with their own anchors, so word boundaries must
+# not be wrapped around them.
+nonword: true
+tokens:
+  - '\b[Dd]elv(?:e[sd]?|ing)\b'
+  - '\b[Cc]ommendable\b'
+  - '\b[Mm]eticulous(?:ly)?\b'
+  - '\b[Ii]ntricate(?:ly)?\b'
+  - '\b[Ii]ntricac(?:y|ies)\b'
+  - '\b[Tt]estament to\b'
+  - '\b[Tt]apestry\b'
+  - '\b[Gg]ame-chang(?:er|ers|ing)\b'
+  - '\b[Ee]ver-evolving\b'
+  - "\\b[Ii]n today['’]s\\b"
+  - '\b[Ss]eamless(?:ly)?\b'
+  - '\b[Ss]upercharg(?:e[sd]?|ing)\b'
+  - '\b[Uu]nlock(?:s|ed|ing)? the (?:full )?(?:power|potential)\b'
+  - "\\b[Ii]t(?: is|['’]s) (?:important to note|worth noting)\\b"
+  - '\b[Ii]n conclusion\b'
+  - '\b[Bb]oasts\b'
+  - "It(?:['’]s| is) not just (?:about )?[^.,;:—–]{1,60}[—–,;] ?it(?:['’]s| is)\\b"

package/node_modules/checkride/templates/shared/styles/Repo/Latin.yml

@@ -0,0 +1,14 @@
+# Latin abbreviations read as shorthand and land as a stumble: `i.e.` and `e.g.`
+# are confused for each other often enough that the plain English is simply
+# clearer. Mechanical, not a matter of voice — the substitution is always
+# available and always says the same thing.
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: error
+ignorecase: false
+# The tokens carry periods, so word boundaries cannot wrap them.
+nonword: true
+swap:
+  '\b(?:eg|e\.g\.)[\s,]': for example
+  '\b(?:ie|i\.e\.)[\s,]': that is
+  '\betc\.': and so on

package/node_modules/checkride/templates/shared/styles/Repo/LyHyphen.yml

@@ -0,0 +1,28 @@
+# An adverb ending in `-ly` cannot modify anything but the word that follows
+# it, so the hyphen adds nothing: `newly created`, not `newly-created`. This is
+# a rule about punctuation, not about how the sentence should read.
+#
+# The exceptions are words that end in `-ly` without being adverbs — `supply
+# chain`, `family friendly`, `early return`. They are the rule's whole
+# false-positive surface, and the list below is a starting point: add to it
+# rather than reaching for a suppression.
+extends: existence
+message: "'%s': an adverb ending in '-ly' takes no hyphen."
+level: error
+ignorecase: true
+# The token spans a hyphen, which word boundaries would cut in half.
+nonword: true
+tokens:
+  - '\b[^\s-]+ly-\w+\b'
+exceptions:
+  - anomaly
+  - apply
+  - assembly
+  - comply
+  - early
+  - family
+  - imply
+  - multiply
+  - only
+  - reply
+  - supply

package/node_modules/checkride/templates/shared/styles/Repo/Minted.yml

@@ -0,0 +1,33 @@
+# The minted dialect: verbs pressed into service as nouns (`the ask`), nouns
+# conscripted as verbs (`to action`), and the corporate register's syllable
+# inflations (`utilize`, three syllables where one does the work). Generated
+# prose leans into this dialect and then copies its own lean, so each swap here
+# is one the next pass never gets to imitate. Mechanical, not a matter of
+# voice — the plain word is always available and always says the same thing.
+#
+# Only unambiguous forms are listed. The noun `leverage` (mechanical advantage,
+# `open-source leverage`) is legitimate English, so only the verb forms match;
+# `the build` stays off the list entirely because in a repository it names the
+# compiled artifact far more often than it apes the dialect.
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: error
+ignorecase: false
+# The patterns carry their own case classes and boundaries.
+nonword: true
+swap:
+  '\b[Tt]he ask\b': the request
+  '\b[Ll]earnings\b': lessons
+  '\b[Aa]ctioned\b': handled
+  '\b[Aa]ctioning\b': handling
+  '\b[Ss]olutioning\b': designing
+  '\b[Tt]o leverage\b': to use
+  '\b[Ll]everages\b': uses
+  '\b[Ll]everaged\b': used
+  '\b[Ll]everaging\b': using
+  '\b[Uu]tilize\b': use
+  '\b[Uu]tilizes\b': uses
+  '\b[Uu]tilized\b': used
+  '\b[Uu]tilizing\b': using
+  '\b[Uu]tilization\b': use
+  '\b[Tt]he lift\b': the effort

package/node_modules/checkride/templates/shared/styles/Repo/ThereIs.yml

@@ -0,0 +1,16 @@
+# `There is a flag that controls X` spends its subject position on a word that
+# names nothing, then makes the reader wait for the real subject. Naming the
+# thing first is shorter every time: `A flag controls X`.
+#
+# Deliberately case-sensitive: only the sentence-initial pattern is the
+# stumble. A mid-clause existential — `when there is nothing to fix` — is
+# idiomatic English with no cleaner rewrite, and flagging it turns careful
+# prose into a wall of contortions. Sentence-initial `There` is always
+# capitalized, so the capital T is the whole test.
+extends: existence
+message: "'%s' postpones the subject — name the thing that acts, then act."
+level: error
+ignorecase: false
+tokens:
+  - 'There (is|are|was|were)'
+  - "There'?s"

package/node_modules/checkride/templates/shared/styles/Repo/Weasel.yml

@@ -0,0 +1,26 @@
+# Weasel words claim an intensity the sentence never earns: `very fast` is not
+# a measurement, and `simply call the function` is a claim about the reader.
+# Cutting one almost never costs meaning.
+#
+# This is the one rule in the set that is taste rather than mechanics, so the
+# scaffolded .vale.ini ships it OFF (`Repo.Weasel = NO`). Careful prose uses
+# some of these deliberately — `just` as "only", `clearly` as a genuine signal —
+# and a rule the author disagrees with becomes a wall of suppressions. Read the
+# list, cut what you would defend, then turn it on.
+extends: existence
+message: "'%s' is a weasel word — cut it, or say the specific thing."
+level: error
+ignorecase: true
+tokens:
+  - actually
+  - basically
+  - clearly
+  - fairly
+  - just
+  - obviously
+  - quite
+  - rather
+  - really
+  - simply
+  - somewhat
+  - very

package/node_modules/checkride/templates/shared/vale.ini

@@ -0,0 +1,34 @@
+# Vale — the `prose` slot. Written by `checkride init --add prose`; yours now.
+#
+# The styles under .vale/styles/Repo are plain YAML in this repo: no download,
+# no `vale sync` on the default path, nothing to keep in step with an upstream.
+# Disagree with a rule and the answer is to edit or delete it, not to suppress
+# it line by line — a style full of suppressions is ceremony.
+
+StylesPath = .vale/styles
+
+# Report everything; only errors decide the check. Vale exits non-zero for
+# error-severity alerts alone, so demoting a rule to `warning` keeps it visible
+# here while making it advisory — which is why this stays at `suggestion`.
+# Raise it and you stop seeing the advisory half rather than silencing it.
+MinAlertLevel = suggestion
+
+# Vale has no TypeScript format of its own. Mapping it to JavaScript lints doc
+# comments and string-free prose, and leaves the code alone.
+[formats]
+ts = js
+
+[*.{md,ts}]
+BasedOnStyles = Vale, Repo
+
+# One spell checker, one wordlist. The `spell` slot (cspell) owns spelling and
+# knows the technical vocabulary a plain en_US dictionary flags as errors.
+Vale.Spelling = NO
+
+# A vocabulary file is that second wordlist through another door — same reason.
+Vale.Terms = NO
+
+# The subjective half. Every other rule here is mechanical; this one is taste,
+# and taste belongs to whoever writes the docs. Read
+# .vale/styles/Repo/Weasel.yml and flip this to YES if you agree with it.
+Repo.Weasel = NO

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",
@@ -45,21 +45,22 @@
     "eval:report": "node test/evals/run.ts --report"
   },
   "devDependencies": {
-    "@ast-grep/cli": "0.43.0",
+    "@ast-grep/cli": "0.45.1",
     "@stryker-mutator/api": "9.6.1",
     "@stryker-mutator/core": "9.6.1",
     "@stryker-mutator/vitest-runner": "9.6.1",
-    "@types/node": "24.13.1",
-    "@vitest/coverage-v8": "4.1.9",
-    "fallow": "2.103.0",
+    "@types/node": "26.2.0",
+    "@vitest/coverage-v8": "4.1.10",
+    "@vvago/vale": "3.17.1",
+    "fallow": "3.14.0",
     "fascicle": "0.8.16",
-    "markdownlint-cli2": "0.22.1",
-    "oxlint": "1.69.0",
+    "markdownlint-cli2": "0.23.2",
+    "oxlint": "1.78.0",
     "typescript": "6.0.3",
-    "vitest": "4.1.9"
+    "vitest": "4.1.10"
   },
   "dependencies": {
-    "checkride": "0.10.2"
+    "checkride": "0.12.2"
   },
   "bundleDependencies": [
     "checkride"

package/skills/build/SKILL.md

@@ -1,116 +1,121 @@
 ---
 name: build
-description: The default engine — read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable — build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses.
+description: "The default engine: read the next planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Swappable: build by hand/vibed/another harness and run /plumbbob:verify instead. `--auto` self-approves and chains to done; a step range like `1-3` self-approves through step 3, then pauses."
 argument-hint: "[step-number | step-range] [--auto]"
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob handoff:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob park:*), Bash(plumbbob agent:*), Bash(plumbbob spike:*), Bash(git diff:*)
 ---
 
-# PlumbBob — build a step (the default engine)
+# PlumbBob: build a step (the default engine)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not on PATH in this session. Marketplace install: confirm the plugin is enabled in /plugin, then /reload-plugins. Skills-dir/global install: npm i -g plumbbob && plumbbob init."`
 
-This is the **bundled executor** — the default engine, not the only one. It is
+This is the **bundled executor**: the default engine, not the only one. It is
 **swappable**: you can implement any step by hand, in a vibe session, or with
-another harness and go straight to `/plumbbob:verify` instead — plumbbob does not care how
+another harness and go straight to `/plumbbob:verify` instead; plumbbob does not care how
 the diff appeared. When you do run it, it reads the plan, writes the step, and
 carries straight through to the verify pause.
 
 Since `/plumbbob:plan` lays down the whole step list up front, the happy path is to run
-`/plumbbob:build` once per step until done — each run builds the next undone step and stops
+`/plumbbob:build` once per step until done: each run builds the next undone step and stops
 at the pause for your approval. **Running `/plumbbob:build` again is itself the clock tick.**
 
-A model note: this skill **inherits the session model** — nothing pins or switches
+A model note: this skill **inherits the session model**; nothing pins or switches
 it. If the step you're about to build carries a `- model:` recommendation that
-differs from the model you're running as, say so before implementing — the human can
+differs from the model you're running as, say so before implementing; the human can
 switch with `/model` and rerun to honor it, or wave you on. Advisory, never a gate.
 
 ## What this skill does, in order
 
-1. **Pick the step.** Use the number you were invoked with (e.g. `/plumbbob:build 4`) — or,
+1. **Pick the step.** Use the number you were invoked with (for example `/plumbbob:build 4`), or,
    if you were given a range like `/plumbbob:build 1-3`, start at the first number and treat
    the second as the auto-approve ceiling (see the range note under `--auto`). With no
-   argument, don't resolve the next step yourself — the CLI does: bare `plumbbob build`
+   argument, don't resolve the next step yourself; the CLI does: bare `plumbbob build`
    (step 2) enters the next undone step and refuses with a `/plumbbob:step` nudge when every
    step is checkpointed.
-2. **Enter the step.** Run `plumbbob build <n>` — or bare `plumbbob build` to enter the
+2. **Enter the step.** Run `plumbbob build <n>`, or bare `plumbbob build` to enter the
    next undone step (records the in-flight STEP + SEAM so `/plumbbob:status` shows the step in
    flight; the seam is awareness, not a lock).
    - **Spike-as-step.** If the step's title opens with `spike:` / `Spike:`, the increment
-     *is* the experiment — resolving a fork the plan couldn't settle on paper. After
+     *is* the experiment: resolving a fork the plan couldn't settle on paper. After
      entering it, run `plumbbob spike report "<slug>"` (the CLI scaffolds a
      `spike-NN-<slug>.md` in the build folder, stamped `via: step <n>`), then work the
      experiment and record your **Findings** and **Verdict** there. A recorded verdict is
-     what the step's done-when should check — the report, not just the code, is the
+     what the step's done-when should check; the report, not just the code, is the
      deliverable. This is the same artifact `/plumbbob:spike` produces for a mid-build fork
-     — D70 (spike-reports).
+     ([D70 (spike-reports)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d70)).
 3. **Read the plan.** Read the step's **done-when**, its **seam**, and the
-   **Decisions** and **Constraints** in `intent.md`. Build to *that* — the deciding
+   **Decisions** and **Constraints** in `intent.md`. Build to *that*; the deciding
    already happened, off the chat.
    - **Bound `before`-agents load context first.** If `plumbbob status` shows a
-     `harness bindings:` block, this build binds agents — see **§ Running bound agents**
+     `harness bindings:` block, this build binds agents; see **§ Running bound agents**
      and load their context in before you write. No bindings, no harness: just build.
 4. **Implement** the step, and only that step, staying within the declared seam. A
    new problem or "ooh what if" that surfaces mid-build is a park, **not** an edit:
-   capture it by running `plumbbob park "<one tidy line>"` — **saying "let's defer
+   capture it by running `plumbbob park "<one tidy line>"`: **saying "let's defer
    that" writes nothing; only the park line in the build log is a capture.** When the
    *human* hands you the tangent mid-build, their message **is** the approval to park
-   it — capture it right away, say what you parked, and stay on the step. If you
+   it; capture it right away, say what you parked, and stay on the step. If you
    genuinely cannot finish without touching more than the seam, that is scope drift:
    surface it to the human rather than sprawling.
    - **Bound agents can shape the build.** If `plumbbob status` shows a
      `harness bindings:` block, a `build`-slot agent may author the diff, a `when`-cue may
-     fire an agent mid-build, and a non-`done` envelope routes by its status — see
+     fire an agent mid-build, and a non-`done` envelope routes by its status; see
      **§ Running bound agents**.
 5. **Verify, through to the pause.** Run the verify tick exactly as `/plumbbob:verify`
    does: `plumbbob check` (on red, read `.check/summary.json` and the failing slot's
    raw output under `.check/` for the actual diagnostics; while iterating on a fix,
-   narrow the loop with `plumbbob check --bail --only <slots>` — the checkpoint gate
+   narrow the loop with `plumbbob check --bail --only <slots>`; the checkpoint gate
    still runs everything) → self-review the diff against the done-when, the Decisions,
    and the Constraints (a single structured read; cite each with its slug from
-   `intent.md` — `C1 (no-new-deps)`, never a bare `C1`) → validate → **PAUSE
+   `intent.md`: `C1 (no-new-deps)`, never a bare `C1`) → validate → **PAUSE
    for the human's approval** → only on approval, checkpoint with
-   `plumbbob checkpoint <n> --body <<'BODY' … BODY` — a commit body **proportional to the
+   `plumbbob checkpoint <n> --body <<'BODY' … BODY`: a commit body **proportional to the
    step** (a line for a trivial change, a short paragraph for a meatier one; no TIL scan,
    no separate commit skill). The CLI owns the subject and appends this step to the
-   build-log's `## Log`, so the history writes itself — you only supply the body (or omit
+   build-log's `## Log`, so the history writes itself; you only supply the body (or omit
    `--body` for the deterministic done-when + seam + diffstat fallback). Do **not** bump
-   the version or changelog — that is the human's `/version` call.
+   the version or changelog; that is the human's `/version` call.
+   - **`--body` reads stdin only.** Redirect the heredoc *into* the command (`--body
+     <<'BODY'`). Do **not** pass it as an argument value (`--body "$(cat <<'BODY'…)"`):
+     `--body` ignores an argument and always reads stdin. Under an agent harness that
+     stdin is a socket, and `--body` now refuses rather than blocking on one; the
+     refusal names this exact heredoc form.
    - **A drifted subject is reconciled at the pause, never silently.** The planned
-     title *is* the checkpoint subject — D68 (conventional-subjects). If the diff drifted
-     from it, **present** a corrected subject at the pause — `planned title → proposed
-     subject`, one line — for explicit approval, and only on approval land it by adding
+     title *is* the checkpoint subject ([D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)). If the diff drifted
+     from it, **present** a corrected subject at the pause (`planned title → proposed
+     subject`, one line) for explicit approval, and only on approval land it by adding
      `-m "<subject>"` to the checkpoint. Present nothing and the deterministic
      title-derived subject lands untouched: the reconcile is the human-approved exception,
-     not a quiet `-m` swap (which is the agent-authored subject D68 (conventional-subjects)
+     not a quiet `-m` swap (which is the agent-authored subject [D68 (conventional-subjects)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d68)
      refuses).
    - **If `plumbbob status` shows a `harness bindings:` block**, fold any bound
-     `after`-agents into that self-review as advisory input — see **§ Running bound
+     `after`-agents into that self-review as advisory input; see **§ Running bound
      agents**.
 
    **The latch makes this pause real.** On the default (non-`--auto`) path you
-   build the step and reach the pause *in one turn* — so under plumbbob's turn hook the
+   build the step and reach the pause *in one turn*, so under plumbbob's turn hook the
    checkpoint at the end of that turn is **refused** ("no human turn since this step
    began"), and that refusal **is** the pause working as designed. Do exactly what the
    pause asks: present the diff and the self-review, emit the closing block below, and
-   **end the turn**. The human's next message — their approval — is the human turn that
+   **end the turn**. The human's next message (their approval) is the human turn that
    lets the checkpoint land: on that turn you run `plumbbob checkpoint <n>` (now allowed)
-   and **stop at the boundary**. Landing the checkpoint is its own deliberate beat — the
-   thing approval triggers — never a side effect of starting the next step, and
+   and **stop at the boundary**. Landing the checkpoint is its own deliberate beat (the
+   thing approval triggers), never a side effect of starting the next step, and
    `/plumbbob:build` only ever starts the *next* step. **Never route around a refusal with a
-   raw `git commit`** — the work plane stays free, but the *record* is latched on purpose.
+   raw `git commit`**; the work plane stays free, but the *record* is latched on purpose.
 
    **End every default build turn with the standardized hand-off block.** Run `plumbbob
-   handoff` and present its output — it renders the same three-part shape (the state, the
+   handoff` and present its output; it renders the same three-part shape (the state, the
    choice, what's next) straight from the session: step N built, the looks-good /
    needs-work choice, and the next undone step with its `- model:` recommendation. Show
    your diff and self-review above it. The CLI owns the block so it can't drift from what
    `/plumbbob:status` reports; you supply only the judgment above it. It already drops the model
-   clause when the next step has none, and says so when no planned step remains — you
+   clause when the next step has none, and says so when no planned step remains; you
    don't reproduce the template by hand.
 
    **Then hand off with the next model.** Once the checkpoint lands in the approval turn,
-   run `plumbbob handoff` again and relay its boundary block — with the step gone from
+   run `plumbbob handoff` again and relay its boundary block; with the step gone from
    in-flight it renders "step N checkpointed" and points at the next undone step, carrying
    that step's `- model:` recommendation (the plan's smallest-model-that-fits call) so the
    human knows which `/model` to select before running `/plumbbob:build` again. It is what
@@ -121,19 +126,19 @@ switch with `/model` and rerun to honor it, or wave you on. Advisory, never a ga
 ## Running bound agents
 
 Skip this section unless `plumbbob status` shows a `harness bindings:` block. Nearly every
-build binds **no** agents — for them the default path above is the whole story. When a
+build binds **no** agents; for them the default path above is the whole story. When a
 harness *is* bound, this is what each affected step gains, in lifecycle order.
 
-- **`before` — load context in (step 3).** If the build's `harness.json` binds agents to
+- **`before`: load context in (step 3).** If the build's `harness.json` binds agents to
   this step's `before` slot, run `plumbbob agent run --step <n> --mode before` first: each
   returns a validated envelope on stdout that plumbbob also appends to the step's
   `handoff.json`, and its `summary`/`body` become **context you read into the build** (that
-  is the whole point of the slot — load the context in before you write). No binding, or no
-  harness, is a clean no-op — just build.
-- **`build` — delegate the diff (step 4).** If a `build`-slot agent is bound, run
+  is the whole point of the slot: load the context in before you write). No binding, or no
+  harness, is a clean no-op: just build.
+- **`build`: delegate the diff (step 4).** If a `build`-slot agent is bound, run
   `plumbbob agent run --step <n> --mode build` and let that agent author the step's code
   instead of writing it yourself; its envelope reports what it did. You still own the verify
-  tick — the diff is reviewed the same way whoever wrote it.
+  tick; the diff is reviewed the same way whoever wrote it.
 - **A manifest's `when` prose is your cue to run an agent mid-build (step 4).** The three
   slots are the only *declarative* lifecycle points; there is no config for "a salient
   moment in the middle." That is judgment, and you are the frontier model in the room: when
@@ -142,17 +147,17 @@ harness *is* bound, this is what each affected step gains, in lifecycle order.
   are the workflow engine.
 - **Route a non-`done` envelope by its status (step 4).** An agent that returns `blocked`
   couldn't finish (missing input, failed precondition): surface its `notes`, let the human
-  unblock, and re-run it — don't work around it. One that returns `drift` finished but found
+  unblock, and re-run it; don't work around it. One that returns `drift` finished but found
   the plan no longer matches reality: **stop and send the human to `/plumbbob:refine`** to repair
   the plan before continuing, rather than building on a plan that's now wrong. A non-zero
   exit is a failed run: report it and stop.
-- **`after` — advisory input to the verify tick (step 5).** After `plumbbob check`, run any
+- **`after`: advisory input to the verify tick (step 5).** After `plumbbob check`, run any
   bound `after`-agents (`plumbbob agent run --step <n> --mode after`) and fold their
-  envelopes into the self-review as **advisory input** — they inform, they never gate
+  envelopes into the self-review as **advisory input**; they inform, they never gate
   (checkride gates, the human is the clock; an `after`-agent that could fail a step would
   be the old lock back in another form).
 
-## `--auto` — let the agent be the clock (opt-in)
+## `--auto`: let the agent be the clock (opt-in)
 
 `/plumbbob:build --auto` is the explicit escape hatch when the human wants unattended
 progress instead of approving each step. It does the same work, but **the agent reviews
@@ -162,41 +167,41 @@ and approves in the human's place**, and it **chains**:
   order as the default path: bound `before`-agents → implement (or the bound `build`-agent) → bound
   `after`-agents → `check` → self-review → **if the check is green AND the
   self-review finds no done-when / Decision / Constraint mismatch, checkpoint** and move
-  straight on to the next planned step. Repeat. `--auto` adds no new machinery — the
+  straight on to the next planned step. Repeat. `--auto` adds no new machinery; the
   `after`-agent output simply feeds the *existing* self-review halt condition.
 - **Stop and hand back to the human** the moment any of these is true: the check is red,
   the self-review finds a mismatch (surface exactly what, and do not checkpoint it), a
-  bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/plumbbob:refine` — an
+  bound agent returns `blocked` or `drift` (unblock-and-re-run, or `/plumbbob:refine`; an
   agent cannot advance the loop), a new decision is needed, no planned steps
   remain, or the top of a requested range is reached. **When `--auto` halts back to the
-  human, give the same hand-off the default pause does** — run `plumbbob handoff` and
+  human, give the same hand-off the default pause does**; run `plumbbob handoff` and
   relay its block: the step just completed, the next undone step, and that next step's
   `- model:` recommendation if it has one, so a fresh context window knows which `/model`
   to select.
 
 `--auto` and a step range are the only paths that checkpoint without a human pause, and
 only because the human asked for it by name; a range re-imposes the pause at its top.
-The default — no flag, no range — always ends at the pause.
+The default (no flag, no range) always ends at the pause.
 
 ### A step range (`N-M`) is a bounded `--auto`
 
 `/plumbbob:build 1-3` self-approves steps 1 through 3 exactly as `--auto` does, then **pauses
-after step 3** instead of chaining to done. The range *is* the opt-in — you do not also
+after step 3** instead of chaining to done. The range *is* the opt-in; you do not also
 pass `--auto`. Run it as the `--auto` loop with one extra halt: **stop before building
-any next step whose plan number is past the top of the range.** It adds no machinery —
+any next step whose plan number is past the top of the range.** It adds no machinery:
 just the one more entry already in the halt list above.
 
-- **`N-M` with N ≤ M** — build N…M, self-approving and checkpointing each, then pause at
+- **`N-M` with N ≤ M**: build N…M, self-approving and checkpointing each, then pause at
   M. `N-N` is just the single step `N` (which already ends at the pause).
-- **N > M** (e.g. `3-1`) — that is not a range you can walk; report it and stop rather
+- **N > M** (for example `3-1`): that is not a range you can walk; report it and stop rather
   than guess the intent.
-- **M past the last planned step** (e.g. `1-9` with three steps) — build through the
+- **M past the last planned step** (for example `1-9` with three steps): build through the
   last planned step and stop; that is the existing "no planned steps remain" halt, not
   an error.
-- **A step inside the range won't build** (missing, or its seam won't parse) — `plumbbob
+- **A step inside the range won't build** (missing, or its seam won't parse): `plumbbob
   build <n>` fails exactly as it always does; surface it and stop, the same as a red
   check. Do not skip past the gap.
-- **N is above the next undone step** — you are jumping over earlier planned work; note
+- **N is above the next undone step**: you are jumping over earlier planned work; note
   that you are skipping the steps before N, then proceed (the same latitude as a
   single-number jump like `/plumbbob:build 4`).
 
@@ -205,27 +210,27 @@ just the one more entry already in the halt list above.
 - **Swappable, never required.** The loop works without this skill; `/plumbbob:verify`
   checkpoints a hand-built or vibed diff just the same.
 - **Build the decided step, not a new one.** Implement what `intent.md` settled. A
-  new idea mid-build is captured with `plumbbob park`, not an edit — a promise to
+  new idea mid-build is captured with `plumbbob park`, not an edit: a promise to
   defer writes nothing; the park line does.
 - **Default ends at the pause.** Implement → verify → wait for approval; never
   checkpoint without it. Only an explicit `--auto` or a step range lets the agent approve
-  in your place, and it still halts on a red check or any mismatch — a range also stops
+  in your place, and it still halts on a red check or any mismatch; a range also stops
   at its top.
 - **Agents feed the beat; they never advance it**. `before` loads context,
-  `build` writes the diff, `after` is advisory — none can checkpoint, flip a step, or
+  `build` writes the diff, `after` is advisory; none can checkpoint, flip a step, or
   chain. `blocked` → unblock and re-run; `drift` → `/plumbbob:refine`. You are still the one
   who verifies and (bar `--auto`) the human is still the clock. See **§ Running bound
   agents** for the mechanics.
 - **A refused checkpoint is the pause, not an error.** Under plumbbob's turn
-  hook a same-turn `checkpoint` is refused by design — present the diff and the closing
+  hook a same-turn `checkpoint` is refused by design: present the diff and the closing
   block, **end the turn**; the human's approval on their next turn is what lets you land
   it, and landing it is a deliberate beat, not a side effect of the next `/plumbbob:build`.
   Never route around it with a raw `git commit`. An explicit `/plumbbob:build --auto` or a typed
-  step range in the human's own prompt are the only self-approvals — **never write `auto`
+  step range in the human's own prompt are the only self-approvals; **never write `auto`
   into a settings file yourself to unlock a checkpoint. A grant you mint is no grant (the
-  latch ignores it — D67 (auto-not-a-grant)); ask the human to type
+  latch ignores it; [D67 (auto-not-a-grant)](https://github.com/robmclarty/plumbbob/blob/main/docs/decisions.md#d67)); ask the human to type
   `/plumbbob:build --auto` again instead.**
 - **Close with the next model.** When a step lands, run `plumbbob handoff` and relay its
-  block — it cites the completed step and the next undone step, and names that next step's
+  block; it cites the completed step and the next undone step, and names that next step's
   `- model:` recommendation if it has one, which is what a fresh context window needs to
   pick the right `/model` before the next run. Guidance, never a gate.

package/skills/doctor/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: doctor
-description: Diagnose the plugin install from inside a session — is plumbbob linked, are the skills and hook present, is there a collision. A thin trigger for `plumbbob doctor`. Matters most for a marketplace install, where the CLI is on PATH only inside Claude Code.
+description: "Diagnose the plugin install from inside a session: is plumbbob linked, are the skills and hook present, is there a collision. A thin trigger for `plumbbob doctor`. Matters most for a marketplace install, where the CLI is on PATH only inside Claude Code."
 disable-model-invocation: true
 model: haiku
 allowed-tools: Bash(plumbbob doctor:*)
 ---
 
-# PlumbBob — doctor (the is-it-installed-right move)
+# PlumbBob: doctor (the is-it-installed-right move)
 
 Install diagnostic (injected when this skill runs): !`plumbbob doctor 2>&1 || true`
 
-This is a **thin driver** for `plumbbob doctor`. The report above is read-only — `doctor`
+This is a **thin driver** for `plumbbob doctor`. The report above is read-only: `doctor`
 inspects, it never writes. This skill carries **no Edit and no Write tool**: never edit a file
 to change what the report says. If a check failed, surface its `→ fix` verbatim and apply
 *that* fix, then have the human **restart Claude Code (or `/reload-plugins`)**. **Never retry.**
@@ -19,23 +19,23 @@ to change what the report says. If a check failed, surface its `→ fix` verbati
 
 The CLI's reach differs by install path, and that is the whole point of running `doctor` here:
 
-- **Marketplace plugin** — `plumbbob` is on PATH **only inside a Claude Code session** (its
-  `bin/` shims are injected into the Bash tool while the plugin is enabled). There is **no
-  terminal `plumbbob`** to run. So this skill — or letting me run `plumbbob doctor` in-session
-  — is the *only* way to reach `doctor`. The fact that this skill loaded at all already proves
+- **Marketplace plugin**: `plumbbob` is on PATH **only inside a Claude Code session** (its
+  `bin/` shims are injected into the Bash tool while the plugin is enabled). **No
+  terminal `plumbbob`** exists. So this skill (or letting me run `plumbbob doctor` in-session)
+  is the *only* way to reach `doctor`. The fact that this skill loaded at all already proves
   the plugin is enabled and the shim is on PATH.
-- **Skills-dir / global install** (`npm i -g plumbbob` + `plumbbob init`) — `plumbbob` is on
+- **Skills-dir / global install** (`npm i -g plumbbob` + `plumbbob init`): `plumbbob` is on
   PATH everywhere, so terminal `plumbbob doctor` works too; this skill is just convenience.
 
 The one failure `doctor` **cannot** diagnose: a plugin that never loaded at all (no
-`/plumbbob:*` skill appears). That is a `/plugin` / `/reload-plugins` problem, not doctor's —
+`/plumbbob:*` skill appears). That is a `/plugin` / `/reload-plugins` problem, not doctor's,
 and if you are reading this, that is not your situation.
 
 ## What it does
 
-1. Surface the injected `doctor` report verbatim — every `✓` and any `✗` with its `→ fix`.
+1. Surface the injected `doctor` report verbatim: every `✓` and any `✗` with its `→ fix`.
    If nothing rendered above (a few headless `-p` sessions skip the injection), just run
-   `plumbbob doctor` yourself — it is in your tools — and surface that.
+   `plumbbob doctor` yourself (it is in your tools) and surface that.
 2. If all checks passed, say so; if a skill still misbehaves, the fix is a restart, not a re-run.
 3. If a check failed, apply its named `→ fix`, then restart Claude Code (or `/reload-plugins`).
 4. If the report is empty or shows `command not found`, the CLI is not on PATH: for a