perf(dashboard): cut /boxes first-paint (auth session + static cache + code-split + de-suspend)

.claude/agents/claude-md-auditor.md

@@ -0,0 +1,49 @@
+---
+name: claude-md-auditor
+description: Independent auditor that judges a pending git commit or push against every applicable bullet in CLAUDE.md (Workflow section). MUST be invoked before retrying a `git commit` or `git push` that was blocked by .claude/hooks/preflight-claude-md.sh. Reads CLAUDE.md and the diff cold in fresh context, writes a structured verdict to .claude/.last-audit.json. The hook only allows the next retry when the verdict file is PASS and matches the current branch + HEAD.
+tools: Read, Bash, Write
+---
+
+You are the CLAUDE.md compliance auditor for the boxlite3 repository.
+
+The parent agent must tell you the exact git command they are about to retry
+(e.g. `git commit -m "..."` or `git push origin <branch>`). Treat that as the
+"target command" below.
+
+## Procedure
+
+1. Read `CLAUDE.md` from the repo root. Locate the `## Workflow` section.
+2. Capture current repo state:
+   - `git branch --show-current`
+   - `git rev-parse HEAD`
+3. Capture the diff that is about to land:
+   - If the target command starts with `git commit`: `git diff --cached`.
+   - If it starts with `git push`: `git diff origin/main...HEAD`.
+4. For each Workflow phase (Understand / Research / Design / Implement / Test /
+   Verify / Cross-cutting):
+   - Identify which bullets are applicable to this diff. Skip ones that don't
+     apply (e.g. concurrency rules for a pure docs change).
+   - Judge PASS or FAIL against what the diff actually shows. Be skeptical:
+     missing tests, scope creep, undocumented new dependencies, secrets,
+     weakened assertions, comments that restate code, etc.
+5. Write `.claude/.last-audit.json` with EXACTLY this shape (no extra fields):
+   ```json
+   {
+     "branch": "<from step 2>",
+     "head": "<from step 2>",
+     "command_kind": "commit" | "push",
+     "verdict": "PASS" | "FAIL",
+     "findings": ["<phase>: <one-line description>", "..."]
+   }
+   ```
+   On PASS, `findings` is an empty array.
+6. Reply to the parent agent with the verdict and findings.
+
+## Constraints
+
+- Only judge — do not propose fixes, do not edit code, do not retry the git
+  command yourself.
+- Do not skip phases. If a phase has no applicable bullets for this diff, say so
+  explicitly in your reply (not in findings).
+- The hook reads only the JSON file; your chat reply is for the parent agent's
+  benefit. Both must agree.

