MIT · EXPLICIT WRITE BOUNDARY

Refactor with evidence, not blind text replacement.

Weavatrix Refactor composes the read-only Core with 11 tools that identify a change, expose uncertainty, preview against the current tree, apply through an explicit write gate and retain a drift-checked rollback.

Install 1.0.11 See every method ↓

# rename-only catalog; preview remains read-only
$ npx -y weavatrix-refactor mcp <repoRoot> --profile=rename

# enable only sessions allowed to apply or roll back source edits
$ WEAVATRIX_ALLOW_SOURCE_EDITS=1 npx -y weavatrix-refactor mcp <repoRoot> --profile=rename

The same method owns preview and apply

rename_symbol and rename_related_symbols own their full two-phase operation. The same method previews first, then applies the exact recomputed plan when called with its single-use confirmation token.

PHASE 1 · READ-ONLY

Preview the exact operation

rename_symbol
symbol: src/users.ts#getUser@12
new_name: getCustomer

PREVIEW_OK
confirmToken: short-lived, plan-bound
completeness + uncovered references

PHASE 2 · WRITE-GATED APPLY

Confirm through the same method

rename_symbol
same symbol + same new_name
mode: apply
confirm_token: <preview token>

APPLIED
journaled, crash-recoverable writes
drift-checked rollback retained

Coordinated rename: rename_related_symbols validates up to 50 JS/TS renames together, rejects overlaps, chains, swaps, shadowing and any failed sub-rename, then applies the set through one journaled operation.

All 11 Refactor methods

Four complete write workflows, four applyable plan producers and three structural review tools. Every uncertainty stays visible instead of being converted into a guessed edit.

`rename_symbol`

Cross-language preview/confirm/apply rename using graph, tokenizer and exact lexical-location evidence. Unproven occurrences stay named and completeness stays PARTIAL.

`rename_related_symbols`

Several JS/TS renames in one conflict-checked, crash-recoverable multi-file operation.

`apply_edit_plan`

Generic two-phase executor for hash-bound weavatrix.edit-plan.v1 envelopes.

`rollback_last_apply`

Restores the latest pre-apply bundle and refuses to overwrite files that drifted after apply.

`change_signature`

Adds or removes JS/TS parameters with byte-exact declaration and call-argument surgery; spreads stay uncertain.

`edit_symbol`

Replaces a symbol body or inserts before/after its parser range, with a JS/TS parse gate.

`bulk_replace`

Two-stage literal or regex replacement over selected, stable occurrence IDs and exact expected counts.

`organize_imports`

Removes only provably unused named JS/TS imports; side-effect, default and namespace imports fail safe.

`move_file`

Builds a relocate review, import rewrites and architecture projection without pretending file relocation is a text edit.

`move_symbol`

Projects cycles, boundaries, target dependencies and blast radius before a declaration is moved.

`delete_readiness`

Returns safe, unsafe or UNPROVEN with references and dynamic risks; deletion is never automated.

One proof chain from target to rollback

The write layer does not replace Core analysis. It carries the same graph, provenance and revision through the edit and back into verification.

IDENTIFYStable symbol ID, parser range, callers and blast radius.
PLANExact before/after text, sha256, provenance and uncertainty.
CONFIRMShort-lived token bound to repository and executable plan.
APPLYLock, stale-tree recheck and journaled bottom-up edits.
VERIFYRefresh graph; inspect impact, architecture, tests and rollback.

Two write gates

Start with WEAVATRIX_ALLOW_SOURCE_EDITS=1, then present the exact single-use token. The rename profile narrows the catalog; it is not an authorization gate.

Stale-tree protection

Under the repository lock, every file hash and exact before string must still match the preview.

Crash-recoverable writes

The journal and rollback bundle live under the repository's .weavatrix/worktree control directory. Recovery remains retryable after an interrupted write or incomplete restore.

Path and encoding boundary

Traversal, escaping links, NTFS streams, non-UTF-8 files, invalid ranges, overlaps and split surrogate pairs are rejected before writing.

Measured against naked Codex and Serena

On the committed toy TypeScript fixture, all three real-agent arms were correct in three runs. Naked Codex was still fastest and cheapest; the rename profile's measured gain is over the previous full Weavatrix surface.

Arm	Correct runs	Median wall time	Median input tokens
Naked Codex	3/3	42,602 ms	72,169
Weavatrix 1.0.6 `--profile=rename`	3/3	48,389 ms	108,155
Weavatrix 1.0.5 full surface	3/3	58,719 ms	275,784
Serena	3/3	68,728 ms	388,271

The rename profile reduced fixed MCP context from 9,331 to 485 exact o200k_base tokens (94.8%) and kept all nine TypeScript, Rust and Python protocol runs at 12/12. These numbers are workload-specific, include each server's catalog and instructions, and report real agent wall time in milliseconds—not a universal claim that a tool beats naked editing on small repositories. Methodology and raw-result links.

Language support says exactly what is proven

A backend never claims more certainty than its evidence supports. Graph-plus-lexical rename remains PARTIAL even when every known reference is found.

Surface	Backend	Applyable proof	Completeness
JavaScript / TypeScript rename	Graph + tokenizer + exact lexical location	EXTRACTED / LEXICAL_EXACT	PARTIAL
SQL tables / fields	Schema-aware scanner	EXTRACTED / LEXICAL_EXACT	Skipped and ambiguous uses reported
Python / Rust / Go	Graph + exact lexical location	EXTRACTED / LEXICAL_EXACT	PARTIAL
Java / C# / Solidity	Graph + exact lexical location	EXTRACTED / LEXICAL_EXACT	PARTIAL
JS/TS signatures and imports	Parser + graph calls/references	EXTRACTED / RESOLVED	Unproven reach stays explicit

Honest limits: related multi-symbol rename is JS/TS-only; move_file and move_symbol are review/projection tools; exported deletion cannot receive an automatic clean verdict; tests, typechecking, runtime checks and review remain the release authority.