@accidentally-awesome-labs/opencode-bestest 0.4.3 → 0.5.0

package/opencode-assets/agents/plan-checker.md

@@ -14,7 +14,7 @@ You are the adversarial checker for a bestest project. You are read-only; you re
 - `[Ambiguity]` — a sentence two reasonable builders would implement differently. Quote it; say the two readings.
 - `[Conflict]` — two statements that cannot both hold. Cite both R-IDs/sections.
 - `[Assumption]` — a load-bearing `[assumed]` tag or an untagged claim with no `[user]`/`[cited:]` evidence.
-Check every R-N.M is real EARS (trigger + observable behavior, one sentence, testable), anti-goals ≥3, out_of_scope non-empty, doneness function falsifiable, autonomy contract present. Gaps and Conflicts are freeze-blockers.
+Check every R-N.M is real EARS (trigger + observable behavior, one sentence, testable), anti-goals ≥3, out_of_scope non-empty, user-facing docs dispositioned (R-IDs or out_of_scope), doneness function falsifiable, autonomy contract present. Gaps and Conflicts are freeze-blockers.
 
 **Plan mode** (given PLAN.md + cards + SPEC): hunt, in order:
 1. R-IDs with no covering card; cards citing phantom R-IDs; orphan cards serving no R-ID.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@accidentally-awesome-labs/opencode-bestest",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "OpenCode head for the bestest plugin: guard/lock/syntax enforcement shelling into the shared bash hooks, passive state injection, and an installer for skills/agents/commands.",
   "license": "MIT",
   "type": "module",

package/payload/VERSION

@@ -1 +1 @@
-0.4.3
+0.5.0

package/payload/agents/plan-checker.md

@@ -12,7 +12,7 @@ You are the adversarial checker for a bestest project. You are read-only; you re
 - `[Ambiguity]` — a sentence two reasonable builders would implement differently. Quote it; say the two readings.
 - `[Conflict]` — two statements that cannot both hold. Cite both R-IDs/sections.
 - `[Assumption]` — a load-bearing `[assumed]` tag or an untagged claim with no `[user]`/`[cited:]` evidence.
-Check every R-N.M is real EARS (trigger + observable behavior, one sentence, testable), anti-goals ≥3, out_of_scope non-empty, doneness function falsifiable, autonomy contract present. Gaps and Conflicts are freeze-blockers.
+Check every R-N.M is real EARS (trigger + observable behavior, one sentence, testable), anti-goals ≥3, out_of_scope non-empty, user-facing docs dispositioned (R-IDs or out_of_scope), doneness function falsifiable, autonomy contract present. Gaps and Conflicts are freeze-blockers.
 
 **Plan mode** (given PLAN.md + cards + SPEC): hunt, in order:
 1. R-IDs with no covering card; cards citing phantom R-IDs; orphan cards serving no R-ID.

package/payload/hooks/lock-guard.sh

