plumbbob 0.1.3

package/src/lib/sidecar.ts

@@ -0,0 +1,82 @@
+// 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.ts'
+
+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: ReadonlyArray<string> = ['DESIGN', 'BUILD', 'REVIEW', 'SPIKE', 'FINISH']
+
+export function sidecarDir(root: string): string {
+  return join(root, DIRNAME)
+}
+
+function statePath(root: string): string {
+  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: string): string {
+  return join(root, DIRNAME, 'SEAM')
+}
+
+export function stepPath(root: string): string {
+  return join(root, DIRNAME, 'STEP')
+}
+
+export function checkpointsPath(root: string): string {
+  return join(root, DIRNAME, 'checkpoints')
+}
+
+export function configPath(root: string): string {
+  return join(root, DIRNAME, 'config')
+}
+
+export function intentPath(root: string): string {
+  return join(root, DIRNAME, 'intent.md')
+}
+
+export function buildLogPath(root: string): string {
+  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: string): boolean {
+  return existsSync(statePath(root))
+}
+
+export function readState(root: string): string | null {
+  try {
+    return readFileSync(statePath(root), 'utf8').trim()
+  } catch {
+    return null
+  }
+}
+
+export function writeState(root: string, state: string): void {
+  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: string): void {
+  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`)
+}

package/src/verbs/build.ts

@@ -0,0 +1,38 @@
+// `plumbbob build <n>` — read step n's seam from intent.md, write the normalized
+// SEAM + STEP, and enter BUILD. Re-entering from REVIEW just re-derives the same
+// seam and flips back to BUILD; it never checkpoints (only `done` commits).
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { findRepoRoot } from '../lib/git.ts'
+import { hasSession, intentPath, seamPath, stepPath, writeState } from '../lib/sidecar.ts'
+import { parseStepSeam } from '../lib/intent.ts'
+
+export function build(cwd: string, args: ReadonlyArray<string>): number {
+  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 raw = args.find((a) => !a.startsWith('--'))
+  if (raw === undefined || !/^\d+$/.test(raw) || Number(raw) < 1) {
+    process.stderr.write('plumbbob: build needs a step number. Try: plumbbob build 2.\n')
+    return 1
+  }
+  const step = Number(raw)
+
+  const parsed = parseStepSeam(readFileSync(intentPath(root), 'utf8'), step)
+  if (!parsed.ok) {
+    process.stderr.write(`plumbbob: ${parsed.error} Fix the step's seam in intent.md, then \`build ${step}\` again.\n`)
+    return 1
+  }
+
+  writeFileSync(seamPath(root), `${parsed.seam.join('\n')}\n`)
+  writeFileSync(stepPath(root), `${step}\n`)
+  writeState(root, 'BUILD')
+
+  process.stdout.write(
+    `plumbbob: building step ${step} — STATE=BUILD. Edits are limited to the seam:\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`,
+  )
+  return 0
+}

package/src/verbs/done.ts

