plumbbob 0.1.3

package/skills/plumbbob-interrogate/SKILL.md

@@ -0,0 +1,33 @@
+---
+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:*)
+---
+
+# Plumbbob — interrogate the frame
+
+Current session state (injected when this skill runs): !`plumbbob status`
+
+## Wrong-state refusal
+
+This skill runs in **DESIGN only**. Read the state injected above and **stop before touching anything** if it is not `DESIGN`:
+
+- `STATE: BUILD` or `STATE: REVIEW` — you are mid-step. Return to DESIGN first: finish the step with `plumbbob done`, or drop a half-built step with `plumbbob revert`. Then re-invoke.
+- `STATE: SPIKE` — close the experiment with `plumbbob spike done` first.
+- `STATE: FINISH` — the session is wrapping up; there is nothing left to interrogate.
+- `NO ACTIVE SESSION` — start one with `plumbbob start "<title>"`.
+
+When the state is wrong, refuse in one line naming the verb above, and edit nothing.
+
+## What this skill does
+
+Hand the frame (the **Frame** and **Architecture sketch** in `intent.md`) a cold, adversarial read and **attack it for holes** — ambiguities, unhandled edge cases, hidden assumptions, and collisions with the existing code. This is the one place early divergence is wanted, and it is divergence in the **problem space only**: surface what is unclear, never propose a solution and never pick between options.
+
+## The one hard contract
+
+- Append every hole as a bullet under `intent.md`'s `## Open questions` section, and **nowhere else**.
+- **Never append to `## Decisions`** — resolving a hole is the human's convergence, not yours (D13). You surface; you do not decide.
+- One question per hole, phrased as a question, each standing on its own.
+- Once the Open questions are appended, **end your turn**. Do not answer them, do not start the next step, do not slide from interrogating into deciding.

package/skills/plumbbob-report/SKILL.md

@@ -0,0 +1,35 @@
+---
+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:*)
+---
+
+# Plumbbob — write the report
+
+Current session state (injected when this skill runs): !`plumbbob status`
+
+## Wrong-state refusal
+
+This skill writes the report **in FINISH only**. Read the state injected above:
+
+- `STATE: FINISH` — proceed.
+- Any other active state (`DESIGN`, `BUILD`, `REVIEW`, `SPIKE`) — **stop and tell the human to run `plumbbob wrap` first** (D28). Entering FINISH is what unlocks writing `report.md`, and this skill is the thing that tells you to wrap.
+- `NO ACTIVE SESSION` — there is nothing to report; start a session with `plumbbob start "<title>"`.
+
+## What this skill does
+
+The first of the three Finish steps. Read `intent.md` and `build-log.md` and synthesize the conclusion — the "yeah, I did that" artifact — into **exactly one file: `.plumbbob/report.md`**. Write nothing else, and touch no other path.
+
+## Required sections
+
+`.plumbbob/report.md` must contain these five sections, in order:
+
+1. **What shipped** — what this session actually built, measured against the Frame's "done looks like".
+2. **The decisions and why** — the decisions taken (the `D#` ledger) and the reasoning behind each.
+3. **Parked items and how each was triaged** — every Park-list item and its triage outcome (blocker / tangent / pivot signal).
+4. **Final status** — done, partial, or abandoned, with the checkpoint SHAs.
+5. **Deferred tangents (future Plumbbobs)** — the tangents worth their own future session.
+
+Once `report.md` exists, the human runs `plumbbob finish` (the closing gate refuses without it) to archive and clear the session.

package/skills/plumbbob-triage/SKILL.md

@@ -0,0 +1,38 @@
+---
+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:*)
+---
+
+# Plumbbob — triage the park list
+
+Current session state (injected when this skill runs): !`plumbbob status`
+
+## Wrong-state refusal
+
+This skill runs in **DESIGN only**, at a **step boundary** (after the step's check has gone green). Read the state injected above and **stop before writing anything** if it is not `DESIGN`:
+
+- `STATE: BUILD` or `STATE: REVIEW` — finish the step first with `plumbbob done`, which returns you to DESIGN; then triage.
+- `STATE: SPIKE` — close the experiment with `plumbbob spike done` first.
+- `STATE: FINISH` — too late to triage; the report skill folds the park list in instead.
+- `NO ACTIVE SESSION` — start one with `plumbbob start "<title>"`.
+
+When the state is wrong, refuse in one line naming the verb above.
+
+## What this skill does
+
+Walk the **Park list** in `build-log.md` item by item and, for each, **propose exactly one class**:
+
+- **blocker** — the plan was wrong or incomplete; can't proceed. Folds into `intent.md` and is handled now.
+- **tangent** — a different path, not clearly better. **The default** — defer or kill.
+- **pivot signal** — real evidence the whole approach is wrong. Stop and replan deliberately.
+
+## The one hard contract
+
+You **propose**; the **human calls it** (D13). For each item, state your proposed class and one line of reasoning, then **wait for the human to confirm or override**. Write **only after** per-item confirmation:
+
+- Record each confirmed class in `build-log.md`'s `## Triage` section.
+- A confirmed **blocker** also folds its decision into `intent.md`.
+- Never reclassify or resolve an item the human hasn't confirmed, and default every uncertain item to **tangent**, never to blocker.

package/src/cli.ts

@@ -0,0 +1,121 @@
+#!/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

@@ -0,0 +1,76 @@
+// 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
+}

