bigpowers 2.28.0 → 2.30.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.28.0",
+  "version": "2.30.0",
   "description": "70 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"

package/.pi/prompts/migrate-spec.md

@@ -71,6 +71,53 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 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:
+
+```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
+```
+
+**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:
+
+```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
+```
+
+**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 diff --name-only HEAD -- specs/ 2>/dev/null | head -20`
@@ -126,7 +173,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 ## Rules
 
-- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX become inline comments in bigpowers targets. Never silently renumber.
+- **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.
@@ -184,9 +231,9 @@ Transform:
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
 Transform:
-- Copy REQ-XX IDs as-is (preserve for cross-referencing)
-- Validated requirements → `in_scope` entries
-- Out-of-Scope → `out_of_scope` entries
+- 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
 
 ---
@@ -404,7 +451,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 - [ ] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
 - [ ] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session.
-- [ ] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability.
+- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
 
 ### From spec-kit
 
@@ -414,7 +461,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 ### From BMAD
 
-- [ ] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability.
+- [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
 - [ ] **`specs/DECISION-LOG.md`** — Lightweight decisions below ADR threshold.
 - [ ] **Adversarial review pass** — Critique epic shard before `develop-tdd`.
 
@@ -454,6 +501,62 @@ For lightweight decisions that don't warrant a full ADR:
 | 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
 ```
 
+### 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 format:

package/.pi/prompts/plan-release.md

@@ -57,9 +57,13 @@ Every task must have a `verify:` command. No verify command = not a task.
 
 ### 4. Save specs/release-plan.yaml
 
+> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
+> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
+> (the expectation), not a number you intend to enforce.
+
 ```yaml
 release:
-  version: "3.0.0"
+  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
   codename: "Feature Name"
   status: planning          # planning | in_progress | released
   semantic_release: true

package/.pi/prompts/session-state.md

@@ -108,8 +108,8 @@ active_epic_id: e02
 active_story_id: e02s01       # required when epic mode: folder
 active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
 release:
-  target_version: "3.0.0"
-  last_tag: null
+  target_version: null         # NOT tracked manually — semantic-release decides at merge
+  last_tag: v2.28.0            # mirror of `gh release view`, reference only
   last_publish: null
 epic_cycle:
   current_step: develop-tdd

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

@@ -73,6 +73,53 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 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:
+
+```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
+```
+
+**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:
+
+```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
+```
+
+**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 diff --name-only HEAD -- specs/ 2>/dev/null | head -20`
@@ -128,7 +175,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 ## Rules
 
-- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX become inline comments in bigpowers targets. Never silently renumber.
+- **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.
@@ -186,9 +233,9 @@ Transform:
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
 Transform:
-- Copy REQ-XX IDs as-is (preserve for cross-referencing)
-- Validated requirements → `in_scope` entries
-- Out-of-Scope → `out_of_scope` entries
+- 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
 
 ---
@@ -406,7 +453,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 - [ ] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
 - [ ] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session.
-- [ ] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability.
+- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
 
 ### From spec-kit
 
@@ -416,7 +463,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 ### From BMAD
 