@@ -60,13 +60,34 @@ patch_paths() {
 paths="$(get_file_path)"
 [ -n "$paths" ] || paths="$(patch_paths)"
 [ -n "$paths" ] || exit 0
-[ -f "$locks" ] || exit 0
 
 block() {
   echo "bestest lock-guard: '$rel' is frozen ($1). $2" >&2
   exit 2
 }
 
+# Spike quarantine: while STATE.md says 'stage: spike-<slug>', file-edit tools may
+# only touch .bestest/ (spike code lives in .bestest/spikes/<slug>/). Checked before
+# the LOCKS existence gate — a spike can predate any lock line.
+stage="$(grep -m1 -E '^stage:' "$root/.bestest/STATE.md" 2>/dev/null | sed -E 's/^stage:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]+$//')"
+case "${stage:-}" in
+  spike-*)
+    while IFS= read -r fp; do
+      [ -n "$fp" ] || continue
+      rel="${fp#"$root"/}"
+      case "$rel" in
+        .bestest/*) ;;
+        *) block "spike quarantine ($stage)" \
+          "Spike code stays in .bestest/spikes/. To exit: record verdict + disposition in the RQ file, then clear stage: per the research skill's spike protocol." ;;
+      esac
+    done <<EOF
+$paths
+EOF
+    ;;
+esac
+
+[ -f "$locks" ] || exit 0
+
 # Known limitation: STATE.md's card: pointer and the card files are writable (the
 # orchestrator updates them constantly). A builder that edits them to self-grant
 # may_edit_tests is caught downstream by the diff-scope gate: cards/STATE are never

package/payload/scripts/trace.sh

@@ -60,6 +60,14 @@ for c in $cards; do
   [ "$bigger" -ge 7 ] && fail "$name complexity $bigger >= 7 — split it (target <= 5)"
 done
 
+# spikes: a spike: block in a research RQ file must carry a disposition: by P3
+for rq in "$b"/research/RQ-*.md; do
+  [ -f "$rq" ] || continue
+  if grep -qE '^spike:' "$rq" && ! grep -qE '^disposition:' "$rq"; then
+    fail "$(basename "$rq") has a spike: block without a disposition: line"
+  fi
+done
+
 # --- full-chain checks (--all) -----------------------------------------------
 if [ "$mode" = "--all" ]; then
   for c in $cards; do

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

@@ -5,8 +5,8 @@ description: Use when routing a bestest project to its lifecycle phase — boots
 
 # 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.
+1. Read `.bestest/STATE.md`. If its `plugin:` path is missing on disk (harness switched), re-resolve per the harness map (using-bestest `references/<harness>.md`) and rewrite that line before anything else. 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, and the baseline test run (exact command, verbatim failure list) — 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; pre-existing failures become RISK entries in DECISIONS.md and no card `verify:` may expect them green — adopting one into scope is a `may_edit_tests: true` card plus a D-ID; (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.
@@ -32,6 +32,6 @@ All via explicit shell gate steps (LOCKS/SPEC are hook-frozen against file edits
 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).
+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). At P3+ the amendment cascades before the next dispatch: cut or patch every card citing a removed/changed R-ID (the amendment D-ID records the cuts), write cards for new R-IDs, re-run plan-checker card mode on touched cards and `trace.sh --plan` — both must pass; done cards citing amended R-IDs get their `verify:` re-run.
 
 Never skip a gate because the work "seems obvious" — gates are where the human front-loaded trust.

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

@@ -10,7 +10,7 @@ Report, compactly, from files only — no edits, no state changes, no "while I'm
 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.
+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. A dead `plugin:` path: report it and point at bestest-go (it re-resolves); do not fix it here.
 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/debug/SKILL.md

@@ -8,7 +8,7 @@ description: Use when a bestest build hits a defect that survives one obvious fi
 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.
+**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. A flaky test is a defect, never noise: its reproduction is a failure **rate** — N consecutive runs (≥10) recorded in the DEBUG file; the fix must reach 0/N, and retry-until-green is banned as both fix and verify.
 
 ## Loop
 1. Symptom: exact observed vs expected, error text verbatim.

package/payload/skills/interrogate/SKILL.md

@@ -10,6 +10,7 @@ Resumable state machine; `stage:` lives in STATE.md. Question discipline: `refer
 ## 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.
+**Imported PRD/spec:** evidence, never a draft SPEC — mine it for candidate requirements and `[user]` quotes, run every stage against it; material adoptions or deviations get D-IDs, and no claim enters SPEC §2 unchallenged.
 
 ## Stage 1 — Premise
 Six forcing questions, strictly one at a time, researching between answers so the next question is informed:
@@ -26,13 +27,13 @@ Between questions, search for existing tools that already solve it; present find
 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]`.
+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]`. A question only execution can answer → the research skill's spike protocol (timeboxed, hook-quarantined, disposition-mandatory).
 
 ## 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`:
+Every candidate requirement gets Include / Defer / Cut / Hold. `out_of_scope` must be non-empty with reasons; Deferred items go to the parking lot. User-facing docs (README, API reference, changelog) get an explicit disposition — Included = R-IDs, else out_of_scope with a reason. 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.

package/payload/skills/plan/SKILL.md

@@ -9,7 +9,7 @@ Input: frozen SPEC. Output: `.bestest/PLAN.md` (ordered index + rationale) and `
 
 ## 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.
+- **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. Its steps include re-confirming every version-sensitive `[cited:URL]` the stack rests on against the live page; drift → FRICTION + re-research before the next dispatch.
 - **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.

package/payload/skills/research/SKILL.md

@@ -16,6 +16,9 @@ Rule zero: **memory is a rumor.** Anything external — API shape, pricing, limi
 ## 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.
 
+## Spike — when only running code can answer
+A question that survives doc research and only execution can settle: add a `spike:` block to its RQ file (falsifiable question, timebox, answer shape) and set `stage: spike-<slug>` in STATE.md. From then on the lock-guard blocks writes outside `.bestest/` — spike code lives in `.bestest/spikes/<slug>/`, as crude as it likes. Paste run evidence into the RQ as `verdict:`, then disposition — mandatory, trace.sh fails P3 on any bare spike: `discarded` (delete the dir via an explicit shell step) or `promoted` — the finding enters SPEC/DECISIONS as `[cited:<RQ path>]`; cards rebuild it, spike code never ships. Clear `stage:` on exit. Discipline and edge cases: `references/spike.md`.
+
 ## Citation hygiene
 - Cite the page you actually fetched, not the search snippet.
 - Version-sensitive claims name the version and date.

package/payload/skills/research/references/spike.md

@@ -0,0 +1,25 @@
+# Spike discipline
+
+Throwaway code as a research instrument: the finding survives, the code never ships.
+
+## The block (top-level keys in the RQ file)
+
+```
+spike:
+  question: <falsifiable — a run answers yes/no/number>
+  timebox: <wall-clock budget, e.g. 2h>
+  answer_shape: <what evidence settles it: timing table, error text, works/fails>
+verdict: <pasted from the actual run — output, not paraphrase>
+disposition: discarded | promoted
+```
+
+One spike per RQ file; a second question is a second RQ.
+
+## Rules
+
+- **Quarantine is physical.** While `stage: spike-<slug>` is set in STATE.md, the lock-guard blocks file-edit tools outside `.bestest/`; spike code lives in `.bestest/spikes/<slug>/`. Hash and glob locks still apply inside `.bestest/` (LOCKS itself stays unwritable), and STATE.md stays editable — no deadlock clearing the stage.
+- **Timebox is the deadline for an answer.** Expiry → `verdict: unknown after <timebox>` and stop; extending needs a D-ID, not enthusiasm.
+- **Quality bar: none.** Spike code proves a point, not a design — no tests, no review, no cards, hardcode freely.
+- **Disposition is mandatory.** trace.sh (`--plan` and `--all`) fails any `spike:` block without a `disposition:` line — an open spike cannot cross into P3.
+- **Promotion moves the finding, never the code.** `promoted` = the verdict enters SPEC §5 / DECISIONS as `[cited:.bestest/research/RQ-<slug>.md]`; production cards rebuild the capability under the normal gates. Harvest exception: fixtures/test data may be copied out, but only by a task card that cites the spike RQ.
+- **Discard is a shell step.** `rm -rf .bestest/spikes/<slug>` — explicit and transcript-visible, never a file-tool delete.

package/payload/skills/ship/SKILL.md

@@ -8,7 +8,7 @@ description: Use when a bestest project enters P5 — UAT against every acceptan
 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).
+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). One retry per R-ID: a second UAT fail means build and criterion disagree at spec level — INTERRUPT with the exact mismatch: amend (D-ID + re-hash) or mark the row FAIL and carry it into go/no-go as an open risk. Never loop a third time.
 
 ## 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.

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

@@ -13,7 +13,7 @@ One lifecycle: **P0 interrogate → P1 research → P2 spec freeze → P3 plan
 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.
+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. One `.bestest/` per repo root, one session driving it at a time — concurrent sessions or multiple projects per root are unsupported (last writer wins on STATE.md).
 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.
 

package/payload/templates/SPEC.md

@@ -14,7 +14,8 @@ R-1.1 WHEN <trigger> [WHILE <state>] THE SYSTEM SHALL <observable behavior>. -->
 <!-- things this project deliberately will NOT do, each with the failure it prevents -->
 
 ## 4. Out of scope
-<!-- non-empty. Each line: item — reason — Include/Defer/Cut/Hold. Deferred items = parking lot. -->
+<!-- non-empty. Each line: item — reason — Include/Defer/Cut/Hold. Deferred items = parking lot.
+     User-facing docs (README, API reference, changelog) must appear here or as R-IDs in §2 — never undispositioned. -->
 
 ## 5. Stack (derived, cited)
 <!-- | layer | choice | why | evidence | — every row [cited:URL] from P1 research -->

package/payload/templates/STATE.md

@@ -5,7 +5,7 @@
 
 phase: P0            # P0 interrogate | P1 research | P2 spec | P3 plan | P4 build | P5 ship | done
 milestone: v1        # archived to .bestest/milestones/<milestone>/ at rollover
-stage: 0             # interrogation stage 0-6, or task id T-## during P4
+stage: 0             # interrogation stage 0-6, task id T-## during P4, or spike-<slug> (lock-guard quarantine)
 spec_hash: none      # sha256 recorded in .bestest/LOCKS at P2 freeze
 card: none           # project-relative path to the active task card (lock-guard reads this)