rouse-context/docs/audit.md
monkopedia-coder 7b6fe5e0b5
Split test-coverage-audit.md into a verified half and a dated one (#654) (#691)
Closes #654

`docs/test-coverage-audit.md` is split into a verified inventory and a fenced
2026-04-06 snapshot. The inventory half is re-derived against `61c84b93`: per-module
counts with the command that reproduces them (288 Kotlin test classes, 21 Rust
integration test files), every named class confirmed to resolve, and a new
**Subject ships?** column separating "this test is green" from "its subject runs in
production".

The row that motivated the issue is `TokenStoreTest` — accurate in every word, and
still supporting a false inference, because it exercises `InMemoryTokenStore` while
production binds `RoomTokenStore`. `RoomTokenStoreTest`, which covers the shipped
path, had never been listed. That row is the one a reader could not have caught from
the date on the file.

The other bad rows failed differently, and review corrected the diagnosis: they were
stale, not fictional. `NotificationAdapter` and its test, the `:integration-tests`
module, the `:health` module, and the relay wake-endpoint test were all real when the
audit named them, and were deleted or moved by a cleanup wave in April 2026. Each
removed row now states that the subject is absent at `61c84b93` and names the commit
that removed it, rather than asserting it never existed. Exactly one row was ever
fictional — `TunnelConnectionStateMachineTest` — and it keeps its own distinct
grounds.

Note the count chain this document has been through, since it is the argument for the
shape: the bridge section read "2 test classes" when there were five; #684 corrected
it to "1 test class" when there were four; it is now four, printed from a command
rather than maintained by hand. A hand-maintained inventory drifts, and it drifts
again in the act of being corrected.

`docs/audit.md` records the file as repaired rather than deleted, and carries the same
stale-not-fictional framing.

Docs only. No code, no behaviour change. `docs/workflow.md:317` is deliberately left
alone; it belongs to the separate annotate-don't-rewrite case.

Reviewed-by: monkopedia-reviewer
2026-09-02 23:55:32 -04:00

16 KiB
Raw Permalink Blame History

Documentation audit — 2026-04-14

Scope: every .md under docs/, plus top-level README.md and BLOCKERS.md. Also audited HTML files under docs/ since the issue called them out. Out of scope: .claude/ rules, KDoc in source, inline code comments.

Totals: 24 markdown files inventoried (23 under docs/ or repo root) + 3 HTML indexes + icon/screenshot PNGs.

  • Current: 8
  • Partially stale / needs update: 8
  • Rewrite (either for docs/user/ or fresh engineering doc): 2
  • Delete / archive: 4
  • Not docs (HTML/images in docs/): 2 directories (plus one HTML sitting directly under docs/notifications/)

Module-level README.md / BLOCKERS.md files: none exist inside modules. Top-level BLOCKERS.md is the only one.


Per-doc findings

README.md (repo root)

  • Length: 93 lines
  • Audience: contributor / user (top-level landing)
  • Accuracy: current. Module table lists :core:bridge, outreach, usage, notifications — all present in the tree. Integration list matches what's shipped. URL form brave-falcon.abc123.rousecontext.com/health/mcp is the legacy format, not the per-integration form shipped in valid_secrets. Minor stale detail.
  • User-facing content?: Yes, partially. It's the main marketing/what-is-it surface.
  • Recommendation: update. Fix the URL example to match the shipped per-integration-hostname scheme (brave-health.cool-penguin...). Otherwise keep as-is. Consider splitting "marketing intro" into docs/user/index.md once the user docs tree exists.

BLOCKERS.md (repo root)

  • Length: 190 lines
  • Audience: historical
  • Accuracy: stale. References T-12 scaffolding blockers (no :api module, no ktlint plugin), an April 2026 FCM-wake flow that "couldn't connect because ACME is stubbed" — all long since resolved (relay uses a real ACME client, :api module exists, ktlint/detekt are configured).
  • User-facing content?: No.
  • Recommendation: delete. This was a handoff note between agents during early implementation; everything described here is fixed or superseded by GitHub Issues now.

docs/workflow.md

  • Length: 704 lines
  • Audience: historical
  • Accuracy: stale. Declares "the relay does not exist yet" and lays out phases 0–6 as a DAG. All phases are shipped. Talks about mcp-core, mcp-health, tunnel flat modules that were renamed long ago.
  • User-facing content?: No.
  • Recommendation: delete. This was the original implementation roadmap. GitHub Issues is now the tracking system (per project memory). If a historical record is wanted, preserve by tagging the last commit that contains it and then delete from main.

docs/test-coverage-audit.md

  • Length: ~1230 lines
  • Audience: engineering
  • Accuracy: split, deliberately. Repaired under #654 on 2026-09-02. The inventory half was rebuilt and verified against 61c84b93 — every count is reproducible from a printed command and every named test class was confirmed to exist. Everything from "Gap Analysis" onward is now explicitly fenced as the 2026-04-06 snapshot, with inline annotations where a gap has since been closed.
  • User-facing content?: No.
  • Recommendation: keep, in its current split shape. The earlier recommendation was to delete, on the grounds that a hand-maintained inventory drifts. That is still true of an exhaustive one, which is why the repair replaced the per-class enumeration with per-module counts plus the command that reproduces them, and names only the classes the document itself cites. #654 also added a Subject ships? column: a ✓ used to mean only that a test existed and passed, which credited production with coverage of a class that never runs. Note that most of the bad rows were ordinary staleness of exactly the kind this entry already described: the April 2026 cleanup wave (#124, #125, #303, and the removal of the orphaned :integration-tests module) deleted the code they named, and nobody updated the audit. Only the TokenStore row failed the other way, staying accurate while supporting a false inference. That one is what #654 is actually about, and it is the one a reader could not have caught from the date on the file.

docs/security.md

  • Length: 237 lines
  • Audience: user (despite being described as "engineering-focused" in the issue — the prose reads as a user-facing trust explanation: "Your phone's data never touches our servers", trust model, what-you-trust lists). Some sections (certificate architecture, renewal windows) are implementation detail.
  • Accuracy: mostly current. Describes per-integration hostnames, ACME DNS-01, mTLS, OAuth 2.1 with PKCE — all shipped. References docs/security-audit-2026-04-07.md and docs/security-decisions.md.
  • User-facing content?: Yes, strongly.
  • Recommendation: rewrite for docs/user/security.md per #119. Keep the implementation-detail parts (certificate architecture, renewal windows, rate limit tables) in a separate engineering doc (docs/engineering/security.md or keep at docs/security.md). Trust model + what-you-trust should go user-facing.

docs/security-audit-2026-04-07.md

  • Length: 39 lines
  • Audience: engineering / historical
  • Accuracy: partially stale. Lists 23 findings. Many criticals (redirect URI validation, PKCE format, encrypted storage) were scheduled for "Week 1" and should be verified as addressed.
  • User-facing content?: No.
  • Recommendation: keep, but update. Annotate each finding with its resolution status (fixed / accepted per security-decisions.md / still open). Without status, it misleads readers into thinking all 23 are still unmitigated.

docs/security-decisions.md

  • Length: 40 lines
  • Audience: engineering
  • Accuracy: current. Companion to security-audit-2026-04-07.md — records which findings were accepted as risk. Cross-references are valid.
  • User-facing content?: No.
  • Recommendation: keep as-is. Extend as new decisions are made.

docs/self-hosting.md

  • Length: 234 lines
  • Audience: contributor (users forking and running their own deployment)
  • Accuracy: current. Describes Cloudflare DNS, Firebase setup, keystore generation, -Pdomain= parameterization, relay systemd unit. Checked: relay_hostname + base_domain fields exist in relay/src/config.rs; keystore guidance aligns with project rules.
  • User-facing content?: Partial — "sophisticated user/contributor" not "end user".
  • Recommendation: keep, with a minor pass. Candidate to move into docs/user/self-hosting.md or docs/contributor/self-hosting.md when that tree exists.

docs/design/overall.md

  • Length: 737 lines
  • Audience: engineering
  • Accuracy: mostly current but long. Early sections (system architecture, identity model, Firestore schema, end-to-end flows) match shipped behavior. Later parts are a massive test-case list (items 165–274) that overlaps test-coverage-audit.md and the actual test files — that part has drifted.
  • User-facing content?: No — design detail.
  • Recommendation: update. Keep the architecture/flow prose. Cut the embedded test-case enumeration (lines ~590–730) — it's not authoritative since the real tests diverge. Add a pointer to test classes instead.

docs/design/android-app.md

  • Length: 377 lines
  • Audience: engineering
  • Accuracy: partially stale. Module map is missing :core:bridge, :outreach, :usage — all shipped modules. McpIntegration interface sketch matches what exists in :api.
  • User-facing content?: No.
  • Recommendation: update. Reconcile module list with the actual project structure. Low effort.

docs/design/relay.md

  • Length: 336 lines
  • Audience: engineering
  • Accuracy: mostly current. Mux frame format, SNI routing, ACME bootstrap match the code.
  • User-facing content?: No.
  • Recommendation: keep, minor update pass. Verify subdomain-lookup caching behavior still matches implementation (skim only; flagged as "may have drifted; needs deeper review").

docs/design/relay-api.md

  • Length: 769 lines
  • Audience: engineering (API reference)
  • Accuracy: mostly current. Endpoints /register, /renew, /wake/:subdomain, /rotate-secret, /ws, /status all exist under relay/src/api/. No /request_subdomain mention though — that endpoint does exist in code. Likely minor drift.
  • User-facing content?: No (API doc for integrators / contributors).
  • Recommendation: update. Add /request-subdomain, cross-check field names against current request/response structs, confirm error code table is accurate. May have drifted; needs deeper review.

docs/design/tunnel-client.md

  • Length: 264 lines
  • Audience: engineering
  • Accuracy: mostly current. KMP structure, mux client responsibilities, FCM dispatch (wake vs renew), state machine all match shipped code. Claim "No reconnect during active streams" may conflict with auto-reconnect-with-backoff behavior added later — flagged as possible drift.
  • User-facing content?: No.
  • Recommendation: update. Minor reconciliation on reconnect behavior.

docs/design/ui.md

  • Length: 633 lines
  • Audience: engineering
  • Accuracy: partially stale. Screen enumeration (Welcome, Dashboard, etc.) and state model are mostly right. Some screens (e.g. Onboarding as banner vs full screen) evolved per issues like #5 and the overnight plan's non-blocking-onboarding goal. May have drifted; needs a deeper review against current AppNavigation + Screen composables.
  • User-facing content?: No.
  • Recommendation: update. Could be worth a sweep that cross-checks against actual nav graph and Screen files (per the "verify rendered path" memory rule).

docs/design/per-integration-hostnames.md

  • Status: deleted (post-ship proposal). Shipped behavior is documented in docs/design/relay-api.md and docs/design/overall.md § Per-integration hostnames.

docs/design/secret-prefix-bot-rejection.md

  • Status: deleted. Superseded by per-integration-hostnames; the shipped routing-key design lives in docs/design/relay-api.md and docs/design/overall.md.

docs/design/notifications-integration.md

  • Length: 70 lines
  • Audience: engineering
  • Accuracy: current (short design doc for the notifications module). Tools listed (list_active_notifications, search_notification_history, etc.) match what the integration exposes.
  • User-facing content?: No.
  • Recommendation: keep.

docs/design/outreach-integration.md

  • Length: 72 lines
  • Audience: engineering
  • Accuracy: current. Matches the :outreach module (launch_app, open_link, copy_to_clipboard, DND tools).
  • User-facing content?: No.
  • Recommendation: keep.

docs/design/usage-integration.md

  • Length: 51 lines
  • Audience: engineering
  • Accuracy: current. Matches :usage module tools.
  • User-facing content?: No.
  • Recommendation: keep.

docs/design/health-connect-expansion.md

  • Length: 59 lines
  • Audience: engineering (proposal/expansion)
  • Accuracy: partially current. RecordTypeRegistry exists in :health. Verify shipped tool names against HealthConnectMcpServer (may still expose the old get_steps alongside generic query, or may have fully migrated).
  • User-facing content?: No.
  • Recommendation: update. Quick pass to mark shipped vs still-planned record types.

Non-markdown under docs/

docs/notifications/index.html (+ icon_*.png)

  • What it is: A standalone HTML notification catalog / design gallery (renders all notification variants for review), using local icon PNGs.
  • Accuracy: Unknown in terms of whether the icons still match shipped notification channels. Not referenced from any markdown/code under the repo.
  • Recommendation: move out of docs/ into design-assets/ or tools/notification-preview/. docs/ should not contain loose HTML design tools — they won't make sense when the docs tree is published.

docs/auth-pages/*.html

  • What it is: Rendered gallery of OAuth auth-page states (approved / denied / expired / waiting / index). Built by AuthPageGalleryTest per test-coverage-audit.md.
  • Recommendation: keep, or move to app/src/test/resources/ since it's test-generated output, not a doc.

docs/screenshots/index.html

  • What it is: Gallery of the current app/screenshots/*.png roborazzi outputs (dark/light pairs across the whole UI). Live and useful.
  • Recommendation: keep. The four standalone docs/screenshot_*.png files that paired with device-test-report.md were deleted on 2026-04-25 along with the report; docs/screenshots/index.html is a separate artifact and references app/screenshots/* instead.

Summary punch list

  • Delete: BLOCKERS.md, docs/workflow.md. docs/test-coverage-audit.md was struck from this list on 2026-09-02: repaired and re-verified under #654 rather than deleted. Done 2026-04-25: docs/overnight-plan-2.md, docs/e2e-status.md, docs/device-test-report.md, and the four docs/screenshot_*.png files paired with that report. Done (post-ship): docs/design/secret-prefix-bot-rejection.md, docs/design/per-integration-hostnames.md — superseded by docs/design/relay-api.md + docs/design/overall.md. docs/screenshots/index.html is kept (it indexes app/screenshots/*, not the deleted PNGs).
  • Rewrite for docs/user/: docs/security.md → split into docs/user/security.md (trust model, what-you-trust, what-ai-can't-do) and keep the implementation-detail parts under docs/engineering/security.md (or keep current path).
  • Move out of docs/ tree: docs/notifications/index.html + its icon_*.png files (they're a design asset, not docs). Optionally move docs/auth-pages/*.html to test resources.
  • Update:
    • README.md — fix the URL example to the shipped per-integration hostname format.
    • docs/security-audit-2026-04-07.md — annotate each of the 23 findings with current status.
    • docs/design/overall.md — drop the embedded test-case list (items 165–274) in favor of a pointer to test classes; keep architecture prose.
    • docs/design/android-app.md — reconcile module map with :core:bridge, :outreach, :usage.
    • docs/design/relay-api.md — add /request-subdomain, verify field names and error codes match code. Needs deeper review.
    • docs/design/tunnel-client.md — reconcile reconnect behavior with auto-reconnect implementation.
    • docs/design/ui.md — deeper review against current nav graph and Screen composables; mark any dead-code screens.
    • docs/design/health-connect-expansion.md — mark shipped record types.
  • Keep as-is:
    • docs/self-hosting.md (candidate for docs/contributor/ move).
    • docs/security-decisions.md.
    • docs/design/relay.md (minor review recommended).
    • docs/design/notifications-integration.md.
    • docs/design/outreach-integration.md.
    • docs/design/usage-integration.md.

Gaps (user-facing content that should exist but doesn't)

  • No docs/user/ tree at all yet (gated on #119).
  • No user-facing getting-started / install guide (today lives implicitly in README.md status line).
  • No user-facing "how to enable an integration" walkthrough.
  • No user-facing FAQ on data retention, audit review, revoking access.
  • No user-facing explanation of subdomain rotation and its cooldown.

These would populate the docs/user/ tree alongside the security rewrite.