plumbbob 0.2.3 → 0.3.0

package/dist/verbs/checkpoint.js

@@ -0,0 +1,83 @@
+// `plumbbob checkpoint [<n>] [-m <msg>]` — the executor-agnostic commit tick (D3).
+// Unlike v1 `done`, it does NOT require BUILD state or a STEP file: the step is
+// whatever you pass, else the in-flight STEP, else the next undone step in intent.
+// It gates on a green check, then commits any pending work (or records the existing
+// HEAD when the tree is already clean — the human's commit skill may have committed
+// first), records the SHA, flips the intent checkbox to `[x]`, clears any STEP/SEAM,
+// and returns to DESIGN. The diff's author is irrelevant: `/pb-build`, your hands,
+// a vibe session, or another harness all checkpoint the same way.
+import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { commit, findRepoRoot, headSha, isDirty, stageAll } from "../lib/git.js";
+import { checkpointsPath, hasSession, intentPath, seamPath, stepPath, writeState } from "../lib/sidecar.js";
+import { runCheck } from "../lib/check.js";
+import { markStepDone, parseSteps } from "../lib/orient.js";
+export function checkpoint(cwd, args) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const step = resolveStep(root, args);
+    if (step === null) {
+        process.stderr.write('plumbbob: no step to checkpoint — pass a number, or plan a step in intent.md first.\n');
+        return 1;
+    }
+    if (runCheck(root) !== 0) {
+        process.stderr.write('plumbbob: check failed (red) — checkpoint refuses on red. Fix it and re-run.\n');
+        return 1;
+    }
+    let sha;
+    if (isDirty(root)) {
+        stageAll(root);
+        sha = commit(root, messageArg(args) ?? `plumbbob: step ${step} done`);
+    }
+    else {
+        sha = headSha(root);
+    }
+    appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
+    flipIntent(root, step);
+    rmSync(seamPath(root), { force: true });
+    rmSync(stepPath(root), { force: true });
+    writeState(root, 'DESIGN');
+    process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. STATE=DESIGN.\n`);
+    return 0;
+}
+// Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
+// intent.md. Returns null when none can be determined.
+function resolveStep(root, args) {
+    const explicit = args.find((a) => /^\d+$/.test(a));
+    if (explicit !== undefined) {
+        return Number(explicit);
+    }
+    const inFlight = readStep(root);
+    if (inFlight !== null) {
+        return inFlight;
+    }
+    try {
+        return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => !s.done)?.n ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function flipIntent(root, step) {
+    try {
+        writeFileSync(intentPath(root), markStepDone(readFileSync(intentPath(root), 'utf8'), step));
+    }
+    catch {
+        // best-effort bookkeeping; the checkpoint SHA is the source of truth.
+    }
+}
+function messageArg(args) {
+    const i = args.indexOf('-m');
+    return i !== -1 && i + 1 < args.length ? (args[i + 1] ?? null) : null;
+}
+function readStep(root) {
+    try {
+        const raw = readFileSync(stepPath(root), 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/verbs/reset.js

@@ -0,0 +1,54 @@
+// `plumbbob reset` (D9) — the v2 close-out, replacing the v1
+// wrap → report → docs → finish ceremony. It archives intent + build-log + report
+// (the `/pb-reset` skill writes the report by default) under .plumbbob/archive/,
+// clears the active files, and deletes the control state (STATE last). Unlike v1
+// `finish` there is NO refuse-without-report gate — guidance offers the artifact, it
+// does not wall the exit. Archive-then-clear, never destroy (C4); git untouched (C5).
+import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { findRepoRoot } from "../lib/git.js";
+import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, stepPath } from "../lib/sidecar.js";
+import { archiveSession, reportPath } from "../lib/archive.js";
+export function reset(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    if (existsSync(reportPath(root))) {
+        appendCheckpointShas(root);
+    }
+    else {
+        process.stderr.write('plumbbob: note — no report.md found; archiving intent + build-log without one ' +
+            '(/pb-reset normally writes the report first). No gate (D9).\n');
+    }
+    const archived = archiveSession(root);
+    // Clear the active files — now safely archived — then the control state, STATE
+    // last so "no session" flips exactly at the end.
+    rmSync(intentPath(root), { force: true });
+    rmSync(buildLogPath(root), { force: true });
+    rmSync(reportPath(root), { force: true });
+    rmSync(seamPath(root), { force: true });
+    rmSync(stepPath(root), { force: true });
+    rmSync(join(sidecarDir(root), 'STATE'), { force: true });
+    process.stdout.write(`plumbbob: reset — archived to ${relative(root, archived)}. Sidecar cleared. ` +
+        'Run `/pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
+    return 0;
+}
+// Append the recorded checkpoints (baseline + each `step n <sha>`) to the report so
+// the archived report lists the SHAs.
+function appendCheckpointShas(root) {
+    let raw = '';
+    try {
+        raw = readFileSync(checkpointsPath(root), 'utf8');
+    }
+    catch {
+        raw = '';
+    }
+    const lines = raw
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .map((l) => `- ${l}`);
+    appendFileSync(reportPath(root), ['', '## Checkpoints', '', ...lines, ''].join('\n'));
+}

