@accidentally-awesome-labs/opencode-bestest 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@accidentally-awesome-labs/opencode-bestest",
-  "version": "0.6.1",
+  "version": "0.7.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.6.1
+0.7.0

package/payload/agents/plan-checker.md

@@ -12,14 +12,15 @@ 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. `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.
+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. A DESIGN.md beside the SPEC gets graded too: `covers:` R-IDs real; Direction holds a specific reference object (adjectives alone = `[Ambiguity]`), ≥3 banned defaults, a signature element; hex only in Tokens; Motion rows numeric; Do/Don't ≥3 each and testable. An interface-shaped premise with no DESIGN.md is a `[Gap]`. `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.
 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.
+5. Complexity Justification table: any structure beyond the simplest satisfying design without a row → blocker; a row naming no rejected rung (reuse / stdlib / platform / installed dep) → blocker.
 6. TDD pairing: implementer cards with `may_edit_tests: true`, or no failing-test card ahead of them.
+7. Design cascade: a card advancing a DESIGN.md `covers:` R-ID without `design: .bestest/DESIGN.md`, or any card inventing visual values the contract doesn't define → blocker.
 
 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/reviewer.md

@@ -13,9 +13,13 @@ Inputs: the card, the diff range, the report, SPEC.md, relevant D-IDs.
 - **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.
 
+**ui-mode** (design-bearing cards — the dispatch includes the DESIGN.md contract and the ui review-rules): audit the diff against every rule; findings cite rule IDs. Blockers at any weight: raw values where a contract token exists, motion off the contract's Motion table, a report lacking a rendered-output pointer (screenshot/recording) for a visual change. Distinctive is not wrong — block only contract and rule violations; taste is at most a flag.
+
 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.
+
+Close every review with a delete-list: opportunities tagged `[delete]` `[stdlib]` `[native]` `[yagni]` `[shrink]`, one line each, ending `net: −N lines possible` — count N from the diff, never estimate; nothing to shrink = `net: 0`. Delete-tags are flags, not blockers — except an interface or dependency no R-ID needs: that one blocks.

package/payload/hooks/session-start.sh

@@ -17,6 +17,21 @@ hash_stdin() {
 # Not a bestest project (or not a repo yet): stay silent.
 [ -d "$b" ] || exit 0
 
+# persona -> per-turn one-line minimalism reminder (UserPromptSubmit, both heads).
+# Scoped to P4/quick: where code is written under an active card. At routing
+# moments (done, P0-P3) it stays silent — "minimum that works" next to a fresh
+# user ask out-shouts the router (measured: quick-lane eval 3/3 process-skips).
+# The full stanza rides 'start'; builders get the ladder via the card contract.
+if [ "$mode" = "persona" ]; then
+  ph="$(grep -m1 -E '^phase:' "$b/STATE.md" 2>/dev/null | sed -E 's/^phase:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]+$//')"
+  case "${ph:-}" in
+    P4|quick)
+      echo "[bestest minimalism reminder — standing plugin behavior] Ladder before new code: delete the need → reuse this repo → stdlib → platform-native → installed dep → minimum that works. Floor: validation, security, error handling, accessibility. The ladder shortens the solution, never the process — the active card and its gates still bind."
+      ;;
+  esac
+  exit 0
+fi
+
 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
@@ -32,6 +47,8 @@ fi
 
 echo "## bestest state (auto-injected — durable source of truth: .bestest/)"
 sed -n '1,60p' "$b/STATE.md"
+echo
+echo "(The plugin: line above is the authoritative root for this project's scripts and templates — trust it as long as that path exists on disk. The live plugin install may sit at a different path; project-local copies are normal, and re-resolution applies only when the recorded path is missing.)"
 
 if [ -f "$b/LOCKS" ] && [ -s "$b/LOCKS" ]; then
   echo
@@ -39,6 +56,12 @@ if [ -f "$b/LOCKS" ] && [ -s "$b/LOCKS" ]; then
   cat "$b/LOCKS"
 fi
 
+# Minimalism persona: the ladder sentence below must byte-match the builder
+# contract in skills/build/SKILL.md (static-checks rule-copy lint).
+echo
+echo "### minimalism persona (standing plugin behavior, active every response; a one-line reminder repeats per turn during build)"
+echo "Build like the laziest senior dev: before new code, descend the ladder: delete the need → reuse this repo → stdlib → platform-native → installed dep → minimum that works; never simplify away validation, security, error handling, accessibility, or anything explicitly asked. Deliberate ceilings: comment 'bestest-defer: <ceiling> until <trigger>' + a DISCOVERED.md line. The ladder shortens the solution, never the process — lanes, cards, and gates still bind."
+
 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

package/payload/scripts/trace.sh