package/src/lib/check.ts

@@ -0,0 +1,29 @@
+// 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.ts'
+
+const DEFAULT_CHECK = 'pnpm run check'
+
+function readCheckCommand(root: string): string {
+  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: string): number {
+  const command = readCheckCommand(root)
+  const result = spawnSync(command, { cwd: root, shell: true, stdio: 'inherit' })
+  return result.status ?? 1
+}

package/src/lib/git.ts

@@ -0,0 +1,73 @@
+// 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: string, args: ReadonlyArray<string>): string {
+  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: string): string | null {
+  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: string): string {
+  return runGit(root, ['rev-parse', '--absolute-git-dir'])
+}
+
+export function headSha(root: string): string {
+  return runGit(root, ['rev-parse', 'HEAD'])
+}
+
+export function hasCommit(root: string): boolean {
+  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: string): boolean {
+  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: string): void {
+  runGit(root, ['add', '-A'])
+}
+
+export function stagedPaths(root: string): ReadonlyArray<string> {
+  const out = runGit(root, ['diff', '--cached', '--name-only'])
+  return out.length === 0 ? [] : out.split('\n')
+}
+
+export function untrackedPaths(root: string): ReadonlyArray<string> {
+  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: string, message: string): string {
+  runGit(root, ['commit', '--allow-empty', '-m', message])
+  return headSha(root)
+}
+
+export function resetHard(root: string, sha: string): void {
+  runGit(root, ['reset', '--hard', sha])
+}

package/src/lib/intent.ts

@@ -0,0 +1,103 @@
+// 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 type SeamParse =
+  | { readonly ok: true; readonly seam: ReadonlyArray<string> }
+  | { readonly ok: false; readonly error: string }
+
+export function parseStepSeam(content: string, step: number): SeamParse {
+  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: Array<{ readonly n: number; readonly idx: number }> = []
+  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: string[] = []
+  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: string[] = []
+  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: string[] = []
+  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: string, tokens: ReadonlyArray<string>): boolean {
+  return tokens.some((token) => (token.endsWith('/') ? relPath.startsWith(token) : relPath === token))
+}
+
+function fail(error: string): SeamParse {
+  return { ok: false, error }
+}

package/src/lib/settings.ts

@@ -0,0 +1,90 @@
+// 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
+// installed hooks dir. This marker matches BOTH the absolute (global) and the
+// `~`-prefixed (repo-scoped) command forms, so uninstall finds either.
+const OURS_MARKER = '.claude/plumbbob/hooks/'
+
+// The PreToolUse edit matcher covers all four editing tools (D5).
+const EDIT_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit'
+
+type HookCommand = { readonly type: string; readonly command: string }
+type HookEntry = { readonly matcher?: string; readonly hooks?: ReadonlyArray<HookCommand> }
+type HookMap = { readonly [event: string]: ReadonlyArray<HookEntry> | undefined }
+interface Settings {
+  hooks?: HookMap
+  [key: string]: unknown
+}
+
+// The three hook registration entries, pointing at `hooksDir` (absolute for the
+// global scope; `~`-prefixed for the repo-scoped files so committed settings
+// carry no machine-absolute home dir — a leading `~/` is shell-expanded when the
+// hook command runs). Mirrors the PreToolUse/PostToolUse shape dev-install wrote.
+function registrationEntries(hooksDir: string): { readonly PreToolUse: HookEntry[]; readonly PostToolUse: HookEntry[] } {
+  const dir = hooksDir.endsWith('/') ? hooksDir.slice(0, -1) : hooksDir
+  const entry = (matcher: string, file: string): HookEntry => ({
+    matcher,
+    hooks: [{ type: 'command', command: `${dir}/${file}` }],
+  })
+  return {
+    PreToolUse: [entry(EDIT_MATCHER, 'pre-edit.sh'), entry('Bash', 'bash-guard.sh')],
+    PostToolUse: [entry(EDIT_MATCHER, 'post-edit.sh')],
+  }
+}
+
+function isOurs(entry: HookEntry): boolean {
+  return (entry.hooks ?? []).some((h) => h.command.includes(OURS_MARKER))
+}
+
+function stripOurs(list: ReadonlyArray<HookEntry> | undefined): HookEntry[] {
+  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: Settings, hooksDir: string): Settings {
+  const entries = registrationEntries(hooksDir)
+  const existing: HookMap = settings.hooks ?? {}
+  const hooks: { [event: string]: ReadonlyArray<HookEntry> | undefined } = { ...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: Settings): Settings {
+  const existing = settings.hooks
+  if (existing === undefined) {
+    return settings
+  }
+  const hooks: { [event: string]: ReadonlyArray<HookEntry> | undefined } = { ...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: string): Settings {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Settings
+  } catch {
+    return {}
+  }
+}
+
+export function writeSettings(path: string, settings: Settings): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`)
+}