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
• Plan: plan.md
• UX reference: ux_reference.md
• Data model: data-model.md
• Contracts: contracts/modules.md, contracts/clean-release-api.openapi.yaml, 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

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

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

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.
• API payloads conform to clean-release-api.openapi.yaml.
• CLI commands and exit codes conform to 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:

cd backend && .venv/bin/python3 -m pytest tests/services/clean_release tests/api/routes -k clean_release -q

CLI smoke tests:

cd backend && .venv/bin/python3 -m pytest tests/scripts/test_clean_release_cli.py -q

TUI thin-client smoke tests:

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