--- name: refactor description: "Orchestrates safe, large-scale structural changes across a codebase — symbol renames, API migrations, pattern standardizations, layer restructurings. Enumerates all affected sites, groups them into dependency layers via the DAG executor, applies changes in parallel per layer with worktree isolation, and verifies behavioral preservation at each layer boundary before proceeding. Exits immediately on first regression, surfacing the exact site, diff, and behavioral delta before any commit." argument-hint: " [--scope ]" failure_modes: - bad decomposition - dependency blindness - false completeness - premature execution context: fork --- ## Sub-agent contract /contract **Skip when:** the change touches ≤3 files and no dependency ordering is required — just edit directly. Also skip when the codebase has no test coverage at all (behavioral preservation cannot be verified; ask the user to add tests first or proceed manually). --- ### Triage (inline, before dispatching any sub-agent) Parse `$ARGUMENT` to extract: - **Change type**: rename | api-migration | pattern-standardization | layer-restructure | dependency-upgrade | other - **Target symbol / path / pattern** (what is changing) - **Destination** (what it becomes) - **Scope**: default to the entire repo; narrow if `--scope` is provided If `$ARGUMENT` is ambiguous on any of the above, stop and ask exactly one question. --- ### Wave 1 — Scope enumeration (parallel, `subagent_type: "research-agent"`) Dispatch both agents simultaneously in a single response turn. **Site-finder agent** - goal: Enumerate every file and symbol that must change for the refactor to be complete and correct. - inputs: change type, target symbol/pattern, scope glob - artifacts: - `sites`: array of `{file, line_range, site_type: "definition"|"import"|"usage"|"type-ref"|"test", change_required: string}` - `dependency_graph`: for each site, which other sites must be changed first (a site depends on its callers if it exports a symbol; a definition must be changed before its imports) - `site_count`: integer - `confidence`: low | medium | high - `coverage_gaps`: what the agent couldn't search (generated files, third-party vendored code, etc.) - non_goals: Do not apply any changes. Do not read unrelated files. - failure_modes: If grep tooling is unavailable, return `confidence: low` and list what was searched manually. **Contract-extractor agent** - goal: Identify the public interfaces and test commands that verify behavioral preservation for the affected API surface. - inputs: site list (from site-finder, passed inline if available; if not yet available, derive from change type + scope) - artifacts: - `contracts`: array of `{symbol, signature_before, exported_by, consumed_by[]}` - `test_commands`: array of shell commands that SCOPE to the affected contracts — target the specific test files or a name pattern, never the whole suite (e.g., `pnpm test src/auth/auth-service.test.ts` or `pnpm test -t "AuthService"`). Under pnpm, `pnpm test -- ` drops the file arg and runs the entire suite — never emit that form. - `test_coverage_verdict`: "adequate" | "partial" | "absent" - `confidence`: low | medium | high - `coverage_gaps`: test paths not reachable by the identified commands - non_goals: Do not run tests. Do not read unrelated files. **Scope gate (after Wave 1):** - `site_count > 50` → warn the user: "This refactor touches N sites. Recommend scoping down with `--scope` or batching via `/parallelize`. Proceeding, but each layer will take longer." - `test_coverage_verdict == "absent"` → hard stop: "No tests cover the affected contracts. Behavioral preservation cannot be verified. Add tests before proceeding, or explicitly confirm you accept unverified risk." - Either agent returns `confidence: low` → surface the coverage gaps and ask the user to confirm before proceeding. --- ### Synthesize: Build the layer map (inline) From `dependency_graph`, compute a topological sort into layers using Kahn's algorithm: - **Layer 0** — leaf sites with no dependents (definitions that nothing imports, or sites that depend on nothing else changing first) - **Layer N** — sites whose dependencies are all in layers 0…N-1 If the graph has cycles (rare but possible in circular-import codebases), surface them explicitly: "Cycle detected between [A, B, C]. Manual intervention required before automation can proceed." Do not continue. --- ### Wave 2 — Layer-by-layer application (sequential between layers, parallel within each layer) For **each layer** (starting at Layer 0): Dispatch one sub-agent per site in this layer, all in parallel, each in a worktree-isolated environment: **Layer applicator agent** (per site, `isolation: "worktree"`) - goal: Apply the transformation at exactly this site and verify it passes its targeted tests. - inputs: site descriptor `{file, line_range, change_required}`, full transformation spec (target → destination), test commands that cover this site - artifacts: - `site`: `{file, line_range}` - `status`: "green" | "red" | "skipped" - `diff_applied`: the exact unified diff applied (≤30 lines; truncate with `...` if longer) - `test_output`: truncated stdout of the targeted test run (last 20 lines) - `failure_reason`: populated only if `status == "red"` — the first failing assertion + the file:line where it fired - non_goals: Do not change any file other than the one in your site descriptor. Do not run the full test suite. - IMPORTANT: this sub-agent MAY call `edit_file` and run bash commands; `isolation: "worktree"` is required. **Layer gate — hard stop before proceeding to the next layer:** - All sites in this layer `status == "green"` → proceed to the next layer. - Any site `status == "red"` → **abort the entire refactor immediately**. Do NOT apply any more changes. Surface: - The failing site (`file:line_range`) - The `diff_applied` for that site - The `failure_reason` - The current layer number and which layers (if any) already completed successfully - Recommendation: "Revert layer N changes manually or run `git stash` in each affected worktree, then diagnose with `/diagnose`." --- ### Wave 3 — Behavioral diff verification (after all layers green, `subagent_type: "research-agent"` or Bash-capable) Dispatch a single behavioral-diff agent: **Behavioral-diff agent** (`isolation: "worktree"`, Bash-capable) - goal: Run the full test suite and compare observable behavior at the API boundary before vs. after. - inputs: `test_commands` from the contract-extractor, plus any project-wide test command (inferred from `package.json`, `Makefile`, etc.) - artifacts: - `full_suite_status`: "all-green" | "failures" - `failing_tests`: array of `{test_name, file, failure_reason}` (empty if all-green) - `behavioral_deltas`: array of `{symbol, before_behavior, after_behavior, expected: true|false}` — note only deltas, not noise - `unexpected_deltas`: subset of `behavioral_deltas` where `expected == false` - `confidence`: low | medium | high - non_goals: Do not commit. Do not push. **Post-Wave 3 decision:** - `full_suite_status == "all-green"` AND `unexpected_deltas` is empty → proceed to synthesis, recommend commit. - `full_suite_status == "failures"` OR `unexpected_deltas` is non-empty → surface the unexpected deltas for human review. Do NOT commit. Recommend: "Review unexpected behavioral changes before committing. If intentional, update tests to reflect new contracts. If not, route to `/diagnose`." --- ### Synthesis: Change report Emit a structured change report: ``` ## Refactor Report **Goal:** — → **Scope:** - Sites enumerated: N - Layers processed: M (of M total) - Status: COMPLETE | ABORTED AT LAYER N **Changes applied:** | File | Lines | Type | Status | |------|-------|------|--------| **Tests run:** - Targeted (per-site): N runs, N green, N red - Full suite: all-green | N failures **Behavioral deltas:** - Expected: N - Unexpected: N (see below if non-zero) **Recommendation:** COMMIT | REVIEW REQUIRED | ABORT ``` If recommendation is COMMIT, offer to invoke `/ship` for the final commit + PR. If REVIEW REQUIRED or ABORT, do not invoke `/ship` and do not commit.