package/dist/verbs/setup.js

@@ -24,7 +24,7 @@ import { join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findRepoRoot } from "../lib/git.js";
 import { mergeRegistration, readSettings, stripRegistration, writeSettings } from "../lib/settings.js";
-const HOOK_FILES = ['pre-edit.sh', 'bash-guard.sh', 'post-edit.sh'];
+const HOOK_FILES = ['post-edit.sh'];
 // The placeholder every skill carries in place of its `plumbbob` invocation;
 // setup substitutes it with the form the chosen install shape resolves.
 const BIN_PLACEHOLDER = '__PLUMBBOB_BIN__';

package/dist/verbs/status.js

@@ -1,13 +1,32 @@
-// `plumbbob status` — print the session state, or NO ACTIVE SESSION. Read-only,
-// always exits 0. Skills pre-inject this output to gate their own behavior.
+// `plumbbob status` — the orientation dashboard (D8/D15), or NO ACTIVE SESSION.
+// Read-only, always exits 0. Skills pre-inject this output to gate their own
+// behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
+import { readFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, readState } from "../lib/sidecar.js";
+import { buildLogPath, checkpointsPath, hasSession, intentPath, readState, stepPath } from "../lib/sidecar.js";
+import { formatOrientation, orient } from "../lib/orient.js";
+function readOr(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
 export function status(cwd) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
         process.stdout.write('NO ACTIVE SESSION\n');
         return 0;
     }
-    process.stdout.write(`STATE: ${readState(root) ?? 'UNKNOWN'}\n`);
+    const inFlightRaw = readOr(stepPath(root)).trim();
+    const orientation = orient({
+        state: readState(root) ?? 'UNKNOWN',
+        intent: readOr(intentPath(root)),
+        buildLog: readOr(buildLogPath(root)),
+        checkpoints: readOr(checkpointsPath(root)),
+        inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
+    });
+    process.stdout.write(`${formatOrientation(orientation)}\n`);
     return 0;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
-  "version": "0.2.3",
-  "description": "Attention-first build process: a CLI + hooks that enforce the deciding/executing boundary.",
+  "version": "0.3.0",
+  "description": "Attention-first build process: eight skills + a CLI that keep you the decider — guidance, not enforcement.",
   "keywords": [
     "claude-code",
     "claude",

package/skills/pb-build/SKILL.md

@@ -1,19 +1,49 @@
 ---
 name: pb-build
-description: Human-triggered driver for `plumbbob build <n>` — write the SEAM for a step and enter BUILD (edits unlocked to those paths only), from the chat.
+description: The optional engine — read the current planned step from intent, implement it (its done-when, seam, Decisions, Constraints), then verify it through to the approval pause. Skip it entirely to implement by hand, vibed, or with another harness.
 disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ build:*)
+model: opus
+allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ build:*), Bash(__PLUMBBOB_BIN__ check:*), Bash(__PLUMBBOB_BIN__ checkpoint:*), Bash(git diff:*)
 ---
 
-# Plumbbob — build a step (driver)
+# Plumbbob — build a step (the optional engine)
 
 Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
 
