plumbbob 0.2.1 → 0.3.0

package/dist/verbs/done.js

@@ -1,63 +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.js";
-import { checkpointsPath, hasSession, readState, seamPath, stepPath, writeState } from "../lib/sidecar.js";
-import { runCheck } from "../lib/check.js";
-import { matchesSeam } from "../lib/intent.js";
-export function done(cwd) {
-    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) {
-    try {
-        const raw = readFileSync(stepPath(root), 'utf8').trim();
-        return /^\d+$/.test(raw) ? Number(raw) : null;
-    }
-    catch {
-        return null;
-    }
-}
-function readSeamTokens(root) {
-    try {
-        return readFileSync(seamPath(root), 'utf8')
-            .split('\n')
-            .map((l) => l.trim())
-            .filter((l) => l.length > 0);
-    }
-    catch {
-        return [];
-    }
-}

package/dist/verbs/finish.js

@@ -1,54 +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.js";
-import { buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, sidecarDir, stepPath, } from "../lib/sidecar.js";
-import { archiveSession, reportPath } from "../lib/archive.js";
-export function finish(cwd) {
-    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) {
-    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/dist/verbs/mode.js

@@ -1,26 +0,0 @@
-// `plumbbob mode <x>` — the hidden escape hatch: set STATE directly when reality
-// and the machine desync. Not part of the normal flow; the lone human-only verb,
-// so the dispatch refuses it under CLAUDECODE and bash-guard blocks it from the
-// model's shell (D21 revised).
-import { findRepoRoot } from "../lib/git.js";
-import { hasSession, readState, writeState, VALID_STATES } from "../lib/sidecar.js";
-export function mode(cwd, args) {
-    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/dist/verbs/review.js

@@ -1,24 +0,0 @@
-// `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.js";
-import { hasSession, readState, writeState } from "../lib/sidecar.js";
-import { runCheck } from "../lib/check.js";
-export function review(cwd) {
-    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/dist/verbs/wrap.js

@@ -1,28 +0,0 @@
-// `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 the human fires — from a terminal
-// or, in-session, via the /pb-wrap driver skill (D21 revised).
-import { findRepoRoot } from "../lib/git.js";
-import { hasSession, readState, writeState } from "../lib/sidecar.js";
-export function wrap(cwd) {
-    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/hooks/bash-guard.sh

@@ -1,62 +0,0 @@
-#!/bin/sh
-# bash-guard.sh — Plumbbob's assistive fence (D21), not a wall. PreToolUse on
-# Bash. Session-gated. Blocks shell commands that poke control state or write
-# files outside BUILD/SPIKE, so the muzzle is not trivially bypassed. Full
-# shell-write detection is unsolvable; the residual gap is accepted (D21).
-
-find_root() {
-  d=$(pwd -P)
-  while [ -n "$d" ]; do
-    if [ -f "$d/.plumbbob/STATE" ]; then
-      printf '%s' "$d"
-      return 0
-    fi
-    [ "$d" = "/" ] && break
-    d=$(dirname "$d")
-  done
-  return 1
-}
-
-deny() {
-  printf 'plumbbob: %s\n' "$1" >&2
-  exit 2
-}
-
-root=$(find_root) || exit 0 # no session: allow
-
-input=$(cat)
-command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)
-[ -z "$command" ] && command=$(printf '%s' "$input" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
-[ -z "$command" ] && exit 0
-
-state=$(tr -d '[:space:]' <"$root/.plumbbob/STATE" 2>/dev/null)
-
-# Always: keep the model out of the control files and the escape hatch (D21).
-case "$command" in
-  *.plumbbob/STATE* | *.plumbbob/SEAM*)
-    deny "blocked: do not touch .plumbbob/STATE or SEAM from the shell. Read state with \`plumbbob status\`; transitions are the human's verbs. Do not retry."
-    ;;
-esac
-case "$command" in
-  *"plumbbob mode"* | *"pb mode"* | *"plumbbob mode"*)
-    deny "blocked: \`plumbbob mode\` is the human's escape hatch, not a model action. Do not retry — ask the human."
-    ;;
-esac
-
-# Outside BUILD/SPIKE: block obvious file-writing shell patterns (D21).
-case "$state" in
-  BUILD | SPIKE) ;;
-  *)
-    # Strip redirects that can't write a real file (stderr merges, /dev/null
-    # sinks) so read-only commands aren't over-blocked. Any surviving `>` is a
-    # real write. The residual gap (e.g. `>/dev/nullEVIL`) is accepted (D21).
-    scrubbed=$(printf '%s' "$command" | sed 's/[0-9]*>&[0-9-]//g; s/&\{0,1\}[0-9]*>>* *\/dev\/null//g')
-    case "$scrubbed" in
-      *">"* | *"tee "* | *"sed -i"* | *"git apply"*)
-        deny "blocked: file-writing shell commands are not allowed in ${state:-?} (code edits happen in BUILD). Do not retry — park it or ask the human to \`plumbbob build <n>\`."
-        ;;
-    esac
-    ;;
-esac
-
-exit 0

