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

package/README.md

@@ -12,8 +12,8 @@ bunx @accidentally-awesome-labs/opencode-bestest init   # or npx
 `init` is idempotent (re-run it to update) and supports `--dry-run` and `--global` (skills/agents/commands into `~/.config/opencode/`). It:
 
 - copies the lifecycle skills into `.opencode/skills/` (prefixed `bestest-*`)
-- installs the plan-checker / researcher / reviewer agents and `/bestest-go` + `/bestest-status` commands
-- copies the runtime payload (guard scripts, `trace.sh`, templates) to `.opencode/bestest/`
+- installs the plan-checker / researcher / reviewer agents (pointer stubs — their canonical bodies ride the payload, so `--global` installs need a project `init` before the roles resolve) and `/bestest-go` + `/bestest-status` commands
+- copies the runtime payload (guard scripts, `trace.sh`, templates, canonical agent bodies) to `.opencode/bestest/`
 - wires `opencode.json`: the `@accidentally-awesome-labs/opencode-bestest` plugin (enforcement) and an `instructions` entry that passively injects `.bestest/.context.md` — the plugin-maintained digest of STATE + LOCKS + active card + DRIFT notice
 
 Then open opencode and run `/bestest-go`.

package/bin/init.ts

@@ -60,7 +60,7 @@ for (const kind of ["agents", "commands"]) {
 
 // 4. Runtime payload for project sessions: hooks (shim targets), trace.sh, templates.
 if (!GLOBAL) {
-  for (const part of ["hooks", "scripts", "templates"]) {
+  for (const part of ["agents", "hooks", "scripts", "templates"]) {
     doCopy(join(src, part), join(cwd, ".opencode", "bestest", part))
   }
   const version = existsSync(join(src, "VERSION")) ? readFileSync(join(src, "VERSION"), "utf8").trim() : "dev"

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

@@ -7,21 +7,4 @@ permission:
   webfetch: deny
 ---
 
-You are the adversarial checker for a bestest project. You are read-only; you report, you never fix. Your job is to be the reviewer who finds the hole *before* it costs a build day. A clean PASS you didn't earn is a failure of yours, not a success of theirs.
-
-**Spec mode** (given SPEC.md): grade completeness, clarity, consistency, measurability, coverage, traceability. Every finding typed and cited:
-- `[Gap]` — something the build will need that no section provides (asset, actor, failure path, data lifecycle).
-- `[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, 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.
-2. **Recompute complexity** per card from its own fields (`1 + 2/extra file + 2/verify cmd + 3 if title needs "and" + 2/new interface`); declared < recomputed, or >6 unsplit → blocker.
-3. Zero-context violations: placeholders, "as discussed", missing signatures/paths, a card a fresh stranger couldn't execute.
-4. Assets consumed but never produced (check `blocked_by:` ordering too).
-5. Complexity Justification table: any structure beyond the simplest satisfying design without a row → blocker.
-6. TDD pairing: implementer cards with `may_edit_tests: true`, or no failing-test card ahead of them.
-
-Verdict format, both modes: `PASS` or `FAIL` + numbered blockers, each with file/R-ID cite and the one-line fix you'd accept. Nits go in a separate short list — never pad blockers.
+Read the file `agents/plan-checker.md` under the bestest plugin root — the `plugin:` line in this project's `.bestest/STATE.md` names that root (this harness: `.opencode/bestest`) — and follow it exactly for the task you were given. You are read-only: never modify any file.

package/opencode-assets/agents/researcher.md

@@ -8,13 +8,4 @@ permission:
   bash: deny
 ---
 
-You research exactly one question (RQ) for a bestest project. Your training data is presumed stale: every claim you return must come from a page you fetched **this session**.
-
-Method:
-1. Read the RQ file you were given; note the answer shape it needs and which decision it feeds.
-2. Search broadly, then fetch primary sources — official docs, changelogs, pricing pages, GitHub issues/releases — over blogs and search snippets. For version- or price-sensitive facts, find the date on the page.
-   For version-sensitive TOOL behavior, docs may describe an unreleased major: prefer running the pinned tool itself (`--help`, a scratch project) over reading about it, and cite the run.
-3. Adversarially check each load-bearing claim: one honest attempt to refute it via a second independent source. Disagreement is a finding — report both sides, don't pick silently.
-4. For dependency candidates, run SLOPCHECK: last release, issue trend, bus factor, install weight, license, "does the platform already do this?".
-
-Write findings into the RQ file: each claim on its own line, tagged `[cited:URL]` (the URL you fetched, not the search result), or `[assumed]` if you genuinely could not verify — with what you tried. Finish with a ≤5-line summary: the answer, confidence, and what would change it. Your final message is just the RQ file path and that summary.
+Read the file `agents/researcher.md` under the bestest plugin root — the `plugin:` line in this project's `.bestest/STATE.md` names that root (this harness: `.opencode/bestest`) — and follow it exactly for the research question you were given. Write only into `.bestest/research/`.

package/opencode-assets/agents/reviewer.md

@@ -6,17 +6,4 @@ permission:
   webfetch: deny
 ---
 
-You review one completed task card for a bestest project. Read-only: you may run read-only commands (tests, linters, `git diff`) but change nothing. You are reviewing the *diff against the card*, not the codebase's life story.
-
-Inputs: the card, the diff range, the report, SPEC.md, relevant D-IDs.
-
-**Depth is risk-scaled by card `weight:`**
-- **weight ≥ 4 — full adversarial:** actively try to break it. Trace the R-IDs' EARS triggers through the code by hand; probe edge/failure paths the tests skip; check the claim→evidence table by re-running what's cheap; hunt silent contract drift (behavior the SPEC forbids, error paths swallowed, security footguns in the diff).
-- **weight < 4 — blockers-only:** correctness of the R-ID behavior, verify commands genuinely proving it, diff staying inside `files:`. No style opinions.
-
-Always check, any weight:
-1. Tests: do they *assert the criterion* or just execute the code? A test the implementation can't fail is a blocker at weight≥4, a flag below.
-2. Report honesty: any claim whose evidence doesn't hold up = blocker, regardless of code quality.
-3. `Bestest-Req:` trailer present and citing the card's R-IDs.
-
-Verdict: `APPROVED` or numbered findings, each: severity (blocker/flag), file:line, what breaks, the smallest fix you'd accept. A finding you raised closes only when you re-confirm the fix — say explicitly what you'd need to see. Do not approve out of fatigue; do not block on taste.
+Read the file `agents/reviewer.md` under the bestest plugin root — the `plugin:` line in this project's `.bestest/STATE.md` names that root (this harness: `.opencode/bestest`) — and follow it exactly for the card you were given. Read-only on product code: run verify commands, never edit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@accidentally-awesome-labs/opencode-bestest",
-  "version": "0.5.0",
+  "version": "0.6.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.5.0
+0.6.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, user-facing docs dispositioned (R-IDs or out_of_scope), 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. `deliverable: findings` SPECs: R-IDs are research questions — require a named verdict shape and evidence bar per R-ID instead of EARS. 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

@@ -95,10 +95,15 @@ esac
 may_edit_tests="false"
 card="$(grep -m1 -E '^card:' "$root/.bestest/STATE.md" 2>/dev/null | sed -E 's/^card:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]+$//')"
 if [ -n "${card:-}" ] && [ -f "$root/$card" ]; then
-  # frontmatter only — a mention of may_edit_tests in the card body must not count
-  if awk '/^---$/{n++; next} n==1' "$root/$card" | grep -m1 -Eq '^may_edit_tests:[[:space:]]*true'; then
-    may_edit_tests="true"
-  fi
+  case "${card##*/}" in
+    Q-*) ;;  # quick lane: may_edit_tests is always false — a tampered grant must not count
+    *)
+      # frontmatter only — a mention of may_edit_tests in the card body must not count
+      if awk '/^---$/{n++; next} n==1' "$root/$card" | grep -m1 -Eq '^may_edit_tests:[[:space:]]*true'; then
+        may_edit_tests="true"
+      fi
+      ;;
+  esac
 fi
 
 check_one_path() {

package/payload/hooks/session-start.sh

@@ -51,6 +51,12 @@ if [ -f "$b/SPEC.md" ]; then
   echo "Autonomy contract in force: SPEC.md section 9 (PROCEED / INTERRUPT / GATED)."
 fi
 
+phase_cur="$(grep -m1 -E '^phase:' "$b/STATE.md" 2>/dev/null | sed -E 's/^phase:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]+$//')"
+if [ "$phase_cur" = "done" ] || [ "$phase_cur" = "quick" ]; then
+  echo
+  echo "Post-ship contract: phase is done — this project's audit chain (gate log, Bestest-Req trailers) requires every new change, any size, to land through the quick lane (a Q-card per the router skill's references/quick.md; template and trace.sh --quick under the STATE plugin: root) or a milestone rollover. A direct untracked edit breaks the chain the shipped milestone was accepted on."
+fi
+
 if [ -f "$snap" ]; then
   old_head="$(grep -m1 '^HEAD=' "$snap" | cut -d= -f2-)"
   old_dirty="$(grep -m1 '^DIRTY=' "$snap" | cut -d= -f2-)"
@@ -60,4 +66,42 @@ if [ -f "$snap" ]; then
   fi
 fi
 
+# STALE-STATE: the injected STATE is only as good as its last rewrite. If product
+# code moved >= STALE_N commits past it, the phase/card/next-action above may lie.
+# Every probe fails silent (no git, never-committed STATE, dirty STATE = just touched).
+STALE_N=5
+state_c="$(git -C "$root" log -1 --format=%H -- .bestest/STATE.md 2>/dev/null || true)"
+state_dirty="$(git -C "$root" status --porcelain -- .bestest/STATE.md 2>/dev/null || true)"
+if [ -n "$state_c" ] && [ -z "$state_dirty" ]; then
+  behind="$(git -C "$root" rev-list --count "$state_c..HEAD" -- . ':(exclude).bestest' 2>/dev/null || echo 0)"
+  if [ "${behind:-0}" -ge "$STALE_N" ] 2>/dev/null; then
+    echo
+    echo "STALE-STATE: $behind product commits since STATE.md was last rewritten. The injected phase/card/next-action above may be stale — re-derive them (and Open interrupts) from git log, plans/*.md status, and reports/, rewrite STATE.md, commit, then continue."
+  fi
+fi
+
+# DECISIONS revisit scan: surface (never act on) waiver/risk lines whose
+# 'revisit' date has arrived. Quieted by an appended 'D-0NN revisited <date>: ...'
+# line — DECISIONS stays append-only. ISO dates compare lexicographically.
+if [ -f "$b/DECISIONS.md" ]; then
+  today="$(date +%Y-%m-%d 2>/dev/null || true)"
+  if [ -n "$today" ]; then
+    due=""
+    while IFS= read -r ln; do
+      d="$(printf '%s' "$ln" | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | head -1)"
+      [ -n "$d" ] || continue
+      [ "$d" \> "$today" ] && continue
+      did="$(printf '%s' "$ln" | grep -oE '(D|RISK)-[0-9]+' | head -1)"
+      if [ -n "$did" ] && grep -i 'revisited' "$b/DECISIONS.md" 2>/dev/null | grep -qE "(^|[^0-9])${did}([^0-9]|$)"; then continue; fi
+      due="${due}${ln}
+"
+    done < <(grep -iE 'revisit' "$b/DECISIONS.md" 2>/dev/null | grep -E '[0-9]{4}-[0-9]{2}-[0-9]{2}' || true)
+    if [ -n "$due" ]; then
+      echo
+      echo "### DECISIONS revisit due (surface only — no auto-action; quiet each with an appended 'D-0NN revisited $today: <outcome>' line)"
+      printf '%s' "$due"
+    fi
+  fi
+fi
+
 exit 0

package/payload/scripts/trace.sh

@@ -12,18 +12,195 @@ 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
+rid_re() { printf '(^|[^0-9.])%s([^0-9]|$)' "$(printf '%s' "$1" | sed 's/\./\\./g')"; }  # R-1.1 must not match R-1.10
+section_filled() { awk -v s="## $2" '$0 ~ "^"s{f=1;next} /^## /{f=0} f&&/^[[:space:]]*<!--/{next} f&&NF{c++} END{exit c?0:1}' "$1"; }
+check_spikes() { # every spike: block in a research RQ file must carry a disposition:
+  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
+}
+check_discovered() { # every DISCOVERED entry needs a disposition by ship
+  [ -f "$b/DISCOVERED.md" ] || return 0
+  while IFS= read -r line; do
+    printf '%s' "$line" | grep -q 'disposition:' \
+      || fail "DISCOVERED entry lacks disposition: ${line%%|*}"
+  done < <(grep -E '^- ' "$b/DISCOVERED.md")
+}
+check_roadmap() { # check_roadmap <1 to also require a verdict on the current milestone's ledger line>
+  ms_cur="$(grep -m1 -E '^milestone:' "$b/STATE.md" 2>/dev/null | sed -E 's/^milestone:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]+$//')"
+  if [ ! -f "$b/ROADMAP.md" ]; then
+    fail "no $b/ROADMAP.md — copy templates/ROADMAP.md and append this milestone's intent line"
+    return 0
+  fi
+  [ "$(wc -l < "$b/ROADMAP.md" | tr -d ' ')" -le 40 ] || fail "ROADMAP.md exceeds its 40-line cap — compress old ledger lines"
+  [ -n "${ms_cur:-}" ] || return 0
+  ml="$(grep -E "^[[:space:]]*$ms_cur[[:space:]]*\|" "$b/ROADMAP.md" | head -1)"
+  if [ -z "$ml" ]; then
+    fail "ROADMAP.md has no ledger line for milestone $ms_cur (append: '$ms_cur | intent: <one clause>')"
+  elif [ "$1" = 1 ]; then
+    printf '%s' "$ml" | grep -q 'verdict:' || fail "ROADMAP.md ledger line for $ms_cur lacks a verdict — complete it before go/no-go"
+  fi
+}
 
 [ -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"
 
+# --- quick-lane checks (--quick): Q-cards only, then exit --------------------
+if [ "$mode" = "--quick" ]; then
+  # tamper canary: the quick lane never amends the SPEC
+  lh="$(grep -m1 -E '^hash [0-9a-f]+ \.bestest/SPEC\.md' "$b/LOCKS" 2>/dev/null | awk '{print $2}')"
+  if [ -n "${lh:-}" ]; then
+    if command -v sha256sum >/dev/null 2>&1; then ch="$(sha256sum "$b/SPEC.md" | cut -d' ' -f1)"
+    else ch="$(shasum -a 256 "$b/SPEC.md" | cut -d' ' -f1)"; fi
+    [ "$lh" = "$ch" ] || fail "SPEC.md no longer matches its LOCKS hash — the quick lane never amends the SPEC"
+  fi
+
+  qcards="$(ls "$b"/plans/Q-*.md 2>/dev/null || true)"
+  [ -n "$qcards" ] || fail "no quick cards in $b/plans/"
+  qn="$(printf '%s\n' "$qcards" | grep -c . || true)"
+  [ "$qn" -gt 5 ] && fail "$qn quick cards since last rollover — this is a milestone; run rollover"
+  manifests='package.json package-lock.json pnpm-lock.yaml yarn.lock bun.lockb Cargo.toml Cargo.lock go.mod go.sum pyproject.toml requirements.txt requirements-dev.txt Gemfile Gemfile.lock pom.xml build.gradle build.gradle.kts composer.json composer.lock'
+
+  for qc in $qcards; do
+    qid="$(basename "$qc" .md)"
+    qfm="$(front "$qc")"
+    rlist=""
+
+    printf '%s' "$qfm" | grep -Eq '^may_edit_tests:[[:space:]]*false' \
+      || fail "$qid may_edit_tests must be false on the quick lane"
+
+    qfiles="$(printf '%s' "$qfm" | grep -E '^files:' | head -1 | sed 's/^files:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr ',' '\n' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' | grep -v '^$' || true)"
+    nq="$(printf '%s\n' "$qfiles" | grep -c . || true)"
+    { [ "$nq" -ge 1 ] && [ "$nq" -le 3 ]; } || fail "$qid files: must list 1-3 paths (found $nq)"
+
+    qreq="$(printf '%s' "$qfm" | grep -E '^requirements:' | head -1 | sed 's/^requirements:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]*$//')"
+    case "$qreq" in
+      none|refactor) : ;;
+      *) rlist="$(printf '%s' "$qreq" | grep -oE 'R-[0-9]+\.[0-9]+' || true)"
+         [ -n "$rlist" ] || fail "$qid requirements: must be none, refactor, or the R-IDs it restores"
+         for r in $rlist; do
+           printf '%s\n' "$rids" | grep -qx "$r" || fail "$qid cites $r which is not in SPEC.md"
+         done ;;
+    esac
+
+    qdid="$(printf '%s' "$qfm" | grep -E '^decision:' | grep -oE 'D-[0-9]+' | head -1)"
+    if [ -n "${qdid:-}" ]; then
+      grep -q "$qdid" "$b/DECISIONS.md" 2>/dev/null || fail "$qid decision $qdid not found in DECISIONS.md"
+    else
+      fail "$qid missing decision: D-### field"
+    fi
+
+    qstart="$(printf '%s' "$qfm" | grep -E '^start:' | head -1 | sed 's/^start:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]*$//')"
+    changed=""
+    if git -C "$root" rev-parse -q --verify "$qstart^{commit}" >/dev/null 2>&1; then
+      changed="$( { git -C "$root" diff --name-only "$qstart"..HEAD; git -C "$root" status --porcelain | awk '{print $NF}'; } 2>/dev/null | grep -v '^\.bestest/' | sort -u || true)"
+      while IFS= read -r chp; do
+        [ -n "$chp" ] || continue
+        printf '%s\n' "$qfiles" | grep -qxF -- "$chp" || fail "$qid touched $chp outside its files: list — escalate (status: escalated + DISCOVERED line)"
+      done <<QEOF
+$changed
+QEOF
+    else
+      fail "$qid start: sha does not resolve"
+    fi
+
+    # neither declared files nor actual changes may hit locked paths or manifests
+    for p in $(printf '%s\n%s\n' "$qfiles" "$changed" | grep -v '^$' | sort -u); do
+      pb="$(basename "$p")"
+      for m in $manifests; do
+        [ "$pb" = "$m" ] && fail "$qid touches dependency manifest $p — that is a milestone, not a quick fix"
+      done
+      [ "$p" = ".bestest/LOCKS" ] && fail "$qid touches the lock registry"
+      if [ -f "$b/LOCKS" ]; then
+        while IFS= read -r line; do
+          kind="${line%% *}"
+          case "$kind" in
+            hash) hp="$(printf '%s' "$line" | awk '{print $3}')"
+                  [ "$p" = "$hp" ] && fail "$qid touches hash-locked $p" ;;
+            glob) pat="$(printf '%s' "$line" | cut -d' ' -f2-)"
+                  case "$p" in $pat) fail "$qid touches glob-locked $p — a fix needing test edits is a milestone" ;; esac ;;
+          esac
+        done < "$b/LOCKS"
+      fi
+    done
+
+    qstatus="$(printf '%s' "$qfm" | grep -E '^status:' | head -1 | grep -oE 'doing|done|escalated' | head -1)"
+    case "${qstatus:-}" in
+      doing) : ;;
+      done)
+        qrep="$b/reports/$qid.md"
+        if [ ! -f "$qrep" ]; then
+          fail "$qid is done but report $qrep is missing"
+        else
+          section_filled "$qrep" FRICTION || fail "$qid report has empty FRICTION section (write 'None' if truly none)"
+          section_filled "$qrep" Lessons  || fail "$qid report has empty Lessons section (list the LESSONS.md lines appended, or 'None')"
+          if [ "$qreq" = refactor ]; then
+            section_filled "$qrep" 'Verify output' || fail "$qid refactor card needs the green incumbent-suite run pasted in Verify output"
+          fi
+        fi
+        git -C "$root" log -E --grep="Bestest-Req:.*$qid([^0-9]|\$)" --oneline -1 2>/dev/null | grep -q . \
+          || fail "$qid has no commit with trailer 'Bestest-Req: $qid'"
+        if [ -n "$rlist" ]; then
+          for r in $rlist; do
+            grep -E "$(rid_re "$r")" "$b/UAT.md" 2>/dev/null | grep -Eq "requick|$qid" \
+              || fail "$r restored by $qid needs a requick row in UAT.md"
+          done
+        fi
+        ;;
+      escalated)
+        grep -q "discovered-from: $qid" "$b/DISCOVERED.md" 2>/dev/null \
+          || fail "$qid escalated without a DISCOVERED.md line (discovered-from: $qid)"
+        ;;
+      *) fail "$qid status must be doing | done | escalated" ;;
+    esac
+  done
+
+  if [ "$fails" -eq 0 ]; then
+    echo "PASS: $qn quick cards, chain clean (--quick)"
+    exit 0
+  fi
+  exit 1
+fi
+
+# --- findings-terminal checks (--findings): no cards, the deliverable is FINDINGS.md
+if [ "$mode" = "--findings" ]; then
+  check_roadmap 1
+  check_spikes
+  check_discovered
+  [ -f "$b/FINDINGS.md" ] || fail "no $b/FINDINGS.md (template: FINDINGS.md)"
+  [ -f "$b/UAT.md" ] || fail "no $b/UAT.md"
+  for r in $rids; do
+    rq_ok=no
+    for rq in "$b"/research/RQ-*.md; do
+      [ -f "$rq" ] || continue
+      if grep -Eq "$(rid_re "$r")" "$rq" && grep -qE '^verdict:' "$rq" && grep -q '\[cited:' "$rq"; then
+        rq_ok=yes; break
+      fi
+    done
+    [ "$rq_ok" = yes ] || fail "$r has no research RQ file with a cited verdict"
+    if [ -f "$b/FINDINGS.md" ]; then
+      grep -Eq "$(rid_re "$r")" "$b/FINDINGS.md" || fail "$r missing from FINDINGS.md"
+    fi
+    if [ -f "$b/UAT.md" ]; then
+      grep -Eq "$(rid_re "$r")" "$b/UAT.md" || fail "$r missing from UAT.md"
+    fi
+  done
+  if [ "$fails" -eq 0 ]; then
+    echo "PASS: $(printf '%s\n' "$rids" | grep -c .) findings requirements, chain clean (--findings)"
+    exit 0
+  fi
+  exit 1
+fi
+
 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
@@ -60,13 +237,42 @@ 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"
+# ROADMAP: direction artifact — intent line by P3, verdict by P5, 40-line cap
+rv=0; [ "$mode" = "--all" ] && rv=1
+check_roadmap "$rv"
+
+# PLAN.md index <-> plans/ card set, both ways (the amendment cascade patches the
+# plan index together with the cards; cuts live in the amendment D-ID, not here)
+if [ -f "$b/PLAN.md" ]; then
+  plan_ids="$(grep -oE 'T-[0-9]+' "$b/PLAN.md" | sort -u)"
+  for c in $cards; do
+    id="$(basename "$c" .md)"
+    printf '%s\n' "$plan_ids" | grep -qx "$id" || fail "PLAN.md index missing $id — the amendment cascade patches the plan, not just cards"
+  done
+  for id in $plan_ids; do
+    [ -f "$b/plans/$id.md" ] || fail "PLAN.md cites $id but $b/plans/$id.md does not exist (cuts live in the amendment D-ID; drop them from the index)"
+  done
+else
+  fail "no $b/PLAN.md (card index + rationale; template: PLAN.md)"
+fi
+
+# CODEBASE.md must postdate the last milestone rollover — it is cited as fact
+# at re-interrogation. Skipped when uncommitted (just regenerated) or pre-rollover.
+if [ -d "$b/milestones" ]; then
+  if [ ! -f "$b/CODEBASE.md" ]; then
+    fail "no $b/CODEBASE.md after rollover — regenerate it (bestest-go rollover step 4)"
+  else
+    cb_t="$(git -C "$root" log -1 --format=%ct -- .bestest/CODEBASE.md 2>/dev/null)"
+    ms_t="$(git -C "$root" log -1 --format=%ct -- .bestest/milestones 2>/dev/null)"
+    cb_dirty="$(git -C "$root" status --porcelain -- .bestest/CODEBASE.md 2>/dev/null)"
+    if [ -n "$cb_t" ] && [ -n "$ms_t" ] && [ -z "$cb_dirty" ] && [ "$cb_t" -lt "$ms_t" ]; then
+      fail "CODEBASE.md predates the last milestone rollover — regenerate it (bestest-go rollover step 4)"
+    fi
   fi
-done
+fi
+
+# spikes: a spike: block in a research RQ file must carry a disposition: by P3
+check_spikes
 
 # --- full-chain checks (--all) -----------------------------------------------
 if [ "$mode" = "--all" ]; then
@@ -76,8 +282,19 @@ if [ "$mode" = "--all" ]; then
     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)"
+    else
+      section_filled "$rep" FRICTION \
+        || fail "$id report has empty FRICTION section (write 'None' if truly none)"
+      # Lessons propagation: every '- ' line the report claims was appended must
+      # actually be in LESSONS.md (substring match survives P5 curation merges).
+      if section_filled "$rep" Lessons; then
+        while IFS= read -r ln; do
+          grep -qF -- "$ln" "$b/LESSONS.md" 2>/dev/null \
+            || fail "$id Lessons line not in LESSONS.md: $ln"
+        done < <(awk '/^## Lessons/{f=1;next} /^## /{f=0} f&&/^-[[:space:]]/' "$rep")
+      else
+        fail "$id report has empty Lessons section (list the LESSONS.md lines appended, or 'None')"
+      fi
     fi
   done
 
@@ -91,12 +308,7 @@ if [ "$mode" = "--all" ]; then
     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
+  check_discovered
 fi
 
 if [ "$fails" -eq 0 ]; then

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

@@ -5,11 +5,11 @@ description: Use when routing a bestest project to its lifecycle phase — boots
 
 # bestest-go — lifecycle router
 
-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.
+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`, `ROADMAP.md`, `LESSONS.md` and `DISCOVERED.md` from the plugin root into `.bestest/`, 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` (template: CODEBASE.md — every claim path-cited, red baseline verbatim); (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.
+2. If `phase: quick`: resume the Q-card per `references/quick.md`. If `phase: done` and new work arrives: below-SPEC fixes, shipped-behavior restorations, and ≤3-file behavior-preserving refactors take the quick lane (`references/quick.md`); anything larger runs **Milestone rollover** below.
 
 3. Otherwise route on `phase:` — load the named skill and resume exactly at `stage:` / `card:`:
 
@@ -21,17 +21,20 @@ description: Use when routing a bestest project to its lifecycle phase — boots
 | 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 |
+| quick | this skill, `references/quick.md` | `trace.sh --quick` PASS → `phase: done`, gate logged |
+
+Findings deliverable (`deliverable: findings` in SPEC): P2 freeze → `phase: P5`, skip logged; gate `trace.sh --findings` (research `references/findings.md`).
 
 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.
+1. `N` = STATE `milestone:` (default v1). `mkdir -p .bestest/milestones/N` and `git mv` SPEC.md, PLAN.md, UAT.md, RUNBOOK.md, CODEBASE.md, FINDINGS.md, plans/, reports/, research/ (those that exist) 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, ROADMAP.md stay live — history, debt and direction 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.
+4. Re-enter **interrogate** Stage 0 as brownfield — regenerate CODEBASE.md first (step 1a contract; trace.sh fails a stale one): prior SPEC (`.bestest/milestones/N/SPEC.md`), ROADMAP.md, the DISCOVERED backlog, and LESSONS are the opening context — the new idea is interrogated against what already ships; unshipped R-IDs and deferred DISCOVERED lines 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). 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.
+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 plus PLAN.md's index (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-go/references/quick.md

@@ -0,0 +1,29 @@
+# Quick lane — Q-cards
+
+One card, no SPEC/PLAN above it. For work below SPEC visibility: a post-ship defect fix that *restores* shipped behavior, a tiny fix no R-ID describes, or a ≤3-file behavior-preserving refactor. Anything that would alter or create an R-ID's observable behavior is a milestone — never negotiate that boundary.
+
+## Entry (only from `phase: done`)
+1. Copy `templates/quick-card.md` (plugin root = the STATE.md `plugin:` line) to `.bestest/plans/Q-##.md`, next free number.
+2. Fill the frontmatter: 1–3 `files:`; `requirements:` = `none`, the R-IDs the fix restores, or `refactor`; `start: $(git rev-parse HEAD)`.
+3. Append the authorizing decision to DECISIONS.md — why this is below SPEC visibility, or which R-ID it restores — and set its D-ID in `decision:`.
+4. Set STATE.md `phase: quick`, `stage: Q-##`, `card: .bestest/plans/Q-##.md`; commit `.bestest/`.
+
+## Work rules
+- Read LESSONS.md first; append what you learn. This is the lane's edge: milestone-earned facts serve a five-minute fix.
+- All locks stand: frozen SPEC, test globs (`may_edit_tests` is clamped false on Q-cards — a fix that needs a test edit escalates), destructive-command guard, drift detection.
+- Out-of-scope findings → one DISCOVERED.md line; never fixed here.
+- Commit with trailer `Bestest-Req: Q-##`.
+
+## Close — the whole ceremony, keep it minutes
+1. Run every `verify:` command; write `.bestest/reports/Q-##.md` (claim→evidence, verify output, FRICTION, Lessons).
+2. Restored R-IDs: one `requick` row per R-ID in UAT.md. Refactor: paste the green incumbent-suite run in the report's Verify output; no UAT row.
+3. `"$PLUGIN"/scripts/trace.sh --quick` (`PLUGIN` = the `plugin:` line) must print PASS — gate evidence.
+4. Card `status: done`; STATE back to `phase: done`, clear `stage:`/`card:`, gate-log line, commit `.bestest/`.
+
+## Escalation — any eligibility breach
+A lock block, a 4th file, a needed test or dependency-manifest edit, R-ID behavior change: set `status: escalated`, append a DISCOVERED.md line (`| discovered-from: Q-##`), offer milestone rollover. The block message is the trigger, not an obstacle to argue with.
+
+## Bounds
+- More than 5 Q-cards since the last rollover: trace fails — that backlog is a milestone; roll over.
+- Refactors beyond 3 files are milestones whose SPEC states the preservation invariants as ordinary R-IDs, derived from CODEBASE.md and the prior SPEC.
+- Q-cards and their reports archive with the next rollover like everything else; the counter resets there.

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

@@ -9,8 +9,9 @@ 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. 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>".
+3. Counts: task cards by status (todo/doing/done), DISCOVERED.md lines lacking `disposition:`, open risks in DECISIONS.md — list RISK rows and any due `revisit:` dates verbatim.
+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 (findings projects: `--findings`). A dead `plugin:` path: report it and point at bestest-go (it re-resolves); do not fix it here.
+5. One line from ROADMAP.md: Destination + Next up (absent: say so).
+6. 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

@@ -8,13 +8,13 @@ description: Use when a bestest project enters P4 — orchestrate fresh subagent
 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)`.
+1. **Pick:** lowest-numbered incomplete card whose `blocked_by:` are all done. Set `card:` + `stage:` + `task_start: $(git rev-parse HEAD)` in STATE.md, mark card `doing`.
 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.
+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`) + Lessons (the exact LESSONS.md lines appended, 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.
+   - `git diff --name-only <task_start from STATE.md>..HEAD` ⊆ card `files:` — out-of-scope diffs get reverted or INTERRUPT; locked paths must show zero diff.
+   - Report FRICTION and Lessons sections 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.
@@ -23,7 +23,7 @@ You are the **orchestrator**: dispatch, gate, close loops. You do not write prod
 - `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-##)`.
+- Out-of-blast-radius discovery → one line in DISCOVERED.md (format in its header). Never fix silently, never drop.
+- LESSONS.md line format: in its header (template: LESSONS.md).
 
 Autonomy Contract (SPEC §9) governs everything above; GATED actions stop the line no matter what a card says.

package/payload/skills/interrogate/SKILL.md

@@ -21,7 +21,7 @@ Six forcing questions, strictly one at a time, researching between answers so th
 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.
+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. A premise whose deliverable is knowledge, not software: record `deliverable: findings` — question-shaped R-IDs, P3–P4 skipped (research `references/findings.md`).
 
 ## 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.
@@ -35,8 +35,8 @@ Now attack the accumulated idea (tactics reference): name tensions between state
 ## 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. 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.
+If a criterion can't be phrased as observable behavior, it isn't a criterion — rework it. (Findings projects: question R-IDs — grammar in research `references/findings.md`.)
+Close the stage by writing **SPEC §8 — the doneness function**: the falsifiable test the P5 go/no-go will evaluate verbatim — and appending this milestone's intent line to `.bestest/ROADMAP.md` (`trace.sh --plan` fails without it).
 
 ## 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.

package/payload/skills/plan/SKILL.md

@@ -5,7 +5,7 @@ description: Use when a bestest project enters P3 — turn the frozen SPEC into
 
 # 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`.
+Input: frozen SPEC. Output: `.bestest/PLAN.md` (template: PLAN.md) 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".
@@ -15,7 +15,7 @@ Input: frozen SPEC. Output: `.bestest/PLAN.md` (ordered index + rationale) and `
 - 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.
+Any design element beyond the simplest thing satisfying the R-IDs gets a row (columns in the PLAN.md template). 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.

package/payload/skills/research/SKILL.md

@@ -8,7 +8,7 @@ description: Use when a bestest project needs external facts — P1 stack deriva
 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.
+1. **Frame** — write `.bestest/research/RQ-<slug>.md` (template: RQ.md).
 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.
@@ -17,7 +17,10 @@ Rule zero: **memory is a rumor.** Anything external — API shape, pricing, limi
 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`.
+A question that survives doc research and only execution can settle: add a `spike:` block to its RQ file (keys in template RQ.md) 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`.
+
+## Research-terminal projects
+`deliverable: findings`: the P1 gate variant and the FINDINGS.md deliverable live in `references/findings.md`.
 
 ## Citation hygiene
 - Cite the page you actually fetched, not the search snippet.

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

@@ -0,0 +1,20 @@
+# Research-terminal projects — `deliverable: findings`
+
+For premises whose deliverable is knowledge, not software: question in, cited verdict out. Declared in the Premise Verdict (`deliverable: findings`, D-ID recorded). Same lifecycle spine; the router skips P3–P4 after the P2 freeze and logs the skip.
+
+## R-ID grammar
+SPEC §2 criteria are questions with a named verdict shape and evidence bar:
+`WHEN research completes THE FINDINGS SHALL state <verdict shape> with <evidence bar>.`
+The observable behavior is the verdict itself — a question that can't name what a usable answer looks like isn't ready to freeze.
+
+## P1 gate variant
+The research loop runs unchanged: fan-out, adversarial verification, spikes. The gate: every R-ID's RQ file carries `verdict:` plus at least one `[cited:URL]` (or pasted run evidence for spikes), and every spike is dispositioned. The stack decision-brief approval is replaced by the question-set freeze at P2 — post-freeze question drift is a SPEC amendment (D-ID + re-hash), which is exactly the discipline the freeze buys.
+
+## Deliverable
+`.bestest/FINDINGS.md` (template: FINDINGS.md): one section per R-ID — verdict (one paragraph max), confidence plus what-would-change-it, evidence pointers into `research/RQ-*.md`. Ends with a Recommendation and a reopen tripwire. RQ files and FINDINGS stay unfrozen: a P5 UAT fail routes back to the research loop, never to P4.
+
+## P5 variant
+Ship runs against FINDINGS.md: UAT walks the user through each R-ID's verdict one at a time; the mechanical gate is `trace.sh --findings` — every R-ID has a cited RQ verdict, a FINDINGS.md section, and a UAT row; spikes and DISCOVERED dispositioned; ROADMAP verdict line present. Runbook is `n/a: findings deliverable` — skip the rollback rehearsal. The doneness function (SPEC §8) is evaluated against FINDINGS.md verbatim. LESSONS curation and the promotion offers run unchanged.
+
+## Out of scope
+No post-done citation-freshness monitoring — findings age like any document; the reopen tripwire is the honest boundary. A build project with research questions is just P1 — this lane is only for projects that END at answers.

package/payload/skills/ship/SKILL.md

@@ -5,19 +5,19 @@ description: Use when a bestest project enters P5 — UAT against every acceptan
 
 # Ship
 
-Nothing new gets built here; P5 proves what exists and stages it for production.
+Nothing new gets built here; P5 proves what exists and stages it for production. Findings variant (`deliverable: findings`): steps 1–2 run against FINDINGS.md with `trace.sh --findings`; step 5 is `n/a: findings deliverable` — discipline: research `references/findings.md`.
 
 ## 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). 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.
+First complete this milestone's ROADMAP.md ledger line with a verdict and refresh its Next-up/Abandoned sections — the audit fails a verdict-less line. Then `"$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.
+Append `| disposition:` to each line (grammar in the DISCOVERED.md header). 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.
+Compress LESSONS.md: dedupe, drop task-local noise, keep durable environment/codebase facts. Then two promotion offers, each one batch, each the user's call: top project-relevant items → the project memory file; `[env]`/`[tool]` facts that hold beyond this project → the user-level memory file (both per harness map). Never write either silently; declined items stay in LESSONS.md.
 
 ## 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`.
@@ -25,4 +25,4 @@ Fill `.bestest/RUNBOOK.md` (template) for the actual derived stack. The rollback
 ## 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).
+On "go": log the gate, set `phase: done` in STATE.md, commit. The lifecycle is complete — new work now routes through the quick lane (small fixes; router `references/quick.md`) or **milestone rollover** (archive to `.bestest/milestones/`, re-enter P0 brownfield).

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

@@ -10,7 +10,8 @@
 | 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 |
+| Project memory file (LESSONS promotion) | CLAUDE.md |
+| User-level memory file (cross-project LESSONS) | `~/.claude/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

@@ -10,7 +10,8 @@
 | 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) |
+| Project memory file (LESSONS promotion) | AGENTS.md (32 KiB read cap) |
+| User-level memory file (cross-project LESSONS) | `~/.codex/AGENTS.md` (FACTS.md 2026-07-12) |
 | 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 |
 

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

@@ -11,7 +11,8 @@
 | 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 |
+| Project memory file (LESSONS promotion) | AGENTS.md |
+| User-level memory file (cross-project LESSONS) | `~/.config/opencode/AGENTS.md` (FACTS.md 2026-07-12) |
 | 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` |
 

package/payload/templates/CODEBASE.md

@@ -0,0 +1,26 @@
+# CODEBASE — <repo name>
+<!-- Written by a read-only subagent at brownfield bootstrap; regenerated at each
+     milestone rollover. Hard cap 60 lines. Every claim cited to a file path —
+     observed fact, not aspiration. -->
+
+## Layout
+<!-- top-level dirs and what lives where -->
+
+## Entry points
+<!-- binaries, main modules, routes — path-cited -->
+
+## Build / run / test
+<!-- exact commands, copy-pasteable -->
+
+## Conventions
+<!-- naming, structure, patterns actually observed (path-cited) -->
+
+## Integration seams
+<!-- where new code plugs in: interfaces, DI points, extension dirs -->
+
+## Deploy surface
+<!-- how it ships today: CI files, Dockerfiles, scripts — or 'none found' -->
+
+## Baseline test run
+<!-- exact command + verbatim failure list. Pre-existing failures become RISK
+     entries in DECISIONS.md; no card verify: may expect them green. -->

package/payload/templates/DECISIONS.md

@@ -8,4 +8,6 @@
 <!-- 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 -->
+<!-- D-0NN | class: Waiver | finding waived | why acceptable | revisit trigger — waivers are decisions, same D-ID sequence.
+     Date triggers as 'revisit: YYYY-MM-DD' — session start surfaces due dates until
+     you append a 'D-0NN revisited <date>: <outcome>' line (append-only; never rewrite). -->

package/payload/templates/DISCOVERED.md

@@ -0,0 +1,6 @@
+# DISCOVERED — out-of-blast-radius work
+<!-- Never fixed silently, never dropped. One line per item, appended when found:
+       - <summary> | discovered-from: T-## | blocks: <T-## or none>
+     At P5 ship every line gains a disposition (trace.sh --all fails bare lines):
+       | disposition: fix-now / deferred to <where> / wontfix because <reason>
+     Survives milestone rollover; deferred lines seed the next interrogation. -->

package/payload/templates/FINDINGS.md

@@ -0,0 +1,14 @@
+# FINDINGS — <project name>
+<!-- The deliverable of a research-terminal project (deliverable: findings).
+     One section per SPEC R-ID. trace.sh --findings requires every R-ID here,
+     each backed by a research/RQ-*.md verdict with citations. Stays unfrozen —
+     a UAT fail routes back to the research loop, never to P4. -->
+
+## R-N.M — <question, one clause>
+verdict: <the answer, one paragraph max>
+confidence: <high|medium|low> — would change if: <falsifier>
+evidence: <research/RQ-<slug>.md + the load-bearing [cited:URL]s>
+
+## Recommendation
+<!-- what to do because of these answers, one paragraph; cite D-IDs -->
+reopen-if: <tripwire that invalidates the recommendation>

package/payload/templates/LESSONS.md

@@ -0,0 +1,5 @@
+# LESSONS — durable facts
+<!-- Builders read this file before every card and append what they learn after.
+     One fact per line, exact format:
+       - [env|tool|codebase] <fact> (T-##)
+     Curated (deduped, compressed) at P5 ship; survives milestone rollover. -->

package/payload/templates/PLAN.md

@@ -0,0 +1,18 @@
+# PLAN — <milestone>
+<!-- Written at P3; the amendment cascade patches this file together with the
+     cards. trace.sh --plan cross-checks the card index against plans/T-*.md
+     both ways: every card indexed, every indexed id has a card file. Cut cards
+     are dropped from the index — the cut itself lives in the amendment D-ID. -->
+
+## Card index
+<!-- one line per live card, in execution order:
+       T-## | <title> | complexity N | blocked_by: <T-## or none> -->
+
+## Rationale
+<!-- why this order and these slices; tracer bullet first -->
+
+## Complexity justification
+<!-- every design element beyond the simplest thing satisfying the R-IDs gets a
+     row — no row means the plan-checker counts it as a blocker:
+| Complexity | Why needed | Simpler alternative rejected because |
+|---|---|---| -->

package/payload/templates/ROADMAP.md

@@ -0,0 +1,21 @@
+# ROADMAP — <project name>
+<!-- Direction, never backlog: items live in DISCOVERED.md, scope in the milestone
+     SPEC — link, don't copy. Hard cap 40 lines (trace.sh enforces). Never hashed:
+     stays editable after the SPEC freeze; survives milestone rollover. -->
+
+## Destination
+<!-- 2-3 lines: where the project is going across milestones; what "done for good"
+     looks like -->
+
+## Milestone ledger
+<!-- one line per milestone, at line start. Intent appended at scope freeze
+     (trace --plan gates it); verdict completed at P5 ship (trace --all gates it).
+     Compress old lines — detail lives in .bestest/milestones/<N>/.
+       vN | intent: <one clause> | verdict: shipped <date> — <one clause outcome> -->
+
+## Next up
+<!-- 1-3 lines: the likely next milestone's theme and why-now; point at DISCOVERED
+     lines and D-IDs, never copy them -->
+
+## Abandoned
+<!-- <direction> — <why> (D-ID) -->

package/payload/templates/RQ.md

@@ -0,0 +1,19 @@
+# RQ — <question slug>
+<!-- One file per research question, written by the researcher agent
+     (file handoff, not chat recall). -->
+
+question: <the falsifiable question>
+feeds: <which R-ID or decision this answers>
+answer_shape: <what a usable answer looks like>
+
+## Findings
+<!-- every external claim [cited:URL] — the page actually fetched, not a search
+     snippet; version-sensitive claims name version + date; [assumed] for
+     anything no fetched URL confirms -->
+
+## Spike
+<!-- only if docs cannot answer (discipline: research references/spike.md).
+     Append these as top-level keys, at line start, when the spike opens:
+       spike: <falsifiable question>       (plus timebox + answer shape)
+       verdict: <actual run output, or 'unknown after <timebox>'>
+       disposition: discarded | promoted   (mandatory — trace.sh fails a bare spike) -->

package/payload/templates/SPEC.md

@@ -4,7 +4,9 @@
 
 ## 1. Premise Verdict
 <!-- one paragraph: the real problem, for whom, why now, why not an existing tool.
-     Every factual claim tagged [user] / [cited:URL] / [assumed]. -->
+     Every factual claim tagged [user] / [cited:URL] / [assumed].
+     Knowledge deliverable, nothing ships: add a 'deliverable: findings' line —
+     R-IDs become questions, P3-P4 are skipped (research references/findings.md). -->
 
 ## 2. Requirements — EARS acceptance criteria
 <!-- one sentence each, numbered R-N.M, observable behavior only:

package/payload/templates/STATE.md

@@ -8,6 +8,7 @@ milestone: v1        # archived to .bestest/milestones/<milestone>/ at rollover
 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)
+task_start: none     # HEAD sha at card dispatch — diff-scope gate baseline; survives compaction via re-injection
 
 ## Now
 - next action: <one imperative sentence — what the very next tool call should do>

package/payload/templates/quick-card.md

@@ -0,0 +1,22 @@
+---
+id: Q-00
+title: <imperative, one clause>
+status: doing            # doing | done | escalated
+files: src/example.py    # 1-3 paths, comma-separated; a diff outside them = escalate
+requirements: none       # none | R-IDs this RESTORES (never alters, never creates) | refactor
+decision: D-000          # DECISIONS.md entry authorizing the quick fix
+start: <sha>             # git rev-parse HEAD before the first edit
+may_edit_tests: false    # always false on the quick lane (lock-guard clamps it)
+verify:
+  - <command proving the fix; refactor: the incumbent test suite>
+---
+## Fix (zero-context contract)
+<!-- symptom, exact paths, expected end state. Read LESSONS.md first; append what
+     you learn. TDD locks stand — a fix that needs a test edit escalates. -->
+
+## Done means
+<!-- report at .bestest/reports/Q-00.md (FRICTION + Lessons included); commit
+     trailer 'Bestest-Req: Q-00'; restored R-IDs get a 'requick' UAT.md row;
+     refactor cards paste the green incumbent-suite run in Verify output;
+     out-of-scope findings -> DISCOVERED.md, never fixed here.
+     trace.sh --quick must PASS before STATE returns to phase: done. -->

package/payload/templates/report.md

@@ -11,5 +11,10 @@
 ## FRICTION
 <!-- REQUIRED. Failed commands, backtracking, wrong card assumptions, environment surprises — or exactly 'None'. The orchestrator patches remaining cards + LESSONS.md from this before the next dispatch. -->
 
+## Lessons
+<!-- REQUIRED. Each durable FRICTION fact as the exact line appended to LESSONS.md
+     ('- [env|tool|codebase] <fact> (T-00)') — or exactly 'None'. trace.sh --all
+     cross-checks every line here against LESSONS.md. -->
+
 ## Discovered
 <!-- out-of-blast-radius items appended to DISCOVERED.md this task, or 'None' -->