plumbbob 0.1.3 → 0.2.3

package/dist/verbs/start.js

@@ -0,0 +1,68 @@
+// `plumbbob start "<title>"` — scaffold the sidecar, record the baseline, enter
+// DESIGN. Refuses on a dirty tree (D22), an existing session, or a non-git dir.
+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, writeState, hasSession, excludeSidecar, } from "../lib/sidecar.js";
+const DEFAULT_CHECK = 'pnpm run check';
+export function start(cwd, args) {
+    const positionals = args.filter((a) => !a.startsWith('--'));
+    const allowDirty = args.includes('--allow-dirty');
+    const title = (positionals[0] ?? '').trim();
+    if (title.length === 0) {
+        process.stderr.write('plumbbob: start needs a title. Try: plumbbob start "what you are building".\n');
+        return 1;
+    }
+    const root = findRepoRoot(cwd);
+    if (root === null) {
+        process.stderr.write('plumbbob: not a git repository. Plumbbob records a baseline commit — run `git init` and make an initial commit first.\n');
+        return 1;
+    }
+    if (!hasCommit(root)) {
+        process.stderr.write('plumbbob: this repository has no commits yet. Make an initial commit so `start` can record a baseline.\n');
+        return 1;
+    }
+    if (hasSession(root)) {
+        process.stderr.write('plumbbob: a session is already active here. Run `plumbbob finish` to close it before starting another.\n');
+        return 1;
+    }
+    if (isDirty(root)) {
+        if (!allowDirty) {
+            process.stderr.write('plumbbob: the working tree is dirty. Commit or stash first, or `plumbbob start --allow-dirty "<title>"` to record the current HEAD as the baseline.\n');
+            return 1;
+        }
+        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');
+    }
+    const sha = headSha(root);
+    const check = detectCheck(root);
+    mkdirSync(sidecarDir(root), { recursive: true });
+    writeState(root, 'DESIGN');
+    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`);
+    }
+    process.stdout.write(`plumbbob: started "${title}" — STATE=DESIGN, baseline ${sha.slice(0, 9)}. Frame and decide in .plumbbob/intent.md; flip to BUILD only 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 };
+    }
+}
+function readTemplate(name) {
+    return readFileSync(fileURLToPath(new URL(`../../templates/${name}`, import.meta.url)), 'utf8');
+}
+function stamp(template, title, check) {
+    return template.split('{{TITLE}}').join(title).split('{{CHECK}}').join(check);
+}

package/dist/verbs/status.js

@@ -0,0 +1,13 @@
+// `plumbbob status` — print the session state, or NO ACTIVE SESSION. Read-only,
+// always exits 0. Skills pre-inject this output to gate their own behavior.
+import { findRepoRoot } from "../lib/git.js";
+import { hasSession, readState } from "../lib/sidecar.js";
+export function status(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stdout.write('NO ACTIVE SESSION\n');
+        return 0;
+    }
+    process.stdout.write(`STATE: ${readState(root) ?? 'UNKNOWN'}\n`);
+    return 0;
+}

package/dist/verbs/wrap.js

@@ -0,0 +1,28 @@
+// `plumbbob wrap` (D19/D28) — the FINISH-entry verb. Sets STATE=FINISH so
+// /plumbbob-report can write report.md and /plumbbob-docs can touch docs/.
+// `finish` stays the closing gate; wrap just opens the one state where
+// documentation may be projected. A transition the human fires — from a terminal
+// or, in-session, via the /pb-wrap driver skill (D21 revised).
+import { findRepoRoot } from "../lib/git.js";
+import { hasSession, readState, writeState } from "../lib/sidecar.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;
+    }
+    const state = readState(root);
+    if (state === 'FINISH') {
+        process.stdout.write('plumbbob: already in FINISH. Run `/plumbbob-report`, then `plumbbob finish` to close.\n');
+        return 0;
+    }
+    if (state !== 'DESIGN') {
+        process.stderr.write(`plumbbob: wrap enters FINISH from DESIGN (current state is ${state ?? 'UNKNOWN'}). ` +
+            'Close the current step first — `done` from BUILD/REVIEW, or `spike done` from SPIKE.\n');
+        return 1;
+    }
+    writeState(root, 'FINISH');
+    process.stdout.write('plumbbob: STATE=FINISH. Now `/plumbbob-report` writes the report (and `/plumbbob-docs` may touch docs/); ' +
+        'then `plumbbob finish` archives and closes.\n');
+    return 0;
+}

