@accidentally-awesome-labs/opencode-bestest 0.4.3

package/README.md

@@ -0,0 +1,36 @@
+# opencode-bestest
+
+The OpenCode head of [the bestest plugin](https://github.com/accidentally-awesome-labs/the-bestest-agent) — one compact lifecycle (P0 interrogate → P5 ship) with *physically enforced* gates: spec freeze, TDD test locks, destructive-command guard, and drift detection.
+
+## Install (per project)
+
+```bash
+cd your-project
+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/`
+- 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`.
+
+## What the plugin enforces
+
+| Tool call | Script | Outcome |
+|---|---|---|
+| `bash` | `guard.sh` | destructive commands (rm -rf /, git reset --hard, force-push to main, …) → blocked |
+| `write` / `edit` / `apply_patch` | `lock-guard.sh` | writes to the frozen SPEC or locked test files → blocked with the amendment path |
+| same, after | `syntax-check.sh` | syntax errors fed straight back (advisory: never blocks when checkers are absent) |
+| `session.idle` | `session-start.sh stop` | drift snapshot; next session's digest carries a DRIFT notice if the tree changed out-of-band |
+
+The bash scripts are byte-identical to the ones the Claude Code and Codex heads run — one guard implementation, three harnesses. Guards **fail closed**: no bash (install Git Bash on Windows) means guarded tools are refused, not waved through.
+
+Dev/source install (no npm): clone the repo, then in your project's `.opencode/plugins/bestest-dev.ts`:
+
+```ts
+export { BestestPlugin } from "/path/to/the-bestest-agent/adapters/opencode/src/index"
+```

package/bin/init.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+// opencode-bestest installer: copies skills/agents/commands + runtime payload
+// into a project (or --global), wires opencode.json. Idempotent; --dry-run.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { sourceRoot } from "../src/resolve"
+
+const args = new Set(process.argv.slice(2))
+const DRY = args.has("--dry-run")
+const GLOBAL = args.has("--global")
+const cwd = process.cwd()
+const base = GLOBAL ? join(homedir(), ".config", "opencode") : join(cwd, ".opencode")
+const src = sourceRoot()
+// opencode-assets sits next to src/ in the package (and in the repo clone)
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..")
+const assetDir = join(pkgRoot, "opencode-assets")
+
+const actions: string[] = []
+const doCopy = (from: string, to: string) => {
+  actions.push(`copy ${from} -> ${to}`)
+  if (!DRY) {
+    mkdirSync(dirname(to), { recursive: true })
+    cpSync(from, to, { recursive: true })
+  }
+}
+
+// 1. Skills — renamed with a bestest- prefix (un-namespaced skill dirs collide:
+//    'plan'/'build'/'debug' are common). Cross-references in prose keep the bare
+//    names; the opencode harness map explains the prefix.
+const RENAME: Record<string, string> = {
+  "using-bestest": "using-bestest",
+  interrogate: "bestest-interrogate",
+  research: "bestest-research",
+  plan: "bestest-plan",
+  build: "bestest-build",
+  ship: "bestest-ship",
+  debug: "bestest-debug",
+  "bestest-go": "bestest-go",
+  "bestest-status": "bestest-status",
+}
+for (const dir of readdirSync(join(src, "skills"))) {
+  const target = RENAME[dir]
+  if (!target) continue
+  doCopy(join(src, "skills", dir), join(base, "skills", target))
+  if (!DRY && target !== dir) {
+    const f = join(base, "skills", target, "SKILL.md")
+    writeFileSync(f, readFileSync(f, "utf8").replace(/^name:\s*.*$/m, `name: ${target}`))
+  }
+}
+
+// 2/3. Agents + command stubs (hand-maintained conversions; bodies byte-identical
+//      to the canonical agents/*.md — static-checks enforce parity).
+for (const kind of ["agents", "commands"]) {
+  for (const f of readdirSync(join(assetDir, kind))) {
+    doCopy(join(assetDir, kind, f), join(base, kind, f))
+  }
+}
+
+// 4. Runtime payload for project sessions: hooks (shim targets), trace.sh, templates.
+if (!GLOBAL) {
+  for (const part of ["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"
+  actions.push(`write .opencode/bestest/VERSION = ${version}`)
+  if (!DRY) writeFileSync(join(cwd, ".opencode", "bestest", "VERSION"), version + "\n")
+}
+
+// 5. opencode.json merge (strict JSON only; JSONC users get manual instructions).
+const cfgPath = GLOBAL ? join(base, "opencode.json") : join(cwd, "opencode.json")
+const PLUGIN = "@accidentally-awesome-labs/opencode-bestest"
+const INSTR = ".bestest/.context.md"
+let cfg: Record<string, unknown> = { $schema: "https://opencode.ai/config.json" }
+let cfgOk = true
+if (existsSync(cfgPath)) {
+  try {
+    cfg = JSON.parse(readFileSync(cfgPath, "utf8"))
+  } catch {
+    cfgOk = false
+  }
+}
+if (cfgOk) {
+  const plugins = new Set([...((cfg.plugin as string[]) ?? [])])
+  plugins.add(PLUGIN)
+  cfg.plugin = [...plugins]
+  const instr = new Set([...((cfg.instructions as string[]) ?? [])])
+  instr.add(INSTR)
+  cfg.instructions = [...instr]
+  actions.push(`merge ${cfgPath}: plugin += ${PLUGIN}, instructions += ${INSTR}`)
+  if (!DRY) writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n")
+} else {
+  actions.push(`SKIPPED ${cfgPath} (not strict JSON) — add manually: "plugin": ["${PLUGIN}"], "instructions": ["${INSTR}"]`)
+}
+
+// 6. gitignore the digest + snapshot (project installs only).
+if (!GLOBAL) {
+  const gi = join(cwd, ".gitignore")
+  const lines = existsSync(gi) ? readFileSync(gi, "utf8") : ""
+  const missing = [".bestest/.context.md", ".bestest/.session-snapshot"].filter((l) => !lines.includes(l))
+  if (missing.length) {
+    actions.push(`append .gitignore: ${missing.join(", ")}`)
+    if (!DRY) writeFileSync(gi, lines + (lines.endsWith("\n") || lines === "" ? "" : "\n") + missing.join("\n") + "\n")
+  }
+}
+
+// 7. Existing .bestest project: build the first digest now (no chicken-and-egg).
+if (!GLOBAL && existsSync(join(cwd, ".bestest")) && Bun.which("bash")) {
+  actions.push("generate initial .bestest/.context.md")
+  if (!DRY) {
+    const proc = Bun.spawn(["bash", join(src, "hooks", "session-start.sh"), "start"], {
+      cwd,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: cwd },
+      stdout: "pipe",
+      stderr: "ignore",
+    })
+    const out = await new Response(proc.stdout).text()
+    await proc.exited
+    if (out.trim()) writeFileSync(join(cwd, ".bestest", ".context.md"), out)
+  }
+}
+
+console.log(`opencode-bestest init ${DRY ? "(dry-run)" : ""}${GLOBAL ? " (global)" : ""}`)
+for (const a of actions) console.log("  " + a)
+console.log(cfgOk ? "Done. Open opencode and run /bestest-go." : "Done with manual steps above. Then open opencode and run /bestest-go.")

package/bin/opencode-bestest

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+// npm rejects .ts bin targets; this shebang launcher keeps `bunx … init` working.
+import "./init.ts"

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

@@ -0,0 +1,27 @@
+---
+description: Adversarial checker for bestest specs (P2 rubric mode) and plans (P3 card mode) — read-only, verdict plus numbered blockers.
+mode: subagent
+permission:
+  edit: deny
+  bash: deny
+  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, 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.

package/opencode-assets/agents/researcher.md

@@ -0,0 +1,20 @@
+---
+description: Fetches and verifies external facts for a bestest research question, returning cited findings — never answers from memory.
+mode: subagent
+permission:
+  edit:
+    "*": deny
+    ".bestest/research/*": allow
+  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.

package/opencode-assets/agents/reviewer.md

@@ -0,0 +1,22 @@
+---
+description: Risk-scaled adversarial code review of a completed bestest task card — read-only on product code, evidence-based verdict.
+mode: subagent
+permission:
+  edit: deny
+  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.

package/opencode-assets/commands/bestest-go.md

@@ -0,0 +1,5 @@
+---
+description: Route to the current bestest lifecycle phase (or start a new project at P0)
+---
+
+Load the **bestest-go** skill and follow it exactly. Plugin runtime root for its bootstrap step (record as the `plugin:` line in STATE.md): `.opencode/bestest`. Note: on this harness the lifecycle skills are installed with a `bestest-` prefix (bestest-interrogate, bestest-plan, …).

package/opencode-assets/commands/bestest-status.md

@@ -0,0 +1,5 @@
+---
+description: Read-only dashboard of the bestest project state — never mutates anything
+---
+
+Load the **bestest-status** skill and follow it exactly (strictly read-only). If STATE.md lacks a `plugin:` line, trace.sh lives under `.opencode/bestest`.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@accidentally-awesome-labs/opencode-bestest",
+  "version": "0.4.3",
+  "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",
+  "exports": "./src/index.ts",
+  "bin": {
+    "opencode-bestest": "bin/opencode-bestest"
+  },
+  "files": [
+    "src",
+    "bin",
+    "payload",
+    "opencode-assets"
+  ],
+  "scripts": {
+    "prepack": "bash prepack.sh",
+    "check": "bun x tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.17.15",
+    "bun-types": "^1.3.14",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/payload/VERSION

@@ -0,0 +1 @@
+0.4.3

package/payload/agents/plan-checker.md

@@ -0,0 +1,25 @@
+---
+name: plan-checker
+description: Adversarial checker for bestest specs (P2 rubric mode) and plans (P3 card mode) — read-only, verdict plus numbered blockers.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+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, 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.

package/payload/agents/researcher.md

@@ -0,0 +1,17 @@
+---
+name: researcher
+description: Fetches and verifies external facts for a bestest research question, returning cited findings — never answers from memory.
+tools: WebSearch, WebFetch, Read, Grep, Glob, Write
+model: sonnet
+---
+
+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.

package/payload/agents/reviewer.md

@@ -0,0 +1,21 @@
+---
+name: reviewer
+description: Risk-scaled adversarial code review of a completed bestest task card — read-only on product code, evidence-based verdict.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+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.

package/payload/hooks/guard.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# bestest: PreToolUse[Bash] guard. Blocks destructive commands (exit 2 = block,
+# stderr is shown to Claude). Everything else passes through silently.
+# Compound commands are split on ;, &&, ||, | and newlines — every segment is
+# analyzed independently, so `safe ; rm -rf /` cannot hide behind the last segment.
+set -u
+
+input="$(cat)"
+root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+get_command() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$input" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("tool_input",{}).get("command",""))
+except Exception: pass' 2>/dev/null
+  else
+    # Last resort (no jq, no python3): sed extraction so the guard cannot fail
+    # open. Crude JSON decoding, but the pattern checks below only need the text.
+    printf '%s' "$input" \
+      | sed -nE 's/.*"command"[[:space:]]*:[[:space:]]*"((\\.|[^"\\])*)".*/\1/p' \
+      | sed -e 's/\\n/;/g' -e 's/\\t/ /g' -e 's/\\"/"/g' -e 's/\\\\/\\/g'
+  fi
+}
+
+cmd="$(get_command)"
+[ -n "$cmd" ] || exit 0
+
+block() {
+  echo "bestest guard: blocked — $1. If genuinely intended, this is a GATED action: ask the user to run it themselves or to approve an exception." >&2
+  exit 2
+}
+
+case "$cmd" in
+  *':(){ :|:& };:'*|*':(){:|:&};:'*) block "fork bomb" ;;
+esac
+
+# --- whole-command checks (substring anywhere is already damning) -------------
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+reset[[:space:]]+--hard'; then
+  block "git reset --hard discards uncommitted work; stash or commit first"
+fi
+
+if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+clean[[:space:]]+-[a-zA-Z]*f'; then
+  block "git clean -f deletes untracked files irreversibly"
+fi
+
+if printf '%s' "$cmd" | grep -Eiq '(psql|mysql|mariadb|sqlite3|mongosh?|sqlcmd|clickhouse|duckdb|dbshell)' \
+   && printf '%s' "$cmd" | grep -Eiq "drop[[:space:]]+(database|schema)[[:space:]]"; then
+  block "DROP DATABASE/SCHEMA is a GATED destructive action"
+fi
+
+if printf '%s' "$cmd" | grep -Eq 'chmod[[:space:]]+(-R[[:space:]]+)?0?777'; then
+  block "chmod 777 is never the fix"
+fi
+
+if printf '%s' "$cmd" | grep -Eq '(^|[;&|[:space:]])(mkfs|fdisk)([[:space:].]|$)|dd[[:space:]]+[^;|&]*of=/dev/(sd|nvme|disk)|>[[:space:]]*/dev/(sd|nvme|disk)'; then
+  block "raw disk write"
+fi
+
+# --- per-segment checks --------------------------------------------------------
+check_rm_segment() {
+  seg="$1"
+  printf '%s' "$seg" | grep -Eq '(^|[[:space:]])rm([[:space:]]|$)' || return 0
+  args="$(printf '%s' "$seg" | sed -E 's/.*(^|[[:space:]])rm[[:space:]]+//')"
+  rec=0; force=0; targets=""
+  for w in $args; do
+    case "$w" in
+      --recursive) rec=1 ;;
+      --force)     force=1 ;;
+      --*) ;;
+      -*)
+        case "$w" in *[rR]*) rec=1 ;; esac
+        case "$w" in *f*)    force=1 ;; esac ;;
+      *) targets="$targets $w" ;;
+    esac
+  done
+  [ "$rec" = 1 ] && [ "$force" = 1 ] || return 0
+  for w in $targets; do
+    w="${w%\"}"; w="${w#\"}"; w="${w%\'}"; w="${w#\'}"
+    case "$w" in
+      /|/\*|'~'|'~/'|'~/*'|\$HOME|\$HOME/|'$HOME/*')
+        block "recursive force-delete of / or home" ;;
+      /tmp/*|/private/tmp/*|/var/tmp/*) continue ;;
+      $root/*) continue ;;
+      /*|'~/'*|\$HOME/*)
+        block "recursive force-delete outside the project ($w) — delete inside the repo or temp dirs only" ;;
+    esac
+  done
+}
+
+check_push_segment() {
+  seg="$1"
+  printf '%s' "$seg" | grep -Eq 'git[[:space:]]+push' || return 0
+  if printf '%s' "$seg" | grep -Eq '[[:space:]](--force|-f)([[:space:]]|$)' \
+     && ! printf '%s' "$seg" | grep -q 'force-with-lease' \
+     && printf '%s' "$seg" | grep -Eq '[[:space:]](main|master)([[:space:]]|$|:)'; then
+    block "force-push to main/master (use --force-with-lease on a feature branch, or get user approval)"
+  fi
+}
+
+while IFS= read -r seg; do
+  [ -n "${seg// /}" ] || continue
+  check_rm_segment "$seg"
+  check_push_segment "$seg"
+done <<EOF
+$(printf '%s' "$cmd" | tr '\n' ';' | sed -E 's/&&|\|\||[;|]/\
+/g')
+EOF
+
+exit 0

package/payload/hooks/lock-guard.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# bestest: PreToolUse[Write|Edit|MultiEdit|apply_patch] lock guard.
+# Blocks writes to paths frozen in .bestest/LOCKS:
+#   hash <sha256> <path>   -> path is frozen (e.g. SPEC.md after P2)
+#   glob <pattern>         -> pattern is frozen (test immutability); exempt only
+#                             when the active card has 'may_edit_tests: true'
+# Two envelope shapes, one contract (exit 2 = block):
+#   Claude Write/Edit  -> .tool_input.file_path
+#   Codex/OpenCode apply_patch -> .tool_input.command holds the patch text;
+#                                 paths come from '*** Add/Update/Delete File:' headers
+# Deliberate escape hatch: gate steps mutate LOCKS/SPEC via explicit shell
+# commands (visible in transcript), never via file-edit tools.
+set -u
+
+input="$(cat)"
+root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+locks="$root/.bestest/LOCKS"
+
+get_file_path() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$input" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("tool_input",{}).get("file_path",""))
+except Exception: pass' 2>/dev/null
+  else
+    # Last resort (no jq, no python3): sed extraction so the lock cannot fail
+    # open. Crude JSON decoding, but path comparison below only needs the text.
+    printf '%s' "$input" \
+      | sed -nE 's/.*"file_path"[[:space:]]*:[[:space:]]*"((\\.|[^"\\])*)".*/\1/p' \
+      | sed -e 's/\\"/"/g' -e 's/\\\\/\\/g'
+  fi
+}
+
+get_command_text() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$input" | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("tool_input",{}).get("command",""))
+except Exception: pass' 2>/dev/null
+  else
+    printf '%s' "$input" \
+      | sed -nE 's/.*"command"[[:space:]]*:[[:space:]]*"((\\.|[^"\\])*)".*/\1/p' \
+      | awk '{gsub(/\\n/,"\n"); gsub(/\\t/,"  "); gsub(/\\"/,"\""); gsub(/\\\\/,"\\"); print}'
+  fi
+}
+
+# apply_patch envelopes: one project-relative path per header line.
+patch_paths() {
+  cmd="$(get_command_text)"
+  case "$cmd" in
+    *'*** Begin Patch'*) ;;
+    *) return 0 ;;
+  esac
+  printf '%s\n' "$cmd" \
+    | sed -nE -e 's/^\*\*\* (Add|Update|Delete) File: //p' -e 's/^\*\*\* Move to: //p'
+}
+
+paths="$(get_file_path)"
+[ -n "$paths" ] || paths="$(patch_paths)"
+[ -n "$paths" ] || exit 0
+[ -f "$locks" ] || exit 0
+
+block() {
+  echo "bestest lock-guard: '$rel' is frozen ($1). $2" >&2
+  exit 2
+}
+
+# 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
+# in a card's own files: list, so the tampering diff fails the per-task gate.
+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
+fi
+
+check_one_path() {
+  # Normalize to a project-relative path.
+  rel="${1#"$root"/}"
+
+  # LOCKS itself is never edited via file-edit tools.
+  [ "$rel" = ".bestest/LOCKS" ] && block "the lock registry" "Gates append to it via explicit shell steps only."
+
+  while IFS= read -r line; do
+    kind="${line%% *}"
+    case "$kind" in
+      hash)
+        path="$(printf '%s' "$line" | awk '{print $3}')"
+        [ "$rel" = "$path" ] && block "hash-locked at spec freeze" \
+          "To amend: record a D-ID in .bestest/DECISIONS.md, apply the amendment via an explicit shell gate step, then update the hash line in LOCKS."
+        ;;
+      glob)
+        pat="$(printf '%s' "$line" | cut -d' ' -f2-)"
+        case "$rel" in
+          $pat)
+            [ "$may_edit_tests" = "true" ] || block "test file (TDD lock)" \
+              "Only a card with 'may_edit_tests: true' may touch tests. Implementer cards make tests pass, not change."
+            ;;
+        esac
+        ;;
+    esac
+  done < "$locks"
+}
+
+while IFS= read -r fp; do
+  [ -n "$fp" ] || continue
+  check_one_path "$fp"
+done <<EOF
+$paths
+EOF
+
+exit 0

package/payload/hooks/session-start.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# bestest: SessionStart + Stop hook (dispatch on argv[1]).
+#   start -> inject .bestest/ state digest into context; detect drift.
+#   stop  -> snapshot HEAD + dirty-tree hash for the next drift check.
+set -u
+
+mode="${1:-start}"
+root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+b="$root/.bestest"
+snap="$b/.session-snapshot"
+
+hash_stdin() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum | cut -d' ' -f1
+  else shasum -a 256 | cut -d' ' -f1; fi
+}
+
+# Not a bestest project (or not a repo yet): stay silent.
+[ -d "$b" ] || exit 0
+
+head="$(git -C "$root" rev-parse HEAD 2>/dev/null || echo none)"
+# Hash content, not just the porcelain listing — an edit that keeps the same
+# file list would otherwise slip past the drift check. Exclude our own snapshot
+# file, whose creation at stop-time would otherwise fabricate drift.
+dirty="$( { git -C "$root" status --porcelain | grep -v '\.bestest/\.session-snapshot'; git -C "$root" diff; git -C "$root" diff --cached; } 2>/dev/null | hash_stdin)"
+
+if [ "$mode" = "stop" ]; then
+  printf 'HEAD=%s\nDIRTY=%s\n' "$head" "$dirty" > "$snap" 2>/dev/null
+  exit 0
+fi
+
+[ -f "$b/STATE.md" ] || exit 0
+
+echo "## bestest state (auto-injected — durable source of truth: .bestest/)"
+sed -n '1,60p' "$b/STATE.md"
+
+if [ -f "$b/LOCKS" ] && [ -s "$b/LOCKS" ]; then
+  echo
+  echo "### LOCKS (frozen paths — writes blocked by hook)"
+  cat "$b/LOCKS"
+fi
+
+card="$(grep -m1 -E '^card:' "$b/STATE.md" 2>/dev/null | sed -E 's/^card:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]+$//')"
+if [ -n "${card:-}" ] && [ "$card" != "none" ] && [ -f "$root/$card" ]; then
+  echo
+  echo "### active task card ($card)"
+  cat "$root/$card"
+fi
+
+if [ -f "$b/SPEC.md" ]; then
+  echo
+  echo "Autonomy contract in force: SPEC.md section 9 (PROCEED / INTERRUPT / GATED)."
+fi
+
+if [ -f "$snap" ]; then
+  old_head="$(grep -m1 '^HEAD=' "$snap" | cut -d= -f2-)"
+  old_dirty="$(grep -m1 '^DIRTY=' "$snap" | cut -d= -f2-)"
+  if [ "$old_head" != "$head" ] || [ "$old_dirty" != "$dirty" ]; then
+    echo
+    echo "DRIFT: the working tree changed since the last session ended. Before continuing, reconcile code against SPEC.md, classify each delta (in-spec / out-of-spec / needs D-ID), and append R-ID-traced tasks to .bestest/PLAN.md."
+  fi
+fi
+
+exit 0