@@ -29,6 +29,28 @@ check_discovered() { # every DISCOVERED entry needs a disposition by ship
       || fail "DISCOVERED entry lacks disposition: ${line%%|*}"
   done < <(grep -E '^- ' "$b/DISCOVERED.md")
 }
+check_defers() { # 'bestest-defer: <ceiling> until <trigger>' markers: rot + harvest audit
+  if git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    hits="$(git -C "$root" grep -In --untracked 'bestest-defer:' -- . ':!.bestest' 2>/dev/null || true)"
+  else
+    hits="$(grep -rIn --exclude-dir=.git --exclude-dir=.bestest --exclude-dir=node_modules 'bestest-defer:' "$root" 2>/dev/null || true)"
+  fi
+  [ -n "$hits" ] || return 0
+  while IFS= read -r h; do
+    [ -n "$h" ] || continue
+    loc="$(printf '%s' "$h" | cut -d: -f1,2)"
+    body="$(printf '%s' "$h" | sed 's/.*bestest-defer:[[:space:]]*//')"
+    case "$body" in
+      *' until '*) : ;;
+      *) fail "deferral marker without ' until <trigger>' — rot: $loc"; continue ;;
+    esac
+    ceiling="${body%% until *}"
+    grep -qF -- "$ceiling" "$b/DISCOVERED.md" 2>/dev/null \
+      || fail "unharvested deferral marker — add a DISCOVERED.md defer line: $loc"
+  done <<DEOF
+$hits
+DEOF
+}
 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
@@ -52,12 +74,16 @@ rids="$(grep -oE 'R-[0-9]+\.[0-9]+' "$b/SPEC.md" | sort -u)"
 
 # --- 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"
+  # tamper canary: the quick lane never amends a frozen artifact (SPEC, DESIGN, …)
+  if [ -f "$b/LOCKS" ]; then
+    while IFS= read -r hl; do
+      [ -n "$hl" ] || continue
+      lh="$(printf '%s' "$hl" | awk '{print $2}')"; hp="$(printf '%s' "$hl" | awk '{print $3}')"
+      [ -f "$root/$hp" ] || continue
+      if command -v sha256sum >/dev/null 2>&1; then ch="$(sha256sum "$root/$hp" | cut -d' ' -f1)"
+      else ch="$(shasum -a 256 "$root/$hp" | cut -d' ' -f1)"; fi
+      [ "$lh" = "$ch" ] || fail "$hp no longer matches its LOCKS hash — the quick lane never amends frozen artifacts"
+    done < <(grep -E '^hash [0-9a-f]+ ' "$b/LOCKS" 2>/dev/null || true)
   fi
 
   qcards="$(ls "$b"/plans/Q-*.md 2>/dev/null || true)"
@@ -274,6 +300,107 @@ fi
 # spikes: a spike: block in a research RQ file must carry a disposition: by P3
 check_spikes
 
