# Tasks: Clean Repository Enterprise Preparation

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

**Tests**: Тестовые задачи включены выборочно для CRITICAL-контрактов и независимой проверки user stories.

**Organization**: Tasks grouped by user story for independent implementation and validation.

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

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Подготовка каркаса clean-release подсистемы и мест хранения артефактов.

- [X] T001 Create feature package skeleton for clean release modules in `backend/src/services/clean_release/__init__.py`
- [X] T002 [P] Create clean release domain models module in `backend/src/models/clean_release.py`
- [X] T003 [P] Create clean release API route module placeholder in `backend/src/api/routes/clean_release.py`
- [X] T004 [P] Implement full interactive ncurses TUI script in `backend/src/scripts/clean_release_tui.py`
- [X] T005 Register clean release router export in `backend/src/api/routes/__init__.py`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Блокирующие основы, обязательные до user stories.

**⚠️ CRITICAL**: No user story work can begin until this phase is complete.

- [X] T006 Implement core enums and lifecycle models (`ReleaseCandidate`, `CleanProfilePolicy`, `ResourceSourceRegistry`, `DistributionManifest`, `ComplianceCheckRun`, `ComplianceViolation`, `ComplianceReport`) in `backend/src/models/clean_release.py`
- [X] T007 [P] Implement persistence adapter for clean release entities in `backend/src/services/clean_release/repository.py`
- [X] T008 [P] Implement compliance stage constants and run state machine helpers in `backend/src/services/clean_release/stages.py`
- [X] T009 Wire clean release dependencies provider in `backend/src/dependencies.py`
- [X] T010 Add API router include for clean release endpoints in `backend/src/app.py`
- [X] T011 Add baseline fixtures for clean release policy/candidate/report payloads in `backend/tests/fixtures/clean_release/fixtures_clean_release.json`

**Checkpoint**: Foundation ready — user story implementation can now begin.

---

## Phase 3: User Story 1 - Чистый корпоративный релиз без тестовых данных (Priority: P1) 🎯 MVP

**Goal**: Формировать enterprise clean-дистрибутив без test/demo payloads с детерминированным manifest.

**Independent Test**: На одном релиз-кандидате с тестовыми артефактами получить `excluded-prohibited`, на чистом — получить manifest без запрещённых категорий.

### Tests for User Story 1

- [X] T012 [P] [US1] Add unit tests for artifact classification and deterministic decisions in `backend/tests/services/clean_release/test_policy_engine.py`
- [X] T013 [P] [US1] Add integration test for manifest generation consistency in `backend/tests/services/clean_release/test_manifest_builder.py`

### Implementation for User Story 1

- [X] T014 [US1] Implement `CleanPolicyEngine` (CRITICAL: PRE: active policy + valid registry; POST: classification in [required-system|allowed|excluded-prohibited]; TESTS: fixture `policy_enterprise_clean`, edges `conflicting_rules`/`missing_registry`/`empty_prohibited_categories`) in `backend/src/services/clean_release/policy_engine.py`
- [X] T015 [US1] Implement distribution manifest builder and deterministic hash logic in `backend/src/services/clean_release/manifest_builder.py`
- [X] T016 [US1] Implement release candidate preparation service flow in `backend/src/services/clean_release/preparation_service.py`
- [X] T017 [US1] Expose candidate preparation API handler in `backend/src/api/routes/clean_release.py`
- [X] T018 [US1] Verify implementation matches `ux_reference.md` (Happy Path & Errors) in `specs/023-clean-repo-enterprise/ux_reference.md`

**Checkpoint**: US1 independently functional and testable.

---

## Phase 4: User Story 2 - Полностью изолированная поставка без внешнего интернета (Priority: P1)

**Goal**: Гарантировать strict internal-only source policy и блокировать внешние endpoints.

**Independent Test**: При наличии внешнего endpoint выпуск блокируется; при internal-only источниках этап source isolation проходит.

### Tests for User Story 2

