docs: create milestone v1.2.1 roadmap (3 phases)

.planning/REQUIREMENTS.md

@@ -65,26 +65,26 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| OGG-01 | TBD | Pending |
+| WAV-01 | Phase 19 | Pending |
-| OGG-02 | TBD | Pending |
+| WAV-02 | Phase 19 | Pending |
-| OGG-03 | TBD | Pending |
+| WAV-03 | Phase 19 | Pending |
-| OGG-04 | TBD | Pending |
+| WAV-04 | Phase 19 | Pending |
-| OGG-05 | TBD | Pending |
+| WAV-05 | Phase 19 | Pending |
-| OGG-06 | TBD | Pending |
+| WAV-06 | Phase 19 | Pending |
-| WAV-01 | TBD | Pending |
+| OGG-01 | Phase 20 | Pending |
-| WAV-02 | TBD | Pending |
+| OGG-02 | Phase 20 | Pending |
-| WAV-03 | TBD | Pending |
+| OGG-03 | Phase 20 | Pending |
-| WAV-04 | TBD | Pending |
+| OGG-04 | Phase 20 | Pending |
-| WAV-05 | TBD | Pending |
+| OGG-05 | Phase 20 | Pending |
-| WAV-06 | TBD | Pending |
+| OGG-06 | Phase 20 | Pending |
-| CLEAN-01 | TBD | Pending |
+| CLEAN-01 | Phase 21 | Pending |
-| CLEAN-02 | TBD | Pending |
+| CLEAN-02 | Phase 21 | Pending |
 
 **Coverage:**
 - v1.2.1 requirements: 14 total
-- Mapped to phases: 0
+- Mapped to phases: 14
-- Unmapped: 14
+- Unmapped: 0 ✓
 
 ---
 *Requirements defined: 2026-03-18*
-*Last updated: 2026-03-18 after initial definition*
+*Last updated: 2026-03-18 — traceability updated with phase mappings*

.planning/ROADMAP.md

@@ -8,6 +8,7 @@
 - ✅ **v1.0 Consolidation** — Phases 1-8 (shipped 2026-03-05) — [archive](milestones/v1.0-ROADMAP.md)
 - ✅ **v1.1 Multi-Library Support** — Phases 9-14 (shipped 2026-03-16) — [archive](milestones/v1.1-ROADMAP.md)
 - ✅ **v1.2 Tag Editing** — Phases 15-18 (shipped 2026-03-18) — [archive](milestones/v1.2-ROADMAP.md)
+- 🔄 **v1.2.1 Format Parity** — Phases 19-21 (in progress)
 
 ## Phases
 
@@ -45,10 +46,51 @@
 - [x] Phase 17: Single Track Edit (2/2 plans) — completed 2026-03-18
 - [x] Phase 18: Batch Edit (2/2 plans) — completed 2026-03-18
 
-**Deferred:** Phase 19 (OGG Vorbis Tag Writing) — stretch goal, deferred to future milestone
+**Deferred:** Phase 19 (OGG Vorbis Tag Writing) — stretch goal, deferred to v1.2.1
 
 </details>
 
+### v1.2.1 Format Parity (Phases 19-21)
+
+- [ ] **Phase 19: WAV Tag Writer** — Full metadata and cover art writing for WAV files via ID3v2-in-RIFF
+- [ ] **Phase 20: OGG Vorbis Tag Writer** — Full metadata and cover art writing for OGG Vorbis files via custom page rewriter
+- [ ] **Phase 21: Cleanup** — Fix lint warnings and small issues carried forward from v1.2
+
+## Phase Details
+
+### Phase 19: WAV Tag Writer
+**Goal**: Users can edit metadata and cover art on WAV files with the same experience as MP3/FLAC
+**Depends on**: Nothing (extends existing tag writing pipeline)
+**Requirements**: WAV-01, WAV-02, WAV-03, WAV-04, WAV-05, WAV-06
+**Success Criteria** (what must be TRUE):
+  1. User can open a WAV file in the single-track editor, change any of the 8 text fields, save, and see the changes persist after re-scanning the library
+  2. User can embed, replace, or remove cover art on a WAV file and see the updated artwork in the track list and player
+  3. Editing a WAV file's tags does not alter audio playback — the file sounds identical before and after
+  4. Existing metadata in the WAV file that wasn't edited (RIFF INFO chunks, bext, cue markers) survives the tag write unchanged
+  5. If the app crashes or loses power during a WAV tag write, the original file is intact (not corrupted or truncated)
+**Plans**: TBD
+
+### Phase 20: OGG Vorbis Tag Writer
+**Goal**: Users can edit metadata and cover art on OGG Vorbis files with the same experience as MP3/FLAC/WAV
+**Depends on**: Phase 19 (pipeline extension pattern proven)
+**Requirements**: OGG-01, OGG-02, OGG-03, OGG-04, OGG-05, OGG-06
+**Success Criteria** (what must be TRUE):
+  1. User can open an OGG Vorbis file in the single-track editor, change any of the 8 text fields, save, and see the changes persist after re-scanning the library
+  2. User can embed, replace, or remove cover art on an OGG Vorbis file via METADATA_BLOCK_PICTURE and see the updated artwork in the track list and player
+  3. Editing an OGG file's tags does not alter audio playback — the file sounds identical before and after
+  4. Existing Vorbis Comments that weren't edited (ReplayGain, lyrics, custom fields) survive the tag write unchanged
+  5. If the app crashes or loses power during an OGG tag write, the original file is intact (not corrupted or truncated)
+**Plans**: TBD
+
+### Phase 21: Cleanup
+**Goal**: Codebase is clean — no lint warnings or loose ends from tag editing work
+**Depends on**: Phase 20 (cleanup after all format work is done)
+**Requirements**: CLEAN-01, CLEAN-02
+**Success Criteria** (what must be TRUE):
+  1. `make lint` passes with zero warnings in dbsync.go and tagwriter.go (nlreturn/wsl violations resolved)
+  2. Any small issues discovered during v1.2 tag editing milestone are resolved
+**Plans**: TBD
+
 ## Progress
 
 | Phase | Milestone | Plans Complete | Status | Completed |
