@accidentally-awesome-labs/opencode-bestest 0.4.3

package/payload/hooks/syntax-check.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# bestest: PostToolUse[Write|Edit|MultiEdit|apply_patch] syntax gate (SWE-agent lint pattern).
+# Extension-dispatched syntax check; no-op when no checker is installed.
+# Exit 2 feeds the error straight back to the model for an immediate fix.
+# Claude edits carry .tool_input.file_path; Codex/OpenCode apply_patch carries
+# the patch text in .tool_input.command — every touched file gets checked.
+set -u
+
+input="$(cat)"
+root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+get_file_path() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$input" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("tool_input",{}).get("file_path",""))
+except Exception: pass' 2>/dev/null
+  fi
+}
+
+get_command_text() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$input" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("tool_input",{}).get("command",""))
+except Exception: pass' 2>/dev/null
+  fi
+}
+
+patch_paths() {
+  cmd="$(get_command_text)"
+  case "$cmd" in
+    *'*** Begin Patch'*) ;;
+    *) return 0 ;;
+  esac
+  printf '%s\n' "$cmd" \
+    | sed -nE -e 's/^\*\*\* (Add|Update|Delete) File: //p' -e 's/^\*\*\* Move to: //p'
+}
+
+paths="$(get_file_path)"
+[ -n "$paths" ] || paths="$(patch_paths)"
+[ -n "$paths" ] || exit 0
+
+fail() {
+  echo "bestest syntax-check: $fp failed — fix before moving on:" >&2
+  echo "$1" >&2
+  exit 2
+}
+
+check_one_file() {
+  fp="$1"
+  out=""
+  case "$fp" in
+    *.py)
+      command -v python3 >/dev/null 2>&1 || return 0
+      out="$(python3 -c 'import ast,sys
+ast.parse(open(sys.argv[1]).read(), sys.argv[1])' "$fp" 2>&1)" || fail "$out" ;;
+    *.js|*.mjs|*.cjs)
+      command -v node >/dev/null 2>&1 || return 0
+      out="$(node --check "$fp" 2>&1)" || fail "$out" ;;
+    *.ts|*.tsx)
+      # Syntax-only (TS1xxx): single-file tsc without the project tsconfig would
+      # false-fail on jsx/paths/module settings (TS17004, TS2307, ...).
+      command -v tsc >/dev/null 2>&1 || return 0
+      out="$(tsc --noEmit --skipLibCheck --jsx preserve "$fp" 2>&1 | grep -F "$(basename "$fp")" | grep -E 'error TS1[0-9]{3}:')"
+      [ -n "$out" ] && fail "$out" ;;
+    *.sh|*.bash)
+      if command -v shellcheck >/dev/null 2>&1; then
+        out="$(shellcheck -S error "$fp" 2>&1)" || fail "$out"
+      else
+        out="$(bash -n "$fp" 2>&1)" || fail "$out"
+      fi ;;
+    *.json)
+      if command -v jq >/dev/null 2>&1; then
+        out="$(jq empty "$fp" 2>&1)" || fail "$out"
+      elif command -v python3 >/dev/null 2>&1; then
+        out="$(python3 -m json.tool "$fp" 2>&1 >/dev/null)" || fail "$out"
+      fi ;;
+  esac
+  return 0
+}
+
+while IFS= read -r fp; do
+  [ -n "$fp" ] || continue
+  # Patch headers are project-relative; anchor them to the project root.
+  case "$fp" in /*) : ;; *) fp="$root/$fp" ;; esac
+  # Deleted files (patch Delete headers) and unresolvable paths are skipped.
+  [ -f "$fp" ] || continue
+  check_one_file "$fp"
+done <<EOF
+$paths
+EOF
+
+exit 0

package/payload/scripts/trace.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# bestest trace: requirement-chain audit. Required gate evidence at P3 (--plan)
+# and P5 (--all). Prints PASS or numbered failures; nonzero exit on failure.
+#
+# Chain audited: SPEC R-N.M -> card frontmatter -> commit trailer 'Bestest-Req:'
+#                -> report FRICTION -> UAT line -> DISCOVERED dispositions.
+set -u
+
+mode="${1:---plan}"
+root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+b="$root/.bestest"
+fails=0
+fail() { fails=$((fails+1)); printf 'FAIL %02d: %s\n' "$fails" "$1"; }
+front() { awk '/^---$/{n++; next} n==1' "$1"; }  # frontmatter body of a card
+
+[ -f "$b/SPEC.md" ] || { echo "FAIL 01: no $b/SPEC.md — nothing to trace"; exit 1; }
+
+rids="$(grep -oE 'R-[0-9]+\.[0-9]+' "$b/SPEC.md" | sort -u)"
+[ -n "$rids" ] || fail "SPEC.md defines no R-N.M acceptance criteria"
+
+cards="$(ls "$b"/plans/T-*.md 2>/dev/null || true)"
+[ -n "$cards" ] || fail "no task cards in $b/plans/"
+
+# --- plan-level checks -------------------------------------------------------
+rid_re() { printf '(^|[^0-9.])%s([^0-9]|$)' "$(printf '%s' "$1" | sed 's/\./\\./g')"; }  # R-1.1 must not match R-1.10
+
+for r in $rids; do
+  covered=no
+  for c in $cards; do
+    front "$c" | grep -E '^requirements:' | grep -Eq "$(rid_re "$r")" && { covered=yes; break; }
+  done
+  [ "$covered" = yes ] || fail "$r has no covering task card"
+done
+
+for c in $cards; do
+  name="$(basename "$c")"
+  fm="$(front "$c")"
+
+  # cards may only cite R-IDs that exist in SPEC
+  for r in $(printf '%s' "$fm" | grep -E '^requirements:' | grep -oE 'R-[0-9]+\.[0-9]+' | sort -u); do
+    printf '%s\n' "$rids" | grep -qx "$r" || fail "$name cites $r which is not in SPEC.md"
+  done
+
+  # blocked_by targets must exist
+  for t in $(printf '%s' "$fm" | grep -E '^blocked_by:' | grep -oE 'T-[0-9]+'); do
+    [ -f "$b/plans/$t.md" ] || fail "$name blocked_by $t but $b/plans/$t.md does not exist"
+  done
+
+  # complexity: recompute floor from mechanical signals, compare to declared
+  nfiles="$(printf '%s' "$fm" | grep -E '^files:' | head -1 | tr ',' '\n' | grep -c '[^[:space:]]' || true)"
+  nverify="$(printf '%s\n' "$fm" | awk '/^verify:/{f=1;next} /^[a-zA-Z_]+:/{f=0} f&&/^[[:space:]]*-[[:space:]]/{c++} END{print c+0}')"
+  andflag=0
+  printf '%s' "$fm" | grep -E '^title:' | grep -Eq '[[:space:]][Aa]nd[[:space:]]' && andflag=1
+  declared="$(printf '%s' "$fm" | grep -E '^complexity:' | grep -oE '[0-9]+' | head -1)"
+  [ "$nfiles" -gt 0 ] || nfiles=1
+  floor=$(( 1 + 2 * (nfiles - 1) + 2 * nverify + 3 * andflag ))
+  [ -n "${declared:-}" ] || { fail "$name missing complexity: field"; declared=0; }
+  [ "$declared" -lt "$floor" ] && fail "$name understates complexity: declared $declared < mechanical floor $floor"
+  bigger=$(( declared > floor ? declared : floor ))
+  [ "$bigger" -ge 7 ] && fail "$name complexity $bigger >= 7 — split it (target <= 5)"
+done
+
+# --- full-chain checks (--all) -----------------------------------------------
+if [ "$mode" = "--all" ]; then
+  for c in $cards; do
+    id="$(basename "$c" .md)"
+    front "$c" | grep -Eq '^status:[[:space:]]*done' || continue
+    rep="$b/reports/$id.md"
+    if [ ! -f "$rep" ]; then
+      fail "$id is done but $rep is missing"
+    elif ! awk '/^## FRICTION/{f=1;next} /^## /{f=0} f&&/^[[:space:]]*<!--/{next} f&&NF{c++} END{exit c?0:1}' "$rep"; then
+      fail "$id report has empty FRICTION section (write 'None' if truly none)"
+    fi
+  done
+
+  for r in $rids; do
+    git -C "$root" log -E --grep="Bestest-Req:.*$(rid_re "$r")" --oneline -1 2>/dev/null | grep -q . \
+      || fail "$r has no commit with trailer 'Bestest-Req: $r'"
+    if [ -f "$b/UAT.md" ]; then
+      grep -Eq "$(rid_re "$r")" "$b/UAT.md" || fail "$r missing from UAT.md"
+    else
+      fail "no $b/UAT.md"
+    fi
+  done
+
+  if [ -f "$b/DISCOVERED.md" ]; then
+    while IFS= read -r line; do
+      printf '%s' "$line" | grep -q 'disposition:' \
+        || fail "DISCOVERED entry lacks disposition: ${line%%|*}"
+    done < <(grep -E '^- ' "$b/DISCOVERED.md")
+  fi
+fi
+
+if [ "$fails" -eq 0 ]; then
+  echo "PASS: $(printf '%s\n' "$rids" | grep -c .) requirements, $(printf '%s\n' "$cards" | grep -c .) cards, chain clean ($mode)"
+  exit 0
+fi
+exit 1

package/payload/skills/bestest-go/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: bestest-go
+description: Use when routing a bestest project to its lifecycle phase — bootstraps .bestest/ at P0 on first run.
+---
+
+# bestest-go — lifecycle router
+
+1. Read `.bestest/STATE.md`. If missing: `mkdir -p .bestest/plans .bestest/reports .bestest/research`, copy `templates/STATE.md` from the plugin root into `.bestest/STATE.md`, set `phase: P0`, `milestone: v1` and `plugin: <plugin root>` — the absolute directory containing the plugin's `skills/`, `templates/`, `scripts/`; the invoking command passes it pre-rendered where the harness supports that, otherwise resolve per the harness map (using-bestest `references/<harness>.md`). Skills resolve `trace.sh` and templates through this line. Append `.bestest/.session-snapshot` to the project's `.gitignore`, commit.
+   **Brownfield check** — the repo already contains product code (real source or git history, not scaffolding)? Then before interrogating: (a) dispatch one read-only subagent to write `.bestest/CODEBASE.md`, ≤60 lines: layout, entry points, build/run/test commands, observed conventions, integration seams, deploy surface — every claim cited to a file path; (b) seed `.bestest/LOCKS` via explicit shell commands with one `glob` line per existing test directory — incumbent tests are immutable to implementers from day one; (c) interrogation treats CODEBASE.md as context and existing behavior as `[cited:path]` fact, not something to re-ask the user.
+   Then load the **interrogate** skill and begin Stage 0 with the user's idea (ask for it if none was given).
+
+2. If `phase: done` (or the P5 ship gate is already logged and new work arrived): run **Milestone rollover** below.
+
+3. Otherwise route on `phase:` — load the named skill and resume exactly at `stage:` / `card:`:
+
+| phase | skill | exit gate (all evidence, no vibes) |
+|---|---|---|
+| P0 | interrogate (stages 0–2, then 4–5; stage 3 hands off to P1) | draft SPEC complete: Premise Verdict + EARS `R-N.M` criteria + non-empty out_of_scope + SPEC §8 doneness |
+| P1 | research | every external claim `[cited:URL]`; stack decision-brief approved → **return to interrogate stage 4** |
+| P2 | interrogate stage 6 (only) | rubric pass → Taste batch → Autonomy Contract → SPEC sha256 appended to LOCKS |
+| P3 | plan | plan-checker PASS (≤3 loops) + `trace.sh --plan` clean + one-screen user approval |
+| P4 | build | every card done: diff-scope clean, verify re-run, review closed |
+| P5 | ship | UAT per R-ID + `trace.sh --all` clean + DISCOVERED dispositioned + user go/no-go |
+
+4. On gate pass: update STATE.md (phase, next action, gate log line, and **re-derive Open interrupts from scratch** — an answered interrupt left standing misroutes the next session), commit `.bestest/`, announce the phase transition in one sentence, continue.
+
+## Milestone rollover (P5 shipped → next milestone)
+
+All via explicit shell gate steps (LOCKS/SPEC are hook-frozen against file edits):
+1. `N` = STATE `milestone:` (default v1). `mkdir -p .bestest/milestones/N` and `git mv` SPEC.md, PLAN.md, UAT.md, RUNBOOK.md, plans/, reports/, research/ into it, plus a `cp` snapshot of the final STATE.md (its gate log is the milestone's ledger). DECISIONS.md, LESSONS.md, DISCOVERED.md stay live — history and debt carry forward.
+2. Rewrite LOCKS dropping the SPEC `hash` line (the archived SPEC keeps its frozen copy); keep every test `glob` — incumbent tests stay immutable.
+3. Fresh STATE.md from the template: `phase: P0`, `milestone: N+1`, same `plugin:` line. Commit `.bestest: roll over N -> N+1`.
+4. Re-enter **interrogate** Stage 0 as brownfield: prior SPEC (`.bestest/milestones/N/SPEC.md`), the DISCOVERED backlog, and LESSONS are the opening context — the new idea is interrogated against what already ships, and unshipped R-IDs must be explicitly re-adopted or cut, never assumed.
+
+Amending a frozen SPEC: new D-ID in DECISIONS.md → apply the edit via an explicit shell gate step → re-hash the `hash` line in LOCKS (the lock-guard block message points here).
+
+Never skip a gate because the work "seems obvious" — gates are where the human front-loaded trust.

package/payload/skills/bestest-status/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: bestest-status
+description: Use when reporting bestest project state — strictly read-only dashboard, never mutates anything.
+---
+
+# bestest-status — dashboard (STRICTLY READ-ONLY)
+
+Report, compactly, from files only — no edits, no state changes, no "while I'm here" fixes:
+
+1. `.bestest/STATE.md` — phase, stage, active card, next action, open interrupts.
+2. Gate log — which gates passed, with dates.
+3. Counts: task cards by status (todo/doing/done), DISCOVERED.md lines lacking `disposition:`, open risks in DECISIONS.md.
+4. If P3+: run `"$PLUGIN"/scripts/trace.sh --plan` where `PLUGIN` = the `plugin:` line in STATE.md (read-only) and show PASS or its failure lines.
+5. One line: "Next: <the next action verbatim from STATE.md>".
+
+If `.bestest/` is missing, say so and point at the **bestest-go** skill.

package/payload/skills/build/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: build
+description: Use when a bestest project enters P4 — orchestrate fresh subagents through task cards with mechanical gates, closed feedback loops, and risk-scaled review.
+---
+
+# Build
+
+You are the **orchestrator**: dispatch, gate, close loops. You do not write product code; builders do.
+
+## Dispatch loop
+1. **Pick:** lowest-numbered incomplete card whose `blocked_by:` are all done. Set `card:` + `stage:` in STATE.md, mark card `doing`, note `task-start=$(git rev-parse HEAD)`.
+2. **Dispatch a fresh subagent** with: the card, LESSONS.md ("read first, append what you learn"), relevant D-IDs. File handoffs only — builders write code + `.bestest/reports/T-##.md`; they get no chat history.
+3. **Builder contract** (put in the prompt): follow the card exactly; TDD (the failing test exists — make it pass, never edit it); commit with trailer `Bestest-Req: <R-IDs>`; on any underdetermined point return `BLOCKED: <specific question>` instead of improvising; report claim→evidence + FRICTION (or `None`) + Discovered.
+4. **Gate mechanically** (never trust the report):
+   - Re-run every `verify:` command yourself; paste output.
+   - `git diff --name-only <task-start>..HEAD` ⊆ card `files:` — out-of-scope diffs get reverted or INTERRUPT; locked paths must show zero diff.
+   - Report FRICTION section present; Discovered lines actually appended to DISCOVERED.md.
+5. **Close the loop:** FRICTION → patch the *remaining* cards now + append environment facts to LESSONS.md — before the next dispatch, not "later".
+6. **Review** (risk-scaled): dispatch **reviewer** agent — card weight ≥4 → full adversarial pass; weight <4 → blockers-only. A finding closes only *fixed-and-reconfirmed by the reviewer*, or waived as a D-ID with a revisit trigger.
+7. Mark done, update STATE.md, commit `.bestest/`, next card.
+
+## Interrupt handling
+- `BLOCKED:` from a builder → answer from SPEC/DECISIONS if derivable; else it's a real gap: INTERRUPT the user, record the answer as a D-ID, redispatch.
+- **Loop tripwire:** same command failing 3× with the same error, or two states alternating 3× → stop the lane, record the signature in LESSONS, escalate to **debug** skill.
+- 3 failed fix attempts on one card → debug skill; debug can't crack it → architecture escape: INTERRUPT with a one-paragraph problem statement + 2 options.
+- Out-of-blast-radius discovery → one line in DISCOVERED.md: `- <summary> | discovered-from: T-## | blocks: <T-## or none>`. Never fix silently, never drop.
+- LESSONS.md line format: `- [env|tool|codebase] <fact> (T-##)`.
+
+Autonomy Contract (SPEC §9) governs everything above; GATED actions stop the line no matter what a card says.

package/payload/skills/debug/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: debug
+description: Use when a bestest build hits a defect that survives one obvious fix attempt, a loop tripwire fires, or a card fails review 3× — hypothesis-driven debugging with a repro-test iron law.
+---
+
+# Debug
+
+Open `.bestest/DEBUG-<slug>.md` (template: DEBUG.md). The file is the investigation; your memory is not.
+
+## Iron law
+**No fix until a failing reproduction test exists.** Smallest deterministic test that shows the defect — it becomes a permanent regression test (author it under a `may_edit_tests: true` micro-card). Can't reproduce it → you have an observation problem, not a bug fix; instrument first.
+
+## Loop
+1. Symptom: exact observed vs expected, error text verbatim.
+2. List hypotheses — **every** plausible cause, cheapest-to-probe first. For each: the discriminating probe (a command, log, or breakpoint that splits the world in two).
+3. Probe one hypothesis at a time. Killed → **Eliminated** (append-only, with evidence). Never re-litigate an eliminated hypothesis; never fix two hypotheses at once.
+4. Confirmed → minimal fix → repro test passes → re-run the card's `verify:` + affected R-ID checks.
+5. Record the root-cause pattern in LESSONS.md if any future card could hit it.
+
+Three exhausted hypothesis rounds → architecture escape (see build skill). A debug that changes SPEC-visible behavior is an INTERRUPT, not a quiet patch.

package/payload/skills/interrogate/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: interrogate
+description: Use when starting a new bestest project or resuming P0/P2 — staged interrogation that challenges a raw idea until ambiguity, gaps, and pointless work are gone, ending in a frozen SPEC.
+---
+
+# Interrogate
+
+Resumable state machine; `stage:` lives in STATE.md. Question discipline: `references/question-protocol.md`. Challenge moves: `references/challenge-tactics.md`. Findings accumulate directly into a draft `.bestest/SPEC.md` (template: SPEC.md) and DECISIONS.md as you go — never hold them in memory.
+
+## Stage 0 — Intake
+Listen uninterrupted. Then play back 2–3 **materially different** interpretations of the idea ("A: a CLI for you; B: a service for your team; C: a library others embed") and have the user pick or correct. Record verbatim quotes as `[user]`.
+**Brownfield:** if `.bestest/CODEBASE.md` or a prior milestone SPEC exists, open from them — each interpretation must say how it fits the existing system, and facts they establish are `[cited:path]`, never re-asked.
+
+## Stage 1 — Premise
+Six forcing questions, strictly one at a time, researching between answers so the next question is informed:
+1. **Demand reality** — who concretely hits this problem, how often, what do they do today?
+2. **Status quo** — why is doing nothing unacceptable?
+3. **Desperate specificity** — describe the single worst recent incident of the problem.
+4. **Narrowest wedge** — what is the smallest version that would still be used weekly?
+5. **Observation** — how will we observe (not hope) that it worked?
+6. **Future-fit** — what changes in 12 months that kills or grows this?
+
+Between questions, search for existing tools that already solve it; present findings before asking the user to justify building. Exit: a written **Premise Verdict** the user confirms — or an honest recommendation to pivot or park.
+
+## Stage 2 — Discovery
+Adaptive, domain-specific gray areas across five buckets: users/actors · data & lifecycle · integration surface · failure/abuse · **Anti-Goals (mandatory, ≥3)**. Present options annotated with what research already found ("Postgres and SQLite both fit; SQLite unless you need concurrent writers — you said single user"). Batch related Taste questions; never ask what Stage-3 research can derive.
+
+## Stage 3 — Research handoff
+Zero user questions by default. Load the **research** skill: fan-out → primary sources → adversarial verification → cited stack table → SLOPCHECK on every proposed dependency. Output: SPEC §5 rows, all `[cited:URL]`.
+
+## Stage 4 — Challenge
+Now attack the accumulated idea (tactics reference): name tensions between stated goals; run the pre-mortem and contribute your own top-2 failure causes; challenge API/library assumptions against fetched docs, not memory; goal-trace every feature back to the Premise Verdict and propose purging orphans; offer an alternative for every weight≥6 decision.
+
+## Stage 5 — Scope freeze
+Every candidate requirement gets Include / Defer / Cut / Hold. `out_of_scope` must be non-empty with reasons; Deferred items go to the parking lot. Write acceptance criteria in **EARS grammar**, one sentence each, numbered `R-N.M`:
+`WHEN <trigger> [WHILE <state>] THE SYSTEM SHALL <observable behavior>.`
+If a criterion can't be phrased as observable behavior, it isn't a criterion — rework it.
+Close the stage by writing **SPEC §8 — the doneness function**: the falsifiable test the P5 go/no-go will evaluate verbatim.
+
+## Stage 6 — Spec & contract freeze (P2 gate)
+1. **Rubric pass:** dispatch the plan-checker agent in spec mode. Findings come back typed `[Gap]` `[Ambiguity]` `[Conflict]` `[Assumption]` with R-ID cites. Freeze is blocked until every Gap/Conflict is fixed or explicitly accepted as a D-ID.
+2. **Taste batch:** present all open judgment calls at once — "N calls I'll make unless you veto."
+3. **Autonomy Contract:** walk the user through SPEC §9; get explicit agreement.
+4. **Freeze:** on the user's explicit approval, run the gate step:
+```bash
+mkdir -p .bestest && h="$( (command -v sha256sum >/dev/null && sha256sum .bestest/SPEC.md || shasum -a 256 .bestest/SPEC.md) | cut -d' ' -f1)" && printf 'hash %s .bestest/SPEC.md\nglob <test-glob>\n' "$h" >> .bestest/LOCKS
+```
+Set `spec_hash:` in STATE.md, commit, advance to P3. This is the **last HIGH-touch moment** — everything after runs on the contract.

package/payload/skills/interrogate/references/challenge-tactics.md

@@ -0,0 +1,21 @@
+# Challenge tactics (Stage 4)
+
+Run all five; report what each found, even if "nothing".
+
+## 1. Tension naming
+Find pairs of stated goals that pull against each other ("offline-first" vs "always-fresh data"; "zero config" vs "multi-tenant"). Name the tension, state which side the current spec silently picked, make the user pick explicitly. D-ID the resolution.
+
+## 2. Pre-mortem
+"It's 6 months later and this project failed / is unused. Why?" Collect the user's causes, then add **your own top-2** — the ones the user is least likely to say (usually: 'the underlying need was occasional, not weekly' and 'integration friction beat the benefit'). Each cause → RISK entry with a tripwire, or a spec change now.
+
+## 3. Doc-cited API challenge
+Every external API/library the idea leans on: fetch the current docs (never trust memory — training data is stale) and verify the load-bearing assumption: rate limits, auth model, pricing, deprecations, platform requirements. Cite what you fetched. One mismatch here can invalidate the whole premise — that's an INTERRUPT, not a footnote.
+
+## 4. Goal-tracing purge
+Walk every feature/requirement back to the Premise Verdict. Anything that doesn't trace is a candidate purge — present the list: "these N items serve no stated goal; cut or justify." Justification creates a new stated goal (user confirms) — silence cuts it.
+
+## 5. Alternatives for heavy decisions
+Every weight≥6 decision gets one genuinely different alternative (not a strawman), with the strongest honest case for it in two sentences. If the user's choice survives the strongest opposing case, it's load-tested; if it flips, the challenge just paid for the whole interrogation.
+
+## SLOPCHECK (dependency vetting, used by Stage 3)
+For each proposed dependency: last release date · open-issue trend · maintainer bus-factor · install weight · license · does the stdlib/platform already do this? Reject any dep that fails two, unless a D-ID records why it's worth it.

package/payload/skills/interrogate/references/question-protocol.md

@@ -0,0 +1,21 @@
+# Question protocol
+
+**Prime Rule: never ask what's derivable.** If docs, code, research, or prior answers can answer it, derive and show your work instead. Asking a derivable question spends user trust and screen time for nothing.
+
+## Classify every decision
+- **Mechanical** — one defensible answer exists (lib version, file layout). Decide, record D-ID, move on. Never ask.
+- **Taste** — several defensible answers; user preference is the tiebreaker (naming, UX tone, strictness). Batch these; present as "I'll do X unless you veto."
+- **User-Challenge** — the user's stated position conflicts with evidence. Always surface, one at a time, evidence first.
+
+## Weight before asking
+`weight = irreversibility (1-3) × scope (1-3)`. Ask only weight ≥ 4. Below that: decide, D-ID, continue. Weight ≥ 6 additionally requires presenting one real alternative.
+
+## Decision brief (the only question format)
+> **Decision:** one line. **Context:** ≤3 lines, what research found. **Options:** A (recommended, why) / B (why not) [/ C]. **Default if no answer:** A.
+
+One decision per message during Stages 1 and 4. No stacked questions.
+
+## Budget & escapes
+- ~25 asked decisions per project. At 20, warn; at 25, switch to **auto-pilot**: everything becomes Mechanical-with-D-ID except GATED items and User-Challenges.
+- **Readiness meter** on every interrogation message: `readiness: 6/10 — premise firm, data lifecycle unknown, no anti-goals yet`. The user can say "freeze" at any level; record the gaps as RISK entries.
+- **2-probe cap on vagueness:** if two rephrasings of the same question both get vague answers, stop probing — record a RISK ("R-x rests on assumed usage pattern [assumed]") and continue. Vague twice means the user doesn't know yet; the risk register, not the user, carries it from here.

package/payload/skills/plan/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: plan
+description: Use when a bestest project enters P3 — turn the frozen SPEC into zero-context task cards that survive the plan-checker and trace.sh.
+---
+
+# Plan
+
+Input: frozen SPEC. Output: `.bestest/PLAN.md` (ordered index + rationale) and `.bestest/plans/T-##.md` cards (template: task-card.md). Assets the build needs (data, fixtures, images, seeds): `references/assets.md`.
+
+## Card discipline
+- **Zero-context contract:** a fresh subagent with only the card + LESSONS.md must succeed. Exact paths, signatures, data shapes, D-ID pointers. No placeholders, no "as discussed".
+- **Tracer bullet first:** T-01 is always the thinnest end-to-end slice through the real stack — it flushes environment lies before they infect ten cards.
+- **TDD pairing:** tests are authored by a card with `may_edit_tests: true`; the implementer card that follows has `false` and makes them pass (the lock-guard hook enforces this physically).
+- **Complexity formula**, computed honestly on every card: `1 + 2/extra file + 2/verify command + 3 if the title needs "and" + 2/new interface`. Over 6 → split before anyone reviews it.
+- Every card: `requirements:` R-IDs (no orphan cards), `files:` blast radius, `verify:` commands a machine can re-run, `blocked_by:` for real order constraints only.
+
+## Complexity Justification table (in PLAN.md)
+Any design element beyond the simplest thing satisfying the R-IDs gets a row: `| Complexity | Why needed | Simpler alternative rejected because |`. No row → the plan-checker counts it as a blocker. This is where architecture astronautics goes to die.
+
+## Checker loop (gate)
+1. Dispatch **plan-checker** agent (card mode) with PLAN.md + cards + SPEC.
+2. It recomputes complexity, hunts placeholders, orphan cards, uncovered R-IDs, missing assets, unjustified complexity. Verdict PASS or numbered blockers.
+3. Fix and redispatch — **max 3 loops**; still failing → the SPEC is probably wrong: INTERRUPT the user with the specific contradiction.
+4. Run `"$PLUGIN"/scripts/trace.sh --plan` where `PLUGIN` = the `plugin:` line in STATE.md — must print PASS (this is gate evidence, attach output).
+5. Show the user one screen: task list, order, complexity totals, justification table. Approval → P4. (Card tampering by builders is caught mechanically: cards are never in a card's own `files:` list, so any card edit fails the diff-scope gate.)

package/payload/skills/plan/references/assets.md

@@ -0,0 +1,15 @@
+# Asset planning
+
+Builds fail on missing *stuff* more often than missing code. During P3, walk SPEC §6 and make every asset a card or a card field — never an implicit hope.
+
+## Checklist per asset
+- **Data/fixtures:** source (generated? scraped? user-provided?), shape (schema written down), volume, refresh story. Generated data gets a generation card with a `verify:` that checks shape + count.
+- **Images/media:** who produces them (model-generated placeholder vs user-supplied final), exact dimensions/format, where they live. Placeholder art is fine if a DISCOVERED line records the swap-before-ship.
+- **Seeds/config/env:** every env var named in a card; secrets are GATED (user provides, never fabricated, never committed — verify `.gitignore` covers their file in the tracer card).
+- **External accounts/keys:** API keys, OAuth apps, buckets — user-provided, requested at plan approval (not mid-build, where they stall a subagent).
+- **Test doubles:** which externals get faked in tests, and one contract test per fake that pins the real shape it mimics.
+
+## Rules
+- An asset nobody is assigned to produce is a plan bug — the plan-checker flags it.
+- Asset-producing cards run **before** their consumers (`blocked_by:`).
+- If an asset needs the user (credentials, brand art, real data), collect it at the P3 approval screen — batch, once.

package/payload/skills/research/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: research
+description: Use when a bestest project needs external facts — P1 stack derivation, doc-cited challenges, or any claim that must be [cited:URL] instead of remembered.
+---
+
+# Research
+
+Rule zero: **memory is a rumor.** Anything external — API shape, pricing, limit, version, benchmark — is `[assumed]` until a fetched URL says otherwise. `[assumed]` load-bearing claims block the P1 gate.
+
+## Loop (per research question)
+1. **Frame** — write `.bestest/research/RQ-<slug>.md`: the question, why it matters (which R-ID/decision it feeds), what answer shape is needed.
+2. **Fan out** — dispatch researcher agents in parallel, one per RQ (or per candidate for comparisons). Each returns findings with URLs; they write their own RQ file (file handoff, not chat recall).
+3. **Verify adversarially** — for each load-bearing claim, one attempt to refute it: a second independent source, or the primary source read closely (changelogs, pricing pages, GitHub issues beat blog posts). Claims that survive get `[cited:URL]`; claims that don't get flagged to the user or dropped.
+4. **Synthesize** — decision-brief per open decision: options, recommendation, evidence rows. Feed SPEC §5 / DECISIONS.
+
+## Stack derivation (P1)
+Stack is an **output**, never an input. From SPEC constraints (platform, team skills `[user]`, data shape, scale honesty from the Premise) derive candidates → SLOPCHECK every dependency (see interrogate references) → produce the stack decision-brief table, every row cited. Present once, whole, for user approval — that's the single P1 gate.
+
+## Citation hygiene
+- Cite the page you actually fetched, not the search snippet.
+- Version-sensitive claims name the version and date.
+- Two sources disagree → say so in the brief; don't silently pick.
+- A dead/paywalled source is not a citation.

package/payload/skills/ship/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ship
+description: Use when a bestest project enters P5 — UAT against every acceptance criterion, full-chain audit, discovered-work disposition, production runbook, and the go/no-go.
+---
+
+# Ship
+
+Nothing new gets built here; P5 proves what exists and stages it for production.
+
+## 1. UAT — one question per criterion
+Create `.bestest/UAT.md` (template). For each `R-N.M` in SPEC §2: restate the EARS criterion as a single check the user can answer, attach the evidence pointer (command output, screenshot, URL), walk the user through them **one at a time**. Any fail → back to P4 with a card citing that R-ID; do not negotiate the criterion mid-UAT (that's a SPEC amendment: D-ID + re-hash).
+
+## 2. Full-chain audit
+`"$PLUGIN"/scripts/trace.sh --all` where `PLUGIN` = the `plugin:` line in STATE.md must print PASS — attach output as gate evidence. It enforces: every criterion covered, every done card reported with FRICTION, every R-ID committed with a `Bestest-Req:` trailer and present in UAT.
+
+## 3. Disposition DISCOVERED.md — every line
+Append `| disposition:` to each: `fix-now` (micro-card, run it) / `deferred to <where>` / `wontfix because <reason>`. trace.sh fails any bare line. This is where "never dropped" gets cashed.
+
+## 4. LESSONS curation
+Compress LESSONS.md: dedupe, drop task-local noise, keep durable environment/codebase facts. Offer the user the top items for promotion to the project memory file (per harness map) — their call, one batch.
+
+## 5. Runbook
+Fill `.bestest/RUNBOOK.md` (template) for the actual derived stack. The rollback section requires a **rehearsal transcript** — actually roll back once, paste it. Timeouts, observability floor, negative-path security smoke, restore drill, spend ceiling: each filled or `n/a + reason`.
+
+## 6. Go/no-go
+One screen: doneness function (SPEC §8) evaluated verbatim · UAT table · trace PASS · runbook gaps · open risks with tripwires. The user says go or no-go. **Deploy itself is GATED** — even after "go", the deploy command runs only with explicit user approval, per the Autonomy Contract.
+
+On "go": log the gate, set `phase: done` in STATE.md, commit. The lifecycle is complete — the router's next run offers **milestone rollover** (archive to `.bestest/milestones/`, re-enter P0 brownfield).

package/payload/skills/using-bestest/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: using-bestest
+description: Use when any bestest-managed project work happens — constitution for the bestest lifecycle, its state files, and its non-negotiable laws.
+---
+
+# Using bestest
+
+One lifecycle: **P0 interrogate → P1 research → P2 spec freeze → P3 plan → P4 build → P5 ship**, routed by the **bestest-go** skill, resumable from `.bestest/STATE.md` after any context clear or compaction (a hook re-injects it).
+
+## Laws
+
+1. **State lives in `.bestest/`, committed.** Memory is disposable; files are not. Update STATE.md at every gate and task boundary — it is what future-you wakes up to.
+2. **Evidence before claims.** Every "done", "works", "faster" carries evidence: command output, diff, or `[cited:URL]`. Tag facts `[user]` / `[cited:URL]` / `[assumed]`.
+3. **Never ask what's derivable.** Research first; ask only weight≥4 decisions (weight = irreversibility × scope).
+4. **The Autonomy Contract (SPEC §9) governs.** PROCEED / INTERRUPT / GATED — when in doubt, INTERRUPT beats improvising.
+5. **Locks are physical — and root-scoped.** Frozen SPEC and test files are hook-enforced, but hooks see only the session's project root: run bestest sessions from the target repo's root, or locks, guards, state injection, and drift tracking silently don't apply. Don't fight the guard; follow the amendment path it names.
+6. **Discovered ≠ do.** Out-of-blast-radius work goes to DISCOVERED.md — never fixed silently, never dropped.
+7. **Compactness is the product.** Budgets in README are law; exceeding them is a bug.
+
+Use your harness's natives — planning mode, todo tracking, subagents, structured questions, worktrees; bestest adds no substitutes. Its names for them, plugin-root resolution, and guarded tools: `references/<harness>.md` (claude-code, codex, opencode).

package/payload/skills/using-bestest/references/claude-code.md

@@ -0,0 +1,16 @@
+# Harness map — Claude Code
+
+| Concept | Native here |
+|---|---|
+| Router | `/bestest:go`, `/bestest:status` (plugin command stubs → bestest-go/bestest-status skills) |
+| Plugin root | `${CLAUDE_PLUGIN_ROOT}`, pre-rendered inside the command stubs; bootstrap records it as the `plugin:` line in STATE.md |
+| Planning mode | plan mode — read-only exploration before mutating anything |
+| Todo tracking | TodoWrite — one entry per gate step or card |
+| Structured user questions | AskUserQuestion — batch weight≥4 decisions into one call |
+| Subagent dispatch | Task tool; plan-checker / researcher / reviewer ship as plugin agents; parallel dispatch supported |
+| Isolation | git worktrees |
+| Compaction survival | SessionStart hook (matcher startup\|resume\|clear\|compact) re-injects STATE.md lines 1–60 + LOCKS + drift notice |
+| Memory file (LESSONS promotion) | CLAUDE.md |
+| Guarded tools | Bash → guard.sh; Write/Edit/MultiEdit → lock-guard.sh, syntax-check.sh |
+
+Everything above is wiring, not behavior: the laws in using-bestest are identical on every harness.

package/payload/skills/using-bestest/references/codex.md

@@ -0,0 +1,17 @@
+# Harness map — Codex CLI
+
+| Concept | Native here |
+|---|---|
+| Router | `$bestest-go` / `$bestest-status` skill mentions (or implicit trigger by description) |
+| Plugin root | newest dir from `ls -d ~/.codex/plugins/cache/*/bestest/*` — bootstrap records it as the `plugin:` line in STATE.md (hooks also get `${CLAUDE_PLUGIN_ROOT}` env) |
+| Planning mode | `/plan` |
+| Todo tracking | built-in plan/update_plan facility |
+| Structured user questions | plain chat — one decision per message, options lettered |
+| Subagent dispatch | prose-directed dispatch works once roles are registered; **bootstrap extra (gated shell step): copy `adapters/codex/agents/*.toml` from the plugin root into the project's `.codex/agents/`** — plugin-bundled agents don't auto-register; depth 1 |
+| Isolation | separate checkout (no native worktree command) |
+| Compaction survival | SessionStart + PostCompact hooks re-inject STATE.md lines 1–60 + LOCKS + drift notice |
+| Memory file (LESSONS promotion) | AGENTS.md (32 KiB read cap) |
+| Guarded tools | shell → guard.sh; apply_patch (file edits) → lock-guard.sh, syntax-check.sh |
+| Hook trust | hooks need a one-time trust review at install; any script update re-flags them — re-trust or they silently stop enforcing |
+
+Everything above is wiring, not behavior: the laws in using-bestest are identical on every harness.

package/payload/skills/using-bestest/references/opencode.md

@@ -0,0 +1,18 @@
+# Harness map — OpenCode
+
+| Concept | Native here |
+|---|---|
+| Router | `/bestest-go`, `/bestest-status` commands (installed stubs → skills) |
+| Skill names | installed with a `bestest-` prefix (`bestest-interrogate`, `bestest-plan`, …) — prose saying "the interrogate skill" means `bestest-interrogate` |
+| Plugin root | `.opencode/bestest` (runtime payload the installer copied); recorded as the `plugin:` line in STATE.md at bootstrap |
+| Planning mode | Plan agent (Tab-cycled primary) |
+| Todo tracking | todowrite tool |
+| Structured user questions | question tool — batch weight≥4 decisions |
+| Subagent dispatch | task tool with the installed plan-checker / researcher / reviewer agents (`@mention` or prose-directed) |
+| Isolation | git worktrees via your own shell steps |
+| Compaction survival | `opencode.json` instructions loads `.bestest/.context.md` (plugin-maintained digest: STATE.md 1–60 + LOCKS + active card + DRIFT); compaction re-inject rides the plugin |
+| Memory file (LESSONS promotion) | AGENTS.md |
+| Guarded tools | bash → guard.sh; write/edit/apply_patch → lock-guard.sh, syntax-check.sh — via the `@accidentally-awesome-labs/opencode-bestest` npm plugin (exit 2 → blocked) |
+| Degraded mode | without the npm plugin there are NO guards, no auto-injection, no drift detection — commands still resume by reading `.bestest/STATE.md` |
+
+Everything above is wiring, not behavior: the laws in using-bestest are identical on every harness.

package/payload/templates/DEBUG.md

@@ -0,0 +1,17 @@
+# DEBUG — <symptom slug>
+<!-- One file per investigation: .bestest/DEBUG-<slug>.md. Survives /clear. -->
+
+## Symptom
+<!-- exact observed behavior + exact expected behavior; error text verbatim -->
+
+## Reproduction test
+<!-- IRON LAW: no fix until a failing repro test exists. Path + command + failing output. -->
+
+## Hypotheses
+<!-- | H# | hypothesis | cheapest discriminating probe | status: open/confirmed/eliminated | -->
+
+## Eliminated (append-only)
+<!-- H# + the evidence that killed it — never retry an eliminated hypothesis -->
+
+## Fix + verification
+<!-- diff summary; repro test now passing (output); which R-IDs re-verified -->

package/payload/templates/DECISIONS.md

@@ -0,0 +1,11 @@
+# DECISIONS — append-only
+<!-- Never rewrite history; supersede with a new D-ID that references the old. -->
+
+## Decisions
+<!-- D-001 | class: Mechanical/Taste/User-Challenge | weight: N | decision | rationale | evidence: [user]/[cited:URL]/[assumed] -->
+
+## Risk register
+<!-- RISK-001 | description | likelihood | blast radius | tripwire that reopens it -->
+
+## Review waivers
+<!-- D-0NN | class: Waiver | finding waived | why acceptable | revisit trigger (date or event) — waivers are decisions, same D-ID sequence -->