# Tasks: Clean Release Compliance Subsystem Redesign

**Input**: Design documents from [`/specs/025-clean-release-compliance/`](specs/025-clean-release-compliance)  
**Prerequisites**: [`plan.md`](specs/025-clean-release-compliance/plan.md), [`spec.md`](specs/025-clean-release-compliance/spec.md), [`ux_reference.md`](specs/025-clean-release-compliance/ux_reference.md), [`research.md`](specs/025-clean-release-compliance/research.md), [`data-model.md`](specs/025-clean-release-compliance/data-model.md), [`contracts/`](specs/025-clean-release-compliance/contracts)

**Tests**: Include service, API, CLI and TUI smoke tests because this is a lifecycle-critical subsystem redesign.

**Organization**: Tasks are grouped by user story to enable independent implementation and testing.

## Format: `[ID] [P?] [Story] Description`

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Prepare new clean-release redesign scaffolding, fixtures and test entrypoints.

- [x] T001 Create clean release redesign module skeletons in `backend/src/services/clean_release/` and `backend/src/services/clean_release/repositories/`
- [x] T002 [P] Add redesign fixture set in `backend/tests/fixtures/clean_release/fixtures_release_v2.json`
- [x] T003 [P] Add API contract test scaffolding in `backend/src/api/routes/__tests__/test_clean_release_v2_api.py` and `backend/src/api/routes/__tests__/test_clean_release_v2_release_api.py`
- [x] T004 [P] Add CLI and TUI smoke test scaffolding in `backend/tests/scripts/test_clean_release_cli.py` and `backend/tests/scripts/test_clean_release_tui_v2.py`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Build canonical lifecycle, persistence boundaries and shared facade before any user story.

- [x] T005 Implement clean release enums, exceptions and DTOs in `backend/src/services/clean_release/enums.py`, `backend/src/services/clean_release/exceptions.py` and `backend/src/services/clean_release/dto.py`
- [x] T006 Implement canonical clean release domain entities and lifecycle guards in `backend/src/models/clean_release.py` (CRITICAL: PRE valid aggregate identifiers and state commands; POST immutable evidence and valid transitions only; TESTS: invalid transition, manifest immutability, publish gate)
- [x] T007 [P] Implement repository interfaces and durable adapters in `backend/src/services/clean_release/repositories/candidate_repository.py`, `backend/src/services/clean_release/repositories/artifact_repository.py`, `backend/src/services/clean_release/repositories/manifest_repository.py`, `backend/src/services/clean_release/repositories/policy_repository.py`, `backend/src/services/clean_release/repositories/compliance_repository.py`, `backend/src/services/clean_release/repositories/report_repository.py`, `backend/src/services/clean_release/repositories/approval_repository.py`, `backend/src/services/clean_release/repositories/publication_repository.py` and `backend/src/services/clean_release/repositories/audit_repository.py`
- [x] T008 [P] Implement facade and DTO mapping in `backend/src/services/clean_release/facade.py` and `backend/src/services/clean_release/mappers.py`
- [x] T009 Wire clean release dependencies for repositories, trusted policy access and task manager in `backend/src/dependencies.py`
- [x] T009a Implement `ConfigManager`-backed resolution for trusted policy store, profile selection, mode and storage wiring in `backend/src/dependencies.py` and `backend/src/services/clean_release/policy_resolution_service.py`
- [x] T010 Add legacy compatibility shim and migration helpers in `backend/src/services/clean_release/__init__.py` and `backend/src/services/clean_release/repository.py`

**Checkpoint**: Foundational layer complete; user stories can proceed.

---

## Phase 3: User Story 1 - Headless release candidate lifecycle (Priority: P1) 🎯 MVP

**Goal**: Make candidate registration, artifact import, manifest build and lifecycle visibility available through CLI/API without TUI.

**Independent Test**: Register candidate, import artifacts, build manifest and query overview using only CLI/API.

### Tests for User Story 1

- [x] T011 [P] [US1] Add lifecycle and manifest versioning tests in `backend/tests/services/clean_release/test_candidate_manifest_services.py`
- [x] T012 [P] [US1] Add API contract tests for candidate/artifact/manifest endpoints in `backend/src/api/routes/__tests__/test_clean_release_v2_api.py`
- [x] T013 [P] [US1] Add CLI smoke tests for candidate register/import/manifest build in `backend/tests/scripts/test_clean_release_cli.py`