- [X] T019 [P] [US2] Add unit tests for internal source registry validation in `backend/tests/services/clean_release/test_source_isolation.py`
- [X] T020 [P] [US2] Add integration test for external endpoint blocking in `backend/tests/api/routes/test_clean_release_source_policy.py`

### Implementation for User Story 2

- [X] T021 [US2] Implement source isolation validator service in `backend/src/services/clean_release/source_isolation.py`
- [X] T022 [US2] Extend `CleanPolicyEngine` with source registry checks for external endpoint detection in `backend/src/services/clean_release/policy_engine.py`
- [X] T023 [US2] Add source registry API contract handling (`internal-only` validation errors) in `backend/src/api/routes/clean_release.py`
- [X] T024 [US2] Update TUI view model to display Allowed Internal Sources panel and External Source blocking messages in `backend/src/scripts/clean_release_tui.py`
- [X] T025 [US2] Verify implementation matches `ux_reference.md` (Happy Path & Errors) in `specs/023-clean-repo-enterprise/ux_reference.md`

**Checkpoint**: US2 independently functional and testable.

---

## Phase 5: User Story 3 - Обязательная проверка соответствия перед выпуском (Priority: P2)

**Goal**: Реализовать обязательный blocking compliance gate с отчётностью для аудита.

**Independent Test**: Запуск проверки возвращает `COMPLIANT` только при pass всех обязательных стадий; иначе `BLOCKED` с violation details.

### Tests for User Story 3

- [X] T026 [P] [US3] Add orchestrator state machine tests for stage pass/fail transitions in `backend/tests/services/clean_release/test_compliance_orchestrator.py`
- [X] T027 [P] [US3] Add report builder validation tests for counters and blocking violations in `backend/tests/services/clean_release/test_report_builder.py`
- [X] T028 [P] [US3] Add API contract tests for `/api/clean-release/checks*` and `/api/clean-release/reports/{id}` in `backend/tests/api/routes/test_clean_release_api.py`

### Implementation for User Story 3

- [X] T029 [US3] Implement `CleanComplianceOrchestrator` (CRITICAL: PRE: candidate exists + active policy; POST: final status COMPLIANT/BLOCKED/FAILED; TESTS: fixture `compliant_candidate`, edges `stage_failure_blocks_release`/`missing_stage_result`/`report_generation_error`) in `backend/src/services/clean_release/compliance_orchestrator.py`
- [X] T030 [US3] Implement `ComplianceReportBuilder` (CRITICAL: PRE: terminal run state; POST: report counters consistent with violations; TESTS: fixture `blocked_with_two_violations`, edges `empty_violations_for_blocked`/`counter_mismatch`/`missing_operator_summary`) in `backend/src/services/clean_release/report_builder.py`
- [X] T031 [US3] Implement clean release API endpoints from `contracts/api.yaml` in `backend/src/api/routes/clean_release.py`
- [X] T032 [US3] Add audit logging hooks for preparation/check/report lifecycle in `backend/src/services/clean_release/audit_service.py`
- [X] T033 [US3] Verify implementation matches `ux_reference.md` (Happy Path & Errors) in `specs/023-clean-repo-enterprise/ux_reference.md`

**Checkpoint**: US3 independently functional and testable.

---

## Phase 6: User Story 4 - Прозрачный операционный регламент (Priority: P3)

**Goal**: Обеспечить воспроизводимый runbook для операторов и onboarding без устных договорённостей.

**Independent Test**: Новый инженер выполняет сценарий только по документации и получает валидный результат проверки.

### Implementation for User Story 4

- [X] T034 [US4] Update operator runbook with enterprise clean lifecycle and recovery actions in `docs/installation.md`
- [X] T035 [US4] Add dedicated enterprise clean deployment section with internal-only source policy in `README.md`
- [X] T036 [US4] Sync quick operational guidance with compliance statuses and report workflow in `specs/023-clean-repo-enterprise/quickstart.md`
- [X] T037 [US4] Add troubleshooting matrix for blocked categories (`data-purity`, `external-source`, `operational-risk`) in `specs/023-clean-repo-enterprise/quickstart.md`
- [X] T038 [US4] Verify implementation matches `ux_reference.md` (Happy Path & Errors) in `specs/023-clean-repo-enterprise/ux_reference.md`

