ss-tools/specs/025-clean-release-compliance/quickstart.md

# Quickstart: Clean Release Compliance Subsystem Redesign

## Purpose

Use this package to implement and validate the redesigned clean release subsystem defined in:
- Spec: [`spec.md`](specs/025-clean-release-compliance/spec.md)
- Plan: [`plan.md`](specs/025-clean-release-compliance/plan.md)
- UX reference: [`ux_reference.md`](specs/025-clean-release-compliance/ux_reference.md)
- Data model: [`data-model.md`](specs/025-clean-release-compliance/data-model.md)
- Contracts: [`contracts/modules.md`](specs/025-clean-release-compliance/contracts/modules.md), [`contracts/clean-release-api.openapi.yaml`](specs/025-clean-release-compliance/contracts/clean-release-api.openapi.yaml), [`contracts/cli.md`](specs/025-clean-release-compliance/contracts/cli.md)

## 1) Backend implementation flow

1. Introduce canonical lifecycle/domain entities and state machine guards.
2. Split current clean release logic into dedicated application services and repository interfaces.
3. Resolve policy and registry from trusted stores into immutable snapshots.
4. Move compliance execution to `TaskManager` and persist stage events, violations and reports.
5. Expose candidate/manifest/compliance/release operations through one facade.
6. Rebuild API and CLI on top of the facade.
7. Refactor TUI into a read/trigger-only client.

## 2) Headless operator flow target

### Candidate registration and artifact import

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

clean-release candidate import-artifacts \
  --candidate-id 2026.03.09-rc1 \
  --input artifacts.json \
  --actor release-bot
```

### Manifest and compliance

```bash
clean-release manifest build --candidate-id 2026.03.09-rc1 --actor release-bot
clean-release compliance run --candidate-id 2026.03.09-rc1 --manifest-id man-001 --actor release-bot --json
clean-release compliance status --run-id run-001 --json
clean-release compliance report --run-id run-001 --json
```

### Approval and publication

```bash
clean-release release approve --candidate-id 2026.03.09-rc1 --report-id rpt-001 --actor release-owner
clean-release release publish --candidate-id 2026.03.09-rc1 --report-id rpt-001 --channel prod --actor release-owner
```

## 3) REST API smoke checklist

- `POST /api/clean-release/candidates` creates candidate and returns overview DTO.
- `POST /api/clean-release/candidates/{candidate_id}/artifacts/import` persists artifacts without triggering compliance.
- `POST /api/clean-release/candidates/{candidate_id}/manifest` creates a new immutable manifest version.
- `POST /api/clean-release/candidates/{candidate_id}/compliance-runs` returns `202` with `run_id` and `task_id`.
- `GET /api/clean-release/compliance-runs/{run_id}` returns live execution status.
- `GET /api/clean-release/compliance-runs/{run_id}/stages` returns ordered stage results.
- `GET /api/clean-release/compliance-runs/{run_id}/violations` returns append-only violations.
- `GET /api/clean-release/compliance-runs/{run_id}/report` returns immutable final report for completed runs.
- `POST /api/clean-release/candidates/{candidate_id}/approve` enforces passed-report gate.
- `POST /api/clean-release/candidates/{candidate_id}/publish` enforces approval gate.

## 4) UX conformance checks (must pass)

- TUI shows latest candidate, latest manifest, latest run and latest report without mutating them.
- `F6` builds manifest explicitly; `F5` never auto-builds hidden manifest.
- `F8` is disabled or blocked with explicit reason unless candidate is in `CHECK_PASSED`.
- `F9` is disabled or blocked with explicit reason unless candidate is `APPROVED`.
- Running state is sourced from real run/task progress, not simulated local state.
- Non-TTY startup redirects the operator to CLI/API path instead of headless TUI mode.
- Demo mode actions never expose or modify real-mode history.

## 5) Contract checks (must pass)

- Domain transitions conform to the lifecycle in [`data-model.md`](specs/025-clean-release-compliance/data-model.md).
- API payloads conform to [`clean-release-api.openapi.yaml`](specs/025-clean-release-compliance/contracts/clean-release-api.openapi.yaml).
- CLI commands and exit codes conform to [`cli.md`](specs/025-clean-release-compliance/contracts/cli.md).
- Immutable entities are never updated in place.
- Real-mode runs, reports, violations and audit events remain append-only.

## 6) Suggested validation commands

Backend targeted tests:
```bash
cd backend && .venv/bin/python3 -m pytest tests/services/clean_release tests/api/routes -k clean_release -q
```

CLI smoke tests:
```bash
cd backend && .venv/bin/python3 -m pytest tests/scripts/test_clean_release_cli.py -q
```

TUI thin-client smoke tests:
```bash
cd backend && .venv/bin/python3 -m pytest tests/scripts/test_clean_release_tui_v2.py -q
```

## 7) Migration checkpoints

1. Old TUI logic no longer directly prepares candidates, builds manifests or finalizes runs.
2. Legacy `/api/clean-release/checks*` entrypoints have explicit compatibility or deprecation behavior.
3. Trusted policy resolution no longer depends on UI/env bootstrap payloads.
4. Compliance run state is visible through both TaskManager and clean-release run records.
5. Demo namespace and real namespace are visibly isolated.

## 8) Validation Results (T049)

### Executed regression subset

Command:
```bash
cd backend && DATABASE_URL=sqlite:///./test_quickstart.db AUTH_DATABASE_URL=sqlite:///./test_quickstart_auth.db TASKS_DATABASE_URL=sqlite:///./test_quickstart_tasks.db PYTHONPATH=/home/busya/dev/ss-tools .venv/bin/python3 -m pytest tests/scripts/test_clean_release_cli.py tests/scripts/test_clean_release_tui_v2.py src/api/routes/__tests__/test_clean_release_v2_api.py src/api/routes/__tests__/test_clean_release_v2_release_api.py src/api/routes/__tests__/test_clean_release_legacy_compat.py -q
```

Result:
- `15 passed`
- exit code `0`
- run completed with non-blocking warnings only (deprecations/config warnings), no functional failures.

### Coverage of quickstart objectives

- Headless lifecycle path validated through CLI smoke tests.
- Thin-client TUI path validated through dedicated TUI v2 smoke tests.
- V2 API and legacy compatibility API paths validated through route tests.
- Legacy `/api/clean-release/checks*` and `/api/clean-release/candidates/prepare` compatibility confirmed.

## 9) Done criteria for planning handoff

- All planning artifacts exist and are internally consistent.
- State machine, trust boundaries and immutable evidence model are defined.
- CLI and REST contracts are stable enough for parallel implementation.
- TUI UX reference is explicitly thin-client only.
- Ready to decompose into executable work items via [`tasks.md`](specs/025-clean-release-compliance/tasks.md).