plumbbob 0.8.13 → 0.8.14

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.8.13",
+  "version": "0.8.14",
   "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/intent.js

@@ -149,6 +149,26 @@ export function parseBuildTitle(content) {
     }
     return '';
 }
+const SCOPE_HEADER = /^\*\*Scope:\*\*\s*(.*)$/;
+const SCOPE_PLACEHOLDER = /^<.*>$/;
+// The build's default Conventional-Commit scope (D4): the `**Scope:**` header
+// field authored once at plan time, its value read verbatim off the line with any
+// trailing `<!-- ... -->` guidance note stripped. An unfilled placeholder — an
+// empty value or an angle-bracket placeholder like `<feature>` — parses as absent
+// (D7), so a freshly scaffolded, not-yet-edited build falls through to the next
+// scope rung (the build slug) rather than landing commits scoped `(<feature>)`.
+// null when the header is absent entirely — the pre-D4 shape (C2 back-compat).
+export function parseBuildScope(content) {
+    for (const line of content.split('\n')) {
+        const m = SCOPE_HEADER.exec(line.trim());
+        if (m === null) {
+            continue;
+        }
+        const value = (m[1] ?? '').split('<!--')[0]?.trim() ?? '';
+        return value === '' || SCOPE_PLACEHOLDER.test(value) ? null : value;
+    }
+    return null;
+}
 export function scrapeBullets(content, heading) {
     const lines = content.split('\n');
     const start = lines.findIndex((l) => l.trim() === heading);

package/dist/lib/orient.js

@@ -73,10 +73,11 @@ export function markStepDone(intent, n) {
     })
         .join('\n');
 }
-// Open questions still open: `- Q\d+:` lines that do not say "resolved".
+// Open questions still open: `- Q\d+:` openers that do not say "resolved". The
+// opener may carry a slug-at-birth gloss — `- Q2 (some-slug): ...` (D3) — which
+// the count reads through; sub-lines (`*plain:*`/`*lean:*`) never match.
 export function parseOpenQuestions(intent) {
-    return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+:/.test(l.trim()) && !/resolved/i.test(l))
-        .length;
+    return sectionLines(intent, '## Open questions').filter((l) => /^- Q\d+(?: \([^)]+\))?:/.test(l.trim()) && !/resolved/i.test(l)).length;
 }
 // Open parked items: `- [ ]` lines under `## Park list` (the `park` verb's format).
 // A harvested item is flipped to `- [x]` by `/pb-harvest` and no longer counts; the

package/dist/verbs/checkpoint.js

@@ -13,7 +13,7 @@ import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, check
 import { runCheck } from "../lib/check.js";
 import { checkLatch } from "../lib/latch.js";
 import { markStepDone, parseSteps } from "../lib/orient.js";
