plumbbob 0.8.10 → 0.8.12

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -23,6 +23,31 @@ Ridgeline runs large, settled work autonomously without you, PlumbBob keeps you
 driver's seat for the work your judgment has to steer. This repository was built using
 PlumbBob, dogfooded on its own loop.
 
+## What a prompt can't replicate
+
+A system prompt can *ask* a model to plan first and stop for review. What it can't do is
+**hold the line when the model doesn't** — and that mechanical half is what PlumbBob adds
+under the skills. Five deterministic edges, enforced by the CLI and git rather than by the
+model's goodwill:
+
+- **A gate that refuses red.** `checkpoint` won't record a step while the check gate is
+  red, and `start` refuses a dirty tree — the [checkride](https://www.npmjs.com/package/checkride)
+  run (types, lint, tests, dead code, docs) has to pass before a step lands.
+- **One SHA per verified step.** Every approved step is its own git commit against a
+  recorded baseline — a ledger of checkpoints, not one undifferentiated diff at the end.
+- **A preservation-aware revert.** `/pb-revert` resets exactly to a recorded checkpoint
+  SHA while keeping your plan and notes intact, and restores *only* SHAs the loop wrote.
+- **A build record that rides the PR.** The tracked `builds/<slug>/` folder — intent, log,
+  checkpoints, report — merges into `main` with the branch instead of dying with the
+  worktree; the archive never destroys.
+- **The approval latch.** `checkpoint` refuses to land a step until the harness records a
+  human turn since that step began ([D64–D66](docs/decisions.md#d64), the ledger-plane
+  enforcement), so the model can't self-commit past you — the refusal *is* the pause.
+
+The planning surface is the on-ramp; these five are the floor under it. And the latch's
+payoff is [measured, not asserted](#why-not-just), not just claimed. **Guidance on the
+work, a latch on the record.**
+
 ## The loop in one picture
 
 <p align="center">
@@ -196,11 +221,10 @@ diff, and `/pb-verify` reads it like any other.
 
 **…use git and a TODO file?** That's the honest skeleton, and if your discipline
 holds by willpower alone, it may be all you need. What the CLI adds is the
-mechanical half of the discipline, so willpower is spent only at the pause: a
-recorded baseline, one SHA per verified step, a revert that returns exactly to
-those SHAs while preserving your notes, an archive that never destroys, and a
-dashboard re-injected into every skill so the model re-orients on each move
-without you re-explaining the state.
+[mechanical half of the discipline](#what-a-prompt-cant-replicate) — the five edges up
+top — so willpower is spent only at the pause. The one not on that list: a status
+dashboard re-injected into every skill, so the model re-orients on each move without you
+re-explaining the state.
 
 **…wait for a vendor to ship this natively?** They're converging on it — plan
 modes, spec kits, native checkpoints — and that convergence is evidence *for* the
@@ -220,26 +244,28 @@ control, because a determined model routes around it and a denial mid-thought le
 legal move. But the **record** is a different plane, and there the tick *is* latched
 ([D64–D66](docs/decisions.md#d64)): `checkpoint` refuses to land a step until the harness
 records a human turn since that step began, so the agent cannot self-commit past you —
-the refusal simply *is* the pause. That extends the deterministic edge PlumbBob already
-holds — `checkpoint` refuses a red check, `start` refuses a dirty tree, `revert` restores
-only recorded SHAs — to the one boundary the product is named after, while leaving human
-what must be human: you, reading the diff. **Guidance on the work, a latch on the
-record.** And when a raw commit does slip the ledger, `status` says so and the checkpoint
-record makes recovery one command — cheap recovery, not a cage, is the control that
-matters.
+the refusal simply *is* the pause. It extends the [deterministic edges above](#what-a-prompt-cant-replicate)
+to the one boundary the product is named after, while leaving human what must be human:
+you, reading the diff. And when a raw commit does slip the ledger, `status` says so and the
+checkpoint record makes recovery one command — cheap recovery, not a cage, is the control
+that matters.
 
 > The latch's payoff is measured, not asserted: the skill-eval harness
 > ([`test/evals/`](test/evals/)) sweeps this loop headless — prose-only baseline vs. the
 > shipped latch, N=5 per contract, every assertion a mechanical read of git state — and
-> commits the receipt to [`research/evals/`](research/evals/2026-07-11.md). The first sweep
-> (opus, 2026-07-11): the latch closes the route it owns — *no checkpoint over a red
-> check under pressure* went from **2/5 prose-only to 5/5 latched** — while the honest
-> numbers it also surfaced (park capture 0/5, and adversarial pressure consistently
-> flipping the `auto` standing grant in settings — a legal, model-writable side door)
-> are the next iteration's work, named in the report rather than papered over. The
-> current sweep ([opus, 2026-07-18](research/evals/2026-07-18.md), plumbbob 0.8.7)
-> reproduces the win — *no checkpoint over a red check* still holds **5/5 latched** —
-> and confirms both gaps stand at 0.8.7, now the target of the hardening build.
+> commits each receipt under [`research/evals/`](research/evals/). The first sweep
+> ([opus, 2026-07-11](research/evals/2026-07-11.md)) closed the route the latch owns —
+> *no checkpoint over a red check under pressure* went from **2/5 prose-only to 5/5
+> latched** — and named, rather than papered over, the two honest gaps it surfaced: park
+> capture at 0/5, and adversarial pressure flipping a standing `auto` grant a model could
+> write into settings, a legal side door. The re-sweep
+> ([opus, 2026-07-18](research/evals/2026-07-18.md), plumbbob 0.8.7) reproduced the win —
+> *no checkpoint over a red check* still **5/5 latched** — and pinned both gaps. The side
+> door is now closed by construction: [D67](docs/decisions.md#d67) (self-approval is
+> human-typed only) retired the settings `auto` grant, so the one approval a model could
+> forge is gone. What remains is park capture (c5) — prose-governed by design
+> ([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13)), the guidance-only gap the
+> latch was never built to reach, still ~0/5 and labeled as such.
 
 ## Documentation
 

package/dist/lib/commitmsg.js

@@ -0,0 +1,72 @@
+// Conventional-Commit subject assembly (D68). Plumbbob's commit subjects read as
+// `type(scope): description` — real feat/fix/chore types and a real parenthesised
+// scope — so `git log` speaks the same grammar as the rest of the branch. The
+// `plumbbob`/`step N` identifiers that used to prefix the subject (the old D34
+// shape) now ride a marker line at the head of the body, which `withMarker`
+// prepends — so `git log --grep plumbbob` still finds every plumbbob commit.
+// Functional/procedural, node-builtins-only (C1/C2), no gate: these only shape a
+// string the CLI is about to commit.
+// The Conventional-Commit type vocabulary plumbbob recognises as a leading prefix
+// on a step title. Anchoring on this closed set keeps a prose title like
+// `Note: rewire the cache` from being misread as a `Note` type — only these words,
+// immediately followed by an optional `(scope)`, an optional `!`, and a colon,
+// count as an author-supplied prefix.
+const TYPES = ['feat', 'fix', 'chore', 'docs', 'refactor', 'test', 'perf', 'build', 'ci', 'style', 'revert'];
+const PREFIX = new RegExp(`^(${TYPES.join('|')})(?:\\(([^)]+)\\))?(!)?:\\s+(.+)$`);
+// Split an optional Conventional prefix off a step title. `feat(escape-hatch): add
+// the flag` → { type:'feat', scope:'escape-hatch', breaking:false, description:'add
+// the flag' }. A title with no recognised prefix comes back whole as the
+// description with a null type/scope — the caller then defaults the type and fills
+// the scope from the build.
+export function parseConventionalTitle(title) {
+    const m = PREFIX.exec(title.trim());
+    if (m === null) {
+        return { type: null, scope: null, breaking: false, description: title.trim() };
+    }
+    return { type: m[1] ?? null, scope: m[2] ?? null, breaking: m[3] === '!', description: (m[4] ?? '').trim() };
+}
+// Assemble a `type(scope)!: description` subject, omitting the `(scope)` segment
+// when there is no scope (Conventional Commits allow a bare `type: description`)
+// and the `!` when the change is not breaking.
+export function conventionalSubject(parts) {
+    const scope = parts.scope ? `(${parts.scope})` : '';
+    const bang = parts.breaking ? '!' : '';
+    return `${parts.type}${scope}${bang}: ${parts.description}`;
+}
+// A Conventional subject from a step title, filling gaps from the build. An
+// author-written prefix (`fix(parser): …`) is honoured verbatim — its type, scope,
+// breaking marker, and exact wording all win. A bare prose title defaults to
+// `defaultType` and the build `scope`, and gets its sentence-case opener
+// de-capitalised (`Add the flag` → `add the flag`) to match Conventional style —
+// while an all-caps acronym start (`API`, `OAuth`) is left alone.
+export function subjectFromTitle(title, defaultType, scope) {
+    const parsed = parseConventionalTitle(title);
+    if (parsed.type !== null) {
+        return conventionalSubject({
+            type: parsed.type,
+            scope: parsed.scope ?? scope,
+            breaking: parsed.breaking,
+            description: parsed.description,
+        });
+    }
+    return conventionalSubject({ type: defaultType, scope, description: lowerFirst(parsed.description) });
+}
+// Prepend a marker line (`plumbbob step 1`, `plumbbob plan`, `plumbbob finish`) to
+// an optional body, separated by a blank line so git keeps them as distinct
+// paragraphs. Always returns at least the marker, so every plumbbob commit carries
+// the greppable identifier in its body even when the prose is empty.
+export function withMarker(marker, body) {
+    const rest = body?.trim();
+    return rest !== undefined && rest.length > 0 ? `${marker}\n\n${rest}` : marker;
+}
+// De-capitalise a sentence-case opener but leave an acronym/proper all-caps start
+// (`API`, `OAuth`) intact: lowercase the first character only when it is uppercase
+// and the second character is not (so `Add` → `add`, but `API` stays `API`).
+function lowerFirst(text) {
+    const a = text[0] ?? '';
+    const b = text[1] ?? '';
+    if (a >= 'A' && a <= 'Z' && b >= 'A' && b <= 'Z') {
+        return text;
+    }
+    return a >= 'A' && a <= 'Z' ? a.toLowerCase() + text.slice(1) : text;
+}

package/dist/lib/sidecar.js

@@ -40,6 +40,18 @@ export function slugify(title) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+// The Conventional-Commit scope for a build (D68): its slug with the `YYYY-MM-DD-`
+// date prefix `start` prepends stripped off, so `2026-07-18-escape-hatch` yields the
+// human-meaningful `escape-hatch`. Null when no build resolves (`--local`, or a slug
+// that is nothing but a date) — the caller then omits the `(scope)` segment, which
+// Conventional Commits permit.
+export function buildScope(slug) {
+    if (slug === null) {
+        return null;
+    }
+    const stripped = slug.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+    return stripped.length > 0 ? stripped : null;
+}
 // Existing build slugs — the directory names under `builds/`, sorted. Empty when
 // `builds/` is absent (a `--local` repo, or before the first tracked `start`).
 export function listBuilds(root) {

package/dist/verbs/checkpoint.js

@@ -9,11 +9,12 @@
 // the same way.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { buildFolder, buildLogPath, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { checkLatch } from "../lib/latch.js";
-import { markStepDone, parseSteps, parseTitle } from "../lib/orient.js";
+import { markStepDone, parseSteps } from "../lib/orient.js";
 import { parseStepSeam, scopeDrift } from "../lib/intent.js";
+import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
 export async function checkpoint(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -53,7 +54,7 @@ export async function checkpoint(cwd, args) {
     if (isDirty(root)) {
         stageAll(root);
         warnScopeDrift(root, step);
-        const body = bodyArg(args) ?? fallbackBody(root, step);
+        const body = withMarker(`plumbbob step ${step}`, bodyArg(args) ?? fallbackBody(root, step));
         sha = commit(root, messageArg(args) ?? subjectForStep(root, step), body);
     }
     else {
@@ -71,12 +72,12 @@ export async function checkpoint(cwd, args) {
     return 0;
 }
 // The plan-approval commit (D36): stage only the active build's artifact folder and
-// commit it as `plumbbob: plan — <title>`, then record a `plan <sha>` line. Giving
+// commit it as `chore(<scope>): plan` (D68), then record a `plan <sha>` line. Giving
 // the plan its own commit keeps the first step's diff from absorbing the scaffold, so
 // `git log` reads baseline → plan → steps. No check gate (there is no code work to
 // verify yet), no intent flip, no step markers — the plan lives entirely in DESIGN.
-// An optional `--body` (stdin heredoc, D34) rides along; the folder is whitelisted
-// artifact plane, so there is no scope-drift to warn about.
+// An optional `--body` (stdin heredoc, D68) rides after the `plumbbob plan` marker;
+// the folder is whitelisted artifact plane, so there is no scope-drift to warn about.
 function checkpointPlan(root, args) {
     // The latch (D64) covers the plan commit too, keyed on the TICK that `start`
     // stamped: the plan pause is a pause. No step number — a range grant does not
@@ -87,7 +88,7 @@ function checkpointPlan(root, args) {
         return 1;
     }
     stagePath(root, buildFolder(root));
-    const sha = commit(root, planSubject(root), bodyArg(args) ?? undefined);
+    const sha = commit(root, planSubject(root), withMarker('plumbbob plan', bodyArg(args) ?? undefined));
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
     // The plan landing consumes `start`'s entry stamp (D64): a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
@@ -95,17 +96,11 @@ function checkpointPlan(root, args) {
     process.stdout.write(`plumbbob: plan committed — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`);
     return 0;
 }
-// The plan commit's CLI-owned subject: the intent's `# <title>`, else a bare
-// `plumbbob: plan` when the title can't be read (mirrors `subjectForStep`'s fallback).
+// The plan commit's CLI-owned subject (D68): `chore(<scope>): plan`, the scope drawn
+// from the active build's slug (a bare `chore: plan` when none resolves). The
+// `plumbbob plan` identifier rides the body marker, not the subject.
 function planSubject(root) {
-    let title = null;
-    try {
-        title = parseTitle(readFileSync(intentPath(root), 'utf8'));
-    }
-    catch {
-        title = null;
-    }
-    return title ? `plumbbob: plan — ${title}` : 'plumbbob: plan';
+    return conventionalSubject({ type: 'chore', scope: buildScope(activeBuild(root)), description: 'plan' });
 }
 // Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
 // intent.md. Returns null when none can be determined. A `-m` value is a message,
@@ -209,12 +204,18 @@ function statsSuffix(root, step) {
     }
     return parts.length > 0 ? parts.join(', ') : null;
 }
-// The CLI-owned, deterministic commit subject: the step's title when intent.md still
-// carries one, else the bare `plumbbob: step N done` fallback (D34 — the CLI owns the
-// subject; a `-m` override or `--body` prose is a separate concern).
+// The CLI-owned, deterministic commit subject (D68): a Conventional `type(scope):
+// description`. The scope comes from the active build's slug; the type and wording
+// come from the step's title — an author-written prefix (`fix(parser): …`) is honoured
+// verbatim, a bare title defaults to `feat`. A titleless step falls back to
+// `chore(<scope>): checkpoint`. The `plumbbob`/`step N` identifiers ride the body
+// marker, not the subject; a `-m` override or `--body` prose is a separate concern.
 function subjectForStep(root, step) {
+    const scope = buildScope(activeBuild(root));
     const title = titleForStep(root, step);
-    return title ? `plumbbob: step ${step} — ${title}` : `plumbbob: step ${step} done`;
+    return title !== null && title.trim().length > 0
+        ? subjectFromTitle(title, 'feat', scope)
+        : conventionalSubject({ type: 'chore', scope, description: 'checkpoint' });
 }
 function titleForStep(root, step) {
     try {

package/dist/verbs/finish.js

@@ -1,15 +1,16 @@
-// `plumbbob finish` (D9/D34) — the close-out: append the checkpoint SHAs to the
+// `plumbbob finish` (D9/D68) — the close-out: append the checkpoint SHAs to the
 // report, make the final commit, and clear the control state. The build folder is
 // NOT deleted — it IS the archive now (D29): tracked, it merges with the branch and
 // shows up in the PR, so nothing is copied into a local-only `archive/` (that
 // helper retired with this step). No refuse-without-report gate — guidance offers
 // the artifact, it does not wall the exit (D9). Git footprint stays additive (C5):
-// one forward commit under the greppable `plumbbob: finish — <title>` subject.
+// one forward commit under the Conventional `chore(<scope>): finish` subject, its
+// `plumbbob finish` identifier riding the body marker (D68).
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
-import { checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
-import { parseTitle } from "../lib/orient.js";
+import { buildScope, checkpointsPath, clearTick, hasSession, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
+import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -33,7 +34,7 @@ export function finish(cwd, args = []) {
     if (isDirty(root)) {
         stageAll(root);
     }
-    const sha = commit(root, subject(root, slug), bodyArg(args) ?? undefined);
+    const sha = commit(root, subject(slug), withMarker('plumbbob finish', bodyArg(args) ?? undefined));
     // Clear the control state: the in-flight markers first, then the session sentinel
     // last (so "no session" flips exactly at the end). Deleting STATE also drops the
     // cursor (D28) — cursor and session share the one file now, so a single delete does
@@ -53,18 +54,12 @@ export function finish(cwd, args = []) {
         'Run `/pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
     return 0;
 }
-// The CLI-owned final-commit subject (D34): `plumbbob: finish — <title>`, mirroring
-// the step-checkpoint format exactly so one greppable shape spans the whole history.
-// Falls back to a bare `plumbbob: finish` when intent.md carries no title.
-function subject(root, slug) {
-    let title = null;
-    try {
-        title = parseTitle(readFileSync(intentPath(root, slug), 'utf8'));
-    }
-    catch {
-        title = null;
-    }
-    return title ? `plumbbob: finish — ${title}` : 'plumbbob: finish';
+// The CLI-owned final-commit subject (D68): `chore(<scope>): finish`, the scope drawn
+// from the build's slug (a bare `chore: finish` when none resolves, e.g. `--local`),
+// mirroring the plan/step Conventional shape so one grammar spans the whole history.
+// The `plumbbob finish` identifier rides the body marker, not the subject.
+function subject(slug) {
+    return conventionalSubject({ type: 'chore', scope: buildScope(slug), description: 'finish' });
 }
 // `--body` reads the final-commit body from stdin (the single-quoted heredoc of
 // D34), so the pb-finish skill can compose a proportional close-out message. Returns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "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",

package/skills/pb-finish/SKILL.md

@@ -29,8 +29,9 @@ 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>`,
-   with an optional proportional body via `--body` (the stdin heredoc) — then
+   report and makes the final commit — subject `chore(<scope>): finish`, its body
+   led by a `plumbbob finish` marker plus an optional proportional `--body` (the
+   stdin heredoc) — then
    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.

package/skills/pb-plan/SKILL.md

@@ -74,6 +74,13 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    sharpened just-in-time when you reach them with `/pb-step`. Keep each small enough to
    verify in one review pass.
 
+   **Give the title a Conventional-Commit type where the change has one** *(optional)*:
+   a `<title>` that opens with `fix:`, `feat(escape-hatch):`, `chore:`, … becomes the
+   checkpoint's commit subject verbatim (its scope and breaking `!` honored) — this is
+   how each step lands a *real* `feat`/`fix`/`chore` in `git log`. Skip the prefix and
+   the checkpoint defaults the type to `feat` and draws the scope from the build slug, so
+   a plain title still yields a clean `feat(<slug>): <title>` ([D68](../../docs/decisions.md#d68)).
+
    **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.
@@ -106,7 +113,8 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    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
+   `chore(<scope>): plan` (with a `plumbbob plan` body marker), only `.plumbbob/builds/<slug>/`,
+   a `plan <sha>` line in
    `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

package/skills/pb-step/SKILL.md

@@ -39,8 +39,11 @@ grew — but its everyday job is to sharpen, not to invent.
    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.
+   `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Give the
+   `<title>` an optional Conventional-Commit prefix (`fix:`, `feat(scope):`, …) when the
+   change has a clear type — it becomes the checkpoint's commit subject; a plain title
+   defaults to `feat` with the build slug as scope ([D68](../../docs/decisions.md#d68)).
+   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)*. 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

package/skills/pb-verify/SKILL.md

@@ -47,10 +47,11 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    the human is the clock. Never checkpoint without it.
 6. **Checkpoint** *(only after approval)*. Run `plumbbob checkpoint`: it makes the WIP
    commit, records the SHA, flips the step to done, appends the step to the build-log's
-   `## Log`, and returns to DESIGN. The CLI owns the commit **subject**
-   (`plumbbob: step N — <title>`); you own the **body**. Compose a body *proportional to
-   the step* — a one-liner for a trivial change, a short paragraph on the what/why for a
-   meatier one — and pass it on stdin:
+   `## Log`, and returns to DESIGN. The CLI owns the commit **subject** — a Conventional
+   `<type>(<scope>): <description>` composed from the step title and the build slug — and
+   leads the **body** with a `plumbbob step N` marker; you own the rest of the **body**.
+   Compose a body *proportional to the step* — a one-liner for a trivial change, a short
+   paragraph on the what/why for a meatier one — and pass it on stdin:
 
    ```bash
    plumbbob checkpoint <n> --body <<'BODY'

package/templates/intent.md

@@ -50,11 +50,13 @@ which `/pb-build` records in the build folder's `SEAM` for orientation — aware
 An optional **model** line recommends the smallest model that can carry the step —
 mechanical work runs fine on a small model; subtle or creative work earns a frontier
 one. Advisory for the human, never a gate; write it plain, no backticks (D62).
-Then drive `/pb-build` until done. Later steps may be fuzzier than the first;
-sharpen the next one just-in-time with `/pb-step` (empty input auto-syncs it), and use
-`/pb-refine` to repair the whole plan when a blocker rewrites it.)*
+A step title may open with a Conventional-Commit type (`fix:`, `feat(scope):`) — it
+becomes the checkpoint's commit subject; skip it and the subject defaults to `feat`,
+scoped by the build slug (D68). Then drive `/pb-build` until done. Later steps may be
+fuzzier than the first; sharpen the next one just-in-time with `/pb-step` (empty input
+auto-syncs it), and use `/pb-refine` to repair the whole plan when a blocker rewrites it.)*
 
-1. [ ] <step> — **done when:** <criterion, ideally a test or check result>
+1. [ ] feat: <step> — **done when:** <criterion, ideally a test or check result>
    - seam: `<file>`, `<file>`
    - model: <smallest that can carry it, e.g. sonnet — mechanical, fully specified>
 2. [ ] <step> — **done when:** <criterion>