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.1	Format Parity	defining_requirements	2026-03-18T19:00:00.000Z	total_phases completed_phases total_plans completed_plans 0 0 0 0

YellowJacket — Project State

Project Reference

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 Position

Phase: Not started (defining requirements) Plan: — Status: Defining requirements Last activity: 2026-03-18 — Milestone v1.2.1 started

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 baseline: 4 phases, 9 plans, 17 tasks in 3 days (~40 commits)

Accumulated Context

Key Decisions

All decisions archived in PROJECT.md Key Decisions table and RETROSPECTIVE.md. 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
• AtomicWrite with .yj-tmp suffix for crash-safe file operations
• suppressEvents flag for batch event coalescing
• Three-state field model via implicit dirty tracking (editValues map presence)

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
• 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
• Phase 19: Custom OGG page rewriter — prototype before committing; consider dropping if too complex

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

---

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-18 - v1.2 Tag Editing milestone shipped Last updated: 2026-03-18 — v1.2 milestone complete and archived