package/hooks/pre-edit.sh

@@ -1,95 +0,0 @@
-#!/bin/sh
-# pre-edit.sh — Plumbbob muzzle + seam-guard. PreToolUse on
-# Edit|Write|MultiEdit|NotebookEdit. Session-gated: a repo with no .plumbbob/
-# session behaves exactly like plain Claude Code (C7). The dormant check is pure
-# sh (test -f) before any JSON parsing, so a no-session edit pays ~nothing (C3).
-# Built from the verified hooks API (D3): input is JSON on stdin
-# (tool_input.file_path / notebook_path, absolute); deny is exit 2 + stderr.
-
-# Walk up from the hook's physical cwd to the session root, like git finds .git.
-find_root() {
-  d=$(pwd -P)
-  while [ -n "$d" ]; do
-    if [ -f "$d/.plumbbob/STATE" ]; then
-      printf '%s' "$d"
-      return 0
-    fi
-    [ "$d" = "/" ] && break
-    d=$(dirname "$d")
-  done
-  return 1
-}
-
-# Seam membership (D23): exact whole-line match, or a `dir/` line by prefix.
-in_seam() {
-  _rel=$1
-  _seam=$2
-  [ -f "$_seam" ] || return 1
-  grep -qFx "$_rel" "$_seam" && return 0
-  while IFS= read -r _line || [ -n "$_line" ]; do
-    case "$_line" in
-      */)
-        case "$_rel" in
-          "$_line"*) return 0 ;;
-        esac
-        ;;
-    esac
-  done <"$_seam"
-  return 1
-}
-
-deny() {
-  printf 'plumbbob: %s\n' "$1" >&2
-  exit 2
-}
-
-root=$(find_root) || exit 0 # no session anywhere above cwd: allow
-
-input=$(cat)
-path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.notebook_path // empty' 2>/dev/null)
-if [ -z "$path" ]; then
-  path=$(printf '%s' "$input" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
-  [ -z "$path" ] && path=$(printf '%s' "$input" | sed -n 's/.*"notebook_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
-fi
-[ -z "$path" ] && exit 0 # nothing to guard: allow
-
-state=$(tr -d '[:space:]' <"$root/.plumbbob/STATE" 2>/dev/null)
-
-# Canonicalize the absolute tool path to repo-relative (D4).
-case "$path" in
-  "$root"/*) rel=${path#"$root"/} ;;
-  *) rel=$path ;;
-esac
-
-# 1. The archive is read-only history — never writable (D6/D19).
-case "$rel" in
-  .plumbbob/archive/*)
-    deny "blocked: $rel is archived history (read-only). Do not retry."
-    ;;
-esac
-
-# 2. The three control docs are writable in every state, so DESIGN and FINISH can
-#    do their work. Anchored exact paths — never a bare */intent.md suffix (D6).
-case "$rel" in
-  .plumbbob/intent.md | .plumbbob/build-log.md | .plumbbob/report.md)
-    exit 0
-    ;;
-esac
-
-# 3. docs/ is writable only in FINISH (D19).
-case "$rel" in
-  docs/*)
-    [ "$state" = "FINISH" ] && exit 0
-    deny "blocked: $rel (docs/) is writable only in FINISH — docs are projected at the end. Do not retry; park it or finish the build first."
-    ;;
-esac
-
-# 4. Everything else is code: allowed only in BUILD, confined to the SEAM (D23).
-#    SPIKE locks the main tree like DESIGN (D18) — spike edits live in dormant
-#    worktrees, so the muzzle never needs to allow SPIKE here.
-if [ "$state" = "BUILD" ]; then
-  in_seam "$rel" "$root/.plumbbob/SEAM" && exit 0
-  deny "blocked: $rel is outside the seam for this step. Do not retry — park it (\`plumbbob park\`), or ask the human to revise the step's seam in intent.md and re-run \`plumbbob build <n>\`."
-fi
-
-deny "blocked: code edits are not allowed in ${state:-?} (they happen in BUILD). Do not retry — if this needs doing it's a decision: park it (\`plumbbob park\`) or ask the human to \`plumbbob build <n>\`."

package/skills/park/SKILL.md

@@ -1,26 +0,0 @@
----
-name: park
-description: Compose one tidy tagged park line, get the human's OK in-turn, then capture it by shelling `plumbbob park` — never by editing a file.
-disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ park:*)
----
-
-# Park
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
-
-## Wrong-state refusal
-
-Parking needs an **active session** to capture into. Read the state injected above: if it is `NO ACTIVE SESSION`, **refuse** and tell the human to run `plumbbob start "<title>"` first. Every active state (`DESIGN`, `BUILD`, `REVIEW`, `SPIKE`, `FINISH`) is fine — capture is always available, which is the whole point of parking.
-
-## What this skill does
-
-Take the idea, problem, or "ooh what if" the human just had and **compose it into one tidy, tagged line** — short, legible, self-contained, so it still reads cleanly weeks later. Then:
-
-1. **Show the composed line to the human** and wait for **in-turn approval** — they confirm it as-is or edit the wording.
-2. **Only after** that approval, capture it by running `__PLUMBBOB_BIN__ park "<the approved line>"` via Bash.
-
-## The one hard contract
-
-The capture itself is the **dumb CLI**, never an edit. This skill carries **no Edit and no Write tool** on purpose (D12): you may not append to `build-log.md` yourself. Compose, get approval, then shell `__PLUMBBOB_BIN__ park` — that is the only write path. If approval never comes, capture nothing.

package/skills/pb-done/SKILL.md

@@ -1,18 +0,0 @@
----
-name: pb-done
-description: Human-triggered driver for `plumbbob done` — ensure the check is green, take the checkpoint commit, record its SHA, and return to DESIGN.
-disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ done:*)
----
-
-# Plumbbob — finish a step (driver)
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
-
-This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob done` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
-
-## What it does
-
-1. Run `__PLUMBBOB_BIN__ done` via Bash.
-2. Report the verb's output verbatim — the checkpoint SHA and return to DESIGN, or any refusal (e.g. the check is red).

package/skills/pb-finish/SKILL.md

@@ -1,18 +0,0 @@
----
-name: pb-finish
-description: Human-triggered driver for `plumbbob finish` — refuse unless a report is archived, then archive, clear the session, and switch the muzzle off.
-disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ finish:*)
----
-
-# Plumbbob — finish the session (driver)
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
-
-This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob finish` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
-
-## What it does
-
-1. Run `__PLUMBBOB_BIN__ finish` via Bash.
-2. Report the verb's output verbatim. It is the closing gate — it **refuses unless `.plumbbob/report.md` exists**. If it refuses, relay that and tell the human to run `/plumbbob-report` first; do not write the report yourself from here.

package/skills/pb-review/SKILL.md

@@ -1,18 +0,0 @@
----
-name: pb-review
-description: Human-triggered driver for `plumbbob review` — run the heavy check and, if green, flip to REVIEW (muzzle back on) to read the diff cold.
-disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ review:*)
----
-
-# Plumbbob — review a step (driver)
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
-
-This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob review` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
-
-## What it does
-
-1. Run `__PLUMBBOB_BIN__ review` via Bash.
-2. Report the verb's output verbatim. If the heavy check is red the verb stays in BUILD and prints the failures — relay them and stop; fixing them is the human's call, not an automatic retry.

package/skills/pb-start/SKILL.md

@@ -1,19 +0,0 @@
----
-name: pb-start
-description: Human-triggered driver for `plumbbob start` — scaffold a new session (.plumbbob/, STATE=DESIGN, baseline commit) without leaving the chat.
-disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ start:*)
----
-
-# Plumbbob — start a session (driver)
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
-
-This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob start` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
-
-## What it does
-
-1. Read the session title from the way you were invoked (e.g. `/pb-start "fix the widget"` → title `fix the widget`). If no title is present, ask for one and run nothing.
-2. Run `__PLUMBBOB_BIN__ start "<title>"` via Bash.
-3. Report the verb's output verbatim. If it refuses (e.g. a session already exists), relay that and stop.

package/skills/pb-wrap/SKILL.md

@@ -1,18 +0,0 @@
----
-name: pb-wrap
-description: Human-triggered driver for `plumbbob wrap` — set STATE=FINISH so the report and docs skills can run.
-disable-model-invocation: true
-model: haiku
-allowed-tools: Bash(__PLUMBBOB_BIN__ status:*), Bash(__PLUMBBOB_BIN__ wrap:*)
----
-
-# Plumbbob — wrap into FINISH (driver)
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
-
-This is a **driver skill** — a chat-side trigger for the mechanical `plumbbob wrap` verb, so the whole workflow runs from the agent window instead of a terminal. It is `disable-model-invocation: true`: only the human fires it. It carries **no Edit and no Write tool** — its only action is to shell the verb and report the verb's output verbatim, including any refusal. The CLI is the source of truth: never retry a refused transition, and never edit a file to work around one.
-
-## What it does
-
-1. Run `__PLUMBBOB_BIN__ wrap` via Bash.
-2. Report the verb's output verbatim. FINISH is what unlocks `/plumbbob-report` and `/plumbbob-docs` — next, run `/plumbbob-report`.

package/skills/plumbbob-docs/SKILL.md

@@ -1,25 +0,0 @@
----
-name: plumbbob-docs
-description: FINISH-phase, optional docs update — conservatively project canonical intent into real docs/, only when warranted.
-disable-model-invocation: true
-model: opus
-allowed-tools: Read, Edit, Write, Bash(__PLUMBBOB_BIN__ status:*)
----
-
-# Plumbbob — update the docs
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ status`
-
-## Wrong-state refusal
-
-`docs/` is writable **only in FINISH** (D19) — the muzzle blocks it everywhere else. Read the state injected above and **refuse if it is not `FINISH`**, naming `plumbbob wrap` as the verb that enters FINISH (the report skill runs first; this docs pass is the optional second Finish step). If the state is `NO ACTIVE SESSION` the hooks are dormant and there is nothing for this skill to gate — just edit docs the ordinary way.
-
-## What this skill does
-
-**Conservative by default.** Most sessions write no docs at all — **a bug fix usually shouldn't spawn a doc**. Update real documentation under `docs/` only when the work genuinely changed how the system should be described, and only from the **canonical** parts of `intent.md` (the Frame, the Decisions) — never from the chat transcript.
-
-## The one hard contract
-
-- Default to doing nothing. Open a doc edit only when you can name what changed for a reader of `docs/`.
-- Project only from `intent.md`; the report is for the session, the docs are for the system.
-- Stay inside `docs/` — and only in FINISH. An edit anywhere else, or in any other state, is the muzzle's job to refuse, not yours to attempt.

package/skills/plumbbob-report/SKILL.md

@@ -1,35 +0,0 @@
----
-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_BIN__ status:*)
----
-
-# Plumbbob — write the report
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ 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

@@ -1,38 +0,0 @@
----
-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_BIN__ status:*)
----
-
-# Plumbbob — triage the park list
-
-Current session state (injected when this skill runs): !`__PLUMBBOB_BIN__ 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.