<purpose>

Migrate `.planning/` from sequential to parallel organizational mode via a single atomic commit. Validates preconditions (clean working tree + sequential source + ≤1 milestone In Progress + valid kebab-case slug), runs interactive D7 research-file disposition (or accepts `--all-milestone` / `--all-project` bulk-override), commits as ONE atomic migration commit.

Phase 68-01 (v1.5.9 Parallel Milestone Organization, MIGR-01 + MIGR-03 partial) ships this command end-to-end:
- Library `bin/lib/migrate-to-parallel.js` (migrateToParallel + buildOpsList + executeMigration; sibling tests 22/22 PASS including 2 mutation-RED probes)
- Shared helper `bin/lib/migrate-dry-run.js` (formatPlannedOperationsReport + EXIT_DRYRUN=10; FOUND-04 2-use-site extraction)
- CLI dispatch arm in `bin/gmd-tools.cjs` parses --dry-run/--yes/--all-milestone/--all-project flags
- Synthetic fixture `tests/fixtures/parallel-mode-multi-milestone/sequential-baseline/` for unit + acceptance tests
- Slash-command shim at `C:/Users/Christopher/.claude/commands/gmd/migrate-to-parallel.md`

Fail-loud discipline (per 68-CONTEXT.md Gates 1+3 + TD-07 + Phase 66 R3 precedent):
- Dirty-working-tree refuse (Gate 3 R1)
- Already-parallel refuse (asymmetric source state)
- Multi-In-Progress refuse (sequential anomaly)
- --yes safety refuse with research files but no bulk-override (Gate 3 R3)
- --all-milestone + --all-project mutual-exclusivity refuse

</purpose>

<required_reading>

Read all files referenced by the invoking prompt's execution_context before starting.

</required_reading>

<process>

## 0. Load Mode + Validate Slug Argument

Run the state-load init to retrieve organizational mode:

```bash
MODE=$(node bin/gmd-tools.cjs state load --raw 2>/dev/null | grep -i organizational_mode | cut -d= -f2 || echo "sequential")
```

If `MODE === 'parallel'`, the library refuses with the LOCKED message; surface the refusal and exit. The library is the single source of truth for refusal — the workflow does not re-implement validation.

Capture the user's slug argument as `$TARGET_SLUG` (positional arg 1). Capture flag arguments: `--dry-run`, `--yes`, `--all-milestone`, `--all-project`.

## 1. Dry-Run First (Always)

Always run `--dry-run` internally as Step 1 to surface refuse messages BEFORE any prompts. This separates validation from mutation; users see precondition violations early.

```bash
DRYRUN_FLAGS=""
if [[ "$ALL_MILESTONE" == "true" ]]; then DRYRUN_FLAGS="--all-milestone"; fi
if [[ "$ALL_PROJECT"   == "true" ]]; then DRYRUN_FLAGS="--all-project";   fi

node bin/gmd-tools.cjs migrate-to-parallel "$TARGET_SLUG" --dry-run $DRYRUN_FLAGS
DRYRUN_EXIT=$?
```

Outcomes:
- `exit 10` (EXIT_DRYRUN sentinel) → dry-run succeeded; report printed to stdout
- `exit 1` → precondition violation; refuse message printed to stderr; workflow exits 1
- Any other exit → unexpected; workflow exits non-zero with the captured message

## 2. Display Planned Operations

The stdout from Step 1 is the planned-operations report (formatted by `formatPlannedOperationsReport`). Surface it verbatim so the user can review:

```
=== Planned Migration to parallel (target: <slug>) ===

## Planned File Moves
- mv .planning/REQUIREMENTS.md → .planning/milestones/<slug>/REQUIREMENTS.md
...

## Planned Rollback Command
- git reset --hard HEAD && git clean -fd <touched-paths-joined>
```

If `--dry-run` was passed by the user (NOT an internal step-1 dry-run), exit 0 here without proceeding — the report is the deliverable.

## 3. Resolve Research-File Dispositions (D7 Interactive)

SKIP this step if:
- `--all-milestone` was passed (every research file → 'milestone')
- `--all-project` was passed (every research file → 'project')
- `--yes` was passed AND research files require disposition (library already refused in Step 1)

Otherwise, parse the `## Would Prompt For (D7 Interactive Disposition)` section from the dry-run output. For EACH listed file, spawn an `AskUserQuestion` with 3 options:

```
Where should '.planning/research/<file>' go after migration?
1. Milestone-specific (Recommended)  → moves under .planning/milestones/<slug>/research/
2. Project-level cross-cutting       → stays at .planning/research/
3. Skip (keep at .planning/research/) → identical to project-level; signals intent
```

Build a comma-separated dispositions string for Step 5 (the library re-accepts via `flags.dispositions` parameter, but for slash-command-driven invocations a `--disposition <file>=<value>,...` flag is the surface; default is to chain --all-milestone for the bulk case).