@@ -71,7 +113,10 @@
 | 16. Tag Writing & Database Sync | v1.2 | 3/3 | Complete | 2026-03-17 |
 | 17. Single Track Edit | v1.2 | 2/2 | Complete | 2026-03-18 |
 | 18. Batch Edit | v1.2 | 2/2 | Complete | 2026-03-18 |
+| 19. WAV Tag Writer | v1.2.1 | 0/? | Not started | - |
+| 20. OGG Vorbis Tag Writer | v1.2.1 | 0/? | Not started | - |
+| 21. Cleanup | v1.2.1 | 0/? | Not started | - |
 
 ---
 *Roadmap created: 2026-02-27*
-*Last updated: 2026-03-18 — v1.2 Tag Editing milestone shipped*
+*Last updated: 2026-03-18 — v1.2.1 Format Parity roadmap created*

.planning/STATE.md

@@ -2,10 +2,10 @@
 gsd_state_version: 1.0
 milestone: "v1.2.1"
 milestone_name: "Format Parity"
-status: defining_requirements
+status: roadmap_complete
-last_updated: "2026-03-18T19:00:00.000Z"
+last_updated: "2026-03-18T20:00:00.000Z"
 progress:
-  total_phases: 0
+  total_phases: 3
   completed_phases: 0
   total_plans: 0
   completed_plans: 0
@@ -18,14 +18,19 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-18)
 
 **Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy.
-**Current focus:** v1.2.1 Format Parity — defining requirements
+**Current focus:** v1.2.1 Format Parity — roadmap complete, ready for phase planning
 
 ## Current Position
 
-Phase: Not started (defining requirements)
+Phase: 19 — WAV Tag Writer (not yet planned)
 Plan: —
-Status: Defining requirements
+Status: Roadmap complete, awaiting `/gsd-plan-phase 19`
-Last activity: 2026-03-18 — Milestone v1.2.1 started
+Last activity: 2026-03-18 — Roadmap created for v1.2.1
+
+```
+v1.2.1 Format Parity
+[░░░░░░░░░░░░░░░░░░░░] 0/3 phases
+```
 
 ## Performance Metrics
 
@@ -60,22 +65,22 @@ All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. K
 - FLAC files require full rewrite for tag changes — atomic write-to-temp-then-rename mandatory
 - Currently-playing file must be stopped before writing (WRITE-06) — Windows file locking is especially strict
 - Shared entity fan-out — editing one track's artist must NOT mutate the shared artist_credit row
-- **Phase 19:** Custom OGG page rewriter — prototype before committing; consider dropping if too complex
+- OGG CRC32 uses non-standard MSB-first bit ordering — Go's `hash/crc32` produces wrong checksums
+- OGG page sequence numbers must be renumbered when comment header page count changes
+- WAV RIFF chunks must start at even byte offsets — odd-length chunks need a padding byte
 
 ### Deferred Improvements
 
 - **Bulk phantom matching performance** — O(n×3) round trips per phantom. Revisit if large external playlist imports occur.
-- **OGG Vorbis tag writing** — Stretch goal deferred from v1.2. Custom OGG page rewriter is medium-high risk.
-- **Pre-existing lint warnings** — nlreturn/wsl warnings in dbsync.go and tagwriter.go. Clean up in a future quick task.
 
 ## Session Continuity
 
 ### Last Session
 
 **Date:** 2026-03-18
-**What happened:** Completed v1.2 Tag Editing milestone. All 4 phases (15-18) shipped. 19/20 requirements fulfilled (WRITE-03 OGG deferred as stretch goal). Milestone archived to .planning/milestones/.
+**What happened:** Created v1.2.1 Format Parity roadmap. 3 phases (19-21): WAV Tag Writer → OGG Vorbis Tag Writer → Cleanup. All 14 requirements mapped.
-**Where we stopped:** Milestone v1.2 complete and archived.
+**Where we stopped:** Roadmap created, ready for phase planning.
-**Next action:** `/gsd-new-milestone` to plan next milestone
+**Next action:** `/gsd-plan-phase 19` to plan WAV Tag Writer
 
 ---
 *State initialized: 2026-02-27*
@@ -88,5 +93,5 @@ All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. K
 | 18 | add multi-column metadata display to playlist-details | 2026-03-08 | ce23177 | [18-add-multi-column-metadata-display-to-pla](./quick/18-add-multi-column-metadata-display-to-pla/) |
 | 19 | fix phantom playlist tracks with multi-root path resolution | 2026-03-16 | 9144ded | [19-fix-phantom-playlist-tracks](./quick/19-fix-phantom-playlist-tracks/) |
 
-Last activity: 2026-03-18 - v1.2 Tag Editing milestone shipped
+Last activity: 2026-03-18 - v1.2.1 roadmap created
-*Last updated: 2026-03-18 — v1.2 milestone complete and archived*
+*Last updated: 2026-03-18 — v1.2.1 roadmap created*