From 739d3219e6f9e9be6378b562309783d371cfd4b6 Mon Sep 17 00:00:00 2001 From: ruv Date: Fri, 31 Jul 2026 00:36:18 -0400 Subject: [PATCH] docs(harness): add route/flywheel command guidance, ADR-286, publish status - .claude/commands/route.md and flywheel.md -- the two CLI subcommands added alongside darwin/router/flywheel wiring never got matching guidance files (unlike doctor/review-diff), so they weren't fully wired into the harness's own MCP tool listing. Added, following the existing pattern. - CLAUDE.md: note the crate + harness are both published now (crates.io v0.3.1, npm v0.1.0). - New ADR-286 documenting the harness's MetaHarness scaffold + the darwin/router/flywheel wiring decision, following the ADR-182/ADR-285 precedent (every harness in this repo gets one). - docs/adr/README.md: index rows for ADR-286 and the crate's ADR (287 -- see the next commit for the renumbering-from-283 story). --- ...i-densepose-sar-harness-via-metaharness.md | 45 +++++++++++++++++++ docs/adr/README.md | 4 +- .../.claude/commands/flywheel.md | 10 +++++ .../.claude/commands/route.md | 10 +++++ harness/wifi-densepose-sar/CLAUDE.md | 4 +- 5 files changed, 71 insertions(+), 2 deletions(-) create mode 100644 docs/adr/ADR-286-wifi-densepose-sar-harness-via-metaharness.md create mode 100644 harness/wifi-densepose-sar/.claude/commands/flywheel.md create mode 100644 harness/wifi-densepose-sar/.claude/commands/route.md diff --git a/docs/adr/ADR-286-wifi-densepose-sar-harness-via-metaharness.md b/docs/adr/ADR-286-wifi-densepose-sar-harness-via-metaharness.md new file mode 100644 index 00000000..aa4bef8a --- /dev/null +++ b/docs/adr/ADR-286-wifi-densepose-sar-harness-via-metaharness.md @@ -0,0 +1,45 @@ +# ADR-286: `wifi-densepose-sar-harness` — a MetaHarness minted via `vendor/metaharness` + +| Field | Value | +|-------|-------| +| **Status** | Accepted — implemented, **published** | +| **Date** | 2026-07-30 | +| **Parent** | ADR-287 (`wifi-densepose-sar`, the crate this harness assists development on) | +| **Relates to** | ADR-182 (`harness/ruview/`, the first MetaHarness-minted harness in this repo), ADR-285 (`harness/homecore/`, the WASM-first pattern this harness's `@metaharness/kernel` dependency follows) | +| **Published** | [`wifi-densepose-sar-harness` v0.1.0](https://www.npmjs.com/package/wifi-densepose-sar-harness) on npm (2026-07-31) | + +## 0. PROOF discipline + +Every claim below about what's "real" versus "illustrative"/"SYNTHETIC" is checked by a passing test in this harness's own suite (14 tests: 5 router + 5 flywheel + 4 install-smoke). Nothing here is asserted without a corresponding `__tests__/*.test.ts` file exercising it. + +## 1. Context + +`wifi-densepose-sar` (ADR-287) is a new, narrowly-scoped research crate. Rather than hand-roll a bespoke development-assistance setup for it, `vendor/metaharness` (the `ruvnet/metaharness` generator, vendored as a git submodule alongside this repo's other `vendor/*` submodules) was used to scaffold one directly: `npx metaharness analyze v2/crates/wifi-densepose-sar --scaffold wifi-densepose-sar-harness --host claude-code` recommended and generated `template: vertical:coding` with four agents (architect/implementer/reviewer/test-writer) and `doctor`/`review-diff` commands — the same generator that produced `harness/ruview/` (ADR-182) and `harness/homecore/` (ADR-285). + +The user's ask that shaped this ADR's scope was specific: wire in **darwin, router, and flywheel** — three complementary `@metaharness/*` packages the base scaffold doesn't include by default (only Darwin Mode ships built-in). + +## 2. Decision + +Land the scaffold at `harness/wifi-densepose-sar/`, and add real wiring for the three requested pieces, each as an actual npm dependency (not a stub, not a `try/catch` optional import): + +1. **`@metaharness/darwin`** (devDependency) — wired by the scaffold itself. `npm run evolve` (real sandbox) / `evolve:dry` (mock sandbox) mutates the harness's own operating config and keeps only measurably-improving changes. +2. **`@metaharness/router`** — `src/router.ts` wires a real `Router` (k-NN over labelled examples, cost-optimal selection against a quality bar) with two example model tiers (`cheap-tier` $1/MTok, `frontier-tier` $15/MTok). Exposed as a CLI command (`route `) with a matching `.claude/commands/route.md` guidance file. +3. **`@metaharness/flywheel`** — `src/flywheel.ts` wires the real `runFlywheelGenerations` promotion loop (propose → evaluate → gate → promote, Ed25519-signed, independently replayable via `verifyReplayBundle`) with a SYNTHETIC proposer/evaluator (`dataSource: 'SYNTHETIC'`, no live model call). Exposed as `flywheel [generations]` with a matching `.claude/commands/flywheel.md` guidance file. + +Every new CLI subcommand gets a `.claude/commands/.md` file, matching the pattern the base scaffold's `doctor`/`review-diff` already establish — the MCP tool listing (`mcp__wifi-densepose-sar-harness__*`) is derived from these, so a command without one isn't fully wired into the harness's own guidance surface even if the CLI itself works. + +## 3. What this explicitly is NOT + +- **Not evolving the crate.** Darwin/Flywheel mutate the harness's own operating policy (agent prompts, review checklist depth) — not `wifi-densepose-sar`'s Rust code or its runtime performance. Actually optimizing the crate (the incremental-phasor-rotation work, ADR-287 §7) was done directly, not through this harness's self-improvement loop. +- **Not a live routing/promotion system.** The router's labelled examples are illustrative seed data, not measured eval-log observations. The flywheel's proposer/evaluator are deterministic stand-ins, not a real model call or a real coding-task benchmark suite. Both are honestly labeled as such in their own source files and in this harness's `CLAUDE.md`. +- **Not manifest-verified.** `.harness/manifest.json`/`manifest.sha256` reflect the initial scaffold output and were not regenerated after adding `router.ts`/`flywheel.ts` — this scaffold has no `manifest:update` script (unlike `harness/homecore/`). Documented as a known gap in the harness's own README. + +## 4. A real bug the flywheel wiring found + +The first version of the SYNTHETIC evaluator returned a constant `noopRate`. `@metaharness/flywheel`'s default promotion gate requires `noopRate` to *strictly improve* generation over generation (one of its five conjunctive clauses) — a constant value, however good, fails that clause forever, so nothing could ever be promoted. Fixed by making `noopRate` actually respond to the (synthetic) policy content; every generation promotes now. Kept as a cautionary note in `src/flywheel.ts`'s comments: a flywheel evaluator with a frozen metric is silently broken, not silently fine. + +## 5. Consequences + +- 14 tests (5 router + 5 flywheel + 4 install-smoke), 0 failed; `npm run build` clean under strict TypeScript. +- Published to npm as `wifi-densepose-sar-harness` v0.1.0 — `npx wifi-densepose-sar-harness init` works from a cold install. +- No risk to any other harness or crate in this repo — this harness only reads/assists on `wifi-densepose-sar`, and its MCP server, memory namespace, and Claude Code plugin are scoped to its own name. diff --git a/docs/adr/README.md b/docs/adr/README.md index 6408d42a..11ca228c 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -9,7 +9,7 @@ Latest proposed decisions: - [ADR-264: Versioned wire protocol for RTL8720F CFR and Range-FFT reports](ADR-264-rtl8720f-radar-wire-protocol.md) - [ADR-263: Adopt RTL8720F 2.4 GHz FMCW radar as an optional RuView sensing platform](ADR-263-rtl8720f-2-4ghz-fmcw-radar-platform.md) -This folder contains 208 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project. (The index tables below list a curated subset per domain; see the directory listing for the full set.) +This folder contains 210 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project. (The index tables below list a curated subset per domain; see the directory listing for the full set.) ## Why ADRs? @@ -142,7 +142,9 @@ Statuses: **Proposed** (under discussion), **Accepted** (approved and/or impleme | [ADR-280](ADR-280-active-sensing-programmable-perception.md) | Active sensing & programmable perception control plane | Accepted (implemented) | | [ADR-281](ADR-281-ble-cs-delay-doppler-pose-factorization.md) | BLE Channel Sounding, delay-Doppler tensors, P3162 import, factorized pose | Accepted (implemented) | | [ADR-282](ADR-282-ruview-ecosystem-positioning.md) | Ecosystem positioning + mandatory L0–L5 evidence ladder | Accepted | +| [ADR-287](ADR-287-coherent-wideband-rf-tomography-crate.md) | `wifi-densepose-sar` — coherent wideband RF tomography research crate | Accepted (implemented, published) | | [ADR-285](ADR-285-homecore-wasm-first-metaharness.md) | WASM-first Homecore developer metaharness via `npx homecore` | Accepted (implemented and validated) | +| [ADR-286](ADR-286-wifi-densepose-sar-harness-via-metaharness.md) | `wifi-densepose-sar-harness` — MetaHarness with darwin/router/flywheel | Accepted (implemented, published) | --- diff --git a/harness/wifi-densepose-sar/.claude/commands/flywheel.md b/harness/wifi-densepose-sar/.claude/commands/flywheel.md new file mode 100644 index 00000000..1283e77e --- /dev/null +++ b/harness/wifi-densepose-sar/.claude/commands/flywheel.md @@ -0,0 +1,10 @@ +--- +description: "Run the SYNTHETIC @metaharness/flywheel self-improvement demo and report the lift curve." +--- + +Run the propose → evaluate → gate → promote loop and report what it found. + +1. Run `npm run build` first if `dist/flywheel.js` doesn't exist yet. +2. Run `wifi-densepose-sar-harness flywheel [generations]` (default 3 if omitted). +3. Report each generation's `primary` score and `delta`, the total promotions, and whether `verifyReplayBundle` passed. +4. State plainly: this run's `dataSource` is `SYNTHETIC` — the proposer and evaluator are deterministic stand-ins (see `src/flywheel.ts`'s honesty note), not a real model call or a real coding-task benchmark. Do not report its numbers as if they reflect real harness improvement. diff --git a/harness/wifi-densepose-sar/.claude/commands/route.md b/harness/wifi-densepose-sar/.claude/commands/route.md new file mode 100644 index 00000000..adc58958 --- /dev/null +++ b/harness/wifi-densepose-sar/.claude/commands/route.md @@ -0,0 +1,10 @@ +--- +description: "Route a 4-axis task embedding to the cost-optimal model tier via @metaharness/router." +--- + +Route one query to the cheapest model tier predicted to clear the quality bar. + +1. Run `npm run build` first if `dist/router.js` doesn't exist yet. +2. Run `wifi-densepose-sar-harness route ` — four 0..1 numbers scoring how much the query looks like each of those four shapes (see `src/router.ts` for the axis definitions). +3. Report the picked tier (`cheap-tier` or `frontier-tier`), its predicted quality, and whether it cleared the 0.8 quality bar. +4. Remind the user: the labelled examples behind this decision are illustrative seed data (see `src/router.ts`'s honesty note), not measured eval logs — the routing mechanism is real, the specific pick isn't backed by production data yet. diff --git a/harness/wifi-densepose-sar/CLAUDE.md b/harness/wifi-densepose-sar/CLAUDE.md index c3e4dd98..d27339c7 100644 --- a/harness/wifi-densepose-sar/CLAUDE.md +++ b/harness/wifi-densepose-sar/CLAUDE.md @@ -1,6 +1,6 @@ # wifi-densepose-sar-harness -Harness for wifi-densepose-sar +Harness for [wifi-densepose-sar](https://crates.io/crates/wifi-densepose-sar) (ADR-287) — the coherent wideband RF tomography research crate this harness assists development on. Both are published: the crate on crates.io, this harness itself as [`wifi-densepose-sar-harness`](https://www.npmjs.com/package/wifi-densepose-sar-harness) on npm. > Advanced Coding harness · domain: `software-engineering`. Generated with [create-agent-harness](https://github.com/ruvnet/agent-harness-generator). @@ -25,6 +25,8 @@ Harness for wifi-densepose-sar ## Commands +Each command below has a matching `.claude/commands/.md` guidance file — the MCP tool listing (`mcp__wifi-densepose-sar-harness__*`) is derived from these, so a new CLI subcommand isn't fully wired up until it has one too. + - `doctor` — Health-check the harness: kernel load, MCP wiring, memory backend, host adapter. - `review-diff` — Review the current working diff for correctness, security, and reuse. - `route ` — cost-optimal model routing via `@metaharness/router` (needs `npm run build` first).