plumbbob 0.6.6 → 0.8.3

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.6",
-  "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance, not enforcement.",
+  "version": "0.8.3",
+  "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

@@ -83,6 +83,24 @@ differs from the model you're running as, say so before implementing — the hum
    `--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.** 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,
+   but the *record* is latched on purpose.
+
+   **Then hand off with the next model.** Once the checkpoint lands on re-fire, close the
+   turn by citing where the loop now stands: the step you just completed and the next
+   undone step. If that next step carries a `- model:` recommendation (the plan's
+   smallest-model-that-fits call, echoed on `plumbbob status`'s `▸ next` line), **name
+   it** so the human knows which `/model` to select before firing `/pb-build` again — it
+   is what carries the plan's suggestion across a fresh context window, which inherits the
+   session model, not the plan's. No `- model:` line means any model will do. Guidance,
+   never a gate.
+
 ## `--auto` — let the agent be the clock (opt-in)
 
 `/pb-build --auto` is the explicit escape hatch when the human wants unattended
@@ -99,7 +117,10 @@ and approves in the human's place**, and it **chains**:
   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), a new decision is needed, no planned steps
-  remain, or the top of a requested range is reached.
+  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** — 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.
@@ -141,3 +162,12 @@ just the one more entry already in the halt list above.
   `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.** 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.
+- **Close with the next model.** When a step lands, cite the completed step and the next
+  undone step, and name that next step's `- model:` recommendation if it has one — it's
+  what a fresh context window needs to pick the right `/model` before re-firing.
+  Guidance, never a gate.

package/skills/pb-finish/SKILL.md

@@ -31,7 +31,8 @@ record.
 2. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
    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
+   clears the control state (the in-flight markers, then `STATE` last — one delete
+   drops both the session sentinel and the active-build cursor it carries). 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.
 

package/skills/pb-plan/SKILL.md

@@ -45,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
@@ -103,6 +107,19 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    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.** 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-verify/SKILL.md

@@ -62,6 +62,30 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    write in one breath. Omit `--body` entirely and the CLI writes a deterministic body
    (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.
+7. **Hand off with the next model** *(once the checkpoint lands)*. `plumbbob checkpoint`
+   prints `step N checkpointed … Back at the boundary` and returns to DESIGN. Close the
+   turn by citing where the loop now stands: the step you just completed and the **next
+   undone step** — its title and done-when. If that next step carries a `- model:`
+   recommendation (the plan's smallest-model-that-fits call, which `plumbbob status`
+   echoes on the `▸ next` line), **name it in the hand-off** so the human knows which
+   `/model` to select before firing `/pb-build` again. This matters most across a context
+   boundary: a fresh window inherits the *session's* model, not the plan's suggestion, so
+   this line is what carries the recommendation over. No `- model:` line means any model
+   will do — say nothing about it. Guidance, never a gate.
+
+## The latch makes the pause real
+
+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; 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
 
@@ -76,3 +100,11 @@ this skill verifies it the same way: **it reads the diff, not the author**.
 - **`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.** 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.
+- **Close with the next model.** After the checkpoint lands, cite the completed step
+  and the next undone step, and surface that next step's `- model:` recommendation when
+  it has one — it is the plan's smallest-model-that-fits call, and it's what a fresh
+  context window needs to pick the right `/model`. Guidance, never a gate.