plumbbob 0.1.3 → 0.2.3

package/README.md

@@ -21,46 +21,66 @@ own enforcement from step 5 onward.
   guard, and a non-blocking light-feedback pass. With no active session they
   short-circuit to allow in microseconds, so a repo without a Plumbbob session
   behaves like plain Claude Code.
-- Five Claude Code skills — the judgment work, each one human-triggered
+- The judgment skills — the design/finish thinking work, each human-triggered
   (`disable-model-invocation: true`): `/plumbbob-interrogate`, `/park`,
   `/plumbbob-triage`, `/plumbbob-report`, `/plumbbob-docs`.
+- The `pb-*` driver skills — thin chat-side triggers for the transition verbs
+  (`/pb-start`, `/pb-build`, `/pb-review`, `/pb-done`, `/pb-revert`, `/pb-wrap`,
+  `/pb-finish`, `/pb-spike`), also `disable-model-invocation: true`, so you can
+  drive the whole loop from the agent window without leaving for a terminal.
 - A `.plumbbob/` sidecar of flat control files (`STATE`, `SEAM`, `checkpoints`,
   `intent.md`, `build-log.md`) that the hooks read with a grep.
 
 ## Install
 
-The npm package is `plumbbob` (the npm name `plumbbob` was taken); it installs
-the CLI as `plumbbob` plus a `pb` shorthand:
+The npm package is `plumbbob`; it installs the CLI as `plumbbob` plus a `pb`
+shorthand, and ships the hooks and skills inside the package. There are two
+install shapes: project-level (self-contained, nothing global) and global.
+
+### Project-level (recommended) — nothing under `~`
+
+Add Plumbbob as a dev dependency and set it up self-contained, so everything
+lives in the repo and `node_modules` with no global install to manage:
 
 ```sh
-npm install -g plumbbob
+pnpm add -D plumbbob
+pnpm exec plumbbob setup --local   # or just `setup` — it auto-detects a project-local install
 ```
 
-`plumbbob setup` copies the hooks to `~/.claude/plumbbob/hooks/` and the skills
-to `~/.claude/skills/`, then registers the hooks in a Claude Code settings file.
-The hooks and skills always install once under `~/.claude/`; the registration
-scope is a sharing choice, not a behavior choice.
+A self-contained `setup` writes **nothing** under `~/.claude`. It copies the
+skills into `<repo>/.claude/skills/` (with their bin invocation pointed at the
+project-local `node_modules/.bin/plumbbob`) and registers the hooks in place at
+`$CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks/`.
 
-| Command                    | Registers in                         | Use for                              |
-|----------------------------|--------------------------------------|--------------------------------------|
-| `plumbbob setup`          | `~/.claude/settings.json`            | yourself, across every repo (default) |
-| `plumbbob setup --project`| `<repo>/.claude/settings.json`       | enrolling a whole team (committable)  |
-| `plumbbob setup --local`  | `<repo>/.claude/settings.local.json` | yourself, this repo only (untracked)  |
+| Command                              | Registers in                         | Use for                          |
+|--------------------------------------|--------------------------------------|----------------------------------|
+| `pnpm exec plumbbob setup --local`   | `<repo>/.claude/settings.local.json` | yourself, this repo (untracked)  |
+| `pnpm exec plumbbob setup --project` | `<repo>/.claude/settings.json`       | enrolling a team (committable)   |
 
-The repo-scoped files register `~`-prefixed command paths, so committed settings
-carry no machine-absolute home directory — a teammate without Plumbbob installed
-gets a non-blocking hook error, not a wall. `plumbbob setup --uninstall` strips
-the registration (the installed files stay in place).
+Both forms address the hooks and the skill bin through `$CLAUDE_PROJECT_DIR`, so
+a committed `settings.json` carries no machine-absolute path — a teammate runs
+`pnpm install` and re-runs `setup` to regenerate their skills copy.
 
