@@ -0,0 +1,257 @@
1+# File Helper and Tooling Refactor Plan
2+
3+## Summary
4+
5+We are moving away from making the LLM directly operate the current hashline `read` / `replace` / `insert` protocol as the primary editing path.
6+
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:
8+
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
14+
15+The new direction is:
16+
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
21+
22+---
23+
24+## Decisions
25+
26+### 1. Prefer shell + helper CLI over direct hashline editing
27+
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.
29+
30+Why:
31+
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
36+
37+### 2. Use a separate helper binary, not `mc file ...`
38+
39+We should expose a separate executable for file operations instead of overloading the main `mc` CLI.
40+
41+Why:
42+
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
49+
50+Working name examples:
51+
52+- `mc-edit`
53+
54+Final naming can be decided later, but it should be a separate bin.
55+
56+### 3. Shared code should live in internal packages
57+
58+The helper bin and the main CLI must not share logic by importing each other’s entrypoints.
59+
60+Instead, shared implementation should be extracted into internal packages / internal modules.
61+
62+High-level principle:
63+
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
68+
69+---
70+
71+## Proposed architecture
72+
73+## Binaries
74+
75+- `mc`
76+ - existing agent CLI
77+- `mc-edit`
78+ - single-purpose safe edit helper, intended to be invoked from shell
79+
80+## Internal packages / modules
81+
82+Suggested initial layout:
83+
84+- `src/internal/file-edit/`
85+ - path resolution
86+ - edit planning and application
87+ - stale-state checks
88+ - result metadata
89+
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.
91+
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.
93+
94+---
95+
96+## Design goals
97+
98+The helper CLI should optimize for **model reliability**, **determinism**, **safety**, and **token efficiency**.
99+
100+### Reliability goals
101+
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
106+
107+### Safety goals
108+
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
112+
113+### Token and performance goals
114+
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
119+
120+---
121+
122+## Model-facing API direction
123+
124+We should keep the helper CLI as small as possible.
125+
126+The shell tool is already sufficient for:
127+
128+- reading files
129+- searching code
130+- inspecting directories
131+- running tests and verification
132+- composing temporary files when needed
133+
134+We do not need to duplicate any of that functionality in the helper.
135+
136+`mc-edit` should do one thing only: apply a safe partial edit to a file without requiring a whole-file overwrite.
137+
138+The exact invocation details can be finalized during implementation, but the shape should stay minimal:
139+
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
145+
146+The helper exists to make ordinary edits reliable and token-conscious. It should not grow into a general-purpose file command suite.
147+
148+---
149+
150+## Output principles
151+
152+The helper CLI should be machine-oriented first.
153+
154+Preferred traits:
155+
156+- stable output format
157+- minimal verbosity
158+- easy success/failure detection
159+- compact enough for shell use
160+
161+Current leaning: keep the output as small and rigid as possible so the model can use it consistently.
162+
163+---
164+
165+## Relationship to existing tools
166+
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
171+
172+Important: the goal is simplification, not running two editing systems indefinitely.
173+
174+---
175+
176+## Migration strategy
177+
178+### Phase 1: Extract internals
179+
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
183+
184+### Phase 2: Add `mc-edit`
185+
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
189+
190+### Phase 3: Switch the agent path
191+
192+- update agent guidance to prefer shell + `mc-edit`
193+- stop steering the model toward hashline edits
194+- monitor behavior in the session DB
195+
196+### Phase 4: Remove old edit tools
197+
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
201+
202+---
203+
204+## Success criteria
205+
206+This refactor is successful if we observe meaningful reduction in:
207+
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
212+
213+And improvement in:
214+
215+- task completion reliability
216+- model confidence after edits
217+- token efficiency of normal edits
218+- maintainability of the editing stack
219+
220+---
221+
222+## Non-goals
223+
224+For this effort, we are **not** trying to:
225+
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
231+
232+Those may still be useful in limited contexts, but they are not the primary direction.
233+
234+---
235+
236+## Open questions for implementation
237+
238+These can be finalized during the implementation phase:
239+
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
244+
245+---
246+
247+## Implementation guidance for future work
248+
249+Implementation should stay scoped and incremental:
250+
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
256+
257+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.