+# --- design-contract checks: active iff .bestest/DESIGN.md exists -------------
+check_design() {
+  df="$b/DESIGN.md"
+  [ -f "$df" ] || return 0
+
+  # covers: line names the UI R-IDs this contract governs; each must be real
+  drids="$(grep -m1 -E '^covers:' "$df" | grep -oE 'R-[0-9]+\.[0-9]+' || true)"
+  if [ -z "$drids" ]; then
+    fail "DESIGN.md needs a 'covers:' line naming its UI R-IDs"
+  else
+    for r in $drids; do
+      printf '%s\n' "$rids" | grep -qx "$r" || fail "DESIGN.md covers $r which is not in SPEC.md"
+    done
+  fi
+
+  # freeze parity: a frozen SPEC demands a frozen design contract
+  if grep -qE '^hash [0-9a-f]+ \.bestest/SPEC\.md' "$b/LOCKS" 2>/dev/null; then
+    grep -qE '^hash [0-9a-f]+ \.bestest/DESIGN\.md' "$b/LOCKS" 2>/dev/null \
+      || fail "SPEC is frozen but DESIGN.md has no LOCKS hash — freeze the design contract at P2"
+  fi
+
+  # every section filled (headers matched verbatim; template guidance is comments)
+  for s in Direction Tokens 'Contrast pairs' Components Motion 'Do / Don' Responsive; do
+    section_filled "$df" "$s" || fail "DESIGN.md section empty: $s"
+  done
+
+  # token discipline: raw values live only in Tokens/Contrast pairs
+  awk '/^## Components/{f=1;next} /^## /{f=0} f' "$df" | grep -qE '#[0-9a-fA-F]{3,8}' \
+    && fail "raw hex in DESIGN.md Components — reference {tokens}; hex lives only in Tokens"
+
+  # Motion rows: numeric ms + named easing, or an explicit none — never vibes
+  while IFS= read -r mrow; do
+    [ -n "$mrow" ] || continue
+    case "$mrow" in *none*) continue ;; esac
+    if ! { printf '%s' "$mrow" | grep -qE '[0-9]+[[:space:]]*ms' \
+        && printf '%s' "$mrow" | grep -qE '(ease|linear|cubic-bezier|spring)'; }; then
+      fail "DESIGN.md Motion row lacks numeric ms + named easing (vibes are not a contract): $mrow"
+    fi
+  done < <(awk '/^## Motion/{f=1;next} /^## /{f=0} f && /^[[:space:]]*\|/' "$df" \
+           | grep -vE '^[[:space:]]*\|[-:| ]*$' | grep -vi 'duration')
+
+  # WCAG contrast on declared pairs (python3 stdlib; SKIP silently degrades)
+  if command -v python3 >/dev/null 2>&1; then
+    cerr="$(awk '/^## Contrast pairs/{f=1;next} /^## /{f=0} f&&/^[[:space:]]*-/' "$df" | python3 -c '
+import sys, re
+def lum(h):
+    h = h.lstrip("#")
+    if len(h) == 3: h = "".join(c * 2 for c in h)
+    def lin(c):
+        c = int(h[c:c+2], 16) / 255.0
+        return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+    return 0.2126 * lin(0) + 0.7152 * lin(2) + 0.0722 * lin(4)
+for line in sys.stdin:
+    m = re.search(r"(#[0-9a-fA-F]{3,6})\s+on\s+(#[0-9a-fA-F]{3,6})", line)
+    if not m: continue
+    hi, lo = sorted((lum(m.group(1)), lum(m.group(2))), reverse=True)
+    ratio = (hi + 0.05) / (lo + 0.05)
+    need = 3.0 if "AA-large" in line else 4.5
+    if ratio < need:
+        print("%s on %s = %.2f (< %.1f)" % (m.group(1), m.group(2), ratio, need))
+' 2>/dev/null || true)"
+    while IFS= read -r ce; do
+      [ -n "$ce" ] && fail "DESIGN.md contrast pair below WCAG AA: $ce"
+    done <<CEOF
+$cerr
+CEOF
+  else
+    echo "SKIP contrast math (no python3)"
+  fi
+
+  # cascade: each covers: R-ID needs >=1 covering card that carries the contract
+  for r in $drids; do
+    dcov=no
+    for c in $cards; do
+      cfm="$(front "$c")"
+      if printf '%s' "$cfm" | grep -E '^requirements:' | grep -Eq "$(rid_re "$r")" \
+         && printf '%s' "$cfm" | grep -E '^design:' | grep -q 'DESIGN.md'; then dcov=yes; break; fi
+    done
+    [ "$dcov" = yes ] || fail "$r is a DESIGN.md covers: R-ID but no covering card carries design: .bestest/DESIGN.md"
+  done
+
+  # --all: covers: R-IDs must show rendered output in UAT, not prose
+  if [ "$mode" = "--all" ]; then
+    for r in $drids; do
+      grep -E "$(rid_re "$r")" "$b/UAT.md" 2>/dev/null | grep -qiE '\.(png|jpe?g|webp|gif|mp4|webm)|screenshot|recording' \
+        || fail "$r is a UI criterion — its UAT evidence must point at rendered output (screenshot/recording)"
+    done
+  fi
+}
+check_design
+
+# any card's design: value must be none or resolve to a file
+for c in $cards; do
+  dval="$(front "$c" | grep -E '^design:' | head -1 | sed 's/^design:[[:space:]]*//; s/[[:space:]]*#.*$//; s/[[:space:]]*$//')"
+  [ -n "${dval:-}" ] || continue
+  case "$dval" in
+    none) : ;;
+    *) [ -f "$root/$dval" ] || fail "$(basename "$c" .md) design: $dval does not resolve to a file" ;;
+  esac
+done
+
 # --- full-chain checks (--all) -----------------------------------------------
 if [ "$mode" = "--all" ]; then
   for c in $cards; do
@@ -309,6 +436,7 @@ if [ "$mode" = "--all" ]; then
   done
 
   check_discovered
+  check_defers
 fi
 
 if [ "$fails" -eq 0 ]; then

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

@@ -30,8 +30,8 @@ Findings deliverable (`deliverable: findings` in SPEC): P2 freeze → `phase: P5
 ## 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, 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.
+1. `N` = STATE `milestone:` (default v1). `mkdir -p .bestest/milestones/N` and `git mv` SPEC.md, DESIGN.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 every `hash` line (archived copies stay frozen); 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 — 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.
 

package/payload/skills/build/SKILL.md

@@ -9,14 +9,14 @@ You are the **orchestrator**: dispatch, gate, close loops. You do not write prod
 
 ## Dispatch loop
 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`) + Lessons (the exact LESSONS.md lines appended, or `None`) + Discovered.
