bigpowers 2.87.4 → 2.87.6

package/.cursor/rules/migrate-spec.mdc

@@ -0,0 +1,907 @@
+---
+description: "Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers YAML layout (state.yaml, release-plan.yaml, epics/, requirements/, plans/, ADRs). Use when migrating foreign spec docs."
+alwaysApply: false
+---
+
+# story: e25s01
+# story: e25s02
+# story: e25s03
+# story: e25s04
+# story: e25s05
+# story: e25s06
+
+# Migrate Spec
+
+Transform existing GSD, spec-kit, or BMAD planning artifacts into the bigpowers `specs/` model. No code is written — the output is a set of bigpowers-format spec files the user can use immediately.
+
+## Quick start
+
+1. Run this skill from the root of the project being migrated (not the bigpowers repo itself).
+2. The skill auto-detects the source framework and presents its findings before transforming anything.
+3. All output goes to `specs/` at the project root.
+
+---
+
+## Red flags — stop and ask
+
+Before proceeding, check for these rationalization traps:
+
+- **Partial artifact set** — only one fingerprint file found (e.g. just `spec.md` with no `plan.md`). Don't assume it's a complete project. Ask: "I found only X — is this the full set of your spec artifacts?"
+- **Wrong trigger** — user said "migrate my code" or "migrate the database", not "migrate my specs". Confirm before running.
+- **Stale source** — source artifacts have commit dates older than 6 months with no recent activity. Flag: "These specs appear inactive since <date>. Are they still the source of truth?"
+- **Active divergence** — source `state.yaml` or `sprint-status.yaml` shows in-progress work. Flag: "There is active work in flight. Migrating now may lose in-progress context. Proceed?"
+
+If any red flag fires: surface it, wait for explicit user confirmation before continuing.
+
+---
+
+## Process
+
+### Step 1 — Detect the source framework
+
+Scan for the fingerprints below. Stop at first match; if multiple match, list them and ask the user which is primary.
+
+| Framework | Fingerprints (any one is sufficient) |
+|-----------|--------------------------------------|
+| **GSD** | `.planning/` directory; `.planning/ROADMAP.md`; `.planning/REQUIREMENTS.md` with `REQ-` IDs |
+| **spec-kit** | `.specify/` directory; `spec.md` + `plan.md` at root; `.github/skills/speckit-*/SKILL.md` |
+| **BMAD** | `_bmad/` directory; `_bmad-output/` directory; `prd.md` with `FR-` IDs; `epic-*.md` or `story-*.md` |
+
+If none found: ask the user which framework before proceeding.
+
+→ verify: `test -d specs && test -f specs/state.yaml`
+
+### Step 2 — Inventory the source artifacts
+
+List every artifact found matching the detected framework. Present the list to the user:
+
+See [REFERENCE.md](REFERENCE.md) — `Detected: GSD...`
+
+→ verify: `test -d specs && test -w specs`
+
+### Step 3 — Transform (one artifact at a time, show diffs)
+
+Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./REFERENCE-GSD.md). For each target file:
+
+1. Show what will be created or appended (title + first 20 lines).
+2. Ask: "Create this? [yes / edit / skip]"
+3. On yes: write to `specs/`.
+
+#### ID Tracking (REQ-XX, FR-XX, UJ-XX)
+
+When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as **first-class YAML fields** in `in_scope` entries, not YAML comments:
+
+See [REFERENCE.md](REFERENCE.md) — `# CORRECT — first-class id: field...`
+
+**When source has no IDs:** Prompt the user: "No IDs found. Assign auto-generated IDs? [yes / no]". If yes, emit `REQ-{NNN}` with `# auto-generated` annotation.
+
+**When source has MIXED IDs:** Items with IDs get `id:` fields; items without IDs receive auto-generated `REQ-NNN` entries. Document which were auto-generated in a comment block at the top of `in_scope`.
+
+See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-format-with-id-tracking) for examples.
+
+#### Traceability Output (FR-XX, UJ-XX)
+
+When source has FR-XX or UJ-XX IDs, emit `specs/product/REQUIREMENTS_TRACE.yaml` for end-to-end requirement traceability:
+
+See [REFERENCE.md](REFERENCE.md) — `trace:...`
+
+**Existing trace file:** If `REQUIREMENTS_TRACE.yaml` already exists, prompt: "REQUIREMENTS_TRACE.yaml exists. [overwrite / merge / skip]"
+
+**No FR-XX/UJ-XX found:** Skip trace file; add note to state.yaml handoff: "No FR-XX/UJ-XX IDs found — traceability file skipped".
+
+See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirements_traceyaml-format) for the complete schema.
+
+> **HARD GATE** — Never overwrite an existing `specs/` file without explicit user confirmation. Merge into it if it exists; don't clobber.
+>
+> → verify: `git rev-parse --git-dir >/dev/null 2>&1 && test -d specs`
+
+→ verify: `test -d specs && [ "$(ls specs/*.md specs/*.yaml 2>/dev/null | wc -l | tr -d " ")" -gt 0 ]`
+
+### Step 4 — Generate state.yaml
+
+Always regenerate `specs/state.yaml` from scratch in bigpowers YAML format (see REFERENCE.md for template). The **handoff block is mandatory** and must include all four fields:
+
+See [REFERENCE.md](REFERENCE.md) — `active_flow: null...`
+
+If no open decisions were found during migration, the `open_decisions` list may be empty with an explanatory comment:
+
+See [REFERENCE.md](REFERENCE.md) — `handoff:...`
+
+→ verify: `grep -q handoff: specs/state.yaml`
+
+---
+
+# migrate-spec Reference — GSD
+
+Full artifact transformation rules for migrating GSD projects to bigpowers YAML layout.
+
+See [REFERENCE.md](./REFERENCE.md) for spec-kit, BMAD, learnings, and ADR/DECISION-LOG formats.
+
+---
+
+## Artifact Locations
+
+GSD stores everything under `.planning/` at the project root.
+
+```
+.planning/
+├── ROADMAP.md
+├── STATE.md
+├── REQUIREMENTS.md
+├── METHODOLOGY.md
+├── HANDOFF.json
+├── .continue-here.md
+└── phases/
+    └── XX-name/
+        ├── XX-CONTEXT.md
+        ├── XX-YY-PLAN.md
+        ├── XX-YY-SUMMARY.md
+        └── XX-DISCUSSION-LOG.md
+    spikes/
+        └── SPIKE-NNN/README.md
+```
+
+---
+
+## Transformation Rules
+
+### `.planning/ROADMAP.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`
+
+GSD ROADMAP has: milestone name, phases, success criteria per phase, plan count.
+
+Transform:
+- Each GSD phase → one epic entry in `release-plan.yaml` (`id`, `title`, `wsjf`, `file`)
+- Phase detail → matching `specs/epics/eNN-slug.yaml` (stories, tasks, `verify`)
+- Completed phases → `done` in `execution-status.yaml`; active → `in_progress`
+
+---
+
+### `.planning/REQUIREMENTS.md` → `specs/product/SCOPE_LATEST.yaml`
+
+GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
+
+Transform:
+- Preserve REQ-XX IDs as **first-class `id:` fields** in `in_scope` entries (see [REFERENCE.md — ID tracking format](./REFERENCE.md#in_scope-format-with-id-tracking))
+- Validated requirements → `in_scope` entries with `id:`, `description:`, `source:` fields
+- Out-of-Scope → `out_of_scope` entries (preserve IDs if present)
+- Active (in-progress) → `in_scope` with status note
+
+---
+
+### `.planning/phases/XX-name/XX-CONTEXT.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
+
+GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context, specifics, deferred.
+
+Transform:
+- `domain` → `plans/TECH_STACK_LATEST.md` Domain section
+- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG_LATEST.md`
+- `canonical_refs` → Reference links in TECH_STACK
+- `code_context` → Architecture section
+- `deferred` → `SCOPE_LATEST.yaml` `out_of_scope` (with "(deferred from GSD)" note)
+
+---
+
+### `.planning/phases/XX-name/XX-YY-PLAN.md` → `specs/epics/eNN-*.yaml` tasks
+
+GSD PLAN has: frontmatter (depends-on, verify), objective, typed tasks, success criteria, output spec.
+
+Transform:
+- Preserve task structure as `tasks[]` in epic shard
+- Keep `verify: <command>` lines
+- Map GSD `depends-on` to task `depends-on` notes
+- SUMMARY.md (execution record) → skip or append to `specs/archive/`
+
+---
+
+### `.planning/METHODOLOGY.md` → `specs/tech-architecture/METHODOLOGY_LATEST.md`
+
+GSD METHODOLOGY.md is a standing reference for analytical lenses (Bayesian updating, STRIDE, cost-of-delay).
+
+Transform:
+- Copy each lens as a section in `specs/tech-architecture/METHODOLOGY_LATEST.md`
+- Note: "These lenses should inform `plan-work` and `audit-code` sessions."
+
+---
+
+### `.planning/HANDOFF.json` + `.continue-here.md` → `specs/state.yaml` `handoff`
+
+GSD HANDOFF has: current phase, last plan, blocking reason, required reading list.
+
+Transform — populate `handoff` in `state.yaml`:
+
+```yaml
+handoff:
+  last_step_completed: "<phase/plan from HANDOFF>"
+  open_decisions:
+    - "<blocking reason if any>"
+  required_reading:
+    - "<required_reading list>"
+  next_skill: survey-context
+```
+
+---
+
+### `.planning/spikes/SPIKE-NNN/README.md` → `specs/archive/spikes/SPIKE-{name}.md`
+
+GSD spike README has: YAML frontmatter (verdict, validates, related), methodology, findings, recommendation.
+
+Transform:
+- Flatten directory into `specs/archive/spikes/SPIKE-{name}.md`
+- Preserve frontmatter as YAML block at top
+- Keep verdict prominently: `**Verdict:** ADOPTED / REJECTED / DEFERRED`
+
+---
+
+## Skip List
+
+These GSD artifacts are not migrated — they are execution records, not planning inputs:
+
+| Artifact | Reason |
+|----------|--------|
+| `.planning/phases/XX/XX-YY-SUMMARY.md` | Execution log; no bigpowers equivalent |
+| `.planning/phases/XX/XX-DISCUSSION-LOG.md` | Audit trail only; not consumed by agents |
+| `.planning/USER-PROFILE.md` | User calibration; bigpowers has no profile system |
+| `.planning/sketches/` | Visual exploration; not spec artifacts |
+
+---
+
+# Migrate Spec — Reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–68 | Navigation |
+| 69–70 | spec-kit → bigpowers Mapping |
+| 71–84 | Artifact Locations |
+| 85–94 | `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md` |
+| 95–105 | `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/` |
+| 106–114 | `tasks.md` → `specs/epics/` (via slice-tasks) |
+| 115–120 | `.specify/` state |
+| 121–122 | BMAD → bigpowers Mapping |
+| 123–141 | Artifact Locations |
+| 142–148 | `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml` |
+| 149–160 | `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml` |
+| 161–167 | `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md` |
+| 168–174 | `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/` |
+| 175–178 | `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml` |
+| 179–182 | `story-*.md` → `specs/epics/` stories |
+| 183–188 | `project-context.md` → `CLAUDE.md` |
+| 189–192 | Learnings to Adopt |
+| 193–198 | From GSD |
+| 199–204 | From spec-kit |
+| 205–212 | From BMAD |
+| 213–214 | Output Formats |
+| 215–224 | ADR format (bigpowers) |
+| 225–227 | Context |
+| 228–230 | Decision |
+| 231–234 | Consequences |
+| 235–246 | DECISION-LOG.md format |
+| 247–257 | MIGRATION-AUDIT.md format |
+| 258–264 | Summary |
+| 265–274 | High Priority Findings |
+| 275–278 | Information |
+| 279–285 | Next Steps |
+| 286–306 | in_scope format with ID tracking |
+| 307–341 | REQUIREMENTS_TRACE.yaml format |
+| 342–397 | `specs/state.yaml` template format |
+| 398–416 | Reference block 1 |
+| 417–432 | Reference block 2 |
+| 433–451 | Reference block 3 |
+| 452–474 | Reference block 4 |
+| 475–482 | Reference block 5 |
+| 483–484 | Findings |
+| 485–489 | High Priority |
+| 490–495 | Information |
+| 496–509 | Reference block 6 |
+| 510–542 | Step 7 — Post-migration: Optional two-pass spec writing gate |
+| 543–574 | Step 8 — Post-migration: Optional methodology doc template |
+| 575–600 | Artifact Mapping Summary |
+| 601–610 | Rules |
+| 611–621 | Step 5 — Surface learnings (optional) |
+| 622–644 | Step 6 — Adversarial review (optional) |
+| 645–646 | Findings |
+| 647–651 | High Priority |
+| 652–660 | Information |
+
+# migrate-spec Reference — spec-kit, BMAD, Learnings
+
+Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.
+
+See [REFERENCE-GSD.md](./REFERENCE-GSD.md) for full GSD → bigpowers YAML mapping.
+
+---
+
+## spec-kit → bigpowers Mapping
+
+### Artifact Locations
+
+```
+project-root/
+├── spec.md         ← user journeys, success criteria, scope
+├── plan.md         ← technology, architecture, constraints
+├── tasks.md        ← atomic task list
+└── .specify/
+    ├── workflow-catalogs.yml
+    └── workflows/runs/<id>/
+        ├── state.json
+        └── log.jsonl
+```
+
+### `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md`
+
+spec-kit `spec.md` focuses on: who uses it, user journeys, success criteria, what's in/out of scope.
+
+Transform:
+- User journeys → `SCOPE_LATEST.yaml` success criteria / `in_scope` entries
+- In/out of scope → `in_scope` / `out_of_scope` sections
+- Domain terms / glossary → `requirements/GLOSSARY_LATEST.yaml`
+- Problem statement / vision → `requirements/VISION_LATEST.yaml`
+
+### `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/`
+
+spec-kit `plan.md` covers: technology stack, architectural patterns, implementation constraints.
+
+Transform:
+- Technology decisions → `plans/TECH_STACK_LATEST.md` Technology section
+- Architecture patterns → Architecture section
+- Hard decisions with trade-offs → `specs/adr/NNNN-{slug}.md`
+- Phased approach / milestones → `release-plan.yaml` epic entries
+- Implementation steps → `epics/eNN-*.yaml` task list with `verify:`
+
+### `tasks.md` → `specs/epics/` (via slice-tasks)
+
+spec-kit tasks are atomic, verifiable in isolation — same principle as bigpowers `verify:` mandate.
+
+Transform:
+- Copy tasks into epic shard `tasks[]`; preserve task numbers
+- Add `verify:` line if spec-kit task has an acceptance criterion
+- Group into epics matching `release-plan.yaml` entries
+
+### `.specify/` state
+
+Discard — workflow engine state; not meaningful in the bigpowers skill model.
+
+---
+
+## BMAD → bigpowers Mapping
+
+### Artifact Locations
+
+```
+project-root/
+├── _bmad/bmm/config.yaml
+├── _bmad-output/
+│   ├── product-brief.md
+│   ├── prfaq-{project}.md
+│   ├── prd.md
+│   ├── addendum.md
+│   ├── decision-log.md
+│   ├── ux-spec.md
+│   └── architecture.md
+├── project-context.md
+└── docs/
+    ├── epic-{slug}.md
+    └── story-{slug}.md
+```
+
+### `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml`
+
+Transform:
+- Vision + core value → `VISION_LATEST.yaml` north_star / success_criteria
+- Target users → notes in VISION or SCOPE
+- prfaq customer FAQ → can inform success criteria in SCOPE
+
+### `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml`
+
+BMAD `prd.md` has: Glossary, FR-XX functional requirements, UJ-XX user journeys, NFRs, assumptions.
+
+Transform:
+- Glossary → `GLOSSARY_LATEST.yaml`
+- FR-XX items → `in_scope` with IDs preserved
+- UJ-XX user journeys → success criteria
+- NFRs → `constraints` section
+- `[ASSUMPTION: ...]` inline tags → collected in scope YAML
+- Out-of-scope features → `out_of_scope`
+
+### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md`
+
+Transform:
+- Hard, irreversible, surprising decisions → individual `specs/adr/NNNN-{slug}.md`
+- Lightweight decisions → `specs/DECISION-LOG_LATEST.md` (date | decision | rationale)
+- `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata
+
+### `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
+
+Transform:
+- ADR sections → individual `specs/adr/NNNN-{slug}.md` files
+- System overview / data models → TECH_STACK Architecture section
+- API contracts → keep at `docs/api.md` or similar; link from TECH_STACK
+
+### `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`
+
+Each epic → one release-plan entry + one epic shard. Acceptance criteria → story tasks with `verify:`.
+
+### `story-*.md` → `specs/epics/` stories
+
+Each story → one story entry in epic shard. Acceptance criteria → `verify:` lines.
+
+### `project-context.md` → `CLAUDE.md`
+
+Add a "## Project Context" section to `CLAUDE.md`. Copy tech stack, coding rules, preferences verbatim.
+
+---
+
+## Learnings to Adopt
+
+Optional enhancements to offer the user after migration. Present as checkboxes.
+
+### From GSD
+
+- [x] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning. (adopted: optional Step 8 template scaffold)
+- [x] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session. (adopted: mandatory in Step 4 output)
+- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
+
+### From spec-kit
+
+- [x] **Two-pass spec writing** — User-journey pass first, then technical-decisions pass. (adopted: optional post-migration gate)
+- [ ] **Explicit inter-phase gate** — "Approve to proceed?" at end of `elaborate-spec`.
+- [ ] **Epic task isolation** — Each task completable in isolation; `depends-on` explicit in epic YAML.
+
+### From BMAD
+
+- [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
+- [ ] **`specs/DECISION-LOG_LATEST.md`** — Lightweight decisions below ADR threshold.
+- [x] **Adversarial review pass** — Critique epic shard before `develop-tdd`. (adopted: optional Step 6 in migration)
+
+---
+
+## Output Formats
+
+### ADR format (bigpowers)
+
+Use `model-domain/ADR-FORMAT.md`. Only create when all three apply: hard to reverse, surprising without context, result of a real trade-off.
+
+```markdown
+# ADR-NNNN: {Title}
+
+**Status:** Accepted
+**Date:** YYYY-MM-DD
+
+## Context
+[What situation forced this decision?]
+
+## Decision
+[What was decided?]
+
+## Consequences
+[What becomes easier or harder?]
+```
+
+### DECISION-LOG.md format
+
+For lightweight decisions that don't warrant a full ADR:
+
+```markdown
+# Decision Log
+
+| Date | Decision | Rationale | Alternatives |
+|------|----------|-----------|--------------|
+| 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
+```
+
+### MIGRATION-AUDIT.md format
+
+Post-migration adversarial review report. Written to `specs/archive/MIGRATION-AUDIT.md` when Step 6 runs:
+
+```markdown
+# Migration Audit — <project-name>
+
+**Source Framework:** <GSD|spec-kit|BMAD>  
+**Date:** <ISO 8601>  
+**Status:** <Pass|Findings|Critical>
+
+## Summary
+
+- TODO markers: N
+- FIXME markers: N
+- MISSING markers: N
+- Epics without verify: N
+
+## High Priority Findings
+
+- **Artifact:** specs/epics/e02-auth-ui/epic.yaml
+  **Issue:** Story e02s01 has no verify: commands in tasks
+  **Recommendation:** Add runnable verify command before develop-tdd
+
+- **Artifact:** specs/state.yaml
+  **Issue:** open_decisions list empty without comment explanation
+  **Recommendation:** Add # comment if all decisions were resolved during migration
+
+## Information
+
+- Artifact specs/epics/e01-auth/epic.yaml contains TODO: "Define Neon Auth client URL injection" (normal for fresh migration)
+
+## Next Steps
+
+1. Address high-priority findings before plan-work
+2. Run bash scripts/audit-compliance.sh to enforce code quality gates
+3. Begin develop-tdd on highest-WSJF epic
+```
+
+### in_scope format with ID tracking
+
+Source IDs (REQ-XX, FR-XX, UJ-XX) are emitted as first-class YAML fields:
+
+```yaml
+in_scope:
+  - id: REQ-001
+    description: "User can register with email and password"
+    source: "REQUIREMENTS.md"
+  - id: FR-015
+    description: "Auth service must support OAuth2 token flow"
+    source: "prd.md"
+  - id: REQ-AUTO-002  # auto-generated when source had no ID
+    description: "Dashboard displays user profile"
+    # auto-generated: true  (optional comment for tracking)
+```
+
+**When source has no IDs:** If the user opts in, auto-generated IDs follow the `REQ-{NNN}` format with an optional `# auto-generated` comment.
+
+**When source has mixed IDs:** Entries with source IDs get `id:` fields; entries without IDs receive auto-generated IDs. A comment block at the top of `in_scope` documents which IDs were auto-generated.
+
+### REQUIREMENTS_TRACE.yaml format
+
+Emitted when source has FR-XX (functional requirement) or UJ-XX (user journey) IDs. Maps source requirements to bigpowers epic/story structure and verification commands:
+
+```yaml
+trace:
+  # Functional Requirements
+  - id: FR-001
+    type: functional_requirement
+    description: "User can register with email/password"
+    source_artifact: "prd.md"
+    epic: "e02-auth-ui"
+    story: "e02s01"
+    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"
+
+  # User Journeys
+  - id: UJ-001
+    type: user_journey
+    description: "New user completes registration flow"
+    source_artifact: "epic-auth-ui.md"
+    epic: "e02-auth-ui"
+    story: "e02s01"
+    verify: "grep -q 'UJ-001' specs/epics/e02-auth-ui/epic.yaml && echo OK"
+
+metadata:
+  source_framework: "BMAD"
+  migrated_at: "2026-06-26T12:00:00Z"
+  total_requirements: 2
+  coverage: "All FR-XX and UJ-XX IDs from source mapped"
+```
+
+**When source has no FR-XX/UJ-XX:** Skip REQUIREMENTS_TRACE.yaml. Add note to `state.yaml` handoff: "No FR-XX/UJ-XX IDs found — traceability file skipped".
+
+**Existing trace file:** If REQUIREMENTS_TRACE.yaml exists, prompt user: "Overwrite? [yes / merge / skip]". Merge appends new entries; skip leaves existing file intact.
+
+### `specs/state.yaml` template format
+
+Generated during Step 4 of migration. Regenerate from scratch in bigpowers YAML format. The **handoff block is mandatory**:
+
+```yaml
+active_flow: null
+active_epic_id: null
+active_story_id: null
+completed_epic: false
+
+epic_cycle:
+  current_step: null
+  next_skill: null
+  story_bcps: null
+  completed_steps: []
+  audit_result: null
+
+bug_cycle:
+  current_step: null
+  completed_steps: []
+
+release:
+  target_version: null
+  last_tag: null
+  last_publish: null
+  ci_verified: false
+
+metrics:
+  story_start: null
+  story_end: null
+  cycle_minutes: null
+  bcp_per_hour: null
+
+git:
+  branch: <current branch>
+  hash: <git rev-parse HEAD>
+  pushed: false
+
+handoff:
+  last_step_completed: "Migrated from <framework> on <date>"
+  open_decisions: []  # Empty if all decisions resolved during migration
+  required_reading:
+    - specs/product/VISION_LATEST.yaml
+    - specs/product/SCOPE_LATEST.yaml
+    - specs/tech-architecture/TECH_STACK_LATEST.md
+    - specs/release-plan.yaml
+  next_skill: survey-context
+
+two_pass_spec:  # Optional: only if user activates two-pass spec writing gate
+  journey_pass: pending
+  technical_pass: pending
+  approved_at: null
+```
+
+---
+
+## Reference block 1
+
+```
+Detected: GSD
+Found:
+  ✓ .planning/ROADMAP.md
+  ✓ .planning/REQUIREMENTS.md  (12 REQ-XX items)
+  ✓ .planning/state.yaml
+  ✓ .planning/phases/01-auth/01-CONTEXT.md
+  ✗ .planning/METHODOLOGY.md  (not present)
+
+Skipping:
+  .planning/phases/01-auth/01-01-SUMMARY.md  (execution record; archived only)
+
+Proceed with migration? [yes / skip <artifact> / abort]
+```
+
+---
+
+## Reference block 2
+
+```yaml
+# CORRECT — first-class id: field
+in_scope:
+  - id: REQ-001
+    description: "User can register with email/password"
+    source: "REQUIREMENTS.md"
+
+# DEPRECATED — comment-only
+in_scope:
+  - "User can register with email/password"  # REQ-001
+```
+
+---
+
+## Reference block 3
+
+```yaml
+trace:
+  - id: FR-001
+    type: functional_requirement
+    description: "User can register with email/password"
+    epic: e02-auth-ui
+    story: e02s01
+    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"
+  - id: UJ-001
+    type: user_journey
+    description: "New user completes registration flow"
+    epic: e02-auth-ui
+    story: e02s01
+```
+
+---
+
+## Reference block 4
+
+```yaml
+active_flow: null
+active_epic_id: null
+active_story_id: null
+
+# ... other state fields ...
+
+handoff:
+  last_step_completed: "Migrated from <framework> on <date>"
+  open_decisions:
+    - "decision text here"
+  required_reading:
+    - specs/product/VISION_LATEST.yaml
+    - specs/product/SCOPE_LATEST.yaml
+    - specs/tech-architecture/TECH_STACK_LATEST.md
+    - specs/release-plan.yaml
+  next_skill: survey-context
+```
+
+---
+
+## Reference block 5
+
+```markdown
+# Migration Audit — <project-name> from <framework>
+
+**Date:** <ISO 8601 timestamp>
+**Status:** Pass / Fail with findings
+
+## Findings
+
+### High Priority
+- Artifact: specs/epics/e02-auth-ui/epic.yaml
+  Finding: No verify: commands in story tasks
+  Recommendation: Add `verify:` to each task before develop-tdd
+
+### Information
+- Count of TODO markers: 3 (normal for fresh migration)
+```
+
+---
+
+## Reference block 6
+
+```
+Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?
+
+[x] Cost of Delay (CD3)           — Priority & trade-off assessment
+[ ] STRIDE                        — Security threat modeling
+[ ] F.I.R.S.T                     — Test quality principles
+[ ] Bayesian Updating            — Probabilistic decision-making
+[ ] OWASP Top 10                 — Web security framework
+```
+
+---
+
+### Step 7 — Post-migration: Optional two-pass spec writing gate
+
+After Steps 1–6, offer the user an optional two-pass spec writing workflow (spec-kit learning):
+
+Prompt: "Use two-pass spec writing (user journeys first, then technical)? [yes / no]"
+
+If **yes**, initialize the gate in `specs/state.yaml`:
+
+```yaml
+two_pass_spec:
+  journey_pass: pending
+  technical_pass: pending
+  approved_at: null
+```
+
+The journey pass must be marked "complete" by the user (after stakeholder approval of user-journey specs) before the technical pass begins:
+
+```yaml
+two_pass_spec:
+  journey_pass: complete
+  approved_at: "2026-06-26T12:00:00Z"
+  technical_pass: pending
+```
+
+Inform the user: "Journey pass is pending. Run `elaborate-spec` for user journeys, get stakeholder approval, then update `two_pass_spec.journey_pass: complete` in state.yaml before proceeding to technical specs."
+
+If **no**, skip the two-pass gate. Proceed directly to plan-work.
+
+→ verify: `grep -q 'two_pass_spec:' specs/state.yaml && echo "two-pass gate initialized" || echo "two-pass gate not activated"`
+
+
+---
+
+### Step 8 — Post-migration: Optional methodology doc template
+
+After Steps 1–7, offer the user an optional analytical framework scaffold (GSD learning):
+
+Prompt: "Create a methodology doc? [yes / no]"
+
+If **yes**, present a checklist of analytical lenses:
+
+```
+Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?
+
+[x] Cost of Delay (CD3)           — Priority & trade-off assessment
+[ ] STRIDE                        — Security threat modeling
+[ ] F.I.R.S.T                     — Test quality principles
+[ ] Bayesian Updating            — Probabilistic decision-making
+[ ] OWASP Top 10                 — Web security framework
+```
+
+Copy the template from `migrate-spec/templates/METHODOLOGY_LATEST.md` to `specs/tech-architecture/METHODOLOGY_LATEST.md`.
+- Active lenses remain uncommented
+- Unselected lenses are left commented out
+- Populate `{{project_name}}` with the migrated project's name
+
+If **no**, skip. Add note to handoff: "Methodology doc: skipped — can be added later via `cp migrate-spec/templates/METHODOLOGY_LATEST.md specs/tech-architecture/`"
+
+→ verify: `test -f specs/tech-architecture/METHODOLOGY_LATEST.md && echo "methodology doc created" || echo "methodology doc skipped"`
+
+---
+
+
+---
+
+## Artifact Mapping Summary
+
+Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.md](./REFERENCE.md) (spec-kit, BMAD, learnings).
+
+| Source | Target |
+|--------|--------|
+| GSD `ROADMAP.md` | `specs/release-plan.yaml + epic shards` |
+| GSD `REQUIREMENTS.md` | `specs/product/SCOPE_LATEST.yaml` |
+| GSD `CONTEXT.md` (phases) | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |
+| GSD `PLAN.md` | `specs/epics/eNN-slug/epic.yaml` (tasks with verify in `-tasks.yaml`) |
+| GSD `METHODOLOGY.md` | `specs/tech-architecture/tech-stack.md` |
+| spec-kit `spec.md` | `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/tech-stack.md` |
+| spec-kit `plan.md` | `specs/tech-architecture/tech-stack.md` + `specs/release-plan.yaml` + `specs/epics/` |
+| spec-kit `tasks.md` | `specs/epics/ (see slice-tasks)` |
+| BMAD `prd.md` | `specs/product/SCOPE_LATEST.yaml` |
+| BMAD `architecture.md` | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |
+| BMAD `epic-*.md` | `specs/release-plan.yaml + epic shards` |
+| BMAD `story-*.md` | `specs/epics/ (see slice-tasks)` |
+| BMAD `project-context.md` | `CLAUDE.md` (append project-specific section) |
+| BMAD `decision-log.md` | `specs/adr/` (one ADR per logged decision) |
+
+---
+
+
+---
+
+## Rules
+
+- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX are emitted as first-class `id:` fields in bigpowers YAML targets (e.g., `in_scope` entries). Never silently renumber. See Step 3 ID Tracking subsection for details.
+- **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.
+- **ADRs are opt-in** — only create an ADR when: hard to reverse, surprising without context, result of a real trade-off. Lightweight decisions go to `specs/DECISION-LOG_LATEST.md`.
+- **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
+- **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.
+
+---
+
+### Step 5 — Surface learnings (optional)
+
+After migration, offer the user a brief analysis of what the source framework did that bigpowers doesn't have yet.
+
+Use the learnings table from [REFERENCE.md](./REFERENCE.md#learnings-to-adopt). Present as checkboxes so the user can decide which to adopt.
+
+→ verify: `grep -c "\- \[ \]" specs/state.yaml 2>/dev/null && echo "pending items recorded" || echo "no pending items in state.yaml"`
+
+
+---
+
+### Step 6 — Adversarial review (optional)
+
+Before the user runs `plan-work`, offer an optional lightweight audit of the migrated artifacts. This catches common migration errors early — incomplete specs, missing verification commands, unresolved decisions.
+
+Prompt: "Run adversarial review of migrated artifacts? [yes / skip]"
+
+If yes, perform these checks:
+
+1. **Scan for incomplete markers** — Find TODO, FIXME, MISSING in specs/
+2. **Verify every epic has `verify:` commands** — Parse all `eNN-*/epic.yaml` files
+3. **Check state.yaml handoff** — Ensure `open_decisions` is documented (even if empty)
+
+Collect findings and write to `specs/archive/MIGRATION-AUDIT.md`:
+
+```markdown
+# Migration Audit — <project-name> from <framework>
+
+**Date:** <ISO 8601 timestamp>
+**Status:** Pass / Fail with findings
+
+
+---
+
+## Findings
+
+### High Priority
+- Artifact: specs/epics/e02-auth-ui/epic.yaml
+  Finding: No verify: commands in story tasks
+  Recommendation: Add `verify:` to each task before develop-tdd
+
+### Information
+- Count of TODO markers: 3 (normal for fresh migration)
+```
+
+If findings exist, the handoff block should note: "Adversarial review: N findings — see `specs/archive/MIGRATION-AUDIT.md`"
+
+If skip is chosen, add to handoff: "Adversarial review: skipped — review manually before plan-work"
+
+→ verify: `test -f specs/archive/MIGRATION-AUDIT.md && echo "audit completed" || echo "audit skipped or not performed"`