awesome-bookmarks/wifi-ruview
3
0
Fork 0
mirror of https://github.com/ruvnet/RuView.git synced 2026-06-02 00:58:56 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
f850d46e9a92d3af50f1c2415c7c61d87f51c882
wifi-ruview/CLAUDE.md
T
rUv 0d3d835bf8 feat(swarm): add ruview-swarm crate — drone swarm control system (ADR-148) (#862) 
* feat(swarm): add wifi-densepose-swarm crate implementing ADR-148 drone swarm control system

New crate `wifi-densepose-swarm` with hierarchical-mesh swarm topology,
Raft consensus, MAPPO MARL, CSI sensing integration, and ITAR-gated
coordination features. Closes 3 of 7 milestones (M1, M2, M5) with 5/5
ADR-148 SOTA performance targets met.

## Modules (45 source files, 14 modules)

- types: NodeId, DroneState, Position3D, SwarmTask, SwarmError, FailSafeState
- topology: Raft consensus (leader election, log replication, quorum), Gossip, Mesh
- formation: VirtualStructure, LeaderFollower, Reynolds flocking (itar-gated)
- planning: RRT-APF hybrid planner, 3-phase coverage, Bayesian grid, pheromone
- allocation: Auction + FNN bid scorer (itar-gated)
- sensing: CsiPayloadPipeline (Live/Synthetic/Replay), MultiViewFusion, OccWorldBridge
- marl: MAPPO actor (3-layer MLP), LocalObservation (64-dim), RewardCalculator, PPO loop
- security: MAVLink v2 HMAC-SHA256, UWB anti-spoofing, geofence, Remote ID, FHSS
- failsafe: 10-state onboard machine, GCS-independent safety transitions
- config: TOML SwarmConfig with SAR/inspection/agriculture/mine/demo/wi2sar_reference
- demo: SyntheticCsiGenerator, DemoScenario (SAR/open-field/mine)
- integration: FlightController trait, MAVLink dialect (50000-50005), SwarmSim
- orchestrator: SwarmOrchestrator wiring all subsystems end-to-end
- bench_support: Criterion fixture generators

## ITAR compliance

Swarming coordination features gated behind `itar-unrestricted` feature
per USML Category VIII(h)(12). Default build compiles clean stubs.

## Benchmark results (criterion, release mode)

- MARL actor inference: 3.3 µs (target ≤ 5 ms — 1,516× headroom)
- RRT-APF planning (100 iter): 0.043 ms (target < 300 ms — 6,946× headroom)
- MultiView CSI fusion (3 UAVs): 58.5 ns (target < 10 ms — 171,000× headroom)
- 3-view localization: 1.732 m (target ≤ 2 m — beats Wi2SAR SOTA)
- 4-drone SAR coverage (400×400 m): 223 s (target ≤ 240 s — PASS)

## Tests

- --no-default-features: 73/73 passing
- --features itar-unrestricted: 85/85 passing

Closes #861

Co-Authored-By: claude-flow <ruv@ruv.net>

* refactor(swarm): rename wifi-densepose-swarm → ruview-swarm

The swarm control system is a RuView-level capability (drone coordination,
Raft consensus, MARL) that operates above the wifi-densepose sensing layer
rather than being a sub-component of it. Rename aligns with the project
identity and separates coordination infrastructure from sensing modules.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(swarm): resolve all clippy warnings + add MARL convergence test

- planning/probability_grid: map_or(true,…) → is_none_or (clippy::unnecessary_map_or)
- planning/pheromone: &mut Vec<T> → &mut [T] on evaporate+deposit (clippy::ptr_arg)
- marl/observation: fix doc lazy-continuation warning on TOTAL line
- marl/trainer: manual Default impl → #[derive(Default)] + #[default] on Demo variant

Also adds test_marl_convergence_improves_mean_return: fills 64-transition
ReplayBuffer with mixed rewards (steps 0-31: negative, 32-63: positive),
runs ppo_update, asserts mean_return is finite and non-zero.

Result: 0 clippy warnings · 74/74 tests (default) · 86/86 (itar-unrestricted)

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(swarm): integrate Ruflo AI-agent capabilities into ruview-swarm

Adds a feature-gated Ruflo integration layer connecting ruview-swarm to the
claude-flow daemon's AgentDB, AIDefence, and SONA intelligence subsystems.
Default build is unaffected (all paths behind `Option<Box<dyn RufloBackend>>`).

## New module: src/ruflo/

- backend.rs: RufloBackend trait (9 async methods) + RufloError, MissionMemoryEntry,
  PatternEntry, MavlinkScanResult types (always compiled)
- mock_backend.rs: MockRufloBackend in-memory impl for testing (always compiled, 5 tests)
- http_backend.rs: HttpRufloBackend — JSON-RPC 2.0 → claude-flow daemon localhost:3000
  (gated behind `ruflo` feature, requires reqwest)
- mission_summary.rs: MissionSummary serializer with pattern description + confidence
  scoring from victim recall, coverage %, collision penalty (always compiled, 3 tests)

## 4 capability areas

1. MissionMemory   → memory_store / memory_search       (cross-mission victim memory)
2. PatternLearner  → agentdb_pattern-store / -search     (HNSW SONA trajectory patterns)
3. MavlinkDefence  → aidefence_is_safe / aidefence_scan  (scan MAVLink before accepting)
4. IntelligenceHooks → trajectory-start/step/end          (SONA learning loop)

## SwarmOrchestrator integration

- with_ruflo(backend): builder to attach a backend
- start_trajectory(task) / finish_trajectory(success, key): SONA mission lifecycle
- receive_peer_detection_checked(): AIDefence scan before accepting peer detections

## Cargo feature

`ruflo = ["dep:reqwest", "dep:serde_json"]` — optional, not in default

## Tests

- --no-default-features: 82/82 pass (8 new ruflo tests)
- --features ruflo,itar-unrestricted: 94/94 pass

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(swarm): M7 mission profiles with victim confirmation reports + pre-merge docs

Adds end-to-end mission runners producing structured MissionReport output,
and updates project docs (CHANGELOG, README, CLAUDE.md) per pre-merge checklist.

## M7 Mission Profiles (integration/mission_report.rs + swarm_sim.rs)

- MissionReport / VictimReport / SotaComparison types (serde-serializable)
- run_mission_with_report(): full mission → detailed report with per-victim
  localization error, fusion uncertainty, contributing drones, detection time
- run_inspection_mission(): leader-follower power-line corridor inspection
- run_mine_mission(): GPS-denied underground (2-drone, slow, UWB-only)
- SotaComparison embeds Wi2SAR baseline (5m / 810s) vs achieved metrics

## Docs (pre-merge checklist)

- CHANGELOG.md: ruview-swarm + Ruflo integration + performance entries
- README.md: ruview-swarm row
- CLAUDE.md: Key Rust Crates table row + ADR-148 in ADR list

## Tests
- --no-default-features: 86/86 pass
- --features ruflo,itar-unrestricted: 98/98 pass

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(swarm): convergence-assist for victim fusion + 5s Ruflo HTTP timeout

Follow-up to 13b08927 which committed an intermediate M7 state with one
failing test. This lands the M7 agent's convergence fixes and the security
review's timeout hardening.

## Fixes
- swarm_sim.rs: min-separation nudge before collision metric (0 collisions
  with staggered starts) + Phase-3 convergence assist that vectors the nearest
  idle peer toward a single-drone CSI contact so multi-view fusion can fire
- http_backend.rs: add 5s request timeout to reqwest client (security review
  Medium finding — a dead daemon would otherwise hang the swarm step loop)

## Security review verdict (HttpRufloBackend)
Safe to merge. No credentials in requests, serde_json prevents injection,
fail-open on daemon-down is documented and appropriate for SAR missions,
MAVLink passed as structured text (not raw bytes). Timeout fix applied.

## Tests
- --no-default-features: 87/87 pass
- --features ruflo,itar-unrestricted: 100/100 pass

Co-Authored-By: claude-flow <ruv@ruv.net>

* perf(swarm): add PPO training-throughput benchmark + fix bench crate-name imports

- bench_ppo_update: PPO update over 64-transition buffer — 244 µs median
- fix: bench imports referenced stale `wifi_densepose_swarm` (pre-rename),
  corrected to `ruview_swarm` so the bench target compiles

M6 benchmark suite now 5/5 compiling and running. Tests unchanged: 87/100.

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(swarm): real Candle autodiff PPO + A-MAPPO role attention + GPU training (M4)

Replaces the finite-difference PPO placeholder with a real GPU-capable Candle
0.9 autodiff trainer, adds A-MAPPO heterogeneous-role attention, a runnable
training binary, and right-sized GCP/local launch scripts. This is the unlock
that makes "GPU long training cycles" actually mean something — the previous
ppo_update did no gradient descent.

## Real autodiff PPO (feature `train`, optional `cuda`)
- candle_ppo.rs: CandleActorCritic (64→128→64 MLP + action/value heads +
  learnable log_std), CandlePpoConfig, CandleTrainer with GAE and a genuine
  optimizer.backward_step over the network. select_device() picks CUDA when
  built --features cuda and a GPU is present, else CPU.
- Verified: 5-episode CPU smoke run shows value_loss 12643→12375 (critic
  actually learning); safetensors checkpoint saved. Placeholder never moved weights.

## A-MAPPO heterogeneous-role attention (role_attention.rs, always compiled)
Addresses the four sensor-vs-relay edge cases:
- relay attention floor (prevents collapse — relays produce no CSI)
- role-segmented sensor/relay attention pools (variable neighbor cardinality)
- sensor-gated triangulation-geometry penalty (protects 3-view fusion baseline,
  ADR-148 §4.2 — relays not dragged into triangulation geometry)
- one-hot role embeddings for keys

## Training binary
- src/bin/train_marl.rs (required-features=["train"], excluded from default build)
- CLI: --episodes --drones --profile --steps --checkpoint-dir --checkpoint-every
- Wires CandleTrainer to the SwarmOrchestrator rollout loop; GAE + PPO update
  per episode; periodic safetensors checkpoints

## Right-sized launch (scripts/gcp/)
- provision_marl.sh: g2-standard-16 (1× L4, 16 vCPU, ~$1.40/hr) — NOT the
  $29/hr A100×8 box. MARL is rollout-bound not matmul-bound; ~21× cheaper.
- run_marl_train.sh: GCP rsync + train + checkpoint pull
- run_marl_train_local.sh: local RTX 5080, $0
- A100×8 provision_training.sh left for OccWorld (which saturates the GPUs)

## Tests
- --no-default-features: 91/91 (87 + 4 role_attention)
- --features train: 96/96 (+ 5 candle_ppo, incl. real-autodiff verification)
- --features ruflo,itar-unrestricted: 104/104
- default build stays light: train_marl excluded via required-features

Co-Authored-By: claude-flow <ruv@ruv.net>

* docs(adr-148): mark M4 complete — real GPU autodiff training; overall 98%

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(swarm): training visualizer — JSONL telemetry + self-contained HTML viewer

Adds an offline, dependency-free visualization for the drone training system:
a top-down swarm replay synced with training-metric curves, fed by a JSONL
telemetry log the trainer emits. No server, no build step, no CDN.

## Telemetry recorder (integration/telemetry.rs, always compiled, no new deps)
- TelemetryRecorder writes newline-delimited JSON: one `meta` (profile, area,
  ground-truth victims), many `step` (per-tick drone x/y/heading/battery/detection
  + coverage%), and per-episode `episode` (mean_return, policy_loss, value_loss).
- Written by hand (no serde_json) so it stays in the default build; 2 tests.

## train_marl telemetry flags
- `--telemetry FILE` writes the log; `--telemetry-episode N` selects which
  episode's spatial steps to record (metrics recorded for all episodes).

## Visualizer (viz/swarm_viz.html — single file, vanilla JS + canvas)
- LEFT: top-down replay — heading-oriented drone triangles (cyan/lime on
  detection), victim markers, growing coverage heatmap, detection pulse rings,
  play/pause/scrub/speed controls + live coverage/detection readout.
- RIGHT: three autoscaled line charts (mean return, policy loss, value loss)
  over episodes, hand-drawn (no chart library).
- Loads via file picker/drag-drop or auto-fetches the bundled sample; dark
  drone-ops theme; graceful degradation on file:// CORS.
- viz/sample_telemetry.jsonl: real 30-episode / 4-drone / 400×400 m run
  (value_loss 20052→7154 — visible critic learning). Parses 1 meta / 60 step / 30 episode.

## Usage
  cargo run --release -p ruview-swarm --features train,cuda --bin train_marl -- \
      --episodes 5000 --telemetry run.jsonl
  open v2/crates/ruview-swarm/viz/swarm_viz.html  # load run.jsonl

Tests unchanged (91 default / 96 train / 104 ruflo+itar); telemetry adds 2.

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(swarm): selectable flight + self-learning patterns, wired into training + viz

Adds multiple flight/coverage-optimization strategies and self-learning
strategies, selectable from the trainer, and fixes drone clustering — the
demo sweep now covers 36% of the area (was ~0.9%) with 4 disjoint strips.

## Flight patterns (planning/patterns.rs) — `FlightPattern`
- PartitionedLawnmower (new default): area split into per-drone strips → no
  overlap, coverage scales ~linearly with swarm size (clustering fix)
- Boustrophedon (baseline), Spiral, Pheromone (stigmergic), PotentialField,
  LevyFlight. from_str/name/all + next_target(&PatternContext).

## Self-learning patterns (marl/learning.rs) — `LearningPattern`
- Mappo (CTDE centralized critic), Ippo (independent, jamming-robust),
  MappoCuriosity (count-based intrinsic novelty), MetaRl (MAML fast-adapt).
- CuriosityModule (visit_bonus = beta/sqrt(count), novelty decays on revisit),
  MetaAdapter (base + fast-weights, reset_fast/consolidate), shaped_reward().

## Trainer wiring (bin/train_marl.rs)
- --flight-pattern {boustrophedon|partitioned|spiral|pheromone|potential|levy}
- --learn-pattern  {mappo|ippo|curiosity|meta}
- Rollout now moves each drone per the selected FlightPattern (PatternContext
  with visited trail + live peers), curiosity-shapes the reward, and logs
  CTDE vs independent. Telemetry meta profile carries the pattern labels so the
  viewer header shows `flight=… · learn=…`.

## Verification
- Browser pass (viz at localhost:8777): partitioned run renders 4 distinct
  serpentine coverage bands, header shows the patterns, final coverage 36.3%,
  scrubber/speed/playback work, ZERO console errors. Screenshot confirmed.
- Regenerated viz/sample_telemetry.jsonl: 1 meta / 120 step / 30 episode,
  coverage 0.9% → 36.3%.

## Tests
- --no-default-features: 103/103 (was 91; +6 patterns +6 learning)
- --features train: 108/108

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(swarm): add flight-pattern telemetry presets for the visualizer

5 loadable presets (verified browser-distinct, physics-ordered coverage):
pheromone ~44% > potential ~40% > partitioned 36% > spiral ~13% > levy ~5%.
Load any in viz/swarm_viz.html to compare flight strategies without retraining.

Co-Authored-By: claude-flow <ruv@ruv.net>

* chore(swarm): clippy-clean + publish guard for ruview-swarm

- ruview-swarm src is now 0 clippy warnings across default/train/full feature
  sets (derive Default, targeted allows for intentional from_str + bounded
  casts + borrow-required index loops; removed redundant unsigned .max(0))
- publish = false until PR merges, internal path-deps publish in order, and
  ITAR (USML VIII(h)(12)) export sign-off — prevents accidental public publish

Tests unchanged: 103 default / 108 train / 116 ruflo+itar / 120 full+train.
(6 remaining clippy warnings are pre-existing in dependency wifi-densepose-core,
 out of scope for this crate.)

Co-Authored-By: claude-flow <ruv@ruv.net>

* ci(swarm): add ruview-swarm CI guard

Path-scoped guard for v2/crates/ruview-swarm/** (ADR-148). Complements the
main ci.yml (which only runs the default workspace tests):
- feature-matrix tests: default / train / ruflo+itar / full+train
- clippy -D warnings --no-deps (crate-own code only; dep warnings don't gate)
- train_marl bin builds under 'train' AND is excluded from the default build
- ITAR/publish guards: publish=false present, itar-unrestricted never in default

All steps verified locally green before commit.

Co-Authored-By: claude-flow <ruv@ruv.net>
2026-05-30 16:00:59 -04:00

18 KiB
Raw Blame History

Claude Code Configuration — WiFi-DensePose + Claude Flow V3

Project: wifi-densepose

WiFi-based human pose estimation using Channel State Information (CSI). Dual codebase: Python v1 (v1/) and Rust port (v2/).

Key Rust Crates

Crate Description
wifi-densepose-core Core types, traits, error types, CSI frame primitives
wifi-densepose-signal SOTA signal processing + RuvSense multistatic sensing (16 modules)
wifi-densepose-nn Neural network inference (ONNX, PyTorch, Candle backends)
wifi-densepose-train Training pipeline with ruvector integration + ruview_metrics
wifi-densepose-mat Mass Casualty Assessment Tool — disaster survivor detection
wifi-densepose-hardware ESP32 aggregator, TDM protocol, channel hopping firmware
wifi-densepose-ruvector RuVector v2.0.4 integration + cross-viewpoint fusion (5 modules)
wifi-densepose-wasm WebAssembly bindings for browser deployment
wifi-densepose-cli CLI tool (wifi-densepose binary)
wifi-densepose-sensing-server Lightweight Axum server for WiFi sensing UI
wifi-densepose-wifiscan Multi-BSSID WiFi scanning (ADR-022)
wifi-densepose-vitals ESP32 CSI-grade vital sign extraction (ADR-021)
nvsim Deterministic NV-diamond magnetometer pipeline simulator (ADR-089) — standalone leaf, WASM-ready
vendor/rvcsi (submodule) rvCSI — edge RF sensing runtime (ADR-095/096): 9 crates (rvcsi-core/-dsp/-events/-adapter-file/-adapter-nexmon/-ruvector/-runtime/-node/-cli). Lives in its own repo (github.com/ruvnet/rvcsi), vendored here under vendor/rvcsi, published to crates.io as rvcsi-* 0.3.x and to npm as @ruv/rvcsi. Not a v2/ workspace member — depend on the published crates (or the submodule's crates/rvcsi-* paths). Normalized CsiFrame/CsiWindow/CsiEvent schema, validate-before-FFI, reusable DSP, typed confidence-scored events, the napi-c Nexmon shim (real nexmon_csi .pcap from a Raspberry Pi 5 / 4 / 3B+ — BCM43455c0), the napi-rs SDK, the rvcsi CLI, a Claude Code plugin.
ruview-swarm Drone swarm control system (ADR-148) — hierarchical-mesh topology, Raft consensus, MARL, CSI sensing payload, MAVLink/PX4 compat, Ruflo AI-agent integration

RuvSense Modules (signal/src/ruvsense/)

Module Purpose
multiband.rs Multi-band CSI frame fusion, cross-channel coherence
phase_align.rs Iterative LO phase offset estimation, circular mean
multistatic.rs Attention-weighted fusion, geometric diversity
coherence.rs Z-score coherence scoring, DriftProfile
coherence_gate.rs Accept/PredictOnly/Reject/Recalibrate gate decisions
pose_tracker.rs 17-keypoint Kalman tracker with AETHER re-ID embeddings
field_model.rs SVD room eigenstructure, perturbation extraction
tomography.rs RF tomography, ISTA L1 solver, voxel grid
longitudinal.rs Welford stats, biomechanics drift detection
intention.rs Pre-movement lead signals (200-500ms)
cross_room.rs Environment fingerprinting, transition graph
gesture.rs DTW template matching gesture classifier
adversarial.rs Physically impossible signal detection, multi-link consistency
cir.rs ADR-134 CSI→CIR via ISTA L1 sparse recovery (NeumannSolver warm-start)
calibration.rs ADR-135 empty-room baseline (Welford amplitude + von Mises phase, drift trigger)

Cross-Viewpoint Fusion (ruvector/src/viewpoint/)

Module Purpose
attention.rs CrossViewpointAttention, GeometricBias, softmax with G_bias
geometry.rs GeometricDiversityIndex, Cramer-Rao bounds, Fisher Information
coherence.rs Phase phasor coherence, hysteresis gate
fusion.rs MultistaticArray aggregate root, domain events

RuVector v2.0.4 Integration (ADR-016 complete, ADR-017 proposed)

All 5 ruvector crates integrated in workspace:

  • ruvector-mincut → metrics.rs (DynamicPersonMatcher) + subcarrier_selection.rs
  • ruvector-attn-mincut → model.rs (apply_antenna_attention) + spectrogram.rs
  • ruvector-temporal-tensor → dataset.rs (CompressedCsiBuffer) + breathing.rs
  • ruvector-solver → subcarrier.rs (sparse interpolation 114→56) + triangulation.rs
  • ruvector-attention → model.rs (apply_spatial_attention) + bvp.rs

Architecture Decisions

43 ADRs in docs/adr/ (ADR-001 through ADR-043). Key ones:

  • ADR-014: SOTA signal processing (Accepted)
  • ADR-015: MM-Fi + Wi-Pose training datasets (Accepted)
  • ADR-016: RuVector training pipeline integration (Accepted — complete)
  • ADR-017: RuVector signal + MAT integration (Proposed — next target)
  • ADR-024: Contrastive CSI embedding / AETHER (Accepted)
  • ADR-027: Cross-environment domain generalization / MERIDIAN (Accepted)
  • ADR-028: ESP32 capability audit + witness verification (Accepted)
  • ADR-029: RuvSense multistatic sensing mode (Proposed)
  • ADR-030: RuvSense persistent field model (Proposed)
  • ADR-031: RuView sensing-first RF mode (Proposed)
  • ADR-032: Multistatic mesh security hardening (Proposed)
  • ADR-148: Drone swarm control system / ruview-swarm (In Progress)

Supported Hardware

Device Port Chip Role Cost
ESP32-S3 (8MB flash) COM9 (ruvzen, was COM7) Xtensa dual-core WiFi CSI sensing node ~$9
ESP32-S3 SuperMini (4MB) — Xtensa dual-core WiFi CSI (compact) ~$6
ESP32-C6 + Seeed MR60BHA2 COM12 (ruvzen, was COM4) RISC-V + 60 GHz FMCW mmWave HR/BR/presence + WiFi CSI ~$15
HLK-LD2410 — 24 GHz FMCW Presence + distance ~$3

Not supported: ESP32 (original), ESP32-C3 — single-core, can't run CSI DSP pipeline.

Build & Test Commands (this repo)

# Rust — full workspace tests (1,031+ tests, ~2 min)
cd v2
cargo test --workspace --no-default-features

# Rust — single crate check (no GPU needed)
cargo check -p wifi-densepose-train --no-default-features

# Python — deterministic proof verification (SHA-256)
python archive/v1/data/proof/verify.py

# Python — test suite
cd archive/v1 && python -m pytest tests/ -x -q

ESP32 Firmware Build (Windows — Python subprocess required)

# Build 8MB firmware (real WiFi CSI mode, no mocks)
# See CLAUDE.local.md for the full Python subprocess command
# Key: must strip MSYSTEM env vars for ESP-IDF v5.4 on Git Bash

# Build 4MB firmware
cp sdkconfig.defaults.4mb sdkconfig.defaults
# then same build process

# Flash to COM7
# [python, idf_py, '-p', 'COM7', 'flash']

# Provision WiFi
python firmware/esp32-csi-node/provision.py --port COM7 \
  --ssid "YourWiFi" --password "secret" --target-ip 192.168.1.20

# Monitor serial
python -m serial.tools.miniterm COM7 115200

Firmware Release Process

  1. Build 8MB from sdkconfig.defaults.template (no mock)
  2. Build 4MB from sdkconfig.defaults.4mb (no mock)
  3. Save 6 binaries: esp32-csi-node.bin, bootloader.bin, partition-table.bin, ota_data_initial.bin, esp32-csi-node-4mb.bin, partition-table-4mb.bin
  4. Tag: git tag v0.X.Y-esp32 && git push origin v0.X.Y-esp32
  5. Release: gh release create v0.X.Y-esp32 <binaries> --title "..." --notes-file ...
  6. Verify on real hardware (COM7) before publishing
  7. CRITICAL: Always test with real WiFi CSI, not mock mode — mock missed the Kconfig threshold bug

Crate Publishing Order

Crates must be published in dependency order:

  1. wifi-densepose-core (no internal deps)
  2. wifi-densepose-vitals (no internal deps)
  3. wifi-densepose-wifiscan (no internal deps)
  4. wifi-densepose-hardware (no internal deps)
  5. wifi-densepose-signal (depends on core)
  6. wifi-densepose-nn (no internal deps, workspace only)
  7. wifi-densepose-ruvector (no internal deps, workspace only)
  8. wifi-densepose-train (depends on signal, nn)
  9. wifi-densepose-mat (depends on core, signal, nn)
  10. wifi-densepose-wasm (depends on mat)
  11. wifi-densepose-sensing-server (depends on wifiscan)
  12. wifi-densepose-cli (depends on mat)

Validation & Witness Verification (ADR-028)

After any significant code change, run the full validation:

# 1. Rust tests — must be 1,031+ passed, 0 failed
cd v2
cargo test --workspace --no-default-features

# 2. Python proof — must print VERDICT: PASS
cd ..
python archive/v1/data/proof/verify.py

# 3. Generate witness bundle (includes both above + firmware hashes)
bash scripts/generate-witness-bundle.sh

# 4. Self-verify the bundle — must be 7/7 PASS
cd dist/witness-bundle-ADR028-*/
bash VERIFY.sh

If the Python proof hash changes (e.g., numpy/scipy version update):

# Regenerate the expected hash, then verify it passes
python archive/v1/data/proof/verify.py --generate-hash
python archive/v1/data/proof/verify.py

Witness bundle contents (dist/witness-bundle-ADR028-<sha>.tar.gz):

  • WITNESS-LOG-028.md — 33-row attestation matrix with evidence per capability
  • ADR-028-esp32-capability-audit.md — Full audit findings
  • proof/verify.py + expected_features.sha256 — Deterministic pipeline proof
  • test-results/rust-workspace-tests.log — Full cargo test output
  • firmware-manifest/source-hashes.txt — SHA-256 of all 7 ESP32 firmware files
  • crate-manifest/versions.txt — All 15 crates with versions
  • VERIFY.sh — One-command self-verification for recipients

Key proof artifacts:

  • archive/v1/data/proof/verify.py — Trust Kill Switch: feeds reference signal through production pipeline, hashes output
  • archive/v1/data/proof/expected_features.sha256 — Published expected hash
  • archive/v1/data/proof/sample_csi_data.json — 1,000 synthetic CSI frames (seed=42)
  • docs/WITNESS-LOG-028.md — 11-step reproducible verification procedure
  • docs/adr/ADR-028-esp32-capability-audit.md — Complete audit record

Branch

Default branch: main Active feature branch: ruvsense-full-implementation (PR #77)

Behavioral Rules (Always Enforced)

  • Do what has been asked; nothing more, nothing less
  • NEVER create files unless they're absolutely necessary for achieving your goal
  • ALWAYS prefer editing an existing file to creating a new one
  • NEVER proactively create documentation files (*.md) or README files unless explicitly requested
  • NEVER save working files, text/mds, or tests to the root folder
  • Never continuously check status after spawning a swarm — wait for results
  • ALWAYS read a file before editing it
  • NEVER commit secrets, credentials, or .env files

File Organization

  • NEVER save to root folder — use the directories below
  • docs/adr/ — Architecture Decision Records (43 ADRs)
  • docs/ddd/ — Domain-Driven Design models
  • v2/crates/ — Rust workspace crates (15 crates)
  • v2/crates/wifi-densepose-signal/src/ruvsense/ — RuvSense multistatic modules (14 files)
  • v2/crates/wifi-densepose-ruvector/src/viewpoint/ — Cross-viewpoint fusion (5 files)
  • v2/crates/wifi-densepose-hardware/src/esp32/ — ESP32 TDM protocol
  • firmware/esp32-csi-node/main/ — ESP32 C firmware (channel hopping, NVS config, TDM)
  • archive/v1/src/ — Python source (core, hardware, services, api)
  • archive/v1/data/proof/ — Deterministic CSI proof bundles
  • .claude-flow/ — Claude Flow coordination state (committed for team sharing)
  • .claude/ — Claude Code settings, agents, memory (committed for team sharing)

Project Architecture

  • Follow Domain-Driven Design with bounded contexts
  • Keep files under 500 lines
  • Use typed interfaces for all public APIs
  • Prefer TDD London School (mock-first) for new code
  • Use event sourcing for state changes
  • Ensure input validation at system boundaries

Project Config

  • Topology: hierarchical-mesh
  • Max Agents: 15
  • Memory: hybrid
  • HNSW: Enabled
  • Neural: Enabled

Pre-Merge Checklist

Before merging any PR, verify each item applies and is addressed:

  1. Rust tests pass — cargo test --workspace --no-default-features (1,031+ passed, 0 failed)
  2. Python proof passes — python archive/v1/data/proof/verify.py (VERDICT: PASS)
  3. README.md — Update platform tables, crate descriptions, hardware tables, feature summaries if scope changed
  4. CLAUDE.md — Update crate table, ADR list, module tables, version if scope changed
  5. CHANGELOG.md — Add entry under [Unreleased] with what was added/fixed/changed
  6. User guide (docs/user-guide.md) — Update if new data sources, CLI flags, or setup steps were added
  7. ADR index — Update ADR count in README docs table if a new ADR was created
  8. Witness bundle — Regenerate if tests or proof hash changed: bash scripts/generate-witness-bundle.sh
  9. Docker Hub image — Only rebuild if Dockerfile, dependencies, or runtime behavior changed
  10. Crate publishing — Only needed if a crate is published to crates.io and its public API changed
  11. .gitignore — Add any new build artifacts or binaries
  12. Security audit — Run security review for new modules touching hardware/network boundaries

Build & Test

# Build
npm run build

# Test
npm test

# Lint
npm run lint
  • ALWAYS run tests after making code changes
  • ALWAYS verify build succeeds before committing

Security Rules

  • NEVER hardcode API keys, secrets, or credentials in source files
  • NEVER commit .env files or any file containing secrets
  • Always validate user input at system boundaries
  • Always sanitize file paths to prevent directory traversal
  • Run npx @claude-flow/cli@latest security scan after security-related changes

Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS

  • All operations MUST be concurrent/parallel in a single message
  • Use Claude Code's Task tool for spawning agents, not just MCP
  • ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
  • ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
  • ALWAYS batch ALL file reads/writes/edits in ONE message
  • ALWAYS batch ALL Bash commands in ONE message

Swarm Orchestration

  • MUST initialize the swarm using CLI tools when starting complex tasks
  • MUST spawn concurrent agents using Claude Code's Task tool
  • Never use CLI tools alone for execution — Task tool agents do the actual work
  • MUST call CLI tools AND Task tool in ONE message for complex work

3-Tier Model Routing (ADR-026)

Tier Handler Latency Cost Use Cases
1 Agent Booster (WASM) <1ms $0 Simple transforms (var→const, add types) — Skip LLM
2 Haiku ~500ms $0.0002 Simple tasks, low complexity (<30%)
3 Sonnet/Opus 2-5s $0.003-0.015 Complex reasoning, architecture, security (>30%)
  • Always check for [AGENT_BOOSTER_AVAILABLE] or [TASK_MODEL_RECOMMENDATION] before spawning agents
  • Use Edit tool directly when [AGENT_BOOSTER_AVAILABLE]

Swarm Configuration & Anti-Drift

  • ALWAYS use hierarchical topology for coding swarms
  • Keep maxAgents at 6-8 for tight coordination
  • Use specialized strategy for clear role boundaries
  • Use raft consensus for hive-mind (leader maintains authoritative state)
  • Run frequent checkpoints via post-task hooks
  • Keep shared memory namespace for all agents
npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized

Swarm Execution Rules

  • ALWAYS use run_in_background: true for all agent Task calls
  • ALWAYS put ALL agent Task calls in ONE message for parallel execution
  • After spawning, STOP — do NOT add more tool calls or check status
  • Never poll TaskOutput or check swarm status — trust agents to return
  • When agent results arrive, review ALL results before proceeding

V3 CLI Commands

Core Commands

Command Subcommands Description
init 4 Project initialization
agent 8 Agent lifecycle management
swarm 6 Multi-agent swarm coordination
memory 11 AgentDB memory with HNSW search
task 6 Task creation and lifecycle
session 7 Session state management
hooks 17 Self-learning hooks + 12 workers
hive-mind 6 Byzantine fault-tolerant consensus

Quick CLI Examples

npx @claude-flow/cli@latest init --wizard
npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
npx @claude-flow/cli@latest swarm init --v3-mode
npx @claude-flow/cli@latest memory search --query "authentication patterns"
npx @claude-flow/cli@latest doctor --fix

Available Agents (60+ Types)

Core Development

coder, reviewer, tester, planner, researcher

Specialized

security-architect, security-auditor, memory-specialist, performance-engineer

Swarm Coordination

hierarchical-coordinator, mesh-coordinator, adaptive-coordinator

GitHub & Repository

pr-manager, code-review-swarm, issue-tracker, release-manager

SPARC Methodology

sparc-coord, sparc-coder, specification, pseudocode, architecture

Memory Commands Reference

# Store (REQUIRED: --key, --value; OPTIONAL: --namespace, --ttl, --tags)
npx @claude-flow/cli@latest memory store --key "pattern-auth" --value "JWT with refresh" --namespace patterns

# Search (REQUIRED: --query; OPTIONAL: --namespace, --limit, --threshold)
npx @claude-flow/cli@latest memory search --query "authentication patterns"

# List (OPTIONAL: --namespace, --limit)
npx @claude-flow/cli@latest memory list --namespace patterns --limit 10

# Retrieve (REQUIRED: --key; OPTIONAL: --namespace)
npx @claude-flow/cli@latest memory retrieve --key "pattern-auth" --namespace patterns

Quick Setup

claude mcp add claude-flow -- npx -y @claude-flow/cli@latest
npx @claude-flow/cli@latest daemon start
npx @claude-flow/cli@latest doctor --fix

Claude Code vs CLI Tools

  • Claude Code's Task tool handles ALL execution: agents, file ops, code generation, git
  • CLI tools handle coordination via Bash: swarm init, memory, hooks, routing
  • NEVER use CLI tools as a substitute for Task tool agents

Support

Reference in New Issue View Git Blame Copy Permalink