+2. **Dispatch a fresh subagent** with: the card, LESSONS.md ("read first, append what you learn"), relevant D-IDs, and the file named by the card's `design:` field when not none. 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); before new code, descend the ladder: delete the need → reuse this repo → stdlib → platform-native → installed dep → minimum that works; never simplify away validation, security, error handling, accessibility, or anything explicitly asked. A deliberate ceiling gets a code comment `bestest-defer: <ceiling> until <trigger>` plus a Discovered line — never silently. 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 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.
+6. **Review** (risk-scaled): dispatch **reviewer** agent — card weight ≥4 → full adversarial pass; weight <4 → blockers-only. Design-bearing cards add **ui-mode**: the dispatch also includes the contract file and the design skill's `references/review-rules.md`. A finding closes only *fixed-and-reconfirmed by the reviewer*, or waived as a D-ID with a revisit trigger.
 7. Mark done, update STATE.md, commit `.bestest/`, next card.
 
 ## Interrupt handling

package/payload/skills/design/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: design
+description: Use when a bestest project has a visible interface — design direction, the frozen DESIGN.md contract, and UI craft rules.
+---
+
+# Design
+
+Loaded from interrogate Stage 2 when discovery finds an interface surface. Output: `.bestest/DESIGN.md` (template: DESIGN.md), frozen at P2 beside the SPEC. Direction method: `references/direction.md`. Motion values: `references/motion.md`. Rules the reviewer applies in ui-mode: `references/review-rules.md`.
+
+## 1. Discovery
+Ask only what research can't derive: platforms and breakpoints · brand constraints (existing tokens, fonts, logo rules) · accessibility floor beyond WCAG AA · motion appetite · the 2–3 screens users live in. **Brownfield:** extract incumbent tokens/components from the codebase first, `[cited:path]` — never re-ask what the stylesheet already answers. **No meaningful visual surface** (CLI, library, service)? Record that as a D-ID and stop — no DESIGN.md, none of the downstream gates activate.
+
+## 2. Direction
+Before any token: run `references/direction.md`. Name the 3 nearest default looks and ban them in the contract; pick ONE specific reference object (never adjectives); pick ONE signature element only this product could have. Present direction as a Taste batch — the user vetoes, you decide the rest.
+
+## 3. Contract
+Fill `templates/DESIGN.md`, headers verbatim. Discipline trace.sh enforces mechanically: `covers:` names the UI R-IDs · raw hex/px/font values live ONLY in Tokens and Contrast pairs — Components reference `{tokens}` · every Motion row is numeric ms + named easing, values from `references/motion.md` (`none` is an honest row) · every text fg/bg pair declared under Contrast pairs (≥4.5:1, or 3:1 marked `— AA-large`) · Do/Don't ≥3 each, testable phrasing.
+
+## 4. Freeze (P2, with the SPEC)
+The plan-checker's spec mode grades the contract alongside the SPEC; blockers block the freeze. Then hash it into LOCKS in the same gate step:
+```bash
+h="$( (command -v sha256sum >/dev/null && sha256sum .bestest/DESIGN.md || shasum -a 256 .bestest/DESIGN.md) | cut -d' ' -f1)" && printf 'hash %s .bestest/DESIGN.md\n' "$h" >> .bestest/LOCKS
+```
+Amendment = D-ID → shell-gate edit → re-hash, exactly like the SPEC. Rollover archives it with the milestone.
+
+## 5. Downstream (all trace-checked)
+P3: every card advancing a `covers:` R-ID sets `design: .bestest/DESIGN.md` — the orchestrator hands that file to builder and reviewer with the card. P4: reviewer runs ui-mode on design-bearing cards (contract + `references/review-rules.md`). P5: each `covers:` R-ID's UAT evidence is a screenshot/recording path, not prose — a UI criterion nobody looked at is not accepted.

package/payload/skills/design/references/direction.md

