220 lines
15 KiB
Markdown
220 lines
15 KiB
Markdown
# 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.
|
|
|
|
- [X] 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`
|
|
- [X] T002 [P] Create the surface-family context helper in `apps/platform/app/Support/Ui/GovernanceArtifactTruth/SurfaceCompressionContext.php`
|
|
- [X] 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.
|
|
|
|
- [X] T004 [P] Extend opt-in artifact-state builders in `apps/platform/tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php`
|
|
- [X] T005 [P] Add context-safe compression memoization assertions in `apps/platform/tests/Feature/Filament/ReviewRegisterDerivedStateMemoizationTest.php` and `apps/platform/tests/Feature/Filament/EvidenceOverviewDerivedStateMemoizationTest.php`
|
|
- [X] T006 Implement shared compressed outcome derivation and central badge selection in `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
|
|
- [X] T007 [P] Expose concise translated summary inputs for compression in `apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php`
|
|
- [X] 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
|
|
|
|
- [X] T009 [P] [US1] Add baseline snapshot list scanability assertions in `apps/platform/tests/Feature/Filament/BaselineSnapshotListFiltersTest.php`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] T012 [US1] Apply compressed row summaries to the baseline snapshot table in `apps/platform/app/Filament/Resources/BaselineSnapshotResource.php`
|
|
- [X] T013 [US1] Apply compressed row summaries to the evidence snapshot table in `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php`
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] 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`
|
|
- [X] T018 [P] [US2] Add evidence snapshot detail hierarchy and combined-limiter assertions in `apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`
|
|
- [X] 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
|
|
|
|
- [X] T020 [US2] Reorder baseline snapshot detail summaries and key facts in `apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php`
|
|
- [X] T021 [US2] Reorder evidence snapshot detail summaries in `apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php`
|
|
- [X] T022 [US2] Reorder tenant review detail summaries in `apps/platform/app/Filament/Resources/TenantReviewResource.php`
|
|
- [X] T023 [US2] Reorder review-pack detail summaries in `apps/platform/app/Filament/Resources/ReviewPackResource.php`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
- [X] T026 [P] [US3] Add artifact-oriented run detail compression assertions in `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T027 [US3] Add compressed operation-run artifact outcome derivation in `apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
|
|
- [X] T028 [US3] Apply the compressed run-detail summary hierarchy in `apps/platform/app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T029 [US3] Keep tenantless run viewer drill-through and summary ordering aligned in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] 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.
|
|
|
|
- [X] T031 [P] Re-run the list-surface review checklist against `docs/product/standards/list-surface-review-checklist.md`
|
|
- [X] 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`
|
|
- [X] 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`
|
|
- [X] 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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.
|