plumbbob 0.6.5 → 0.8.0

package/node_modules/checkride/schema/checkride.config.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/robmclarty/checkride/main/schema/checkride.config.schema.json",
+  "title": "checkride configuration",
+  "description": "Schema for checkride.config.json — add it only to deviate from the zero-config defaults.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URL of this JSON Schema, for editor validation and autocompletion."
+    },
+    "extends": {
+      "description": "Preset(s) to inherit — a file path (./base.json) or package specifier (@acme/preset), or an array of them. Bases merge left-to-right and the local config wins over all; objects deep-merge, arrays and scalars replace (arrays are not concatenated).",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+    "timeout": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Default per-check timeout in seconds. Unset, checks fall back to the built-in 600s cap; 0 here or on a check disables the cap."
+    },
+    "checks": {
+      "type": "object",
+      "description": "Per-slot configuration. A key that matches a catalogue slot (types, format, lint, struct, dead, test, docs, links, spell, mutation, security, publint, attw) configures that slot; any other key is a custom check that runs alongside the catalogue. Naming an opt-in slot (format, mutation, security, publint, attw) here also opts it into the default run.",
+      "additionalProperties": {
+        "$ref": "#/definitions/slotConfig"
+      }
+    }
+  },
+  "definitions": {
+    "slotConfig": {
+      "description": "How to fill a slot: an adapter name, false to disable it, an adapter with overrides, or a custom check.",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Adapter name that fills this slot, beating detection."
+        },
+        {
+          "const": false,
+          "description": "Disable this slot (skipped, not failed)."
+        },
+        { "$ref": "#/definitions/useConfig" },
+        { "$ref": "#/definitions/customCheck" }
+      ]
+    },
+    "useConfig": {
+      "type": "object",
+      "description": "Pick an adapter by name and override individual fields.",
+      "required": ["use"],
+      "additionalProperties": false,
+      "properties": {
+        "use": {
+          "type": "string",
+          "description": "Adapter name to select from the registry."
+        },
+        "command": { "type": "string" },
+        "args": { "type": "array", "items": { "type": "string" } },
+        "description": { "type": "string" },
+        "outputFile": { "type": ["string", "null"] },
+        "changedArgs": { "type": "array", "items": { "type": "string" } },
+        "fixArgs": { "type": "array", "items": { "type": "string" } },
+        "timeout": { "type": "number", "minimum": 0 }
+      }
+    },
+    "customCheck": {
+      "type": "object",
+      "description": "A bare command that needs no adapter.",
+      "required": ["command"],
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "Executable to spawn."
+        },
+        "args": { "type": "array", "items": { "type": "string" } },
+        "description": { "type": "string" },
+        "outputFile": { "type": ["string", "null"] },
+        "changedArgs": { "type": "array", "items": { "type": "string" } },
+        "fixArgs": { "type": "array", "items": { "type": "string" } },
+        "timeout": { "type": "number", "minimum": 0 },
+        "name": { "type": "string" },
+        "detect": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Marker files that gate a non-catalogue custom check: it runs only when at least one listed file exists, and is skipped otherwise. Ignored on an entry that fills a catalogue slot."
+        },
+        "order": {
+          "enum": ["first", "last"],
+          "description": "Where a non-catalogue custom check runs relative to the catalogue. Default 'last'."
+        }
+      }
+    }
+  }
+}

