docs(20-02): complete OGG Vorbis tag writer tests plan

.planning/REQUIREMENTS.md

@@ -14,7 +14,7 @@ Requirements for Format Parity milestone. Each maps to roadmap phases.
 - [x] **OGG-03**: OGG tag writes preserve audio data identically (lossless round-trip)
 - [x] **OGG-04**: User can embed, replace, and remove cover art in OGG Vorbis files via METADATA_BLOCK_PICTURE
 - [x] **OGG-05**: OGG tag writing uses crash-safe atomic writes (write-to-temp-then-rename)
-- [ ] **OGG-06**: OGG writer round-trip tests verify all fields via dhowden/tag read-back
+- [x] **OGG-06**: OGG writer round-trip tests verify all fields via dhowden/tag read-back
 
 ### WAV Tag Writing
 
@@ -76,7 +76,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | OGG-03 | Phase 20 | Complete |
 | OGG-04 | Phase 20 | Complete |
 | OGG-05 | Phase 20 | Complete |
-| OGG-06 | Phase 20 | Pending |
+| OGG-06 | Phase 20 | Complete |
 | CLEAN-01 | Phase 21 | Pending |
 | CLEAN-02 | Phase 21 | Pending |
 

.planning/ROADMAP.md

@@ -53,7 +53,7 @@
 ### v1.2.1 Format Parity (Phases 19-21)
 
 - [x] **Phase 19: WAV Tag Writer** — Full metadata and cover art writing for WAV files via ID3v2-in-RIFF (completed 2026-03-19)
-- [ ] **Phase 20: OGG Vorbis Tag Writer** — Full metadata and cover art writing for OGG Vorbis files via custom page rewriter
+- [x] **Phase 20: OGG Vorbis Tag Writer** — Full metadata and cover art writing for OGG Vorbis files via custom page rewriter (completed 2026-03-19)
 - [ ] **Phase 21: Cleanup** — Fix lint warnings and small issues carried forward from v1.2
 
 ## Phase Details
@@ -84,7 +84,7 @@ Plans:
   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:** 1/2 plans executed
+**Plans:** 2/2 plans complete
 
 Plans:
 - [ ] 20-01-PLAN.md — OGG page parser/writer, Vorbis Comment serializer, writeOggTags, pipeline integration
@@ -122,7 +122,7 @@ Plans:
 | 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 | 2/2 | Complete    | 2026-03-19 | - |
-| 20. OGG Vorbis Tag Writer | 1/2 | In Progress|  | - |
+| 20. OGG Vorbis Tag Writer | 2/2 | Complete   | 2026-03-19 | - |
 | 21. Cleanup | v1.2.1 | 0/? | Not started | - |
 
 ---

.planning/STATE.md

@@ -3,12 +3,12 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: in-progress
-last_updated: "2026-03-19T17:53:47Z"
+last_updated: "2026-03-19T18:02:38Z"
 progress:
   total_phases: 1
   completed_phases: 1
   total_plans: 4
-  completed_plans: 3
+  completed_plans: 4
 ---
 
 # YellowJacket — Project State
@@ -18,14 +18,14 @@ 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 — Phase 20 in progress (OGG Vorbis tag writer)
+**Current focus:** v1.2.1 Format Parity — Phase 20 complete (OGG Vorbis tag writer)
 
 ## Current Position
 
