kata-move-phase

What this skill does

<objective>
Move a pending phase to a different milestone or reorder phases within a milestone.

Purpose: Enable flexible phase reorganization (cross-milestone moves and within-milestone reordering).
Output: Phase moved/reordered, directories renamed, ROADMAP.md updated, STATE.md updated, git commit as historical record.

**Supported operations:**
- Cross-milestone move: `/kata-move-phase 3 to v1.6.0`
- Reorder within milestone: `/kata-move-phase 3 before 1` or `/kata-move-phase 3 after 1`
</objective>

<execution_context>
@.planning/ROADMAP.md
@.planning/STATE.md
</execution_context>

<process>

<step name="parse_arguments">
Parse the command arguments. First arg is always the phase number (integer).

**Detect operation type from second arg:**
- `"to"` + milestone version → cross-milestone move
- `"before"` or `"after"` + target phase number → reorder within milestone

**Cross-milestone move:**
- `/kata-move-phase 3 to v1.6.0`

**Reorder within milestone:**
- `/kata-move-phase 3 before 1` → Phase 3 takes position 1, everything shifts up
- `/kata-move-phase 3 after 1` → Phase 3 takes position 2, phases 2+ shift up

**Validation:**
- If no arguments or missing second arg:

```
ERROR: Phase number and operation required
Usage: /kata-move-phase <phase> to <milestone>
       /kata-move-phase <phase> before|after <position>
```

Exit.

- If second arg is not "to", "before", or "after":

```
ERROR: Invalid operation "{arg}"
Expected: to, before, or after
```

Exit.

Store: PHASE_NUM, OPERATION (move|reorder), and either TARGET_MILESTONE or POSITION+TARGET_POSITION.
</step>

<step name="preflight_roadmap_format">
**Pre-flight: Check roadmap format (auto-migration)**

If ROADMAP.md exists, check format and auto-migrate if old:

```bash
if [ -f .planning/ROADMAP.md ]; then
  node "${CLAUDE_PLUGIN_ROOT}/skills/kata-move-phase/scripts/kata-lib.cjs" check-roadmap 2>/dev/null
  FORMAT_EXIT=$?
  
  if [ $FORMAT_EXIT -eq 1 ]; then
    echo "Old roadmap format detected. Running auto-migration..."
  fi
fi
```

**If exit code 1 (old format):**

Invoke kata-doctor in auto mode:

```
Skill("kata-doctor", "--auto")
```

Continue after migration completes.

**If exit code 0 or 2:** Continue silently.
</step>

<step name="load_state">
Load project state:

```bash
cat .planning/STATE.md 2>/dev/null
cat .planning/ROADMAP.md 2>/dev/null
```

Parse current milestone version from ROADMAP.md. Use the "Current Milestone:" heading or `🔄` line marker:
```bash
VERSION=$(grep -E "Current Milestone:|🔄" .planning/ROADMAP.md | grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 | tr -d 'v')
```
</step>

<step name="validate_phase_exists">
Verify the phase exists in ROADMAP.md and find its directory:

1. Search for `#### Phase {N}:` heading within the current milestone
2. Use universal phase discovery (search active/pending/completed with padded and unpadded names, fallback to flat)
3. If not found: `ERROR: Phase {N} not found in roadmap` + list available phases. Exit.
</step>

<step name="validate_phase_movable">
Verify the phase can be moved/reordered:

