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

- [x] Render semantic edits into `supervised/` artifacts.
- [x] Add force-onset endpoint and waveform add-onset mode.
- [x] Add suppressed-hit restore endpoint and button.
- [x] Add exact suggestion diff previews.
- [x] 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

- [x] Auto-start processing after drop/upload.
- [x] Group sample cards by type.
- [x] Add draw-another-candidate interaction.
- [x] Add dismiss-card interaction.
- [x] Add simple trim/extend/save timing interaction.
- [x] 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:

- [x] Add Spleeter backend option.
- [x] Default new jobs to Spleeter `spleeter:4stems` + `drums`.
- [x] Keep Demucs as explicit quality/fallback backend.
- [x] Add `none` backend for full-mix preview.
- [x] Add optional `requirements-spleeter.txt`.
- [x] Add per-card checkbox selection.
- [x] Add selected-only backend export.
- [x] Persist draw-next representative overrides.
- [x] Rewrite preview audio immediately for trim/extend edits.
- [x] 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.