TenantAtlas/specs/214-governance-outcome-compression/tasks.md

Tasks: Governance Operator Outcome Compression

Input: Design documents from /specs/214-governance-outcome-compression/
Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Runtime behavior changes in this repo require Pest coverage. This feature must keep proof in the fast-feedback and confidence lanes, keep shared helper growth opt-in, and validate the shared-detail-family surfaces explicitly.

Phase 1: Setup (Shared Compression Scaffolding)

Purpose: Introduce the bounded shared types needed for surface-aware outcome compression before wiring any operator surface.

• T001 [P] Add failing unit coverage for surface-aware compressed outcomes, centralized badge reuse, and operator-facing summary vocabulary in apps/platform/tests/Unit/Support/Ui/GovernanceArtifactTruth/CompressedGovernanceOutcomeTest.php
• T002 [P] Create the surface-family context helper in apps/platform/app/Support/Ui/GovernanceArtifactTruth/SurfaceCompressionContext.php
• T003 [P] Create the bounded derived outcome value object in apps/platform/app/Support/Ui/GovernanceArtifactTruth/CompressedGovernanceOutcome.php

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Build the shared compression seam, fixture support, and cache-safety guarantees that every user story depends on.

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

• T004 [P] Extend opt-in artifact-state builders in apps/platform/tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php
• T005 [P] Add context-safe compression memoization assertions in apps/platform/tests/Feature/Filament/ReviewRegisterDerivedStateMemoizationTest.php and apps/platform/tests/Feature/Filament/EvidenceOverviewDerivedStateMemoizationTest.php
• T006 Implement shared compressed outcome derivation and central badge selection in apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
• T007 [P] Expose concise translated summary inputs for compression in apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php
• T008 Wire compressed outcome serialization and BadgeCatalog-backed summary fields into apps/platform/app/Support/Ui/GovernanceArtifactTruth/CompressedGovernanceOutcome.php, apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthEnvelope.php, and apps/platform/app/Support/Badges/BadgeCatalog.php

Checkpoint: Shared compression infrastructure is ready; user story work can now proceed.

---

Phase 3: User Story 1 - Scan Artifact Surfaces Fast (Priority: P1) 🎯 MVP

Goal: Covered list and registry surfaces answer the first operator question with one dominant outcome, one short reason, and one next step.

Independent Test: Seed mixed trustworthy, stale, partial, and blocked artifacts, then verify that list and registry surfaces expose one dominant operator outcome per row instead of several equal-weight semantic columns.

Tests for User Story 1

• T009 [P] [US1] Add baseline snapshot list scanability assertions in apps/platform/tests/Feature/Filament/BaselineSnapshotListFiltersTest.php
• T010 [P] [US1] Add evidence list and overview compression plus canonical-view prefilter and deny-as-not-found assertions in apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php
• T011 [P] [US1] Add review register and review-pack list compression plus view-safe, tenant-prefilter, and deny-as-not-found regression assertions in apps/platform/tests/Feature/TenantReview/TenantReviewRegisterTest.php and apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php

Implementation for User Story 1

• T012 [US1] Apply compressed row summaries to the baseline snapshot table in apps/platform/app/Filament/Resources/BaselineSnapshotResource.php
• T013 [US1] Apply compressed row summaries to the evidence snapshot table in apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
• T014 [US1] Apply compressed row summaries to tenant review and review-pack tables in apps/platform/app/Filament/Resources/TenantReviewResource.php and apps/platform/app/Filament/Resources/ReviewPackResource.php
• T015 [US1] Apply canonical row compression, tenant-prefilter continuity, and entitlement-safe row rendering in apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php and apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
• T016 [US1] Run the US1 fast-feedback verification commands documented in specs/214-governance-outcome-compression/quickstart.md

Checkpoint: User Story 1 is independently deliverable as the MVP scan-surface improvement.

---

Phase 4: User Story 2 - Open Artifact Detail Without Losing Trust Meaning (Priority: P2)

