refactor(cleanup): delete dead codec_keyboard.py duplicate (A-8)

AGENTS.md

@@ -54,7 +54,7 @@ skills/                      71 built-in skill modules
 docs/                        API.md, MCP_HTTP_SETUP.md, CONTEXT_REPORT.md, design docs
 ```
 
-Other engine modules (`codec_overlays`, `codec_metrics`, `codec_logging`, `codec_gdocs`, `codec_google_auth`, `codec_cdp`, `codec_llm_proxy`, `codec_retry`, `codec_alerts`, `codec_search`, `codec_textassist`, `codec_keyboard`, `codec_watcher`, `codec_watchdog`) are internal helpers — read them when you need them, but they're not part of the navigation surface for an agent making structural changes.
+Other engine modules (`codec_overlays`, `codec_metrics`, `codec_logging`, `codec_gdocs`, `codec_google_auth`, `codec_cdp`, `codec_llm_proxy`, `codec_retry`, `codec_alerts`, `codec_search`, `codec_textassist`, `codec_watcher`, `codec_watchdog`) are internal helpers — read them when you need them, but they're not part of the navigation surface for an agent making structural changes. (Keyboard handling — wake word, F13 toggle, F18 voice, double-tap — lives **inline in `codec.py`** in the `codec` PM2 process; the old standalone `codec_keyboard.py` was deleted as a dead duplicate per A-8.)
 
 ## 3. Agent + Crew runtime
 

CONTRIBUTING.md

@@ -55,9 +55,8 @@ Drop it in `~/.codec/skills/` — CODEC loads it on restart.
 ## Project Structure
 
 ```
-codec.py              — Entry point (imports modules)
+codec.py              — Entry point + inline keyboard listener (wake word, F13/F18, double-tap)
 codec_config.py       — Configuration and constants
-codec_keyboard.py     — Keyboard listener and input handling
 codec_dispatch.py     — Skill matching and dispatch
 codec_agent.py        — LLM agent session builder
 codec_overlays.py     — Tkinter overlay popups

docs/audits/PHASE-1-CODE-QUALITY.md

@@ -85,6 +85,8 @@ Both scan `SKILLS_DIR` independently, so a skill file is loaded twice in differe
 
 ### A-8 — `codec_keyboard.py` (398 LOC) is dead in production [MEDIUM]
 **Location:** `codec_keyboard.py` (entire file). `start_keyboard_listener` defined at line 25.
+
+> **Closed by PR-3 A-8** (branch `fix/pr3-a8-delete-codec-keyboard`) via option (b) — delete. **Verify-first evidence:** (1) no production importer — only `tests/test_full_product_audit.py` + `tests/test_transcript.py` referenced it; (2) no PM2 entry runs it — `ecosystem.config.js` has no `codec_keyboard.py` script; the live keyboard path is inline in `codec.py` (`on_press`@788, `on_release`@858, `keyboard.Listener`@919) in the `codec` process; (3) `clean_transcript` is *defined* in `codec_config.py:841` (codec_keyboard only re-imported it). **Chose delete over the audit's option (a) "migrate to it":** option (a) would swap the live, battle-tested core-UX keyboard handler for an unused module that's nearly untestable in CI (no real pynput headless) — a regression risk on F13/F18/wake-word for an aesthetic gain, violating "never break working code." Deleted `codec_keyboard.py` (398 LOC); redirected `test_full_product_audit.py::TestKeyboard` to assert codec.py's live handlers + F13 debounce ≥1.0s + that the dead module stays gone; simplified `test_transcript.py` to import `clean_transcript` from `codec_config`. Note: the `overlay_events.jsonl` toggle-logging was a codec_keyboard-only feature that was never live (codec.py's handler doesn't write it) — no production behavior lost. AGENTS.md §2 + CONTRIBUTING.md updated.
 **Description:** `start_keyboard_listener` is never imported except by `tests/test_full_product_audit.py` and `tests/test_transcript.py` (which only verifies callable existence and imports `clean_transcript`). Production keyboard handling lives inline in `codec.py:1015-1097` (`on_press`/`on_release`) and `codec.py:1141-1148` (`keyboard.Listener` startup). Two implementations of wake-word + double-tap detection.
 **Impact:** ~398 LOC of unused engine module. Confusing for anyone trying to understand "where does F18 get handled."
 **Recommended fix:** Either (a) migrate `codec.py:on_press/on_release` to use `start_keyboard_listener` (so the module becomes the canonical implementation), or (b) delete `codec_keyboard.py` and move `clean_transcript` to `codec_config.py` where it's already imported from. Option (a) is the bigger improvement because the codec_keyboard implementation appears to be the cleaner one.

docs/audits/PHASE-1-CONSOLIDATED-TRIAGE.md

