@@ -1,295 +0,0 @@
1-# File Helper Refactor Plan
2-
3-## Status at a glance
4-
5-This refactor is complete on this branch.
6-
7-mini-coder now follows the intended shell-first model:
8-
9-- `mc-edit` exists as a dedicated helper binary
10-- shared file-edit logic lives under `src/internal/file-edit/`
11-- shell exposes `mc-edit` as the targeted edit path
12-- the system prompt and tool surface are simplified around shell usage
13-- old model-facing local file tools are removed
14-- hook support is removed
15-- `/undo` is conversation-turn undo only
16-
17-`/undo` no longer tries to restore filesystem state, which keeps the architecture honest with the real shell + `mc-edit` edit path.
18-
19----
20-
21-## Why this refactor exists
22-
23-The old hashline editing protocol (`read` + `replace` / `insert`) was too fragile for normal model use.
24-
25-Problems with the old approach:
26-
27-- `read` returned decorated `line:hash|` output instead of plain file text
28-- edits depended on exact protocol choreography across multiple tool calls
29-- models had to carry stale anchors and hashes across turns
30-- semantically correct edits often failed because the payload shape or anchor state was slightly wrong
31-- failures regularly degraded into reread-and-repair loops
32-- when that happened, shell was already the practical fallback
33-
34-The point of this refactor was **not** to improve that protocol.
35-The point was to replace it with a simpler contract that matches how models already work best:
36-
37-- inspect with shell
38-- edit with a narrow helper
39-- verify with shell
40-
41-That is why `mc-edit` exists.
42-
43----
44-
45-## Target architecture
46-
47-### Final model-facing tool surface
48-
49-The steady state is:
50-
51-- connected **MCP tools**
52-- **`shell`**
53-- **`subagent`**
54-- **`listSkills`**
55-- **`readSkill`**
56-- **`webSearch`** and **`webContent`** when Exa is configured
57-
58-Removed local runtime tools:
59-
60-- `read`
61-- `create`
62-- `replace`
63-- `insert`
64-- hook-related runtime tooling
65-
66-### Final file workflow
67-
68-The intended workflow is:
69-
70-1. inspect/search with shell
71-2. mutate files with `mc-edit`
72-3. verify with shell
73-
74-`mc-edit` is intentionally narrow:
75-
76-- exact-text edits only
77-- deterministic failure on stale or ambiguous state
78-- machine-friendly output
79-- no broad file-management abstraction beyond the edit helper itself
80-
81----
82-
83-## What landed on this branch
84-
85-### 1. Shared file-edit internals were extracted
86-
87-Implemented under:
88-
89-- `src/internal/file-edit/cli.ts`
90-- `src/internal/file-edit/exact-text.ts`
91-- `src/internal/file-edit/path.ts`
92-- `src/internal/file-edit/command.ts`
93-
94-### 2. `mc-edit` was added as its own binary
95-
96-Implemented via:
97-
98-- `src/mc-edit.ts`
99-- `package.json`
100-- `scripts/build.ts`
101-
102-### 3. The agent was moved to a shell-first editing model
103-
104-Implemented via:
105-
106-- shell prelude injection in `src/tools/shell.ts`
107-- prompt guidance in `src/agent/system-prompt.ts`
108-- shell tests covering `mc-edit` wiring
109-
110-### 4. The old structured edit path was removed
111-
112-Implemented by removing the hashline edit flow built around `replace` and `insert`, and by collapsing the surrounding plumbing that only existed to support that protocol.
113-
114-### 5. The local tool surface was reduced
115-
116-The local runtime surface is now centered on:
117-
118-- `shell`
119-- `subagent`
120-- `listSkills`
121-- `readSkill`
122-- optional Exa tools
123-
124-### 6. Hook support was removed instead of redesigned
125-
126-This cleanup was part of the refactor because hooks were tied to the old, heavier local tool story and were not worth carrying forward in the middle of this architecture change.
127-
128-### 7. CLI and docs cleanup was completed
129-
130-Prompt text, tool rendering, help text, and docs now consistently reflect the shell-first model and the conversation-only `/undo` behavior.
131-
132----
133-
134-## Key decisions
135-
136-### 1. Shell is the primary interface for repo work
137-
138-Shell is the default for:
139-
140-- reading files
141-- searching
142-- running tests/builds
143-- git inspection
144-- verification
145-- invoking `mc-edit`
146-
147-We are no longer optimizing around a large local file-tool API.
148-
149-### 2. `mc-edit` is the safe path for targeted edits
150-
151-We want one narrow edit helper instead of several model-facing edit tools.
152-
153-That keeps the contract simpler:
154-
155-- shell handles orchestration
156-- `mc-edit` handles exact mutation
157-
158-### 3. `listSkills` and `readSkill` stay
159-
160-These are not general-purpose file tools. They are support tools for community/project config and should remain available.
161-
162-### 4. `read` and `create` should not remain as compatibility tools
163-
164-If file inspection is shell-driven and edits are shell + `mc-edit`, keeping old local file tools around only muddies the contract.
165-
166-### 5. Hooks are out for this refactor
167-
168-The correct choice here is deletion, not redesign.
169-
170-If hooks ever come back, that should happen as a separate effort with a clear use case.
171-
172-### 6. `/undo` should stay aligned with the real edit path
173-
174-The old snapshot model was built around tool-managed writes.
175-That no longer matches reality.
176-
177-The correct result for this refactor is to keep `/undo` as conversation history undo only, not a filesystem restoration feature for shell-driven edits.
178-
179-### 7. MCP descriptions matter more now
180-
181-With fewer local tools, MCP tools take up a larger share of the model-visible surface.
182-Their names and descriptions should stay concise and easy to distinguish from shell work.
183-
184----
185-
186-## Completion status
187-
188-### 1. Redesign `/undo`
189-
190-This work is done.
191-
192-#### What changed
193-
194-Undo no longer depends on the old snapshot path.
195-The snapshot-specific pieces were removed, including:
196-
197-- `src/tools/snapshot.ts`
198-- `src/agent/undo-snapshot.ts`
199-- `src/session/db/snapshot-repo.ts`
200-
201-`/undo` now removes only the most recent conversation turn from session history.
202-It does not try to infer or restore filesystem state from shell-driven edits.
203-
204-#### Result
205-
206-- `/undo` doesn't manage filesystem changes
207-- snapshotting is removed from runtime code and docs
208-
209----
210-
211-### 2. Finish the docs and help-text consistency pass
212-
213-This work is done.
214-
215-README, config/docs pages, bundled commands/skills guidance, and `mini-coder-idea.md` consistently describe the shell-first model, name `mc-edit` as the targeted edit path, and keep `/undo` scoped to conversation history only.
216-
217-#### Done when
218-
219-- docs match implementation
220-- examples reinforce shell + `mc-edit`
221-- there are no stale references to removed tools or hooks
222-- `/undo` is consistently described as conversation-history undo only
223-
224----
225-
226-### 3. Final prompt, CLI, and rendering polish
227-
228-This work is done.
229-
230-The system prompt names the final built-in tool surface explicitly, `/help` keeps `/undo` aligned with the conversation-only guarantee, MCP tool descriptions are tighter, and skill-tool call/result rendering is compact and readable.
231-
232-#### Done when
233-
234-- prompt text exactly matches runtime behavior
235-- CLI output reflects only the remaining architecture
236-- MCP descriptions are concise and distinguishable
237-
238----
239-
240-### 4. Verify the cleanup end-to-end
241-
242-This work is done on this branch.
243-
244-The runtime tool set is reduced to the intended surface, the bundled hook example files were removed, and the full repo verification command passes.
245-
246-#### Repo verification command
247-
248-Run:
249-
250-```bash
251-bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun run test
252-```
253-
254-Status on this branch: this command passes after the full shell-first cleanup.
255-
256----
257-
258-## Completion checklist
259-
260-This refactor is complete when all of the following are true:
261-
262-- the model-visible tool surface is shell, subagent, listSkills, readSkill, connected MCP tools, and optional Exa tools
263-- `mc-edit` is the clear targeted edit path
264-- the old hashline edit path is fully gone
265-- hooks are fully gone from runtime, UI, and docs/examples
266-- `/undo` is aligned with the shell-first architecture by only undoing conversation history
267-- prompt, CLI, and docs all describe the same architecture
268-- bundled commands/skills/examples reinforce the shell-first workflow
269-
270----
271-
272-## Non-goals
273-
274-This effort is not trying to:
275-
276-- improve the old hashline edit protocol
277-- keep old local edit tools as fallback paths
278-- redesign a new hook framework right now
279-- guarantee undo for arbitrary raw shell file operations
280-- turn `mc-edit` into a broad file-management CLI
281-
282----
283-
284-## Practical conclusion
285-
286-Compared to `main`, this branch completed the hard architectural shift: `mc-edit` exists, shell is the primary path, the old local edit model is gone, hooks are gone, and `/undo` is aligned with conversation history rather than filesystem restoration.
287-
288-At this point, the refactor is complete in the intended sense:
289-
290-- the model-visible tool surface is small and shell-first
291-- `mc-edit` is the clear targeted edit path
292-- prompt, CLI, docs, and bundled examples describe the same architecture
293-- verification passes on the branch
294-
295-Future work can build on this baseline, but the file-helper refactor itself has reached its intended end state.