package/node_modules/checkride/schema/checkride.summary.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/robmclarty/checkride/main/schema/checkride.summary.schema.json",
+  "title": "checkride run summary",
+  "description": "Schema for .check/summary.json — the aggregate report every run writes. A public API for agents and gate consumers. Fields are additive under schema_version 1: they are added (in lockstep with this schema), never renamed, removed, or retyped without a version bump. See docs/contract.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "timestamp", "ok", "checks_run", "total_duration_ms", "checks"],
+  "properties": {
+    "schema_version": {
+      "const": 1,
+      "description": "Version of this report shape. Bumped only for a breaking (non-additive) change."
+    },
+    "timestamp": {
+      "type": "string",
+      "description": "ISO 8601 time the report was written."
+    },
+    "ok": {
+      "type": "boolean",
+      "description": "True when every check passed (skipped checks count as ok). Can be vacuous — see checks_run."
+    },
+    "checks_run": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Count of checks that actually executed (skipped entries excluded). ok=true with checks_run=0 is a vacuous green: nothing was verified. Gate consumers should treat it as a failure (or run with --strict, which exits 2)."
+    },
+    "total_duration_ms": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Sum of all check durations in milliseconds."
+    },
+    "checks": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/check" },
+      "description": "One entry per selected slot, in pipeline order."
+    }
+  },
+  "definitions": {
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "adapter", "description", "ok", "exit_code", "duration_ms", "output_file"],
+      "properties": {
+        "name": { "type": "string", "description": "Slot name (e.g. lint), or a custom check's key." },
+        "adapter": { "type": ["string", "null"], "description": "Adapter that ran (e.g. oxlint), or null when the slot resolved to nothing." },
+        "description": { "type": "string", "description": "Human description of the check." },
+        "ok": { "type": "boolean", "description": "Pass/fail after any baseline masking; skipped checks are ok." },
+        "skipped": { "type": "boolean", "description": "Present (true) when the check did not execute; see reason." },
+        "reason": { "type": "string", "description": "Why a skipped check sat out (no tool detected, disabled in config, unavailable under this package manager, ...)." },
+        "exit_code": { "type": ["integer", "null"], "description": "The tool's exit code; -1 for spawn failure or timeout; null when skipped." },
+        "duration_ms": { "type": "number", "description": "Wall-clock duration in milliseconds (0 when skipped)." },
+        "output_file": { "type": ["string", "null"], "description": "The .check/ file holding the tool's raw JSON output, when it emits JSON on stdout." },
+        "baselined": { "type": "integer", "minimum": 1, "description": "Present only when a committed baseline masked diagnostics: how many current findings are grandfathered." }
+      }
+    }
+  }
+}

package/node_modules/checkride/templates/shared/cspell.json

@@ -12,6 +12,7 @@
   ],
   "words": [
     "checkride",
+    "baselined",
     "biome",
     "cspell",
     "devDeps",

package/node_modules/checkride/templates/shared/prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "semi": true
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
-  "version": "0.6.5",
-  "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance, not enforcement.",
+  "version": "0.8.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",
     "claude",
@@ -48,13 +48,14 @@
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "fallow": "^2.103.0",
+    "fascicle": "0.8.16",
     "markdownlint-cli2": "^0.22.1",
     "oxlint": "^1.69.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "checkride": "0.1.6"
+    "checkride": "0.3.0"
   },
   "bundleDependencies": [
     "checkride"
@@ -63,6 +64,9 @@
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
     "check": "checkride",
-    "test": "vitest run"
+    "test": "vitest run",
+    "eval:baseline": "pnpm build && node test/evals/run.ts --sweep baseline",
+    "eval:latched": "pnpm build && node test/evals/run.ts --sweep latched",
+    "eval:report": "node test/evals/run.ts --report"
   }
 }

package/skills/pb-build/SKILL.md

@@ -3,7 +3,6 @@ name: pb-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 /pb-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
-model: opus
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent:*), Bash(git diff:*)
 ---
 
@@ -12,7 +11,7 @@ allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob build:*
 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
