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

$ 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.

4.7 KiB Raw Permalink Blame History Unescape Escape