# Workflow: compass:migrate

You are the migrate agent. Mission: migrate a project's `.compass/.state/` layout from Compass v0.x to v1.0 safely and idempotently.

**Principles:** Idempotent (safe to re-run). Back up before rewriting. Never destroy user data — on any unclear state, stop and surface the issue.

**Purpose**: Promote a legacy `.compass/.state/` layout (v0.x) to the v1.0 shape, creating `project-memory.json` and reorganizing sessions so subsequent commands work without surprises.

**Output**: A summary printed to the terminal. No documents are produced.

---

Apply the UX rules from `core/shared/ux-rules.md`.

> **Additional rule for migrate**: Migrate pre-dates the project registry, so if `resolve-project` returns `status=none` (or the config is missing), fall back to operating at `cwd` and proceed. Default `lang` to `en` when no config is available.

---

## Step 0 — Resolve active project

Apply the shared snippet from `core/shared/resolve-project.md`. It sets up `$PROJECT_ROOT`, `$CONFIG`, and `$PROJECT_NAME` for downstream steps and prints the "Using: <name>" banner.

**Migrate-specific `status=none` handler**: if the registry is empty OR no `$PROJECT_ROOT` can be resolved (pre-registry layouts), skip the ambiguous/none prompts from the shared snippet and continue with `$PROJECT_ROOT="$(pwd)"`. The migration CLI is designed to bootstrap legacy projects, so this graceful fallback is expected.

Extract `lang` from `$CONFIG` (default: `en`). Config missing is OK — migrate does not require it.

---

## Step 1 — Run migration

Call the CLI against the resolved project root (falls back to `cwd` per Step 0):

```bash
compass-cli migrate "$PROJECT_ROOT"
```

The CLI:
- Detects whether `.compass/.state/` is already v1.0 (no-op in that case).
- Writes backups into `$PROJECT_ROOT/.compass/.state/.backup-<ISO>/` before rewriting any file.
- Creates `$PROJECT_ROOT/.compass/.state/project-memory.json` if it doesn't exist.
- Promotes legacy session files into the v1.0 layout.
- Prints a JSON object on stdout summarizing what happened.

**Edge cases:**
- `compass-cli` not on PATH → show: `"⚠ compass-cli not found. Re-run ~/.compass/bin/install and try again."` Stop.
- Exit code ≠ 0 → read stderr, surface the first meaningful line, and stop. Do NOT retry blindly.
- Stdout is not valid JSON → show the raw output as-is and stop.

---

## Step 2 — Parse JSON result

Expected keys (fields may be added over time — ignore unknown keys):

- `already_v1` — boolean. True when nothing needed to change.
- `sessions_migrated` — integer count of session directories promoted.
- `backups_written` — integer count of backup files created.
- `project_memory` — one of `"created"` | `"exists"` | `"skipped"`.
- `errors` — array of `{ file, message }` objects. Empty array = success.

Parse with `jq` or `python3 -c "import json,sys; ..."`. If parsing fails, treat as a hard error (Step 1 edge case).

---

## Step 3 — Display summary

**If `already_v1 = true`:**
Print: `"✓ Already on v1.0 state layout — nothing to migrate."`

**If migration ran (no errors):**

```
✓ Migrated to v1.0 state layout.

  Sessions migrated:   <sessions_migrated>
  Backups written:     <backups_written>  →  $PROJECT_ROOT/.compass/.state/.backup-<ISO>/
  project-memory.json: <project_memory>   ("created" or "exists")

  Safe to re-run anytime — migrate is idempotent.
```

(AI translates per `$LANG` — see `core/shared/ux-rules.md` Language Policy.)

---

## Step 4 — Handle errors (if any)

If `errors` is non-empty, list each entry and give an actionable next step. Do NOT pretend success.

```
⚠ Migration completed with <N> issue(s):

  • <file>: <message>

  Your original files are preserved in $PROJECT_ROOT/.compass/.state/.backup-<ISO>/.
  Fix the issue above and re-run: /compass:migrate
```

Exit code is still 0 for partial success — the user decides whether to re-run.

---

## Edge cases summary

| Situation | Behavior |
|---|---|
| No `$PROJECT_ROOT/.compass/` folder | CLI returns `{"already_v1": false, "sessions_migrated": 0, "project_memory": "skipped"}` — tell user to run `/compass:init` first |
| Already v1.0 | "Already on v1.0 state layout" — stop |
| `compass-cli` not installed | Point to `~/.compass/bin/install` |
| Non-zero exit | Surface stderr, do NOT retry |
| Invalid JSON on stdout | Show raw output, do NOT retry |
| Partial errors | List each one, point to the backup path |

---

## Final — Hand-off

Print:

`✓ Migration complete. Run `/compass:status` to verify the migrated state.`

(AI translates per `$LANG` — see `core/shared/ux-rules.md` Language Policy.)

Then stop. Do NOT auto-invoke the next workflow.