-**swappable** (D3): you can implement any step by hand, in a vibe session, or with
+**swappable**: you can implement any step by hand, in a vibe session, or with
 another harness and go straight to `/pb-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.
@@ -21,6 +20,11 @@ Since `/pb-plan` lays down the whole step list up front, the happy path is to fi
 `/pb-build` once per step until done — each run builds the next undone step and stops
 at the pause for your approval. **Re-firing `/pb-build` is itself the clock tick.**
 
+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
+`/model` and re-fire 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. `/pb-build 4`) — or,
@@ -34,7 +38,7 @@ at the pause for your approval. **Re-firing `/pb-build` is itself the clock tick
 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
    already happened, off the chat.
-   - **Run any bound `before`-agents** *(D43/D59)*. If the build's `harness.json` binds
+   - **Run any bound `before`-agents**. 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
@@ -45,17 +49,17 @@ at the pause for your approval. **Re-firing `/pb-build` is itself the clock tick
    edit — capture it 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.
-   - **If a `build`-slot agent is bound, delegate the diff to it** *(D43)*. Run
+   - **If a `build`-slot agent is bound, delegate the diff to it**. 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 below — the diff is reviewed the same way whoever wrote it (D3).
-   - **A manifest's `when` prose is your cue to fire an agent mid-build** *(D43/D55)*.
+     own the verify tick below — the diff is reviewed the same way whoever wrote it.
+   - **A manifest's `when` prose is your cue to fire an agent mid-build**.
      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 the work reaches the situation a bound agent's `when` (or a step
      `note`) describes, fire `plumbbob agent run <name> --step <n>` yourself. Prose is
      the orchestration language; you are the workflow engine.
-   - **Route a non-`done` envelope by its status** *(D52)*. An agent that returns
+   - **Route a non-`done` envelope by its status**. 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 the plan no longer matches reality: **stop and send the
@@ -68,9 +72,9 @@ at the pause for your approval. **Re-firing `/pb-build` is itself the clock tick
    still runs everything) → 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 (checkride gates, the human is the clock; an
-   `after`-agent that could fail a step is the lock in autonomy's costume, D45) →
+   `after`-agent that could fail a step is the lock in autonomy's costume) →
    self-review the diff against the done-when, the Decisions, and the Constraints (a
-   single structured read, D16) → validate → **PAUSE
+   single structured read) → validate → **PAUSE
    for the human's approval** → only on approval, checkpoint with
    `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,
@@ -79,14 +83,23 @@ at the pause for your approval. **Re-firing `/pb-build` is itself the clock tick
    `--body` for the deterministic done-when + seam + diffstat fallback). Do **not** bump
    the version or changelog — that is the human's `/version` call.
 
+   **The latch makes this pause real (D64).** On the default (non-`--auto`) path you
+   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 already asks: present the diff and the self-review, **end the turn**, and the
+   human's next message is the tick that lands the checkpoint when you re-fire. **Never
+   route around a refusal with a raw `git commit`** — the work plane stays free (D10/D13),
+   but the *record* is latched on purpose.
+
 ## `--auto` — let the agent be the clock (opt-in)
 
 `/pb-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
 and approves in the human's place**, and it **chains**:
 
-- Build the next step, running its slots in the same order as the default path
-  (D56): bound `before`-agents → implement (or the bound `build`-agent) → bound
+- Build the next step, running its slots in the same 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
@@ -94,7 +107,7 @@ and approves in the human's place**, and it **chains**:
 - **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 `/pb-refine` — an
-  agent cannot advance the loop, C6), a new decision is needed, no planned steps
+  agent cannot advance the loop), a new decision is needed, no planned steps
   remain, or the top of a requested range is reached.
 
 `--auto` and a step range are the only paths that checkpoint without a human pause, and
@@ -126,14 +139,19 @@ just the one more entry already in the halt list above.
 ## The hard contracts
 
 - **Swappable, never required.** The loop works without this skill; `/pb-verify`
-  checkpoints a hand-built or vibed diff just the same (D3).
+  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 a `/pb-park`, not an edit.
 - **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
   at its top.
-- **Agents feed the beat; they never advance it** (C6/D45). `before` loads context,
+- **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
   chain. `blocked` → unblock and re-run; `drift` → `/pb-refine`. You are still the one
   who verifies and (bar `--auto`) the human is still the clock.
+- **A refused checkpoint is the pause, not an error (D64).** Under plumbbob's turn
+  hook a same-turn `checkpoint` is refused by design — present the diff, **end the
+  turn**, and the human's next message is the tick that lands it on re-fire. Never route
+  around it with a raw `git commit`; `--auto`, a typed range, or `auto: true` are the
+  only self-approvals.

package/skills/pb-finish/SKILL.md

@@ -2,7 +2,6 @@
 name: pb-finish
 description: Finish the build — write the report (what shipped, decisions, parked/harvested items, deferred tangents), then make the final commit that closes the session. The build folder rides the branch into the PR — no separate archive. Report by default, no gate.
 disable-model-invocation: true
-model: opus
 allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob finish:*)
 ---
 
@@ -11,8 +10,8 @@ allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob finish:*)
 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."`
 
 `/pb-finish` ends the build: it captures what happened, then makes the final commit