Goal: Covered detail screens lead with outcome, short explanation, and next action before diagnostics.

Independent Test: Open baseline snapshot, evidence snapshot, tenant review, and review-pack detail pages for current, stale, partial, and blocked artifacts and verify that summary-first hierarchy is visible without opening technical sections.

Tests for User Story 2

• T017 [P] [US2] Add baseline snapshot detail hierarchy assertions in apps/platform/tests/Feature/Filament/BaselineSnapshotTruthSurfaceTest.php and apps/platform/tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php
• T018 [P] [US2] Add evidence snapshot detail hierarchy and combined-limiter assertions in apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
• T019 [P] [US2] Add tenant review and review-pack detail hierarchy, combined-limiter, list/detail parity, and architecture-first label suppression assertions in apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php, apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php, apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php, and apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php

Implementation for User Story 2

• T020 [US2] Reorder baseline snapshot detail summaries and key facts in apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php
• T021 [US2] Reorder evidence snapshot detail summaries in apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php
• T022 [US2] Reorder tenant review detail summaries in apps/platform/app/Filament/Resources/TenantReviewResource.php
• T023 [US2] Reorder review-pack detail summaries in apps/platform/app/Filament/Resources/ReviewPackResource.php
• T024 [US2] Render primary, secondary, and diagnostics tiers with translated operator-first summary labels and no architecture-first primary labels in apps/platform/resources/views/filament/infolists/entries/governance-artifact-truth.blade.php
• T025 [US2] Run the US2 detail verification flow documented in specs/214-governance-outcome-compression/quickstart.md

Checkpoint: User Stories 1 and 2 both work independently, with list and detail surfaces using the same compressed language.

---

Phase 5: User Story 3 - Keep Run Detail And Artifact Meaning Aligned (Priority: P3)

Goal: Artifact-oriented run detail explains the dominant artifact impact and next step without contradicting the linked artifact surface.

Independent Test: Open artifact-oriented run detail for baseline, evidence, review, or review-pack runs that ended in limited or blocked artifact outcomes and verify that run detail preserves the same decision direction as the linked artifact.

Tests for User Story 3

• T026 [P] [US3] Add artifact-oriented run detail compression assertions in apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php

Implementation for User Story 3

• T027 [US3] Add compressed operation-run artifact outcome derivation in apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
• T028 [US3] Apply the compressed run-detail summary hierarchy in apps/platform/app/Filament/Resources/OperationRunResource.php
• T029 [US3] Keep tenantless run viewer drill-through and summary ordering aligned in apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
• T030 [US3] Run the US3 operation-run verification flow documented in specs/214-governance-outcome-compression/quickstart.md

Checkpoint: All user stories are now independently functional and directionally aligned.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final guardrail review, verification, and close-out across all stories.

• T031 [P] Re-run the list-surface review checklist against docs/product/standards/list-surface-review-checklist.md
• T032 [P] Refresh final verification notes and payload expectations in specs/214-governance-outcome-compression/quickstart.md and specs/214-governance-outcome-compression/contracts/governance-outcome-compression.logical.openapi.yaml
• T033 Run formatting, the final focused Pest command set, and the manual quickstart smoke pass including the 10-second scan validation and architecture-first label leakage check from specs/214-governance-outcome-compression/quickstart.md
• T034 Record the active feature close-out proof, guardrail status, lane outcome, and document-in-feature test-governance disposition in specs/214-governance-outcome-compression/plan.md

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies; can start immediately.
• Foundational (Phase 2): Depends on Setup completion and blocks all user stories.
• User Story 1 (Phase 3): Depends on Foundational completion.
• User Story 2 (Phase 4): Depends on Foundational completion; does not require US1 to ship, but shares some resource files and should serialize edits per file.
• User Story 3 (Phase 5): Depends on Foundational completion; can proceed independently of US1 and US2 once the compression seam is stable.
• Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