**Checkpoint**: US4 independently functional and testable.

---

## Phase 7: Polish & Cross-Cutting Concerns

**Purpose**: Финализация, smoke-проверки и governance-замыкание.

- [X] T039 [P] Run end-to-end smoke validation of TUI scenario from `quickstart.md` and record results in `specs/023-clean-repo-enterprise/quickstart.md`
- [X] T040 [P] Validate OpenAPI contract consistency against implemented routes in `backend/tests/api/routes/test_clean_release_api.py`
- [X] T041 Add release checklist artifact template for compliance evidence packaging in `specs/023-clean-repo-enterprise/checklists/release-readiness.md`
- [X] T042 Resolve numeric-prefix governance conflict note (`020-*`) and document decision in `specs/023-clean-repo-enterprise/plan.md`
- [X] T043 Update feature status traceability and final notes in `specs/023-clean-repo-enterprise/plan.md`
- [X] T044 Remediate CRITICAL semantic test-contract gaps by adding `@TEST_CONTRACT` metadata in backend/frontend flagged modules and recording coverage update in `specs/023-clean-repo-enterprise/tests/coverage.md`

---

## Dependencies & Execution Order

### Phase Dependencies

- **Phase 1 (Setup)**: Start immediately.
- **Phase 2 (Foundational)**: Depends on Phase 1 — blocks all stories.
- **Phase 3 (US1)**: Depends on Phase 2.
- **Phase 4 (US2)**: Depends on Phase 2; can run in parallel with US1 if staffed.
- **Phase 5 (US3)**: Depends on Phase 2 and outputs from US1/US2.
- **Phase 6 (US4)**: Depends on stable outputs from US1–US3.
- **Phase 7 (Polish)**: Depends on all selected user stories complete.

### User Story Dependencies

- **US1 (P1)**: Independent after foundation.
- **US2 (P1)**: Independent after foundation, integrates with US1 policy artifacts.
- **US3 (P2)**: Uses services from US1/US2 for full compliance gate.
- **US4 (P3)**: Depends on finalized behavior from US1–US3.

### Parallel Opportunities

- Phase 1 tasks marked [P]: T002, T003, T004.
- Phase 2 tasks marked [P]: T007, T008.
- US1 tests T012/T013 parallel.
- US2 tests T019/T020 parallel.
- US3 tests T026/T027/T028 parallel.
- Polish tasks T039/T040 parallel.

---

## Parallel Example: User Story 2

```bash
# Parallel test implementation
Task: "T019 [US2] Add unit tests for internal source registry validation in backend/tests/services/clean_release/test_source_isolation.py"
Task: "T020 [US2] Add integration test for external endpoint blocking in backend/tests/api/routes/test_clean_release_source_policy.py"

# Parallel implementation after tests
Task: "T021 [US2] Implement source isolation validator service in backend/src/services/clean_release/source_isolation.py"
Task: "T024 [US2] Update TUI view model for Allowed Internal Sources and blocking messages in backend/src/scripts/clean_release_tui.py"
```

---

## Implementation Strategy

### MVP First (US1)

1. Complete Phase 1 + Phase 2.
2. Deliver Phase 3 (US1) completely.
3. Validate US1 independently (clean distribution without test/demo data).
4. Demo MVP.

### Incremental Delivery

1. US1 (clean artifacts)  
2. US2 (strict internal-only sources)  
3. US3 (blocking compliance gate + reports)  
4. US4 (operational runbook and onboarding)  
5. Polish and governance closure.

### UX Preservation Check

- Tasks explicitly preserve TUI/ncurses interaction model from [`ux_reference.md`](./ux_reference.md).
- No task introduces web UI replacement for the primary operator flow.
- Each user story phase contains a mandatory UX conformance verification task.