-that closes the session. **Report by default** (D9) — no refuse-without-report gate,
-and no separate docs phase. The build folder is tracked (D26/D29): it merges with the
+that closes the session. **Report by default** — no refuse-without-report gate,
+and no separate docs phase. The build folder is tracked: it merges with the
 branch and shows up in the PR, so there is nothing to archive — the folder *is* the
 record.
 
@@ -30,8 +29,8 @@ record.
    - **Deferred tangents** — the harvested items that become future work.
    This is the "yeah, I did that" artifact. Write it by default; the human may edit it.
 2. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
-   report and makes the final commit — subject `plumbbob: finish — <title>` (D34),
-   with an optional proportional body via `--body` (the D34 stdin heredoc) — then
+   report and makes the final commit — subject `plumbbob: finish — <title>`,
+   with an optional proportional body via `--body` (the stdin heredoc) — then
    clears the control state (markers, the `activeBuild` cursor, STATE last). The
    build folder stays in place, committed, and rides the branch into the PR.
 3. **Point at the next goal** — `/pb-plan` to frame the next one.
@@ -43,7 +42,7 @@ record.
 - **The log is the history; the report is the synthesis.** `checkpoint` already recorded
   what shipped, step by step — finish applies the *unique additions* (the why, the deferred
   tangents, the final status), it does not rewrite the timeline.
-- **The folder is the archive, never destroy** (C4/D29). `finish` keeps intent +
+- **The folder is the archive, never destroy**. `finish` keeps intent +
   build-log + report in `builds/<slug>/` and commits them; nothing is copied out and
   nothing is deleted but the untracked control markers.
 - **No version bump, no docs phase.** Updating real docs is a separate, explicit ask;

package/skills/pb-harvest/SKILL.md

@@ -2,7 +2,6 @@
 name: pb-harvest
 description: Triage the park list at a step boundary — propose one class (blocker/tangent/pivot) per parked item, write only after the human confirms each, record under ## Harvest, and fold a confirmed blocker into intent.
 disable-model-invocation: true
-model: opus
 allowed-tools: Read, Edit, Bash(plumbbob status:*)
 ---
 
@@ -10,7 +9,7 @@ allowed-tools: Read, Edit, Bash(plumbbob status:*)
 
 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."`
 
-`/pb-harvest` is the complement of `/pb-park` (D7): you parked ideas as seeds during a
+`/pb-harvest` is the complement of `/pb-park`: you parked ideas as seeds during a
 build; now, at a boundary, you harvest them — decide what each one is.
 
 ## When to run it — boundary only

package/skills/pb-park/SKILL.md

@@ -12,7 +12,7 @@ allowed-tools: Bash(plumbbob status:*), Bash(plumbbob park:*)
 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."`
 
 `/pb-park` is the **capture** half of the loop; `/pb-harvest` is where parked items
-get triaged later (D7). Capturing the instant an idea arrives — instead of acting on
+get triaged later. Capturing the instant an idea arrives — instead of acting on
 it — is the whole point: it protects the step in flight.
 
 ## Wrong-state refusal

package/skills/pb-plan/SKILL.md

@@ -3,7 +3,6 @@ name: pb-plan
 description: "Frame a fresh goal and author the whole plan — Frame, Decisions, Constraints, and all Steps — before any code. Three input modes: no arg interviews you; a file path absorbs a spec; any other text expands your inline intent."
 argument-hint: "[spec-path | intent]"
 disable-model-invocation: true
-model: opus
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent list:*)
 ---
 
@@ -17,6 +16,11 @@ of your head and onto `intent.md` *before* any code. By default it authors the
 `/pb-build` until done. (Revising a single increment later is the separate `/pb-step`
 move; do not confuse the two.)
 
+A model note: this skill **inherits the session model** — nothing pins or switches
+it. Planning is where frontier-class judgment pays for itself, so if the session is
+running a small model, suggest `/model opus` (or better) before framing — the
+human's call, never a gate.
+
 ## Three input modes (disambiguated for you — no quotes needed)
 
 Look at the argument the human gave and pick the mode yourself:
