CLAUDE.md

1# wifi-veil-harness
2 
3Harness for [`wifi-veil`](..)
4(WiFi Veil — the compliant-waveform WiFi-sensing privacy shield, ADR-288). This
5package is defined by ADR-289.
6 
7> Advanced Coding harness · domain: `software-engineering`. Modeled on the
8> `wifi-densepose-sar-harness` scaffold (ADR-286), generated with
9> [create-agent-harness](https://github.com/ruvnet/agent-harness-generator).
10 
11## Behavioral rules
12 
13- Use the harness's tools for orchestration; memory and routing are handled by
14  the kernel.
15- Defer destructive operations to the user.
16- **Never present WiFi sensing as camera-grade, and never relabel WiFi Veil's
17  SYNTHETIC/L0 results as MEASURED** — a hardware witness is required first
18  (CLAUDE.md hardware rule; ADR-282 ladder). The harness is a development aid;
19  it does not run a radio and cannot emit RF.
20- WiFi Veil uses compliant waveform controls only — **never jamming.** Do not add,
21  suggest, or scaffold interference-based "defenses."
22 
23## Commands
24 
25- `init` — boot the kernel + host adapter.
26- `doctor` — verify the install end-to-end (kernel, host, guidance map).
27- `guidance --topic <t> [--query <q>]` — read-only WiFi Veil capability map
28  (dependency-free; topics: `overview`, `threat`, `countermeasure`,
29  `compliance`, `optimization`, `experiment`). Source-cited and
30  evidence-labelled; navigation only, not authority.
31- `route <e0> <e1> <e2> <e3>` — cost-optimal model routing via
32  `@metaharness/router` (needs `npm run build`).
33- `flywheel [generations]` — SYNTHETIC self-improvement demo via
34  `@metaharness/flywheel` (needs `npm run build`).
35 
36## Architecture
37 
38Uses [@metaharness/kernel](https://www.npmjs.com/package/@metaharness/kernel)
39(Rust-compiled WASM with a NAPI-RS native fallback) so the same code runs on
40every platform. The `@metaharness/*` packages are imported *dynamically* inside
41the commands that need them, so `guidance`/`--help` work with no dependencies
42installed.
43 
44### Darwin, router, flywheel
45 
46- **Darwin Mode** (`@metaharness/darwin`, devDependency) — `npm run evolve` /
47  `evolve:dry` mutates the harness's own config and keeps only measurable
48  improvements.
49- **Router** (`@metaharness/router`) — `src/router.ts` wires a real cost-optimal
50  `Router` (`qualityBar: 0.8`) over two model tiers. Its labelled examples are
51  illustrative seed data (see the file's honesty note), not measured eval-log
52  observations.
53- **Flywheel** (`@metaharness/flywheel`) — `src/flywheel.ts` wires the real
54  promotion loop (propose → evaluate → gate → promote, Ed25519-signed,
55  independently replayable) with a SYNTHETIC proposer/evaluator
56  (`dataSource: 'SYNTHETIC'`, no model call). A LIVE run needs a real Proposer
57  and Evaluator supplied by the operator — see the file's comments.
58 
59## Relationship to the crate
60 
61This harness assists development *on* the WiFi Veil crate; it does not replace the
62crate's own gates. The authoritative validation for a WiFi Veil change is still:
63 
64```bash
65cargo test
66cargo clippy --all-targets -- -D warnings
67```
68