@@ -0,0 +1,71 @@
+// `plumbbob done` — the step gate. Refuses on a red check, then stages the whole
+// step (D8: `git add -A`; the sidecar is git-excluded so it never lands), warns
+// about anything committed outside the SEAM, takes the checkpoint commit, records
+// its SHA, and returns to DESIGN.
+
+import { appendFileSync, readFileSync, rmSync } from 'node:fs'
+import { commit, findRepoRoot, stageAll, stagedPaths } from '../lib/git.ts'
+import { checkpointsPath, hasSession, readState, seamPath, stepPath, writeState } from '../lib/sidecar.ts'
+import { runCheck } from '../lib/check.ts'
+import { matchesSeam } from '../lib/intent.ts'
+
+export function done(cwd: string): number {
+  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 !== 'BUILD' && state !== 'REVIEW') {
+    process.stderr.write(`plumbbob: done runs from BUILD or REVIEW (current state is ${state ?? 'UNKNOWN'}). Run \`plumbbob build <n>\` first.\n`)
+    return 1
+  }
+  const step = readStepNumber(root)
+  if (step === null) {
+    process.stderr.write('plumbbob: no in-flight step — run `plumbbob build <n>` first.\n')
+    return 1
+  }
+
+  if (runCheck(root) !== 0) {
+    process.stderr.write('plumbbob: check failed (red) — done refuses on red. Fix it and re-run `done`.\n')
+    return 1
+  }
+
+  stageAll(root)
+  const seam = readSeamTokens(root)
+  const outside = stagedPaths(root).filter((p) => !matchesSeam(p, seam))
+  if (outside.length > 0) {
+    process.stderr.write(
+      `plumbbob: WARNING committed paths outside the SEAM: ${outside.join(', ')}. The checkpoint captures them, but scope drift may mean the plan needs revising.\n`,
+    )
+  }
+
+  const sha = commit(root, `plumbbob: step ${step} done`)
+  appendFileSync(checkpointsPath(root), `step ${step} ${sha}\n`)
+  rmSync(seamPath(root), { force: true })
+  rmSync(stepPath(root), { force: true })
+  writeState(root, 'DESIGN')
+
+  process.stdout.write(`plumbbob: step ${step} done — checkpoint ${sha.slice(0, 9)}. STATE=DESIGN.\n`)
+  return 0
+}
+
+function readStepNumber(root: string): number | null {
+  try {
+    const raw = readFileSync(stepPath(root), 'utf8').trim()
+    return /^\d+$/.test(raw) ? Number(raw) : null
+  } catch {
+    return null
+  }
+}
+
+function readSeamTokens(root: string): ReadonlyArray<string> {
+  try {
+    return readFileSync(seamPath(root), 'utf8')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0)
+  } catch {
+    return []
+  }
+}

package/src/verbs/finish.ts

@@ -0,0 +1,72 @@
+// `plumbbob finish` (D19/D20) — the closing gate, symmetric with the step gate.
+// Refuses unless a report exists, appends the checkpoint SHA list to it, archives
+// intent + build-log + report under .plumbbob/archive/, clears the active files,
+// and deletes SEAM, STEP, then STATE LAST (deleting STATE is what switches the
+// muzzle off, so it happens exactly at session end). Never touches git (C5).
+
+import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { findRepoRoot } from '../lib/git.ts'
+import {
+  buildLogPath,
+  checkpointsPath,
+  hasSession,
+  intentPath,
+  seamPath,
+  sidecarDir,
+  stepPath,
+} from '../lib/sidecar.ts'
+import { archiveSession, reportPath } from '../lib/archive.ts'
+
+export function finish(cwd: string): number {
+  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))) {
+    process.stderr.write(
+      'plumbbob: finish refuses without a report — run `/plumbbob-report` first (it writes .plumbbob/report.md). ' +
+        'The closing gate is symmetric with the step gate: you do not walk away without capturing what happened.\n',
+    )
+    return 1
+  }
+
+  appendCheckpointShas(root)
+  const archived = archiveSession(root)
+
+  // Clear the active files — now safely archived.
+  rmSync(intentPath(root), { force: true })
+  rmSync(buildLogPath(root), { force: true })
+  rmSync(reportPath(root), { force: true })
+
+  // Delete the control files LAST, STATE the very last: while STATE exists the
+  // muzzle is live, so it comes off only once everything else is torn down.
+  rmSync(seamPath(root), { force: true })
+  rmSync(stepPath(root), { force: true })
+  rmSync(join(sidecarDir(root), 'STATE'), { force: true })
+
+  process.stdout.write(
+    `plumbbob: finished — archived to ${relative(root, archived)}. STATE cleared (muzzle off). ` +
+      'Run `plumbbob start "<title>"` to begin the next task.\n',
+  )
+  return 0
+}
+
+// Append the recorded checkpoints (baseline + each `step n <sha>`) to the report,
+// so the archived report lists the SHAs (spec: "finish lists the SHAs in the
+// report").
+function appendCheckpointShas(root: string): void {
+  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'))
+}

package/src/verbs/mode.ts