@@ -41,6 +45,10 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
 1. **Scaffold.** If there is no active session, run `plumbbob start "<title>"`
    to create `.plumbbob/` (baseline recorded, session opened). If a session already
    exists, say so and edit the existing `intent.md` rather than starting over.
+   - **If `start` warns that the gate sees no code checks**, surface that to the
+     human now — while they're still deciding, not at the first refused
+     checkpoint — and offer to set the `check` key in `.plumbbob/settings.json`
+     (e.g. `"check": "npm test"`) before any step is built.
 2. **Frame** (`.plumbbob/intent.md`), with the human: the **Problem** in plain words,
    the **smallest thing** that solves it, what **done looks like**, and what you are
    **explicitly NOT doing**. This is the human's convergence — propose wording, but
@@ -54,13 +62,24 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    ```markdown
    1. [ ] <title> — **done when:** <criterion, ideally a test or check result>
       - seam: `<file>`, `<file>`
+      - model: <optional — smallest that can carry it, with the one-phrase why>
    ```
 
    Every step needs a **done-when** `/pb-verify` can check and a **seam** (the exact
    paths it touches). Later steps may be fuzzier than the first — that's fine; they get
    sharpened just-in-time when you reach them with `/pb-step`. Keep each small enough to
    verify in one review pass.
-5. **Offer harness bindings** *(optional — D42/D43)*. If the build will lean on
+
+   **Recommend a model per step where the signal is clear** *(optional)*: the
+   `- model:` sub-line names the **smallest model that can carry the step**, with the
+   one-phrase why — the human buys capability only where the step needs it. E.g.
+   `model: sonnet — mechanical, fully specified by the done-when` for rote edits;
+   `model: opus — strong-assertion test authoring` where the tests do the thinking;
+   `model: fable — subtle cross-cutting design` for judgment-heavy or creative work.
+   It is advisory metadata for the human — `/pb-status` surfaces it before each build —
+   never a gate, and nothing switches models automatically. Write it plain (no
+   backticks) and omit it when any model would do.
+5. **Offer harness bindings** *(optional)*. If the build will lean on
    user-authored agents, author `harness.json` in the build folder (beside `intent.md`)
    and review it at the **same plan pause**, alongside the steps — bindings are
    plan-adjacent configuration, so they converge with the plan. It binds agents to a