@@ -244,7 +244,8 @@ Mirror the Intake Phase 3 wave pattern. 7 waves planned; sizes are PR-counts, NO
 - PR-3F (optional, large): A-19 — bridge unification (iMessage + Telegram → `BridgeRouter`)
 - PR-3G: small misc ✅ (branch `fix/pr3g-small-misc-cleanup`) — closed A-9 (DISABLED overlay, ~90 LOC), A-10 (run_session_module, 33 LOC + orphan `import sys`), A-14 (close_session shadow import), A-18 (9 unused Pydantic models + dead typing import). A-13 (dashboard pattern blocker) verified **already closed by PR-2C**. 6 regression tests; zero net-new ruff (net −); full suite 1344 passing. **Deferred from this batch (each needs its own focused PR):** A-8 (codec_keyboard.py 398 LOC — verify-first delete-or-migrate decision), A-15 (config_version — additive migration feature touching `load_config`), A-20 (inline sqlite in the live dispatch path — reliability fix needing a CodecMemory method).
 - A-15: config schema versioning ✅ (branch `fix/pr3-a15-config-versioning`; `CONFIG_SCHEMA_VERSION=1` + migration ladder + idempotent atomic write-back in `load_config`; never creates-on-missing or overwrites-corrupt; 12 tests; zero net-new ruff; full suite 1356 passing).
-- A-20: inline-sqlite reliability fix ✅ (branch `fix/pr3-a20-inline-sqlite`; added `codec_core._db_connect()` with WAL+busy_timeout + `update_session_response()`; replaced codec.py's inline lock-prone UPDATE; retrofitted all 4 codec_core session connects; removed now-unused sqlite3/DB_PATH imports; 9 tests; net-negative ruff; full suite 1365 passing). **Still deferred: A-8** (codec_keyboard.py 398 LOC — verify-first delete-or-migrate).
+- A-20: inline-sqlite reliability fix ✅ (branch `fix/pr3-a20-inline-sqlite`; added `codec_core._db_connect()` with WAL+busy_timeout + `update_session_response()`; replaced codec.py's inline lock-prone UPDATE; retrofitted all 4 codec_core session connects; removed now-unused sqlite3/DB_PATH imports; 9 tests; net-negative ruff; full suite 1365 passing).
+- A-8: codec_keyboard.py deleted ✅ (branch `fix/pr3-a8-delete-codec-keyboard`; verify-first confirmed dead — no prod importer, no PM2 entry, live keyboard path inline in codec.py, clean_transcript lives in codec_config; chose delete over migrate to avoid swapping battle-tested core-UX code for an untested module; redirected TestKeyboard to codec.py; full suite passing). **All eight PR-3G-cluster findings now closed** (A-8/9/10/13/14/15/18/20).
 
 **Rationale:** Audit A is the broadest in scope — clean up patterns and dead code. PR-3A alone deletes ~730 LOC and improves the first-impression of the most-read file.
 

tests/test_full_product_audit.py

@@ -1057,26 +1057,33 @@ def test_session_uses_centralized_dangerous(self):
 # ============================================================================
 
 class TestKeyboard:
-    """Test keyboard module."""
+    """Test the LIVE keyboard path.
 
-    def test_keyboard_imports(self):
-        from codec_keyboard import start_keyboard_listener
-        assert callable(start_keyboard_listener)
+    A-8 (PR-3): the unused `codec_keyboard.py` module (398 LOC, only ever
+    imported by tests) was deleted. Production keyboard handling is inline
+    in codec.py (the `codec` PM2 process). These tests now pin codec.py's
+    real handlers + the F13 debounce invariant."""
+
+    def test_live_keyboard_handlers_in_codec(self):
+        """codec.py owns the live on_press/on_release + keyboard.Listener."""
+        code = Path(REPO, "codec.py").read_text()
+        assert "def on_press" in code
+        assert "def on_release" in code
+        assert "keyboard.Listener" in code
 
     def test_f13_debounce(self):
-        """F13 debounce should be >= 1.0 seconds."""
-        code = Path(REPO, "codec_keyboard.py").read_text()
-        # Find the debounce check
+        """F13 debounce should be >= 1.0 seconds (codec.py live handler)."""
+        code = Path(REPO, "codec.py").read_text()
         match = re.search(r'last_f13.*?<\s*([\d.]+)', code)
-        assert match, "F13 debounce not found"
+        assert match, "F13 debounce not found in codec.py"
         debounce = float(match.group(1))
         assert debounce >= 1.0, f"F13 debounce too short: {debounce}s"
 
-    def test_overlay_events_path(self):
-        """Should use ~/.codec/ not /tmp/."""
-        code = Path(REPO, "codec_keyboard.py").read_text()
-        assert "/tmp/" not in code, "Still using /tmp/ path"
-        assert "~/.codec/" in code or "overlay_events" in code
+    def test_codec_keyboard_module_removed(self):
+        """The dead duplicate module must stay gone (A-8)."""
+        assert not Path(REPO, "codec_keyboard.py").exists(), (
+            "codec_keyboard.py was deleted as dead code (A-8) — must not return"
+        )
 
 
 # ============================================================================

tests/test_transcript.py

@@ -7,10 +7,9 @@
 
 
 def test_import():
-    try:
-        from codec_keyboard import clean_transcript
-    except ImportError:
-        from codec_config import clean_transcript
+    # A-8 (PR-3): clean_transcript is defined in codec_config; the old
+    # codec_keyboard re-export was deleted along with that dead module.
+    from codec_config import clean_transcript
     assert clean_transcript is not None