@@ -0,0 +1,27 @@
+// `plumbbob mode <x>` — the hidden escape hatch: set STATE directly when reality
+// and the machine desync. Not part of the normal flow; a transition verb, so the
+// dispatch refuses it under CLAUDECODE (D21).
+
+import { findRepoRoot } from '../lib/git.ts'
+import { hasSession, readState, writeState, VALID_STATES } from '../lib/sidecar.ts'
+
+export function mode(cwd: string, args: ReadonlyArray<string>): number {
+  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 target = args[0]
+  if (target === undefined) {
+    process.stderr.write(`plumbbob: mode needs a state — one of: ${VALID_STATES.join(', ')}.\n`)
+    return 1
+  }
+  if (!VALID_STATES.includes(target)) {
+    process.stderr.write(`plumbbob: '${target}' is not a valid state — one of: ${VALID_STATES.join(', ')}.\n`)
+    return 1
+  }
+  const previous = readState(root) ?? 'UNKNOWN'
+  writeState(root, target)
+  process.stdout.write(`STATE: ${previous} -> ${target} (escape hatch — prefer the normal verbs when you can).\n`)
+  return 0
+}

package/src/verbs/park.ts

@@ -0,0 +1,56 @@
+// `plumbbob park "<text>"` — the dumb capture path: append one raw line under
+// the build-log's Park list. No model turn, no composition (that is /park's job).
+// Exempt from the CLAUDECODE transition refusal so capture is always available.
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { findRepoRoot } from '../lib/git.ts'
+import { hasSession, buildLogPath } from '../lib/sidecar.ts'
+
+export function park(cwd: string, args: ReadonlyArray<string>): number {
+  const root = findRepoRoot(cwd)
+  if (root === null || !hasSession(root)) {
+    process.stderr.write(
+      'plumbbob: no active session — nothing to park to. Run `plumbbob start "<title>"` first.\n',
+    )
+    return 1
+  }
+  const text = args
+    .filter((a) => !a.startsWith('--'))
+    .join(' ')
+    .trim()
+  if (text.length === 0) {
+    process.stderr.write('plumbbob: park needs text. Try: plumbbob park "the idea you do not want to chase right now".\n')
+    return 1
+  }
+  const path = buildLogPath(root)
+  const updated = insertParkItem(readFileSync(path, 'utf8'), text)
+  if (updated === null) {
+    process.stderr.write('plumbbob: could not find a "## Park list" section in build-log.md.\n')
+    return 1
+  }
+  writeFileSync(path, updated)
+  process.stdout.write(`parked: ${text}\n`)
+  return 0
+}
+
+// Append after the last non-blank line of the Park list section (i.e. just before
+// the next `## ` heading). Returns null if there is no Park list to append to.
+function insertParkItem(content: string, text: string): string | null {
+  const lines = content.split('\n')
+  const headingIdx = lines.findIndex((line) => line.trim() === '## Park list')
+  if (headingIdx === -1) {
+    return null
+  }
+  let nextSection = lines.findIndex((line, i) => i > headingIdx && line.startsWith('## '))
+  if (nextSection === -1) {
+    nextSection = lines.length
+  }
+  let insertAt = headingIdx + 1
+  for (let i = headingIdx + 1; i < nextSection; i++) {
+    if ((lines[i] ?? '').trim() !== '') {
+      insertAt = i + 1
+    }
+  }
+  lines.splice(insertAt, 0, `- [ ] ${text}`)
+  return lines.join('\n')
+}

package/src/verbs/revert.ts