-import { parseStepSeam, scopeDrift } from "../lib/intent.js";
+import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
@@ -101,11 +101,12 @@ 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 (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.
+// The plan commit's CLI-owned subject (D68): `chore(<scope>): plan`, the scope
+// resolved through the build-default fallback chain (a bare `chore: plan` when
+// none resolves). The `plumbbob plan` identifier rides the body marker, not the
+// subject.
 function planSubject(root) {
-    return conventionalSubject({ type: 'chore', scope: buildScope(activeBuild(root)), description: 'plan' });
+    return conventionalSubject({ type: 'chore', scope: buildDefaultScope(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,
@@ -210,18 +211,36 @@ function statsSuffix(root, step) {
     return parts.length > 0 ? parts.join(', ') : null;
 }
 // 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.
+// description`. 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`.
+// The scope falls back through the chain (D3): the title's own `(scope)` wins
+// (handled inside `subjectFromTitle`), else `buildDefaultScope`. 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 scope = buildDefaultScope(root);
     const title = titleForStep(root, step);
     return title !== null && title.trim().length > 0
         ? subjectFromTitle(title, 'feat', scope)
         : conventionalSubject({ type: 'chore', scope, description: 'checkpoint' });
 }
+// The build-default Conventional scope (D3/D4): the `**Scope:**` header field in
+// intent.md when authored and filled, else the build slug (D68's original rung,
+// now the penultimate one), else null — a bare subject (C2 back-compat: a build
+// with neither field behaves exactly as before D4).
+function buildDefaultScope(root) {
+    try {
+        const fromHeader = parseBuildScope(readFileSync(intentPath(root), 'utf8'));
+        if (fromHeader !== null) {
+            return fromHeader;
+        }
+    }
+    catch {
+        // no intent.md yet — fall through to the slug rung.
+    }
+    return buildScope(activeBuild(root));
+}
 function titleForStep(root, step) {
     try {
         return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => s.n === step)?.title ?? null;

package/dist/verbs/finish.js

@@ -9,8 +9,9 @@
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
-import { buildScope, checkpointsPath, clearTick, hasSession, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
+import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
+import { parseBuildScope } from "../lib/intent.js";
 export function finish(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
@@ -34,7 +35,7 @@ export function finish(cwd, args = []) {
     if (isDirty(root)) {
         stageAll(root);
     }
-    const sha = commit(root, subject(slug), withMarker('plumbbob finish', bodyArg(args) ?? undefined));
+    const sha = commit(root, subject(root, 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
@@ -54,12 +55,27 @@ 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 (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' });
+// The CLI-owned final-commit subject (D68): `chore(<scope>): finish`, the scope
+// resolved through the same build-default fallback chain as plan/step subjects
+// (D3/D4): the `**Scope:**` header field, else the build slug, else bare (e.g.
+// `--local`). The `plumbbob finish` identifier rides the body marker, not the
+// subject.
+function subject(root, slug) {
+    return conventionalSubject({ type: 'chore', scope: buildDefaultScope(root, slug), description: 'finish' });
+}
+// See checkpoint.ts's twin of this helper (same fallback, this verb's own `slug`
+// resolution instead of the active-build cursor).
+function buildDefaultScope(root, slug) {
+    try {
+        const fromHeader = parseBuildScope(readFileSync(intentPath(root, slug), 'utf8'));
+        if (fromHeader !== null) {
+            return fromHeader;
+        }
+    }
+    catch {
+        // no intent.md — fall through to the slug rung.
+    }
+    return buildScope(slug);
 }
 // `--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.13",
+  "version": "0.8.14",
   "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-build/SKILL.md

@@ -74,6 +74,13 @@ differs from the model you're running as, say so before implementing — the hum
    build-log's `## Log`, so the history writes itself — you only supply the body (or omit
    `--body` for the deterministic done-when + seam + diffstat fallback). Do **not** bump
    the version or changelog — that is the human's `/version` call.
+   - **A drifted subject is reconciled at the pause, never silently (D5/D6).** The planned
+     title *is* the checkpoint subject (D1). If the diff drifted from it, **present** a
+     corrected subject at the pause — `planned title → proposed subject`, one line — for
+     explicit approval, and only on approval land it by adding `-m "<subject>"` to the
+     checkpoint. Present nothing and the deterministic title-derived subject lands
+     untouched: the reconcile is the human-approved exception, not a quiet `-m` swap (which
+     is the agent-authored subject D68 refuses).
    - **If `plumbbob status` shows a `harness bindings:` block**, fold any bound
      `after`-agents into that self-review as advisory input — see **§ Running bound
      agents**.

package/skills/pb-park/SKILL.md

@@ -25,8 +25,9 @@ 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:
+tidy, tagged line** — short, legible, self-contained, and carrying a **one-clause why**
+(what it is *and* why it's worth revisiting), so it still reads cleanly weeks later when
+harvest triages it cold. Then:
 
 1. **Show the composed line to the human** and wait for **in-turn approval** — they
    confirm it as-is or edit the wording.

package/skills/pb-plan/SKILL.md

@@ -58,13 +58,23 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    **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.
+   *because*) and the hard rules the build must honor. **Slug each at birth** — mint a
+   two- or three-word slug where the item is born (`D1 (default-waves): …`,
+   `C1 (no-new-deps): …`) and copy that slug at every reference site, so a later
+   mention reads `D4 (default-waves)` and stays legible: **never a bare `D4`/`C6`/`Q2`
+   reference — always carry its gloss**, so a cold reader never has to hunt the number
+   down. An unresolved hole goes to **Open questions**, never guessed into a Decision —
+   and it goes in the expanded form the template shows: a slugged opener (the hole as a
+   question), a `*plain:*` sub-line (what's at stake, in plain words, enough to judge it
+   cold), then a `*lean:*` sub-line (your proposed resolution — one answer to react to,
+   not a menu), so the human settles it in one pass without a round-trip. (A tiny,
+   obvious question may stay one bare line; the sub-lines earn their keep only when a
+   human decision genuinely waits on it.)
 4. **Author the Steps.** Write the **full build plan** under `## Steps` — each step a
    small, verifiable increment in the exact format the parser reads:
 
    ```markdown
-   1. [ ] <title> — **done when:** <criterion, ideally a test or check result>
+   1. [ ] feat(scope): <title> — **done when:** <criterion, ideally a test or check result>
       - seam: `<file>`, `<file>`
       - model: <optional — smallest that can carry it, with the one-phrase why>
    ```
@@ -74,12 +84,23 @@ 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)).
+   **The title *is* the commit subject — author it as one** *(D1)*: write each
+   `<title>` as a plain, single-line Conventional-Commit subject,
+   `type(scope): description`, and it lands in `git log` verbatim (its breaking `!`
+   honored) — this is how each step lands a *real* `feat`/`fix`/`chore` in the history.
+   Keep load-bearing detail — file paths, module names — in `seam` and `done-when`; it is
+   **never jammed into the title** (D2), which has to read as plain English and as a clean
+   subject at once. Aim for **≤72 characters** (GitHub's subject convention) — soft
+   guidance you eyeball at plan time, no lint, no gate (D9).
+
+   **Set the build's default scope, then let steps override it** *(D8)*: fill the
+   `**Scope:**` header once with a short feature-level name — the catch-all every step
+   inherits — and give a step its own `(scope)` when it touches a distinct code area
+   (`pb-plan`, `commitmsg`, `docs`). A step's `(scope)` names the *code area*; the header
+   names the *feature*, so scopes stay consistent and greppable across builds. Scope
+   resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
+   title-type → `feat`, so a scopeless plain title still yields a clean
+   `feat(<slug>): <title>` unchanged ([D68](../../docs/decisions.md#d68), D3).
 
    **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

package/skills/pb-refine/SKILL.md

@@ -27,13 +27,28 @@ is fine — refining is always available.
 - **Attack (diverge in the problem space).** Hand the **Frame**, **Decisions**, and
   **Architecture sketch** a cold, adversarial read and surface holes — ambiguities,
   unhandled edge cases, hidden assumptions, collisions with the existing code. Append
-  each as a one-line question under `## Open questions`, **never** as a Decision:
-  resolving a hole is the human's convergence, not yours. This mode surfaces; it does
-  not decide.
+  each under `## Open questions` in the expanded form the template shows — an opener
+  line (the hole as a question, slugged at birth: `- Q2 (some-slug): …`), a `*plain:*`
+  sub-line (what's at stake in plain words, enough to judge it cold), and a `*lean:*`
+  sub-line (your proposed resolution — one answer to react to, not a menu). Never
+  append a hole as a Decision: resolving it is the human's convergence, not yours —
+  the lean proposes; this mode surfaces, it does not decide. (A tiny, obvious question
+  may stay one bare line; the sub-lines earn their keep only when a human decision
+  genuinely waits on it.)
+
+  Then walk the human through it in the chat: list every hole you appended, each as
+  its explanation first and its lean second, and invite per-question answers — the
+  human can settle any of them right there in one message, no doc-flipping, no extra
+  round-trip per hole.
 - **Repair (re-sync to reality).** When the plan has drifted — a Decision was overtaken
-  by what you built, a Constraint changed, a Step no longer matches the seam — propose
-  the edits that bring `intent.md` back in line with the truth. Show the before/after for
-  each, and **write only what the human approves**.
+  by what you built, a Constraint changed, a Step no longer matches the seam, or a
+  **step's title no longer describes what the diff actually does** — propose the edits
+  that bring `intent.md` back in line with the truth. A step title *is* its checkpoint
+  commit subject (D1), so bringing a drifted one back in line means keeping it a plain,
+  single-line `type(scope): description` subject, with load-bearing detail (file paths,
+  module names) in `seam` and `done-when`, **never jammed into the title** (D2) — the
+  checkpoint body pass then reconciles and lands that subject at the verify pause (D5).
+  Show the before/after for each, and **write only what the human approves**.
 
 ## The hard contracts
 

package/skills/pb-step/SKILL.md

@@ -39,11 +39,16 @@ 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. 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.
+   `N. [ ] <title> — **done when:** <criterion>` with a `- seam:` sub-line. Keep the
+   sharpened `<title>` a plain, single-line Conventional-Commit subject,
+   `type(scope): description` — it lands in `git log` verbatim, so as the step tightens
+   keep load-bearing detail (file paths, module names) in `seam` and `done-when`,
+   **never jammed into the title** (D1/D2). A sharpened step carries its own `(scope)`
+   when it touches a distinct code area — one that **overrides the build-default**
+   `**Scope:**` header; drop the scope and it falls back to that default → build slug →
+   bare, and the type to `feat` ([D68](../../docs/decisions.md#d68), D8). Aim for a soft
+   ≤72 chars, no gate (D9). 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

@@ -45,6 +45,14 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    findings), 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.
+   - **Reconcile a drifted subject here, in the open (D5).** The planned title *is* the
+     checkpoint subject (D1). If the diff drifted from it — the step landed something the
+     title no longer describes — the body pass may propose a corrected subject, but it
+     **presents** it at this pause for explicit approval: show `planned title → proposed
+     subject`, one line, as part of what the human OKs. This is the exception, not the
+     default (D6): with **nothing presented**, the deterministic title-derived subject
+     lands untouched. A silent `-m` swap is exactly the agent-authored subject D68 refuses
+     — so a reconcile is *only ever* the visible, approved kind.
 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** — a Conventional
@@ -62,7 +70,10 @@ this skill verifies it the same way: **it reads the diff, not the author**.
    Do **not** run a TIL scan or reach for a separate commit skill — the body is yours to
    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.
+   touch the changelog — that is the human's `/version` call. And if step 5 surfaced a
+   drifted subject the human approved, land *that* subject by adding `-m "<subject>"` —
+   overriding the title-derived default for this one commit; unpresented, the CLI's
+   deterministic subject stands.
 7. **Hand off with the next model** *(once the checkpoint lands)*. `plumbbob checkpoint`
    returns to DESIGN; then run `plumbbob handoff` and relay its boundary block. With the
    step gone from in-flight it renders `step N checkpointed — back at the boundary` and

package/templates/intent.md

@@ -5,12 +5,18 @@ head; the chat is the hand. When the model floods you, read this, not your memor
 Size to the work: a small change fills Frame + a couple of Decisions and deletes
 the rest; a medium feature fills it all. Opinionated where decided, explicit where
 open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
+
+One rule runs through the whole doc: compress what's settled; expand what's pending.
+Decisions and Constraints stay one line each — they re-inject into every build step,
+so their tokens recur. Open questions expand into plain-then-lean prose — a human
+reads them once, to decide, and that legibility buys back a chat round-trip.
 -->
 
 # {{TITLE}}
 
 **Phase** (your own bookkeeping while framing): frame
 **Size:** tiny | small | medium
+**Scope:** <short-scope>  <!-- the build's default commit scope (D4): a short feature-level name each step's own `(scope)` overrides. Leave the `<…>` placeholder (or blank) and it parses as absent — commits fall through to the build slug (D7). -->
 
 ## Frame
 
@@ -31,16 +37,20 @@ open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
 
 ## Decisions
 
-*(One line each. Settled, not re-litigated in the chat. Grows as you resolve the
-holes `/pb-refine` surfaces, and as blockers fold in during BUILD.)*
+*(One line each — settled, not re-litigated in the chat. Grows as you resolve the
+holes `/pb-refine` surfaces, and as blockers fold in during BUILD. Mint a two- or
+three-word slug where each item is born — `D1 (slug-here)` — and copy that slug at
+every reference site, so a later `D4 (default-waves)` never decays into a bare `D4`
+a cold reader has to hunt down.)*
 
-- D1: <decision> — *because* <the one reason that mattered>
+- D1 (slug-here): <decision> — *because* <the one reason that mattered>
 
 ## Constraints
 
-*(Hard rules the build must honor. `/pb-verify` and `/pb-refine` read against these.)*
+*(Hard rules the build must honor. `/pb-verify` and `/pb-refine` read against these.
+Slug and gloss them at birth too — `C1 (no-new-deps)` — same one line, same rule.)*
 
-- C1: <e.g. functional/procedural only; no new dependencies>
+- C1 (no-new-deps): <e.g. functional/procedural only; no new dependencies>
 
 ## Steps
 
@@ -50,9 +60,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).
-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
+The step title *is* the checkpoint's commit subject: write it as one plain line,
+`type(scope): description` — load-bearing paths live in `seam`, never jammed into the
+title (D2) — aiming for ≤72 characters (GitHub's subject convention: soft, no gate, D9).
+The `(scope)` names the primary code area the step touches (`pb-plan`, `commitmsg`); the
+build's `**Scope:**` header is the feature-level catch-all a step overrides (D8). Scope
+resolves title-scope → `**Scope:**` default → build slug → bare, and type resolves
+title-type → `feat` (D3/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.)*
 
@@ -64,10 +78,40 @@ auto-syncs it), and use `/pb-refine` to repair the whole plan when a blocker rew
 
 ## Open questions
 
-*(Holes you could NOT resolve on paper. Do not guess them into Decisions. A genuine
-fork goes to a SPIKE; record the verdict below and in Decisions.)*
+*(Holes you could NOT resolve on paper — the one section that expands rather than
+compresses. Do not guess them into Decisions; a genuine fork goes to a SPIKE, with
+the verdict recorded below and in Decisions.)*
+
+<!--
+Write each open question so a cold reader could answer it without flipping back to
+the code or the chat — that cold-reader test is the whole point of expanding it.
+Three lines:
+
+  · the opener — the hole as a question, slugged at birth, tagged
+    *resolve by:* decide | spike | ask
+  · *plain:* — what's at stake, in plain words: the context and the cost of getting
+    it wrong, enough to judge it cold
+  · *lean:* — the model's proposed resolution: one answer to react to, not a menu
+
+The human reads *plain* to understand, then *lean* to approve or redirect — one
+pass, no round-trip.
+
+When a question resolves, swap *resolve by:* for *resolved:* <date, the call> ON THE
+OPENER LINE, e.g.
+
+  - Q3 (default-waves): *resolved:* 2026-07-18, default off
+
+The status counter reads opener lines only, so a *resolved:* left on a *plain:* or
+*lean:* sub-line leaves the question still counted as open.
+
+Size to the work: a tiny build's single, obvious question may stay one bare line —
+the *plain:*/*lean:* pair earns its keep only when a human decision genuinely waits
+on it.
+-->
 
-- Q1: <unresolved> — *resolve by:* decide | spike | ask
+- Q1 (slug-here): <the unresolved hole, framed as a question> — *resolve by:* decide | spike | ask
+  - *plain:* <what's at stake, in plain words — enough to judge it cold>
+  - *lean:* <the model's proposed resolution — the answer to react to>
 
 ## Verdicts