plumbbob 0.1.3

package/src/verbs/spike.ts

@@ -0,0 +1,129 @@
+// `plumbbob spike` (D18) — the spike lifecycle for a genuine fork the design
+// phase couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree +
+// `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default opts a/b)
+// and sets STATE=SPIKE; the main tree stays DESIGN-locked while you experiment in
+// the worktrees, which are hook-dormant by construction — the untracked sidecar
+// (D17) doesn't exist in a fresh checkout, so the hooks find no STATE there.
+// `spike done` removes every spike worktree + branch and returns to DESIGN.
+//
+// Worktree git calls run directly here rather than via lib/git.ts (which holds the
+// shared additive read/commit helpers): worktree management is spike-local, and
+// this is the only place Plumbbob creates branches.
+
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { findRepoRoot } from '../lib/git.ts'
+import { hasSession, readState, writeState } from '../lib/sidecar.ts'
+
+const DEFAULT_OPTIONS: ReadonlyArray<string> = ['a', 'b']
+
+export function spike(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 positionals = args.filter((a) => !a.startsWith('--'))
+  if (positionals[0] === 'done') {
+    return spikeDone(root)
+  }
+  return spikeStart(root, positionals)
+}
+
+function spikeStart(root: string, positionals: ReadonlyArray<string>): number {
+  const state = readState(root)
+  if (state === 'SPIKE') {
+    process.stderr.write('plumbbob: already in a spike. Run `plumbbob spike done` to close it first.\n')
+    return 1
+  }
+  if (state !== 'DESIGN') {
+    process.stderr.write(
+      `plumbbob: spike starts from DESIGN (current state is ${state ?? 'UNKNOWN'}). ` +
+        'A spike is a deliberate fork — close the current step first with `done`.\n',
+    )
+    return 1
+  }
+  const slug = sanitize(positionals[0] ?? '')
+  if (slug.length === 0) {
+    process.stderr.write('plumbbob: spike needs a slug. Try: plumbbob spike "auth-store" a b.\n')
+    return 1
+  }
+  const explicit = positionals.slice(1).map(sanitize).filter((o) => o.length > 0)
+  const options = explicit.length > 0 ? explicit : DEFAULT_OPTIONS
+
+  const created: string[] = []
+  for (const opt of options) {
+    const path = join(dirname(root), `${basename(root)}-spike-${slug}-${opt}`)
+    if (existsSync(path)) {
+      process.stderr.write(`plumbbob: ${path} already exists — remove it or run \`plumbbob spike done\` first.\n`)
+      return 1
+    }
+    git(root, ['worktree', 'add', '-b', `spike/${slug}-${opt}`, path, 'HEAD'])
+    created.push(path)
+  }
+
+  writeState(root, 'SPIKE')
+  process.stdout.write(
+    `plumbbob: STATE=SPIKE — the main tree stays DESIGN-locked. Experiment in the throwaway worktrees:\n${created
+      .map((p) => `  ${p}`)
+      .join('\n')}\nWhen you've decided, record the verdict in intent.md and run \`plumbbob spike done\`.\n`,
+  )
+  return 0
+}
+
+function spikeDone(root: string): number {
+  const state = readState(root)
+  if (state !== 'SPIKE') {
+    process.stderr.write(`plumbbob: no active spike (state is ${state ?? 'UNKNOWN'}).\n`)
+    return 1
+  }
+  for (const path of spikeWorktrees(root)) {
+    git(root, ['worktree', 'remove', '--force', path])
+  }
+  git(root, ['worktree', 'prune'])
+  for (const branch of spikeBranches(root)) {
+    git(root, ['branch', '-D', branch])
+  }
+  writeState(root, 'DESIGN')
+  process.stdout.write(
+    'plumbbob: spike closed — STATE=DESIGN, worktrees and branches removed. ' +
+      'Record the verdict (which option won, and why) in intent.md before you `build`.\n',
+  )
+  return 0
+}
+
+// Worktree paths whose checked-out branch is under spike/ — parsed from the
+// porcelain output (blank-line-separated `worktree <path>` / `branch <ref>` blocks).
+function spikeWorktrees(root: string): ReadonlyArray<string> {
+  const out = git(root, ['worktree', 'list', '--porcelain'])
+  const paths: string[] = []
+  let current: string | null = null
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      current = line.slice('worktree '.length)
+    } else if (current !== null && line.startsWith('branch refs/heads/spike/')) {
+      paths.push(current)
+    }
+  }
+  return paths
+}
+
+function spikeBranches(root: string): ReadonlyArray<string> {
+  const out = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/spike/'])
+  return out.length === 0 ? [] : out.split('\n').filter((b) => b.length > 0)
+}
+
+function sanitize(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function git(root: string, args: ReadonlyArray<string>): string {
+  return execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'inherit'],
+  }).trim()
+}

package/src/verbs/start.ts

@@ -0,0 +1,103 @@
+// `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.ts'
+import {
+  sidecarDir,
+  checkpointsPath,
+  configPath,
+  intentPath,
+  buildLogPath,
+  writeState,
+  hasSession,
+  excludeSidecar,
+} from '../lib/sidecar.ts'
+
+const DEFAULT_CHECK = 'pnpm run check'
+
+export function start(cwd: string, args: ReadonlyArray<string>): number {
+  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: string): { readonly command: string; readonly warn: boolean } {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+      scripts?: Record<string, string>
+    }
+    return { command: DEFAULT_CHECK, warn: pkg.scripts?.check === undefined }
+  } catch {
+    return { command: DEFAULT_CHECK, warn: true }
+  }
+}
+
+function readTemplate(name: string): string {
+  return readFileSync(fileURLToPath(new URL(`../../templates/${name}`, import.meta.url)), 'utf8')
+}
+
+function stamp(template: string, title: string, check: string): string {
+  return template.split('{{TITLE}}').join(title).split('{{CHECK}}').join(check)
+}

