# UX Reference: Clean Release Compliance Subsystem Redesign

**Feature Branch**: `025-clean-release-compliance`  
**Created**: 2026-03-09  
**Status**: Draft

## 1. User Persona & Context

- **Who is the user?**: Release manager, compliance operator, enterprise support engineer.
- **What is their goal?**: Safely move a release candidate through candidate preparation, compliance, approval and publication without hidden state.
- **Context**: Usually works in terminal-first infrastructure, often in restricted or headless environments, sometimes with a TTY, sometimes from CI.

## 2. The Happy Path Narrative

Оператор регистрирует кандидата и импортирует артефакты через CLI или API. Затем он открывает TUI и сразу видит candidate overview: latest manifest, active policy snapshot, latest run, violations и publication state. Нажатие `F6` строит manifest, `F5` запускает compliance, а экран показывает реальный прогресс stage-by-stage из task/run logs, а не локальную имитацию. После `PASSED` оператор выполняет `F8` approve и `F9` publish, и каждое действие мгновенно отражается в overview без скрытых сайд-эффектов.

## 3. Interface Mockups

### CLI Interaction

```bash
$ clean-release candidate register \
    --candidate-id 2026.03.09-rc1 \
    --version 1.2.0 \
    --source-snapshot v1.2.0-rc1

Candidate created: 2026.03.09-rc1
Status: DRAFT

$ clean-release manifest build --candidate-id 2026.03.09-rc1
Manifest created: man-001
Manifest digest: sha256:9fa...
Status: MANIFEST_BUILT

$ clean-release compliance run --candidate-id 2026.03.09-rc1 --json
{
  "run_id": "run-001",
  "candidate_id": "2026.03.09-rc1",
  "status": "PENDING",
  "task_id": "task-123"
}
```

### TUI Layout & Flow

**Screen/Component**: Clean Release Overview

- **Layout**: Three-pane terminal layout.
  - Top header: current candidate, lifecycle state, active mode (`real` or `demo`).
  - Left pane: candidate summary, latest manifest, approval/publication state.
  - Right pane: latest compliance run, stage timeline, violations list.
  - Bottom action bar: `F5 Run`, `F6 Manifest`, `F7 Refresh`, `F8 Approve`, `F9 Publish`, `F10 Exit`.
- **Key Elements**:
  - **Candidate Summary**: shows candidate id, version, source snapshot, current state.
  - **Latest Manifest Card**: manifest id, version, digest, created time.
  - **Policy Snapshot Card**: policy id/version and registry version used for latest run.
  - **Violations Table**: severity, code, artifact path, short message.
- **States**:
  - **Default**: Existing overview visible, no hidden mutation.
  - **Running**: Current run and current stage are highlighted; logs update live from task events.
  - **Passed**: Action bar enables `Approve` when transition is legal.
  - **Blocked/Error**: Violations or failure reason become the dominant focus; approval/publish actions stay disabled.

## 4. The Error Experience

**Philosophy**: Surface the real state and tell the operator what transition is blocked. Never hide missing prerequisites by auto-fixing them in the UI.

### Scenario A: Missing Manifest

- **User Action**: Presses `F5` to run compliance before a manifest exists.
- **System Response**:
  - TUI: inline error banner `Manifest required before compliance run` and highlight on `F6 Build manifest`.
  - CLI: `Error: candidate 2026.03.09-rc1 has no manifest. Build a manifest first.`
- **Recovery**: Operator runs build manifest, returns to overview, retries compliance.

### Scenario B: Blocked By Policy

- **System Response**: Run ends in `BLOCKED`, latest report card turns warning state, violations table is focused automatically.
- **Recovery**: Operator can inspect violations, export/report details, fix candidate inputs, build a new manifest and request a new run.

### Scenario C: Policy Store Unavailable

- **System Response**: Request is rejected as input/system error before stage execution; UI explicitly says policy snapshot could not be resolved.
- **Recovery**: Retry when trusted policy source is restored. No fake run is shown.

### Scenario D: Headless Environment

- **System Response**: TUI refuses to start without TTY and instructs operator to use CLI/API flow.
- **Recovery**: Run equivalent `clean-release ...` command or call API.

## 5. Tone & Voice

- **Style**: Concise, operational, deterministic.
- **Terminology**: Use `candidate`, `manifest`, `policy snapshot`, `compliance run`, `report`, `approval`, `publication` consistently.
- **Avoided Terms**: Avoid vague legacy words like `checker`, `fake run`, `history cleanup`, `headless ready` inside the operator UX.