### Implementation for User Story 1

- [x] T014 [US1] Implement candidate preparation service in `backend/src/services/clean_release/candidate_service.py` (CRITICAL: PRE unique candidate id and valid artifacts; POST candidate/artifacts persisted and status advances only through legal states; TESTS: duplicate id, malformed artifact input, empty artifact set)
- [x] T015 [US1] Implement manifest service in `backend/src/services/clean_release/manifest_service.py` (CRITICAL: PRE candidate prepared and artifacts available; POST immutable manifest snapshot with deterministic digest and version increment; TESTS: rebuild creates new version, existing manifest cannot be mutated, missing candidate rejected)
- [x] T016 [US1] Implement policy resolution service with trusted snapshot reads in `backend/src/services/clean_release/policy_resolution_service.py` (CRITICAL: PRE trusted profile exists; POST immutable policy and registry snapshots without UI/env overrides; TESTS: missing profile, missing registry, override attempt)
- [x] T017 [US1] Implement candidate and manifest CLI commands in `backend/src/scripts/clean_release_cli.py`
- [x] T018 [US1] Implement candidate/artifact/manifest REST endpoints and expanded overview DTO mapping in `backend/src/api/routes/clean_release.py`
- [x] T019 [US1] Verify implementation matches [`ux_reference.md`](specs/025-clean-release-compliance/ux_reference.md) (Happy Path & Errors)

**Checkpoint**: US1 independently functional and usable from headless automation.

---

## Phase 4: User Story 2 - Trusted and immutable compliance evidence (Priority: P1)

**Goal**: Execute compliance as an observable, append-only TaskManager-backed pipeline with immutable reports and trusted snapshots.

**Independent Test**: Start a run through API/CLI, observe task/run progress, inspect stage records and violations, then verify immutable final report persistence.

### Tests for User Story 2

- [x] T020 [P] [US2] Add stage pipeline and run finalization tests in `backend/tests/services/clean_release/test_compliance_execution_service.py`
- [x] T021 [P] [US2] Add TaskManager integration tests for clean release runs in `backend/tests/services/clean_release/test_compliance_task_integration.py`
- [x] T022 [P] [US2] Add report and audit immutability tests in `backend/tests/services/clean_release/test_report_audit_immutability.py`

### Implementation for User Story 2

- [x] T023 [US2] Implement pluggable stage base and default stage modules in `backend/src/services/clean_release/stages/base.py`, `backend/src/services/clean_release/stages/data_purity.py`, `backend/src/services/clean_release/stages/internal_sources_only.py`, `backend/src/services/clean_release/stages/no_external_endpoints.py` and `backend/src/services/clean_release/stages/manifest_consistency.py`
- [x] T024 [US2] Implement compliance execution service in `backend/src/services/clean_release/compliance_execution_service.py` (CRITICAL: PRE candidate exists and explicit or latest manifest plus trusted snapshots are resolvable; POST run, stage records, violations and report remain mutually consistent; TESTS: run without manifest, task crash mid-run, blocked report finalization)
- [x] T025 [US2] Bind compliance runs to TaskManager and reports service in `backend/src/services/clean_release/compliance_execution_service.py`, `backend/src/services/reports/report_service.py` and `backend/src/dependencies.py`
- [x] T026 [US2] Implement compliance REST endpoints for run creation, run status, stages, violations and report in `backend/src/api/routes/clean_release.py`
- [x] T027 [US2] Implement compliance CLI commands (`run`, `status`, `report`, `violations`) in `backend/src/scripts/clean_release_cli.py` with latest-manifest fallback when `--manifest-id` is omitted
- [x] T028 [US2] Implement append-only audit hooks for run lifecycle and violations in `backend/src/services/clean_release/audit_service.py`
- [x] T029 [US2] Verify implementation matches [`ux_reference.md`](specs/025-clean-release-compliance/ux_reference.md) (Happy Path & Errors)

**Checkpoint**: US2 independently functional with real run evidence and immutable reporting.

---

