@@ -0,0 +1,169 @@
1+# Code Health Remediation Plan
2+
3+## Goal
4+Address maintainability and reliability issues identified in `code-health.md` with low-risk, incremental refactors that keep behavior stable.
5+
6+## Constraints
7+- Keep `mini-coder-idea.md` and `README.md` unchanged.
8+- Prefer small PR-sized changes with passing tests after each step.
9+- Preserve current CLI behavior while improving structure.
10+
11+## Workstreams
12+
13+### 1) Decompose `src/agent/agent.ts` (High)
14+**Outcome:** `runAgent` remains orchestration entrypoint; responsibilities split into focused modules.
15+
16+**Steps:**
17+1. Add `src/agent/reporter.ts` interface (narrow surface for output/status/tool events).
18+2. Extract session lifecycle + turn loop into `src/agent/session-runner.ts`.
19+3. Extract subagent execution into `src/agent/subagent-runner.ts`.
20+4. Extract snapshot/undo helpers into `src/agent/undo-snapshot.ts`.
21+5. Extract user input processing into `src/agent/input-loop.ts`.
22+6. Keep `agent.ts` as composition/wiring file only.
23+
24+**Checks:**
25+- Add/adjust unit tests around orchestration boundaries.
26+- Ensure no behavior regressions in interrupts, resume, and tool-call flows.
27+
28+---
29+
30+### 2) Decompose `src/cli/output.ts` (High)
31+**Outcome:** Rendering responsibilities isolated and testable.
32+
33+**Target modules:**
34+- `src/cli/spinner.ts`
35+- `src/cli/tool-render.ts`
36+- `src/cli/stream-render.ts`
37+- `src/cli/status-bar.ts`
38+- `src/cli/error-render.ts`
39+- `src/cli/output.ts` as facade
40+
41+**Steps:**
42+1. Extract pure formatting helpers first (no IO).
43+2. Extract spinner lifecycle module.
44+3. Extract stream queue/tick/flush behavior.
45+4. Keep compatibility exports in `output.ts` to avoid broad callsite churn.
46+
47+**Checks:**
48+- Add focused tests for formatting + stream behavior.
49+- Verify terminal rendering remains stable manually.
50+
51+---
52+
53+### 3) Introduce `TerminalIO` abstraction (Medium)
54+**Outcome:** Centralized process/TTY interactions and signal lifecycle.
55+
56+**Steps:**
57+1. Create `src/cli/terminal-io.ts` with methods for stdout/stderr writes, raw mode, signal subscriptions.
58+2. Replace direct `process.*` use in output/input stack with injected `TerminalIO`.
59+3. Centralize signal registration/unregistration in one lifecycle owner.
60+
61+**Checks:**
62+- Add unit tests for signal registration cleanup semantics.
63+- Confirm no stuck raw-mode edge cases.
64+
65+---
66+
67+### 4) Split DB layer by domain (Medium)
68+**Outcome:** Reduced blast radius and clearer data ownership.
69+
70+**Target modules:**
71+- `src/session/db/connection.ts`
72+- `src/session/db/session-repo.ts`
73+- `src/session/db/message-repo.ts`
74+- `src/session/db/settings-repo.ts`
75+- `src/session/db/mcp-repo.ts`
76+- `src/session/db/snapshot-repo.ts`
77+- `src/session/db/index.ts` (facade exports)
78+
79+**Steps:**
80+1. Move code without behavior changes.
81+2. Keep SQL and schema unchanged initially.
82+3. Replace direct `JSON.parse` in message loading with guarded parser:
83+ - skip malformed rows
84+ - emit diagnostic via logger/reporter
85+
86+**Checks:**
87+- Add tests for malformed payload handling.
88+- Validate existing DB tests still pass.
89+
90+---
91+
92+### 5) Shared markdown config loader (Medium)
93+**Outcome:** Remove duplication across agents/skills/custom-commands.
94+
95+**Steps:**
96+1. Create `src/cli/load-markdown-configs.ts` with parameterized layout strategy.
97+2. Migrate:
98+ - `src/cli/agents.ts`
99+ - `src/cli/skills.ts`
100+ - `src/cli/custom-commands.ts`
101+3. Keep precedence rules identical (built-in/user/project).
102+4. Preserve existing frontmatter semantics.
103+
104+**Checks:**
105+- Reuse/expand existing loader tests to cover parity.
106+
107+---
108+
109+### 6) Runtime/UI decoupling via reporter boundary (Medium)
110+**Outcome:** Core runtime no longer depends directly on terminal rendering.
111+
112+**Steps:**
113+1. Define domain events or reporter interface in `src/agent/reporter.ts`.
114+2. Implement CLI reporter adapter in `src/cli/output-reporter.ts`.
115+3. Replace direct output calls in agent runtime with reporter calls.
116+
117+**Checks:**
118+- Add tests using test reporter to assert emitted events.
119+
120+---
121+
122+### 7) Error observability and silent catches (Medium)
123+**Outcome:** Non-fatal failures become diagnosable without crashing.
124+
125+**Steps:**
126+1. Find empty/broad catches in agent/output/loaders.
127+2. Add debug-level diagnostics with contextual metadata.
128+3. Keep user-facing behavior unchanged unless critical.
129+
130+**Checks:**
131+- Validate noisy paths are still quiet at normal verbosity.
132+
133+---
134+
135+### 8) Startup FS sync usage (Low/Deferred)
136+**Outcome:** Optional responsiveness improvement if startup cost grows.
137+
138+**Steps:**
139+1. Measure startup and config-loading time first.
140+2. If needed, move high-volume file scanning to async or cache results with invalidation.
141+
142+---
143+
144+### 9) Test hygiene cleanup (Low)
145+**Outcome:** Cleaner CI output.
146+
147+**Steps:**
148+1. Remove `console.log` skip notices in `src/tools/shell.test.ts`.
149+2. Use test-framework-native skip annotations/helpers.
150+
151+---
152+
153+## Execution Order (recommended)
154+1. Reporter interface (foundation for later decoupling).
155+2. `agent.ts` decomposition.
156+3. `output.ts` decomposition.
157+4. Shared config loader extraction.
158+5. DB module split + safe JSON parsing.
159+6. TerminalIO + centralized signals.
160+7. Silent catch diagnostics.
161+8. Test hygiene and any deferred FS optimization.
162+
163+## Definition of Done
164+- `bun run typecheck && bun run format && bun run lint && bun test` passes.
165+- No behavior regressions in interactive CLI flows.
166+- `agent.ts` and `output.ts` materially reduced in size/responsibility.
167+- Config loader duplication removed.
168+- Message loading resilient to malformed JSON rows.
169+- New abstractions documented in code comments where non-obvious.