• User Story 1 (P1): No dependency on other user stories; this is the MVP and should ship first.
• User Story 2 (P2): Independent after Phase 2, but it reuses the same compressed truth language introduced for US1.
• User Story 3 (P3): Independent after Phase 2, but it must preserve parity with the shared compressed truth language.

Within Each User Story

• Tests must be written and fail before the corresponding implementation tasks.
• Shared fixture or helper updates must land before the first new story-level assertions that depend on them.
• Surface implementation should follow this order: row/detail tests, page/resource updates, then quickstart validation.
• Finish each story's validation task before moving to the next priority when working sequentially.

Parallel Opportunities

• Setup: T001, T002, and T003 can run in parallel.
• Foundational: T004, T005, and T007 can run in parallel before T006/T008 are finalized.
• US1 tests: T009, T010, and T011 can run in parallel.
• US1 implementation: T012 and T013 can run in parallel; T014 and T015 should serialize around shared summary language decisions.
• US2 tests: T017, T018, and T019 can run in parallel.
• US2 implementation: T020, T021, T022, and T023 can run in parallel, with T024 following once the shared summary tier rules are settled.
• US3: T026 can run while T027 is prepared, but T028 and T029 should follow the final run-detail outcome mapping.

---

Parallel Example: User Story 1

# Run US1 test updates in parallel:
T009 `apps/platform/tests/Feature/Filament/BaselineSnapshotListFiltersTest.php`
T010 `apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php` and `apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php`
T011 `apps/platform/tests/Feature/TenantReview/TenantReviewRegisterTest.php` and `apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php`

# Then split the non-conflicting list-surface implementation files:
T012 `apps/platform/app/Filament/Resources/BaselineSnapshotResource.php`
T013 `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php`

---

Parallel Example: User Story 2

# Run US2 detail assertions in parallel:
T017 `apps/platform/tests/Feature/Filament/BaselineSnapshotTruthSurfaceTest.php` and `apps/platform/tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php`
T018 `apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`
T019 `apps/platform/tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php`, `apps/platform/tests/Feature/TenantReview/TenantReviewUiContractTest.php`, `apps/platform/tests/Feature/ReviewPack/ReviewPackResourceTest.php`, and `apps/platform/tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php`

# Then split the detail-surface implementation by artifact family:
T020 `apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php`
T021 `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php`
T022 `apps/platform/app/Filament/Resources/TenantReviewResource.php`
T023 `apps/platform/app/Filament/Resources/ReviewPackResource.php`

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. STOP and VALIDATE with T016.
5. Demo or ship the scan-surface improvement before detail and run-detail follow-ups.

Incremental Delivery

1. Setup + Foundational establish the shared compression seam.
2. Add User Story 1 and validate list/register scanability.
3. Add User Story 2 and validate summary-first detail hierarchy.
4. Add User Story 3 and validate run-detail parity.
5. Finish with polish, formatting, and close-out proof.

Parallel Team Strategy

With multiple developers:

1. Complete Setup + Foundational together.
2. After Phase 2:
   • Developer A: canonical list/register work in apps/platform/app/Filament/Pages/Reviews/ReviewRegister.php, apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php, and related tests.
   • Developer B: detail-family work in apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php and apps/platform/resources/views/filament/infolists/entries/governance-artifact-truth.blade.php.
   • Developer C: run-detail parity work in apps/platform/app/Filament/Resources/OperationRunResource.php, apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php, and apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php.
3. Serialize edits in apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php, apps/platform/app/Filament/Resources/TenantReviewResource.php, and apps/platform/app/Filament/Resources/ReviewPackResource.php because US1 and US2 both touch those files.

---

Notes

• [P] tasks only mark file-separated work with no unresolved prerequisites.
• [US1], [US2], and [US3] map directly to the spec's independently testable user stories.
• The narrowest proving lane remains fast-feedback plus confidence; do not widen into browser or heavy-governance without explicit follow-up justification.
• Keep any new helper or fixture growth opt-in and bounded to the governance artifact family.