-After installing, restart Claude Code (or reload settings) for the hooks to take
-effect. The npm install puts `plumbbob` on your `PATH`, which the skills' status
-pre-injection needs to resolve; from a dev checkout, alias it at the CLI entry
-point instead:
+### Global — one install, every repo
+
+```sh
+npm install -g plumbbob
+plumbbob setup --global
+```
+
+`setup --global` copies the hooks to `~/.claude/plumbbob/hooks/` and the skills
+to `~/.claude/skills/`, then registers absolute command paths in
+`~/.claude/settings.json`. The skills call a bare `plumbbob`, which the global
+install puts on your `PATH`; from a dev checkout, alias it instead:
 
 ```sh
 alias plumbbob='node /path/to/plumbbob/src/cli.ts'
 ```
 
+`plumbbob setup --uninstall` (with the same scope flag) strips the registration;
+the installed/copied files stay in place. After installing, restart Claude Code
+(or reload settings) for the hooks to take effect.
+
 ## The verbs and skills
 
 Mechanical verbs are the `plumbbob` CLI, run from your terminal. The judgment
@@ -83,10 +103,26 @@ work is skills, invoked from the chat pane. The split is judgment-vs-mechanism.
 | `plumbbob finish`         | refuse unless a report exists; archive; clear; muzzle off        | CLI           |
 | `plumbbob spike "<slug>"` | throwaway worktree experiment per option; `spike done` tears down | CLI          |
 | `plumbbob mode <x>`       | escape hatch: set `STATE` directly (not part of the normal flow) | CLI (hidden)  |
-| `plumbbob setup`          | install hooks + skills; register them (D27 scopes above)         | CLI           |
-
-In a Claude Code session the deciding/transition verbs refuse to run (they are
-yours to type in a terminal); `status` and `park` are the deliberate exceptions.
+| `plumbbob setup`          | install hooks + skills; register them (install shapes above)     | CLI           |
+
+### Driving the transitions from the chat
+
+Every transition verb also has a thin `pb-*` driver skill, so you can run the
+whole loop from the agent window without switching to a terminal: `/pb-start`,
+`/pb-build`, `/pb-review`, `/pb-done`, `/pb-revert`, `/pb-wrap`, `/pb-finish`,
+`/pb-spike`. Each shells exactly its verb and reports the result verbatim; each is
+`disable-model-invocation: true`, so *only you* can fire it.
+
+The boundary the one law protects is **human-initiated vs model-initiated**, not
+terminal-vs-chat. A `disable-model-invocation` skill is a human trigger that
+happens to live in the chat: the model can never invoke it, the deciding still
+happens in `intent.md`, and the verb is still dumb mechanism. So the transition
+verbs run in-session now (a terminal still works too) — the lone hold-out is
+`mode`, the escape hatch, which stays human-only (refused in-session, and blocked
+from the model's shell by the Bash guard). The transition verbs are deliberately
+kept out of your settings allowlist, so a stray *model-initiated* transition
+surfaces a Claude Code permission prompt; each driver skill self-authorizes only
+its own verb, only while you are running it.
 
 ## The core / adapter boundary
 
@@ -119,8 +155,15 @@ These are deliberate v1 boundaries, decided on the record, not oversights:
 ```sh
 pnpm install
 pnpm check     # tsc, oxlint, ast-grep, vitest, knip, markdownlint
+pnpm build     # emit dist/ (what the published bin runs); prepack runs this for you
 ```
 
+The published `bin` (`plumbbob` / `pb`) points at `dist/cli.js`, not the `.ts`
+source, so a fresh install runs under plain `node` without `tsx`. The `prepack`
+hook rebuilds `dist/` before every pack/publish; you only need `pnpm build` by
+hand when you want to run the compiled output locally. From a dev checkout the
+source still runs directly (`node src/cli.ts`) via Node's type stripping.
+
 **The pnpm pin.** `package.json` pins `devEngines.packageManager` to an *exact*
 pnpm version (`11.1.2`) rather than a range, because the `^` range broke every
 pnpm command at the time of writing. That exact pin will need bumping by hand on
@@ -128,7 +171,7 @@ the next pnpm upgrade; moving back to a ranged constraint is a future revisit.
 
 `scripts/dev-install.sh` is the development installer: it registers the hooks
 pointing at this working tree's `hooks/` (so hook edits take effect with no
-re-copy), where `plumbbob setup` copies them into `~/.claude/`. Use
+re-copy), where `plumbbob setup --global` copies them into `~/.claude/`. Use
 `dev-install.sh` while hacking on the hooks themselves; use `plumbbob setup` to
 install Plumbbob for real.
 

