# Claude Observations Plan

Reference source: `claude-observations.txt`

This file is a fact-checked implementation plan based on the numbered observations
in `claude-observations.txt`. It reflects the current worktree state on 2026-04-18,
not just the last committed `main`.

## Fact Check Summary

| Observation | Status | Fact Check | Planned Action |
|---|---|---|---|
| 1. `format_tv_key` duplicates normalized key mapping | Confirmed | `src/daemon/mod.rs` still has a 33-arm `format_tv_key` helper and one call site in the `SendKey` action detail path. `src/adapters/mod.rs` still has a separate `parse_normalized_tv_key` table and `TvKey` keeps `#[serde(rename_all = "kebab-case")]`. | Remove the duplicate reverse table. Preferred fix: add a canonical string conversion on `TvKey` and use it from the daemon response text. |
| 2. `DeviceRegistry::remove` duplicates `find` matching logic | Confirmed | `src/daemon/registry.rs` has `find()` with inline UUID/name matching and `remove()` with separate `matches_target(...)` logic. | Refactor `remove()` to reuse `find()` or otherwise share one target-matching implementation. Delete the duplicate matcher after the refactor. |
| 3. `parse_bool` is a no-value wrapper | Confirmed | `src/daemon/config.rs` still has `fn parse_bool(...) { parse_value(...) }` and uses it in `set_value(...)`. | Delete `parse_bool` and switch the bool assignments to `parse_value(...)`. |
| 4. HTTP API loops back through the Unix socket even though it is in-process | Completed locally on 2026-04-18 | Refactored `src/api/mod.rs` to call `daemon::execute_request(...)` directly and added an in-process HTTP regression test that succeeds without starting the daemon Unix socket server. | No further change needed unless follow-up regressions are found. |
| 5. `PROJECT_MAP.md` is stale about Milestone 5 / HTTP status | Stale in current worktree | In the current worktree, `PROJECT_MAP.md` is already locally updated to `Last updated: 2026-04-18` and `Phase: Milestone 6 in progress`. This observation was valid against an older snapshot, not the current tree. | No repo change needed for this item unless those local doc edits are reverted before commit. |
| 6. Missing cleanup for `node-compile-cache/` and `phantomjs/` | Partially confirmed | Neither directory exists in the current repo tree, but `.gitignore` does not currently list them. The observation appears archive-related rather than evidence of a current tracked repo problem. | Add preventive ignore entries later if desired. No tracked-file cleanup is needed unless those directories reappear. |
| 7. `get_value()` allocates a full `BTreeMap` for one lookup | Confirmed | `src/daemon/config.rs` still implements `get_value()` as `self.entries().remove(key)`. | Rewrite `get_value()` as a direct `match` over stable keys so it no longer allocates the full map for single-key reads. |
| 8. `roku_key_paths` unsupported-key intent is unclear | Confirmed | `src/adapters/roku/mod.rs` still falls through from valid `Ok(...)` arms into a bottom branch where `Stop`, `Skip`, `Power`, `PowerOn`, and `Options` are only used to build `InvalidKey(...)`. | Add a clarifying comment above the fall-through block. No behavior change needed. |
| 9. `RefreshAppsBody` optional `clear` handling can be simplified | Cosmetic | `src/api/mod.rs` still uses `body.map(|value| value.clear).unwrap_or(false)`. | Fold into a smaller expression while touching the HTTP module for higher-priority work. Do not treat this as a standalone task. |
| 10. Rust 2024 edition note | Informational only | `Cargo.toml` already uses `edition = "2024"`. No code issue is implied. | No repo change needed now. Keep the note in mind when CI is added so the toolchain is new enough. |

## Execution Order

The future implementation order should stay low-risk first and defer the heavier
HTTP refactor until the small cleanups are merged or at least locally stable.

1. Remove duplication and low-risk cleanup
   - Observation 3: delete `parse_bool`
   - Observation 8: add unsupported-key comment in `roku_key_paths`
   - Observation 9: simplify `RefreshAppsBody` boolean handling if already editing `src/api/mod.rs`

2. Remove duplicated matching / key-string tables
   - Observation 2: unify `DeviceRegistry` target matching
   - Observation 1: replace `format_tv_key` with one canonical `TvKey` string path
   - Observation 7: rewrite `get_value()` to avoid `entries()` allocation

3. Perform the medium-risk HTTP architecture cleanup
   - Observation 4: replace Unix-socket loopback in the HTTP API with direct `execute_request(...)`
   - Add focused regression coverage around HTTP handlers after this change because it changes the transport path, not just formatting

4. Preventive hygiene
   - Observation 6: add `.gitignore` entries for `node-compile-cache/` and `phantomjs/` if we want to harden against future archive/worktree leakage

## Constraints For Future Work

- Keep this work separate from the current uncommitted logging-related changes already in the worktree unless the user explicitly asks to batch them together.
- Do not assume all Claude observations are still valid against the live tree. Re-check each item immediately before implementation.
- Preserve current user-facing behavior where possible, especially for daemon/API error payloads and CLI help/output.