plumbbob 0.4.13 → 0.5.3

package/dist/lib/intent.js

@@ -78,11 +78,30 @@ export function parseStepSeam(content, step) {
     return { ok: true, seam };
 }
 // Seam membership (D23): a repo-relative path is in-seam if it equals an exact
-// token, or is prefixed by a `dir/` grant. Shared by `done` (scope-drift warn)
-// and `revert` (untracked cleanup).
+// token, or is prefixed by a `dir/` grant. Shared by `checkpoint` (scope-drift
+// warn) and `revert` (untracked cleanup).
 export function matchesSeam(relPath, tokens) {
     return tokens.some((token) => (token.endsWith('/') ? relPath.startsWith(token) : relPath === token));
 }
+// Plumbbob's own artifact plane (D17): everything under `.plumbbob/` is plumbbob's
+// bookkeeping — the tracked intent/build-log/checkpoints that ride the branch, and
+// the excluded control markers. It is never the user's code, so it never counts as
+// scope drift, and `revert`'s untracked cleanup must never delete it. checkpoint
+// stages this plane itself on every tick (the `[x]` flip, the build-log line), so
+// without this whitelist every checkpoint would cry wolf about its own writes.
+export function isArtifactPath(relPath) {
+    return relPath === '.plumbbob' || relPath.startsWith('.plumbbob/');
+}
+// The staged paths that fall outside the step's seam AND outside the artifact
+// plane — the scope-drift set `checkpoint` warns about (guidance, not a gate: the
+// checkpoint still commits them). An empty seam yields no drift, so callers that
+// cannot resolve a seam simply skip the warning rather than flagging everything.
+export function scopeDrift(paths, seam) {
+    if (seam.length === 0) {
+        return [];
+    }
+    return paths.filter((p) => !matchesSeam(p, seam) && !isArtifactPath(p));
+}
 function fail(error) {
     return { ok: false, error };
 }

package/dist/lib/orient.js

@@ -110,9 +110,9 @@ function nextMove(spiking, steps, inFlight, parked) {
             return 'plan the first step — `/plumbbob:pb-step`';
         }
         // Batch-default: the steps were planned up front, so finishing them usually
-        // means "wrap up" — but `/plumbbob:pb-step` can still add an increment if reality grew.
+        // means "finish up" — but `/plumbbob:pb-step` can still add an increment if reality grew.
         const harvest = parked > 0 ? `harvest ${parked} parked idea${parked === 1 ? '' : 's'} — \`/plumbbob:pb-harvest\`; then ` : '';
-        return `${harvest}wrap up — \`/plumbbob:pb-wrap\` (or \`/plumbbob:pb-step\` to add another increment)`;
+        return `${harvest}finish up — \`/plumbbob:pb-finish\` (or \`/plumbbob:pb-step\` to add another increment)`;
     }
     return nextUndone.planned
         ? `build step ${nextUndone.n} — \`/plumbbob:pb-build\` (or \`/plumbbob:pb-step\` to revise it first)`

package/dist/lib/settings.js