-- [ ] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability.
+- [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
 - [ ] **`specs/DECISION-LOG.md`** — Lightweight decisions below ADR threshold.
 - [ ] **Adversarial review pass** — Critique epic shard before `develop-tdd`.
 
@@ -456,6 +503,62 @@ For lightweight decisions that don't warrant a full ADR:
 | 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
 ```
 
+### 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 format:

package/.pi/skills/plan-release/SKILL.md

@@ -59,9 +59,13 @@ Every task must have a `verify:` command. No verify command = not a task.
 
 ### 4. Save specs/release-plan.yaml
 
+> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
+> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
+> (the expectation), not a number you intend to enforce.
+
 ```yaml
 release:
-  version: "3.0.0"
+  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
   codename: "Feature Name"
   status: planning          # planning | in_progress | released
   semantic_release: true

package/.pi/skills/session-state/SKILL.md

@@ -110,8 +110,8 @@ active_epic_id: e02
 active_story_id: e02s01       # required when epic mode: folder
 active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
 release:
-  target_version: "3.0.0"
-  last_tag: null
+  target_version: null         # NOT tracked manually — semantic-release decides at merge
+  last_tag: v2.28.0            # mirror of `gh release view`, reference only
   last_publish: null
 epic_cycle:
   current_step: develop-tdd

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.30.0](https://github.com/danielvm-git/bigpowers/compare/v2.29.0...v2.30.0) (2026-06-26)
+
+
+### Features
+
+* **migrate-spec:** emit REQUIREMENTS_TRACE.yaml for FR-XX/UJ-XX IDs ([955a1fd](https://github.com/danielvm-git/bigpowers/commit/955a1fd37b898ec70a86895d8772f0ec6fb8a0fa))
+
+# [2.29.0](https://github.com/danielvm-git/bigpowers/compare/v2.28.0...v2.29.0) (2026-06-26)
+
+
+### Features
+
+* **migrate-spec:** promote ID tracking from comments to first-class YAML fields ([f1c8d73](https://github.com/danielvm-git/bigpowers/commit/f1c8d73a5140175fc0067a191f119eea70395075)), closes [#22](https://github.com/danielvm-git/bigpowers/issues/22)
+
 # [2.28.0](https://github.com/danielvm-git/bigpowers/compare/v2.27.0...v2.28.0) (2026-06-22)
 
 

package/CONVENTIONS.md

@@ -96,11 +96,16 @@ Epic IDs: `e01`, `e30`. Story IDs: `e01s01`. One FR in SCOPE may span multiple e
 
 When planning closes, copy to `specs/product/snapshots/release-<version>/` (`release-plan.yaml`, `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml`). No separate `baselines/` folder.
 
-### Semantic-release — three places
+### Semantic-release — the real version is never hand-tracked
 
-1. **Planning intent** — `specs/release-plan.yaml` → `release.version`, `release.bump_hint` (minor/patch/major expectation).
-2. **Published version** — repo root: `package.json`, git tag `vX.Y.Z`, `CHANGELOG.md` (CI semantic-release; not hand-edited in specs).
-3. **Dashboard optional** — `specs/state.yaml` → `release.last_tag`, `release.last_publish` (from tags/CI).
+> **The authority is `gh release view` / git tags.** semantic-release decides the version
+> at merge from Conventional Commits. Never hand-maintain a `target_version` to "predict" it —
+> that field drifts from reality every release. The specs only *mirror* the real tag for reference.
+
+1. **Planning intent (codename only)** — `specs/release-plan.yaml` → `release.version`, `release.bump_hint`.
+   Treat `version` as a non-authoritative label; if you write a number, mark it "mirror, not the authority".
+2. **Published version (authority)** — repo root `package.json`, git tag `vX.Y.Z`, `CHANGELOG.md` (CI semantic-release; not hand-edited in specs). Read with `gh release view`.
+3. **Dashboard mirror** — `specs/state.yaml` → `release.last_tag`, `release.last_publish` (copied from `gh release view`; `target_version` is `null` — not tracked manually).
 
 ### Guardrails and other artifacts
 

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-22T13:26:01Z
+**Generated:** 2026-06-26T22:23:41Z
 **Skills:** 70
 
 ---

package/migrate-spec/REFERENCE-GSD.md

@@ -48,9 +48,9 @@ Transform:
 GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
 
 Transform:
-- Copy REQ-XX IDs as-is (preserve for cross-referencing)
-- Validated requirements → `in_scope` entries
-- Out-of-Scope → `out_of_scope` entries
+- 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
 
 ---

package/migrate-spec/REFERENCE.md

@@ -134,7 +134,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 - [ ] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
 - [ ] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session.
-- [ ] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability.
+- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
 
 ### From spec-kit
 
@@ -144,7 +144,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 
 ### From BMAD
 
-- [ ] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability.
+- [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
 - [ ] **`specs/DECISION-LOG.md`** — Lightweight decisions below ADR threshold.
 - [ ] **Adversarial review pass** — Critique epic shard before `develop-tdd`.
 
@@ -184,6 +184,62 @@ For lightweight decisions that don't warrant a full ADR:
 | 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
 ```
 
+### 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 format:

package/migrate-spec/SKILL.md

@@ -74,6 +74,53 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 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:
+
+```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
+```
+
+**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:
+
+```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
+```
+
+**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 diff --name-only HEAD -- specs/ 2>/dev/null | head -20`
@@ -131,7 +178,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.
 
 ## Rules
 
-- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX become inline comments in bigpowers targets. Never silently renumber.
+- **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.

package/migrate-spec/templates/REQUIREMENTS_TRACE.yaml

@@ -0,0 +1,28 @@
+# Auto-generated from {{source_framework}} FR-XX / UJ-XX IDs during migration
+# Maps source requirements to bigpowers epic/story structure and verification commands.
+
+trace:
+  # Functional Requirements (FR-XX)
+  - id: FR-001
+    type: functional_requirement
+    description: "User can register with email/password"
+    source_artifact: "{{source_file}}"
+    epic: "e02-auth-ui"
+    story: "e02s01"
+    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK || echo FAIL"
+
+  # User Journeys (UJ-XX)
+  - id: UJ-001
+    type: user_journey
+    description: "New user completes registration flow"
+    source_artifact: "{{source_file}}"
+    epic: "e02-auth-ui"
+    story: "e02s01"
+    verify: "grep -q 'UJ-001' specs/epics/e02-auth-ui/epic.yaml && echo OK || echo FAIL"
+
+# Metadata
+metadata:
+  source_framework: "{{source_framework}}"  # e.g., BMAD, GSD, spec-kit
+  migrated_at: "{{timestamp}}"
+  total_requirements: "{{count}}"
+  coverage: "All FR-XX and UJ-XX IDs from source mapped to bigpowers artifacts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.28.0",
+  "version": "2.30.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {

package/plan-release/SKILL.md

@@ -58,9 +58,13 @@ Every task must have a `verify:` command. No verify command = not a task.
 
 ### 4. Save specs/release-plan.yaml
 
+> **Do NOT hand-track the real version.** semantic-release decides it at merge. `version` here is a
+> non-authoritative mirror/label only — read the real number with `gh release view`. Set `bump_hint`
+> (the expectation), not a number you intend to enforce.
+
 ```yaml
 release:
-  version: "3.0.0"
+  version: "2.29.0"         # mirror of next expected tag, NOT authoritative — gh release view wins
   codename: "Feature Name"
   status: planning          # planning | in_progress | released
   semantic_release: true

package/scripts/sync-status-from-epics.sh

@@ -37,6 +37,9 @@ for folder in sorted(epics_dir.glob("e*/")):
         em = re.search(r"^id:\s*(e\d+)", text, re.M)
         if em:
             keys.setdefault(em.group(1), "backlog")
+        # Parse inline story IDs from capsule epic.yaml (same pattern as flat files)
+        for sm in re.finditer(r"^\s+- id:\s*(e\d+s\d+)", text, re.M):
+            keys.setdefault(sm.group(1), "backlog")
     for story in (folder / "stories").glob("e*s*.md"):
         m = re.match(r"(e\d+s\d+)", story.name)
         if m:

package/session-state/SKILL.md

@@ -109,8 +109,8 @@ active_epic_id: e02
 active_story_id: e02s01       # required when epic mode: folder
 active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
 release:
-  target_version: "3.0.0"
-  last_tag: null
+  target_version: null         # NOT tracked manually — semantic-release decides at merge
+  last_tag: v2.28.0            # mirror of `gh release view`, reference only
   last_publish: null
 epic_cycle:
   current_step: develop-tdd

package/skills-lock.json

@@ -163,7 +163,7 @@
     },
     "migrate-spec": {
       "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.",
-      "sha256": "912299321559a5e2",
+      "sha256": "72006537bb12ab1a",
       "path": "migrate-spec/SKILL.md"
     },
     "model-domain": {
@@ -188,7 +188,7 @@
     },
     "plan-release": {
       "description": "\"RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics.\"",
-      "sha256": "4eeb65607ca2f799",
+      "sha256": "352d54fe911757ad",
       "path": "plan-release/SKILL.md"
     },
     "plan-work": {
@@ -263,7 +263,7 @@
     },
     "session-state": {
       "description": "Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached.",
-      "sha256": "4efd54a453e3e2cd",
+      "sha256": "0141daaed69b05dc",
       "path": "session-state/SKILL.md"
     },
     "setup-environment": {