@@ -76,18 +95,31 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    }
    ```
 
-   Keep it **bindings + prose only, never a conditional** (C3): the file says *which*
+   Keep it **bindings + prose only, never a conditional**: the file says *which*
    agent, not *when* — the host model reads each manifest's `when` prose and a step's
    `note` and decides when to fire one mid-build. Skip the file entirely when no step
-   uses an agent — the loop runs identically without it (D54). The plan commit picks it
+   uses an agent — the loop runs identically without it. The plan commit picks it
    up automatically (it lives in the build folder).
 6. **Commit the plan.** Once the human approves the frame and steps, run
    `plumbbob checkpoint --plan` to commit the scaffold on its own — subject
    `plumbbob: plan — <title>`, only `.plumbbob/builds/<slug>/`, a `plan <sha>` line in
-   `checkpoints` (D36). This keeps the first step's diff clean, so history reads
+   `checkpoints`. This keeps the first step's diff clean, so history reads
    baseline → plan → steps. Pass a proportional `--body` (the single-quoted stdin
    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 commit is latched too (D64).** 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
+     commit on re-fire — the refusal *is* the plan pause. Never route around it with a
+     raw `git commit`. (One documented seam: the very first plan of a brand-new
+     session runs `start` *before* the turn hook has ever ticked, so that single
+     commit predates the ledger and stays guidance-governed — it lands without a
+     refusal.)
+   - **Say what the commit publishes.** The close-out line names the tracked folder:
+     `.plumbbob/builds/<slug>/` now rides this branch into the PR, so teammates will
+     see the plan and build record in review. In the same breath, offer the way out:
+     a repo that won't track a tool folder can restart with `plumbbob start --local`
+     (a fully untracked sidecar) before any steps are built.
 7. **Offer to stress-test it.** Suggest `/pb-refine` to attack the frame for holes (or
    to repair the plan as it drifts). Optional, the human's call.
 

package/skills/pb-refine/SKILL.md

@@ -3,7 +3,6 @@ name: pb-refine
 description: Keep intent.md true — attack the plan for holes (append as Open questions) and refine or repair the Frame, Decisions, Constraints, and Steps to match reality. Usable at any point; you propose, the human approves.
 argument-hint: "[focus]"
 disable-model-invocation: true
-model: opus
 allowed-tools: Read, Edit, Bash(plumbbob status:*)
 ---
 

package/skills/pb-status/SKILL.md

@@ -19,4 +19,8 @@ skill carries **no Edit and no Write tool**: the CLI is the source of truth, so
 ## What it does
 
 1. Surface the injected `status` output — the dashboard and its suggested next move.
-2. If it reads `NO ACTIVE SESSION`, tell the human to `/pb-plan` to frame a goal.
+2. If the next step's detail carries a `model:` line, point it out: it is the
+   plan's recommendation of the smallest model that can carry that step, so the human
+   can switch (e.g. `/model sonnet`) before firing `/pb-build` — or ignore it. Guidance,
+   never a gate.
+3. If it reads `NO ACTIVE SESSION`, tell the human to `/pb-plan` to frame a goal.

package/skills/pb-step/SKILL.md

@@ -3,7 +3,6 @@ name: pb-step
 description: Revise the next increment just-in-time — sharpen the next undone step against what's now true, or (with input) re-cut, split, or add a step. Empty input runs an automatic sharpen. One at a time; the human approves.
 argument-hint: "[what-changed]"
 disable-model-invocation: true
-model: opus
 allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob agent list:*)
 ---
 
@@ -36,17 +35,19 @@ grew — but its everyday job is to sharpen, not to invent.
 2. **Propose the revision** (or the new/split step): a one-line **title**, a **done-when**
    `/pb-verify` can validate, and a **seam** (exact paths, or a `dir/` grant). Keep it
    small enough to verify in one review pass. Show the before/after so the human can see
-   what you changed and why.
+   what you changed and why. Re-check the optional `- model:` recommendation too:
+   a step that sharpened into rote work can drop to a smaller model; one that grew subtle
+   earns a frontier one. Advisory, plain text (no backticks), never a gate.
 3. **Get the human's OK**, then write it into `## Steps` in the standard format —
    `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Revise the
    existing step in place; only append when you are genuinely adding an increment.
-4. **Revise the step's harness bindings if they drifted too** *(optional — D42)*. If the
+4. **Revise the step's harness bindings if they drifted too** *(optional)*. If the
    build carries a `harness.json` (beside `intent.md`) and the reality that moved the
    step also changed which agents it wants, sharpen that step's slot bindings
    (`before`/`build`/`after`) and `note` at the same time — this is the just-in-time
    counterpart to `/pb-plan`'s plan-time binding. `plumbbob agent list` shows what's
    resolvable. Same rule as the plan move: bindings + prose only, never a conditional
-   (C3). Leave it untouched when the step's agents are still right, or when the build
+  . Leave it untouched when the step's agents are still right, or when the build
    uses none.
 
 ## The hard contracts

package/skills/pb-verify/SKILL.md

@@ -2,7 +2,6 @@
 name: pb-verify
 description: "The verify tick — run the check, self-review the diff against intent, validate the step's done-when, pause for your approval, then checkpoint. Executor-agnostic: it reads the diff, not who wrote it."
 disable-model-invocation: true
-model: opus
 allowed-tools: Read, Bash(plumbbob status:*), Bash(plumbbob check:*), Bash(plumbbob checkpoint:*), Bash(plumbbob agent:*), Bash(git diff:*), Bash(git status:*)
 ---
 
@@ -12,29 +11,29 @@ Current session state (injected when this skill runs): !`plumbbob status 2>/dev/
 
 This is the **tick** — the one beat where the human is the clock. Whatever produced
 the current diff — `/pb-build`, your own hands, a vibe session, another harness —
