plumbbob 0.8.11 → 0.8.12

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.11",
+  "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/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.11",
+  "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>