diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 5a723ff..f663a9e 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -65,26 +65,26 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| OGG-01 | TBD | Pending | -| OGG-02 | TBD | Pending | -| OGG-03 | TBD | Pending | -| OGG-04 | TBD | Pending | -| OGG-05 | TBD | Pending | -| OGG-06 | TBD | Pending | -| WAV-01 | TBD | Pending | -| WAV-02 | TBD | Pending | -| WAV-03 | TBD | Pending | -| WAV-04 | TBD | Pending | -| WAV-05 | TBD | Pending | -| WAV-06 | TBD | Pending | -| CLEAN-01 | TBD | Pending | -| CLEAN-02 | TBD | Pending | +| WAV-01 | Phase 19 | Pending | +| WAV-02 | Phase 19 | Pending | +| WAV-03 | Phase 19 | Pending | +| WAV-04 | Phase 19 | Pending | +| WAV-05 | Phase 19 | Pending | +| WAV-06 | Phase 19 | Pending | +| OGG-01 | Phase 20 | Pending | +| OGG-02 | Phase 20 | Pending | +| OGG-03 | Phase 20 | Pending | +| OGG-04 | Phase 20 | Pending | +| OGG-05 | Phase 20 | Pending | +| OGG-06 | Phase 20 | Pending | +| CLEAN-01 | Phase 21 | Pending | +| CLEAN-02 | Phase 21 | Pending | **Coverage:** - v1.2.1 requirements: 14 total -- Mapped to phases: 0 -- Unmapped: 14 +- Mapped to phases: 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* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index dafe715..b783e6e 100644 --- a/.planning/ROADMAP.md +++ b/.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 +### 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* diff --git a/.planning/STATE.md b/.planning/STATE.md index 61e85bb..8d2a32e 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,10 +2,10 @@ gsd_state_version: 1.0 milestone: "v1.2.1" milestone_name: "Format Parity" -status: defining_requirements -last_updated: "2026-03-18T19:00:00.000Z" +status: roadmap_complete +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 -Last activity: 2026-03-18 — Milestone v1.2.1 started +Status: Roadmap complete, awaiting `/gsd-plan-phase 19` +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/. -**Where we stopped:** Milestone v1.2 complete and archived. -**Next action:** `/gsd-new-milestone` to plan next milestone +**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:** Roadmap created, ready for phase planning. +**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 updated: 2026-03-18 — v1.2 milestone complete and archived* +Last activity: 2026-03-18 - v1.2.1 roadmap created +*Last updated: 2026-03-18 — v1.2.1 roadmap created*