lithermes-ai 0.5.0

package/assets/lithermes-plugin/skills/refactor/SKILL.md

@@ -0,0 +1,770 @@
+---
+name: refactor
+description: "Intelligent refactor command. Triggers: refactor, refactoring, cleanup, restructure, extract, simplify, modernize."
+---
+
+## LitHermes Hermes-native execution (authoritative — overrides any harness examples below)
+
+In Hermes there is **one** way to fan out refactor lanes: the native **`delegate_task`**
+tool. It takes a batch of child tasks — `delegate_task(tasks:[{goal, context, toolsets?, role?}])`
+— that run in **parallel**; the parent blocks until every child returns, then receives all
+results together. Roles are `leaf` or `orchestrator`. There is no single-agent spawn
+primitive, no `task()`, no background-output polling call, no named-agent registry, and no
+per-child model selection. The prose and code blocks further down were copied from a
+different harness and use foreign delegation names; translate every one of them to a
+`delegate_task` child whose `goal`/`context` **inline** the role's full mandate.
+
+| Legacy prose says | Do this in Hermes |
+| --- | --- |
+| "fire N explore agents in background" | call `delegate_task` **once** with a batch of N children (they run in parallel) |
+| any "call the explore agent" / `subagent_type="explore"` call | a `delegate_task` child, `role:"leaf"`, whose `goal` is "codebase-search role: find …" and `context` carries the target/diff inline |
+| any "call the librarian agent" call | a `delegate_task` child, `role:"leaf"`, `goal` "external-research role: find the modern API replacement for …" |
+| any `subagent_type="plan"` call | a `delegate_task` child, `role:"leaf"`, `goal` "plan-generation role: produce the atomic refactor plan …" with the codemap inlined in `context` |
+| any `subagent_type="oracle"` verification call | a `delegate_task` child, `role:"leaf"`, `goal` "plan-review / verification role: confirm step <N> introduced no regression …" |
+| any background-output / wait-for-agent poll | nothing to call — the `delegate_task` batch already blocked until every child returned |
+| any persistent-team primitive ("team" tools) | there is no persistent team; re-dispatch a fresh `delegate_task` batch of `leaf` children each time |
+| `load_skills=[...]` | name the skills to load inside the child's `goal`/`context` text |
+
+When you need refactor lanes worked in parallel, dispatch them all in a **single**
+`delegate_task` batch and inline each lane's mandate. The plugin's `subagent_stop` hook
+logs each child as it finishes. If a code block below conflicts with this section, this
+section wins — every foreign delegation call in the prose below is a LEGACY illustration
+copied from another harness; never call any of them literally, map each to a
+`delegate_task` child.
+
+export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command
+
+## Usage
+\`\`\`
+/refactor <refactoring-target> [--scope=<file|module|project>] [--strategy=<safe|aggressive>]
+
+Arguments:
+  refactoring-target: What to refactor. Can be:
+    - File path: src/auth/handler.ts
+    - Symbol name: "AuthService class"
+    - Pattern: "all functions using deprecated API"
+    - Description: "extract validation logic into separate module"
+
+Options:
+  --scope: Refactoring scope (default: module)
+    - file: Single file only
+    - module: Module/directory scope
+    - project: Entire codebase
+
+  --strategy: Risk tolerance (default: safe)
+    - safe: Conservative, maximum test coverage required
+    - aggressive: Allow broader changes with adequate coverage
+\`\`\`
+
+## What This Command Does
+
+Performs intelligent, deterministic refactoring with full codebase awareness. Unlike blind search-and-replace, this command:
+
+1. **Understands your intent** - Analyzes what you actually want to achieve
+2. **Maps the codebase** - Builds a definitive codemap before touching anything
+3. **Assesses risk** - Evaluates test coverage and determines verification strategy
+4. **Plans meticulously** - Creates a detailed plan with Plan agent
+5. **Executes precisely** - Step-by-step refactoring with LSP and AST-grep
+6. **Verifies constantly** - Runs tests after each change to ensure zero regression
+
+---
+
+# PHASE 0: INTENT GATE (MANDATORY FIRST STEP)
+
+**BEFORE ANY ACTION, classify and validate the request.**
+
+## Step 0.1: Parse Request Type
+
+| Signal | Classification | Action |
+|--------|----------------|--------|
+| Specific file/symbol | Explicit | Proceed to codebase analysis |
+| "Refactor X to Y" | Clear transformation | Proceed to codebase analysis |
+| "Improve", "Clean up" | Open-ended | **MUST ask**: "What specific improvement?" |
+| Ambiguous scope | Uncertain | **MUST ask**: "Which modules/files?" |
+| Missing context | Incomplete | **MUST ask**: "What's the desired outcome?" |
+
+## Step 0.2: Validate Understanding
+
+Before proceeding, confirm:
+- [ ] Target is clearly identified
+- [ ] Desired outcome is understood
+- [ ] Scope is defined (file/module/project)
+- [ ] Success criteria can be articulated
+
+**If ANY of above is unclear, ASK CLARIFYING QUESTION:**
+
+\`\`\`
+I want to make sure I understand the refactoring goal correctly.
+
+**What I understood**: [interpretation]
+**What I'm unsure about**: [specific ambiguity]
+
+Options I see:
+1. [Option A] - [implications]
+2. [Option B] - [implications]
+
+**My recommendation**: [suggestion with reasoning]
+
+Should I proceed with [recommendation], or would you prefer differently?
+\`\`\`
+
+## Step 0.3: Create Initial Todos
+
+**IMMEDIATELY after understanding the request, create todos:**
+
+\`\`\`
+TodoWrite([
+  {"id": "phase-1", "content": "PHASE 1: Codebase Analysis - launch parallel explore agents", "status": "pending", "priority": "high"},
+  {"id": "phase-2", "content": "PHASE 2: Build Codemap - map dependencies and impact zones", "status": "pending", "priority": "high"},
+  {"id": "phase-3", "content": "PHASE 3: Test Assessment - analyze test coverage and verification strategy", "status": "pending", "priority": "high"},
+  {"id": "phase-4", "content": "PHASE 4: Plan Generation - invoke Plan agent for detailed refactoring plan", "status": "pending", "priority": "high"},
+  {"id": "phase-5", "content": "PHASE 5: Execute Refactoring - step-by-step with continuous verification", "status": "pending", "priority": "high"},
+  {"id": "phase-6", "content": "PHASE 6: Final Verification - full test suite and regression check", "status": "pending", "priority": "high"}
+])
+\`\`\`
+
+---
+
+# PHASE 1: CODEBASE ANALYSIS (PARALLEL EXPLORATION)
+
+**Mark phase-1 as in_progress.**
+
+## 1.1: Launch Parallel Codebase-Search Lanes
+
+Fan ALL of these out in **one** \`delegate_task\` batch — five \`leaf\` children that run in
+parallel. Each child plays the **codebase-search role**; inline its mandate in \`goal\`/\`context\`:
+
+\`\`\`
+delegate_task(tasks=[
+  // Lane 1: Find the refactoring target
+  {
+    role: "leaf",
+    goal: "codebase-search role: find all occurrences and definitions of [TARGET].",
+    context: "Report: file paths, line numbers, usage patterns."
+  },
+  // Lane 2: Find related code
+  {
+    role: "leaf",
+    goal: "codebase-search role: find all code that imports, uses, or depends on [TARGET].",
+    context: "Report: dependency chains, import graphs."
+  },
+  // Lane 3: Find similar patterns
+  {
+    role: "leaf",
+    goal: "codebase-search role: find similar code patterns to [TARGET] in the codebase.",
+    context: "Report: analogous implementations, established conventions."
+  },
+  // Lane 4: Find tests
+  {
+    role: "leaf",
+    goal: "codebase-search role: find all test files related to [TARGET].",
+    context: "Report: test file paths, test case names, coverage indicators."
+  },
+  // Lane 5: Architecture context
+  {
+    role: "leaf",
+    goal: "codebase-search role: find architectural patterns and module organization around [TARGET].",
+    context: "Report: module boundaries, layer structure, design patterns in use."
+  }
+])
+\`\`\`
+
+The batch blocks until all five children return; you receive every result together.
+
+## 1.2: Direct Tool Exploration (BEFORE OR AFTER THE BATCH)
+
+The \`delegate_task\` batch blocks the parent, so run these direct tools either before you
+dispatch the batch or after it returns — not concurrently with it:
+
+### LSP Tools for Precise Analysis:
+
+\`\`\`typescript
+// Find definition(s)
+LspGotoDefinition(filePath, line, character)  // Where is it defined?
+
+// Find ALL usages across workspace
+LspFindReferences(filePath, line, character, includeDeclaration=true)
+
+// Get file structure
+LspDocumentSymbols(filePath)  // Hierarchical outline
+LspWorkspaceSymbols(filePath, query="[target_symbol]")  // Search by name
+
+// Get current diagnostics
+lsp_diagnostics(filePath)  // Errors, warnings before we start
+\`\`\`
+
+### AST-Grep for Pattern Analysis:
+
+\`\`\`typescript
+// Find structural patterns
+ast_grep_search(
+  pattern="function $NAME($$$) { $$$ }",  // or relevant pattern
+  lang="typescript",  // or relevant language
+  paths=["src/"]
+)
+
+// Preview refactoring (DRY RUN)
+ast_grep_replace(
+  pattern="[old_pattern]",
+  rewrite="[new_pattern]",
+  lang="[language]",
+  dryRun=true  // ALWAYS preview first
+)
+\`\`\`
+
+### Grep for Text Patterns:
+
+\`\`\`
+grep(pattern="[search_term]", path="src/", include="*.ts")
+\`\`\`
+
+## 1.3: Collect Lane Results
+
+The single \`delegate_task\` batch from 1.1 already returned every lane's result together —
+there is nothing extra to poll. Read each child's findings (target locations, dependency
+chains, similar patterns, tests, architecture) straight from the batch result.
+
+**Mark phase-1 as completed after all results collected.**
+
+---
+
+# PHASE 2: BUILD CODEMAP (DEPENDENCY MAPPING)
+
+**Mark phase-2 as in_progress.**
+
+## 2.1: Construct Definitive Codemap
+
+Based on Phase 1 results, build:
+
+\`\`\`
+## CODEMAP: [TARGET]
+
+### Core Files (Direct Impact)
+- \`path/to/file.ts:L10-L50\` - Primary definition
+- \`path/to/file2.ts:L25\` - Key usage
+
+### Dependency Graph
+\`\`\`
+[TARGET]
+├── imports from:
+│   ├── module-a (types)
+│   └── module-b (utils)
+├── imported by:
+│   ├── consumer-1.ts
+│   ├── consumer-2.ts
+│   └── consumer-3.ts
+└── used by:
+    ├── handler.ts (direct call)
+    └── service.ts (dependency injection)
+\`\`\`
+
+### Impact Zones
+| Zone | Risk Level | Files Affected | Test Coverage |
+|------|------------|----------------|---------------|
+| Core | HIGH | 3 files | 85% covered |
+| Consumers | MEDIUM | 8 files | 70% covered |
+| Edge | LOW | 2 files | 50% covered |
+
+### Established Patterns
+- Pattern A: [description] - used in N places
+- Pattern B: [description] - established convention
+\`\`\`
+
+## 2.2: Identify Refactoring Constraints
+
+Based on codemap:
+- **MUST follow**: [existing patterns identified]
+- **MUST NOT break**: [critical dependencies]
+- **Safe to change**: [isolated code zones]
+- **Requires migration**: [breaking changes impact]
+
+**Mark phase-2 as completed.**
+
+---
+
+# PHASE 3: TEST ASSESSMENT (VERIFICATION STRATEGY)
+
+**Mark phase-3 as in_progress.**
+
+## 3.1: Detect Test Infrastructure
+
+\`\`\`bash
+# Check for test commands
+cat package.json | jq '.scripts | keys[] | select(test("test"))'
+
+# Or for Python
+ls -la pytest.ini pyproject.toml setup.cfg
+
+# Or for Go
+ls -la *_test.go
+\`\`\`
+
+## 3.2: Analyze Test Coverage
+
+\`\`\`
+// One codebase-search child; the batch blocks, so the result is available inline.
+delegate_task(tasks=[
+  {
+    role: "leaf",
+    goal: "codebase-search role: analyze test coverage for [TARGET].",
+    context: "Answer: 1. Which test files cover this code? 2. What test cases exist? "
+           + "3. Are there integration tests? 4. What edge cases are tested? "
+           + "5. Estimated coverage percentage?"
+  }
+])
+\`\`\`
+
+## 3.3: Determine Verification Strategy
+
+Based on test analysis:
+
+| Coverage Level | Strategy |
+|----------------|----------|
+| HIGH (>80%) | Run existing tests after each step |
+| MEDIUM (50-80%) | Run tests + add safety assertions |
+| LOW (<50%) | **PAUSE**: Propose adding tests first |
+| NONE | **BLOCK**: Refuse aggressive refactoring |
+
+**If coverage is LOW or NONE, ask user:**
+
+\`\`\`
+Test coverage for [TARGET] is [LEVEL].
+
+**Risk Assessment**: Refactoring without adequate tests is dangerous.
+
+Options:
+1. Add tests first, then refactor (RECOMMENDED)
+2. Proceed with extra caution, manual verification required
+3. Abort refactoring
+
+Which approach do you prefer?
+\`\`\`
+
+## 3.4: Document Verification Plan
+
+\`\`\`
+## VERIFICATION PLAN
+
+### Test Commands
+- Unit: \`bun test\` / \`npm test\` / \`pytest\` / etc.
+- Integration: [command if exists]
+- Type check: \`tsc --noEmit\` / \`pyright\` / etc.
+
+### Verification Checkpoints
+After each refactoring step:
+1. lsp_diagnostics → zero new errors
+2. Run test command → all pass
+3. Type check → clean
+
+### Regression Indicators
+- [Specific test that must pass]
+- [Behavior that must be preserved]
+- [API contract that must not change]
+\`\`\`
+
+**Mark phase-3 as completed.**
+
+---
+
+# PHASE 4: PLAN GENERATION (PLAN-GENERATION ROLE)
+
+**Mark phase-4 as in_progress.**
+
+## 4.1: Dispatch the plan-generation lane
+
+\`\`\`
+delegate_task(tasks=[{
+  role: "leaf",
+  goal: "plan-generation role: create a detailed refactoring plan.",
+  context: "Create a detailed refactoring plan:
+
+  ## Refactoring Goal
+  [User's original request]
+
+  ## Codemap (from Phase 2)
+  [Insert codemap here]
+
+  ## Test Coverage (from Phase 3)
+  [Insert verification plan here]
+
+  ## Constraints
+  - MUST follow existing patterns: [list]
+  - MUST NOT break: [critical paths]
+  - MUST run tests after each step
+
+  ## Requirements
+  1. Break down into atomic refactoring steps
+  2. Each step must be independently verifiable
+  3. Order steps by dependency (what must happen first)
+  4. Specify exact files and line ranges for each step
+  5. Include rollback strategy for each step
+  6. Define commit checkpoints"
+}])
+\`\`\`
+
+## 4.2: Review and Validate Plan
+
+After the plan-generation lane returns:
+
+1. **Verify completeness**: All identified files addressed?
+2. **Verify safety**: Each step reversible?
+3. **Verify order**: Dependencies respected?
+4. **Verify verification**: Test commands specified?
+
+## 4.3: Register Detailed Todos
+
+Convert the plan-generation lane's output into granular todos:
+
+\`\`\`
+TodoWrite([
+  // Each step from the plan becomes a todo
+  {"id": "refactor-1", "content": "Step 1: [description]", "status": "pending", "priority": "high"},
+  {"id": "verify-1", "content": "Verify Step 1: run tests", "status": "pending", "priority": "high"},
+  {"id": "refactor-2", "content": "Step 2: [description]", "status": "pending", "priority": "medium"},
+  {"id": "verify-2", "content": "Verify Step 2: run tests", "status": "pending", "priority": "medium"},
+  // ... continue for all steps
+])
+\`\`\`
+
+**Mark phase-4 as completed.**
+
+---
+
+# PHASE 5: EXECUTE REFACTORING (DETERMINISTIC EXECUTION)
+
+**Mark phase-5 as in_progress.**
+
+## 5.1: Execution Protocol
+
+For EACH refactoring step:
+
+### Pre-Step
+1. Mark step todo as \`in_progress\`
+2. Read current file state
+3. Verify lsp_diagnostics is baseline
+
+### Execute Step
+Use appropriate tool:
+
+**For Symbol Renames:**
+\`\`\`typescript
+lsp_prepare_rename(filePath, line, character)  // Validate rename is possible
+lsp_rename(filePath, line, character, newName)  // Execute rename
+\`\`\`
+
+**For Pattern Transformations:**
+\`\`\`typescript
+// Preview first
+ast_grep_replace(pattern, rewrite, lang, dryRun=true)
+
+// If preview looks good, execute
+ast_grep_replace(pattern, rewrite, lang, dryRun=false)
+\`\`\`
+
+**For Structural Changes:**
+\`\`\`typescript
+// Use Edit tool for precise changes
+edit(filePath, oldString, newString)
+\`\`\`
+
+### Post-Step Verification (MANDATORY)
+
+\`\`\`typescript
+// 1. Check diagnostics
+lsp_diagnostics(filePath)  // Must be clean or same as baseline
+
+// 2. Run tests
+bash("bun test")  // Or appropriate test command
+
+// 3. Type check
+bash("tsc --noEmit")  // Or appropriate type check
+\`\`\`
+
+### Step Completion
+1. If verification passes → Mark step todo as \`completed\`
+2. If verification fails → **STOP AND FIX**
+
+## 5.2: Failure Recovery Protocol
+
+If ANY verification fails:
+
+1. **STOP** immediately
+2. **REVERT** the failed change
+3. **DIAGNOSE** what went wrong
+4. **OPTIONS**:
+   - Fix the issue and retry
+   - Skip this step (if optional)
+   - Dispatch a plan-review lane (a \`delegate_task\` \`leaf\` child whose \`goal\` inlines the failure + ask for a fix strategy)
+   - Ask user for guidance
+
+**NEVER proceed to next step with broken tests.**
+
+## 5.3: Commit Checkpoints
+
+After each logical group of changes:
+
+\`\`\`bash
+git add [changed-files]
+git commit -m "refactor(scope): description
+
+[details of what was changed and why]"
+\`\`\`
+
+**Mark phase-5 as completed when all refactoring steps done.**
+
+---
+
+# PHASE 6: FINAL VERIFICATION (REGRESSION CHECK)
+
+**Mark phase-6 as in_progress.**
+
+## 6.1: Full Test Suite
+
+\`\`\`bash
+# Run complete test suite
+bun test  # or npm test, pytest, go test, etc.
+\`\`\`
+
+## 6.2: Type Check
+
+\`\`\`bash
+# Full type check
+tsc --noEmit  # or equivalent
+\`\`\`
+
+## 6.3: Lint Check
+
+\`\`\`bash
+# Run linter
+eslint .  # or equivalent
+\`\`\`
+
+## 6.4: Build Verification (if applicable)
+
+\`\`\`bash
+# Ensure build still works
+bun run build  # or npm run build, etc.
+\`\`\`
+
+## 6.5: Final Diagnostics
+
+\`\`\`typescript
+// Check all changed files
+for (file of changedFiles) {
+  lsp_diagnostics(file)  // Must all be clean
+}
+\`\`\`
+
+## 6.6: Generate Summary
+
+\`\`\`markdown
+## Refactoring Complete
+
+### What Changed
+- [List of changes made]
+
+### Files Modified
+- \`path/to/file.ts\` - [what changed]
+- \`path/to/file2.ts\` - [what changed]
+
+### Verification Results
+- Tests: PASSED (X/Y passing)
+- Type Check: CLEAN
+- Lint: CLEAN
+- Build: SUCCESS
+
+### No Regressions Detected
+All existing tests pass. No new errors introduced.
+\`\`\`
+
+**Mark phase-6 as completed.**
+
+---
+
+# CRITICAL RULES
+
+## NEVER DO
+- Skip lsp_diagnostics check after changes
+- Proceed with failing tests
+- Make changes without understanding impact
+- Use \`as any\`, \`@ts-ignore\`, \`@ts-expect-error\`
+- Delete tests to make them pass
+- Commit broken code
+- Refactor without understanding existing patterns
+
+## ALWAYS DO
+- Understand before changing
+- Preview before applying (ast_grep dryRun=true)
+- Verify after every change
+- Follow existing codebase patterns
+- Keep todos updated in real-time
+- Commit at logical checkpoints
+- Report issues immediately
+
+## ABORT CONDITIONS
+If any of these occur, **STOP and consult user**:
+- Test coverage is zero for target code
+- Changes would break public API
+- Refactoring scope is unclear
+- 3 consecutive verification failures
+- User-defined constraints violated
+
+---
+
+# Tool Usage Philosophy
+
+You already know these tools. Use them intelligently:
+
+## LSP Tools
+Leverage LSP tools for precision analysis. Key patterns:
+- **Understand before changing**: \`LspGotoDefinition\` to grasp context
+- **Impact analysis**: \`LspFindReferences\` to map all usages before modification
+- **Safe refactoring**: \`lsp_prepare_rename\` → \`lsp_rename\` for symbol renames
+- **Continuous verification**: \`lsp_diagnostics\` after every change
+
+## AST-Grep
+Use \`ast_grep_search\` and \`ast_grep_replace\` for structural transformations.
+**Critical**: Always \`dryRun=true\` first, review, then execute.
+
+## Delegation Roles
+
+Every role below is a \`delegate_task\` child — there is no agent registry and no named
+personas. Inline the role's mandate in the child's \`goal\`/\`context\`. Dispatch independent
+roles together in **one** \`delegate_task\` batch so they run in parallel:
+
+- **codebase-search role**: parallel codebase pattern discovery — locate the target, its
+  dependents, similar patterns, related tests, and architecture context.
+- **plan-generation role**: produce the detailed atomic refactor plan with verifiable steps,
+  ordering, exact files/line ranges, rollback strategy, and commit checkpoints.
+- **plan-review / verification role**: read-only consultation for complex architectural
+  decisions, debugging, and confirming a step introduced no regression.
+- **external-research role**: use when encountering deprecated methods or library-migration
+  tasks — query official docs and OSS examples for the modern replacements.
+
+## Deprecated Code & Library Migration
+When you encounter deprecated methods/APIs during refactoring:
+1. Dispatch an **external-research** lane (a \`delegate_task\` \`leaf\` child) to find the recommended modern alternative
+2. **DO NOT auto-upgrade to latest version** unless user explicitly requests migration
+3. If user requests library migration, use the **external-research** lane to fetch latest API docs before making changes
+
+---
+
+**Remember: Refactoring without tests is reckless. Refactoring without understanding is destructive. This command ensures you do neither.**
+
+<user-request>
+$ARGUMENTS
+</user-request>
+`
+
+export const REFACTOR_PARALLEL_DISPATCH_ADDENDUM = `
+---
+
+# Parallel Refactor Dispatch (Hermes \`delegate_task\`)
+
+When the plan has several file-independent steps, you can work them in parallel with the
+native \`delegate_task\` batch instead of executing each step inline. This addendum **refines
+Phase 4-6** — it does not introduce any new primitive. There is still only one orchestrator
+(you) and a set of \`leaf\` children dispatched per \`delegate_task\` batch; the parent blocks
+until every child in a batch returns. There is no persistent team, no team registry, no
+named worker personas, and no per-child model selection.
+
+## Phase 4 refinement: parallelism analysis in the plan
+
+When you dispatch the plan-generation lane in Phase 4.1, append this requirement to its
+\`goal\`/\`context\` so the plan tells you what is safe to parallelize — missing fields block
+Phase 5 batching:
+
+\`\`\`
+7. Output a Parallelism Analysis section with these fields:
+   - total_atomic_steps: integer
+   - file_independent_steps: integer (parallelizable, no cross-file blocker)
+   - cross_file_dependent_steps: integer (has blockers)
+   - per_step_class: [{step_id, class: 'mechanical' | 'reasoning', blockedBy: [step_ids], rationale}]
+   - dispatch_recommendation: 'parallel-batch' | 'sequential' with reason
+   - rationale for the grouping
+\`\`\`
+
+**Step classification** the plan-generation lane must apply to each step:
+- \`mechanical\`: LSP rename, extract variable, inline, simple move, signature change without call-site logic.
+- \`reasoning\`: logic-preserving refactors that need thought — extract function, restructure conditional, pattern transformation, cross-file API change.
+- Recommend \`parallel-batch\` when \`file_independent_steps >= 3\`; recommend \`sequential\` otherwise.
+
+## Phase 5 refinement: choose batch vs sequential
+
+Read the Parallelism Analysis from Phase 4. If any required field is missing, STOP and
+re-request the plan with the exact missing field names — do not batch from a partial plan.
+
+Then choose:
+
+- **Parallel-batch path (5.1-B)**: when the plan recommends \`parallel-batch\` AND \`file_independent_steps >= 3\`. Dispatch the independent steps as \`leaf\` children in one \`delegate_task\` batch.
+- **Sequential path (5.1-S)**: otherwise. Use the original 5.1 / 5.2 / 5.3 flow above.
+
+Record the chosen path in the TodoWrite list.
+
+## Phase 5.1-B: parallel-batch execution
+
+**Preconditions** (fail hard if any check fails):
+
+1. Confirm every step you intend to batch is marked \`file_independent\` (empty \`blockedBy\`) in the plan. Steps with blockers run sequentially in dependency order.
+2. Group steps so that no two children in the same batch touch the same file. Children share no state; overlapping edits would race.
+3. Inline each child's mandate fully — children do not see prior conversation. Each child receives its own slim brief.
+
+**Per-child brief** — every child you dispatch carries its full mandate inline in
+\`goal\`/\`context\`:
+
+- For a **mechanical** step: "mechanical-refactor role: apply this step verbatim — no scope
+  expansion. Use LSP tools for correctness. After edits, request \`lsp_diagnostics\` on
+  touched files. Return: files touched + diagnostics status + diff summary. Do not run
+  tests, do not git add."
+- For a **reasoning** step: "reasoning-refactor role: read this plan step carefully. Preview
+  with \`ast_grep_replace\` dryRun=true first, review, then execute. If the step is ambiguous
+  or would require out-of-scope changes, STOP and return \`UNCLEAR\` with the reason rather
+  than guessing. Return: files touched + diagnostics status + diff summary. Do not run
+  tests."
+
+**Dispatch the batch** — pass the shared refactor context (codemap summary, constraints,
+and established patterns from Phase 2) and the verification spec (exact test/typecheck/lint
+commands + expected pass counts + regression indicators from Phase 3.4) **inline in every
+child's \`context\`**; children cannot read a broadcast channel:
+
+\`\`\`
+delegate_task(tasks=[
+  {
+    role: "leaf",
+    goal: "<mechanical|reasoning>-refactor role: refactor step <N> — <short>",
+    context: "<per-step instructions: target files + line ranges + rollback strategy> "
+           + "<codemap summary + constraints + established patterns> "
+           + "<verify context for reference only — do NOT run tests>"
+  },
+  // ... one child per file-independent step, no two touching the same file ...
+])
+\`\`\`
+
+The batch blocks until every child returns. You receive all of their reports together.
+
+**After the batch returns** (orchestrator owns verification — children never run tests):
+
+- For each completed step, run the verification yourself, or dispatch a **plan-review /
+  verification** lane as a \`leaf\` child whose \`goal\` inlines the touched files + the verify
+  commands and asks it to return \`PASS\` or \`FAIL:<failing test + specific error + suggested
+  revert hunks>\`. Do not create a commit checkpoint until verification is PASS.
+- On PASS: make the commit checkpoint for that step (see original 5.3). Proceed.
+- On FAIL: decide —
+  - **Retry with fix hint**: re-dispatch that one step as a fresh \`leaf\` child whose \`context\` inlines the specific failure from verification.
+  - **Escalate**: after three FAIL cycles on the same step, STOP and consult the user with full evidence.
+- On a child returning \`UNCLEAR\`: re-harvest context with a targeted codebase-search lane, then re-dispatch that step with the clarified brief inlined.
+
+Proceed to Phase 6 only when every batched step is committed AND every paired verification returned PASS.
+
+## Phase 6 refinement: report the dispatch path
+
+Append to the 6.6 summary a "Dispatch path" line and, when the parallel-batch path was used,
+the batch metrics (batches dispatched, children per batch, verification lanes run).
+
+## MUST NOT (parallel-batch)
+
+- Never put two children that touch the same file in the same batch — they race.
+- Do not assume a child can see prior conversation, a broadcast, or another child's output — inline everything each child needs.
+- Children never run tests or commit — the orchestrator owns verification and the commit checkpoints.
+- Do not invent a persistent team or a named-agent registry; every lane is a fresh \`delegate_task\` \`leaf\` child whose mandate is inlined.
+`