## Phase 5: User Story 3 - Controlled approval and publication gate (Priority: P2)

**Goal**: Enforce legal approval/publication transitions over completed compliance results.

**Independent Test**: Attempt invalid approve/publish transitions, then complete the valid `CHECK_PASSED -> APPROVED -> PUBLISHED -> REVOKED` flow.

### Tests for User Story 3

- [x] T030 [P] [US3] Add approval gate tests in `backend/tests/services/clean_release/test_approval_service.py`
- [x] T031 [P] [US3] Add publication gate tests in `backend/tests/services/clean_release/test_publication_service.py`
- [x] T032 [P] [US3] Add API/CLI tests for approve, reject, publish and revoke in `backend/src/api/routes/__tests__/test_clean_release_v2_release_api.py` and `backend/tests/scripts/test_clean_release_cli.py`

### Implementation for User Story 3

- [x] T033 [US3] Implement approval service in `backend/src/services/clean_release/approval_service.py` (CRITICAL: PRE report belongs to candidate and final status is PASSED for approve; POST immutable decision persisted, approve may advance candidate state, reject blocks publication gate without rewriting compliance evidence; TESTS: approve blocked report, approve foreign report, duplicate approve, reject then publish)
- [x] T034 [US3] Implement publication service in `backend/src/services/clean_release/publication_service.py` (CRITICAL: PRE candidate approved; POST immutable publication/revocation record and legal state transition; TESTS: publish without approval, revoke unknown publication, republish after revoke)
- [x] T035 [US3] Implement release CLI commands (`approve`, `reject`, `publish`, `revoke`) in `backend/src/scripts/clean_release_cli.py`
- [x] T036 [US3] Implement release REST endpoints in `backend/src/api/routes/clean_release.py`
- [x] T037 [US3] Extend facade overview/read models for policy snapshot, approval and publication state in `backend/src/services/clean_release/facade.py` and `backend/src/services/clean_release/dto.py`
- [x] T038 [US3] Verify implementation matches [`ux_reference.md`](specs/025-clean-release-compliance/ux_reference.md) (Happy Path & Errors)

**Checkpoint**: US3 independently functional with explicit release gates.

---

## Phase 6: User Story 4 - Thin operational interfaces (Priority: P3)

**Goal**: Convert TUI into a real thin client and isolate demo behavior from real-mode evidence.

**Independent Test**: Operate the same candidate through TUI using facade-backed actions and confirm that TUI behavior matches CLI/API semantics without hidden side effects.

### Tests for User Story 4

- [x] T039 [P] [US4] Add TUI thin-client smoke tests for facade actions and blocked transitions in `backend/tests/scripts/test_clean_release_tui_v2.py`
- [x] T040 [P] [US4] Add demo namespace isolation tests in `backend/tests/services/clean_release/test_demo_mode_isolation.py`
- [x] T041 [P] [US4] Add non-TTY startup behavior tests in `backend/tests/scripts/test_clean_release_tui_v2.py`

### Implementation for User Story 4

- [x] T042 [US4] Refactor TUI to call only facade methods and render DTOs in `backend/src/scripts/clean_release_tui.py` (CRITICAL: PRE valid TTY and candidate context; POST no hidden manifest/policy/run mutations outside facade; TESTS: no TTY, missing manifest on F5, blocked report on F8)
- [x] T043 [US4] Implement isolated demo data service and namespace handling in `backend/src/services/clean_release/demo_data_service.py` and `backend/src/services/clean_release/repositories/`
- [x] T044 [US4] Remove real-mode `clear_history` and pseudo-headless fallback behavior in `backend/src/scripts/clean_release_tui.py`
- [x] T045 [US4] Implement TUI overview panels and action keys `F5/F6/F7/F8/F9/F10` aligned with facade DTOs in `backend/src/scripts/clean_release_tui.py`
- [x] T046 [US4] Verify implementation matches [`ux_reference.md`](specs/025-clean-release-compliance/ux_reference.md) (Happy Path & Errors)

**Checkpoint**: US4 independently functional with thin-client TUI and isolated demo mode.

---

## Phase 7: Polish & Cross-Cutting Concerns

**Purpose**: Finalize migration, compatibility and operational documentation.

