busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
9ddb6a7911f86afb45316034dd9835de8b00a451
ss-tools/specs/025-clean-release-compliance/tasks.md

16 KiB
Raw Blame History

Tasks: Clean Release Compliance Subsystem Redesign

Input: Design documents from /specs/025-clean-release-compliance/
Prerequisites: plan.md, spec.md, ux_reference.md, research.md, data-model.md, 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.

  • T001 Create clean release redesign module skeletons in backend/src/services/clean_release/ and backend/src/services/clean_release/repositories/
  • T002 [P] Add redesign fixture set in backend/tests/fixtures/clean_release/fixtures_release_v2.json
  • 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
  • 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.

  • 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
  • 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)
  • 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
  • T008 [P] Implement facade and DTO mapping in backend/src/services/clean_release/facade.py and backend/src/services/clean_release/mappers.py
  • T009 Wire clean release dependencies for repositories, trusted policy access and task manager in backend/src/dependencies.py
  • 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
  • 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

  • T011 [P] [US1] Add lifecycle and manifest versioning tests in backend/tests/services/clean_release/test_candidate_manifest_services.py
  • T012 [P] [US1] Add API contract tests for candidate/artifact/manifest endpoints in backend/src/api/routes/__tests__/test_clean_release_v2_api.py
  • 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

  • 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)
  • 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)
  • 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)
  • T017 [US1] Implement candidate and manifest CLI commands in backend/src/scripts/clean_release_cli.py
  • T018 [US1] Implement candidate/artifact/manifest REST endpoints and expanded overview DTO mapping in backend/src/api/routes/clean_release.py
  • T019 [US1] Verify implementation matches 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

  • T020 [P] [US2] Add stage pipeline and run finalization tests in backend/tests/services/clean_release/test_compliance_execution_service.py
  • T021 [P] [US2] Add TaskManager integration tests for clean release runs in backend/tests/services/clean_release/test_compliance_task_integration.py
  • 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

  • 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
  • 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)
  • 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
  • T026 [US2] Implement compliance REST endpoints for run creation, run status, stages, violations and report in backend/src/api/routes/clean_release.py
  • 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
  • T028 [US2] Implement append-only audit hooks for run lifecycle and violations in backend/src/services/clean_release/audit_service.py
  • T029 [US2] Verify implementation matches 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

  • T030 [P] [US3] Add approval gate tests in backend/tests/services/clean_release/test_approval_service.py
  • T031 [P] [US3] Add publication gate tests in backend/tests/services/clean_release/test_publication_service.py
  • 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

  • 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)
  • 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)
  • T035 [US3] Implement release CLI commands (approve, reject, publish, revoke) in backend/src/scripts/clean_release_cli.py
  • T036 [US3] Implement release REST endpoints in backend/src/api/routes/clean_release.py
  • 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
  • T038 [US3] Verify implementation matches 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

  • 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
  • T040 [P] [US4] Add demo namespace isolation tests in backend/tests/services/clean_release/test_demo_mode_isolation.py
  • T041 [P] [US4] Add non-TTY startup behavior tests in backend/tests/scripts/test_clean_release_tui_v2.py

Implementation for User Story 4

  • 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)
  • 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/
  • T044 [US4] Remove real-mode clear_history and pseudo-headless fallback behavior in backend/src/scripts/clean_release_tui.py
  • 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
  • T046 [US4] Verify implementation matches 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.

  • 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
  • T048 [P] Update operational documentation for new CLI/API/TUI workflow in README.md and docs/installation.md
  • T049 Run end-to-end quickstart validation and capture results in specs/025-clean-release-compliance/quickstart.md
  • 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
  • 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
  • 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

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

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.
Each user story contains a mandatory UX verification task: T019, T029, T038, T046.