@@ -1,169 +0,0 @@
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.