-This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob build` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+This is the **bundled executor** — one way to turn a planned step into code. It is
+**optional** (D3): 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.
 
-## What it does
+## What this skill does, in order
 
-1. Read the step number from the way you were invoked (e.g. `/pb-build 3` → step `3`). If no number is present, ask for one and run nothing.
-2. Run `__PLUMBBOB_BIN__ build <n>` via Bash.
-3. Report the verb's output verbatim — the SEAM it wrote and the new state, or any refusal.
+1. **Pick the step.** Use the number you were invoked with (e.g. `/pb-build 4`), else
+   the next undone, planned step in `.plumbbob/intent.md`. If there is no planned step
+   to build, stop and tell the human to `/pb-step` first.
+2. **Enter the step.** Run `__PLUMBBOB_BIN__ build <n>` (records the in-flight STEP +
+   SEAM so `/pb-status` shows the step in flight; in v2 the seam is awareness, not a
+   lock).
+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.
+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 `/pb-park`, **not** an
+   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.
+5. **Verify, through to the pause.** Run the verify tick exactly as `/pb-verify`
+   does: `__PLUMBBOB_BIN__ check` → self-review the diff against the done-when, the
+   Decisions, and the Constraints (a single structured read, D16) → validate → **PAUSE
+   for the human's approval** → only on approval, checkpoint with
+   `__PLUMBBOB_BIN__ checkpoint`. Do **not** bump the version or changelog — that is
+   the human's `/version` call.
+
+## The hard contracts
+
+- **Optional, never required.** The loop works without this skill; `/pb-verify`
+  checkpoints a hand-built or vibed diff just the same (D3).
+- **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.
+- **Always end at the pause.** Implement → verify → wait for approval. Never
+  checkpoint without it; the human is the clock.

package/skills/pb-harvest/SKILL.md

@@ -0,0 +1,47 @@
+---
+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_BIN__ status:*)
+---
+
+# Plumbbob — harvest the park list
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+`/pb-harvest` is the complement of `/pb-park` (D7): you parked ideas as seeds during a
+build; now, at a boundary, you harvest them — decide what each one is.
+
+## When to run it — wrong-state refusal
+
+Harvest at a **step boundary**: after a step is checkpointed and you are back in
+DESIGN, not mid-step. Read the state injected above:
+
+- `NO ACTIVE SESSION` — **refuse**; tell the human to `plumbbob start "<title>"` first.
+- `BUILD` — a step is in flight; **refuse** and suggest finishing it with `/pb-verify`
+  before harvesting. Chasing parked items mid-step is the disease parking prevents.
+- `DESIGN` (and other settled states) — go ahead.
+
+## What this skill does
+
+Walk the **Park list** in `build-log.md` item by item and, for each, **propose exactly
+one class**:
+
+- **blocker** — the plan was wrong or incomplete; can't proceed. Folds into `intent.md`
+  and is handled now.
+- **tangent** — a different path, not clearly better. **The default** — defer or kill.
+- **pivot signal** — real evidence the whole approach is wrong. Stop and replan.
+
+## The one hard contract
+
+You **propose**; the **human calls it**. For each item, state your proposed class and
+one line of reasoning, then **wait for the human to confirm or override**. Write
+**only after** per-item confirmation:
+
+- Record each confirmed class in `build-log.md`'s `## Harvest` section.
+- **Flip the harvested item** from `- [ ]` to `- [x]` in the Park list, so `/pb-status`
+  stops counting it as open.
+- A confirmed **blocker** also folds its decision into `intent.md`.
+- Never reclassify or resolve an item the human hasn't confirmed, and default every
+  uncertain item to **tangent**, never to blocker.

package/skills/pb-park/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: pb-park
+description: Compose one tidy tagged park line, get the human's OK in-turn, then capture it by shelling `plumbbob park` — never by editing a file. The capture half of the park/harvest loop.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ park:*)
+---
+
+# Plumbbob — park an idea (capture, don't chase)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+`/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
+it — is the whole point: it protects the step in flight.
+
+## Wrong-state refusal
+
+Parking needs an **active session** to capture into. Read the state injected above: if
+it is `NO ACTIVE SESSION`, **refuse** and tell the human to run `plumbbob start
+"<title>"` first. Every active state (`DESIGN`, `BUILD`, `SPIKE`, `FINISH`) is fine —
+capture is always available, which is the whole point of parking.
+
+## What this skill does
+
+Take the idea, problem, or "ooh what if" the human just had and **compose it into one
+tidy, tagged line** — short, legible, self-contained, so it still reads cleanly weeks
+later. Then:
+
+1. **Show the composed line to the human** and wait for **in-turn approval** — they
+   confirm it as-is or edit the wording.
+2. **Only after** that approval, capture it by running `__PLUMBBOB_BIN__ park "<the
+   approved line>"` via Bash.
+
+## The one hard contract
+
+The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and
+no Write tool** on purpose: you may not append to `build-log.md` yourself. Compose, get
+approval, then shell `__PLUMBBOB_BIN__ park` — that is the only write path. If approval
+never comes, capture nothing.

