# RHA Wrapper — Session Handoff (read me first)

**Product:** deterministic verification wrapper for LLM codegen. prompt → frozen IR (tests before code) → build → RHA bounded repair. Small local models are the THESIS — never recommend bigger models to fix failures; tighten the algorithm.

**Two tiers:** Tier 2 = local Express engine (localhost:4100, src/server + src/core). Tier 1 = the whole pipeline inside the Chrome extension (src/tier1 bundled to extension/tier1.bundle.js; jobs run in the offscreen document; suites execute in a sandboxed page; runs persist in chrome.storage via the SW). Site (web/) is STATIC on Cloudflare Pages (project `rha-software`, domain rha.software) — extension hosts all local data; keep the site low-tech.

**BINDING DOCTRINE — read `DOCTRINE.md` in this repo BEFORE diagnosing a run, proposing a fix, or writing a Cursor instruction set.** It is binding project policy, not reference material. The 24 maxims, in short form:

1 substrate before model · 2 the model supplies permutations, never validity · 3 the prompt is the intent oracle · 4 per-member certification precedes aggregation · 5 a crash is absence of evidence · 6 one invariant, one owner · 7 conservation of evidence (one start, one terminal disposition, before/after evidence) · 8 reachability is part of implementation · 9 inventory all paths before changing one · 10 canonical state is explicit · 11 metrics are typed measurements · 12 names do not confer semantics · 13 exceptions require stronger oracles · 14 falsifier before fix · 15 tests model the failure mechanism · 16 no invented eligibility thresholds · 17 fail-open operation is not fail-open certification · 18 repair requires confirming measurement · 19 complete means terminally certified · 20 small-model constraints are algorithm requirements · 21 advice is not execution authority · 22 a fix must survive reconstruction · 23 historical success is not current reachability · 24 one real cause does not end the search.

**Mandatory output order:** for every nontrivial request, write the `DOCTRINE COMPLIANCE REVIEW` record (DOCTRINE.md §IV) — decision, user outcome, work unit, canonical owner, path inventory, deterministic predicate, failure dispositions, metric equations, causal hypothesis, falsifier, production-shaped proof, terminal certification, release blockers. **Cursor instructions may follow only after `Decision: PASS`.** A failed gate is never silently downgraded to an implementation note; supply the smallest read-only probe or ask the one product question instead.

**CPU/LLM allocation (operational form of maxim 20):** CPU takes deterministic low-complexity work; LLM takes semantic pattern recognition. AST/regex extraction is CPU; idiom/trope/scheme identification on top of it is LLM. Never fold either way silently — folding a CPU task into an LLM prompt burns tokens; folding an LLM task into a CPU regex excises intelligence. See memory `cpu-vs-llm-allocation.md`.

**My eleven earned blind spots (DOCTRINE.md §I):** A source presence read as runtime capability · B one call site patched instead of one owner boundary · C aggregates trusted over members · D labels reasoned from instead of the object · E exceptions that weaken the invariant they bypass · F premature closure on the first plausible cause · G tests shaped like the implementation, not the failure · H invented constants promoted to policy gates · I canonical and derived state drifting · J telemetry accepted as causal proof · K local green counted as closure.

**Final maxim:** nothing is implemented because it is present, repaired because it was changed, valid because it was named, or complete because the loop ended.

**Release pipeline (MANDATORY for extension/web changes):** bump extension/manifest.json patch version → rebuild tier1 bundle if src/tier1|src/core changed (`npx vite build --config vite.tier1.config.ts`) → `npm run build:web` → `npx wrangler pages deploy web/dist --project-name rha-software --branch main --commit-dirty=true` (MUST be --branch main) → poll the edge until the zip serves the new version → atomically swap `~/rha-provider-vault` (never rm-in-place) → user ⟳'s the card, NEVER mid-run. The two patcher scripts (MacOS-Linux-Plugin-Patcher.sh / Windows-Plugin-Patcher.ps1) must always change together.

**Workflow (binding):** Andy drives execution via Cursor. **Claude is the analyst and instruction author; Cursor is the execution owner unless Andy explicitly says otherwise for a specific task.** Claude's deliverable is the doctrine-compliance review plus an instruction set in CURSOR_BACKLOG.md (active-only file; completed work lives in git). Andy's rationale: the spec gate of Claude writing instructions plus Cursor's fresh entropy produces higher fidelity than Claude executing directly. Enqueue EVERYTHING discussed since the last queue by default. Treat multi-part messages as checklists. Every set carries the auto-approve-all-gates directive (standing duty A3).

**Gotchas paid for in blood:** never restart the engine or reload the extension during an active job (in-memory state dies); web/src is typechecked only via `tsc -p tsconfig.web.json` (Escalation dup types are known pre-existing errors); Pages edge serves stale zips briefly after deploy (poll before trusting); offscreen documents have NO chrome.storage/notifications (route through the SW); the SW imports nothing heavy (a bad bundle must never kill the vault); scripted span-edits on App.tsx have twice deleted neighboring functions — verify boot (#root renders) after edits.

**Verification norms:** all tests `npx vitest run tests` must stay green; mock e2e is the algorithm's proof; browser-context checks for anything bundled (no `process`/`Buffer` in browser — shimmed in src/tier1/entry.ts).
