From ef72c00a027e19d68ab5a8e9d86d808ab3570b69 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 24 May 2026 20:07:03 -0400 Subject: [PATCH] docs(adr-118): root README Documentation table BFLD row (337/337 GREEN) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Iter 51. PR-readiness pivot iter #2. Adds BFLD to the workspace-root README.md Documentation table — closes pre-merge checklist item #3 (README.md update if scope changed). GitHub renders this; new contributors / operators browsing ruvnet/RuView see the entry on landing. Added (in README.md, top-level Documentation table): - New row right after the Home Assistant + Matter row, linking to v2/crates/wifi-densepose-bfld/README.md (iter-49 crate README). - Summary covers: * 3 type-enforced structural invariants (raw BFI never exits / in-RAM-only embedding / cross-site cryptographically impossible) * Full operator surface (BfldPipeline, BfldPipelineHandle, SoulMatchOracle) * MQTT topic router + HA-DISCO + availability + LWT * 3 operator HA blueprints * Two runnable examples * eclipse-mosquitto:2 CI service container * 327+ tests - Per-ADR links: 118 (umbrella), 119 (frame), 120 (privacy class), 121 (risk scoring), 122 (HA/Matter), 123 (capture path) - Research dossier pointer: docs/research/BFLD/ (11 files, 13,544 words) Added (in v2/crates/wifi-densepose-bfld/tests/root_readme_link.rs): - 5 named tests via include_str!: root_readme_links_to_bfld_crate_readme root_readme_mentions_bfld_acronym_and_full_name root_readme_cites_all_six_bfld_adrs (per-ADR substring check) root_readme_points_at_research_bundle root_readme_documents_three_structural_invariants_in_summary ("raw BFI never exits", "in-RAM-only", "cross-site" — three invariants surfaced in the short table summary) ADR-124 status (iter step 0 sibling check): - docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md unchanged at 431 lines. SENSE-BRIDGE scope remains orthogonal. ACs progressed: - Pre-merge checklist item #3 (CLAUDE.md) — root README updated to point at the new crate. Operator discovery path now reaches BFLD from the GitHub repo landing page in 1 click. - ADR-118 §2.1 documentation surface — discovery path complete: GitHub README → crate README → operator examples → ADRs → research dossier. All hops covered by include_str + link tests. Test config: - cargo test --no-default-features → 101 passed (root_readme_link cfg-out) - cargo test → 337 passed (332 + 5) Out of scope (next iter target): - Pre-merge checklist remaining: user-guide.md update (#6) if new CLI flags / setup steps, witness bundle regeneration (#8). External- resource-gated work (KIT BFId, Pi5/Nexmon) still skipped. Co-Authored-By: claude-flow --- README.md | 1 + .../tests/root_readme_link.rs | 65 +++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 v2/crates/wifi-densepose-bfld/tests/root_readme_link.rs diff --git a/README.md b/README.md index 91ab923c..43de8306 100644 --- a/README.md +++ b/README.md @@ -594,6 +594,7 @@ Verify the plugin structure: `bash plugins/ruview/scripts/smoke.sh`. Full detail | [User Guide](docs/user-guide.md) | Step-by-step guide: installation, first run, API usage, hardware setup, training | | [Build Guide](docs/build-guide.md) | Building from source (Rust and Python) | | [**Home Assistant + Matter Integration**](docs/integrations/home-assistant.md) | **Works with Home Assistant** via MQTT auto-discovery + **Works with Matter** (Apple Home / Google Home / Alexa / SmartThings) — full entity catalog, 3 starter blueprints, Lovelace dashboards, privacy mode, threshold tuning ([ADR-115](docs/adr/ADR-115-home-assistant-integration.md)). | +| [**BFLD — Beamforming Feedback Layer for Detection**](v2/crates/wifi-densepose-bfld/README.md) | New privacy-gated WiFi sensing layer that measures + structurally prevents identity leakage from 802.11ac/ax Beamforming Feedback Information. Three type-enforced invariants (raw BFI never exits node, identity embedding is in-RAM-only, cross-site correlation cryptographically impossible via per-site BLAKE3 keyed hash + daily rotation). Ships full operator surface (`BfldPipeline`, `BfldPipelineHandle`, Soul Signature `SoulMatchOracle` integration), MQTT topic router + HA-DISCO + availability + LWT, 3 operator HA blueprints, two runnable examples, eclipse-mosquitto:2 CI service container. 327+ tests. [ADR-118](docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md) umbrella + sub-ADRs [119](docs/adr/ADR-119-bfld-frame-format-and-wire-protocol.md)/[120](docs/adr/ADR-120-bfld-privacy-class-and-hash-rotation.md)/[121](docs/adr/ADR-121-bfld-identity-risk-scoring.md)/[122](docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md)/[123](docs/adr/ADR-123-bfld-capture-path-nexmon-and-esp32.md). Research dossier: [`docs/research/BFLD/`](docs/research/BFLD/) (11 files, 13,544 words). | | [Semantic Primitives — Precision/Recall](docs/integrations/semantic-primitives-metrics.md) | Per-primitive F1 on the held-out paired-capture set: someone-sleeping, possible-distress, room-active, elderly-inactivity-anomaly, meeting, bathroom, fall-risk, bed-exit, no-movement, multi-room. | | [Claude Code / Codex Plugin](plugins/ruview/README.md) | The `ruview` plugin + marketplace — skills, `/ruview-*` commands, agents, and the Codex prompt mirror | | [Architecture Decisions](docs/adr/README.md) | 96 ADRs — why each technical choice was made, organized by domain (hardware, signal processing, ML, platform, infrastructure) | diff --git a/v2/crates/wifi-densepose-bfld/tests/root_readme_link.rs b/v2/crates/wifi-densepose-bfld/tests/root_readme_link.rs new file mode 100644 index 00000000..ca20a22a --- /dev/null +++ b/v2/crates/wifi-densepose-bfld/tests/root_readme_link.rs @@ -0,0 +1,65 @@ +//! Validate the workspace-root `README.md` Documentation table cites the +//! BFLD crate. crates.io won't show this, but new contributors browsing +//! `ruvnet/RuView` on GitHub will — the entry is the primary discovery +//! path for operators looking for "WiFi sensing privacy layer". + +#![cfg(feature = "std")] + +const ROOT_README: &str = include_str!("../../../../README.md"); + +#[test] +fn root_readme_links_to_bfld_crate_readme() { + assert!( + ROOT_README.contains("v2/crates/wifi-densepose-bfld/README.md"), + "root README must link to the BFLD crate README from the Documentation table", + ); +} + +#[test] +fn root_readme_mentions_bfld_acronym_and_full_name() { + assert!( + ROOT_README.contains("BFLD"), + "root README must mention the BFLD acronym", + ); + assert!( + ROOT_README.contains("Beamforming Feedback Layer for Detection"), + "root README must expand the BFLD acronym at least once", + ); +} + +#[test] +fn root_readme_cites_all_six_bfld_adrs() { + for adr in ["ADR-118", "ADR-119", "ADR-120", "ADR-121", "ADR-122", "ADR-123"] { + assert!( + ROOT_README.contains(adr), + "root README must cite {adr} so the discovery path is intact", + ); + } +} + +#[test] +fn root_readme_points_at_research_bundle() { + assert!( + ROOT_README.contains("docs/research/BFLD/"), + "root README must point at the BFLD research dossier", + ); +} + +#[test] +fn root_readme_documents_three_structural_invariants_in_summary() { + // The doc-table summary is short, but it should still mention the + // three I1/I2/I3 invariants since they're the single most operator- + // visible property of BFLD. + assert!( + ROOT_README.contains("raw BFI never exits"), + "root README must mention invariant I1 in the BFLD summary", + ); + assert!( + ROOT_README.contains("in-RAM-only") || ROOT_README.contains("in-RAM only"), + "root README must mention invariant I2 in the BFLD summary", + ); + assert!( + ROOT_README.contains("cross-site"), + "root README must mention invariant I3 in the BFLD summary", + ); +}