package/hooks/bash-guard.sh

@@ -47,7 +47,11 @@ esac
 case "$state" in
   BUILD | SPIKE) ;;
   *)
-    case "$command" in
+    # Strip redirects that can't write a real file (stderr merges, /dev/null
+    # sinks) so read-only commands aren't over-blocked. Any surviving `>` is a
+    # real write. The residual gap (e.g. `>/dev/nullEVIL`) is accepted (D21).
+    scrubbed=$(printf '%s' "$command" | sed 's/[0-9]*>&[0-9-]//g; s/&\{0,1\}[0-9]*>>* *\/dev\/null//g')
+    case "$scrubbed" in
       *">"* | *"tee "* | *"sed -i"* | *"git apply"*)
         deny "blocked: file-writing shell commands are not allowed in ${state:-?} (code edits happen in BUILD). Do not retry — park it or ask the human to \`plumbbob build <n>\`."
         ;;

package/hooks/pre-edit.sh

@@ -84,6 +84,23 @@ case "$rel" in
     ;;
 esac
 
+# The seam muzzle below governs repo code only (D23). A path *outside* the repo
+# (Claude's own plan-mode scratch in ~/.claude/plans, an editor tmpfile) and a
+# git-ignored path *inside* it (fallow data, dist/, coverage/) are none of its
+# business — never block them. `.plumbbob/` is itself git-ignored but is
+# plumbbob's own control surface, so its non-doc files (STATE/SEAM/...) must stay
+# governed by the muzzle, never skipped here.
+case "$rel" in
+  .plumbbob/*) ;; # control state: stays governed by the muzzle, never skipped
+  *)
+    # git resolves the path via the repo toplevel (robust to symlinked cwds).
+    # check-ignore exit: 0 = ignored, 128 = outside the repo — neither is the
+    # muzzle's business; 1 = in-repo, tracked territory -> fall through to it.
+    git -C "$root" check-ignore -q -- "$path" 2>/dev/null
+    [ "$?" -ne 1 ] && exit 0
+    ;;
+esac
+
 # 4. Everything else is code: allowed only in BUILD, confined to the SEAM (D23).
 #    SPIKE locks the main tree like DESIGN (D18) — spike edits live in dormant
 #    worktrees, so the muzzle never needs to allow SPIKE here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.1.3",
+  "version": "0.2.3",
   "description": "Attention-first build process: a CLI + hooks that enforce the deciding/executing boundary.",
   "keywords": [
     "claude-code",
@@ -20,11 +20,11 @@
   "license": "Apache-2.0",
   "author": "Rob McLarty <hello@robmclarty.com>",
   "bin": {
-    "plumbbob": "src/cli.ts",
-    "pb": "src/cli.ts"
+    "plumbbob": "dist/cli.js",
+    "pb": "dist/cli.js"
   },
   "files": [
-    "src",
+    "dist",
     "hooks",
     "skills",
     "templates"
@@ -49,6 +49,8 @@
     "vitest": "^4.1.8"
   },
   "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",

package/skills/park/SKILL.md

@@ -3,12 +3,12 @@ name: park
 description: Compose one tidy tagged park line, get the human's OK in-turn, then capture it by shelling `plumbbob park` — never by editing a file.
 disable-model-invocation: true
 model: haiku
-allowed-tools: Bash(plumbbob status:*), Bash(plumbbob park:*)
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ park:*)
 ---
 
 # Park
 
-Current session state (injected when this skill runs): !`plumbbob status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
 
 ## Wrong-state refusal
 
@@ -19,8 +19,8 @@ Parking needs an **active session** to capture into. Read the state injected abo
 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:
 
 1. **Show the composed line to the human** and wait for **in-turn approval** — they confirm it as-is or edit the wording.
-2. **Only after** that approval, capture it by running `plumbbob park "<the approved line>"` via Bash.
+2. **Only after** that approval, capture it by running `__PLUMBBOB_BIN__ park "<the approved line>"` via Bash.
 
 ## The one hard contract
 
-The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and no Write tool** on purpose (D12): you may not append to `build-log.md` yourself. Compose, get approval, then shell `plumbbob park` — that is the only write path. If approval never comes, capture nothing.
+The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and no Write tool** on purpose (D12): you may not append to `build-log.md` yourself. Compose, get approval, then shell `__PLUMBBOB_BIN__ park` — that is the only write path. If approval never comes, capture nothing.

package/skills/pb-build/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: pb-build
+description: Human-triggered driver for `plumbbob build <n>` — write the SEAM for a step and enter BUILD (edits unlocked to those paths only), from the chat.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ build:*)
+---
+
+# Plumbbob — build a step (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob build` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Read the step number from the way you were invoked (e.g. `/pb-build 3` → step `3`). If no number is present, ask for one and run nothing.
+2. Run `__PLUMBBOB_BIN__ build <n>` via Bash.
+3. Report the verb's output verbatim — the SEAM it wrote and the new state, or any refusal.

package/skills/pb-done/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pb-done
+description: Human-triggered driver for `plumbbob done` — ensure the check is green, take the checkpoint commit, record its SHA, and return to DESIGN.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ done:*)
+---
+
+# Plumbbob — finish a step (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob done` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Run `__PLUMBBOB_BIN__ done` via Bash.
+2. Report the verb's output verbatim — the checkpoint SHA and return to DESIGN, or any refusal (e.g. the check is red).

package/skills/pb-finish/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pb-finish
+description: Human-triggered driver for `plumbbob finish` — refuse unless a report is archived, then archive, clear the session, and switch the muzzle off.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ finish:*)
+---
+
+# Plumbbob — finish the session (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob finish` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Run `__PLUMBBOB_BIN__ finish` via Bash.
+2. Report the verb's output verbatim. It is the closing gate — it **refuses unless `.plumbbob/report.md` exists**. If it refuses, relay that and tell the human to run `/plumbbob-report` first; do not write the report yourself from here.

package/skills/pb-revert/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: pb-revert
+description: Human-triggered driver for `plumbbob revert` — git reset --hard to a checkpoint SHA (discarding the half-done step) and return to DESIGN.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ revert:*)
+---
+
+# Plumbbob — revert to a checkpoint (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob revert` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Read an optional target step from the way you were invoked (e.g. `/pb-revert --to 2` → step `2`). With no target, revert goes to the last done-checkpoint.
+2. Run `__PLUMBBOB_BIN__ revert` (or `__PLUMBBOB_BIN__ revert --to <n>`) via Bash. This is a `git reset --hard` — it discards the current in-progress step. Run it exactly as the human asked; do not add or drop the `--to` on your own.
+3. Report the verb's output verbatim — which checkpoint it reset to, or any refusal.

package/skills/pb-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pb-review
+description: Human-triggered driver for `plumbbob review` — run the heavy check and, if green, flip to REVIEW (muzzle back on) to read the diff cold.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ review:*)
+---
+
+# Plumbbob — review a step (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob review` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Run `__PLUMBBOB_BIN__ review` via Bash.
+2. Report the verb's output verbatim. If the heavy check is red the verb stays in BUILD and prints the failures — relay them and stop; fixing them is the human's call, not an automatic retry.

package/skills/pb-spike/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: pb-spike
+description: Human-triggered driver for `plumbbob spike` — open a throwaway worktree experiment for a genuine fork, or tear it down with `spike done`.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ spike:*)
+---
+
+# Plumbbob — spike an experiment (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob spike` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Read the spike target from the way you were invoked: a slug to open one (e.g. `/pb-spike redis-cache`), or the literal `done` to tear the current spike down (`/pb-spike done`). If neither is present, ask which and run nothing.
+2. Run `__PLUMBBOB_BIN__ spike "<slug>"` or `__PLUMBBOB_BIN__ spike done` via Bash.
+3. Report the verb's output verbatim — the worktree it created or removed, or any refusal.

package/skills/pb-start/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: pb-start
+description: Human-triggered driver for `plumbbob start` — scaffold a new session (.plumbbob/, STATE=DESIGN, baseline commit) without leaving the chat.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ start:*)
+---
+
+# Plumbbob — start a session (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob start` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Read the session title from the way you were invoked (e.g. `/pb-start "fix the widget"` → title `fix the widget`). If no title is present, ask for one and run nothing.
+2. Run `__PLUMBBOB_BIN__ start "<title>"` via Bash.
+3. Report the verb's output verbatim. If it refuses (e.g. a session already exists), relay that and stop.

package/skills/pb-wrap/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: pb-wrap
+description: Human-triggered driver for `plumbbob wrap` — set STATE=FINISH so the report and docs skills can run.
+disable-model-invocation: true
+model: haiku
+allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ wrap:*)
+---
+
+# Plumbbob — wrap into FINISH (driver)
+
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
+
+This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob wrap` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
+
+## What it does
+
+1. Run `__PLUMBBOB_BIN__ wrap` via Bash.
+2. Report the verb's output verbatim. FINISH is what unlocks `/plumbbob-report` and `/plumbbob-docs` — next, run `/plumbbob-report`.

package/skills/plumbbob-docs/SKILL.md

@@ -3,12 +3,12 @@ name: plumbbob-docs
 description: FINISH-phase, optional docs update — conservatively project canonical intent into real docs/, only when warranted.
 disable-model-invocation: true
 model: opus
-allowed-tools: Read, Edit, Write, Bash(plumbbob status:*)
+allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*)
 ---
 
 # Plumbbob — update the docs
 
-Current session state (injected when this skill runs): !`plumbbob status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
 
 ## Wrong-state refusal
 

package/skills/plumbbob-interrogate/SKILL.md

@@ -3,12 +3,12 @@ name: plumbbob-interrogate
 description: DESIGN-phase frame interrogation — attack the plan for holes and append them as Open questions, without deciding anything.
 disable-model-invocation: true
 model: opus
-allowed-tools: Read, Edit, Bash(plumbbob status:*)
+allowed-tools: Read, Edit, Bash(__PLUMBBOB_BIN__ status:*)
 ---
 
 # Plumbbob — interrogate the frame
 
-Current session state (injected when this skill runs): !`plumbbob status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
 
 ## Wrong-state refusal
 

package/skills/plumbbob-report/SKILL.md

@@ -3,12 +3,12 @@ name: plumbbob-report
 description: FINISH-phase report — synthesize intent + build-log into exactly .plumbbob/report.md with the five required sections.
 disable-model-invocation: true
 model: opus
-allowed-tools: Read, Write, Bash(plumbbob status:*)
+allowed-tools: Read, Write, Bash(__PLUMBBOB_BIN__ status:*)
 ---
 
 # Plumbbob — write the report
 
-Current session state (injected when this skill runs): !`plumbbob status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
 
 ## Wrong-state refusal
 

package/skills/plumbbob-triage/SKILL.md

@@ -3,12 +3,12 @@ name: plumbbob-triage
 description: DESIGN-phase, step-boundary triage — propose one class per parked item, write only after the human confirms each.
 disable-model-invocation: true
 model: opus
-allowed-tools: Read, Edit, Bash(plumbbob status:*)
+allowed-tools: Read, Edit, Bash(__PLUMBBOB_BIN__ status:*)
 ---
 
 # Plumbbob — triage the park list
 
-Current session state (injected when this skill runs): !`plumbbob status`
+Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
 
 ## Wrong-state refusal
 

package/src/cli.ts

@@ -1,121 +0,0 @@
-#!/usr/bin/env node
-// plumbbob CLI — hand-rolled argv dispatch, zero runtime deps, node: builtins
-// only (D1/C2). Functional/procedural: no classes, no `this`, no default
-// export (C1). Verbs are wired up build step by build step.
-
-import { start } from './verbs/start.ts'
-import { status } from './verbs/status.ts'
-import { mode } from './verbs/mode.ts'
-import { park } from './verbs/park.ts'
-import { build } from './verbs/build.ts'
-import { review } from './verbs/review.ts'
-import { done } from './verbs/done.ts'
-import { revert } from './verbs/revert.ts'
-import { spike } from './verbs/spike.ts'
-import { wrap } from './verbs/wrap.ts'
-import { finish } from './verbs/finish.ts'
-import { setup } from './verbs/setup.ts'
-
-type Verb = {
-  readonly name: string
-  readonly summary: string
-}
-
-const VERBS: ReadonlyArray<Verb> = [
-  { name: 'start', summary: 'scaffold .plumbbob/; STATE=DESIGN; record the baseline commit' },
-  { name: 'status', summary: 'print the session state, or NO ACTIVE SESSION' },
-  { name: 'build', summary: 'build <n>: write SEAM from step n; STATE=BUILD' },
-  { name: 'review', summary: 'run the heavy check; if green flip to STATE=REVIEW' },
-  { name: 'done', summary: 'ensure check green; checkpoint commit + record SHA; STATE=DESIGN' },
-  { name: 'revert', summary: 'revert [--to n]: git reset --hard to a checkpoint SHA; STATE=DESIGN' },
-  { name: 'park', summary: 'park "<text>": append a raw line to the park list' },
-  { name: 'spike', summary: 'spike "<slug>" | spike done: throwaway worktree experiment' },
-  { name: 'wrap', summary: 'set STATE=FINISH so /plumbbob-report and /plumbbob-docs can run' },
-  { name: 'finish', summary: 'refuse unless a report is archived; archive; clear; muzzle off' },
-  { name: 'mode', summary: 'mode <x>: set STATE directly (hidden escape hatch)' },
-  { name: 'setup', summary: 'install hooks + skills; register them (default global; --project / --local per D27)' },
-]
-
-// D21: deciding/transition verbs are human-only. In a Claude Code session
-// (CLAUDECODE set) the dispatch refuses them so the model cannot drive a state
-// transition. `park` and `status` are the deliberate exceptions — dumb capture
-// and read-only inspection are model-safe.
-const TRANSITION_VERBS: ReadonlySet<string> = new Set([
-  'start',
-  'build',
-  'review',
-  'done',
-  'revert',
-  'spike',
-  'wrap',
-  'finish',
-  'mode',
-])
-
-function formatHelp(): string {
-  const width = Math.max(...VERBS.map((v) => v.name.length))
-  const rows = VERBS.map((v) => `  ${v.name.padEnd(width)}  ${v.summary}`)
-  return ['plumbbob — attention-first build process', '', 'Usage: plumbbob <verb> [args]', '', 'Verbs:', ...rows, ''].join(
-    '\n',
-  )
-}
-
-function dispatch(verb: string, cwd: string, rest: ReadonlyArray<string>): number {
-  switch (verb) {
-    case 'start':
-      return start(cwd, rest)
-    case 'status':
-      return status(cwd)
-    case 'mode':
-      return mode(cwd, rest)
-    case 'park':
-      return park(cwd, rest)
-    case 'build':
-      return build(cwd, rest)
-    case 'review':
-      return review(cwd)
-    case 'done':
-      return done(cwd)
-    case 'revert':
-      return revert(cwd, rest)
-    case 'spike':
-      return spike(cwd, rest)
-    case 'wrap':
-      return wrap(cwd)
-    case 'finish':
-      return finish(cwd)
-    case 'setup':
-      return setup(cwd, rest)
-    default:
-      process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`)
-      return 1
-  }
-}
-
-function run(argv: ReadonlyArray<string>): number {
-  const verb = argv[0] ?? 'help'
-  const rest = argv.slice(1)
-
-  if (verb === 'help' || verb === '--help' || verb === '-h') {
-    process.stdout.write(`${formatHelp()}\n`)
-    return 0
-  }
-
-  if (TRANSITION_VERBS.has(verb) && process.env.CLAUDECODE) {
-    process.stderr.write(
-      `plumbbob: '${verb}' is a deciding verb — only the human runs it (you appear to be in a Claude Code session). ` +
-        `Do not retry. Ask the human to run \`plumbbob ${verb}\` in their terminal.\n`,
-    )
-    return 1
-  }
-
-  try {
-    return dispatch(verb, process.cwd(), rest)
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err)
-    process.stderr.write(`plumbbob: ${verb} failed: ${message}\n`)
-    return 1
-  }
-}
-
-process.exit(run(process.argv.slice(2)))

package/src/lib/archive.ts

@@ -1,76 +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.ts'
-
-// 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: string): string {
-  return join(sidecarDir(root), 'report.md')
-}
-
-function archiveRoot(root: string): string {
-  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: string): string {
-  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: string): string {
-  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(): string {
-  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: string, base: string): string {
-  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. The report must already exist (finish guards that); intent
-// and build-log always exist in an active session.
-export function archiveSession(root: string): string {
-  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'))
-  copyFileSync(reportPath(root), join(dir, 'report.md'))
-  return dir
-}