phase: 01_verification_gate

All green. Report:

**Implemented / verified (phase 01 final pass)**
- `.agents/validate.sh` re-verified as the gate: ①`tests/run_tests.sh` ②`SANITIZE=1` run ③`uv … platformio run -e bridge -e console` ④page byte count ⑤hygiene, then the informational `tools/hw_probe.sh`. Added an explicit `== repo hygiene ==` header + `repo hygiene: OK (57 tracked files…)` verdict line so every check prints one (previously hygiene passed in silence).
- `.agents/HW_VERIFICATION.md`: baseline (bridge 26.7 %/87 592 B, 36.1 %/1 135 293 B; console 16.8 %/33.6 %; 3406 checks; page 48 598 B) re-confirmed; served-page row extended with this pass's one-attempt measurements.

**Tests / gate (100 % green)**
- `bash .agents/validate.sh` → **exit 0** (also from `/tmp`): `RESULT: all suites passed` twice (3406 = 3162 C++ + 160 relayctl + 84 page), `2 succeeded`, `page bytes: 48598`, `repo hygiene: OK`, `validation OK`.
- Faults re-demonstrated then reverted: (a) inverted `test_keystate` assert → cold-copy gate `RESULT: FAILED`, **GATE_EXIT=1**; (b) markup id `pArmed`→`pArmedZ` → page suite rc 1; (c) type error in `src/main.cpp` → `bridge FAILED / console FAILED`, rc 1; (d) hygiene regex matches `certs/test.pem` (git index commands are forbidden in this pass — task 01's report holds the original live `git add` demo).
- Lint: no linter is configured for this repo; compiler is the linter — `-Wall -Wextra` host suites + both firmware builds: **0 warnings**; `bash -n` clean; `py_compile` clean. `ruff check` (this machine's broad ruleset) reports 21 pre-existing *preview-rule* style nits in untouched `tools/*.py` + `tests/test_relayctl.py` (SIM/UP/ISC/EXE/RUF/FURB), zero correctness findings — not churned: `watch_target.py`/`relayctl.py` are hardware-verified artifacts outside this phase. `shellcheck` is absent here and not in the local container image (fetching it would violate the gate's no-network rule). Coverage: n/a (shell + docs; no new Python).

**Completion criteria** — all met: exit 0 with per-check output ✓; SANITIZE in-gate ✓; no `-t upload`/device curl/network fetch (grep: only in comments; `run_tests.sh` checks `podman image exists` first, so never pulls) ✓; faults bite ✓; HW_VERIFICATION.md names command+expected observation for every 02–05 device claim + one-attempt rule ✓; full suite green, `git status` = phase artifacts + mandated doc edits, nothing stray ✓.

**Documentation** — README inconsistencies found & fixed: `test_proto` 193→**2327** (table now sums to the headline 3406); duplicate stale `test_page 47` row deleted (element-id clause merged into the 84 row); "last six checks"/"fails 3 checks" claims replaced by measurement (5 fail-safe source pins; `linked()` gate → 2, accept-stamp → 1, both → 3); console line formats corrected to what the code prints (`mouse interface=present target=report protocol buttons=0x00 …`, `queue 0 keys pending…`, `target=BOOT protocol (refused)`); status-JSON sample gained `typed/typing/mouse/mbtn/mframes`; footprint 87 400/35.5 %→87 592/36.1 %; page delivery `Content-Length: 35164`→**48 598** (re-measured live, one capped curl: 200/48 598, 404 on `/nope`, 401 on `/status`); stale Backlog item "Mouse." removed and renumbered; "~35 KB"→"~48 KB"; page-button names matched to the real markup; `validate.sh`/`HW_VERIFICATION.md`/`hw_probe.sh` added to Architecture, Tests and End-to-end. AGENTS.md: only stale statements fixed — "one commit, `Initial import`… predates the mouse and `output.h`" and the pure-module list missing `mouse.h`/`output.h`; not expanded.

**Deviations** — Did not run the keystroke/mouse device rows: the board's target is this very machine, so injecting input during an unattended pass is the side effect the README's "hazard nobody warns you about" forbids; those rows stay blank per the contract (read-only GETs only). No live infra changed.

**Next pending phase:** `02_tls_control_channel` (tasks `01_tls_identity_module` … `06_tls_docs_rollback`).

.agents/phases/complete/01_verification_gate/00_phase.md

@@ -0,0 +1,49 @@
+# Phase 01 — Verification gate and hardware contract
+
+**Source:** `TODO.md` — (foundation, no TODO line). Required before the four TODO items
+can be executed by subprocesses behind a pass/fail gate.
+**Story:** `n/a`
+**Context:** `PLAN.md` "Validation / Verification Workflow"; `tests/run_tests.sh`; `AGENTS.md` "Build, test, flash"
+
+## Objective
+
+Give this repository a `.agents/validate.sh` that actually fails when keyrelay is broken —
+host suites (including the sanitiser run and the page suite) plus **both** firmware builds —
+and write down the hardware contract so that no later unit ever blocks waiting for a board
+that nobody is holding.
+
+## Dependencies
+
+- — (none)
+
+## Tasks
+
+1. `01_adapt_validate_sh.md` — author `.agents/validate.sh` with keyrelay's real checks and
+   the template's repo-hygiene gates, and prove it fails on a deliberately broken tree.
+2. `02_hardware_contract.md` — `.agents/HW_VERIFICATION.md` + `tools/hw_probe.sh`: what can
+   only be checked on hardware, how to check it, the baseline RAM/flash numbers, and the
+   rule that a unit attempts a device step once, with a timeout, and records the outcome.
+
+## Testing & Quality
+
+- Unit/integration: the gate itself is the artifact. It must pass on a healthy tree **and**
+  fail on each injected fault: a failing C++ assertion, a page-suite id mismatch, a firmware
+  compile error in `src/main.cpp`, and a tracked `*.pem`.
+- Coverage: n/a for shell scripts; >90% applies only to any Python added (`tools/hw_probe.sh`
+  is shell, not Python).
+- `.agents/validate.sh` must run the **full** suite — a partial gate defeats the
+  "no phase commits unless 100% passing" guarantee.
+
+## Completion Criteria
+
+- [ ] `bash .agents/validate.sh` exits 0 on the untouched tree and prints, per check: the
+      suite results (`RESULT: all suites passed`), the two build results, and the hygiene verdict.
+- [ ] `SANITIZE=1` is exercised by the gate (or by a documented, gate-called second pass) and
+      passes.
+- [ ] The gate contains no `pio … -t upload`, no `curl` to a device, no network fetch.
+- [ ] Each of the four injected faults makes the gate exit non-zero (demonstrated in the
+      task's report, then reverted).
+- [ ] `.agents/HW_VERIFICATION.md` exists and names, for every device-only claim in this
+      roadmap, the command that observes it (`tools/watch_target.py`, the serial console,
+      `curl -k https://keyrelay.local/status`).
+- [ ] Full test suite green; `git status` shows only planning artifacts.