package/dist/cli.js

@@ -0,0 +1,99 @@
+#!/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.js";
+import { status } from "./verbs/status.js";
+import { mode } from "./verbs/mode.js";
+import { park } from "./verbs/park.js";
+import { build } from "./verbs/build.js";
+import { review } from "./verbs/review.js";
+import { done } from "./verbs/done.js";
+import { revert } from "./verbs/revert.js";
+import { spike } from "./verbs/spike.js";
+import { wrap } from "./verbs/wrap.js";
+import { finish } from "./verbs/finish.js";
+import { setup } from "./verbs/setup.js";
+const VERBS = [
+    { 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 (self-contained per-project by default; --global for ~/.claude)' },
+];
+// D21 (revised): the human owns every transition — but the trigger surface is no
+// longer "terminal vs chat", it is "human-initiated vs model-initiated". The
+// human now fires transitions from the chat through the `pb-*` driver skills
+// (`disable-model-invocation: true`, so the model can never invoke them) just as
+// well as from a terminal, so the blanket in-session refusal is gone. The lone
+// hold-out is `mode`, the hidden escape hatch for desyncs: it stays human-only,
+// refused in-session (CLAUDECODE set) and also blocked from the model's shell by
+// bash-guard.sh. A stray model-initiated transition is caught by Claude Code's
+// permission prompt, since the transition verbs are deliberately kept out of the
+// settings allowlist (only each driver skill self-authorizes its own verb).
+const HUMAN_ONLY_VERBS = new Set(['mode']);
+function formatHelp() {
+    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, cwd, rest) {
+    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) {
+    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 (HUMAN_ONLY_VERBS.has(verb) && process.env.CLAUDECODE) {
+        process.stderr.write(`plumbbob: '${verb}' is the human's escape hatch, not a model action (you appear to be in a Claude Code session). ` +
+            `Do not retry. Ask the human to run \`plumbbob ${verb}\` themselves.\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/dist/lib/archive.js

@@ -0,0 +1,69 @@
+// 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. The report must already exist (finish guards that); intent
+// and build-log always exist in an active session.
+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'));
+    copyFileSync(reportPath(root), join(dir, 'report.md'));
+    return dir;
+}

package/dist/lib/check.js

@@ -0,0 +1,26 @@
+// The heavy check (D16/D24): the full gate that `review` and `done` refuse to
+// advance past while red. The command is read from `.plumbbob/config` (`check=`)
+// so non-pnpm repos gate too; tests point it at a stub (`true`/`false`) since a
+// real `pnpm check` would recurse into vitest (D14).
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { configPath } from "./sidecar.js";
+const DEFAULT_CHECK = 'pnpm run check';
+function readCheckCommand(root) {
+    let config = '';
+    try {
+        config = readFileSync(configPath(root), 'utf8');
+    }
+    catch {
+        return DEFAULT_CHECK;
+    }
+    const line = config.split('\n').find((l) => l.startsWith('check='));
+    return line === undefined ? DEFAULT_CHECK : line.slice('check='.length).trim();
+}
+// Runs the configured check in `root`, streaming its output to the terminal so
+// the human sees what failed. Returns the exit code (0 = green).
+export function runCheck(root) {
+    const command = readCheckCommand(root);
+    const result = spawnSync(command, { cwd: root, shell: true, stdio: 'inherit' });
+    return result.status ?? 1;
+}

package/dist/lib/git.js

@@ -0,0 +1,62 @@
+// Thin git wrapper over `node:child_process` (C2: node builtins only, zero
+// runtime deps). Functional/procedural, no classes (C1). Plumbbob's git
+// footprint is additive (C5); these helpers only read and locate.
+import { execFileSync } from 'node:child_process';
+function runGit(root, args) {
+    return execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+}
+// The git toplevel for `cwd`, or null when `cwd` is not inside a git repo.
+export function findRepoRoot(cwd) {
+    try {
+        return runGit(cwd, ['rev-parse', '--show-toplevel']);
+    }
+    catch {
+        return null;
+    }
+}
+// Absolute path to the .git directory (handles worktrees/linked git dirs).
+export function gitDir(root) {
+    return runGit(root, ['rev-parse', '--absolute-git-dir']);
+}
+export function headSha(root) {
+    return runGit(root, ['rev-parse', 'HEAD']);
+}
+export function hasCommit(root) {
+    try {
+        runGit(root, ['rev-parse', '--verify', 'HEAD']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Dirty = any tracked change or non-ignored untracked file. The sidecar is
+// git-excluded (D17), so an active session never reads as dirty.
+export function isDirty(root) {
+    return runGit(root, ['status', '--porcelain']).length > 0;
+}
+// --- mutation helpers (build-loop: done checkpoints, revert resets). Additive
+// only (C5): stage/commit forward, reset --hard to a recorded checkpoint SHA. ---
+export function stageAll(root) {
+    runGit(root, ['add', '-A']);
+}
+export function stagedPaths(root) {
+    const out = runGit(root, ['diff', '--cached', '--name-only']);
+    return out.length === 0 ? [] : out.split('\n');
+}
+export function untrackedPaths(root) {
+    const out = runGit(root, ['ls-files', '--others', '--exclude-standard']);
+    return out.length === 0 ? [] : out.split('\n');
+}
+// Commit whatever is staged as a checkpoint and return its SHA. --allow-empty so
+// a step that touched only ignored files still gets a checkpoint to revert to.
+export function commit(root, message) {
+    runGit(root, ['commit', '--allow-empty', '-m', message]);
+    return headSha(root);
+}
+export function resetHard(root, sha) {
+    runGit(root, ['reset', '--hard', sha]);
+}

package/dist/lib/intent.js

@@ -0,0 +1,88 @@
+// The strict intent parser. `build <n>` reads the nth step under `## Steps` and
+// extracts its seam — the backtick-wrapped paths on the single `seam:` sub-line.
+// Strict by design: it refuses precisely on globs, absolute paths, a missing
+// step, a missing seam, or more than one seam line, rather than guessing.
+const GLOB_CHARS = /[*?[\]{}]/;
+export function parseStepSeam(content, step) {
+    const lines = content.split('\n');
+    const stepsIdx = lines.findIndex((l) => l.trim() === '## Steps');
+    if (stepsIdx === -1) {
+        return fail('intent.md has no "## Steps" section.');
+    }
+    let sectionEnd = lines.findIndex((l, i) => i > stepsIdx && l.startsWith('## '));
+    if (sectionEnd === -1) {
+        sectionEnd = lines.length;
+    }
+    const itemStarts = [];
+    for (let i = stepsIdx + 1; i < sectionEnd; i++) {
+        const m = /^(\d+)\.\s/.exec(lines[i] ?? '');
+        if (m) {
+            itemStarts.push({ n: Number(m[1]), idx: i });
+        }
+    }
+    const pos = itemStarts.findIndex((s) => s.n === step);
+    if (pos === -1) {
+        return fail(`intent.md has no step ${step} under "## Steps".`);
+    }
+    const itemStart = itemStarts[pos]?.idx ?? stepsIdx;
+    const nextStart = itemStarts[pos + 1]?.idx;
+    const itemEnd = nextStart === undefined ? sectionEnd : nextStart;
+    const itemLines = lines.slice(itemStart, itemEnd);
+    const seamLines = itemLines
+        .map((l, i) => ({ l, i }))
+        .filter(({ l }) => /^\s*-\s*seam:/.test(l))
+        .map(({ i }) => i);
+    if (seamLines.length === 0) {
+        return fail(`step ${step} has no \`seam:\` line.`);
+    }
+    if (seamLines.length > 1) {
+        return fail(`step ${step} has more than one \`seam:\` line.`);
+    }
+    // The seam declaration is the seam line plus any wrapped continuation lines.
+    // Truncate each at an HTML-comment opener so a trailing `<!-- ... -->` note
+    // (which may carry its own backticks) is never read as a seam token; a
+    // continuation ends at the first line whose pre-comment text has no backtick.
+    const seamStart = seamLines[0] ?? 0;
+    const decl = [];
+    for (let i = seamStart; i < itemLines.length; i++) {
+        const beforeComment = (itemLines[i] ?? '').split('<!--')[0] ?? '';
+        if (i > seamStart && !beforeComment.includes('`')) {
+            break;
+        }
+        decl.push(beforeComment);
+    }
+    const tokens = [];
+    const re = /`([^`]+)`/g;
+    for (const line of decl) {
+        for (let m = re.exec(line); m !== null; m = re.exec(line)) {
+            tokens.push(m[1] ?? '');
+        }
+    }
+    if (tokens.length === 0) {
+        return fail(`step ${step}'s seam lists no files.`);
+    }
+    const seam = [];
+    for (const raw of tokens) {
+        const token = raw.trim().replace(/^\.\//, '');
+        if (token === '') {
+            return fail(`step ${step}'s seam has an empty token.`);
+        }
+        if (GLOB_CHARS.test(token)) {
+            return fail(`step ${step}'s seam token \`${raw}\` is a glob; seams are exact paths or \`dir/\` grants (D23).`);
+        }
+        if (token.startsWith('/')) {
+            return fail(`step ${step}'s seam token \`${raw}\` is absolute; seams are repo-relative.`);
+        }
+        seam.push(token);
+    }
+    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); the pre-edit hook reimplements it in sh.
+export function matchesSeam(relPath, tokens) {
+    return tokens.some((token) => (token.endsWith('/') ? relPath.startsWith(token) : relPath === token));
+}
+function fail(error) {
+    return { ok: false, error };
+}

package/dist/lib/settings.js

@@ -0,0 +1,79 @@
+// Claude Code settings.json hook registration (D27). A pure-TS JSON merge (zero
+// runtime deps, node builtins only — C2): strip our entries, then re-add them, so
+// a re-run is byte-identical. The same logic serves all three D27 scopes — only
+// the settings file path and the command-path representation differ, both chosen
+// by the `setup` verb. Functional/procedural, no classes (C1).
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+// A registration entry is "ours" iff one of its hook commands points into our
+// hooks dir. This marker matches every command form we emit: the global
+// `~/.claude/plumbbob/hooks/...` copy and the self-contained
+// `$CLAUDE_PROJECT_DIR/node_modules/plumbbob/hooks/...` reference both contain
+// `plumbbob/hooks/`, so uninstall finds either.
+const OURS_MARKER = 'plumbbob/hooks/';
+// The PreToolUse edit matcher covers all four editing tools (D5).
+const EDIT_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+// The three hook registration entries, pointing at `hooksDir`. Two command forms:
+//   global       — a direct absolute path to the +x copy under ~/.claude.
+//   self (viaSh) — `sh "<dir>/<file>"` against the package's hooks/ under
+//                  node_modules, addressed through `$CLAUDE_PROJECT_DIR` so the
+//                  committed/portable form carries no machine-absolute path and
+//                  needs no execute bit (pnpm's store may not preserve one).
+// Mirrors the PreToolUse/PostToolUse shape dev-install wrote.
+function registrationEntries(hooksDir, viaSh) {
+    const dir = hooksDir.endsWith('/') ? hooksDir.slice(0, -1) : hooksDir;
+    const command = (file) => (viaSh ? `sh "${dir}/${file}"` : `${dir}/${file}`);
+    const entry = (matcher, file) => ({
+        matcher,
+        hooks: [{ type: 'command', command: command(file) }],
+    });
+    return {
+        PreToolUse: [entry(EDIT_MATCHER, 'pre-edit.sh'), entry('Bash', 'bash-guard.sh')],
+        PostToolUse: [entry(EDIT_MATCHER, 'post-edit.sh')],
+    };
+}
+function isOurs(entry) {
+    return (entry.hooks ?? []).some((h) => h.command.includes(OURS_MARKER));
+}
+function stripOurs(list) {
+    return (list ?? []).filter((e) => !isOurs(e));
+}
+// Merge our registration into a parsed settings object (strip-then-add). Returns
+// a new object; every unrelated key and unrelated hook is preserved, and key
+// order is stable across runs so a second merge is byte-identical.
+export function mergeRegistration(settings, hooksDir, viaSh = false) {
+    const entries = registrationEntries(hooksDir, viaSh);
+    const existing = settings.hooks ?? {};
+    const hooks = { ...existing };
+    hooks.PreToolUse = [...stripOurs(existing.PreToolUse), ...entries.PreToolUse];
+    hooks.PostToolUse = [...stripOurs(existing.PostToolUse), ...entries.PostToolUse];
+    return { ...settings, hooks };
+}
+// Remove only our entries from the two events we manage, leaving everything else
+// untouched (uninstall, and the idempotent strip half of a re-install).
+export function stripRegistration(settings) {
+    const existing = settings.hooks;
+    if (existing === undefined) {
+        return settings;
+    }
+    const hooks = { ...existing };
+    if (existing.PreToolUse !== undefined) {
+        hooks.PreToolUse = stripOurs(existing.PreToolUse);
+    }
+    if (existing.PostToolUse !== undefined) {
+        hooks.PostToolUse = stripOurs(existing.PostToolUse);
+    }
+    return { ...settings, hooks };
+}
+export function readSettings(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeSettings(path, settings) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+}

package/dist/lib/sidecar.js

@@ -0,0 +1,69 @@
+// The .plumbbob/ sidecar: control state lives in flat files so the hooks can
+// read it with a grep and no markdown parsing (D7). Functional/procedural,
+// node builtins only (C1/C2).
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { gitDir } from "./git.js";
+const DIRNAME = '.plumbbob';
+// The five legal control states (README mode machine). `mode` validates against
+// this; the muzzle allows edits iff STATE is BUILD or SPIKE.
+export const VALID_STATES = ['DESIGN', 'BUILD', 'REVIEW', 'SPIKE', 'FINISH'];
+export function sidecarDir(root) {
+    return join(root, DIRNAME);
+}
+function statePath(root) {
+    return join(root, DIRNAME, 'STATE');
+}
+// 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 stepPath(root) {
+    return join(root, DIRNAME, 'STEP');
+}
+export function checkpointsPath(root) {
+    return join(root, DIRNAME, 'checkpoints');
+}
+export function configPath(root) {
+    return join(root, DIRNAME, 'config');
+}
+export function intentPath(root) {
+    return join(root, DIRNAME, 'intent.md');
+}
+export function buildLogPath(root) {
+    return join(root, DIRNAME, 'build-log.md');
+}
+// A session exists iff STATE exists. Deleting STATE (at finish) is what switches
+// the muzzle off — so it is the single source of truth for "is there a session".
+export function hasSession(root) {
+    return existsSync(statePath(root));
+}
+export function readState(root) {
+    try {
+        return readFileSync(statePath(root), 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(root, state) {
+    writeFileSync(statePath(root), `${state}\n`);
+}
+// 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');
+    let current = '';
+    try {
+        current = readFileSync(exclude, 'utf8');
+    }
+    catch {
+        current = '';
+    }
+    if (current.split('\n').some((line) => line.trim() === `${DIRNAME}/`)) {
+        return;
+    }
+    const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
+    appendFileSync(exclude, `${prefix}${DIRNAME}/\n`);
+}