Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file"

Refactoring with GitNexus When to Use "Rename this function safely" "Extract this into a module" "Split this service" "Move this to a new file" Any task involving renaming, extracting, splitting, or restructuring code Bind the repository first Refactoring writes to disk. rename with dry run: false edits files in whichever repository was resolved, so binding identity here is a safety gate, not bookkeeping. Call list repos {} before the first tool call. With one indexed repository, use the examples below as written. With more than one, pass repo on every call: an omitted repo normally errors, but under an MCP policy with a configured default it resolves to that default silently. If you cannot tell which repository is meant, stop and ask. Never run rename with dry run: false until the preview in the same bound repository has been reviewed — its returned file path values show which checkout is about to be written, so read them as a confirmation of identity. list repos is paginated, so page with offset: pagination.nextOffset until hasMore is false before concluding a repository is absent. detect changes takes worktree when you are editing a linked worktree the MCP server was not launched from; otherwise git diff runs in the wrong checkout and reports nothing changed, which reads as a verified refactor. Workflow If "Index is stale" → run node .gitnexus/run.cjs analyze in terminal. Hot tool staleness names which index answered ( branch / lastCommit ) and how fresh it is ( status ). Re analyze only for behind or diverged — current is identity, unknown is unmeasurable. Checklists Rename Symbol Extract Module Split Function/Service Tools rename — semantic rename; preview first, then apply: dry run omitted or true previews and never writes; dry run: false requires the successful preview's plan token . Keep the same repository, selected symbol, and destination name. Tokens are single use, expire after 15 minutes or a server restart, and may be evicted when retained previews reach 16 plans or 64 MiB. Any apply attempt consumes the token; request and review a fresh preview to retry. An MCP server started with GITNEXUS MCP READ ONLY=1 still lists rename , but as preview only: it rejects any dry run other than omitted or true , so apply through a server that permits writes. Request and review a fresh preview there; tokens belong to the process that issued them. Rename uses the indexed graph and GitNexus's own semantic layer. Language providers resolve current source through scopes and bindings; no compiler or language service is loaded. Unsupported syntax, ambiguous bindings, stale declarations, and incomplete occurrence coverage fail closed. Coverage describes indexed files accepted by the selected provider, including supported embedded sources, and excludes unindexed files and external consumers. All registered source language providers supply rename rules. Declaration and override families require complete semantic evidence. Dynamic or computed references block a rename when the provider cannot resolve them or exclude them from the selected family. Provider specific limits, including class renames requiring a file move, remain explicit in results. There is no regex fallback: legacy graph edits and text search edits are zero. Comments, strings, and unrelated same spelled symbols are not replacements. Preview captures the exact semantic plan, source hashes and physical file targets. Apply validates that plan and executes its edits without replanning. Changes to indexed targets, source bytes or paths (including newly added untracked source files) reject the plan before writing. Unindexed files remain outside semantic coverage; analyze first when they need refactoring. Results use result version: 2 ; total edits counts occurrences, not matching lines. Exact replacements are shown in new text . Check planning status , application status , and applied . A completed apply has status: "success" , application status: "applied" , and applied: true . A successful preview has not written files. rename does not accept branch : it inspects the current checkout. Recover from a blocked or incomplete rename before applying again. A failed result carries code and error ; nothing was written unless the last row applies. Result Next step stale graph Re analyze the bound repository, then preview again with rename ( dry run omitted or true ). source changed Preview again against the current source and review it. If it appears during an apply, see the partial row. plan required , invalid plan , plan mismatch Apply needs the successful preview's token and identical repository, symbol and new name. Expired, consumed or evicted plans require a fresh reviewed preview. source set changed Source paths changed, including untracked files. Re analyze and review a fresh preview. plan too large The captured plan exceeds the 64 MiB retention budget. Narrow the indexed repository before previewing again. unsupported Stop automated rename and inspect the reported limitation. Use a language aware manual refactor if needed. Ambiguous target ( status: "ambiguous" with candidates) Inspect the returned candidates or context , then preview with the chosen symbol uid . ambiguous reference , incomplete semantics The planner could not prove a reference, import, or declaration is covered. Stop automated rename; resolve the named location by hand or pick a different symbol. name collision new name would collide with, or change the identity of, another declaration or binding. Choose a different name and preview again. invalid name new name is empty, equals the current name, or is not valid in the target language. Choose a valid, different identifier. invalid argument dry run was sent but is not a boolean. Omit it or send true or false . no locations The planner produced no edits. Do not apply; re check the target with context and pass symbol uid . overlapping edits , invalid edit The planned spans conflict or do not match the source text. The plan is rejected before any write; do not apply. Refactor manually or report the case. duplicate file , missing snapshot , outside repository A planner safety check failed (two paths resolve to one real file, a file has no source snapshot, or a path leaves the repository). Re analyze and preview again; if it repeats, stop and report it. source unavailable ( reason: "content retention" or "checkout missing" ) The index was built without full source retention ( GITNEXUS CONTENT RETENTION ), or the checkout directory is missing. Re analyze with full retention, or run against the checkout. rename failed An unexpected error while planning, before any write ( application status: "not started" ). Re analyze and preview once more; if it repeats, stop and report the error text. application status: "partial" or "failed" ( write failed , or source changed mid apply) Writes are not transactional. Inspect landed changes (already written, with their counts), failed files (the one file whose write or validation failed), and unattempted files (later files never touched). Reconcile the current files, re index, and review a fresh preview; never blindly retry the apply call. Run the project validation suite after applying. impact — map all dependents first: detect changes — verify your changes after refactoring: partial: true (a graph query failed) or truncated: true (the changed symbol listing was capped) means the result is short of the truth: a short or empty list is not proof that only the expected files changed. Re run it rather than treat the refactor as verified. A wrong worktree zero carries neither flag and is indistinguishable from a clean verification, so confirm the diffed checkout is the one you edited. cypher — custom reference queries: Risk Rules Risk Factor Mitigation Many callers ( 5) Use rename for automated updates Cross area refs Use detect changes after to verify scope String/dynamic refs query to find them External/public API Version and deprecate properly Same name in another indexed repo Bind repo ; verify previewed paths before applying Example: Rename validateUser to authenticateUser With a single indexed repository, step 0 returns total: 1 and the repo argument drops out of every call above.

gitnexus-refactoring