plumbbob 0.8.13 → 0.8.17

package/node_modules/checkride/dist/snippets.js

@@ -0,0 +1,360 @@
+/**
+ * Built-in `snippets` check.
+ *
+ * A doc snippet typecheck ported to match fascicle's `check-doc-snippets.mjs`
+ * byte-for-byte so the origin repo can adopt the slot verbatim (D11). It pulls
+ * fenced ```ts / ```typescript blocks out of `README.md` and the non-recursive
+ * `docs/*.md`, and typechecks only the ones explicitly opted in with an HTML
+ * comment on the line immediately above the fence:
+ *
+ *     <!-- snippet: check -->
+ *
+ * Opt-in (rather than checking every fence) keeps the check honest: many doc
+ * fences are deliberately partial fragments that assert nothing about the API.
+ * A tagged snippet that fails to compile is documentation that lies — this
+ * turns that into a build failure. Opting the slot in but tagging *nothing* is
+ * a misconfiguration, not a vacuous pass, so zero tagged snippets is a hard
+ * error ({@link vacuousOptInError}; fascicle exits 2).
+ *
+ * The pure machinery — no filesystem, no spawning:
+ *
+ *   - {@link extractSnippets} parses one doc's markdown into its ts/typescript
+ *     fenced blocks, recording each block's start line and whether it is tagged;
+ *   - {@link slugForDoc} / {@link snippetFileName} name the emitted scratch file
+ *     for a block (`<slug>__<n>.ts`);
+ *   - {@link planSnippets} folds a set of docs into the emission plan (the
+ *     checked blocks to write, each mapped back to `<doc>:<line>`) plus the
+ *     checked/skipped counts;
+ *   - {@link generateSnippetTsconfig} builds the generated tsconfig (extends the
+ *     repo's own, relaxes the three emit/style flags plus the composite-build
+ *     fields a `tsc --build` project carries, embeds the caller's mode-specific
+ *     `paths`).
+ *
+ * Execution (D12/Q1), consuming the primitives above:
+ *
+ *   - {@link deriveSrcPaths} resolves **src mode**'s `paths` mapping: the repo's
+ *     own tsconfig `paths` when present, else the `src/index.ts` convention,
+ *     else null (the caller fails, recommending `snippets-dist`);
+ *   - {@link checkSnippets} discovers the doc set, plans it, derives the mode's
+ *     `paths`, emits the scratch files + generated tsconfig under
+ *     `.check/doc-snippets/`, and typechecks them via a spawned
+ *     `<pm> exec tsc --noEmit -p`, returning a {@link CheckOutcome} whose
+ *     failure `stderr` carries tsc's raw output plus the `snippet -> source
+ *     map:` legend.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { translateExec } from './pm/index.js';
+/**
+ * The opt-in marker: an HTML comment `<!-- snippet: check -->` that must sit on
+ * the line immediately above a fence for its snippet to be typechecked. Exact
+ * fascicle regex (D11).
+ */
+export const CHECK_MARKER_RE = /<!--\s*snippet:\s*check\s*-->/;
+/** An opening fence — `ts` or `typescript` only, nothing else on the line (D11). */
+export const FENCE_OPEN_RE = /^```(ts|typescript)\s*$/;
+/** A closing fence: three backticks alone on the line. */
+export const FENCE_CLOSE_RE = /^```\s*$/;
+/**
+ * Select the doc files to check from a `docs/` directory listing (D11): always
+ * `README.md`, then every non-recursive `docs/*.md` entry, README first and the
+ * `docs/` entries in the order given. Pure — the caller does the (non-recursive)
+ * `readdir` and passes its entries; a plain entry list means a nested
+ * `docs/sub/x.md` never appears (its listing entry `sub` fails `.md`), matching
+ * fascicle's non-recursive `doc_files`.
+ */
+export function selectDocFiles(docsEntries) {
+    const files = ['README.md'];
+    for (const name of docsEntries) {
+        if (name.endsWith('.md'))
+            files.push(`docs/${name}`);
+    }
+    return files;
+}
+/**
+ * Parse a doc's markdown into its `ts`/`typescript` fenced blocks (D11). A block
+ * is `checked` when a {@link CHECK_MARKER_RE} marker sits on the line immediately
+ * above its opening fence — a marker anywhere else does not count. Untagged
+ * blocks are still returned (the caller counts them as skipped). Semantics match
+ * fascicle's `extract_blocks` exactly.
+ */
+export function extractSnippets(text) {
+    const lines = text.split('\n');
+    const blocks = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (FENCE_OPEN_RE.test(lines[i] ?? '')) {
+            const startLine = i + 1;
+            const checked = i > 0 && CHECK_MARKER_RE.test(lines[i - 1] ?? '');
+            const body = [];
+            i += 1;
+            while (i < lines.length && !FENCE_CLOSE_RE.test(lines[i] ?? '')) {
+                body.push(lines[i] ?? '');
+                i += 1;
+            }
+            blocks.push({ code: body.join('\n'), startLine, checked });
+        }
+        i += 1;
+    }
+    return blocks;
+}
+/**
+ * The scratch-file slug for a doc's repo-relative path: every non-alphanumeric
+ * run collapses to a single `_`, with leading/trailing `_` trimmed
+ * (`README.md` → `README_md`, `docs/guide.md` → `docs_guide_md`). Exact fascicle
+ * algorithm. Distinct docs in the discovered namespace (`README.md` plus the
+ * flat `docs/*.md`) map to distinct slugs, so their emitted files never collide.
+ */
+export function slugForDoc(relPath) {
+    return relPath.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+/**
+ * The scratch-file name for a block: `<slug>__<n>.ts`, where `n` is the block's
+ * 1-based position among *all* ts/typescript fences in its doc (checked or not) —
+ * so a skipped fence still advances the number, matching fascicle.
+ */
+export function snippetFileName(relPath, blockIndex) {
+    return `${slugForDoc(relPath)}__${blockIndex}.ts`;
+}
+/**
+ * Fold a set of docs into the emission plan: every checked block becomes a
+ * {@link SnippetPlanEntry} (named, mapped back to `<doc>:<line>`), untagged
+ * blocks bump `skipped`. The block index for naming counts all fences in a doc,
+ * so a checked block keeps its position even after skipped ones (fascicle
+ * parity). Pure — the caller reads the docs and writes the files.
+ */
+export function planSnippets(docs) {
+    const entries = [];
+    let checked = 0;
+    let skipped = 0;
+    for (const doc of docs) {
+        extractSnippets(doc.text).forEach((block, index) => {
+            if (!block.checked) {
+                skipped += 1;
+                return;
+            }
+            entries.push({
+                name: snippetFileName(doc.relPath, index + 1),
+                file: doc.relPath,
+                line: block.startLine,
+                code: block.code,
+            });
+            checked += 1;
+        });
+    }
+    return { entries, checked, skipped };
+}
+/**
+ * The vacuous-opt-in guard (D11): a plan with no checked snippets is a hard
+ * error, not a vacuous green — opting the slot in obligates at least one tagged
+ * fence. Returns the error message for step 8 to surface (fascicle exits 2), or
+ * null when the plan has something to check.
+ */
+export function vacuousOptInError(plan) {
+    if (plan.checked > 0)
+        return null;
+    return 'no tagged snippets found — refusing to pass vacuously (add a `<!-- snippet: check -->` marker above a ts/typescript fence)';
+}
+/**
+ * Build the generated tsconfig (D11): extend the repo's own config so the
+ * snippets inherit its strictness, then relax exactly the three flags that
+ * false-positive on illustrative snippets (`verbatimModuleSyntax`,
+ * `isolatedModules`, `noPropertyAccessFromIndexSignature`) while keeping the
+ * type-correctness flags that catch real API drift. `include` clears the parent's
+ * `.check` exclusion so the emitted `./*.ts` are seen; `paths` is the caller's
+ * mode-specific module resolution (src vs dist — Q1).
+ *
+ * A `tsc --build` project (composite, `rootDir`/`outDir` pinned to `src`/`dist`
+ * for project-reference emit) fails TS6059 on any *source* file outside its
+ * `rootDir` — and the generated snippets live under `.check/doc-snippets/`,
+ * while src mode's `paths` mapping pulls in a real source file elsewhere in the
+ * repo (dist mode's self-referenced `.d.ts` is exempt: a declaration file isn't
+ * subject to the same check). `rootDir: '../..'` re-scopes to `cwd` — the
+ * common ancestor of both — so either file satisfies it; `composite`/
+ * `declaration`/`declarationMap`/`incremental` are turned off since this is a
+ * one-shot typecheck, never a build. All four are no-ops on a plain
+ * (non-composite) project's tsconfig, so the override is harmless there too.
+ */
+export function generateSnippetTsconfig(opts) {
+    return {
+        extends: opts.extendsPath,
+        compilerOptions: {
+            paths: opts.paths,
+            noEmit: true,
+            verbatimModuleSyntax: false,
+            isolatedModules: false,
+            noPropertyAccessFromIndexSignature: false,
+            rootDir: '../..',
+            composite: false,
+            declaration: false,
+            declarationMap: false,
+            incremental: false,
+        },
+        include: ['./*.ts'],
+        exclude: [],
+    };
+}
+/** Where the generated snippet files + tsconfig land, relative to `cwd`. */
+const OUT_DIR_REL = join('.check', 'doc-snippets');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read the doc set (D11): `README.md` plus non-recursive `docs/*.md`, skipping
+ * any that don't exist — a repo with no `docs/` directory (or no `README.md`)
+ * still runs on what it has; an empty result is caught by
+ * {@link vacuousOptInError}.
+ */
+async function discoverDocs(cwd) {
+    let docsEntries = [];
+    try {
+        docsEntries = await readdir(join(cwd, 'docs'));
+    }
+    catch {
+        // No docs/ directory — README.md alone still gets checked.
+    }
+    const found = await Promise.all(selectDocFiles(docsEntries).map(async (relPath) => {
+        try {
+            return { relPath, text: await readFile(join(cwd, relPath), 'utf8') };
+        }
+        catch {
+            return null;
+        }
+    }));
+    return found.filter((d) => d !== null);
+}
+/** The package name from `package.json`, or null on any read/parse failure or a missing `name`. */
+async function readManifestName(cwd) {
+    try {
+        const parsed = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+        const name = isRecord(parsed) ? parsed['name'] : undefined;
+        return typeof name === 'string' && name ? name : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The repo's own `tsconfig.json`'s **own** `compilerOptions.paths` (not resolved
+ * through its `extends` chain — a repo that hand-declares self-referencing
+ * paths, as fascicle does, puts them directly on the root file), or null when
+ * absent, unreadable, or empty.
+ */
+async function readOwnTsconfigPaths(cwd) {
+    try {
+        const parsed = JSON.parse(await readFile(join(cwd, 'tsconfig.json'), 'utf8'));
+        const compilerOptions = isRecord(parsed) ? parsed['compilerOptions'] : undefined;
+        const paths = isRecord(compilerOptions) ? compilerOptions['paths'] : undefined;
+        if (!isRecord(paths))
+            return null;
+        const out = {};
+        for (const [key, value] of Object.entries(paths)) {
+            if (Array.isArray(value) && value.every((v) => typeof v === 'string'))
+                out[key] = value;
+        }
+        return Object.keys(out).length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rewrite a tsconfig-root-relative target (`./src/x.ts` or `src/x.ts`) to resolve from `.check/doc-snippets/`. */
+function remapRootRelative(target) {
+    const stripped = target.startsWith('./') ? target.slice(2) : target;
+    return `../../${stripped}`;
+}
+/**
+ * Derive the `paths` mapping **src mode** needs so `import { x } from
+ * '<pkg-name>'` resolves against source (Q1): the repo's own tsconfig `paths`
+ * when present (remapped two directories deeper, to where the generated
+ * tsconfig lives), else the `src/index.ts` convention (`<pkg-name>` maps to its
+ * root `src/index.ts`) when the manifest names the package and that file
+ * exists, else null — the caller turns a null into a failing outcome that
+ * recommends `snippets-dist` (whose dist-mode compilation needs no mapping at
+ * all: package self-reference through `exports` resolves the built types).
+ */
+export function deriveSrcPaths(opts) {
+    if (opts.tsconfigPaths && Object.keys(opts.tsconfigPaths).length > 0) {
+        const remapped = {};
+        for (const [key, targets] of Object.entries(opts.tsconfigPaths)) {
+            remapped[key] = targets.map(remapRootRelative);
+        }
+        return remapped;
+    }
+    if (opts.manifestName !== null && opts.hasSrcIndex) {
+        return { [opts.manifestName]: ['../../src/index.ts'] };
+    }
+    return null;
+}
+function failOutcome(message) {
+    return {
+        ok: false,
+        exit_code: 1,
+        stdout: `${JSON.stringify({ ok: false, error: message }, null, 2)}\n`,
+        stderr: `check-snippets: ${message}\n`,
+    };
+}
+/** Compile the generated tsconfig via `<pm> exec tsc --noEmit -p <path>`, translated per PM. */
+function runTsc(cwd, tsconfigRelPath, pm, spawn, timeoutSec) {
+    const { command, args } = translateExec('pnpm', ['exec', 'tsc', '--noEmit', '-p', tsconfigRelPath], pm);
+    return spawn(command, args, cwd, timeoutSec);
+}
+/**
+ * Run the `snippets` check against `cwd` in `mode` (D12: the `snippets` src
+ * adapter passes `'src'`, `snippets-dist` passes `'dist'`). Discovers the doc
+ * set, plans the checked snippets ({@link vacuousOptInError} applies first —
+ * zero tagged snippets is a hard error before anything is written), derives
+ * the mode's `paths` mapping, emits the scratch files plus a generated
+ * tsconfig under `.check/doc-snippets/`, and typechecks them through the
+ * injected `spawn`. A compile failure's `stderr` carries tsc's raw output plus
+ * the `snippet -> source map:` legend mapping each generated file back to
+ * `<doc>:<line>` (D11).
+ */
+export async function checkSnippets(opts) {
+    const { cwd, mode, pm, spawn, timeoutSec } = opts;
+    const plan = planSnippets(await discoverDocs(cwd));
+    const vacuous = vacuousOptInError(plan);
+    if (vacuous)
+        return failOutcome(vacuous);
+    let paths = {};
+    if (mode === 'src') {
+        const [manifestName, tsconfigPaths] = await Promise.all([readManifestName(cwd), readOwnTsconfigPaths(cwd)]);
+        const derived = deriveSrcPaths({
+            manifestName,
+            tsconfigPaths,
+            hasSrcIndex: existsSync(join(cwd, 'src', 'index.ts')),
+        });
+        if (derived === null) {
+            return failOutcome("cannot map snippet imports to source: tsconfig.json has no self-referencing 'paths' and there is no " +
+                "src/index.ts — add a 'paths' entry for the package name, or opt into the 'snippets-dist' adapter " +
+                'instead (dist mode needs no mapping)');
+        }
+        paths = derived;
+    }
+    const outDir = join(cwd, OUT_DIR_REL);
+    await rm(outDir, { recursive: true, force: true });
+    await mkdir(outDir, { recursive: true });
+    await Promise.all(plan.entries.map((e) => writeFile(join(outDir, e.name), `${e.code}\n`, 'utf8')));
+    const tsconfig = generateSnippetTsconfig({ extendsPath: '../../tsconfig.json', paths });
+    await writeFile(join(outDir, 'tsconfig.json'), `${JSON.stringify(tsconfig, null, 2)}\n`, 'utf8');
+    const outcome = await runTsc(cwd, join(OUT_DIR_REL, 'tsconfig.json'), pm, spawn, timeoutSec);
+    const status = { checked: plan.checked, skipped: plan.skipped, mode };
+    if (outcome.ok) {
+        return {
+            ok: true,
+            exit_code: 0,
+            stdout: `${JSON.stringify({ ok: true, ...status }, null, 2)}\n`,
+            stderr: `check-snippets: ${plan.checked} snippet(s) compile against ${mode} (${plan.skipped} skipped)\n`,
+        };
+    }
+    const legend = plan.entries.map((e) => `  ${e.name}  <-  ${e.file}:${e.line}`).join('\n');
+    const tscOutput = `${outcome.stdout}${outcome.stderr}`.trim();
+    return {
+        ok: false,
+        exit_code: 1,
+        stdout: `${JSON.stringify({ ok: false, ...status }, null, 2)}\n`,
+        stderr: `check-snippets: snippet(s) failed to compile:\n\n${tscOutput}\n\nsnippet -> source map:\n${legend}\n`,
+    };
+}
+//# sourceMappingURL=snippets.js.map

package/node_modules/checkride/dist/snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippets.js","sourceRoot":"","sources":["../src/snippets.ts"],"names":[],"mappings":"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"}

package/node_modules/checkride/package.json

@@ -1,6 +1,6 @@
 {
   "name": "checkride",
-  "version": "0.3.0",
+  "version": "0.5.2",
   "description": "An agent harness for TypeScript repositories: one command that is the definition of done, plus mechanically enforced module boundaries.",
   "license": "MIT",
   "author": "Rob McLarty",
@@ -62,6 +62,7 @@
     "prepublishOnly": "tsc --build && vitest run"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.4",
     "@ast-grep/cli": "0.42.1",
     "@stryker-mutator/core": "9.6.1",
     "@stryker-mutator/vitest-runner": "9.6.1",
@@ -69,10 +70,11 @@
     "@vitest/coverage-v8": "4.1.5",
     "ajv": "8.20.0",
     "cspell": "10.0.0",
-    "fallow": "2.48.0",
+    "fallow": "3.5.0",
     "markdownlint-cli2": "0.22.1",
     "oxlint": "1.61.0",
     "oxlint-tsgolint": "0.21.1",
+    "publint": "0.3.21",
     "typescript": "6.0.3",
     "vitest": "4.1.5"
   }

package/node_modules/checkride/schema/checkride.config.schema.json

@@ -24,7 +24,7 @@
     },
     "checks": {
       "type": "object",
-      "description": "Per-slot configuration. A key that matches a catalogue slot (types, format, lint, struct, dead, test, docs, links, spell, mutation, security, publint, attw) configures that slot; any other key is a custom check that runs alongside the catalogue. Naming an opt-in slot (format, mutation, security, publint, attw) here also opts it into the default run.",
+      "description": "Per-slot configuration. A key that matches a catalogue slot (types, format, lint, struct, dead, dupes, health, test, docs, links, spell, mutation, security, publint, attw) configures that slot; any other key is a custom check that runs alongside the catalogue. Naming an opt-in slot (format, dupes, health, mutation, security, publint, attw) here also opts it into the default run.",
       "additionalProperties": {
         "$ref": "#/definitions/slotConfig"
       }
@@ -62,9 +62,17 @@
         "outputFile": { "type": ["string", "null"] },
         "changedArgs": { "type": "array", "items": { "type": "string" } },
         "fixArgs": { "type": "array", "items": { "type": "string" } },
-        "timeout": { "type": "number", "minimum": 0 }
+        "timeout": { "type": "number", "minimum": 0 },
+        "order": { "$ref": "#/definitions/order" }
       }
     },
+    "order": {
+      "description": "Scheduling order. A number places the check on the ascending wave line (equal numbers run together as one wave; decimals sequence steps within a wave); the keywords place it relative to that line — first/last before/after everything, single exclusively on its own, middle/any unordered in the main group.",
+      "oneOf": [
+        { "enum": ["first", "last", "middle", "single", "any"] },
+        { "type": "number" }
+      ]
+    },
     "customCheck": {
       "type": "object",
       "description": "A bare command that needs no adapter.",
@@ -87,10 +95,7 @@
           "items": { "type": "string" },
           "description": "Marker files that gate a non-catalogue custom check: it runs only when at least one listed file exists, and is skipped otherwise. Ignored on an entry that fills a catalogue slot."
         },
-        "order": {
-          "enum": ["first", "last"],
-          "description": "Where a non-catalogue custom check runs relative to the catalogue. Default 'last'."
-        }
+        "order": { "$ref": "#/definitions/order" }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.8.13",
+  "version": "0.8.17",
   "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",
@@ -46,6 +46,7 @@
   },
   "devDependencies": {
     "@ast-grep/cli": "0.43.0",
+    "@stryker-mutator/api": "9.6.1",
     "@stryker-mutator/core": "9.6.1",
     "@stryker-mutator/vitest-runner": "9.6.1",
     "@types/node": "24.13.1",
@@ -58,7 +59,7 @@
     "vitest": "4.1.9"
   },
   "dependencies": {
-    "checkride": "0.3.0"
+    "checkride": "0.5.2"
   },
   "bundleDependencies": [
     "checkride"

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