plumbbob 0.1.3 → 0.2.1

package/src/lib/git.ts

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

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

@@ -1,90 +0,0 @@
-// 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`)
-}

package/src/lib/sidecar.ts

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

@@ -1,38 +0,0 @@
-// `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

@@ -1,71 +0,0 @@
-// `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

@@ -1,72 +0,0 @@
-// `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

@@ -1,27 +0,0 @@
-// `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

@@ -1,56 +0,0 @@
-// `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')
-}