plumbbob 0.4.13 → 0.5.3

package/dist/verbs/start.js

@@ -4,12 +4,18 @@ import { fileURLToPath } from 'node:url';
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { findRepoRoot, hasCommit, headSha, isDirty } from "../lib/git.js";
-import { sidecarDir, checkpointsPath, configPath, intentPath, buildLogPath, beginSession, hasSession, excludeSidecar, } from "../lib/sidecar.js";
-const DEFAULT_CHECK = 'pnpm run check';
+import { sidecarDir, buildDir, listBuilds, slugify, checkpointsPath, intentPath, buildLogPath, beginSession, hasSession, excludeControl, excludeSidecar, } from "../lib/sidecar.js";
+import { settingsPath, setLocalSetting } from "../lib/settings.js";
+// D24/D32: the gate is checkride unless a `check` setting overrides it, so
+// settings.json seeds with no `check` key at all — absence IS the default. The
+// templates' {{CHECK}} line is a human-readable echo of that.
+const CHECK_ECHO = 'checkride (set a "check" key in .plumbbob/settings.json to override)';
 export function start(cwd, args) {
     const positionals = args.filter((a) => !a.startsWith('--'));
     const allowDirty = args.includes('--allow-dirty');
+    const local = args.includes('--local');
     const title = (positionals[0] ?? '').trim();
+    const slug = (flagValue(args, '--slug') ?? slugify(title)).trim();
     if (title.length === 0) {
         process.stderr.write('plumbbob: start needs a title. Try: plumbbob start "what you are building".\n');
         return 1;
@@ -34,31 +40,49 @@ export function start(cwd, args) {
         }
         process.stderr.write('plumbbob: WARNING --allow-dirty: recording HEAD as baseline with a dirty tree. A later revert-to-baseline will DISCARD the uncommitted work.\n');
     }
+    if (!local && slug.length === 0) {
+        process.stderr.write(`plumbbob: could not derive a build slug from "${title}". Pass --slug <name>, or retitle with letters or digits.\n`);
+        return 1;
+    }
+    if (!local && listBuilds(root).includes(slug)) {
+        process.stderr.write(`plumbbob: a build named "${slug}" already exists in .plumbbob/builds/. Retitle, or pass --slug <name> to choose another.\n`);
+        return 1;
+    }
     const sha = headSha(root);
-    const check = detectCheck(root);
     mkdirSync(sidecarDir(root), { recursive: true });
     beginSession(root);
-    writeFileSync(checkpointsPath(root), `baseline ${sha}\n`);
-    writeFileSync(configPath(root), `check=${check.command}\n`);
-    writeFileSync(intentPath(root), stamp(readTemplate('intent.md'), title, check.command));
-    writeFileSync(buildLogPath(root), stamp(readTemplate('build-log.md'), title, check.command));
-    excludeSidecar(root);
-    if (check.warn) {
-        process.stderr.write(`plumbbob: WARNING the heavy check '${check.command}' is not defined in this repo's package.json. Edit .plumbbob/config (check=...) to set the real gate before \`review\`/\`done\`.\n`);
+    writeFileSync(settingsPath(root), `${JSON.stringify({ auto: false }, null, 2)}\n`);
+    // D26: `--local` keeps today's fully-untracked flat layout (whole `.plumbbob/`
+    // excluded); the default plants a tracked, PR-riding `builds/<slug>/` folder
+    // (D26) and points the per-worktree cursor at it (D28), excluding only control
+    // files (D17). The slug is validated unique above — the CLI refuses, never
+    // suffixes (D38).
+    let intentLocation;
+    if (local) {
+        writeFileSync(checkpointsPath(root), `baseline ${sha}\n`);
+        writeFileSync(intentPath(root), stamp(readTemplate('intent.md'), title, CHECK_ECHO));
+        writeFileSync(buildLogPath(root), stamp(readTemplate('build-log.md'), title, CHECK_ECHO));
+        excludeSidecar(root);
+        intentLocation = '.plumbbob/intent.md';
     }
-    process.stdout.write(`plumbbob: started "${title}" — baseline ${sha.slice(0, 9)}. Frame and decide in .plumbbob/intent.md; \`build\` a step once the decisions are made.\n`);
+    else {
+        const dir = buildDir(root, slug);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'checkpoints'), `baseline ${sha}\n`);
+        writeFileSync(join(dir, 'intent.md'), stamp(readTemplate('intent.md'), title, CHECK_ECHO));
+        writeFileSync(join(dir, 'build-log.md'), stamp(readTemplate('build-log.md'), title, CHECK_ECHO));
+        setLocalSetting(root, 'activeBuild', slug);
+        excludeControl(root);
+        intentLocation = `.plumbbob/builds/${slug}/intent.md`;
+    }
+    process.stdout.write(`plumbbob: started "${title}" — baseline ${sha.slice(0, 9)}. Frame and decide in ${intentLocation}; \`build\` a step once the decisions are made.\n`);
     return 0;
 }
