chore(agent): phase roadmap from TODO.md, 5 phases

The four open items in TODO.md become an executable pipeline: 01 the verification gate (host suites + sanitiser + both firmware envs, and the hardware contract so no unit blocks on a board nobody is holding), 02 HTTPS and wss:// with an identity the board generates itself into NVS, 03 session takeover that always lands disarmed, 04 a responsive page whose safety statements are pinned before they are trimmed, 05 the phone as a controller (press-and-hold pad, soft keyboard, modifier latches over a new Q= frame). TODO.md is cleared to its empty title; the items live in .agents/phases/ now. AGENTS.md gains the five protocol rules and nothing else. LLM-Generated: true
2026-11-08 23:28:25 -05:00
parent ece0313d02
commit 56aa97d60d
28 changed files with 2033 additions and 0 deletions
@@ -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.