package/skills/pb-plan/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pb-plan
+description: Frame a fresh goal — scaffold the session and author the intent's Frame, Decisions, and Constraints before any code. Steps stay empty; they come one at a time from /pb-step.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ start:*)
+---
+
+# Plumbbob — frame a goal (the whole-goal move)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+`/pb-plan` is the **whole-goal** move — it opens a session and gets the deciding out
+of your head and onto `intent.md` *before* any code. (Planning a single increment is
+the separate `/pb-step` move; do not confuse the two.)
+
+## What this skill does
+
+1. **Scaffold.** If there is no active session, run `__PLUMBBOB_BIN__ start "<title>"`
+   to create `.plumbbob/` (STATE=DESIGN, baseline recorded). If a session already
+   exists, say so and edit the existing `intent.md` rather than starting over.
+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
+   the human decides every line.
+3. **Decisions & Constraints.** Record the settled calls (one line each, with the
+   *because*) and the hard rules the build must honor. An unresolved hole goes to
+   **Open questions**, never guessed into a Decision.
+4. **Leave `## Steps` empty.** Steps are planned just-in-time (D6) — one at a time
+   with `/pb-step` — so do not write the build plan here.
+
+## The hard contracts
+
+- **Deciding before code.** `/pb-plan` writes `intent.md` only — never source.
+- **The human converges.** You surface options and draft wording; the human picks.
+  An unresolved hole is an Open question, not a guessed Decision.
+- **Size to the work.** A small change fills Frame + a couple of Decisions and stops;
+  ceremony on a one-liner is the failure mode, not thoroughness.

package/skills/pb-reset/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: pb-reset
+description: Close out the build — write the report (what shipped, decisions, parked/harvested items, deferred tangents), then archive intent + build-log + report and clear for a fresh goal. Report by default, no gate.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Write, Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ reset:*)
+---
+
+# Plumbbob — reset for a new goal (the close-out)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+`/pb-reset` ends the build: it captures what happened, archives it, and clears the
+sidecar for the next goal. **Report by default** (D9) — no refuse-without-report gate,
+and no separate docs phase.
+
+## What this skill does, in order
+
+1. **Write the report** to `.plumbbob/report.md`, from `intent.md` + `build-log.md`:
+   - **What shipped** — the steps completed and what they delivered.
+   - **Decisions and why** — the settled calls that shaped the build.
+   - **Parked & harvested** — what was captured and how each was classified.
+   - **Final status** — done or partial, and what is left.
+   - **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. **Archive & clear.** Run `__PLUMBBOB_BIN__ reset`, which appends the checkpoint SHAs
+   to the report, archives intent + build-log + report to
+   `.plumbbob/archive/<date>-<slug>/`, and clears the sidecar (STATE last). Git is not
+   touched.
+3. **Point at the next goal** — `/pb-plan` to frame the next one.
+
+## The hard contracts
+
+- **Report by default, never a gate.** Always offer the report; never wall the exit. A
+  bug fix's report can be three lines — size it to the work.
+- **Archive-then-clear, never destroy** (C4). The archive is the record; the active
+  files only clear once they are safely copied.
+- **No version bump, no docs phase.** Updating real docs is a separate, explicit ask;
+  cutting a release is the human's `/version`.

package/skills/pb-status/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: pb-status
+description: Show the orientation dashboard — where you are, what's done, what's parked, and the next move. A thin trigger for `plumbbob status`.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*)
+---
+
+# Plumbbob — orient (the where-am-I move)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **thin driver** for `__PLUMBBOB_BIN__ status`. The dashboard above is your
+orientation — the intent, the step list, the parked/open-question counts, and the
+inferred next move. Report it verbatim and point the human at that next move. This
+skill carries **no Edit and no Write tool**: the CLI is the source of truth, so
+**never retry**, and never edit a file to change what the orientation says.
+
+## 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.