-// D24: default the heavy check to `pnpm run check`; warn (but still record it)
-// when the target repo has no such script, so a non-pnpm repo gets a clear nudge.
-function detectCheck(root) {
-    try {
-        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
-        return { command: DEFAULT_CHECK, warn: pkg.scripts?.check === undefined };
-    }
-    catch {
-        return { command: DEFAULT_CHECK, warn: true };
-    }
+// Read the value that follows a `--flag` in argv (e.g. `--slug my-build`), or
+// undefined when the flag is absent or trails with no value.
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
 }
 function readTemplate(name) {
     return readFileSync(fileURLToPath(new URL(`../../templates/${name}`, import.meta.url)), 'utf8');

package/dist/verbs/status.js

@@ -3,7 +3,7 @@
 // behavior, so the `NO ACTIVE SESSION` sentinel is kept exact.
 import { readFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, stepPath } from "../lib/sidecar.js";
+import { buildLogPath, checkpointsPath, hasSession, inSpike, intentPath, listBuilds, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { formatOrientation, orient } from "../lib/orient.js";
 function readOr(path) {
     try {
@@ -13,19 +13,30 @@ function readOr(path) {
         return '';
     }
 }
-export function status(cwd) {
+export function status(cwd, args = []) {
     const root = findRepoRoot(cwd);
     if (root === null || !hasSession(root)) {
         process.stdout.write('NO ACTIVE SESSION\n');
         return 0;
     }
-    const inFlightRaw = readOr(stepPath(root)).trim();
+    // A session with builds but no resolvable cursor (finish cleared it, or the repo
+    // holds several builds and none is active) has no single dashboard to show, so
+    // list the builds and point at `use` instead of rendering a broken, empty one.
+    const { build: slug } = resolveBuild(root, args);
+    if (slug === null) {
+        const builds = listBuilds(root);
+        if (builds.length > 0) {
+            process.stdout.write(`NO ACTIVE BUILD — pick one with \`plumbbob use <slug>\`:\n${builds.map((b) => `  ${b}`).join('\n')}\n`);
+            return 0;
+        }
+    }
+    const inFlightRaw = readOr(stepPath(root, slug)).trim();
     const orientation = orient({
-        intent: readOr(intentPath(root)),
-        buildLog: readOr(buildLogPath(root)),
-        checkpoints: readOr(checkpointsPath(root)),
+        intent: readOr(intentPath(root, slug)),
+        buildLog: readOr(buildLogPath(root, slug)),
+        checkpoints: readOr(checkpointsPath(root, slug)),
         inFlight: /^\d+$/.test(inFlightRaw) ? Number(inFlightRaw) : null,
-        spiking: inSpike(root),
+        spiking: inSpike(root, slug),
     });
     process.stdout.write(`${formatOrientation(orientation)}\n`);
     return 0;

package/dist/verbs/use.js

@@ -0,0 +1,44 @@
+// `plumbbob use <slug>` (D30) — re-point the per-worktree cursor at an existing
+// build and resume it. Both switching and resuming are the same one word (Q10,
+// `nvm use`-shaped): the cursor is a single scalar key in settings.local.json, so
+// pointing it elsewhere IS the switch and one-active-per-worktree holds by
+// construction (D28). It validates the target folder exists, and warns — but
+// allows — leaving a build with a step in flight: that surviving in-flight state
+// is D26's whole payoff, resumed the next time you `use` that build.
+import { existsSync } from 'node:fs';
+import { findRepoRoot } from "../lib/git.js";
+import { activeBuild, hasSession, intentPath, listBuilds, stepPath } from "../lib/sidecar.js";
+import { setLocalSetting } from "../lib/settings.js";
+export function use(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 builds = listBuilds(root);
+    const target = args.find((a) => !a.startsWith('--'));
+    if (target === undefined || target.length === 0) {
+        process.stderr.write(`plumbbob: use needs a build slug.${buildsHint(builds)}\n`);
+        return 1;
+    }
+    // Validate by the folder's intent.md, not the dir alone: an empty `builds/<slug>/`
+    // is not a resumable build, and the flat `--local` layout has no builds/ at all.
+    if (!existsSync(intentPath(root, target))) {
+        process.stderr.write(`plumbbob: no build named "${target}" in .plumbbob/builds/.${buildsHint(builds)}\n`);
+        return 1;
+    }
+    const leaving = activeBuild(root);
+    if (leaving !== null && leaving !== target && existsSync(stepPath(root, leaving))) {
+        process.stderr.write(`plumbbob: note — build "${leaving}" has a step in flight; its in-flight state is preserved ` +
+            `and resumes when you \`use ${leaving}\` again.\n`);
+    }
+    setLocalSetting(root, 'activeBuild', target);
+    const resuming = existsSync(stepPath(root, target)) ? ' (a step is in flight — `status` shows where)' : '';
+    process.stdout.write(`plumbbob: now on build "${target}"${resuming}. \`status\` to orient.\n`);
+    return 0;
+}
+// A trailing " Builds: a, b." hint when any exist, so a bad or missing slug points
+// the user straight at the valid choices.
+function buildsHint(builds) {
+    return builds.length > 0 ? ` Builds: ${builds.join(', ')}.` : '';
+}

package/hooks/post-edit.sh

@@ -1,14 +1,20 @@
 #!/bin/sh
 # post-edit.sh — light feedback (D25). PostToolUse, non-blocking, ALWAYS exits 0.
 # Runs file-scoped oxlint + ast-grep on the changed file and injects any failures
-# into the model's context via additionalContext (verified API, D3). No-ops when
+# into the model's context via additionalContext (verified API, D25). No-ops when
 # the tools are absent or there is no session. tsc is deferred to the heavy tier
 # (D25): it has no true single-file mode and would tax every keystroke.
 
+# The repo root is the nearest ancestor whose .plumbbob/settings.local.json carries
+# an `activeBuild` cursor — the per-worktree signal that a tracked build is live
+# here (D28). Grep the same way the file_path read below does: a plain pattern
+# match, no JSON parse. The cursor replaces the old .plumbbob/STATE probe as the
+# "a build is active here" root marker.
 find_root() {
   d=$(pwd -P)
   while [ -n "$d" ]; do
-    if [ -f "$d/.plumbbob/STATE" ]; then
+    if [ -f "$d/.plumbbob/settings.local.json" ] &&
+      grep -q '"activeBuild"' "$d/.plumbbob/settings.local.json" 2>/dev/null; then
       printf '%s' "$d"
       return 0
     fi
@@ -18,7 +24,7 @@ find_root() {
   return 1
 }
 
-root=$(find_root) || exit 0 # no session: no feedback
+root=$(find_root) || exit 0 # no active build here: no feedback
 
 input=$(cat)
 path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty' 2>/dev/null)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
-  "version": "0.4.13",
-  "description": "Attention-first build process: 11 skills + a CLI that keep you the decider — guidance, not enforcement.",
+  "version": "0.5.3",
+  "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance, not enforcement.",
   "keywords": [
     "claude-code",
     "claude",
@@ -43,22 +43,23 @@
   },
   "devDependencies": {
     "@ast-grep/cli": "^0.43.0",
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^24.0.0",
-    "knip": "^6.16.1",
-    "markdownlint-cli": "^0.48.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "fallow": "^2.103.0",
+    "markdownlint-cli2": "^0.22.1",
     "oxlint": "^1.69.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   },
+  "dependencies": {
+    "checkride": "0.1.6"
+  },
   "scripts": {
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.build.json",
-    "check": "pnpm run check:tsc && pnpm run check:oxlint && pnpm run check:astgrep && pnpm run check:test && pnpm run check:knip && pnpm run check:md",
-    "check:tsc": "tsc --noEmit",
-    "check:oxlint": "oxlint",
-    "check:astgrep": "ast-grep scan",
-    "check:test": "vitest run",
-    "check:knip": "knip",
-    "check:md": "markdownlint --config .markdownlint.jsonc \"**/*.md\" --ignore node_modules --ignore research"
+    "check": "checkride",
+    "test": "vitest run"
   }
 }

package/skills/pb-build/SKILL.md

@@ -27,7 +27,7 @@ at the pause for your approval. **Re-firing `/pb-build` is itself the clock tick
    the next undone, planned step in `.plumbbob/intent.md`. If there is no planned step
    to build, stop and tell the human to `/pb-step` first.
 2. **Enter the step.** Run `plumbbob build <n>` (records the in-flight STEP +
-   SEAM so `/pb-status` shows the step in flight; in v2 the seam is awareness, not a
+   SEAM so `/pb-status` shows the step in flight; the seam is awareness, not a
    lock).
 3. **Read the plan.** Read the step's **done-when**, its **seam**, and the
    **Decisions** and **Constraints** in `intent.md`. Build to *that* — the deciding
@@ -38,11 +38,17 @@ at the pause for your approval. **Re-firing `/pb-build` is itself the clock tick
    touching more than the seam, that is scope drift: surface it to the human rather
    than sprawling.
 5. **Verify, through to the pause.** Run the verify tick exactly as `/pb-verify`
-   does: `plumbbob check` → self-review the diff against the done-when, the
+   does: `plumbbob check` (on red, read `.check/summary.json` and the failing slot's
+   raw output under `.check/` for the actual diagnostics; while iterating on a fix,
+   narrow the loop with `plumbbob check --bail --only <slots>` — the checkpoint gate
+   still runs everything) → self-review the diff against the done-when, the
    Decisions, and the Constraints (a single structured read, D16) → validate → **PAUSE
    for the human's approval** → only on approval, checkpoint with
-   `plumbbob checkpoint` (which also appends this step to the build-log's `## Log` — the
-   history writes itself at each checkpoint, so you don't hand-log it). Do **not** bump
+   `plumbbob checkpoint <n> --body <<'BODY' … BODY` — a commit body **proportional to the
+   step** (a line for a trivial change, a short paragraph for a meatier one; no TIL scan,
+   no separate commit skill). The CLI owns the subject and appends this step to the
+   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.
 
 ## `--auto` — let the agent be the clock (opt-in)

package/skills/{pb-wrap → pb-finish}/SKILL.md

@@ -1,22 +1,25 @@
 ---
-name: pb-wrap
-description: Wrap up the build — write the report (what shipped, decisions, parked/harvested items, deferred tangents), then safely archive intent + build-log + report before clearing for a fresh goal. Archive-then-clear, never destroy. Report by default, no gate.
+name: pb-finish
+description: Finish the build — write the report (what shipped, decisions, parked/harvested items, deferred tangents), then make the final commit that closes the session. The build folder rides the branch into the PR — no separate archive. Report by default, no gate.
 disable-model-invocation: true
 model: opus
-allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob wrap:*)
+allowed-tools: Read, Write, Bash(plumbbob status:*), Bash(plumbbob finish:*)
 ---
 
-# PlumbBob — wrap the build (the close-out)
+# PlumbBob — finish the build (the close-out)
 
 Current session state (injected when this skill runs): !`plumbbob status 2>/dev/null || echo "plumbbob CLI not found - install the dep and re-run: npm i -g plumbbob && plumbbob init"`
 
-`/pb-wrap` ends the build: it captures what happened, archives it, and clears the
-sidecar for the next goal. **Report by default** (D9) — no refuse-without-report gate,
-and no separate docs phase.
+`/pb-finish` ends the build: it captures what happened, then makes the final commit
+that closes the session. **Report by default** (D9) — no refuse-without-report gate,
+and no separate docs phase. The build folder is tracked (D26/D29): it merges with the
+branch and shows up in the PR, so there is nothing to archive — the folder *is* the
+record.
 
 ## What this skill does, in order
 
-1. **Write the report** to `.plumbbob/report.md`, from `intent.md` + `build-log.md`.
+1. **Write the report** to the active build's `report.md`
+   (`.plumbbob/builds/<slug>/report.md`), from `intent.md` + `build-log.md`.
    The build-log's `## Log` is already the chronological history — `plumbbob checkpoint`
    wrote a dated line for every step as it landed. **Read it as the spine; do not
    re-narrate it.** The report adds only what the log does not already carry:
@@ -26,10 +29,11 @@ and no separate docs phase.
    - **Final status** — done or partial, and what is left.
    - **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. **Archive & clear.** Run `plumbbob wrap`, which appends the checkpoint SHAs
-   to the report, archives intent + build-log + report to
-   `.plumbbob/archive/<date>-<slug>/`, and clears the sidecar (STATE last). Git is not
-   touched.
+2. **Finish.** Run `plumbbob finish`, which appends the checkpoint SHAs to the
+   report and makes the final commit — subject `plumbbob: finish — <title>` (D34),
+   with an optional proportional body via `--body` (the D34 stdin heredoc) — then
+   clears the control state (markers, the `activeBuild` cursor, STATE last). The
+   build folder stays in place, committed, and rides the branch into the PR.
 3. **Point at the next goal** — `/pb-plan` to frame the next one.
 
 ## The hard contracts
@@ -37,9 +41,10 @@ and no separate docs phase.
 - **Report by default, never a gate.** Always offer the report; never wall the exit. A
   bug fix's report can be three lines — size it to the work.
 - **The log is the history; the report is the synthesis.** `checkpoint` already recorded
-  what shipped, step by step — wrap applies the *unique additions* (the why, the deferred
+  what shipped, step by step — finish applies the *unique additions* (the why, the deferred
   tangents, the final status), it does not rewrite the timeline.
-- **Archive-then-clear, never destroy** (C4). The archive is the record; the active
-  files only clear once they are safely copied.
+- **The folder is the archive, never destroy** (C4/D29). `finish` keeps intent +
+  build-log + report in `builds/<slug>/` and commits them; nothing is copied out and
+  nothing is deleted but the untracked control markers.
 - **No version bump, no docs phase.** Updating real docs is a separate, explicit ask;
   cutting a release is the human's `/version`.

package/skills/pb-plan/SKILL.md

@@ -4,7 +4,7 @@ description: "Frame a fresh goal and author the whole plan — Frame, Decisions,
 argument-hint: "[spec-path | intent]"
 disable-model-invocation: true
 model: opus
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*)
+allowed-tools: Read, Edit, Write, Bash(plumbbob status:*), Bash(plumbbob start:*), Bash(plumbbob checkpoint:*)
 ---
 
 # PlumbBob — plan a goal (the whole-goal move)
@@ -60,7 +60,14 @@ an agent can follow with `/pb-build`. The argument only seeds how you get there.
    paths it touches). Later steps may be fuzzier than the first — that's fine; they get
    sharpened just-in-time when you reach them with `/pb-step`. Keep each small enough to
    verify in one review pass.
-5. **Offer to stress-test it.** Suggest `/pb-refine` to attack the frame for holes (or
+5. **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
+   `checkpoints` (D36). 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
+   only on the human's approval — the plan is their convergence.
+6. **Offer to stress-test it.** Suggest `/pb-refine` to attack the frame for holes (or
    to repair the plan as it drifts). Optional, the human's call.
 
 ## The interview (mode 1)

package/skills/pb-verify/SKILL.md

@@ -16,9 +16,14 @@ this skill verifies it the same way: **it reads the diff, not the author** (D3).
 
 ## What this skill does, in order
 
-1. **Check.** Run `plumbbob check` (the heavy gate). If it comes back
-   **red**, stop here: report what failed and do **not** pause for approval — there
-   is nothing to approve yet. The human fixes it and re-invokes.
+1. **Check.** Run `plumbbob check` (the heavy gate — checkride unless the repo
+   configures a `check` override, D32). If it comes back **red**, stop here: the gate
+   names the failing slots and where each tool's raw output landed — read
+   `.check/summary.json`, then the failing slot's own file (`.check/<slot>.json` or
+   `.check/<slot>.stdout.txt`) for the actual diagnostics instead of scraping
+   scrollback. Report what failed and do **not** pause for approval — there is
+   nothing to approve yet. The human fixes it and re-invokes. (Exit 2 means the gate
+   itself broke — a harness problem to surface, not a code failure.)
 2. **Self-review** *(a single structured read, D16)*. Read `git diff` and
    `.plumbbob/intent.md`, then in one pass check the diff against:
    - the current step's **done-when** criterion — is it actually met?
@@ -29,10 +34,22 @@ this skill verifies it the same way: **it reads the diff, not the author** (D3).
 4. **PAUSE.** Present the check result, the self-review, 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.
-5. **Checkpoint** *(only after approval)*. Commit the work — the human's
-   commit-with-TIL skill for a rich message, or let `checkpoint` make the WIP commit
-   — then run `plumbbob checkpoint` to record the SHA, flip the step to done, append the
-   step to the build-log's `## Log`, and return to DESIGN. Do **not** bump the version or
+5. **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:
+
+   ```bash
+   plumbbob checkpoint <n> --body <<'BODY'
+   <your proportional body — what changed and why, no ceremony>
+   BODY
+   ```
+
+   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.
 
 ## The hard contracts

package/templates/build-log.md

@@ -6,7 +6,7 @@ step boundaries. The antidote to "my plan got lost in the noise."
   Park list : where ideas go so you do not chase them. CAPTURE, never act inline.
   Harvest   : the boundary ritual that keeps you on one branch.
   Log       : the build's history. `plumbbob checkpoint` appends a line per step as it
-              lands; feeds the /pb-wrap report, then gets archived.
+              lands; feeds the /pb-finish report, which rides the branch into the PR.
 -->
 
 # Build log — {{TITLE}}
@@ -52,5 +52,5 @@ Harvest results this boundary:
 every time a step lands — via `/pb-build` or `/pb-verify` — so this
 fills in as you go, not at the end. Add your own decision/event lines too: this is what
 you point at to say "I did that — the LLM helped, but those were my calls."
-`/pb-wrap` reads this for the report; `plumbbob wrap` archives it under
-`.plumbbob/archive/`.)*
+`/pb-finish` reads this for the report; `plumbbob finish` commits it with the build
+folder, so it rides the branch into the PR.)*

package/templates/intent.md

@@ -46,8 +46,8 @@ holes `/pb-refine` surfaces, and as blockers fold in during BUILD.)*
 
 *(The build plan. `/pb-plan` authors the **whole list up front** — each step a small,
 verifiable increment with its own **done-when** and **seam** (the paths it will touch,
-which `/pb-build` records in `.plumbbob/SEAM` for orientation — awareness, not a lock
-in v2). Then drive `/pb-build` until done. Later steps may be fuzzier than the first;
+which `/pb-build` records in the build folder's `SEAM` for orientation — awareness, not a lock).
+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.)*
 

package/dist/lib/archive.js

@@ -1,72 +0,0 @@
-// The finish-phase archive helper (D20: archive is local-only markdown in v1).
-// `finish` copies the three active files into .plumbbob/archive/<date>-<slug>/
-// before clearing the actives — "archive-then-clear, never destroy" (C4).
-// Functional/procedural, node builtins only (C1/C2).
-import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { sidecarDir, intentPath, buildLogPath } from "./sidecar.js";
-// report.md lives beside intent.md / build-log.md in the sidecar. It is written by
-// /plumbbob-report and is the gate `finish` refuses without (D19). Derived from
-// the exported sidecarDir so this module needs nothing new from sidecar.ts.
-export function reportPath(root) {
-    return join(sidecarDir(root), 'report.md');
-}
-function archiveRoot(root) {
-    return join(sidecarDir(root), 'archive');
-}
-// A filesystem-safe slug from arbitrary title text: lowercased, runs of
-// non-alphanumerics collapsed to a single hyphen, ends trimmed. Empty → `session`.
-function slugify(title) {
-    const slug = title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-    return slug.length === 0 ? 'session' : slug;
-}
-// The session title is intent.md's first `# ` heading (start stamps `# <title>`).
-function sessionTitle(root) {
-    let content = '';
-    try {
-        content = readFileSync(intentPath(root), 'utf8');
-    }
-    catch {
-        return 'session';
-    }
-    for (const line of content.split('\n')) {
-        const m = /^#\s+(.+)$/.exec(line);
-        if (m) {
-            return (m[1] ?? '').trim();
-        }
-    }
-    return 'session';
-}
-// Today as YYYY-MM-DD (UTC); the archive directory is <date>-<slug>.
-function today() {
-    return new Date().toISOString().slice(0, 10);
-}
-// Choose <date>-<slug>, disambiguating with -2, -3, … if a same-day, same-slug
-// session was already archived — so a second session lands ALONGSIDE the first,
-// never on top of it.
-function uniqueArchiveDir(root, base) {
-    let candidate = join(archiveRoot(root), base);
-    let n = 2;
-    while (existsSync(candidate)) {
-        candidate = join(archiveRoot(root), `${base}-${n}`);
-        n += 1;
-    }
-    return candidate;
-}
-// Copy intent + build-log + report into archive/<date>-<slug>/ and return the
-// directory created. Intent and build-log always exist in an active session; the
-// report is copied only when present — v2 `wrap` does not gate on it (D9), so a
-// close-out without a report still archives the rest.
-export function archiveSession(root) {
-    const dir = uniqueArchiveDir(root, `${today()}-${slugify(sessionTitle(root))}`);
-    mkdirSync(dir, { recursive: true });
-    copyFileSync(intentPath(root), join(dir, 'intent.md'));
-    copyFileSync(buildLogPath(root), join(dir, 'build-log.md'));
-    if (existsSync(reportPath(root))) {
-        copyFileSync(reportPath(root), join(dir, 'report.md'));
-    }
-    return dir;
-}

package/dist/verbs/wrap.js

@@ -1,55 +0,0 @@
-// `plumbbob wrap` (D9) — the v2 close-out, replacing the v1 four-verb
-// finish ceremony. It archives intent + build-log + report
-// (the `/plumbbob:pb-wrap` skill writes the report by default) under .plumbbob/archive/,
-// clears the active files, and deletes the control state (STATE last). Unlike v1
-// `finish` there is NO refuse-without-report gate — guidance offers the artifact, it
-// does not wall the exit. Archive-then-clear, never destroy (C4); git untouched (C5).
-import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import { findRepoRoot } from "../lib/git.js";
-import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, spikePath, stepPath } from "../lib/sidecar.js";
-import { archiveSession, reportPath } from "../lib/archive.js";
-export function wrap(cwd) {
-    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 (existsSync(reportPath(root))) {
-        appendCheckpointShas(root);
-    }
-    else {
-        process.stderr.write('plumbbob: note — no report.md found; archiving intent + build-log without one ' +
-            '(/plumbbob:pb-wrap normally writes the report first). No gate (D9).\n');
-    }
-    const archived = archiveSession(root);
-    // Clear the active files — now safely archived — then the control state, STATE
-    // last so "no session" flips exactly at the end.
-    rmSync(intentPath(root), { force: true });
-    rmSync(buildLogPath(root), { force: true });
-    rmSync(reportPath(root), { force: true });
-    rmSync(seamPath(root), { force: true });
-    rmSync(stepPath(root), { force: true });
-    rmSync(spikePath(root), { force: true });
-    rmSync(join(sidecarDir(root), 'STATE'), { force: true });
-    process.stdout.write(`plumbbob: wrap — archived to ${relative(root, archived)}. Sidecar cleared. ` +
-        'Run `/plumbbob:pb-plan` (or `plumbbob start "<title>"`) to frame the next goal.\n');
-    return 0;
-}
-// Append the recorded checkpoints (baseline + each `step n <sha>`) to the report so
-// the archived report lists the SHAs.
-function appendCheckpointShas(root) {
-    let raw = '';
-    try {
-        raw = readFileSync(checkpointsPath(root), 'utf8');
-    }
-    catch {
-        raw = '';
-    }
-    const lines = raw
-        .split('\n')
-        .map((l) => l.trim())
-        .filter((l) => l.length > 0)
-        .map((l) => `- ${l}`);
-    appendFileSync(reportPath(root), ['', '## Checkpoints', '', ...lines, ''].join('\n'));
-}