- [x] T047 [P] Add compatibility/deprecation tests for legacy `/api/clean-release/checks*` and `/api/clean-release/candidates/prepare` paths in `backend/src/api/routes/__tests__/test_clean_release_legacy_compat.py`
- [x] T048 [P] Update operational documentation for new CLI/API/TUI workflow in `README.md` and `docs/installation.md`
- [x] T049 Run end-to-end quickstart validation and capture results in `specs/025-clean-release-compliance/quickstart.md`
- [x] T050 Migrate or wrap legacy clean release modules in `backend/src/services/clean_release/preparation_service.py`, `backend/src/services/clean_release/manifest_builder.py`, `backend/src/services/clean_release/compliance_orchestrator.py` and `backend/src/services/clean_release/repository.py`
- [x] T051 Align clean release report surfacing with shared reports/task views in `backend/src/services/reports/report_service.py` and `backend/src/api/routes/reports.py`
- [x] T052 Run semantic compliance review for touched clean release modules and close critical `[DEF]`/contract gaps in `backend/src/models/clean_release.py`, `backend/src/services/clean_release/` and `backend/src/scripts/clean_release_tui.py`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Phase 1 (Setup)**: No dependencies.
- **Phase 2 (Foundational)**: Depends on Phase 1 and blocks all stories.
- **Phase 3 (US1)**: Depends on Phase 2.
- **Phase 4 (US2)**: Depends on Phase 2 and reuses outputs from US1 trusted snapshot and facade work.
- **Phase 5 (US3)**: Depends on Phase 2 and a stable report model from US2.
- **Phase 6 (US4)**: Depends on Phases 3-5 because TUI must sit on stable facade/API semantics.
- **Phase 7 (Polish)**: Depends on all selected stories.

### User Story Dependencies

- **US1 (P1)**: First deliverable and MVP.
- **US2 (P1)**: Depends on facade/repository foundations and benefits from US1 candidate/manifest flow.
- **US3 (P2)**: Depends on successful report persistence from US2.
- **US4 (P3)**: Depends on stable facade and release-gate behavior from US1-US3.

Graph: `US1 -> US2 -> US3 -> US4`

### Parallel Opportunities

- Setup tasks T002, T003, T004.
- Foundational tasks T007 and T008 after T005/T006 are stable.
- US1 tests T011, T012, T013.
- US2 tests T020, T021, T022.
- US3 tests T030, T031, T032.
- US4 tests T039, T040, T041.
- Polish tasks T047 and T048.

---

## Parallel Example: User Story 1

```bash
Task: "T011 [US1] Add lifecycle and manifest tests in backend/tests/services/clean_release/test_candidate_manifest_services.py"
Task: "T012 [US1] Add API contract tests in backend/src/api/routes/__tests__/test_clean_release_v2_api.py"
Task: "T013 [US1] Add CLI smoke tests in backend/tests/scripts/test_clean_release_cli.py"
```

## Parallel Example: User Story 2

```bash
Task: "T020 [US2] Add stage pipeline tests in backend/tests/services/clean_release/test_compliance_execution_service.py"
Task: "T021 [US2] Add TaskManager integration tests in backend/tests/services/clean_release/test_compliance_task_integration.py"
Task: "T022 [US2] Add report immutability tests in backend/tests/services/clean_release/test_report_audit_immutability.py"
```

---

## Implementation Strategy

### MVP First (Recommended)

1. Complete Phase 1 and Phase 2.
2. Deliver Phase 3 (US1) so candidate lifecycle works headlessly through CLI/API.
3. Validate independent test for US1.
4. Then add US2 for trusted compliance evidence before moving to release gates and TUI refactor.

### Incremental Delivery

1. US1: headless candidate lifecycle.
2. US2: trusted compliance execution + immutable evidence.
3. US3: approval/publication gate.
4. US4: thin TUI + demo isolation.
5. Phase 7: compatibility, docs and semantic cleanup.

### UX Preservation Rule

No task in this plan is allowed to reintroduce hidden business logic into TUI or to degrade the explicit operator flow in [`ux_reference.md`](specs/025-clean-release-compliance/ux_reference.md).  
Each user story contains a mandatory UX verification task: T019, T029, T038, T046.