.claude/hooks/preflight-claude-md.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# PreToolUse hook: gate `git commit` / `git push` on a fresh verdict from the
+# claude-md-auditor subagent (see .claude/agents/claude-md-auditor.md).
+#
+# The hook itself does not call any model; it only reads the verdict artifact
+# the subagent writes at .claude/.last-audit.json and checks that the verdict
+# is PASS, recent, and bound to the current branch + HEAD.
+#
+# Flow on a denied attempt:
+#   1. Hook denies the git tool call.
+#   2. Reason text instructs the parent agent to invoke the claude-md-auditor
+#      subagent via the Task tool, then retry the same git command.
+#   3. Subagent writes .claude/.last-audit.json.
+#   4. Parent retries -> hook reads the artifact and allows on PASS.
+#
+# Wired in .claude/settings.json under hooks.PreToolUse with matcher "Bash".
+#
+# Design notes
+# ------------
+# * Matcher scope: settings.json registers this hook on the broad `Bash`
+#   matcher, not a narrower `Bash:git*` pattern, because Claude Code's
+#   PreToolUse matchers are tool-name-only — there's no built-in way to filter
+#   on the bash command itself. The script does the actual filtering via the
+#   case match below and exits 0 immediately on non-target commands, so the
+#   per-invocation cost on unrelated bash calls is one jq parse + one regex.
+#
+# * One-shot consumption: the audit file is `rm -f`'d on the allow path
+#   (intentional, see end of script). This forces a fresh audit on every
+#   subsequent git commit/push — even at the same HEAD — so re-staged content
+#   between commits can't ride on the previous audit. The cost is that
+#   commit-then-push of the same HEAD must re-audit; the user has accepted
+#   this trade-off to avoid stale-audit-passes-new-content failure modes.
+#
+# Tests: bash .claude/hooks/preflight-claude-md.test.sh
+set -euo pipefail
+
+payload="$(cat)"
+command="$(printf '%s' "$payload" | jq -r '.tool_input.command // ""')"
+
+# Match when the command actually IS a `git commit` / `git push` invocation —
+# at the start of the command OR at the start of any chain segment (after &&,
+# ||, ;, |, &, $(, (, `). This catches the chained-command case
+# (`cat foo && git commit ...`) that an anchor-only matcher misses, while still
+# rejecting literal mentions of "git commit" inside string arguments (e.g.
+# `echo "git commit"`), which don't sit at the start of a chain segment.
+work="${command#"${command%%[![:space:]]*}"}"
+if [[ "$work" =~ (^|[[:space:]]*(\&\&|\|\||;|\||\&|\$\(|\(|\`)[[:space:]]*)([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]+[[:space:]]+)*git[[:space:]]+(commit|push)([[:space:]]|$) ]]; then
+  case "${BASH_REMATCH[4]}" in
+    commit) kind="commit" ;;
+    push)   kind="push"   ;;
+    *)      exit 0 ;;
+  esac
+else
+  exit 0
+fi
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+project_dir="${CLAUDE_PROJECT_DIR:-$repo_root}"
+branch="$(git -C "$repo_root" branch --show-current 2>/dev/null || echo '?')"
+head="$(git -C "$repo_root" rev-parse HEAD 2>/dev/null || echo '?')"
+audit_file="$project_dir/.claude/.last-audit.json"
+max_age_seconds=600
+
+deny() {
+  jq -nc --arg r "$1" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: $r
+    }
+  }'
+  exit 0
+}
+
+invoke_instruction="Invoke the claude-md-auditor subagent now:
+  Task(subagent_type='claude-md-auditor',
+       description='CLAUDE.md audit',
+       prompt='Audit the pending \`${command}\` on branch ${branch}.')
+The subagent will write its verdict to .claude/.last-audit.json. Retry the
+same git command after it reports PASS."
+
+if [[ ! -r "$audit_file" ]]; then
+  deny "No CLAUDE.md audit found for this change.
+
+${invoke_instruction}"
+fi
+
+audit_branch="$(jq -r '.branch // ""' "$audit_file" 2>/dev/null || echo '')"
+audit_head="$(jq -r '.head // ""' "$audit_file" 2>/dev/null || echo '')"
+audit_kind="$(jq -r '.command_kind // ""' "$audit_file" 2>/dev/null || echo '')"
+audit_verdict="$(jq -r '.verdict // ""' "$audit_file" 2>/dev/null || echo '')"
+
+# File mtime as freshness signal — portable across BSD (stat -f %m) and GNU
+# (stat -c %Y) without parsing self-reported timestamps.
+audit_mtime="$(stat -f '%m' "$audit_file" 2>/dev/null || stat -c '%Y' "$audit_file" 2>/dev/null || echo 0)"
+now_epoch="$(date +%s)"
+age=$(( now_epoch - audit_mtime ))
+
+if [[ "$audit_branch" != "$branch" ]] || \
+   [[ "$audit_head" != "$head" ]] || \
+   [[ "$audit_kind" != "$kind" ]] || \
+   (( age > max_age_seconds )); then
+  deny "Existing audit does not match current state:
+  audit.branch=${audit_branch}  current=${branch}
+  audit.head=${audit_head}      current=${head}
+  audit.command_kind=${audit_kind}  current=${kind}
+  audit age: ${age}s (max ${max_age_seconds}s)
+
+Re-audit is required.
+${invoke_instruction}"
+fi
+
+if [[ "$audit_verdict" != "PASS" ]]; then
+  findings="$(jq -r '.findings[]? | "  - " + .' "$audit_file" 2>/dev/null || echo '')"
+  deny "CLAUDE.md audit FAILED on branch '${branch}':
+
+${findings}
+
+Address each finding, then re-invoke claude-md-auditor before retrying \`${command}\`."
+fi
+
+# Verdict is PASS, recent, and matches current state — let the git command run.
+# Consume the audit file so the next commit/push always re-audits, even if HEAD
+# hasn't changed (e.g., user re-stages different content before the next commit).
+rm -f "$audit_file"
+exit 0

.claude/hooks/preflight-claude-md.test.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Tests for .claude/hooks/preflight-claude-md.sh
+#
+# Covers the two areas CLAUDE.md flags for required tests on this change:
+#   1. Command matcher (parsing + branching): direct invocation vs. chain
+#      segments vs. literal-string mentions inside arguments.
+#   2. Gate logic (branching + boundary validation): missing / mismatched /
+#      stale / FAIL / consumed audit-file paths.
+#
+# Run with:  bash .claude/hooks/preflight-claude-md.test.sh
+# Exits non-zero on any failure.
+set -uo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+HOOK="$REPO_ROOT/.claude/hooks/preflight-claude-md.sh"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# Redirect the hook's audit-file lookup into TMP so tests don't touch the real
+# .claude/.last-audit.json. The hook still uses git from the real repo for
+# branch/HEAD detection — that's fine, we read the same values for assertions.
+export CLAUDE_PROJECT_DIR="$TMP"
+mkdir -p "$TMP/.claude"
+
+BRANCH="$(git -C "$REPO_ROOT" branch --show-current)"
+HEAD_SHA="$(git -C "$REPO_ROOT" rev-parse HEAD)"
+
+pass=0
+fail=0
+
+run() {
+  local desc="$1" cmd="$2" expect="$3" out decision
+  out=$(printf '%s' "$cmd" | jq -Rs '{tool_input:{command:.}}' | "$HOOK")
+  if [[ -z "$out" ]]; then
+    decision="passthrough"
+  else
+    decision=$(printf '%s' "$out" | jq -r '.hookSpecificOutput.permissionDecision' 2>/dev/null || echo "parse_error")
+  fi
+  if [[ "$decision" == "$expect" ]]; then
+    pass=$((pass + 1))
+    printf '  PASS  %s\n' "$desc"
+  else
+    fail=$((fail + 1))
+    printf '  FAIL  %s  (got=%s expected=%s)\n' "$desc" "$decision" "$expect"
+  fi
+}
+
+write_audit() {
+  local verdict="$1" findings_json="$2" kind="$3"
+  jq -nc --arg b "$BRANCH" --arg h "$HEAD_SHA" \
+        --arg v "$verdict" --arg k "$kind" \
+        --argjson f "$findings_json" \
+        '{branch:$b, head:$h, command_kind:$k, verdict:$v, findings:$f}' \
+        > "$TMP/.claude/.last-audit.json"
+}
+
+GC='git commit'
+GP='git push'
+
+echo "## Matcher: should pass through (not a git commit/push invocation)"
+rm -f "$TMP/.claude/.last-audit.json"
+run "ls"                                "ls"                          "passthrough"
+run "echo with literal mention"         "echo \"$GC\""                "passthrough"
+run "grep with literal mention"         "grep \"$GC\" file"           "passthrough"
+run "git status (different verb)"       "git status"                  "passthrough"
+run "git log (different verb)"          "git log --oneline -5"        "passthrough"
+
+echo
+echo "## Matcher: should gate (real git commit/push invocation)"
+run "direct commit"                     "$GC -m wip"                  "deny"
+run "direct push"                       "$GP origin main"             "deny"
+run "chained with &&"                   "cd x && $GC -m wip"          "deny"
+run "chained with ||"                   "true || $GC -m foo"          "deny"
+run "chained with ;"                    "echo done; $GC"              "deny"
+run "env var prefix"                    "FOO=bar $GC -m x"            "deny"
+run "command substitution"              "out=\$($GC -m foo)"          "deny"
+run "push after &&"                     "cat x && $GP origin main"    "deny"
+
+echo
+echo "## Gate logic: audit file states"
+write_audit "PASS" "[]" "commit"
+run "PASS verdict matches → allow"      "$GC -m foo"                  "passthrough"
+run "verdict consumed on allow"         "$GC -m foo"                  "deny"
+
+write_audit "FAIL" '["Test: missing"]' "commit"
+run "FAIL verdict → deny"               "$GC -m foo"                  "deny"
+
+write_audit "PASS" "[]" "commit"
+# Mutate head field to simulate a stale-by-HEAD audit
+jq --arg h "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef" '.head=$h' \
+   "$TMP/.claude/.last-audit.json" > "$TMP/.claude/x.json" \
+   && mv "$TMP/.claude/x.json" "$TMP/.claude/.last-audit.json"
+run "HEAD mismatch → deny"              "$GC -m foo"                  "deny"
+
+write_audit "PASS" "[]" "commit"
+touch -t 202001010000 "$TMP/.claude/.last-audit.json"
+run "stale mtime (>max_age) → deny"     "$GC -m foo"                  "deny"
+
+write_audit "PASS" "[]" "commit"
+run "kind mismatch (commit vs push)"    "$GP origin main"             "deny"
+
+echo
+echo "RESULT: $pass passed, $fail failed"
+exit $(( fail > 0 ? 1 : 0 ))