# Interactive UX scope

## Scope model

Features are grouped by implementation risk and product leverage.

- **MVP**: should be built first; high value, technically feasible, foundational.
- **V2**: valuable after the core supervised editing loop exists.
- **Research/backlog**: plausible, but higher risk or dependent on stronger state/model infrastructure.

## MVP scope and status

### 1. Constraint-aware cluster editing

Status: **partial / foundation implemented**.

Implemented:

- Move hit/sample to cluster.
- Pull hit/sample out into a new cluster.
- Create `must-link`, `cannot-link`, and `force-cluster` constraints.
- Preserve explicit edits in `supervision_state.json` across reload.
- Generate basic suggestions after edits.

Remaining:

- True local neighborhood reclustering from cached feature vectors.
- Constraint violation detection.
- Edited artifact re-export.

### 2. Lock confirmed clusters

Status: **implemented**.

Implemented:

- Lock/unlock cluster.
- Persist lock state.
- Show lock state in the cluster board and target cluster control.
- Confidence scoring accounts for locked state.

Remaining:

- Prevent future batch reruns from violating locked cluster identity through deterministic replay.

### 3. Outlier-first review queue

Status: **implemented**.

Implemented:

- Confidence score per hit and cluster.
- Review list sorted by uncertainty priority.
- Quick actions: accept, favorite, move, pull out, suppress.

Remaining:

- Split/restore/batch actions.
- Expected-impact scoring using feature margin and reconstruction contribution.

### 4. Confidence-weighted UI

Status: **implemented**.

Implemented:

- Confidence per hit and cluster.
- Low-confidence row emphasis.
- Suppressed rows recede.
- State summary badges.

### 5. Click-to-add missed onset

Status: **not implemented**.

Current waveform clicks audition existing hits. Add-onset mode is the next direct correction primitive.

### 6. Bleed suppression examples

Status: **partial**.

Implemented:

- Mark selected hit as bleed/noise.
- Store `suppress-pattern`.
- Generate similar suppression suggestions.

Remaining:

- Region brush.
- Restore suppressed hits.
- Exclude suppressed hits from supervised export.

### 7. Explain this cluster

Status: **implemented**.

Implemented:

- Representative ID.
- Members/outliers.
- Confidence reasons.
- Label distribution.
- Relevant constraints.
- Locked/suppressed counts.

## V2 scope

### 1. Predictive batch questions

Status: **partial**.

Basic suggestions exist. Exact diff previews, grouped approval UX, and richer reasoning are not complete.

### 2. Live counterfactual previews

Status: **not implemented**.

### 3. Auto-clean this family

Status: **not implemented**.

### 4. Multi-resolution semantic clustering

Status: **not implemented**.

### 5. Run-to-run preference memory

Status: **not implemented**.

## Research/backlog scope

Unchanged from design intent:

- Reconstruction-error-driven correction.
- Drag clusters in semantic space.
- Cluster gravity / physics metaphor.
- Context-aware classification.
- Teach mode across songs.

## Explicitly out of scope for MVP

- Realtime Demucs.
- Training neural models from scratch.
- Cloud multi-user collaboration.
- DAW plugin integration.
- Full Ableton/Logic export format support.
- Automatic perfect drum transcription claims.

## MVP acceptance criteria status

Target loop:

```text
cached stem is analyzed
→ clusters appear
→ uncertain items are prioritized
→ user moves one wrong hit
→ system stores a constraint
→ affected state recomputes
→ related mistakes are suggested
→ locked clusters remain stable in state
→ semantic decisions reload reproducibly
```

Status: **mostly achieved for semantic state**.

Not achieved yet:

```text
→ edited state can be exported reproducibly as updated WAV/MIDI/ZIP artifacts
→ local feature reclustering updates related hits without manually accepting suggestions
```


## Pass 5 implementation status

Implemented after initial alignment:

- supervised edited-state export under `supervised/`,
- add-onset waveform mode backed by `POST /api/jobs/{job_id}/hits/force-onset`,
- suppressed-hit restore backed by `POST /api/jobs/{job_id}/hits/{hit_id}/restore`,
- exact suggestion diff previews in API state and UI,
- validation via `scripts/test_supervised_export_and_force_onset.py`.

Still open:

- cluster merge/relabel/split workflows,
- cached feature-vector local reclustering,
- edited-vs-original comparison,
- browser-level UI tests.