docs/interactive-ux/TASKS.md

Interactive UX tasks

Status legend

Status	Meaning
todo	Not started
doing	In progress
partial	Implemented as a useful first version but not complete
done	Completed for the current architecture
blocked	Waiting on prerequisite decision/work

Phase 0: Documentation and design capture

ID	Task	Status	Acceptance criteria
UX-000	Capture feature requirements	done	Requirements documented in FEATURE_REQUIREMENTS.md
UX-001	Capture scope boundaries	done	MVP/V2/backlog documented in SCOPE.md
UX-002	Capture feasibility matrix	done	Scores documented in FEASIBILITY_MATRIX.md
UX-003	Capture implementation tasks	done	Task backlog documented here
UX-004	Capture progress	done	Progress documented in PROGRESS.md
UX-005	Align supplied docs with implemented project	done	All documents updated to reflect current code/API/UI behavior

Phase 1: State model and persistence

ID	Task	Status	Acceptance criteria
UX-101	Define persisted job state schema	done	supervised_state.py creates supervision_state.json with hits, clusters, constraints, events, suggestions, and undo state
UX-102	Add event log	done	User/system changes append events and the event log is stored with job output
UX-103	Add constraint store	done	must-link, cannot-link, force-cluster, lock-cluster, suppress-pattern, and pin-representative are saved
UX-104	Add artifact/cache references	partial	State stores hit audio file refs and manifest fingerprint; feature refs and content-addressed feature cache are not implemented yet
UX-105	Add deterministic replay command	todo	A job can be regenerated from source digest, params, and constraints
UX-106	Add semantic undo stack	done	POST /api/jobs/{job_id}/undo restores the previous semantic state snapshot

Phase 2: Confidence and review queue

ID	Task	Status	Acceptance criteria
UX-201	Compute hit assignment confidence	partial	Each hit has confidence from cluster confidence, label agreement, energy rank, representative/explicit/suppressed state; feature-vector margin is not implemented
UX-202	Compute cluster confidence	partial	Each cluster has confidence from purity, size, representative, lock state; true feature cohesion/stability is not implemented
UX-203	Add uncertainty ranking	done	Backend returns review_queue sorted by priority
UX-204	Add low-confidence UI emphasis	done	Hit rows and review queue emphasize low-confidence and suppressed items
UX-205	Add review quick actions	partial	Accept, favorite, move, pull-out, suppress are available; split/restore/batch actions are still incomplete

Phase 3: Constraint-aware editing

ID	Task	Status	Acceptance criteria
UX-301	Move hit to cluster endpoint	done	Moving a hit creates force-cluster and usually must-link constraints
UX-302	Pull hit into new cluster endpoint	done	Pulling a hit creates a new user cluster plus cannot-link/force-cluster constraints
UX-303	Lock cluster endpoint	done	Locked cluster state persists and is shown in the UI
UX-304	Local neighborhood recomputation	partial	Semantic state and confidence are recomputed; true cached feature-neighborhood reclustering is not implemented
UX-305	Constraint violation detection	todo	Backend reports attempted changes that violate user constraints
UX-306	Undo last interaction	done	User can reverse the previous semantic edit
UX-307	Suggest similar moves from a hit move	partial	Heuristic suggestions are generated using label, centroid, and energy similarity

Phase 4: Missed onset and bleed interactions

ID	Task	Status	Acceptance criteria
UX-401	Add force-onset endpoint	todo	User can add onset by time; hit is sliced/classified/clustered
UX-402	Add waveform click interaction	partial	Existing waveform clicks audition nearest hit; add-onset mode is not implemented
UX-403	Add bleed suppression endpoint	done	User can mark hit as bleed/noise and create a suppress-pattern example
UX-404	Implement similar-false-positive search	partial	Heuristic suppress suggestions are generated from energy/centroid/label similarity
UX-405	Add suppression restore	todo	Suppressed hits can be restored individually or in batches

Phase 5: Suggestions and explanations

ID	Task	Status	Acceptance criteria
UX-501	Add suggestion model	done	Suggestions have type, confidence, reason, preview count, status, accept/reject state
UX-502	Generate move suggestions from cluster edits	partial	Basic suggestions generated after move edits
UX-503	Generate split suggestions from cannot-link edits	partial	Basic split suggestions generated after pull-out edits
UX-504	Generate suppression suggestions	partial	Basic suppression suggestions generated after suppress edits
UX-505	Add suggestion inbox UI	done	Suggestions are visible and can be accepted/rejected
UX-506	Add explain-cluster endpoint	done	Backend returns representative, confidence reasons, outliers, constraints, label distribution
UX-507	Add explanation drawer UI	done	UI renders explanation JSON for the selected cluster
UX-508	Add diff previews before suggestion acceptance	todo	Suggestions show exact before/after cluster membership changes before acceptance

Phase 6: Counterfactuals and advanced quality features

ID	Task	Status	Acceptance criteria
UX-601	Add parameter diff estimator	todo	UI can preview approximate effect of parameter changes
UX-602	Add cached local parameter recompute	todo	Parameter changes reuse hit features where possible
UX-603	Add reconstruction error map	todo	Backend computes original-vs-reconstruction mismatch by region
UX-604	Add reconstruction correction workflow	todo	User can select bad region and get likely causes/fixes
UX-605	Add multi-resolution cluster hierarchy	todo	Clusters can be browsed coarse-to-fine

Phase 7: Preference memory / teach mode

ID	Task	Status	Acceptance criteria
UX-701	Persist user correction profiles	todo	Reusable preference profile stores accepted correction patterns
UX-702	Apply profile to new jobs	todo	New jobs can opt into prior preferences
UX-703	Add profile safety controls	todo	User can inspect, disable, delete, and scope learned preferences
UX-704	Evaluate profile impact	todo	Benchmarks compare profile-on vs profile-off results

Current recommended next task

Start with UX-401 plus supervised export.

Reason:

The project now has a replayable state/events/constraints foundation plus supervised edited artifact export. The largest UX gaps are cluster merge/relabel/split, cached feature-neighborhood reclustering, and edited-vs-original comparison.

Pass 5 completed

• Render semantic edits into supervised/ artifacts.
• Add force-onset endpoint and waveform add-onset mode.
• Add suppressed-hit restore endpoint and button.
• Add exact suggestion diff previews.
• Add validation script for supervised export and force-onset.

Next interactive tasks

• Cluster merge/relabel/split controls.
• Cached feature-vector local reclustering.
• Edited-vs-original comparison view.
• Browser tests for waveform add-onset and edited export.

Automatic card-flow follow-up tasks

• Auto-start processing after drop/upload.
• Group sample cards by type.
• Add draw-another-candidate interaction.
• Add dismiss-card interaction.
• Add simple trim/extend/save timing interaction.
• Add waveform zoom/pan.
• Persist drawn candidate cards as representative overrides.
• Recluster locally after card-level decisions.
• Add browser-level tests for the card flow.

Selected cards and separation backends

Completed:

• Add Spleeter backend option.
• Default new jobs to Spleeter spleeter:4stems + drums.
• Keep Demucs as explicit quality/fallback backend.
• Add none backend for full-mix preview.
• Add optional requirements-spleeter.txt.
• Add per-card checkbox selection.
• Add selected-only backend export.
• Persist draw-next representative overrides.
• Rewrite preview audio immediately for trim/extend edits.
• Add regression smoke test for selected export/card actions.

Next:

• Add card-column relabel/merge/split actions.
• Add browser-level tests for card selection/export/edit flows.
• Add localized high-quality separation refinement on short candidate windows.