@@ -0,0 +1,23 @@
+# Direction — escaping the default look
+
+Generated design clusters hard around three looks: cream/warm-paper background + high-contrast serif display + terracotta accent · near-black background + one acid-green or vermilion accent · broadsheet layout with hairline rules. They are defaults, not choices. If another system given a similar prompt would produce substantially the same interface, the direction step failed.
+
+## Method, in order
+1. **Name the defaults.** Write the 3 most likely default looks for THIS product type — a pattern you haven't named is a pattern you can't avoid. They go in DESIGN.md as banned defaults.
+2. **One specific reference.** A reference object describes a point; adjectives describe a region. "A 1970s graduate lecture handout" beats "clean, modern, trustworthy" — and naming the object names its negatives for free (a handout doesn't glow or use gradients).
+3. **One signature element.** Something that could only exist for this product — a domain-shaped motif, an unexpected but purposeful structural move. "The overall feel" doesn't count; you must be able to point at it.
+4. **Tokens from the world.** 4–6 named colors whose names evoke the reference ("ink", "parchment"). Reading the token list aloud should evoke the product, not a template ("gray-700", "surface-2").
+
+## Craft rules (defaults that ARE choices)
+- Hierarchy: ONE focal point per view; weight and color do more hierarchy work than size; trust modest type ratios (1.2–1.333).
+- Color: 60/30/10 distribution; dark-mode surfaces climb roughly +7/+9/+12% lightness per level; borders are low-alpha white, not opaque gray.
+- Shape: inputs sit darker/inset — they receive content; sidebars share the canvas color; nested radii concentric — child ≤ parent, outer = inner + padding.
+- Type and data: tabular numerals for figures; balance-wrapped headings; density is a choice — state it in px, tight or airy, never unexamined.
+- Touch targets ≥44px.
+- **Use what exists:** native element → headless primitive → hand-roll last; hand-rolling owes the full behavior contract (keyboard nav, focus trap and return, ARIA names).
+
+## Self-tests before the contract freezes
+- **Swap test:** cover the product name — is the interface still recognizably this product?
+- **Squint test:** blur the view — does exactly one focal point survive?
+- **Token test:** read the token names aloud — world or template?
+- **Signature test:** point at five specific decisions that are yours; vibes don't count.

package/payload/skills/design/references/motion.md

@@ -0,0 +1,33 @@
+# Motion — the numeric canon
+
+Fill the DESIGN.md Motion table from these values; deviations are Taste calls recorded in the contract. When in doubt: less. The remedial step for a bad animation is deletion, not tuning.
+
+## When to animate
+- Action fired 100+ times a day (shortcuts, command palette, tab switches): **no animation, ever** — write the row as `none`; that is a contract, not an omission.
+- Never animate keyboard-initiated focus or typing.
+- Tens/day: minimal or none. Occasional (modals, toasts): standard. Rare or first-run: delight allowed.
+
+## Durations
+Press feedback 100–160 ms · tooltips 125–200 ms · dropdowns/popovers 150–250 ms · modals/drawers 200–500 ms · everything non-modal under 300 ms. Exits run 60–70% of their enter — leaving should feel faster than arriving. Stagger list entrances 30–50 ms per item.
+
+## Easing
+- Entering or exiting the screen → ease-out.
+- Moving on-screen (reorder, resize, reposition) → ease-in-out.
+- Hover, color, opacity → ease.
+- Constant motion (spinners, progress) → linear.
+- **Never ease-in for UI** — it delays movement at the exact moment the user is watching closest.
+
+Tokens: `--ease-out: cubic-bezier(0.23, 1, 0.32, 1)` · `--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1)` · `--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1)`.
+
+## Physicality
+- Nothing appears from nothing: enter from scale(0.95) + opacity 0, never scale(0).
+- Pressables compress: scale(0.97) on active press.
+- Popovers and menus scale from their trigger (transform-origin at the trigger); centered modals are exempt.
+- State that retargets mid-flight (toasts, toggles, gestures) uses interruptible transitions/springs, never restart-from-zero keyframes.
+
+## Performance
+- Animate transform and opacity only; never layout properties (width, height, top, left).
+- Write full transform strings — animation-library shorthand props may bypass hardware acceleration.
+- Never drive child transforms through a parent CSS variable (per-frame recalculation storm).
+- Blur ≤20px.
+- `prefers-reduced-motion`: movement degrades to opacity; never silently remove feedback.

package/payload/skills/design/references/review-rules.md

@@ -0,0 +1,42 @@
+# UI review rules — reviewer ui-mode
+
+Audit the diff against every rule; each finding cites its rule ID. Blockers at any weight: raw values where a DESIGN.md token exists, motion off the contract's Motion table, a report with no rendered-output pointer (screenshot/recording) for a visual change. Distinctive is not wrong — block only contract and rule violations; taste is at most a flag. Default to flagging; approval is earned.
+
+## Interaction
+- I1 NEVER block paste in inputs or textareas.
+- I2 MUST: hit targets ≥44×44px, or padded to it.
+- I3 MUST: visible focus state on every interactive element; never remove an outline without a replacement.
+- I4 MUST: URL reflects shareable state — filters, tabs, pagination survive reload and share.
+- I5 MUST: no double-submit — disable or make idempotent after first activation.
+
+## Layout
+- L1 MUST: flex children that truncate need min-width 0.
+- L2 NEVER: horizontal scroll at a breakpoint DESIGN.md declares.
+- L3 MUST: nested radii concentric — child ≤ parent.
+
+## Forms
+- F1 MUST: every input has a label or accessible name.
+- F2 MUST: validate on blur, not per keystroke; error text says how to fix.
+
+## Feedback
+- B1 MUST: mutations reflect in under 500 ms or show optimistic/pending state.
+- B2 MUST: destructive actions get confirm or undo.
+- B3 MUST: operations over 300 ms show a loading state; known layouts prefer skeleton over spinner.
+
+## Accessibility
+- A1 MUST: text contrast satisfies the DESIGN.md Contrast pairs (4.5:1; 3:1 AA-large); a new fg/bg pair the diff introduces gets declared in the contract, not eyeballed.
+- A2 MUST: modals trap focus and return it on close.
+- A3 MUST: icon-only buttons carry an accessible name.
+- A4 NEVER: emoji as icons.
+
+## Motion
+- M1 MUST: every animation in the diff matches a DESIGN.md Motion row (duration + easing); an unlisted animation is an undeclared contract change.
+- M2 NEVER: ease-in on UI; never enter from scale(0); never animate 100+/day actions.
+- M3 MUST: prefers-reduced-motion handled — movement degrades to opacity.
+- M4 MUST: transform/opacity only; no layout-property animation.
+
+## Tokens
+- T1 MUST: no raw hex/px/font/duration where a contract token exists — new values are contract amendments, not inline improvisation.
+- T2 MUST: the DESIGN.md signature element survives in the shipped surface; flag a diff that erodes it.
+
+Report shape: rule-ID findings first (blockers, then flags), then the standard delete-list.

package/payload/skills/interrogate/SKILL.md

@@ -24,7 +24,7 @@ Six forcing questions, strictly one at a time, researching between answers so th
 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.
+Adaptive, domain-specific gray areas across six buckets: users/actors · data & lifecycle · integration surface · failure/abuse · **interface surface** (visible UI → load the **design** skill) · **Anti-Goals (mandatory, ≥3)**. Present options annotated with what research already found ("Postgres and SQLite both fit; SQLite unless you need concurrent writers — you said single user"). Batch related Taste questions; never ask what Stage-3 research can derive.
 
 ## Stage 3 — Research handoff
 Zero user questions by default. Load the **research** skill: fan-out → primary sources → adversarial verification → cited stack table → SLOPCHECK on every proposed dependency. Output: SPEC §5 rows, all `[cited:URL]`. A question only execution can answer → the research skill's spike protocol (timeboxed, hook-quarantined, disposition-mandatory).
@@ -46,4 +46,4 @@ Close the stage by writing **SPEC §8 — the doneness function**: the falsifiab
 ```bash
 mkdir -p .bestest && h="$( (command -v sha256sum >/dev/null && sha256sum .bestest/SPEC.md || shasum -a 256 .bestest/SPEC.md) | cut -d' ' -f1)" && printf 'hash %s .bestest/SPEC.md\nglob <test-glob>\n' "$h" >> .bestest/LOCKS
 ```
-Set `spec_hash:` in STATE.md, commit, advance to P3. This is the **last HIGH-touch moment** — everything after runs on the contract.
+UI projects append the DESIGN.md hash line too (design skill §4). Set `spec_hash:` in STATE.md, commit, advance to P3. This is the **last HIGH-touch moment** — everything after runs on the contract.

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

@@ -1,6 +1,6 @@
 # Challenge tactics (Stage 4)
 
-Run all five; report what each found, even if "nothing".
+Run all six; report what each found, even if "nothing".
 
 ## 1. Tension naming
 Find pairs of stated goals that pull against each other ("offline-first" vs "always-fresh data"; "zero config" vs "multi-tenant"). Name the tension, state which side the current spec silently picked, make the user pick explicitly. D-ID the resolution.
@@ -17,5 +17,8 @@ Walk every feature/requirement back to the Premise Verdict. Anything that doesn'
 ## 5. Alternatives for heavy decisions
 Every weight≥6 decision gets one genuinely different alternative (not a strawman), with the strongest honest case for it in two sentences. If the user's choice survives the strongest opposing case, it's load-tested; if it flips, the challenge just paid for the whole interrogation.
 
+## 6. YAGNI ladder on requirements
+For every surviving requirement: what observably breaks if we ship without it? Could reuse, the stdlib, or the platform satisfy it with no new code? "We might need it" becomes Defer with a written reopen trigger. Challenge in-answer ("did X; Y covers it — need full X? say so"), never as a stall. Floor — never cut: validation, security, error handling, accessibility, anything the user explicitly asked for. A requirement is complexity smuggled in as prose; challenge it like code.
+
 ## SLOPCHECK (dependency vetting, used by Stage 3)
 For each proposed dependency: last release date · open-issue trend · maintainer bus-factor · install weight · license · does the stdlib/platform already do this? Reject any dep that fails two, unless a D-ID records why it's worth it.

package/payload/skills/plan/SKILL.md

@@ -13,9 +13,10 @@ Input: frozen SPEC. Output: `.bestest/PLAN.md` (template: PLAN.md) and `.bestest
 - **TDD pairing:** tests are authored by a card with `may_edit_tests: true`; the implementer card that follows has `false` and makes them pass (the lock-guard hook enforces this physically).
 - **Complexity formula**, computed honestly on every card: `1 + 2/extra file + 2/verify command + 3 if the title needs "and" + 2/new interface`. Over 6 → split before anyone reviews it.
 - Every card: `requirements:` R-IDs (no orphan cards), `files:` blast radius, `verify:` commands a machine can re-run, `blocked_by:` for real order constraints only.
+- **Design-bearing cards:** every card advancing an R-ID named by a DESIGN.md `covers:` line sets `design: .bestest/DESIGN.md` and consumes contract tokens — never invented visual values (`trace.sh --plan` checks the cascade).
 
 ## Complexity Justification table (in PLAN.md)
-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.
+Any design element beyond the simplest thing satisfying the R-IDs gets a row (columns in the PLAN.md template). Each row names the next-simpler rung rejected — reuse in this codebase / stdlib / platform-native / installed dep — "we might need it" is not a justification. 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/ship/SKILL.md

@@ -8,13 +8,13 @@ description: Use when a bestest project enters P5 — UAT against every acceptan
 Nothing new gets built here; P5 proves what exists and stages it for production. 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.
+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**. R-IDs named by a DESIGN.md `covers:` line: the evidence must be a screenshot/recording path — `trace.sh --all` fails prose-only UI rows. 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
 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 line (grammar in the DISCOVERED.md header). trace.sh fails any bare line. This is where "never dropped" gets cashed.
+First harvest deferral markers: `git grep -n 'bestest-defer:'` — every marker gets a DISCOVERED `defer:` line (grammar in the header); trace.sh --all fails trigger-less and unharvested markers. Then append `| disposition:` to each line. 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. 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.

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

@@ -3,7 +3,7 @@
 | Concept | Native here |
 |---|---|
 | Router | `/bestest:go`, `/bestest:status` (plugin command stubs → bestest-go/bestest-status skills) |
-| Plugin root | `${CLAUDE_PLUGIN_ROOT}`, pre-rendered inside the command stubs; bootstrap records it as the `plugin:` line in STATE.md |
+| Plugin root | `${CLAUDE_PLUGIN_ROOT}`, pre-rendered inside the command stubs; first-time bootstrap records it as the `plugin:` line in STATE.md — an existing line that resolves on disk wins |
 | Planning mode | plan mode — read-only exploration before mutating anything |
 | Todo tracking | TodoWrite — one entry per gate step or card |
 | Structured user questions | AskUserQuestion — batch weight≥4 decisions into one call |

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

@@ -3,7 +3,7 @@
 | Concept | Native here |
 |---|---|
 | Router | `$bestest-go` / `$bestest-status` skill mentions (or implicit trigger by description) |
-| Plugin root | newest dir from `ls -d ~/.codex/plugins/cache/*/bestest/*` — bootstrap records it as the `plugin:` line in STATE.md (hooks also get `${CLAUDE_PLUGIN_ROOT}` env) |
+| Plugin root | newest dir from `ls -d ~/.codex/plugins/cache/*/bestest/*` — first-time bootstrap records it as the `plugin:` line in STATE.md; an existing line that resolves on disk wins (hooks also get `${CLAUDE_PLUGIN_ROOT}` env) |
 | Planning mode | `/plan` |
 | Todo tracking | built-in plan/update_plan facility |
 | Structured user questions | plain chat — one decision per message, options lettered |

package/payload/templates/DESIGN.md

@@ -0,0 +1,54 @@
+# DESIGN — <project> visual contract
+<!-- Written by the design skill (P0–P2), frozen at P2: its sha256 joins
+     .bestest/LOCKS beside the SPEC hash (lock-guard then blocks edits).
+     Amendment = D-ID → shell-gate edit → re-hash, same ceremony as the SPEC.
+     trace.sh gates: covers: R-IDs real in SPEC · every section filled · hex
+     only in Tokens/Contrast pairs · Motion rows numeric · contrast pairs
+     ≥4.5:1 (3:1 with "— AA-large") · each covers: R-ID needs a design-bearing
+     card (--plan) and rendered UAT evidence (--all).
+     Section headers are matched verbatim — do not rename them.
+     Guidance lives in comments; leave a section empty until it is real. -->
+covers: <comma-separated R-N.M this contract governs>
+
+## Direction
+<!-- - reference: ONE specific object ("a 1970s graduate lecture handout"),
+       never adjectives — a reference describes a point, adjectives a region.
+     - signature: one element that could only exist for THIS product.
+     - banned defaults: >=3 nearest default looks, named and rejected
+       (e.g. cream + high-contrast serif + terracotta accent; near-black +
+       single acid-green accent; broadsheet hairline rules). -->
+
+## Tokens
+<!-- The ONLY home for raw hex/px/font values. 4–6 named colors with roles;
+     names evoke the world ("ink", "parchment"), not the template ("gray-700").
+       | token | value | role |
+     Plus: spacing unit · radius scale (nested: child <= parent; concentric:
+     outer = inner + padding) · type family / scale ratio / weights. -->
+
+## Contrast pairs
+<!-- Every text-bearing fg/bg pair, one per line, exact grammar:
+       - #RRGGBB on #RRGGBB
+       - #RRGGBB on #RRGGBB — AA-large   (>=24px, or bold >=19px)
+     trace.sh computes WCAG ratios from these lines (python3). -->
+
+## Components
+<!-- Per-component specs referencing {tokens} only — raw hex here fails trace.
+       e.g. button-primary: bg {ink} · text {parchment} · radius {r1} · 36px h
+     Component sizes/paddings may cite the spacing unit. -->
+
+## Motion
+<!-- One row per animated element; "none" is a valid, honest contract row.
+     Keep the header row — trace.sh skips it and the |---| separator, then
+     demands numeric ms + a named easing (ease*/linear/cubic-bezier/spring)
+     on every other row. Values come from the design skill's motion canon.
+       | element | trigger | duration | easing | notes |
+       |---|---|---|---|---|
+       | modal | open | 240 ms | ease-out | scale 0.95→1 + opacity | -->
+
+## Do / Don't
+<!-- >=3 each, testable phrasing ("Don't use bold anywhere; body stays 400/500",
+     not "keep it clean"). The plan-checker blocks vibes here. -->
+
+## Responsive
+<!-- Breakpoints + what reflows at each; no horizontal scroll at any declared
+     breakpoint (review rule). Touch targets >=44px below the pointer break. -->