-this skill verifies it the same way: **it reads the diff, not the author** (D3).
+this skill verifies it the same way: **it reads the diff, not the author**.
 
 ## What this skill does, in order
 
 1. **Check.** Run `plumbbob check` (the heavy gate — checkride unless the repo
-   configures a `check` override, D32). If it comes back **red**, stop here: the gate
+   configures a `check` override). If it comes back **red**, stop here: the gate
    names the failing slots and where each tool's raw output landed — read
    `.check/summary.json`, then the failing slot's own file (`.check/<slot>.json` or
    `.check/<slot>.stdout.txt`) for the actual diagnostics instead of scraping
    scrollback. Report what failed and do **not** pause for approval — there is
    nothing to approve yet. The human fixes it and re-invokes. (Exit 2 means the gate
    itself broke — a harness problem to surface, not a code failure.)
-2. **Run any bound `after`-agents** *(optional — D45)*. If the build's `harness.json`
+2. **Run any bound `after`-agents** *(optional)*. If the build's `harness.json`
    binds agents to this step's `after` slot, run `plumbbob agent run --step <n> --mode
    after`. Their envelopes are **advisory input to the self-review, never a gate** —
    `plumbbob check` already gated in step 1, and an `after`-agent that could fail a step
-   is the lock returning in autonomy's costume (D45). Fold a `done` envelope's
-   `summary`/`body` into the review below; route a non-`done` one by its status (D52): a
+   is the lock returning in autonomy's costume. Fold a `done` envelope's
+   `summary`/`body` into the review below; route a non-`done` one by its status: a
    `blocked` agent couldn't finish — surface its `notes`, let the human unblock, re-run;
    a `drift` agent found the plan no longer matches reality — stop and send the human to
    `/pb-refine` to repair the plan before checkpointing. No binding, or no harness, is a
    clean no-op.
-3. **Self-review** *(a single structured read, D16)*. Read `git diff` and
+3. **Self-review** *(a single structured read)*. Read `git diff` and
    `.plumbbob/intent.md`, then in one pass check the diff against:
    - the current step's **done-when** criterion — is it actually met?
    - the **Decisions** — does anything contradict a settled call?
@@ -64,16 +63,34 @@ this skill verifies it the same way: **it reads the diff, not the author** (D3).
    (done-when + seam + diffstat) on its own. Either way, do **not** bump the version or
    touch the changelog — that is the human's `/version` call.
 
+## The latch makes the pause real (D64)
+
+When this session runs under plumbbob's turn hook, `plumbbob checkpoint` **refuses to
+land a step in the same turn it was entered** — and that refusal **is** this pause, not
+an error to route around. If the checkpoint prints *"checkpoint refused — no human turn
+since this step began,"* you have reached the pause the hard way: present the diff and
+the self-review, **end the turn**, and the human's next message is the tick that lets
+the checkpoint land when you re-fire. **Never reach for a raw `git commit` to force the
+land** — that forges the very record the latch exists to keep honest, and the
+commit-ask hook asks the human about it anyway. The refusal is a healthy latch doing its
+job on the *record* while the *work* plane stays free (D10/D13); a `/pb-build --auto` or
+a typed step range in the human's own prompt is the only self-approval, and `auto: true`
+in settings is the standing one.
+
 ## The hard contracts
 
 - **Never skip the pause.** Check → self-review → validate, then wait. Approval is
   the only thing that triggers the checkpoint.
-- **Read the diff, not the author** (D3). Verify identically whether the code was
+- **Read the diff, not the author**. Verify identically whether the code was
   built by `/pb-build`, by hand, vibed, or by another harness.
 - **Red means stop, not pause.** A failing check is not an approval decision; report
   it and end your turn.
 - **You review; you do not build.** If the self-review finds a problem, surface it
   and stop — fixing is a new build beat, not part of verify.
-- **`after`-agents advise; they never gate** (D45). Their output feeds the
+- **`after`-agents advise; they never gate**. Their output feeds the
   self-review — checkride gates, the human approves. `blocked` → unblock and re-run;
   `drift` → `/pb-refine` before checkpointing. No code path makes them blocking.
+- **A refused checkpoint is the pause, never a workaround (D64).** Under the turn
+  hook a same-turn checkpoint is refused *by design* — present the diff, **end the
+  turn**, and let the human's next message re-tick it. Never route around it with a raw
+  `git commit`; the latch guards the record, not the work.