DUPES=$(for state in active pending completed; do
  ls .planning/phases/${state}/ 2>/dev/null
done | grep -oE '^[0-9]+' | sort -n | uniq -d)

If no duplicates found:

Exit.
</step>

<step name="validate_environment">

Read ROADMAP.md and STATE.md. Confirm project is active:

```bash
[ -f .planning/ROADMAP.md ] || { echo "ERROR: No ROADMAP.md found. Not a Kata project."; exit 1; }
[ -f .planning/STATE.md ] || { echo "ERROR: No STATE.md found. Not a Kata project."; exit 1; }

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► PHASE MIGRATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Duplicate prefixes detected: [list]
◆ Building chronology from ROADMAP.md...

GLOBAL_SEQ=0
CHRONOLOGY=""

Decimal phases (2.1, 2.2) get sequential integer numbers after their parent. Document order determines sequence.

Display: `Chronology ([N] phases): 00 → foundation, 01 → api-endpoints, ...`
</step>

<step name="map_directories_to_phases">

Match each phase name from the chronology to its existing directory. Search across `active/`, `pending/`, `completed/`, and flat fallback.

For each chronology entry `{seq} {name}`:
1. Find directories whose slug matches `{name}` across all states
2. If multiple matches, use the one whose numeric prefix matches the original milestone-local number
3. Build mapping: `STATE/OLD_DIR → STATE/NEW_PREFIX-SLUG`

Strip numeric prefix from each directory name to get slug, compare against chronology name. Build `MAPPING` as newline-delimited entries: `STATE/OLD_DIR → PADDED-SLUG`.

Display the full mapping table.
</step>

<step name="present_migration_plan">

Display the rename table:

Use AskUserQuestion:
- header: "Migration"
- question: "Rename [N] directories to globally sequential numbers?"
- options:
  - "Proceed" — Execute all renames
  - "Cancel" — Abort migration

If cancelled, exit with "Migration cancelled."
</step>

<step name="execute_renames">

Two-pass approach to avoid mid-rename collisions (established pattern from `kata-move-phase`):

**Pass 1:** Rename all directories to temporary names: `mv OLD tmp-{seq}-{slug}`

**Pass 2:** Rename from temporary to final: `mv tmp-{seq}-{slug} {padded}-{slug}`

For active/pending phases in Pass 2, also rename internal files (`*-PLAN.md`, `*-RESEARCH.md`, `*-CONTEXT.md`, `*-SUMMARY.md`) by replacing the old phase prefix with the new padded prefix: `sed "s/^[0-9.]*-/${PADDED}-/"`.

Completed phase internal files left unchanged. Wildcard lookup (`*-PLAN.md`) handles them.

Display:

</step>

<step name="update_documentation">

**Update ROADMAP.md current milestone phase numbers:**

For the current (non-archived) milestone section, update `#### Phase N:` headings to use new global numbers. Match phase names to chronology to determine correct new number.

**Update STATE.md current position:**

Update the current phase reference to use the new global number. Find the line referencing the active phase and update its number.

**Leave historical `<details>` blocks unchanged.** They are archived records. Milestone archive files in `.planning/milestones/` are authoritative.

Display:

</step>

<step name="verify">

Re-run collision detection:

```bash
DUPES=$(for state in active pending completed; do
  ls .planning/phases/${state}/ 2>/dev/null
done | grep -oE '^[0-9]+' | sort -n | uniq -d)

FLAT_DUPES=$(ls .planning/phases/ 2>/dev/null | grep -E '^[0-9]' | grep -oE '^[0-9]+' | sort -n | uniq -d)

ALL_DUPES=$(echo -e "${DUPES}\n${FLAT_DUPES}" | sort -nu | grep -v '^$')

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► MIGRATION COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ [N] directories renamed to globally sequential numbers
✓ No duplicate prefixes remain
✓ ROADMAP.md and STATE.md updated

COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

git add .planning/phases/ .planning/ROADMAP.md .planning/STATE.md
git commit -m "$(cat <<'EOF'
chore: migrate phase directories to globally sequential numbering
EOF
)"