diff options
| -rw-r--r-- | .agent/code-map.md | 7 | ||||
| -rw-r--r-- | .agent/config.md | 3 | ||||
| -rw-r--r-- | .agent/review-intent-reality.md | 114 |
3 files changed, 122 insertions, 2 deletions
diff --git a/.agent/code-map.md b/.agent/code-map.md index eb2f564..1a36542 100644 --- a/.agent/code-map.md +++ b/.agent/code-map.md @@ -359,8 +359,11 @@ CI (`android.yml`) triggers only on pushes to `main`. Firebase App Distribution ## 8. Context Tips & Gotchas ### Navigation / GPS -- `DeviceGpsProvider` uses `FusedLocationProviderClient`. External GPS comes via NMEA TCP/UDP through `NmeaStreamManager` → `NmeaParser` → `GpsProvider` interface. -- GPS fix is stale after 10 s — `MainViewModel` shows red "No GPS" banner. +- `LocationService` (foreground service) uses `FusedLocationProviderClient` for Android GPS. External GPS comes via NMEA TCP/UDP through `NmeaStreamManager` → `NmeaParser`, emitted on `LocationService.nmeaGpsPositionFlow`. +- `LocationService.recomputeBestPosition()` fuses NMEA + Android GPS: prefers NMEA if < 5 s old, falls back to Android. Result is `bestPosition: StateFlow<GpsPosition?>`. +- `locationFlow: SharedFlow<GpsPosition>(replay=1)` carries raw Android fixes. **`replay=1` means new subscribers immediately receive the last cached position regardless of age — there is no staleness expiry.** Consumers must check `gpsData.timestampMs` if they care about age. +- `DeviceGpsProvider` implements `GpsProvider` and has a `fixLostRunnable` (10 s timeout), but is **dead code** — it is never instantiated. `LocationService` does not use the `GpsProvider` interface. There is no "No GPS" banner. +- Background location: `throttleLocationIfIdle()` (called on `onPause`) sends `ACTION_STOP_UPDATES` to stop `fusedLocationClient` when neither recording nor anchor-watch is active. `restoreLocationMode()` (called on `onResume`) restarts appropriate mode. ### NMEA - `NmeaStreamManager` handles connection lifecycle (reconnect on failure). Don't manage socket lifecycle elsewhere. diff --git a/.agent/config.md b/.agent/config.md index 56d9df5..376cd89 100644 --- a/.agent/config.md +++ b/.agent/config.md @@ -14,6 +14,7 @@ This is the primary source of truth for all AI agents working on **Nav**. These | `mission.md` | **Mission & Values** — Strategic goals and agent personality. | | `narrative.md` | **Background** — Historical context and evolution of the project. | | `preferences.md` | **User Prefs** — Living record of user-specific likes/dislikes. | +| `review-intent-reality.md` | **Audit Prompt** — Structured review to find gaps between documented intent and implemented reality. Run after major merges or when a regression reveals a code-map error. | ## 2. Branch Policy — MANDATORY SESSION START ACTION @@ -48,3 +49,5 @@ The repo ships a pre-commit hook in `scripts/git-hooks/pre-commit` that hard-blo 1. **Continuous Capture:** Agents MUST proactively update the files in ".agent/" as new decisions, patterns, or user preferences are revealed. 2. **No Stale Instructions:** If a workflow or technical standard evolves, the agent is responsible for reflecting that change in the Master Rulebook immediately. 3. **Worklog Integrity:** The ".agent/worklog.md" must be updated at the start and end of EVERY session. +4. **Code-Map Accuracy:** `code-map.md` must describe what the code **does**, not what was intended. If a refactor changes a class's role, removes a feature, or leaves dead code, update `code-map.md` in the same commit. Never leave a known-wrong entry — a wrong code-map is worse than no code-map. +5. **Intent-Reality Audit:** After any significant merge or refactor, check whether existing code-map entries, comments, and `design.md` still reflect reality. When they don't, fix them immediately. For a full audit, run the prompt in `review-intent-reality.md`. 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"`. |