package/skills/pb-step/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: pb-step
+description: Plan the next increment — propose one small step with a done-when criterion and a seam, get the human's OK, and append it to intent's ## Steps. One by default; several only if the human already knows them.
+disable-model-invocation: true
+model: opus
+allowed-tools: Read, Edit, Bash(__PLUMBBOB_BIN__ status:*)
+---
+
+# Plumbbob — plan the next step (the single-increment move)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+`/pb-step` plans the **next increment** just-in-time (D6) — the smallest verifiable
+piece of the framed goal, planned only when you reach it. (Framing the whole goal is
+the separate `/pb-plan` move.)
+
+## What this skill does
+
+1. **Read the plan.** Read `intent.md`'s Frame, Decisions, Constraints, and the steps
+   already done, to see what the *next* increment should be.
+2. **Propose one step.** Draft a single step:
+   - a one-line **title**,
+   - a **done-when** criterion — ideally a test or check result, something
+     `/pb-verify` can actually validate,
+   - a **seam**: the specific files it should touch (exact paths, or a `dir/` grant).
+   Keep it small enough to verify in one review pass.
+3. **Get the human's OK**, then **append** it to `## Steps` in the standard format —
+   `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Default
+   to **one** step; plan several only when the human already knows them.
+
+## The hard contracts
+
+- **One verifiable increment.** Each step carries a done-when `/pb-verify` can check
+  and a seam small enough to review in one pass.
+- **Append to `## Steps` only**, in the standard format `status` and `build` parse —
+  never the Roadmap, never loose prose.
+- **The human approves the step** before it lands. You propose; they decide.

package/skills/pb-verify/SKILL.md

@@ -0,0 +1,47 @@
+---
+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_BIN__ status:*), Bash(__PLUMBBOB_BIN__ check:*), Bash(__PLUMBBOB_BIN__ checkpoint:*), Bash(git diff:*), Bash(git status:*)
+---
+
+# Plumbbob — verify a step (the tick)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+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).
+
+## What this skill does, in order
+
+1. **Check.** Run `__PLUMBBOB_BIN__ check` (the heavy gate). If it comes back
+   **red**, stop here: report what failed and do **not** pause for approval — there
+   is nothing to approve yet. The human fixes it and re-invokes.
+2. **Self-review** *(a single structured read, D16)*. 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?
+   - the **Constraints** — are any violated?
+   Surface every mismatch plainly. You are reviewing, not building — do not fix anything.
+3. **Validate.** State, yes or no, whether the step's done-when is met, with the evidence.
+4. **PAUSE.** Present the check result, the self-review, and the validation, then
+   **stop and wait for the human's explicit approval.** This is the convergence beat;
+   the human is the clock. Never checkpoint without it.
+5. **Checkpoint** *(only after approval)*. Commit the work — the human's
+   commit-with-TIL skill for a rich message, or let `checkpoint` make the WIP commit
+   — then run `__PLUMBBOB_BIN__ checkpoint` to record the SHA, flip the step to done,
+   and return to DESIGN. Do **not** bump the version or touch the changelog — that is
+   the human's `/version` call.
+
+## 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
+  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.

package/dist/verbs/done.js

