@@ -1,259 +1,338 @@
1-# File Helper and Tooling Refactor Plan
1+# File Helper Refactor Plan
22
3-## Summary
3+## Status at a glance
44
5-We are moving away from making the LLM directly operate the current hashline `read` / `replace` / `insert` protocol as the primary editing path.
5+This refactor is mostly done.
66
7-The root problem is not only stale anchors or poor recovery. The bigger issue is that the current model-facing edit API is too complex and stateful for reliable use:
7+The branch has already moved mini-coder toward the intended shell-first model:
88
9-- `read` returns decorated lines that must be translated back into plain text
10-- edits require choosing between several write modes
11-- writes are coupled to prior reads and exact anchors
12-- models frequently produce valid-looking but bad edits, then enter reread / repair loops
13-- shell becomes the escape hatch when structured edits break down
9+- `mc-edit` exists as a dedicated helper binary
10+- shared file-edit logic was extracted under `src/internal/file-edit/`
11+- shell now exposes `mc-edit` as the preferred targeted edit path
12+- the system prompt and tool surface were simplified around shell usage
13+- model-facing local file tools have been removed or are in the process of being fully deleted from the old path
14+- hook support has been removed as part of the same cleanup
1415
15-The new direction is:
16+The main work still left is **undo**.
1617
17-- prefer **shell-driven workflows** for reading, searching, verification, and other general repo actions
18-- provide a **dedicated helper CLI binary** for one thing only: safe, token-conscious file edits
19-- keep shared logic in **internal packages**, with thin bin entrypoints
20-- remove the old hashline-based edit tools and update prompts/tool guidance to reflect the new approach
18+`/undo` is still implemented around the old tool-managed snapshot model, while real edits now happen through shell commands that invoke `mc-edit`. Until that is redesigned, the architecture is not fully aligned.
2119
2220 ---
2321
24-## Decisions
22+## Why this refactor exists
2523
26-### 1. Prefer shell + helper CLI over direct hashline editing
24+The old hashline editing protocol (`read` + `replace` / `insert`) was too fragile for normal model use.
2725
28-The agent should primarily edit files via shell commands that call a purpose-built helper CLI, instead of directly using `replace` / `insert` for most code changes.
26+Problems with the old approach:
2927
30-Why:
28+- `read` returned decorated `line:hash|` output instead of plain file text
29+- edits depended on exact protocol choreography across multiple tool calls
30+- models had to carry stale anchors and hashes across turns
31+- semantically correct edits often failed because the payload shape or anchor state was slightly wrong
32+- failures regularly degraded into reread-and-repair loops
33+- when that happened, shell was already the practical fallback
3134
32-- models are generally stronger with shell-shaped workflows
33-- a helper CLI can still enforce safety and deterministic behavior
34-- this reduces the protocol burden compared with multi-step anchor editing
35-- it gives us a simpler model-facing interface without giving up control
35+The point of this refactor is **not** to improve that protocol.
36+The point is to replace it with a simpler contract that matches how models already work best:
3637
37-### 2. Use a separate helper binary, not `mc file ...`
38+- inspect with shell
39+- edit with a narrow helper
40+- verify with shell
3841
39-We should expose a separate executable for file operations instead of overloading the main `mc` CLI.
42+That is why `mc-edit` exists.
4043
41-Why:
44+---
45+
46+## Target architecture
47+
48+### Final model-facing tool surface
4249
43-- cleaner mental model:
44- - `mc` = agent CLI
45- - helper bin = deterministic file operations
46-- lower command ambiguity for models
47-- easier to evolve independently
48-- easier to document as a narrow, machine-oriented interface
50+The intended steady state is:
4951
50-Working name examples:
52+- connected **MCP tools**
53+- **`shell`**
54+- **`subagent`**
55+- **`listSkills`**
56+- **`readSkill`**
57+- **`webSearch`** and **`webContent`** when Exa is configured
5158
52-- `mc-edit`
59+Removed local runtime tools:
5360
54-Final naming can be decided later, but it should be a separate bin.
61+- `read`
62+- `create`
63+- `replace`
64+- `insert`
65+- hook-related runtime tooling
5566
56-### 3. Shared code should live in internal packages
67+### Final file workflow
5768
58-The helper bin and the main CLI must not share logic by importing each other’s entrypoints.
69+The intended workflow is:
5970
60-Instead, shared implementation should be extracted into internal packages / internal modules.
71+1. inspect/search with shell
72+2. mutate files with `mc-edit`
73+3. verify with shell
6174
62-High-level principle:
75+`mc-edit` is intentionally narrow:
6376
64-- bins are thin adapters
65-- reusable logic lives below them
66-- tests should target internal packages directly where possible
67-- Consider migration to a typescript monorepo or just nested packages
77+- exact-text edits only
78+- deterministic failure on stale or ambiguous state
79+- machine-friendly output
80+- no broad file-management abstraction beyond the edit helper itself
6881
6982 ---
7083
71-## Proposed architecture
84+## What has landed on this branch
7285
73-## Binaries
86+### 1. Shared file-edit internals were extracted
7487
75-- `mc`
76- - existing agent CLI
77-- `mc-edit`
78- - single-purpose safe edit helper, intended to be invoked from shell
88+Implemented under:
7989
80-## Internal packages / modules
90+- `src/internal/file-edit/cli.ts`
91+- `src/internal/file-edit/exact-text.ts`
92+- `src/internal/file-edit/path.ts`
93+- `src/internal/file-edit/command.ts`
8194
82-Suggested initial layout:
95+### 2. `mc-edit` was added as its own binary
8396
84-- `src/internal/file-edit/`
85- - path resolution
86- - edit planning and application
87- - stale-state checks
88- - result metadata
97+Implemented via:
8998
90-Exact layout can be refined during implementation. The important constraint is that the bin stays thin and the editing logic lives in shared internals.
99+- `src/mc-edit.ts`
100+- `package.json`
101+- `scripts/build.ts`
91102
92-A key simplification here is that we are **not** designing a broad file-operations CLI. Shell already covers reading, searching, moving files, and orchestration well enough. The helper only needs to solve one problem: safe partial file edits.
103+### 3. The agent was moved to a shell-first editing model
93104
94----
105+Implemented via:
106+
107+- shell prelude injection in `src/tools/shell.ts`
108+- prompt guidance in `src/agent/system-prompt.ts`
109+- shell tests covering `mc-edit` wiring
95110
96-## Design goals
111+### 4. The old structured edit path was removed
97112
98-The helper CLI should optimize for **model reliability**, **determinism**, **safety**, and **token efficiency**.
113+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.
99114
100-### Reliability goals
115+### 5. The local tool surface was reduced
101116
102-- one simple mental model for edits
103-- avoid anchor bookkeeping entirely in the model-facing API
104-- keep the operation narrow enough that the model can use it consistently
105-- make stale state explicit and easy to recover from
117+The branch now targets a much smaller local runtime surface centered on:
106118
107-### Safety goals
119+- `shell`
120+- `subagent`
121+- `listSkills`
122+- `readSkill`
123+- optional Exa tools
108124
109-- apply targeted edits instead of defaulting to whole-file rewrites
110-- fail clearly when the expected target no longer matches
111-- avoid silent partial success
125+That is the right direction and should remain the end state.
112126
113-### Token and performance goals
127+### 6. Hook support was removed instead of redesigned
114128
115-- avoid full-file rewrites for ordinary edits
116-- keep helper invocations and outputs compact
117-- reduce reread / repair loops caused by bad accepted edits
118-- preserve existing repo performance standards
129+This cleanup is 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.
130+
131+### 7. CLI and docs cleanup has started
132+
133+Prompt text, tool rendering, help text, and docs have already been pushed toward the shell-first model, but this part still needs a final consistency pass after undo is redesigned.
119134
120135 ---
121136
122-## Model-facing API direction
137+## Key decisions
123138
124-We should keep the helper CLI as small as possible.
139+### 1. Shell is the primary interface for repo work
125140
126-The shell tool is already sufficient for:
141+Shell should be the default for:
127142
128143 - reading files
129-- searching code
130-- inspecting directories
131-- running tests and verification
132-- composing temporary files when needed
144+- searching
145+- running tests/builds
146+- git inspection
147+- verification
148+- invoking `mc-edit`
133149
134-We do not need to duplicate any of that functionality in the helper.
150+We are no longer optimizing around a large local file-tool API.
135151
136-`mc-edit` should do one thing only: apply a safe partial edit to a file without requiring a whole-file overwrite.
152+### 2. `mc-edit` is the safe path for targeted edits
137153
138-The exact invocation details can be finalized during implementation, but the shape should stay minimal:
154+We want one narrow edit helper instead of several model-facing edit tools.
139155
140-- one binary
141-- one edit operation
142-- targeted file edits
143-- clear failure when the expected target no longer matches
144-- compact, machine-friendly output
156+That keeps the contract simpler:
145157
146-The helper exists to make ordinary edits reliable and token-conscious. It should not grow into a general-purpose file command suite.
158+- shell handles orchestration
159+- `mc-edit` handles exact mutation
147160
148----
161+### 3. `listSkills` and `readSkill` stay
149162
150-## Output principles
163+These are not general-purpose file tools. They are support tools for community/project config and should remain available.
151164
152-The helper CLI should be machine-oriented first.
165+### 4. `read` and `create` should not remain as compatibility tools
153166
154-Preferred traits:
167+If file inspection is shell-driven and edits are shell + `mc-edit`, keeping old local file tools around only muddies the contract.
155168
156-- stable output format
157-- minimal verbosity
158-- easy success/failure detection
159-- compact enough for shell use
169+### 5. Hooks are out for this refactor
160170
161-Current leaning: keep the output as small and rigid as possible so the model can use it consistently.
171+The correct choice here is deletion, not redesign.
162172
163----
173+If hooks ever come back, that should happen as a separate effort with a clear use case.
164174
165-## Relationship to existing tools
175+### 6. `/undo` must follow the real edit path
166176
167-- do not expand the current hashline protocol further
168-- do not keep the old edit tools as a fallback path
169-- once `mc-edit` is proven out, remove `replace` / `insert` / related hashline edit plumbing and clean up the associated prompting
170-- any shared logic worth keeping should be extracted into the new internal package rather than preserved through compatibility layers
177+The old snapshot model was built around tool-managed writes.
178+That no longer matches reality.
171179
172-Important: the goal is simplification, not running two editing systems indefinitely.
180+If `/undo` is kept, it should primarily guarantee restoration for edits that went through `mc-edit`, not arbitrary raw shell file operations.
181+
182+### 7. MCP descriptions matter more now
183+
184+With fewer local tools, MCP tools take up a larger share of the model-visible surface.
185+Their names and descriptions should stay concise and easy to distinguish from shell work.
173186
174187 ---
175188
176-## Migration strategy
189+## What is left to do
190+
191+### 1. Redesign `/undo` around `mc-edit`
177192
178-### Phase 1: Extract internals
193+This is the main unfinished work.
179194
180-- move reusable file-edit logic into an internal package
181-- keep the extraction narrowly focused on safe partial edit application
182-- add focused tests around success and failure behavior
195+### Current state
183196
184-### Phase 2: Add `mc-edit`
197+Undo still depends on the old snapshot path:
185198
186-- add `mc-edit` as a separate binary
187-- implement only the minimal safe-edit behavior
188-- ensure the output contract is stable and compact
199+- `src/tools/snapshot.ts`
200+- `src/agent/undo-snapshot.ts`
201+- `src/agent/session-runner.ts`
202+- `src/session/db/snapshot-repo.ts`
189203
190-### Phase 3: Switch the agent path
204+That design assumes the agent knows when file writes happen through local tools.
205+But the new edit path is shell-driven, so that assumption is no longer valid.
191206
192-- update agent guidance to prefer shell + `mc-edit`
193-- stop steering the model toward hashline edits
194-- monitor behavior in the session DB
207+### Recommended decision
195208
196-### Phase 4: Remove old edit tools
209+Keep `/undo` and a conversation turn undo only. Remove snapshotting and file changes tracking. Reflect this in the repor documentation as well.
197210
198-- delete the old hashline-based edit tools and their supporting code
199-- remove obsolete tests, prompts, and documentation
200-- keep only the new editing path
211+### Done when
212+
213+- /undo doesn't manage filesystem changes
214+- snapshotting is completly removed
201215
202216 ---
203217
204-## Success criteria
218+### 2. Finish the docs and help-text consistency pass
219+
220+The repo is already telling the new story in several places, but not yet from one consistent source of truth.
205221
206-This refactor is successful if we observe meaningful reduction in:
222+### Sweep targets
207223
208-- reread / edit loops on the same file
209-- overlapping repair edits after a "successful" write
210-- malformed but accepted edit payloads
211-- need to abandon the safe edit path and fall back to raw shell rewrites
224+- `mini-coder-idea.md` Note: keep it focused and in the existing idea style.
225+- `README.md`
226+- `docs/mini-coder.1.md`
227+- `docs/configs.md`
228+- `docs/custom-commands.md`
229+- `docs/custom-agents.md`
230+- `docs/skills.md`
231+- `.agents/commands/*`
232+- `.agents/agents/*`
233+- `.agents/skills/*`
212234
213-And improvement in:
235+### What to check
214236
215-- task completion reliability
216-- model confidence after edits
217-- token efficiency of normal edits
218-- maintainability of the editing stack
237+- mini-coder is described as shell-first
238+- `mc-edit` is clearly named as the targeted edit path
239+- removed local file tools are not described as active runtime tools
240+- removed hook support is not described anywhere
241+- `/undo` wording matches the redesigned guarantee once that work lands
242+
243+### Done when
244+
245+- docs match implementation
246+- examples reinforce shell + `mc-edit`
247+- there are no stale references to removed tools or hooks
219248
220249 ---
221250
222-## Non-goals
251+### 3. Final prompt, CLI, and rendering polish
252+
253+Most of this is already moving in the right direction, but it still needs a final pass once undo is settled.
223254
224-For this effort, we are **not** trying to:
255+### Areas to review
225256
226-- perfect the existing hashline anchor format
227-- add more anchor variants or richer line matching as the main strategy
228-- turn the main `mc` CLI into a multi-purpose file helper interface
229-- build a broad file-management helper that duplicates shell capabilities
230-- add multiple helper subcommands or grow a larger command surface
257+- `src/agent/system-prompt.ts`
258+- `src/cli/tool-render.ts`
259+- `src/cli/tool-result-renderers.ts`
260+- `src/cli/commands-help.ts`
261+- `src/mcp/client.ts`
231262
232-Those may still be useful in limited contexts, but they are not the primary direction.
263+### What to improve
264+
265+- ensure the prompt matches the final tool surface exactly
266+- keep shell guidance crisp and unambiguous
267+- make MCP descriptions more context-efficient if needed
268+- keep result previews compact and useful for shell and MCP output
269+- remove any remaining wording tied to old snapshot behavior
270+
271+### Done when
272+
273+- prompt text exactly matches runtime behavior
274+- CLI output reflects only the remaining architecture
275+- MCP descriptions are concise and distinguishable
276+
277+---
278+
279+### 4. Verify the cleanup end-to-end
280+
281+Before this refactor is considered complete, we should do one final dead-code and behavior sweep.
282+
283+### Check for
284+
285+- no runtime registration of removed local file tools
286+- no dead hashline or old edit-protocol code left behind
287+- no hook runtime/UI/doc code left behind
288+- tests aligned with the new tool surface
289+- shell + `mc-edit` workflow working in practice
290+
291+### Repo verification command
292+
293+Run:
294+
295+```bash
296+bun run jscpd && bun run knip && bun run typecheck && bun run format && bun run lint && bun run test
297+```
233298
234299 ---
235300
236-## Open questions for implementation
301+## Completion checklist
302+
303+This refactor is complete when all of the following are true:
304+
305+- the model-visible tool surface is shell, subagent, listSkills, readSkill, connected MCP tools, and optional Exa tools
306+- `mc-edit` is the clear targeted edit path
307+- the old hashline edit path is fully gone
308+- hooks are fully gone from runtime, UI, and docs
309+- `/undo` is aligned with shell + `mc-edit`
310+- prompt, CLI, and docs all describe the same architecture
311+- bundled commands/skills/examples reinforce the shell-first workflow
312+
313+---
314+
315+## Non-goals
237316
238-These can be finalized during the implementation phase:
317+This effort is not trying to:
239318
240-- final helper binary name and exact invocation shape -- `mc-edit`
241-- the simplest safe matching strategy for partial edits
242-- exact result format on success and failure
243-- the cleanest removal sequence for the old edit tools and their prompt wiring
319+- improve the old hashline edit protocol
320+- keep old local edit tools as fallback paths
321+- redesign a new hook framework right now
322+- guarantee undo for arbitrary raw shell file operations
323+- turn `mc-edit` into a broad file-management CLI
244324
245325 ---
246326
247-## Implementation guidance for future work
327+## Practical conclusion
248328
249-Implementation should stay scoped and incremental:
329+Compared to `main`, the branch has already done the hard architectural shift: `mc-edit` exists, shell is the primary path, and the old local edit model has been largely dismantled.
250330
251-1. extract internal file-edit primitives first
252-2. add the separate helper bin second
253-3. keep the command surface to a single edit behavior
254-4. add focused tests before broad integration changes
255-5. switch agent behavior and then remove the old tools
331+What remains is mostly about making the new architecture complete and honest:
256332
257-Commit your progress each step.
333+- finish `/undo`
334+- finish the docs/help/prompt consistency pass
335+- do one final MCP/CLI polish sweep
336+- verify no stale code or messaging remains
258337
259-Do not begin by expanding the current hashline API. The point of this effort is to replace it with a much simpler editing contract, not add more protocol complexity.
338+That is the real endgame for this refactor.