yellowjacket/.planning/STATE.md

gsd_state_version, milestone, milestone_name, status, last_updated, progress

gsd_state_version	milestone	milestone_name	status	last_updated	progress
1.0	v1.2	Tag Editing	roadmap_created	2026-03-16T21:00:00.000Z	total_phases completed_phases total_plans completed_plans 5 0 0 0

YellowJacket — Project State

Project Reference

See: .planning/PROJECT.md (updated 2026-03-16)

Core value: The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy. Current focus: v1.2 Tag Editing

Current Position

Phase: Phase 15 — Schema Migration & Write Safety (not started) Plan: — Status: Roadmap created, ready for phase planning Last activity: 2026-03-16 — v1.2 roadmap created (5 phases, 20 requirements mapped)

Phase Overview

Phase	Status
15. Schema Migration & Write Safety	Not started
16. Tag Writing & Database Sync	Not started
17. Single Track Edit	Not started
18. Batch Edit	Not started
19. OGG Vorbis Tag Writing	Not started

v1.2 Requirement Coverage

Category	Requirements	Phase(s)
Schema & Safety	SCHEMA-01, SCHEMA-02	Phase 15
Tag Writing	WRITE-01, WRITE-02	Phase 16
Tag Writing	WRITE-03	Phase 19
Tag Writing	WRITE-04, WRITE-05, WRITE-06	Phase 15, 16
Database Sync	SYNC-01, SYNC-02, SYNC-03, SYNC-04	Phase 16
Single Track Edit	EDIT-01, EDIT-02, EDIT-03, EDIT-04	Phase 17
Batch Edit	BATCH-01, BATCH-02, BATCH-03, BATCH-04	Phase 18

Performance Metrics

v1.0 baseline: 8 phases, 17 plans, 34 tasks in 6 days (107 commits) v1.1 baseline: 6 phases, 18 plans in 10 days (~85 commits) v1.2 scope: 5 phases, 20 requirements

Phase	Plan	Duration	Tasks	Files
(v1.2 plans not yet started)

Accumulated Context

Key Decisions

Decisions from v1.0 and v1.1 are archived in PROJECT.md Key Decisions table. Key patterns to carry forward:

• Mutex-protected setter pattern (lock → write → release → callbacks)
• SAFETY comment convention for hand-crafted SQL
• AST-based codegen for cross-language constant sync
• Design tokens via :host scoped CSS custom properties
• queueMicrotask coalescing for store notifications
• .renderItem + .keyFunction (not repeat() children) for lit-virtualizer
• Upsert-and-relink for shared entities (never mutate shared artist/album/genre rows)
• ScanHooks/RemovalHooks/RescanHooks callback patterns for cross-package coordination

v1.2 Roadmap Decisions

Decision	Rationale
5 phases (15-19) for 20 requirements	Natural clustering: foundation → writers → single edit → batch edit → stretch OGG
WRITE-05 in Phase 15 (not 16)	Atomic write utility is foundational infrastructure, not format-specific
Cover art embed (WRITE-04) in Phase 16	Cover art embedding is format-specific writer work, shares test infrastructure with tag writing
Cover art UI (EDIT-03) in Phase 17	Cover art selection UX is part of the single-track edit dialog
OGG as separate Phase 19 (stretch)	Custom OGG page rewriter is MEDIUM-HIGH risk; MP3+FLAC covers vast majority of libraries
SYNC-04 (scan pause during edits) in Phase 16	Scan/edit mutual exclusion is part of the write pipeline, not the UI layer
Phase 18 depends on Phase 17	Batch editing is N × single with UI complexity on top; pipeline must be solid first
Phase 19 depends on Phase 16 (not 17)	OGG writing is a backend writer addition; UI integration is format-transparent

Warnings (carry forward)

• Player lock ordering (p.mu before speaker.Lock(), goroutine dispatch in beep callback)
• modernc.org/libc version must match exactly when updating modernc.org/sqlite
• @lit-labs/signals is experimental (v0.2.0) — not blocking but noted
• FTS5 contentless can't DELETE rows — SCHEMA-01 fixes this with contentless_delete migration
• Orphan cleanup must not delete shared entities across libraries (reference-counting bottom-up)
• 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

Research Flags

• Phase 16: go-flac libraries (44 stars) — verify round-trip with edge-case FLAC files early
• Phase 19: Custom OGG page rewriter — prototype before committing; consider dropping if too complex
• Phase 16: Album artist storage — not currently a separate entity; resolve during planning

Deferred Improvements

• Bulk phantom matching performance — O(n×3) round trips per phantom. Revisit if large external playlist imports occur.

Session Continuity

Last Session

Date: 2026-03-16 What happened: Created v1.2 Tag Editing roadmap — 5 phases (15-19) covering all 20 requirements. Derived phases from requirement clustering: schema foundation → tag writers + DB sync → single-track UI → batch UI → OGG stretch. Where we stopped: Roadmap created, ready for phase planning Next action: /gsd-plan-phase 15 — Schema Migration & Write Safety

---

State initialized: 2026-02-27

Quick Tasks Completed

#	Description	Date	Commit	Directory
16	add ctrl+a hotkey to multi-select views to select all items	2026-03-07	043c74c	16-add-ctrl-a-hotkey-to-multi-select-views-
17	refactor playlist view to use subpages	2026-03-08	955cd68	17-refactor-playlist-view-to-use-subpages-l
18	add multi-column metadata display to playlist-details	2026-03-08	ce23177	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

Last activity: 2026-03-16 - Completed quick task 19: fix phantom playlist tracks with multi-root path resolution Last updated: 2026-03-16 — v1.2 roadmap created