@@ -0,0 +1,110 @@
+// `plumbbob revert [--to n]` — git reset --hard to a checkpoint SHA (the most
+// recent step, or `--to n`, with the baseline as fallback), then remove untracked
+// files under the SEAM only. The sidecar is git-excluded (D17), so the reset
+// never touches it — park lines and intent edits survive the revert (C4).
+
+import { readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { findRepoRoot, resetHard, untrackedPaths } from '../lib/git.ts'
+import { checkpointsPath, hasSession, seamPath, stepPath, writeState } from '../lib/sidecar.ts'
+import { matchesSeam } from '../lib/intent.ts'
+
+export function revert(cwd: string, args: ReadonlyArray<string>): number {
+  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 to = parseTo(args)
+  if (to === 'invalid') {
+    process.stderr.write('plumbbob: revert --to needs a step number. Try: plumbbob revert --to 2.\n')
+    return 1
+  }
+
+  const checkpoints = readCheckpoints(root)
+  let sha: string | undefined
+  if (to === null) {
+    sha = checkpoints.steps.at(-1)?.sha ?? checkpoints.baseline
+  } else {
+    const entry = checkpoints.steps.find((e) => e.n === to)
+    if (entry === undefined) {
+      process.stderr.write(`plumbbob: no checkpoint recorded for step ${to}.\n`)
+      return 1
+    }
+    sha = entry.sha
+  }
+  if (sha === undefined) {
+    process.stderr.write('plumbbob: no baseline recorded in checkpoints — cannot revert.\n')
+    return 1
+  }
+
+  // Compute untracked-in-seam BEFORE the reset (reset --hard leaves untracked and
+  // ignored files alone, so they must be removed explicitly afterward).
+  const seam = readSeamTokens(root)
+  const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam))
+
+  resetHard(root, sha)
+  for (const rel of toRemove) {
+    rmSync(join(root, rel), { force: true, recursive: true })
+  }
+  rmSync(seamPath(root), { force: true })
+  rmSync(stepPath(root), { force: true })
+  writeState(root, 'DESIGN')
+
+  process.stdout.write(
+    `plumbbob: reverted to ${sha.slice(0, 9)} — STATE=DESIGN. Park lines and intent edits were preserved.\n`,
+  )
+  return 0
+}
+
+function parseTo(args: ReadonlyArray<string>): number | null | 'invalid' {
+  const idx = args.indexOf('--to')
+  if (idx === -1) {
+    return null
+  }
+  const raw = args[idx + 1]
+  if (raw === undefined || !/^\d+$/.test(raw)) {
+    return 'invalid'
+  }
+  return Number(raw)
+}
+
+type Checkpoints = {
+  readonly baseline: string | undefined
+  readonly steps: ReadonlyArray<{ readonly n: number; readonly sha: string }>
+}
+
+function readCheckpoints(root: string): Checkpoints {
+  let content = ''
+  try {
+    content = readFileSync(checkpointsPath(root), 'utf8')
+  } catch {
+    return { baseline: undefined, steps: [] }
+  }
+  let baseline: string | undefined
+  const steps: Array<{ readonly n: number; readonly sha: string }> = []
+  for (const line of content.split('\n')) {
+    const baselineMatch = /^baseline\s+(\S+)/.exec(line)
+    if (baselineMatch) {
+      baseline = baselineMatch[1]
+      continue
+    }
+    const stepMatch = /^step\s+(\d+)\s+(\S+)/.exec(line)
+    if (stepMatch) {
+      steps.push({ n: Number(stepMatch[1]), sha: stepMatch[2] ?? '' })
+    }
+  }
+  return { baseline, steps }
+}
+
+function readSeamTokens(root: string): ReadonlyArray<string> {
+  try {
+    return readFileSync(seamPath(root), 'utf8')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0)
+  } catch {
+    return []
+  }
+}

package/src/verbs/review.ts

@@ -0,0 +1,30 @@
+// `plumbbob review` — run the heavy check from BUILD. Green flips to REVIEW (the
+// muzzle goes back on so reading the diff can't slide into editing). Red stays in
+// BUILD. The state only advances on a green check.
+
+import { findRepoRoot } from '../lib/git.ts'
+import { hasSession, readState, writeState } from '../lib/sidecar.ts'
+import { runCheck } from '../lib/check.ts'
+
+export function review(cwd: string): number {
+  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 (readState(root) !== 'BUILD') {
+    process.stderr.write(`plumbbob: review runs from BUILD (current state is ${readState(root) ?? 'UNKNOWN'}). Run \`plumbbob build <n>\` first.\n`)
+    return 1
+  }
+
+  if (runCheck(root) !== 0) {
+    process.stderr.write('plumbbob: check failed (red) — staying in BUILD. Fix it and re-run `review` (or `done` once green).\n')
+    return 1
+  }
+
+  writeState(root, 'REVIEW')
+  process.stdout.write(
+    'plumbbob: check green — STATE=REVIEW. Read the diff against intent.md (edits muzzled). `build <n>` to re-enter and fix, or `done` to checkpoint.\n',
+  )
+  return 0
+}

package/src/verbs/setup.ts

