1 files changed, 114 insertions, 0 deletions
diff --git a/.agent/review-intent-reality.md b/.agent/review-intent-reality.md
new file mode 100644
index 0000000..7df10f2
--- /dev/null
+++ b/.agent/review-intent-reality.md
@@ -0,0 +1,114 @@
+# Intent-vs-Reality Review
+
+**Purpose:** Find all places where documented intent, comments, or code-map descriptions diverge from what the code actually does. Run this whenever a significant refactor lands, before merging a long-running branch, or whenever a regression reveals a code-map inaccuracy.
+
+**How to run:** paste the prompt below into a new agent session with access to the repo. It is intentionally exhaustive — expect 30–60 min of analysis.
+
+---
+
+## Prompt
+
+You are auditing the Nav Android codebase for gaps between **documented intent** and **implemented reality**. A gap is any case where a comment, doc file, code-map entry, or TODO describes behavior that differs from what the code actually does.
+
+Work through each category below. For each finding, report:
+- **File and line** (or doc file + section)
+- **What it claims** (quote the doc/comment)
+- **What the code does** (cite the relevant lines)
+- **Severity**: `MISLEADING` (wrong, will cause future bugs), `STALE` (was true, no longer is), or `ASPIRATIONAL` (planned but not built)
+
+### Category 1 — Code-map vs implementation
+
+Read `.agent/code-map.md` sections 3 (Source Package Map) and 8 (Context Tips & Gotchas). For every class or behavior mentioned:
+
+1. Verify the class exists at the stated path.
+2. Verify the described role matches the actual implementation.
+3. Flag any class listed with a role that has been superseded or is dead code.
+
+Pay special attention to:
+- Classes listed under `gps/` — `DeviceGpsProvider` has historically been misrepresented
+- The "Navigation / GPS" gotcha section — descriptions of flow and staleness behavior
+- Any mention of flows, StateFlows, or SharedFlows — check `replay` values and whether subscribers actually receive stale data
+- Any mention of UI features (banners, dialogs, buttons) — verify they exist in layouts and are wired up
+
+### Category 2 — Dead code with documented intent
+
+Search for code that is defined but never instantiated or called. These represent features that were planned, partially built, or left behind after a refactor:
+
+1. Run: find all classes implementing an interface — check if any implementation is never constructed anywhere (grep for `= MyClass(` and `MyClass(` across all Kotlin files).
+2. Look specifically at:
+   - `gps/GpsProvider.kt` and its implementations
+   - Any `Handler` with a posted `Runnable` that looks like a timeout/watchdog
+   - Any `companion object` constant named `*_TIMEOUT_MS` or `*_THRESHOLD_MS` — verify the timeout is actually used
+3. For each dead class/method, check git log to understand if it was once wired up and was removed in a refactor (use `git log --all -S 'ClassName'` to find commits that removed references).
+
+### Category 3 — Comments that describe the wrong behavior
+
+Scan for inline comments that assert behavior (`// GPS updates every 1 Hz`, `// always fresh`, `// cleared on pause`, `// foreground only`, etc.) and verify the code around them matches the claim:
+
+1. Search for `// TODO` entries — for each one, determine if the TODO was actually completed elsewhere (the code may have been fixed but the comment not removed).
+2. Search for comments referencing specific class names, method names, or behaviors — verify those classes/methods/behaviors still exist with the described properties.
+3. Look for comments in `MainActivity.kt`, `LocationService.kt`, and `MainViewModel.kt` specifically — these are the highest-churn files.
+
+### Category 4 — Architectural invariants not enforced
+
+Read `.agent/code-map.md` section 5 (Key Architectural Invariants). For each invariant:
+
+1. Verify the invariant holds in the current code.
+2. If it was intended to be enforced by a specific mechanism (e.g., `@Synchronized`, a guard variable, a specific flow), verify that mechanism is actually in place.
+3. Flag any invariant that is stated as a rule but has no enforcement — these are regression risks.
+
+Current invariants to check:
+- Track storage source-of-truth = GPX/SAF (Room is read-cache only)
+- `getExternalFilesDir()` never used for user data
+- `NavLogger` as primary debug tool (not just Android `Log`)
+- MOB button always visible and non-dismissible
+- `InMemoryLogbookRepository` has `@Synchronized` on save/getAll/reload
+- `VoiceLogFragment` passes both `onSelect` and `onReport` to `SavedTrackAdapter`
+- MapLibre speed-color uses `Expression.step()` not `Expression.get("color")`
+- NMEA wind data is apparent, converted to true in `PerformanceViewModel`
+- All display values go through `UnitPrefs`
+
+### Category 5 — Design doc vs shipped code
+
+Read `.agent/design.md`. For any feature described as "implemented" or in a "completed" state:
+
+1. Verify the feature exists in the code.
+2. Verify the implementation matches the described design (API shape, data flow, UI layout).
+3. Flag features described as in-progress that appear to have been abandoned without a code-map update.
+
+### Category 6 — Worklog vs current state
+
+Read `.agent/worklog.md` section "Recently Completed". For each completed item:
+
+1. Spot-check that the described change is actually present in the code.
+2. Look for cases where a "completed" item was later reverted or partially undone by a subsequent merge (use `git log --all --oneline -- <file>` to trace history).
+
+---
+
+## Output format
+
+Group findings by category. Use this structure:
+
+```
+## [Category N] — [Category name]
+
+### Finding: [short title]
+- **Doc claim**: "[exact quote]" — `file:line`
+- **Code reality**: [what the code actually does] — `file:line`
+- **Severity**: MISLEADING / STALE / ASPIRATIONAL
+- **Suggested fix**: [one sentence — update the doc, delete the dead code, or implement the feature]
+```
+
+End with a **Summary** section: total findings by severity, and the top 3 highest-risk gaps (most likely to cause future bugs or agent confusion).
+
+---
+
+## After the review
+
+For each `MISLEADING` finding: fix the code-map or comment immediately in the same session. Do not leave the session with any known-wrong documentation.
+
+For `ASPIRATIONAL` findings: add a note to `.agent/worklog.md` backlog if the feature is still wanted, or delete the dead code if it is not.
+
+For `STALE` findings: update the documentation to match current reality.
+
+Commit all documentation fixes as a single commit: `"docs(agent): intent-reality audit — correct N misleading entries"`.