@@ -1,63 +0,0 @@
-// `plumbbob done` — the step gate. Refuses on a red check, then stages the whole
-// step (D8: `git add -A`; the sidecar is git-excluded so it never lands), warns
-// about anything committed outside the SEAM, takes the checkpoint commit, records
-// its SHA, and returns to DESIGN.
-import { appendFileSync, readFileSync, rmSync } from 'node:fs';
-import { commit, findRepoRoot, stageAll, stagedPaths } from "../lib/git.js";
-import { checkpointsPath, hasSession, readState, seamPath, stepPath, writeState } from "../lib/sidecar.js";
-import { runCheck } from "../lib/check.js";
-import { matchesSeam } from "../lib/intent.js";
-export function done(cwd) {
-    const root = findRepoRoot(cwd);
-    if (root === null || !hasSession(root)) {
-        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
-        return 1;
-    }
-    const state = readState(root);
-    if (state !== 'BUILD' && state !== 'REVIEW') {
-        process.stderr.write(`plumbbob: done runs from BUILD or REVIEW (current state is ${state ?? 'UNKNOWN'}). Run \`plumbbob build <n>\` first.\n`);
-        return 1;
-    }
-    const step = readStepNumber(root);
-    if (step === null) {
-        process.stderr.write('plumbbob: no in-flight step — run `plumbbob build <n>` first.\n');
-        return 1;
-    }
-    if (runCheck(root) !== 0) {
-        process.stderr.write('plumbbob: check failed (red) — done refuses on red. Fix it and re-run `done`.\n');
-        return 1;
-    }
-    stageAll(root);
-    const seam = readSeamTokens(root);
-    const outside = stagedPaths(root).filter((p) => !matchesSeam(p, seam));
-    if (outside.length > 0) {
-        process.stderr.write(`plumbbob: WARNING committed paths outside the SEAM: ${outside.join(', ')}. The checkpoint captures them, but scope drift may mean the plan needs revising.\n`);
-    }
-    const sha = commit(root, `plumbbob: step ${step} done`);
-    appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`);
-    rmSync(seamPath(root), { force: true });
-    rmSync(stepPath(root), { force: true });
-    writeState(root, 'DESIGN');
-    process.stdout.write(`plumbbob: step ${step} done — checkpoint ${sha.slice(0, 9)}. STATE=DESIGN.\n`);
-    return 0;
-}
-function readStepNumber(root) {
-    try {
-        const raw = readFileSync(stepPath(root), 'utf8').trim();
-        return /^\d+$/.test(raw) ? Number(raw) : null;
-    }
-    catch {
-        return null;
-    }
-}
-function readSeamTokens(root) {
-    try {
-        return readFileSync(seamPath(root), 'utf8')
-            .split('\n')
-            .map((l) => l.trim())
-            .filter((l) => l.length > 0);
-    }
-    catch {
-        return [];
-    }
-}

package/dist/verbs/finish.js

@@ -1,54 +0,0 @@
-// `plumbbob finish` (D19/D20) — the closing gate, symmetric with the step gate.
-// Refuses unless a report exists, appends the checkpoint SHA list to it, archives
-// intent + build-log + report under .plumbbob/archive/, clears the active files,
-// and deletes SEAM, STEP, then STATE LAST (deleting STATE is what switches the
-// muzzle off, so it happens exactly at session end). Never touches git (C5).
-import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import { findRepoRoot } from "../lib/git.js";
-import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, stepPath, } from "../lib/sidecar.js";
-import { archiveSession, reportPath } from "../lib/archive.js";
-export function finish(cwd) {
-    const root = findRepoRoot(cwd);
-    if (root === null || !hasSession(root)) {
-        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
-        return 1;
-    }
-    if (!existsSync(reportPath(root))) {
-        process.stderr.write('plumbbob: finish refuses without a report — run `/plumbbob-report` first (it writes .plumbbob/report.md). ' +
-            'The closing gate is symmetric with the step gate: you do not walk away without capturing what happened.\n');
-        return 1;
-    }
-    appendCheckpointShas(root);
-    const archived = archiveSession(root);
-    // Clear the active files — now safely archived.
-    rmSync(intentPath(root), { force: true });
-    rmSync(buildLogPath(root), { force: true });
-    rmSync(reportPath(root), { force: true });
-    // Delete the control files LAST, STATE the very last: while STATE exists the
-    // muzzle is live, so it comes off only once everything else is torn down.
-    rmSync(seamPath(root), { force: true });
-    rmSync(stepPath(root), { force: true });
-    rmSync(join(sidecarDir(root), 'STATE'), { force: true });
-    process.stdout.write(`plumbbob: finished — archived to ${relative(root, archived)}. STATE cleared (muzzle off). ` +
-        'Run `plumbbob start "<title>"` to begin the next task.\n');
-    return 0;
-}
-// Append the recorded checkpoints (baseline + each `step n <sha>`) to the report,
-// so the archived report lists the SHAs (spec: "finish lists the SHAs in the
-// report").
-function appendCheckpointShas(root) {
-    let raw = '';
-    try {
-        raw = readFileSync(checkpointsPath(root), 'utf8');
-    }
-    catch {
-        raw = '';
-    }
-    const lines = raw
-        .split('\n')
-        .map((l) => l.trim())
-        .filter((l) => l.length > 0)
-        .map((l) => `- ${l}`);
-    appendFileSync(reportPath(root), ['', '## Checkpoints', '', ...lines, ''].join('\n'));
-}