From 8ecb1de3069e6268b8fdcf29c0abfeca1e03d10e Mon Sep 17 00:00:00 2001 From: Caleb Allen Date: Sun, 8 Mar 2026 12:12:50 -0400 Subject: [PATCH] docs: create multi-library roadmap (4 phases, 23 requirements) Phases 10-13 for v1.1 Multi-Library Support: - Phase 10: Schema & Migration (libraries table, library_id FK, phantom columns) - Phase 11: Per-Library Scan Pipeline (sequential coordination, per-library progress) - Phase 12: Library CRUD & Data Integrity (add/rename/remove, orphan cleanup, FTS5) - Phase 13: Library Views & Phantom Tracks (unified views, filtering, phantom display) --- .planning/REQUIREMENTS.md | 52 ++++++++++++++-------------- .planning/ROADMAP.md | 72 ++++++++++++++++++++++++++++----------- .planning/STATE.md | 30 +++++++++------- 3 files changed, 96 insertions(+), 58 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index eb330c2..76bc07d 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -180,34 +180,34 @@ Which phases cover which requirements. Updated during roadmap creation. | KEY-03 | Phase 9 | Complete | | KEY-04 | Phase 9 | Complete | | KEY-05 | Phase 9 | Complete | -| LIB-01 | TBD | Pending | -| LIB-02 | TBD | Pending | -| LIB-03 | TBD | Pending | -| LIB-04 | TBD | Pending | -| LIB-05 | TBD | Pending | -| LIB-06 | TBD | Pending | -| LSCAN-01 | TBD | Pending | -| LSCAN-02 | TBD | Pending | -| LSCAN-03 | TBD | Pending | -| LSCAN-04 | TBD | Pending | -| LSCAN-05 | TBD | Pending | -| VIEW-01 | TBD | Pending | -| VIEW-02 | TBD | Pending | -| VIEW-03 | TBD | Pending | -| VIEW-04 | TBD | Pending | -| PLAY-01 | TBD | Pending | -| PLAY-02 | TBD | Pending | -| PLAY-03 | TBD | Pending | -| PLAY-04 | TBD | Pending | -| DATA-01 | TBD | Pending | -| DATA-02 | TBD | Pending | -| DATA-03 | TBD | Pending | -| DATA-04 | TBD | Pending | +| LIB-01 | Phase 12 | Pending | +| LIB-02 | Phase 12 | Pending | +| LIB-03 | Phase 12 | Pending | +| LIB-04 | Phase 10 | Pending | +| LIB-05 | Phase 10 | Pending | +| LIB-06 | Phase 12 | Pending | +| LSCAN-01 | Phase 11 | Pending | +| LSCAN-02 | Phase 11 | Pending | +| LSCAN-03 | Phase 11 | Pending | +| LSCAN-04 | Phase 11 | Pending | +| LSCAN-05 | Phase 10 | Pending | +| VIEW-01 | Phase 13 | Pending | +| VIEW-02 | Phase 13 | Pending | +| VIEW-03 | Phase 13 | Pending | +| VIEW-04 | Phase 13 | Pending | +| PLAY-01 | Phase 13 | Pending | +| PLAY-02 | Phase 13 | Pending | +| PLAY-03 | Phase 13 | Pending | +| PLAY-04 | Phase 12 | Pending | +| DATA-01 | Phase 10 | Pending | +| DATA-02 | Phase 12 | Pending | +| DATA-03 | Phase 12 | Pending | +| DATA-04 | Phase 10 | Pending | **Coverage:** -- v1.1 requirements: 28 total (8 complete + 20 pending) -- Mapped to phases: 8 (Phase 9 complete) -- Awaiting roadmap: 20 +- v1.1 requirements: 31 total (8 complete + 23 pending) +- Mapped to phases: 31/31 ✓ (Phase 9: 8 complete, Phases 10-13: 23 pending) +- No orphaned requirements --- *Requirements defined: 2026-03-06* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 5b934a8..ea8244c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -7,7 +7,7 @@ ## Milestones - ✅ **v1.0 Consolidation** — Phases 1-8 (shipped 2026-03-05) — [archive](milestones/v1.0-ROADMAP.md) -- 🔄 **v1.1 Multi-Library Support** — Phase 9 complete, multi-library phases TBD (in progress) +- 🔄 **v1.1 Multi-Library Support** — Phase 9 complete, Phases 10-13 in progress ## Phases @@ -25,10 +25,13 @@ -### v1.1 Multi-Library Support (Phase 9 + Multi-Library Phases) +### v1.1 Multi-Library Support (Phases 9-13) - [x] **Phase 9: Scan Cancellation & Keyboard Shortcuts** — Cancellable library scans and configurable keyboard shortcuts -- [ ] **Phases 10+: Multi-Library Support** — TBD (awaiting roadmap creation from gsd-roadmapper) +- [ ] **Phase 10: Schema & Migration** — Libraries table, library_id FK, playlist_tracks phantom rebuild, config migration +- [ ] **Phase 11: Per-Library Scan Pipeline** — Scan pipeline refactored for per-library scanning with sequential coordination +- [ ] **Phase 12: Library CRUD & Data Integrity** — Library management API, orphan cleanup, queue/playlist lifecycle, library manager UI +- [ ] **Phase 13: Library Views & Phantom Tracks** — Filtered presentation across all views, search, browse, and phantom track display ## Phase Details @@ -50,23 +53,51 @@ Plans: - [x] 09-04-PLAN.md — Frontend shortcut settings UI (record-style capture, conflict detection) - [x] 09-05-PLAN.md — Integration verification checkpoint -### Multi-Library Phases (10+) +### Phase 10: Schema & Migration +**Goal:** The database supports multiple libraries and phantom tracks — existing users upgrade seamlessly +**Depends on:** Phase 9 (builds on existing schema and scan infrastructure) +**Requirements:** DATA-01, DATA-04, LIB-04, LIB-05, LSCAN-05 +**Success Criteria** (what must be TRUE): + 1. A fresh install creates a `libraries` table and `audio_files.library_id` FK — new audio files are always associated with a library + 2. An existing user's database is migrated on first launch: their single directory becomes a named library, all existing audio_files get that library_id, and everything works without any user action + 3. The `playlist_tracks` table supports nullable `audio_file_id` with phantom metadata columns — the schema is ready for phantom track preservation + 4. All migration operations complete atomically — a crash mid-migration leaves the database unchanged (not half-migrated) +**Plans:** TBD -**Awaiting roadmap creation.** The gsd-roadmapper will create phased breakdown covering 20 requirements: -- LIB-01..06 (Library Management) -- LSCAN-01..05 (Library Scanning) -- VIEW-01..04 (Unified Presentation) -- PLAY-01..04 (Playlists & Queue) -- DATA-01..04 (Data Integrity) +### Phase 11: Per-Library Scan Pipeline +**Goal:** Users can scan individual libraries independently with proper sequential coordination +**Depends on:** Phase 10 (requires libraries table and library_id FK) +**Requirements:** LSCAN-01, LSCAN-02, LSCAN-03, LSCAN-04 +**Success Criteria** (what must be TRUE): + 1. User can trigger a scan for a specific library and only that library's directory is scanned — other libraries are untouched + 2. Only one library scans at a time — requesting a second scan while one is running either queues it or is rejected with clear feedback + 3. Scan progress UI identifies which library is currently being scanned (library name visible in progress indicator) + 4. Existing cancel and pause/resume controls work correctly for per-library scans — cancelling one library's scan doesn't affect others +**Plans:** TBD -**Architecture decisions:** -- Hybrid model: `library_id` FK on `audio_files` only; artists/albums/genres stay global -- Libraries stored in SQLite, not TOML config -- Sequential scanning (one library at a time) -- Phantom tracks for playlist preservation on library removal -- Backend filtering for library views +### Phase 12: Library CRUD & Data Integrity +**Goal:** Users can add, rename, and remove libraries through the UI with correct data lifecycle management +**Depends on:** Phase 11 (requires per-library scanning for add-then-scan workflow) +**Requirements:** LIB-01, LIB-02, LIB-03, LIB-06, DATA-02, DATA-03, PLAY-04 +**Success Criteria** (what must be TRUE): + 1. User can add a new library via folder picker, give it a name, and trigger a scan — new tracks appear in the library + 2. User can rename a library's display name and the change reflects everywhere immediately + 3. User can remove a library — its tracks are deleted, shared artists/albums/genres used only by that library are cleaned up, but entities shared with other libraries survive intact + 4. Removing a library cleans up FTS5 search index entries for that library's tracks (no stale search results) + 5. Queue tracks from a removed library are cascade-deleted; the queue continues playing from the next valid track +**Plans:** TBD -See `.planning/research/SUMMARY.md` for full research. +### Phase 13: Library Views & Phantom Tracks +**Goal:** Users experience a unified multi-library presentation with optional filtering and graceful playlist preservation +**Depends on:** Phase 12 (requires library CRUD and data integrity for full integration) +**Requirements:** VIEW-01, VIEW-02, VIEW-03, VIEW-04, PLAY-01, PLAY-02, PLAY-03 +**Success Criteria** (what must be TRUE): + 1. The default track list shows tracks from all libraries merged — the user sees their complete collection as one unified view + 2. User can select a specific library from a filter control and all views (tracks, albums, artists, genres) show only that library's content + 3. Search results respect the active library filter — searching with a library selected returns only matches from that library; with "All Libraries" selected, searches everything + 4. Playlists can contain tracks from multiple libraries — adding tracks from different libraries to the same playlist works naturally + 5. When a library is removed, its tracks in playlists become phantom entries — visually distinguished (greyed out / icon) with preserved title, artist, album metadata instead of disappearing +**Plans:** TBD ## Progress @@ -81,8 +112,11 @@ See `.planning/research/SUMMARY.md` for full research. | 7. Backend Performance | v1.0 | 2/2 | Complete | 2026-03-05 | | 8. Frontend Performance & UX | v1.0 | 4/4 | Complete | 2026-03-05 | | 9. Scan Cancellation & Keyboard Shortcuts | v1.1 | 5/5 | Complete | 2026-03-07 | -| 10+ Multi-Library phases | v1.1 | 0/? | Awaiting roadmap | - | +| 10. Schema & Migration | v1.1 | 0/? | Not started | - | +| 11. Per-Library Scan Pipeline | v1.1 | 0/? | Not started | - | +| 12. Library CRUD & Data Integrity | v1.1 | 0/? | Not started | - | +| 13. Library Views & Phantom Tracks | v1.1 | 0/? | Not started | - | --- *Roadmap created: 2026-02-27* -*Last updated: 2026-03-08 — v1.1 restructured for multi-library support, old phases 10-14 deferred* +*Last updated: 2026-03-08 — Multi-library phases 10-13 created from 23 requirements* diff --git a/.planning/STATE.md b/.planning/STATE.md index f3c6bad..e2d47a5 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,7 +5,7 @@ milestone_name: Multi-Library Support status: planning last_updated: "2026-03-08" progress: - total_phases: 1 + total_phases: 5 completed_phases: 1 total_plans: 5 completed_plans: 5 @@ -18,27 +18,30 @@ progress: See: .planning/PROJECT.md (updated 2026-03-08) **Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy. -**Current focus:** v1.1 Multi-Library Support — roadmap planning +**Current focus:** v1.1 Multi-Library Support — Phase 10 (Schema & Migration) ## Current Position -Phase: 9 — Scan Cancellation & Keyboard Shortcuts (last completed) -Plan: 5 of 5 -Status: Complete — awaiting multi-library roadmap -Progress: Roadmap creation in progress -Last activity: 2026-03-08 — Restructured v1.1 milestone for multi-library support +Phase: 10 — Schema & Migration (next up) +Plan: TBD (awaiting plan creation) +Status: Roadmap created — ready for phase planning +Progress: ████░░░░░░░░░░░░░░░░ 1/5 phases complete (Phase 9) +Last activity: 2026-03-08 — Multi-library roadmap created (Phases 10-13) ### Phase Overview | Phase | Status | |-------|--------| | 9. Scan Cancellation & Keyboard Shortcuts | Complete (5/5 plans) ✅ | -| 10+ Multi-Library phases | Awaiting roadmap creation | +| 10. Schema & Migration | Not started | +| 11. Per-Library Scan Pipeline | Not started | +| 12. Library CRUD & Data Integrity | Not started | +| 13. Library Views & Phantom Tracks | Not started | ## Performance Metrics **v1.0 baseline:** 8 phases, 17 plans, 34 tasks in 6 days (107 commits) -**v1.1 scope:** Phase 9 complete (5 plans), multi-library phases TBD (20 requirements) +**v1.1 scope:** Phase 9 complete (5 plans), Phases 10-13 pending (20 requirements across 4 phases) | Phase | Plan | Duration | Tasks | Files | |-------|------|----------|-------|-------| @@ -73,6 +76,7 @@ Decisions from v1.0 are archived in PROJECT.md Key Decisions table. Key patterns | CASCADE for queue_tracks FK | Queue is ephemeral, not user-curated like playlists | | Sequential scanning | SQLite single-writer makes parallel scans pointless | | Backend filtering, not frontend | Don't load 150K tracks when viewing one library | +| 4 multi-library phases (10-13) | Natural delivery boundaries: schema → scan → CRUD → views, each phase delivers verifiable capability | ### Warnings (carry forward) @@ -96,9 +100,9 @@ Decisions from v1.0 are archived in PROJECT.md Key Decisions table. Key patterns ### Last Session **Date:** 2026-03-08 -**What happened:** Restructured v1.1 milestone from "Features & Extensibility" to "Multi-Library Support". Ran 4 parallel researchers (Stack, Features, Architecture, Pitfalls). Defined 20 multi-library requirements (LIB, LSCAN, VIEW, PLAY, DATA). Deferred TAG/SMRT/GAP/MB/LAYOUT/PLUG to future milestones. Updated PROJECT.md, REQUIREMENTS.md, STATE.md, ROADMAP.md. -**Where we stopped:** Planning documents updated, ready for roadmap creation -**Next action:** Run gsd-roadmapper to create phased multi-library roadmap (phases 10+) +**What happened:** Created multi-library roadmap (Phases 10-13) from 20 requirements. Phase 10 = Schema & Migration (DATA-01, DATA-04, LIB-04, LIB-05, LSCAN-05). Phase 11 = Per-Library Scan Pipeline (LSCAN-01..04). Phase 12 = Library CRUD & Data Integrity (LIB-01..03, LIB-06, DATA-02, DATA-03, PLAY-04). Phase 13 = Library Views & Phantom Tracks (VIEW-01..04, PLAY-01..03). +**Where we stopped:** Roadmap written, ready for phase planning +**Next action:** Run `gsd-plan-phase 10` to create plans for Schema & Migration --- *State initialized: 2026-02-27* @@ -111,4 +115,4 @@ Decisions from v1.0 are archived in PROJECT.md Key Decisions table. Key patterns | 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/) | Last activity: 2026-03-08 - Completed quick task 18: add multi-column metadata display to playlist-details -*Last updated: 2026-03-08 — v1.1 restructured for multi-library support* +*Last updated: 2026-03-08 — Multi-library roadmap created (Phases 10-13)*