package/src/verbs/status.ts

@@ -0,0 +1,15 @@
+// `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.ts'
+import { hasSession, readState } from '../lib/sidecar.ts'
+
+export function status(cwd: string): number {
+  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/src/verbs/wrap.ts

@@ -0,0 +1,34 @@
+// `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 verb, so dispatch refuses it under
+// CLAUDECODE (D21).
+
+import { findRepoRoot } from '../lib/git.ts'
+import { hasSession, readState, writeState } from '../lib/sidecar.ts'
+
+export function wrap(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 === '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/templates/build-log.md

@@ -0,0 +1,54 @@
+<!--
+build-log.md — your live ledger for execution. Append constantly; reorganize at
+step boundaries. The antidote to "my plan got lost in the noise."
+
+  Steps     : where you are. One step in flight at a time.
+  Park list : where ideas go so you do not chase them. CAPTURE, never act inline.
+  Triage    : the boundary ritual that keeps you on one branch.
+  Log       : the audit trail. Feeds /plumbbob-report, then gets archived.
+-->
+
+# Build log — {{TITLE}}
+
+**Current step:** none (DESIGN) · **STATE:** DESIGN
+**Heavy check:** {{CHECK}}
+
+## Steps
+
+*(Mirror of intent.md's Steps, with live status. Only ONE step is in flight. A step
+is done only after `plumbbob done` — check green + checkpoint taken.)*
+
+- ☐ 1. <step>
+
+## Park list
+
+> Mid-step, every new problem / idea / "ooh what if" lands HERE, untouched, and you
+> go straight back to the step. Acting the instant an idea arrives is the disease.
+> Capture is one line (`/park` composes it, or raw `plumbbob park`). Triage happens
+> only at the boundary.
+
+## Triage  *(run at each step boundary, after green)*
+
+Classify each parked item as exactly ONE. Naming it before acting is what keeps you
+from sprawling across branches.
+
+| Class            | Meaning                                   | Action                        |
+|------------------|-------------------------------------------|-------------------------------|
+| **blocker**      | Plan was wrong/incomplete; can't proceed  | `revert`, fold into intent.md |
+| **tangent**      | A different path, not clearly better      | Defer or kill. Default here.  |
+| **pivot signal** | Evidence the whole approach is wrong      | Stop. Replan deliberately.    |
+
+> Reality check: almost everything that *feels* like a pivot is a tangent. Require a
+> failed assumption, not a shinier idea, before you pivot.
+
+Triage results this boundary:
+
+- (none yet)
+
+## Log
+
+*(Append-only. One decision or event per line, dated. What you point at to say "I
+did that — the LLM helped, but those were my calls." `/plumbbob-report` reads this;
+`plumbbob finish` archives it under `.plumbbob/archive/`.)*
+
+- <date> — <decision / event / what shipped this step>

package/templates/intent.md

@@ -0,0 +1,67 @@
+<!--
+intent.md — your canonical intent, written in DESIGN before any code. This is the
+head; the chat is the hand. When the model floods you, read this, not your memory.
+
+Size to the work: a small change fills Frame + a couple of Decisions and deletes
+the rest; a medium feature fills it all. Opinionated where decided, explicit where
+open. If the implementor (you-later, or the LLM) has to guess, the doc failed.
+-->
+
+# {{TITLE}}
+
+**STATE:** DESIGN
+**Phase** (bookkeeping while in DESIGN): frame
+**Size:** tiny | small | medium
+
+## Frame
+
+*(You, on paper first. The problem in plain words — before any solution.)*
+
+- **Problem:** <what is wrong or missing, and why it matters>
+- **Smallest thing that solves it:** <the minimal change, not the ideal system>
+- **Done looks like:** <the observable, checkable outcome>
+- **Explicitly NOT doing:** <scope you are refusing, so it cannot creep in>
+
+## Architecture sketch
+
+*(Hand-drawn is best. Photograph it in, or describe the boxes and arrows.)*
+
+```
+<ascii, or a link to the paper sketch>
+```
+
+## Decisions
+
+*(One line each. Settled, not re-litigated in the chat. Grows as you resolve the
+holes the interrogation surfaces, and as blockers fold in during BUILD.)*
+
+- D1: <decision> — *because* <the one reason that mattered>
+
+## Constraints
+
+*(Hard rules the build must honor. Triage and review read against these.)*
+
+- C1: <e.g. functional/procedural only; no new dependencies>
+
+## Steps
+
+*(The build plan. Each step carries its own seam — the paths `plumbbob build <n>`
+writes into `.plumbbob/SEAM` and the seam-guard enforces. Keep each step small
+enough to verify in one review pass. A blocker may rewrite a step's seam: fold the
+new decision, revise the seam here, then `build <n>` again.)*
+
+1. [ ] <step> — **done when:** <criterion, ideally a test or check result>
+   - seam: `<file>`, `<file>`
+
+## Open questions
+
+*(Holes you could NOT resolve on paper. Do not guess them into Decisions. A genuine
+fork goes to a SPIKE; record the verdict below and in Decisions.)*
+
+- Q1: <unresolved> — *resolve by:* decide | spike | ask
+
+## Verdicts
+
+*(Filled in as spikes and forks resolve — the audit trail of "these were my calls.")*
+
+- <date> — <fork> → chose <option> because <reason>; deleted <the rest>