@@ -0,0 +1,71 @@
+// The settings ladder (D27): a resolved setting comes from, in priority order,
+//   1. a CLI flag           — passed in by the verb (undefined when absent)
+//   2. settings.local.json  — untracked personal overlay + per-worktree cursor
+//   3. settings.json        — tracked project defaults
+//   4. a built-in default   — supplied by the caller
+// The first defined rung wins. Both files are optional JSON; a missing or
+// malformed file contributes nothing rather than throwing, so a broken personal
+// overlay can never wedge the tool. Functional/procedural, node builtins (C1/C2).
+//
+// Known keys: `check` (string — the heavy gate, tracked in settings.json) and
+// `auto` (boolean — whether the agent approves in the human's place; a personal
+// preference, so it belongs in settings.local.json). `activeBuild` (the
+// per-worktree cursor) also lives in settings.local.json but is resolved by
+// sidecar.ts, not here.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const DIRNAME = '.plumbbob';
+export function settingsPath(root) {
+    return join(root, DIRNAME, 'settings.json');
+}
+export function localSettingsPath(root) {
+    return join(root, DIRNAME, 'settings.local.json');
+}
+function readSettings(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+// The raw ladder: flag → local overlay → project defaults → undefined. The typed
+// helpers below apply the built-in default and reject wrong-typed rungs.
+function resolveSetting(root, key, flag) {
+    if (flag !== undefined)
+        return flag;
+    const local = readSettings(localSettingsPath(root))[key];
+    if (local !== undefined)
+        return local;
+    return readSettings(settingsPath(root))[key];
+}
+// Resolve a string setting (e.g. `check`). A missing rung, or one holding a
+// non-string / blank value, yields the caller's fallback rather than gating on
+// garbage.
+export function resolveString(root, key, fallback, flag) {
+    const value = resolveSetting(root, key, flag);
+    return typeof value === 'string' && value.trim().length > 0 ? value : fallback;
+}
+// Resolve a boolean setting (e.g. `auto`). A missing or non-boolean rung yields
+// the caller's fallback.
+export function resolveBoolean(root, key, fallback, flag) {
+    const value = resolveSetting(root, key, flag);
+    return typeof value === 'boolean' ? value : fallback;
+}
+// Read one key from the untracked local overlay ONLY — no project or built-in
+// fallback. The `activeBuild` cursor lives here and must never resolve from the
+// tracked settings.json (it is per-worktree state, not a shared default).
+export function localSetting(root, key) {
+    return readSettings(localSettingsPath(root))[key];
+}
+// Merge one key into settings.local.json, preserving the other keys and creating
+// the file when absent. Pretty-printed so the overlay stays hand-editable. A
+// malformed existing file contributes nothing (readSettings yields {}) and is
+// overwritten with a clean object rather than throwing.
+export function setLocalSetting(root, key, value) {
+    const path = localSettingsPath(root);
+    mkdirSync(dirname(path), { recursive: true });
+    const merged = { ...readSettings(path), [key]: value };
+    writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`);
+}

package/dist/lib/sidecar.js

@@ -6,45 +6,128 @@
 // and nothing reads its content. The phase the dashboard shows (DESIGN/BUILD/
 // SPIKE) is derived, not stored — BUILD ⇔ a STEP is in flight, SPIKE ⇔ the SPIKE
 // marker is present, otherwise DESIGN.
-import { existsSync, readFileSync, writeFileSync, appendFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { gitDir } from "./git.js";
+import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, rmSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { gitPath } from "./git.js";
+import { localSetting } from "./settings.js";
 const DIRNAME = '.plumbbob';
 export function sidecarDir(root) {
     return join(root, DIRNAME);
 }
+// The tracked artifact plane (D26): each build owns a self-contained folder under
+// `.plumbbob/builds/<slug>/` that rides its branch into the PR. `buildDir` is the
+// per-build root; intent.md, build-log.md, checkpoints, and report.md live inside
+// it (the in-flight STEP/SEAM/SPIKE markers do too, but stay git-excluded).
+function buildsDir(root) {
+    return join(root, DIRNAME, 'builds');
+}
+export function buildDir(root, slug) {
+    return join(buildsDir(root), slug);
+}
+// Derive a filesystem-safe slug from a build title: lowercased, every run of
+// non-alphanumerics collapsed to a single hyphen, trimmed of leading/trailing
+// hyphens. The CLI stays dumb and explicit (D38) — collision handling belongs to
+// the caller (`start` refuses rather than silently suffixing `-2`). A title with
+// no alphanumerics yields `''`, which the caller must reject or override.
+export function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+// 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) {
+    try {
+        return readdirSync(buildsDir(root), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// Resolve which build a verb acts on (D28): an explicit `--build <slug>` flag →
+// the `activeBuild` cursor in settings.local.json → the sole build in `builds/`
+// → null (the caller then refuses with a hint). One-active-per-worktree holds by
+// construction: the cursor is a single scalar key in an untracked file, so it can
+// never point at two builds (D28).
+export function activeBuild(root, flag) {
+    if (flag !== undefined && flag.length > 0)
+        return flag;
+    const cursor = localSetting(root, 'activeBuild');
+    if (typeof cursor === 'string' && cursor.length > 0)
+        return cursor;
+    const builds = listBuilds(root);
+    return builds.length === 1 ? (builds[0] ?? null) : null;
+}
+// The build a verb should act on, plus its argv with the `--build <slug>` pair
+// stripped (D28). Every verb resolves through this: an explicit `--build <slug>`
+// wins, else the cursor / sole-build fallback of `activeBuild`. `rest` matters
+// because the slug is a bare token — scanning positionals on the raw argv would let
+// it masquerade as a step number or a spike slug, so callers scan `rest` instead.
+export function resolveBuild(root, args) {
+    const i = args.indexOf('--build');
+    if (i === -1)
+        return { build: activeBuild(root), rest: args };
+    return { build: activeBuild(root, args[i + 1]), rest: [...args.slice(0, i), ...args.slice(i + 2)] };
+}
 function statePath(root) {
     return join(root, DIRNAME, 'STATE');
 }
+// Where a build's artifacts and in-flight markers live (D26): the `builds/<slug>/`
+// folder for the resolved build, else the flat sidecar root. `slug` is the value
+// the verb already resolved via `resolveBuild`/`activeBuild`; omit it and the dir
+// resolves from the cursor (the default the executor-agnostic path reads lean on).
+// Either way a `null` slug falls back to the flat sidecar root, which covers the
+// `--local` layout (D26) and any no-cursor/no-build repo, so the path reads stay
+// stable even before a tracked build exists or when a "no active session" guard is
+// about to fire.
+function artifactDir(root, slug) {
+    const resolved = slug === undefined ? activeBuild(root) : slug;
+    return resolved === null ? sidecarDir(root) : buildDir(root, resolved);
+}
+// The resolved build's artifact folder — the `builds/<slug>/` dir for the active
+// build (or the flat sidecar root under `--local`/no-cursor). Public so the
+// plan-approval commit can stage exactly this build's scaffold and nothing else
+// (D36); `slug` follows the same resolution as the path helpers above.
+export function buildFolder(root, slug) {
+    return artifactDir(root, slug);
+}
 // The SPIKE marker (a single-purpose presence flag, like SEAM/STEP): written by
 // `spike` on open, removed on `spike done`. Its existence is the one signal that
 // the dashboard and the spike gates read to know "a spike is active".
-export function spikePath(root) {
-    return join(root, DIRNAME, 'SPIKE');
+export function spikePath(root, slug) {
+    return join(artifactDir(root, slug), 'SPIKE');
 }
 // SEAM and STEP carry the in-flight step (D4/D7): a plain path list and a bare
 // number, so the hooks read them with a grep and no markdown parsing.
-export function seamPath(root) {
-    return join(root, DIRNAME, 'SEAM');
+export function seamPath(root, slug) {
+    return join(artifactDir(root, slug), 'SEAM');
 }
-export function stepPath(root) {
-    return join(root, DIRNAME, 'STEP');
+export function stepPath(root, slug) {
+    return join(artifactDir(root, slug), 'STEP');
 }
-export function checkpointsPath(root) {
-    return join(root, DIRNAME, 'checkpoints');
+export function checkpointsPath(root, slug) {
+    return join(artifactDir(root, slug), 'checkpoints');
 }
-export function configPath(root) {
-    return join(root, DIRNAME, 'config');
+export function intentPath(root, slug) {
+    return join(artifactDir(root, slug), 'intent.md');
 }
-export function intentPath(root) {
-    return join(root, DIRNAME, 'intent.md');
+export function buildLogPath(root, slug) {
+    return join(artifactDir(root, slug), 'build-log.md');
 }
-export function buildLogPath(root) {
-    return join(root, DIRNAME, 'build-log.md');
+// report.md sits beside intent.md / build-log.md inside the build folder. The
+// pb-finish skill writes it and `finish` commits it with the folder — the folder
+// IS the archive now (D29), so the report rides the branch into the PR instead of
+// being copied into a local-only `archive/` (which retired with `archive.ts`).
+export function reportPath(root, slug) {
+    return join(artifactDir(root, slug), 'report.md');
 }
-// A session exists iff STATE exists. Deleting STATE (at wrap) is what flips the
+// A session exists iff STATE exists. Deleting STATE (at finish) is what flips the
 // repo back to "no session" — so it is the single source of truth for "is there
-// a session". `start` calls beginSession; `wrap` removes the file.
+// a session". `start` calls beginSession; `finish` removes the file.
 export function hasSession(root) {
     return existsSync(statePath(root));
 }
@@ -52,19 +135,22 @@ export function beginSession(root) {
     writeFileSync(statePath(root), 'active\n');
 }
 // SPIKE marker helpers — existence is the whole signal (content is irrelevant).
-export function inSpike(root) {
-    return existsSync(spikePath(root));
+export function inSpike(root, slug) {
+    return existsSync(spikePath(root, slug));
 }
-export function markSpike(root) {
-    writeFileSync(spikePath(root), 'active\n');
+export function markSpike(root, slug) {
+    writeFileSync(spikePath(root, slug), 'active\n');
 }
-export function clearSpike(root) {
-    rmSync(spikePath(root), { force: true });
+export function clearSpike(root, slug) {
+    rmSync(spikePath(root, slug), { force: true });
 }
-// D17: keep the sidecar untracked by appending `.plumbbob/` to the repo's
-// git/info/exclude. Idempotent — a re-`start` after finish must not double-add.
-export function excludeSidecar(root) {
-    const exclude = join(gitDir(root), 'info', 'exclude');
+// Append `patterns` to the repo's info/exclude, each at most once (idempotent —
+// a re-`start` after finish must not double-add). `gitPath` resolves to the
+// *common* gitdir's exclude — the only one git reads — so this works from a
+// linked worktree, whose per-worktree gitdir has no `info/` (D33).
+function addExcludes(root, patterns) {
+    const exclude = gitPath(root, 'info/exclude');
+    mkdirSync(dirname(exclude), { recursive: true });
     let current = '';
     try {
         current = readFileSync(exclude, 'utf8');
@@ -72,9 +158,33 @@ export function excludeSidecar(root) {
     catch {
         current = '';
     }
-    if (current.split('\n').some((line) => line.trim() === `${DIRNAME}/`)) {
+    const present = new Set(current.split('\n').map((line) => line.trim()));
+    const missing = patterns.filter((pattern) => !present.has(pattern));
+    if (missing.length === 0)
         return;
-    }
     const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
-    appendFileSync(exclude, `${prefix}${DIRNAME}/\n`);
+    appendFileSync(exclude, `${prefix}${missing.join('\n')}\n`);
+}
+// The narrowed control plane (D17): with `builds/<slug>/` now tracked, only the
+// per-worktree control files stay git-excluded — the local settings overlay (its
+// `activeBuild` cursor), the session sentinel, and the in-flight step markers
+// inside every build. Everything else under `.plumbbob/` (settings.json, and each
+// build's intent/build-log/checkpoints/report) rides the branch into the PR.
+export function excludeControl(root) {
+    addExcludes(root, [
+        `${DIRNAME}/STATE`,
+        `${DIRNAME}/settings.local.json`,
+        `${DIRNAME}/builds/*/STEP`,
+        `${DIRNAME}/builds/*/SEAM`,
+        `${DIRNAME}/builds/*/SPIKE`,
+        // The checkride gate (D32) writes raw tool output to `.check/`; checkpoint's
+        // stageAll must never sweep it into a step commit.
+        '.check/',
+    ]);
+}
+// D26: `start --local` opts out of the tracked layout into a fully-untracked
+// sidecar (today's behavior) — some team repos won't accept tool folders in-tree.
+// Excludes the whole `.plumbbob/` directory.
+export function excludeSidecar(root) {
+    addExcludes(root, [`${DIRNAME}/`, '.check/']);
 }

package/dist/verbs/build.js

@@ -3,7 +3,7 @@
 // BUILD phase from it); it never checkpoints (only `checkpoint` commits).
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, intentPath, seamPath, stepPath } from "../lib/sidecar.js";
+import { hasSession, intentPath, resolveBuild, seamPath, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -11,19 +11,20 @@ export function build(cwd, args) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
-    const raw = args.find((a) => !a.startsWith('--'));
+    const { build: slug, rest } = resolveBuild(root, args);
+    const raw = rest.find((a) => !a.startsWith('--'));
     if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1) {
         process.stderr.write('plumbbob: build needs a step number. Try: plumbbob build 2.\n');
         return 1;
     }
     const step = Number(raw);
-    const parsed = parseStepSeam(readFileSync(intentPath(root), 'utf8'), step);
+    const parsed = parseStepSeam(readFileSync(intentPath(root, slug), 'utf8'), step);
     if (!parsed.ok) {
         process.stderr.write(`plumbbob: ${parsed.error} Fix the step's seam in intent.md, then \`build ${step}\` again.\n`);
         return 1;
     }
-    writeFileSync(seamPath(root), `${parsed.seam.join('\n')}\n`);
-    writeFileSync(stepPath(root), `${step}\n`);
-    process.stdout.write(`plumbbob: building step ${step}. Seam (for orientation; not a lock in v2):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
+    writeFileSync(seamPath(root, slug), `${parsed.seam.join('\n')}\n`);
+    writeFileSync(stepPath(root, slug), `${step}\n`);
+    process.stdout.write(`plumbbob: building step ${step}. Seam (for orientation; not a lock):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;
 }

package/dist/verbs/check.js

@@ -1,17 +1,51 @@
-// `plumbbob check` — run the heavy gate (D16/D24) and report, with NO state
+// `plumbbob check` — run the heavy gate (D16/D24/D32) and report, with NO state
 // change. The read-only half of the verify tick: `/plumbbob:pb-verify` runs this before the
 // pause so the human approves on a known-green check. Exits with the check's own
-// code (0 = green).
+// code (0 = green, 1 = red, 2 = the gate itself broke).
+//
+// Narrowing flags for the iteration loop (`check --bail --only types,lint`) map
+// straight onto checkride's RunFlags (D32). Only this verb takes them — the
+// checkpoint gate is always full-fat.
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
-export function check(cwd) {
+export async function check(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
-    const code = runCheck(root);
-    process.stdout.write(code === 0 ? '\nplumbbob: check green.\n' : '\nplumbbob: check RED — fix it before checkpointing.\n');
+    const code = await runCheck(root, parseFlags(args));
+    process.stdout.write(verdictLine(code));
     return code;
 }
+// argv → CheckFlags: bare booleans plus comma-separated slot lists. Unknown
+// args are ignored rather than refused — the gate itself is the point.
+function parseFlags(args) {
+    return {
+        ...(args.includes('--bail') ? { bail: true } : {}),
+        ...(args.includes('--changed') ? { changed: true } : {}),
+        ...(args.includes('--all') ? { all: true } : {}),
+        ...slotList(args, '--only'),
+        ...slotList(args, '--skip'),
+        ...slotList(args, '--include'),
+    };
+}
+function slotList(args, flag) {
+    const i = args.indexOf(flag);
+    const value = i >= 0 ? args[i + 1] : undefined;
+    if (value === undefined || value.startsWith('--'))
+        return {};
+    const names = value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return names.length > 0 ? { [flag.slice(2)]: names } : {};
+}
+function verdictLine(code) {
+    if (code === 0)
+        return '\nplumbbob: check green.\n';
+    if (code === 2)
+        return '\nplumbbob: check ERROR — the gate itself broke; fix the harness before trusting green or red.\n';
+    return '\nplumbbob: check RED — fix it before checkpointing.\n';
+}

package/dist/verbs/checkpoint.js

@@ -1,5 +1,5 @@
 // `plumbbob checkpoint [<n>] [-m <msg>]` — the executor-agnostic commit tick (D3).
-// Unlike v1 `done`, it does NOT require a STEP file: the step is whatever you pass,
+// It does NOT require a STEP file: the step is whatever you pass,
 // else the in-flight STEP, else the next undone step in intent. It gates on a green
 // check, then commits any pending work (or records the existing HEAD when the tree
 // is already clean — the human's commit skill may have committed first), records the
@@ -8,30 +8,39 @@
 // `/plumbbob:pb-build`, your hands, a vibe session, or another harness all checkpoint
 // the same way.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { commit, findRepoRoot, headSha, isDirty, stageAll } from "../lib/git.js";
-import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, stepPath } from "../lib/sidecar.js";
+import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
+import { buildFolder, buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, stepPath } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
-import { markStepDone, parseSteps } from "../lib/orient.js";
+import { markStepDone, parseSteps, parseTitle } from "../lib/orient.js";
+import { parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { appendToSection, checkpointLogLine } from "../lib/buildlog.js";
-export function checkpoint(cwd, args) {
+export async function checkpoint(cwd, args) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
+    if (args.includes('--plan')) {
+        return checkpointPlan(root, args);
+    }
     const step = resolveStep(root, args);
     if (step === null) {
         process.stderr.write('plumbbob: no step to checkpoint — pass a number, or plan a step in intent.md first.\n');
         return 1;
     }
-    if (runCheck(root) !== 0) {
-        process.stderr.write('plumbbob: check failed (red) — checkpoint refuses on red. Fix it and re-run.\n');
+    const gate = await runCheck(root);
+    if (gate !== 0) {
+        process.stderr.write(gate === 2
+            ? 'plumbbob: the check gate itself broke — checkpoint refuses until the harness is fixed.\n'
+            : 'plumbbob: check failed (red) — checkpoint refuses on red. Fix it and re-run.\n');
         return 1;
     }
     let sha;
     if (isDirty(root)) {
         stageAll(root);
-        sha = commit(root, messageArg(args) ?? `plumbbob: step ${step} done`);
+        warnScopeDrift(root, step);
+        const body = bodyArg(args) ?? fallbackBody(root, step);
+        sha = commit(root, messageArg(args) ?? subjectForStep(root, step), body);
     }
     else {
         sha = headSha(root);
@@ -44,6 +53,32 @@ export function checkpoint(cwd, args) {
     process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. Back at the boundary.\n`);
     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
+// 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.
+function checkpointPlan(root, args) {
+    stagePath(root, buildFolder(root));
+    const sha = commit(root, planSubject(root), bodyArg(args) ?? undefined);
+    appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
+    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).
+function planSubject(root) {
+    let title = null;
+    try {
+        title = parseTitle(readFileSync(intentPath(root), 'utf8'));
+    }
+    catch {
+        title = null;
+    }
+    return title ? `plumbbob: plan — ${title}` : 'plumbbob: plan';
+}
 // Step resolution (D3): explicit arg > in-flight STEP file > first undone step in
 // intent.md. Returns null when none can be determined.
 function resolveStep(root, args) {
@@ -62,6 +97,38 @@ function resolveStep(root, args) {
         return null;
     }
 }
+// Guidance, not a gate (the enforce→guide pivot): warn when the staged tree reaches
+// beyond the step's seam, then commit anyway. The seam comes from the in-flight SEAM
+// file when a build is live, else the step's declared seam in intent.md. Plumbbob's
+// own artifact plane is whitelisted (`scopeDrift`), so the `[x]` flip and build-log
+// line this very checkpoint stages never read as drift. No seam ⇒ no warning.
+function warnScopeDrift(root, step) {
+    const seam = seamTokens(root, step);
+    const outside = scopeDrift(stagedPaths(root), seam);
+    if (outside.length > 0) {
+        process.stderr.write(`plumbbob: heads-up — staged paths outside step ${step}'s seam: ${outside.join(', ')}. ` +
+            `The checkpoint captures them; if that's real scope drift, the plan may need a \`/plumbbob:pb-step\` revision.\n`);
+    }
+}
+// The seam tokens for the in-flight step: the normalized SEAM file `build` wrote
+// (authoritative while a build is live), falling back to the step's declared seam
+// parsed from intent.md. Empty when neither resolves — the caller then skips the
+// warning rather than flagging the whole tree.
+function seamTokens(root, step) {
+    try {
+        const fromFile = readFileSync(seamPath(root), 'utf8')
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+        if (fromFile.length > 0) {
+            return fromFile;
+        }
+    }
+    catch {
+        // no SEAM file — fall through to the declared seam.
+    }
+    return seamForStep(root, step);
+}
 function flipIntent(root, step) {
     try {
         writeFileSync(intentPath(root), markStepDone(readFileSync(intentPath(root), 'utf8'), step));
@@ -71,7 +138,7 @@ function flipIntent(root, step) {
     }
 }
 // Append a dated line to the build-log's `## Log` so the build's history accrues at
-// each checkpoint instead of being reconstructed at wrap. The step's title is lifted
+// each checkpoint instead of being reconstructed at finish. The step's title is lifted
 // from intent.md when still present. Best-effort: a missing/odd build-log never blocks
 // a checkpoint — the `checkpoints` SHA is the source of truth.
 function logCheckpoint(root, step, sha) {
@@ -88,6 +155,13 @@ function logCheckpoint(root, step, sha) {
         // best-effort ledger; never fail a checkpoint over the build-log.
     }
 }
+// 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).
+function subjectForStep(root, step) {
+    const title = titleForStep(root, step);
+    return title ? `plumbbob: step ${step} — ${title}` : `plumbbob: step ${step} done`;
+}
 function titleForStep(root, step) {
     try {
         return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => s.n === step)?.title ?? null;
@@ -100,6 +174,68 @@ function messageArg(args) {
     const i = args.indexOf('-m');
     return i !== -1 && i + 1 < args.length ? (args[i + 1] ?? null) : null;
 }
+// `--body` reads the commit body from stdin (the single-quoted heredoc of D34),
+// so the skill can compose proportional prose the CLI never could. Returns null
+// when the flag is absent or stdin is empty — either way the deterministic
+// fallback body takes over. Reading fd 0 blocks until EOF, which the heredoc
+// supplies; a read error (no stdin attached) degrades to the fallback.
+function bodyArg(args) {
+    if (!args.includes('--body')) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(0, 'utf8').trimEnd();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The deterministic checkpoint body (D35): the step's done-when, its seam, and the
+// staged diffstat — so a hand-built or vibed checkpoint still gets informative
+// history without a model turn. Each part is best-effort; a missing piece is
+// simply omitted, and an empty result leaves the commit body blank.
+function fallbackBody(root, step) {
+    const parts = [];
+    const doneWhen = doneWhenForStep(root, step);
+    if (doneWhen !== null) {
+        parts.push(`done when: ${doneWhen}`);
+    }
+    const seam = seamForStep(root, step);
+    if (seam.length > 0) {
+        parts.push(`seam: ${seam.join(', ')}`);
+    }
+    const stat = safeStagedStat(root);
+    if (stat.length > 0) {
+        parts.push(stat);
+    }
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+function doneWhenForStep(root, step) {
+    try {
+        return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => s.n === step)?.doneWhen ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function seamForStep(root, step) {
+    try {
+        const parsed = parseStepSeam(readFileSync(intentPath(root), 'utf8'), step);
+        return parsed.ok ? parsed.seam : [];
+    }
+    catch {
+        return [];
+    }
+}
+function safeStagedStat(root) {
+    try {
+        return stagedStat(root);
+    }
+    catch {
+        return '';
+    }
+}
 function readStep(root) {
     try {
         const raw = readFileSync(stepPath(root), 'utf8').trim();