compass-st 1.1.2

package/core/workflows/init.md

@@ -0,0 +1,524 @@
+# Workflow: compass:init (v1.1.1 smart-detect)
+
+You are the onboarding orchestrator. Mission: set up the right thing for the right context. One entry point, 3 modes:
+
+- **Mode A** (first-time global): `~/.compass/global-config.json` does NOT exist → run the global preferences wizard, then proceed to Mode B.
+- **Mode B** (project-create): cwd has no `.compass/.state/config.json` → ask to create a new Compass project at cwd, set up Silver Tiger folder structure, register in `~/.compass/projects.json`, set as `last_active`.
+- **Mode C** (config-update): cwd already has `.compass/.state/config.json` → ask which field(s) to update, edit in place.
+
+All user-facing text uses `lang` from `~/.compass/global-config.json` if set, else `en`. Apply the UX rules from `core/shared/ux-rules.md` throughout. `compass:init` is the ONE workflow that does NOT include `core/shared/resolve-project.md` at Step 0 — it IS the setup that produces the registry/global-config files the resolver depends on.
+
+> **Additional rules for init**:
+> - Before language is chosen (Mode A) OR loaded from global config, default to English. Do not mix languages mid-flow.
+> - Show progress implicitly via cumulative checkmarks (e.g. `✓ Global ✓ Project → Structure...`) — never expose internal step or mode names to the user.
+> - Every invocation starts fresh. If the user dismissed or aborted a previous run of this workflow (in the same conversation), DISCARD all prior answers. Re-detect mode every time.
+> - When the workflow falls through from Mode A → Mode B in the same run, the global wizard's answers serve as defaults for project setup — do not re-ask the same field unless the PO opts to override.
+
+---
+
+## Step 0 — Detect mode (silent)
+
+Run BEFORE any output:
+
+```bash
+# Does global config exist?
+if [ ! -f "$HOME/.compass/global-config.json" ]; then
+  MODE="A"
+elif [ -f ".compass/.state/config.json" ]; then
+  MODE="C"
+else
+  MODE="B"
+fi
+```
+
+Then print exactly one banner before proceeding (raw English here — `lang` is not yet known in Mode A; in B/C the global default `lang` is loaded and the banner is rendered in that language — see translations below):
+
+| Mode | en banner | vi banner |
+|------|-----------|-----------|
+| A    | `👋 First-time setup — configuring global Compass preferences...` | (always en — language not chosen yet) |
+| B    | `📦 Creating Compass project at $(pwd)...` | `📦 Đang tạo project Compass tại $(pwd)...` |
+| C    | `🔧 Updating Compass config for $(basename $(pwd))...` | `🔧 Đang cập nhật cấu hình Compass cho $(basename $(pwd))...` |
+
+For Mode B / Mode C: load `lang` first via `compass-cli project global-config get --key lang` (default `en` if missing), then print the matching banner.
+
+After the banner, branch on `$MODE`:
+- `A` → Step 1, then fall through to Step 2.
+- `B` → Step 2.
+- `C` → Step 3.
+
+---
+
+## Step 1 (Mode A only) — Global wizard
+
+The aim: capture the PO's defaults once so subsequent project creates pre-fill cleanly. All Mode A text is in English (the language hasn't been chosen yet).
+
+### 1a. Batch the four global questions
+
+Use a single `AskUserQuestion` call (`ux-rules` permits 1–4 questions per call). Use this EXACT JSON shape:
+
+```json
+{"questions": [
+  {"question": "Which language should Compass speak with you?", "header": "Language", "multiSelect": false, "options": [
+    {"label": "Tiếng Việt", "description": "Chat + tài liệu đều tiếng Việt"},
+    {"label": "English", "description": "Chat + docs all in English"}
+  ]},
+  {"question": "What's your default tech stack? (pick all that apply)", "header": "Tech stack", "multiSelect": true, "options": [
+    {"label": "typescript", "description": "TypeScript / JavaScript projects"},
+    {"label": "python", "description": "Python services / scripts"},
+    {"label": "rust", "description": "Rust binaries / libraries"},
+    {"label": "go", "description": "Go services"},
+    {"label": "java", "description": "Java / Kotlin / JVM"},
+    {"label": "None — tôi sẽ chọn per-project", "description": "Skip default; choose stack each time"}
+  ]},
+  {"question": "Default review style for documents?", "header": "Review style", "multiSelect": false, "options": [
+    {"label": "whole_document", "description": "Review the full doc end-to-end in one pass"},
+    {"label": "section_by_section", "description": "Walk section by section, confirm each before moving on"}
+  ]},
+  {"question": "Default product domain?", "header": "Domain", "multiSelect": false, "options": [
+    {"label": "ard", "description": "Anti Reverse / Defense"},
+    {"label": "platform", "description": "Platform / infra"},
+    {"label": "communication", "description": "Communication products"},
+    {"label": "internal", "description": "Internal tooling"},
+    {"label": "access", "description": "Access / identity"},
+    {"label": "ai", "description": "AI products / agents"},
+    {"label": "None — ask per-project", "description": "No default; ask every project"}
+  ]}
+]}
+```
+
+### 1b. Map answers and persist via the CLI
+
+- `Tiếng Việt` → `lang=vi`. `English` → `lang=en`.
+- Multi-select tech stack → JSON array (e.g. `["typescript","python"]`). If `None — tôi sẽ chọn per-project` selected, save `[]`.
+- Review style → save the literal label (`whole_document` / `section_by_section`).
+- Domain → save the literal label, or `null` if `None — ask per-project`.
+
+```bash
+compass-cli project global-config set --key lang --value "<lang>"
+compass-cli project global-config set --key default_tech_stack --value '<json-array>'
+compass-cli project global-config set --key default_review_style --value "<style>"
+compass-cli project global-config set --key default_domain --value "<domain-or-null>"
+```
+
+`global-config set` creates `~/.compass/global-config.json` on first write and stamps `created_at` / `updated_at`.
+
+### 1c. Echo summary (in the just-saved `lang`)
+
+en:
+```
+✓ Global preferences saved to ~/.compass/global-config.json
+   Language:        <lang>
+   Tech stack:      <list or "(none)">
+   Review style:    <style>
+   Default domain:  <domain or "(ask per-project)">
+```
+
+vi:
+```
+✓ Đã lưu cấu hình toàn cục vào ~/.compass/global-config.json
+   Ngôn ngữ:         <lang>
+   Tech stack:       <list hoặc "(không có)">
+   Kiểu review:      <style>
+   Domain mặc định:  <domain hoặc "(hỏi mỗi project)">
+```
+
+### 1d. Fall through to Mode B
+
+cwd has no project yet — the natural next step is to create one. Print:
+
+- en: `→ Now let's set up a project at $(pwd)...`
+- vi: `→ Tiếp theo, tạo project tại $(pwd)...`
+
+Continue to Step 2.
+
+---
+
+## Step 2 (Mode B) — Create project at cwd
+
+### 2a. Load global defaults
+
+```bash
+GLOBAL=$(compass-cli project global-config get)   # full JSON
+LANG=$(echo "$GLOBAL" | jq -r '.lang // "en"')
+DEF_STACK=$(echo "$GLOBAL" | jq -c '.default_tech_stack // []')
+DEF_REVIEW=$(echo "$GLOBAL" | jq -r '.default_review_style // "whole_document"')
+DEF_DOMAIN=$(echo "$GLOBAL" | jq -r '.default_domain // empty')
+```
+
+From here on, ALL user-facing chat is in `$LANG`.
+
+### 2b. Confirm target path
+
+Use AskUserQuestion (pick `lang` version):
+
+en:
+```json
+{"questions": [{"question": "Create Compass project at $(pwd)?", "header": "Target", "multiSelect": false, "options": [
+  {"label": "Yes — create here", "description": "Use $(pwd) as the project root"},
+  {"label": "No — specify a different path", "description": "I'll point to another absolute path"},
+  {"label": "Cancel", "description": "Stop without creating anything"}
+]}]}
+```
+
+vi:
+```json
+{"questions": [{"question": "Tạo project Compass tại $(pwd)?", "header": "Đích", "multiSelect": false, "options": [
+  {"label": "Có — tạo ở đây", "description": "Dùng $(pwd) làm project root"},
+  {"label": "Không — chọn đường dẫn khác", "description": "Tôi sẽ trỏ tới một absolute path khác"},
+  {"label": "Huỷ", "description": "Dừng, không tạo gì"}
+]}]}
+```
+
+Branch:
+- `Yes / Có` → `TARGET="$(pwd)"`.
+- `No / Không` → ask for the absolute path (use `Type your own answer`), resolve it, set `TARGET=<absolute>`. Validate that the directory exists and is writable; if not, abort with a clear error.
+- `Cancel / Huỷ` → stop cleanly. Print: en `Stopped — no changes made.` / vi `Đã dừng — không thay đổi gì.`
+
+### 2c. Project-specific questions (batched)
+
+Detect smart defaults BEFORE asking:
+
+```bash
+DETECTED_NAME=$(basename "$TARGET")                    # folder name
+DETECTED_USER=$(git config user.name 2>/dev/null || echo "$USER")
+# Prefix: uppercase first letter of each dash-separated word, 2-5 chars
+DETECTED_PREFIX=$(echo "$DETECTED_NAME" | awk -F- '{for(i=1;i<=NF;i++) printf "%s", toupper(substr($i,1,1))}' | cut -c1-5)
+```
+
+Decide whether to ask the domain question:
+- If `$DEF_DOMAIN` is non-empty → DO NOT ask domain. Use the global default.
+- If `$DEF_DOMAIN` is empty → include the 6-domain question in the batch.
+
+Send 3 or 4 questions in one AskUserQuestion call. Example with all 4 (domain included):
+
+en:
+```json
+{"questions": [
+  {"question": "Project name?", "header": "Project", "multiSelect": false, "options": [
+    {"label": "<DETECTED_NAME>", "description": "From folder name"},
+    {"label": "<title-cased DETECTED_NAME>", "description": "Title-cased variant"}
+  ]},
+  {"question": "Who's the PO?", "header": "PO", "multiSelect": false, "options": [
+    {"label": "@<DETECTED_USER>", "description": "From git config / $USER"},
+    {"label": "@me", "description": "Self-assign for now, change later"}
+  ]},
+  {"question": "Issue prefix? (2–5 uppercase letters)", "header": "Prefix", "multiSelect": false, "options": [
+    {"label": "<DETECTED_PREFIX>", "description": "Derived from project name"},
+    {"label": "<DETECTED_PREFIX[0:3]>", "description": "Shorter variant"}
+  ]},
+  {"question": "Product domain?", "header": "Domain", "multiSelect": false, "options": [
+    {"label": "ard", "description": "Anti Reverse / Defense"},
+    {"label": "platform", "description": "Platform / infra"},
+    {"label": "communication", "description": "Communication products"},
+    {"label": "internal", "description": "Internal tooling"},
+    {"label": "access", "description": "Access / identity"},
+    {"label": "ai", "description": "AI products / agents"}
+  ]}
+]}
+```
+
+vi (same shape, translated):
+```json
+{"questions": [
+  {"question": "Tên project?", "header": "Project", "multiSelect": false, "options": [
+    {"label": "<DETECTED_NAME>", "description": "Từ tên thư mục"},
+    {"label": "<title-cased DETECTED_NAME>", "description": "Biến thể title-case"}
+  ]},
+  {"question": "PO phụ trách?", "header": "PO", "multiSelect": false, "options": [
+    {"label": "@<DETECTED_USER>", "description": "Từ git config / $USER"},
+    {"label": "@me", "description": "Tự assign tạm, đổi sau"}
+  ]},
+  {"question": "Prefix ticket? (2–5 chữ cái viết hoa)", "header": "Prefix", "multiSelect": false, "options": [
+    {"label": "<DETECTED_PREFIX>", "description": "Suy ra từ tên project"},
+    {"label": "<DETECTED_PREFIX[0:3]>", "description": "Biến thể ngắn hơn"}
+  ]},
+  {"question": "Domain sản phẩm?", "header": "Domain", "multiSelect": false, "options": [
+    {"label": "ard", "description": "Anti Reverse / Defense"},
+    {"label": "platform", "description": "Platform / infra"},
+    {"label": "communication", "description": "Sản phẩm communication"},
+    {"label": "internal", "description": "Tooling nội bộ"},
+    {"label": "access", "description": "Access / identity"},
+    {"label": "ai", "description": "AI products / agents"}
+  ]}
+]}
+```
+
+**IMPORTANT:** Replace every `<placeholder>` with actual detected values BEFORE calling AskUserQuestion. The "Type your own answer" affordance handles free-text overrides — never use empty `Other` options.
+
+### 2d. Create folder structure
+
+```bash
+mkdir -p "$TARGET/prd" \
+         "$TARGET/epics" \
+         "$TARGET/wiki" \
+         "$TARGET/prototype" \
+         "$TARGET/technical" \
+         "$TARGET/release-notes" \
+         "$TARGET/research" \
+         "$TARGET/.compass/.state/sessions"
+```
+
+### 2e. Write `.compass/.state/config.json`
+
+Merge global defaults + project-specific answers. Version = `"1.1.1"`. Schema:
+
+```json
+{
+  "version": "1.1.1",
+  "lang": "<from global>",
+  "spec_lang": "<from global, default same as lang>",
+  "project": {
+    "name": "<from 2c>",
+    "po": "@<from 2c>",
+    "prefix": "<from 2c>",
+    "domain": "<from 2c or global default>"
+  },
+  "tech_stack": <global default_tech_stack array>,
+  "review_style": "<global default_review_style>",
+  "mode": "silver-tiger",
+  "created_at": "<ISO-8601 now>"
+}
+```
+
+Write atomically:
+
+```bash
+cat > "$TARGET/.compass/.state/config.json" <<JSON
+{ ... merged JSON above ... }
+JSON
+```
+
+### 2f. Write Silver Tiger CLAUDE.md
+
+`$TARGET/CLAUDE.md` — header block matches the Silver Tiger v1.1 convention so domain rules are reachable from any Claude Code session:
+
+```markdown
+# Claude Context — <project-name>
+
+<!-- Domain rules: /product-owner/shared/domain-rules/<domain>.md -->
+
+- product: <project-name>
+- domain: <domain>
+- po: <po>
+- <domain>_po_lead: <po>
+
+## <Project Name> – Product Description
+
+<1–2 paragraphs describing what this product does, who it's for, and what makes it different. To be filled by the PO after init.>
+
+## Core Concept
+
+<Key concept / differentiator, 3–6 bullets. To be filled by the PO after init.>
+
+## Architecture
+
+<Key technical decisions, stack, constraints. To be filled as the product evolves.>
+
+## Epic Map
+
+| ID | Name | Priority | Status |
+|----|------|----------|--------|
+| | | | |
+
+## Team
+
+| Role | Person |
+|------|--------|
+| PO | <po> |
+
+## Document Structure
+
+- `prd/` — PRDs (<PREFIX>-YYYY-MM-DD-slug.md)
+- `epics/` — Epics + User Stories
+- `research/` — Ideas, Backlog, Research
+- `wiki/` — Product overview, glossary, features
+- `prototype/` — UI prototypes
+- `release-notes/` — Release notes
+- `technical/` — Technical specs
+```
+
+If `domain` is null → omit the `<!-- Domain rules: ... -->` comment AND the `domain` / `<domain>_po_lead` bullets. Keep `product` + `po`.
+
+**Do NOT list Compass commands in CLAUDE.md.** Adapter files load them automatically.
+
+### 2g. Write `domain.yaml`
+
+```yaml
+domain: <from config or "general">
+product: <project-name>
+po: "<po>"
+po_lead: "<po>"
+keywords:
+  - <project-name>
+  - <2–3 keywords inferred from name / folder>
+related_domains: []
+```
+
+### 2h. Write `README.md` stub (only if not present)
+
+```markdown
+# <Project Name>
+
+<One-line description — to be filled>
+
+- **PO:** <po>
+- **Domain:** <domain>
+- **Prefix:** <PREFIX>
+
+## Document Structure
+
+```
+<project>/
+├── prd/                PRDs (<PREFIX>-YYYY-MM-DD-slug.md)
+├── epics/              Epics + User Stories
+├── research/           Ideas, Backlog, Research
+├── prototype/          Prototypes
+├── release-notes/      Release notes
+├── technical/          Technical specs
+├── wiki/               Product overview, glossary, features
+└── .compass/.state/    Compass config + sessions
+```
+```
+
+### 2i. Register in `~/.compass/projects.json`
+
+```bash
+compass-cli project add "$TARGET"     # idempotent
+compass-cli project use "$TARGET"     # set last_active + touch last_used
+```
+
+If either CLI call fails, surface the error to the user — never silently swallow. Project files are already on disk; the failure mode is "registered? no — fix and retry `compass-cli project add`".
+
+### 2j. Success summary
+
+en:
+```
+✓ Compass project ready.
+   Name:    <project-name>
+   Path:    <TARGET>
+   PO:      <po>
+   Prefix:  <PREFIX>
+   Domain:  <domain or "(none)">
+   Active:  yes (set as last_active)
+```
+
+vi:
+```
+✓ Project Compass đã sẵn sàng.
+   Tên:     <project-name>
+   Đường dẫn: <TARGET>
+   PO:      <po>
+   Prefix:  <PREFIX>
+   Domain:  <domain hoặc "(không có)">
+   Active:  có (đặt làm last_active)
+```
+
+Continue to the Final hand-off block.
+
+---
+
+## Step 3 (Mode C) — Update config in place
+
+### 3a. Load current config
+
+```bash
+CONFIG_PATH=".compass/.state/config.json"
+CONFIG=$(cat "$CONFIG_PATH")
+LANG=$(echo "$CONFIG" | jq -r '.lang // "en"')
+```
+
+All Mode C user-facing chat uses this `$LANG`.
+
+### 3b. Pick fields to update
+
+Use AskUserQuestion (multi-select). Build options dynamically from the keys actually present in the config — typical set: `lang`, `spec_lang`, `prefix` (under `project.prefix`), `domain` (under `project.domain`), `po` (under `project.po`). Always add a `Cancel — no changes` escape hatch.
+
+en:
+```json
+{"questions": [{"question": "Which fields would you like to update?", "header": "Update", "multiSelect": true, "options": [
+  {"label": "lang", "description": "UI/chat language (current: <lang>)"},
+  {"label": "spec_lang", "description": "Document/spec language (current: <spec_lang>)"},
+  {"label": "prefix", "description": "Issue prefix (current: <prefix>)"},
+  {"label": "domain", "description": "Product domain (current: <domain>)"},
+  {"label": "po", "description": "Product Owner handle (current: <po>)"},
+  {"label": "Cancel — no changes", "description": "Exit without modifying anything"}
+]}]}
+```
+
+vi:
+```json
+{"questions": [{"question": "Bạn muốn cập nhật trường nào?", "header": "Update", "multiSelect": true, "options": [
+  {"label": "lang", "description": "Ngôn ngữ chat/UI (hiện tại: <lang>)"},
+  {"label": "spec_lang", "description": "Ngôn ngữ tài liệu/spec (hiện tại: <spec_lang>)"},
+  {"label": "prefix", "description": "Prefix ticket (hiện tại: <prefix>)"},
+  {"label": "domain", "description": "Domain sản phẩm (hiện tại: <domain>)"},
+  {"label": "po", "description": "Handle PO (hiện tại: <po>)"},
+  {"label": "Huỷ — không đổi gì", "description": "Thoát, không cập nhật"}
+]}]}
+```
+
+If the user picks `Cancel / Huỷ`, stop immediately — print en `No changes made.` / vi `Không có thay đổi.`
+
+### 3c. Ask new value for each picked field
+
+For every selected field, send ONE AskUserQuestion with smart defaults — current value as the first option:
+
+- `lang` / `spec_lang` → 2 options: `Tiếng Việt` / `English`.
+- `prefix` → 2 options: current prefix, plus a Type-your-own affordance (the user almost certainly wants free text here).
+- `domain` → the 6-domain enum (same list as Mode B).
+- `po` → 2 options: current value, plus `@<git config user.name or $USER>`.
+
+Across multiple selected fields, batch in a SINGLE AskUserQuestion call (max 4 fields per call — if the PO somehow picked >4, split into two calls).
+
+### 3d. Write back
+
+Load the full existing config, overlay only the picked keys (preserve every untouched field, including `version`, `created_at`, nested objects). Write back atomically:
+
+```bash
+TMP=$(mktemp)
+echo "$NEW_CONFIG" | jq '.' > "$TMP" && mv "$TMP" "$CONFIG_PATH"
+```
+
+If `lang` changed, also touch `~/.compass/projects.json` so the next session sees the latest:
+
+```bash
+compass-cli project use "$(pwd)"   # idempotent — refreshes last_used
+```
+
+### 3e. Summary of changes
+
+en:
+```
+✓ Config updated.
+   <field-1>: <old> → <new>
+   <field-2>: <old> → <new>
+```
+
+vi:
+```
+✓ Đã cập nhật cấu hình.
+   <field-1>: <old> → <new>
+   <field-2>: <old> → <new>
+```
+
+---
+
+## Final — Hand off
+
+After Mode B success or Mode C summary (Mode A always falls through to B and exits via B's hand-off), print:
+
+en:
+```
+✓ Compass ready.
+   Active project: <name> (<path>)
+   Next: /compass:brief <task>  or  /compass:prd
+```
+
+vi:
+```
+✓ Compass đã sẵn sàng.
+   Project active: <name> (<path>)
+   Tiếp theo: /compass:brief <task>  hoặc  /compass:prd
+```
+
+Stop. Do NOT auto-invoke any other workflow.

package/core/workflows/migrate.md

@@ -0,0 +1,136 @@
+# 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
+
+Pick the version matching `lang`.
+
+**If `already_v1 = true`:**
+- en: `"✓ Already on v1.0 state layout — nothing to migrate."`
+- vi: `"✓ Đã ở layout v1.0 — không cần migrate."`
+
+**If migration ran (no errors):**
+
+English:
+```
+✓ 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.
+```
+
+Vietnamese:
+```
+✓ Đã migrate sang layout v1.0.
+
+  Session đã chuyển:   <sessions_migrated>
+  Backup đã tạo:       <backups_written>  →  $PROJECT_ROOT/.compass/.state/.backup-<ISO>/
+  project-memory.json: <project_memory>   ("created" hoặc "exists")
+
+  Chạy lại lúc nào cũng an toàn — migrate là idempotent.
+```
+
+---
+
+## Step 4 — Handle errors (if any)
+
+If `errors` is non-empty, list each entry and give an actionable next step. Do NOT pretend success.
+
+- en:
+```
+⚠ 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
+```
+
+- vi:
+```
+⚠ Migrate xong nhưng có <N> lỗi:
+
+  • <file>: <message>
+
+  File gốc vẫn giữ trong $PROJECT_ROOT/.compass/.state/.backup-<ISO>/.
+  Sửa lỗi ở trên rồi chạy lại: /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 |