1. **Must be in pending/** (not active or completed). If not: `ERROR: Phase {N} is in {state}/ and cannot be moved`. Exit.
2. **Must not have SUMMARY.md files** (no executed plans). If found: `ERROR: Phase {N} has completed work`. Exit.
</step>

<step name="validate_target_milestone">
**Cross-milestone move only.** Skip for reorder operations.

1. Target milestone heading must exist in ROADMAP.md. If not: `ERROR: Milestone {target} not found` + list available. Exit.
2. Target must differ from source. If same: `ERROR: Phase already in {milestone}. Use before/after to reorder.` Exit.
</step>

<step name="validate_reorder_target">
**Reorder only.** Skip for cross-milestone moves.

Validate the target position phase exists in the same milestone:

1. Target position phase must exist in ROADMAP.md within the current milestone
2. Target can be any state (active, pending, completed) since we're reordering the roadmap listing
3. The phase being moved must be pending (already validated in validate_phase_movable)

Calculate the effective target position:
- `before N` → target position = N (phase takes position N, everything at N+ shifts up)
- `after N` → target position = N+1 (phase takes position N+1, everything at N+1+ shifts up)

If target position phase not found:

```
ERROR: Phase {target_position} not found in current milestone
Available phases: [list phase numbers]
```

Exit.
</step>

<step name="confirm_reorder">
**Reorder only.** Skip for cross-milestone moves.

Show the planned reorder and wait for confirmation:

```
Reordering Phase {N}: {Name}

Current order:
  Phase 1: {name}
  Phase 2: {name}
  Phase 3: {name}

New order:
  Phase 1: {name}  (was Phase 3)
  Phase 2: {name}  (was Phase 1)
  Phase 3: {name}  (was Phase 2)

This will renumber all phase directories and update ROADMAP.md.

Proceed? (y/n)
```

Wait for confirmation.
</step>

<step name="reorder_roadmap">
**Reorder only.** Skip for cross-milestone moves.

Update ROADMAP.md to reflect the new phase order:

1. Extract all phase sections within the current milestone
2. Remove the moving phase section from its current position
3. Insert it at the target position
4. Renumber ALL phase headings in the milestone sequentially (1, 2, 3, ...)
5. Update all references within the milestone:
   - Phase headings: `#### Phase {old}:` -> `#### Phase {new}:`
   - Phase list entries
   - Progress table rows
   - Plan references: `{old}-01:` -> `{new}-01:`
   - Dependency references: `Depends on: Phase {old}` -> `Depends on: Phase {new}`
   - Decimal phase references if any

Write updated ROADMAP.md.
</step>

<step name="renumber_all_directories">
**Reorder only.** Skip for cross-milestone moves.

Rename ALL phase directories in the milestone to match new numbering. Use a three-pass approach to avoid collision:

1. **Pass 1:** Move the reordering phase to a temp name (`tmp-{slug}`)
2. **Pass 2:** Renumber all remaining phases sequentially. Process order matters:
   - Phases shifting down (higher->lower): process lowest first
   - Phases shifting up (lower->higher): process highest first
   - For each: find across state subdirectories, rename directory and internal files
3. **Pass 3:** Move temp directory to its final numbered position, rename internal files

Handle decimal phases: they follow their parent integer phase and renumber accordingly.
</step>

<step name="calculate_destination_number">
**Cross-milestone move only.** Skip for reorder operations.

Find next phase number in target milestone: parse `#### Phase N:` headings, take highest + 1 (or 1 if empty). Format as two-digit padded.
</step>

<step name="confirm_move">
**Cross-milestone move only.** Skip for reorder operations.

Show: source milestone, target milestone, new phase number, directory rename, number of phases to renumber in source. Wait for confirmation.
</step>

<step name="remove_from_source_milestone">
**Cross-milestone move only.** Skip for reorder operations.

Remove phase section from source milestone in ROADMAP.md and renumber remaining phases to close the gap. Follow the same renumbering approach as kata-remove-phase:
- Phase headings, list entries, progress table rows
- Plan references (`{old}-01:` -> `{new}-01:`)
- Dependency references (`Depends on: Phase {old}` -> `Phase {new}`)
- Decimal phase references
</step>

<step name="add_to_target_milestone">
**Cross-milestone move only.** Skip for reorder operations.

Insert phase section into target milestone in ROADMAP.md at the calculated destination number. Preserve goal, requirements, success criteria. Remove or note cross-milestone dependency references that no longer apply.
</step>

<step name="rename_phase_directory">
**Cross-milestone move only.** Skip for reorder operations (handled by renumber_all_directories).

Rename phase directory to new number within pending/. Rename all files inside (PLAN.md, RESEARCH.md, etc.) to match. Handle decimal phases (N.1, N.2