-Phase: 20 — OGG Vorbis Tag Writer (IN PROGRESS)
+Phase: 20 — OGG Vorbis Tag Writer (COMPLETE)
-Plan: 1 of 2 complete
+Plan: 2 of 2 complete
-Status: Plan 01 complete (implementation) — Plan 02 pending (tests)
+Status: Phase complete — all plans executed
-Last activity: 2026-03-19 — Completed 20-01-PLAN.md (OGG Vorbis tag writer implementation)
+Last activity: 2026-03-19 — Completed 20-02-PLAN.md (OGG Vorbis tag writer tests)
 
 ```
 v1.2.1 Format Parity
@@ -43,6 +43,7 @@ v1.2.1 Format Parity
 | 19-01 | WAV tag writer impl | 5 min | 2 | 4 |
 | 19-02 | WAV tag writer tests | 9 min | 3 | 2 |
 | 20-01 | OGG Vorbis tag writer impl | 3 min | 1 | 4 |
+| 20-02 | OGG Vorbis tag writer tests | 5 min | 3 | 1 |
 
 ## Accumulated Context
 
@@ -67,6 +68,7 @@ All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. K
 - Custom OGG CRC32 with precomputed lookup table (hash/crc32 uses incompatible reflected bit ordering)
 - Raw byte preservation for Vorbis Comment entries — [][]byte instead of []string for non-UTF-8 safety
 - METADATA_BLOCK_PICTURE + legacy COVERART/COVERARTMIME stripping on all OGG cover art operations
+- OGG test fixture built programmatically via createTestOGG using page structures (no embedded binary)
 
 ### Warnings (carry forward)
 
@@ -90,9 +92,9 @@ All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. K
 ### Last Session
 
 **Date:** 2026-03-19
-**What happened:** Executed 20-01-PLAN.md — OGG Vorbis tag writer implementation. Created custom OGG page parser/writer with MSB-first CRC32, Vorbis Comment packet serializer with METADATA_BLOCK_PICTURE cover art, and pipeline integration.
+**What happened:** Executed 20-02-PLAN.md — OGG Vorbis tag writer tests. 9 round-trip test functions covering all 6 OGG requirements with programmatic fixture builder and CRC32 validation.
-**Where we stopped:** Completed 20-01-PLAN.md
+**Where we stopped:** Completed 20-02-PLAN.md — Phase 20 complete
-**Next action:** Execute 20-02-PLAN.md (OGG Vorbis tag writer tests)
+**Next action:** Plan/execute next phase (Phase 21 or milestone completion)
 
 ---
 *State initialized: 2026-02-27*
@@ -105,5 +107,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-19 - completed 20-01-PLAN.md
+Last activity: 2026-03-19 - completed 20-02-PLAN.md
-*Last updated: 2026-03-19 — completed 20-01-PLAN.md (OGG Vorbis tag writer implementation)*
+*Last updated: 2026-03-19 — completed 20-02-PLAN.md (OGG Vorbis tag writer tests)*

.planning/phases/20-ogg-vorbis-tag-writer/20-02-SUMMARY.md

@@ -0,0 +1,101 @@
+---
+phase: 20-ogg-vorbis-tag-writer
+plan: 02
+subsystem: tagwriter
+tags: [ogg, vorbis, testing, round-trip, crc32, metadata, cover-art, dhowden-tag]
+
+# Dependency graph
+requires:
+  - phase: 20-ogg-vorbis-tag-writer
+    provides: writeOggTags, parseOggPages, oggCRC, pipeline integration
+provides:
+  - Comprehensive round-trip tests for OGG Vorbis tag writer (OGG-01 through OGG-06)
+  - Programmatic OGG Vorbis test fixture builder
+  - CRC32 validation against known vectors
+affects: [tagwriter]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [programmatic OGG Vorbis fixture generation, CRC32 known-vector validation]
+
+key-files:
+  created:
+    - backend/tagwriter/ogg_test.go
+  modified: []
+
+key-decisions:
+  - "Programmatic OGG fixture builder instead of embedded binary — avoids fragile byte literals, uses Plan 01 page structures directly"
+  - "CRC32 validated against independently computed known vectors (OggS→0x5fb0a94f, {1..8}→0x7d0f3681) plus fixture self-consistency"
+
+patterns-established:
+  - "OGG test fixture via createTestOGG: builds identification + comment + setup + audio pages programmatically"
+  - "Audio preservation test: capture audio page data before/after write, assert byte-identical"
+
+requirements-completed: [OGG-01, OGG-02, OGG-03, OGG-04, OGG-05, OGG-06]
+
+# Metrics
+duration: 5min
+completed: 2026-03-19
+---
+
+# Phase 20 Plan 02: OGG Vorbis Tag Writer Tests Summary
+
+**9 round-trip test functions covering all 6 OGG requirements with programmatic fixture builder, CRC32 known-vector validation, and dhowden/tag read-back verification**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-19T17:56:41Z
+- **Completed:** 2026-03-19T18:02:38Z
+- **Tasks:** 3
+- **Files modified:** 1
+
+## Accomplishments
+- Programmatic OGG Vorbis test fixture builder (createTestOGG) that constructs valid files from page structures
+- CRC32 validation against known vectors and fixture page self-consistency
+- All 9 text fields round-trip correctly through writeOggTags → metadata.ExtractTags (OGG-01)
+- Cover art embed, replace, and clear via METADATA_BLOCK_PICTURE (OGG-04)
+- Non-edited fields survive partial updates (OGG-02)
+- Audio page data byte-identical after tag write (OGG-03)
+- Atomic safety: corrupt files untouched on failure (OGG-05)
+- Non-Vorbis and multi-stream OGG rejection tested
+- Full tagwriter suite (MP3 + FLAC + WAV + OGG) passes with zero regressions
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create OGG test fixture and CRC32 validation** - `246a991` (test)
+2. **Task 2: Write round-trip tests for all OGG requirements** - `f13aa70` (test)
+3. **Task 3: Full test suite verification** - no commit (verification-only, all green)
+
+## Files Created/Modified
+- `backend/tagwriter/ogg_test.go` - 659 lines: test fixture builder, CRC32 validation, 9 round-trip test functions covering all OGG requirements
+
+## Decisions Made
+- Built OGG test fixture programmatically using Plan 01's page structures (buildVorbisIdentPacket, buildHeaderPages, writeOggPage) rather than embedding a pre-generated binary — gives full control and avoids fragile byte literals
+- CRC32 validated with independently computed known vectors plus self-consistency checks on fixture pages
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 20 (OGG Vorbis tag writer) is complete — implementation + tests both done
+- All format writers now have comprehensive test coverage: MP3, FLAC, WAV, OGG
+- Ready for phase transition to next milestone phase
+
+## Self-Check: PASSED
+
+All files verified on disk, all commits found in git log. ogg_test.go is 659 lines (exceeds 300 minimum).
+
+---
+*Phase: 20-ogg-vorbis-tag-writer*
+*Completed: 2026-03-19*