@@ -0,0 +1,95 @@
+// `plumbbob setup` — the production installer (D27, replacing dev-install.sh).
+// Copies the hooks to ~/.claude/plumbbob/hooks/ and the skills to
+// ~/.claude/skills/, then merges the hook registration into the settings file the
+// chosen scope selects:
+//   (default)   ~/.claude/settings.json            — global, this machine
+//   --project   <repo>/.claude/settings.json       — committable, enrolls the team
+//   --local     <repo>/.claude/settings.local.json — personal, untracked
+// Hooks and skills always install once under ~/.claude/; only the registration's
+// location and command-path form vary by scope. `--uninstall` strips the
+// registration (the installed files are left in place). The hooks are
+// session-gated, so a global registration is safe in every repo (C7).
+
+import { chmodSync, cpSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findRepoRoot } from '../lib/git.ts'
+import { mergeRegistration, readSettings, stripRegistration, writeSettings } from '../lib/settings.ts'
+
+const HOOK_FILES: ReadonlyArray<string> = ['pre-edit.sh', 'bash-guard.sh', 'post-edit.sh']
+
+type Scope = 'global' | 'project' | 'local'
+
+export function setup(cwd: string, args: ReadonlyArray<string>): number {
+  const scope = pickScope(args)
+  const home = process.env.HOME ?? homedir()
+
+  const settingsFile = resolveSettingsFile(scope, cwd, home)
+  if (settingsFile === null) {
+    process.stderr.write(
+      `plumbbob: --${scope} writes <repo>/.claude/, but this is not a git repository. Run setup from inside the repo, or use the default global scope.\n`,
+    )
+    return 1
+  }
+
+  if (args.includes('--uninstall')) {
+    writeSettings(settingsFile, stripRegistration(readSettings(settingsFile)))
+    process.stdout.write(
+      `plumbbob: removed the hook registration from ${settingsFile}. The installed hooks/skills under ~/.claude/ were left in place.\n`,
+    )
+    return 0
+  }
+
+  // Hooks + skills install once under ~/.claude/ regardless of scope.
+  const installedHooksDir = join(home, '.claude', 'plumbbob', 'hooks')
+  const installedSkillsDir = join(home, '.claude', 'skills')
+  cpSync(packageDir('hooks'), installedHooksDir, { recursive: true })
+  for (const file of HOOK_FILES) {
+    chmodSync(join(installedHooksDir, file), 0o755)
+  }
+  cpSync(packageDir('skills'), installedSkillsDir, { recursive: true })
+
+  // D27: global registers absolute command paths (its settings file is itself
+  // under ~); the repo-scoped files register `~`-prefixed paths so committed
+  // settings carry no machine-absolute home dir.
+  const commandDir = scope === 'global' ? installedHooksDir : '~/.claude/plumbbob/hooks'
+  writeSettings(settingsFile, mergeRegistration(readSettings(settingsFile), commandDir))
+
+  process.stdout.write(
+    `plumbbob: installed hooks → ${installedHooksDir}, skills → ${installedSkillsDir}.\n` +
+      `plumbbob: registered the hooks in ${settingsFile} (${scope} scope).\n` +
+      'plumbbob: restart Claude Code (or reload settings) for the hooks to take effect.\n' +
+      "plumbbob: installed from npm, `plumbbob` (and its `pb` alias) is already on your PATH; from a dev checkout add `alias plumbbob='node <repo>/src/cli.ts'` so the skills' status pre-injection resolves.\n",
+  )
+  return 0
+}
+
+function pickScope(args: ReadonlyArray<string>): Scope {
+  if (args.includes('--project')) {
+    return 'project'
+  }
+  if (args.includes('--local')) {
+    return 'local'
+  }
+  return 'global'
+}
+
+// The settings file the scope writes. Global lives under ~; the repo scopes need
+// a git root and return null outside one so the verb can refuse with a clear note.
+function resolveSettingsFile(scope: Scope, cwd: string, home: string): string | null {
+  if (scope === 'global') {
+    return join(home, '.claude', 'settings.json')
+  }
+  const root = findRepoRoot(cwd)
+  if (root === null) {
+    return null
+  }
+  return scope === 'project' ? join(root, '.claude', 'settings.json') : join(root, '.claude', 'settings.local.json')
+}
+
+// hooks/ and skills/ ship beside src/ in the package; resolve them off this
+// module's URL the way `start` resolves templates/.
+function packageDir(name: string): string {
+  return fileURLToPath(new URL(`../../${name}/`, import.meta.url))
+}