## 4. Confirm

If `--yes` was NOT passed, ask one final confirmation:

```
Proceed with migration? [y/N]
```

Default is `N` (safer). On `n` / empty / non-y input, print `Migration cancelled.` and exit 0.

## 5. Execute Migration

Re-invoke the CLI without `--dry-run`:

```bash
EXEC_FLAGS=""
if [[ "$YES" == "true" ]] || [[ -n "$RESOLVED_DISPOSITIONS" ]]; then EXEC_FLAGS="$EXEC_FLAGS --yes"; fi
if [[ "$ALL_MILESTONE" == "true" ]]; then EXEC_FLAGS="$EXEC_FLAGS --all-milestone"; fi
if [[ "$ALL_PROJECT"   == "true" ]]; then EXEC_FLAGS="$EXEC_FLAGS --all-project";   fi

node bin/gmd-tools.cjs migrate-to-parallel "$TARGET_SLUG" $EXEC_FLAGS
EXEC_EXIT=$?
```

The library re-validates all preconditions (defense-in-depth — Step 1's dry-run state may have drifted between Step 2 and Step 5) and executes the single-commit atomic migration. On any mid-step failure, the library performs scoped rollback (`git reset --hard HEAD && git clean -fd <touched-paths>`) and throws; this workflow surfaces the error and exits non-zero.

## 6. Report Result

On success (exit 0), the CLI prints:

```
Migrated to parallel. Active milestone: <slug>. Commit: <short-sha>
```

Surface the message and recommend the next action:

```
Migrated to parallel. Active milestone: <slug>.
Run /gmd:plan-phase to plan the first phase of <slug>,
or /gmd:list-milestones to see the multi-milestone index.
```

</process>

<failure_handling>

ALL refusals are emitted by the library to stderr with EXIT 1. The workflow surfaces them verbatim — never paraphrases. LOCKED refusal messages (asserted byte-for-byte in `bin/lib/migrate-to-parallel.test.cjs`):

- Dirty tree: `refusing migration: working tree not clean. Commit or stash changes before running /gmd:migrate-to-parallel.`
- Already parallel: `refusing migration: organizational_mode already 'parallel'. /gmd:migrate-to-parallel is sequential→parallel only.`
- Multi-In-Progress: `refusing migration: <N> milestones In Progress (...); sequential mode expects ≤1. Resolve manually before migrating.`
- --yes without disposition: `refusing --yes migration: <N> research files require explicit disposition. Use --all-milestone, --all-project, or run interactively.`
- Mutual exclusivity: `refusing migration: --all-milestone and --all-project are mutually exclusive`
- Invalid slug: `refusing migration: <validateKebabSlug error>`

Mid-step failure rollback: scoped via `git reset --hard HEAD && git clean -fd <touched-paths>` (NOT global `git clean -fd .`). Verified by test E2 + mutation-RED probe G2. The library catches the original error, performs rollback, re-throws — the workflow exits non-zero with the original message.

</failure_handling>

<carryforward>

DEFER-65-01 RESOLVED (Phase 69-02): `bin/lib/mirror-check.js` SCOPES extended to cover `workflows/*.md` (and `templates/*.md`). Per-plan `cp + diff -q + git add -f` discipline OBVIATED — mirror byte-identity for this workflow file is now pre-commit-hook enforced via the SCOPES walker.

DEFER-66-02 RESOLVED (Phase 69-02): template-path resolution for parallel-mode milestone scaffolding shifted into the library `bin/lib/migrate-to-parallel.js` (renderMilestoneTemplateBody → opts.repoRoot + 'templates'). This workflow itself contains no HOME-hardcoded template path — it delegates all migration mechanics to the library. Companion workflows that DO contain template-path code (`workflows/new-project.md` Step 3.6 + `workflows/new-milestone.md` parallel branch 1P.3) now consume `bin/lib/get-template-root.js` (the helper introduced same plan). Future evolution of the migrate-to-parallel library may consume `getTemplateRoot()` in place of the current `opts.repoRoot + 'templates'` pattern for npm-global install compatibility; tracked as a follow-on refinement (non-blocking — current dev-repo invocations work).

P1 sequential-mode byte-identical regression: this migration command is ADDITIVE. Existing sequential-mode commands (e.g., `/gmd:progress`, `/gmd:plan-phase`, `/gmd:execute-phase` against sequential-mode projects) are unchanged in this plan. Final P1 verification in Task 3 of 68-01-PLAN.md.

Plan 68-02 consumes `bin/lib/migrate-dry-run.js` (LOCKED signatures) for the reverse direction (`/gmd:migrate-to-sequential`). Plan 68-03 acceptance test against tradesrv3 verifies real-world D9 set-equal modulo allowed-differ list.

</carryforward>
