bigpowers 2.34.1 → 2.35.0

package/.pi/skills/develop-tdd/SKILL.md

@@ -71,70 +71,15 @@ After all tests pass: extract duplication, deepen modules, apply SOLID principle
 
 After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
 
-### 6a. CI dry-run sub-step (when modifying workflows)
-
-If this cycle modified files in `.github/workflows/`, run a CI dry-run before pushing:
-
-```bash
-# 1. Check for workflow file changes
-CHANGED_WORKFLOWS=$(git diff --name-only HEAD | grep '\.github/workflows/' || true)
-if [ -n "$CHANGED_WORKFLOWS" ]; then
-  echo "==> CI dry-run: workflow files changed"
-  echo "    $CHANGED_WORKFLOWS"
-
-  # 2. Validate YAML syntax
-  if command -v yamllint &>/dev/null; then
-    for f in $CHANGED_WORKFLOWS; do
-      yamllint "$f" && echo "  OK: $f passes YAML lint" || echo "  WARN: $f has YAML issues"
-    done
-  else
-    # Fallback: Python YAML parse
-    for f in $CHANGED_WORKFLOWS; do
-      python3 -c "import yaml; yaml.safe_load(open('$f'))" 2>/dev/null && \
-        echo "  OK: $f YAML syntax valid" || \
-        echo "  FAIL: $f has YAML syntax errors"
-    done
-  fi
-
-  # 3. Run actionlint if available
-  if command -v actionlint &>/dev/null; then
-    for f in $CHANGED_WORKFLOWS; do
-      actionlint "$f" && echo "  OK: $f passes actionlint" || echo "  WARN: $f has actionlint issues"
-    done
-  fi
-
-  # 4. Check common pitfalls
-  for f in $CHANGED_WORKFLOWS; do
-    # Missing permissions block
-    if ! grep -q 'permissions:' "$f"; then
-      echo "  WARNING: $f missing permissions block — add one for security"
-    fi
-    # npm publish without NPM_TOKEN
-    if grep -q 'npm publish\|npx semantic-release' "$f" && ! grep -q 'NPM_TOKEN' "$f"; then
-      echo "  WARNING: $f has npm publish/semantic-release but no NPM_TOKEN in secrets"
-    fi
-    # Hardcoded Node versions
-    if grep -q 'node-version: [0-9]' "$f"; then
-      echo "  NOTE: $f has hardcoded Node version — consider node-version-file: .nvmrc"
-    fi
-  done
-
-  # 5. Suggest local dry-run
-  if command -v act &>/dev/null; then
-    echo "  SUGGESTION: Run 'act push --dry-run' to test workflows locally"
-  fi
-fi
-```
-
-Checklist:
-- [ ] YAML syntax validated for all changed workflow files
-- [ ] No missing permissions, secrets, or hardcoded versions flagged
-- [ ] Local dry-run suggested if `act` is available
-
 ### 7. Manual Verification Handover
 
 Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.
 
+
+### 6a. CI dry-run sub-step
+
+If this cycle modified files in `.github/workflows/`, run the CI dry-run procedure documented in [REFERENCE.md](REFERENCE.md#ci-dry-run).
+
 ## Checklist Per Cycle
 
 ```
@@ -150,26 +95,6 @@ Once all tests pass: locate the Verification Script in the active epic capsule,
 [ ] verify: command passes
 ```
 
-## --config mode
-
-For pure-config tasks (update package.json, edit YAML, tweak manifest) where there is no test infrastructure to write against. The RED state is "verify command fails"; GREEN is "verify command passes."
-
-**When to use:** task has a runnable `verify:` command and the deliverable is a config file change with no new behavior to unit-test. Invoke as `develop-tdd --config`.
-
-**Cycle:**
-
-```
-RED:    Run verify command → it fails (expected)
-GREEN:  Apply config change → verify passes
-COMMIT: commit: chore(<scope>): <change>
-```
-
-**Rules:**
-- Skips test-writing phase entirely — do NOT write a test file for config tasks.
-- `verify:` command is **required** and must be runnable (no placeholder).
-- Commit message follows Conventional Commits (`chore:` or `feat:` as appropriate).
-- Still runs full `verify-work` after all tasks complete.
-
 ## Handoff
 
 Gate: READY -> next: verify-work

package/.pi/skills/migrate-spec/SKILL.md

@@ -48,20 +48,7 @@ If none found: ask the user which framework before proceeding.
 
 List every artifact found matching the detected framework. Present the list to the user:
 
-```
-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]
-```
+See [REFERENCE.md](REFERENCE.md) — `Detected: GSD...`
 
 → verify: `find . -maxdepth 4 \( -name "ROADMAP.md" -o -name "spec.md" -o -name "prd.md" -o -name "REQUIREMENTS.md" \) 2>/dev/null | grep -v ".git" | head -15`
 
@@ -77,17 +64,7 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 
 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:
 
-```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
-```
+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.
 
@@ -99,20 +76,7 @@ See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-
 
 When source has FR-XX or UJ-XX IDs, emit `specs/product/REQUIREMENTS_TRACE.yaml` for end-to-end requirement traceability:
 
-```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
-```
+See [REFERENCE.md](REFERENCE.md) — `trace:...`
 
 **Existing trace file:** If `REQUIREMENTS_TRACE.yaml` already exists, prompt: "REQUIREMENTS_TRACE.yaml exists. [overwrite / merge / skip]"
 
@@ -130,170 +94,14 @@ See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirement
 
 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:
 
-```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
-```
+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:
 
-```yaml
-handoff:
-  last_step_completed: "..."
-  open_decisions: []  # None — all decisions resolved during migration
-  required_reading: [...]
-  next_skill: survey-context
-```
+See [REFERENCE.md](REFERENCE.md) — `handoff:...`
 
 → verify: `grep -q 'handoff:' specs/state.yaml && grep -q 'last_step_completed' specs/state.yaml && echo "ok" || echo "MISSING or INCOMPLETE: handoff block"`
 
-### 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"`
-
-### 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.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`.
-
 ---
 
 # migrate-spec Reference — GSD
@@ -430,6 +238,8 @@ These GSD artifacts are not migrated — they are execution records, not plannin
 
 ---
 
+# Migrate Spec — Reference
+
 # migrate-spec Reference — spec-kit, BMAD, Learnings
 
 Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.
@@ -764,3 +574,269 @@ two_pass_spec:  # Optional: only if user activates two-pass spec writing gate
   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.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"`