package/payload/templates/DISCOVERED.md

@@ -1,6 +1,9 @@
 # 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>
+     Deliberate ceilings marked in code ('bestest-defer: <ceiling> until <trigger>')
+     get a line too — trace.sh --all fails trigger-less or unharvested markers:
+       - defer: <ceiling> | discovered-from: T-## | marker: <file>
      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/PLAN.md

@@ -14,5 +14,5 @@
 ## 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 |
+| Complexity | Why needed | Next-simpler rung rejected (reuse / stdlib / platform / installed dep) because |
 |---|---|---| -->

package/payload/templates/SPEC.md

@@ -6,7 +6,9 @@
 <!-- one paragraph: the real problem, for whom, why now, why not an existing tool.
      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). -->
+     R-IDs become questions, P3-P4 are skipped (research references/findings.md).
+     Visible interface: the design skill produces .bestest/DESIGN.md, frozen
+     beside this SPEC; its covers: line names the UI R-IDs from §2. -->
 
 ## 2. Requirements — EARS acceptance criteria
 <!-- one sentence each, numbered R-N.M, observable behavior only:

package/payload/templates/UAT.md

@@ -1,6 +1,8 @@
 # UAT — one question per acceptance criterion
 <!-- Filled at P5. One row per R-N.M from SPEC §2. The user answers the question;
-     'pass' requires their yes plus the evidence pointer. -->
+     'pass' requires their yes plus the evidence pointer. R-IDs named by a
+     DESIGN.md covers: line need a screenshot/recording path as evidence —
+     trace.sh --all fails prose-only UI rows. -->
 
 | R-ID | question to user (restates the EARS criterion as a check) | evidence | result |
 |------|-----------------------------------------------------------|----------|--------|

package/payload/templates/task-card.md

@@ -8,6 +8,9 @@ weight: 3               # irreversibility x scope; >=4 -> full adversarial revie
 complexity: 3           # 1 + 2/extra file + 2/verify cmd + 3 if title needs "and" + 2/new interface; >6 split
 blocked_by: none        # comma-separated T-IDs
 may_edit_tests: false   # true only on test-author cards (lock-guard enforces)
+design: none            # .bestest/DESIGN.md when this card renders human-facing UI —
+                        # the orchestrator hands that file to builder AND reviewer
+                        # (ui-mode) with the card; trace.sh checks the cascade
 verify:
   - <command that proves this card done — orchestrator re-runs it>
 ---