Skip to content

docs: calibration guide + trust/engine-error diagnostics (closes #1456) - #1457

Merged
ruvnet merged 1 commit into
mainfrom
docs/1456-calibration-and-trust-demotion
Jul 28, 2026
Merged

docs: calibration guide + trust/engine-error diagnostics (closes #1456)#1457
ruvnet merged 1 commit into
mainfrom
docs/1456-calibration-and-trust-demotion

Conversation

@ruvnet

@ruvnet ruvnet commented Jul 28, 2026

Copy link
Copy Markdown
Owner

Summary

Closes #1456 (follow-up documentation gap tracked from #1401). Two new operator-facing docs, both grounded in the actual Rust source (not ADR aspirational prose) — every specific number/threshold below is cited with a file:line and was spot-checked against source before this PR was opened.

docs/calibration-guide.md

  • The empty-room baseline has a hard, enforced minimum of 600 frames (DEFAULT_MIN_FRAMES, wifi-densepose-signal/src/ruvsense/calibration.rs:48) — calibrate fails outright below it, it doesn't degrade silently.
  • Documents the real per-anchor quality gate thresholds used by enroll (AnchorQualityGate), and that train-room only requires a non-empty anchor list — a partial anchor set silently produces a bank missing whichever specialists lacked their prerequisite anchors.
  • Pets: honest finding — PresenceSpecialist has no size/species discrimination at all, purely amplitude-variance/mean-shift thresholding. Documented as an open limitation, not glossed over.
  • Baseline conditions: explains why a steady interferer (HVAC, fan) gets correctly absorbed into "empty" via Welford statistics, but also flags that ADR-135's described drift_score/BaselineDrift staleness system does not exist in the actual code — only a cruder baseline_id-mismatch check in bank.rs is real.

docs/trust-and-engine-errors.md

  • Traces engine_error_count and the separate, non-sticky demoted flag to their exact trigger conditions in engine_bridge.rs / wifi-densepose-engine.
  • Confirms /health/ready and /api/v1/status share a handler and expose a trust block, but plainly states the real diagnostic gap: no per-cause error breakdown is exposed over the API — the rate-limited log line is the closest thing today.
  • Documents the real recovery path for persistent clock-drift demotion (WDP_GUARD_INTERVAL_US, from issue Make multistatic guard_interval_us configurable (hardcoded 5000 µs causes permanent trust demotion with 2 ESP32-S3 nodes) #1049) and that engine_error_count has no reset besides a process restart.
  • On the reporter's Hugging-Face-converted-model angle: states plainly that --convert-model and the engine/trust cycle are separate code paths with no call-through found — no invented causal link.

Both docs are added to the README documentation table.

Test plan

  • Docs-only change — confirmed via git status/diff that nothing outside docs/ and README.md was touched.
  • Spot-checked the load-bearing claims (DEFAULT_MIN_FRAMES = 600, engine_error_count increment/no-reset, WDP_GUARD_INTERVAL_US, demote_one/self.demoted = trust.demoted) directly against source before opening this PR.
  • No code changes, so no test/build impact expected — CI should be green on docs alone.

🤖 Generated with Claude Code

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

Closes the two documentation gaps from #1456 (follow-up to #1401):

- docs/calibration-guide.md: what calibrate/enroll/train-room actually
  enforce, grounded in v2/crates/wifi-densepose-calibration and
  wifi-densepose-cli source (not just ADR-135/151 aspirational prose).
  Covers the hard 600-frame baseline minimum, per-anchor quality gate
  thresholds, the unsolved pet/small-motion presence-detection gap, and
  what the empty-room baseline capture actually needs (steady vs silent).
  Flags that ADR-135's drift_score/BaselineDrift staleness system is not
  implemented in code — only bank.rs's baseline_id STALE check is real.

- docs/trust-and-engine-errors.md: exact trigger conditions for
  engine_error_count vs the separate, non-sticky `demoted` privacy-class
  flag, where both are exposed (/health/ready and /api/v1/status share a
  handler), the real diagnostic gap (no per-cause breakdown, log line is
  the closest thing), the WDP_GUARD_INTERVAL_US recovery path for
  persistent clock-drift demotion, and an honest "no code path found"
  answer on whether a converted HuggingFace model explains engine errors.

Also adds both docs to the README documentation table. No code changes.
@ruvnet
ruvnet merged commit e606297 into main Jul 28, 2026
21 checks passed
@ruvnet
ruvnet deleted the docs/1456-calibration-and-trust-demotion branch July 28, 2026 04:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs gap: calibration guidance (empty-room meaning, duration) + trust/engine-error demotion diagnostics (from #1401)

1 participant