217 lines
17 KiB
Markdown
217 lines
17 KiB
Markdown
# Tasks: Baseline Compare Summary Trust Propagation & Compliance Claim Hardening
|
|
|
|
**Input**: Design documents from `/specs/165-baseline-summary-trust/`
|
|
**Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/`
|
|
|
|
**Tests**: Tests are REQUIRED for this feature. Use Pest and Livewire coverage in `tests/Feature/Baselines/BaselineCompareStatsTest.php`, `tests/Feature/Baselines/BaselineCompareExplanationFallbackTest.php`, `tests/Feature/Baselines/BaselineCompareSummaryAssessmentTest.php`, `tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php`, `tests/Feature/Filament/BaselineCompareNowWidgetTest.php`, `tests/Feature/Filament/NeedsAttentionWidgetTest.php`, `tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php`, `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php`, `tests/Feature/Filament/BaselineCompareCoverageBannerTest.php`, `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php`, `tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php`, `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, `tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php`, and focused DB-only dashboard coverage in `tests/Feature/Filament/TenantDashboardDbOnlyTest.php`.
|
|
**Operations**: This feature reads existing baseline compare `OperationRun` evidence only. No new run creation, lifecycle transition, notification, or `summary_counts` producer work is introduced.
|
|
**RBAC**: Existing tenant-view access and existing capability-gated `Compare now` behavior must remain unchanged. Tests must prove no regression for tenant membership, deny-as-not-found semantics, and capability-gated compare execution.
|
|
**Operator Surfaces**: Dashboard widget, dashboard attention summary, coverage banner, and landing summary must remain operator-first and must never claim a stronger governance state than the canonical run detail.
|
|
**Filament UI Action Surfaces**: No new actions are added. Existing links and the guarded `Compare now` action must remain intact while summary wording and state selection change.
|
|
**Filament UI UX-001**: Existing widgets, banner, and landing layout remain compact and sectioned; diagnostics stay secondary.
|
|
**Badges**: Any changed status-like badge or tone must continue to use centralized semantics rather than page-local success or warning mappings.
|
|
|
|
**Organization**: Tasks are grouped by user story so each story can be implemented and validated as an incremental slice once the shared summary contract is in place.
|
|
|
|
## Phase 1: Setup (Shared Summary Contract)
|
|
|
|
**Purpose**: Create the reusable support-layer contract that all in-scope summary surfaces will consume.
|
|
|
|
- [X] T001 Create the compact summary DTO in `app/Support/Baselines/BaselineCompareSummaryAssessment.php`
|
|
- [X] T002 [P] Create the shared summary assessor that derives state family, headline, tone, and next action from stats plus explanation in `app/Support/Baselines/BaselineCompareSummaryAssessor.php`
|
|
- [X] T003 [P] Add support-layer scenario coverage for the shared summary contract in `tests/Feature/Baselines/BaselineCompareSummaryAssessmentTest.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Truth Propagation Prerequisites)
|
|
|
|
**Purpose**: Wire the summary contract into the existing baseline truth layer before touching any operator-facing surface.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T004 Expose the shared summary assessment from baseline compare stats in `app/Support/Baselines/BaselineCompareStats.php`
|
|
- [X] T005 [P] Align compact-surface explanation family, stale-versus-not-ready distinction, and next-action derivation in `app/Support/Baselines/BaselineCompareExplanationRegistry.php`
|
|
- [X] T006 [P] Keep positive-claim reason semantics explicit for compact summaries in `app/Support/Baselines/BaselineCompareReasonCode.php` and `app/Support/ReasonTranslation/ReasonTranslator.php`
|
|
|
|
**Checkpoint**: The support layer now provides one reusable, trust-aware summary assessment for all covered surfaces.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Trust Dashboard Summary Claims (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Remove false calm from tenant-dashboard summary surfaces so zero findings no longer implies a compliant or all-clear state when evidence is limited.
|
|
|
|
**Independent Test**: Render dashboard summary surfaces for trustworthy, limited-confidence, evidence-gap-affected, stale, failed, in-progress, and unavailable compare scenarios and verify that only genuinely trustworthy no-drift results can present a positive state.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T007 [P] [US1] Replace the false compliant widget assertion and add trustworthy, limited-confidence, stale, failed, in-progress, and unavailable scenarios plus widget drilldown expectations in `tests/Feature/Filament/BaselineCompareNowWidgetTest.php`
|
|
- [X] T008 [P] [US1] Add dashboard attention-summary coverage for limited-confidence, evidence-gap, stale, in-progress, and unavailable compare states while keeping `Needs Attention` explicitly non-navigational in `tests/Feature/Filament/NeedsAttentionWidgetTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T009 [US1] Feed the shared summary assessment into the dashboard baseline widget in `app/Filament/Widgets/Dashboard/BaselineCompareNow.php`
|
|
- [X] T010 [US1] Render contract-driven positive, cautionary, stale, unavailable, and in-progress states in `resources/views/filament/widgets/dashboard/baseline-compare-now.blade.php`
|
|
- [X] T011 [US1] Rebuild dashboard healthy and attention item selection from the shared summary contract in `app/Filament/Widgets/Dashboard/NeedsAttention.php`
|
|
- [X] T012 [US1] Render truthful caution and next-step fallback copy in `resources/views/filament/widgets/dashboard/needs-attention.blade.php`
|
|
- [X] T013 [US1] Keep dashboard KPI cards quantitative-only and free of implicit all-clear claims in `app/Filament/Widgets/Dashboard/DashboardKpis.php`
|
|
- [X] T014 [US1] Run the focused dashboard regression pack in `tests/Feature/Filament/BaselineCompareNowWidgetTest.php`, `tests/Feature/Filament/NeedsAttentionWidgetTest.php`, and `tests/Feature/Filament/TenantDashboardDbOnlyTest.php`
|
|
|
|
**Checkpoint**: Tenant dashboard summary surfaces can no longer issue a false compliant or healthy claim when compare trust is limited.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Triage Constrained Compare Results Safely (Priority: P2)
|
|
|
|
**Goal**: Ensure landing and banner surfaces present limited, suppressed, failed, stale, in-progress, or unavailable compare results honestly and with a clear next step.
|
|
|
|
**Independent Test**: Open the landing page and coverage banner for limited-confidence, suppressed-output, evidence-gap, failed, stale-history, no-snapshot, in-progress, and no-result-yet scenarios and verify that each surface stays cautionary, in-progress, or unavailable rather than healthy.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T015 [P] [US2] Extend limited-confidence, suppressed-output, and failed-result landing coverage in `tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php`
|
|
- [X] T016 [P] [US2] Extend zero-findings, evidence-gap, stale-history, in-progress, and unavailable landing coverage in `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php`
|
|
- [X] T017 [P] [US2] Add coverage-banner truth propagation, failed-result handling, and banner drilldown coverage in `tests/Feature/Filament/BaselineCompareCoverageBannerTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T018 [US2] Expose the shared summary assessment to landing-page view data in `app/Filament/Pages/BaselineCompareLanding.php`
|
|
- [X] T019 [US2] Replace findings-only all-clear fallback and keep stale-history, in-progress, and unavailable summary copy distinct in `resources/views/filament/pages/baseline-compare-landing.blade.php`
|
|
- [X] T020 [US2] Propagate evidence-gap-aware and limited-confidence summary state into the coverage banner widget in `app/Filament/Widgets/Tenant/BaselineCompareCoverageBanner.php`
|
|
- [X] T021 [US2] Render compact banner messaging for incomplete evidence, suppressed output, failed-result, and unavailable baseline states in `resources/views/filament/widgets/tenant/baseline-compare-coverage-banner.blade.php`
|
|
- [X] T022 [US2] Align landing summary translations and operator-facing copy with the hardened claim contract in `lang/en/baseline-compare.php`
|
|
- [X] T023 [US2] Run the focused landing and banner regression pack in `tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php`, `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php`, and `tests/Feature/Filament/BaselineCompareCoverageBannerTest.php`
|
|
|
|
**Checkpoint**: Landing and banner surfaces now distinguish trustworthy no-drift, limited confidence, incomplete evidence, failed compare, and unavailable compare states.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - See One Truth Across Summary and Detail (Priority: P3)
|
|
|
|
**Goal**: Keep dashboard, landing, banner, and canonical run detail semantically aligned so compact surfaces never out-claim the deeper truth surface.
|
|
|
|
**Independent Test**: Compare the same baseline compare scenarios across dashboard, landing, banner, and canonical run detail and verify that compact surfaces are equally cautious or more cautious, never more optimistic, while guardrails and drilldowns remain intact.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T024 [P] [US3] Add cross-surface consistency coverage for shared compare scenarios in `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php`
|
|
- [X] T025 [P] [US3] Extend canonical baseline truth surface assertions so compact summaries never out-claim run detail in `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
|
- [X] T026 [P] [US3] Preserve DB-only tenant dashboard rendering while summary logic changes in `tests/Feature/Filament/TenantDashboardDbOnlyTest.php`
|
|
- [X] T027 [P] [US3] Preserve deny-as-not-found access, compare-now capability gating, dashboard, banner, and landing drilldowns into canonical run detail or findings, and the intentionally non-navigational `Needs Attention` summary behavior in `tests/Feature/Filament/BaselineCompareNowWidgetTest.php`, `tests/Feature/Filament/NeedsAttentionWidgetTest.php`, `tests/Feature/Filament/BaselineCompareCoverageBannerTest.php`, `tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php`, and `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php`
|
|
- [X] T028 [P] [US3] Extend reason-translation and why-no-findings regression coverage for compact summary trust semantics in `tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php` and `tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T029 [US3] Finalize cross-surface headline, tone, stale-versus-not-ready state families, and next-step selection in `app/Support/Baselines/BaselineCompareSummaryAssessor.php`
|
|
- [X] T030 [US3] Keep reason-translation fallback labels aligned with summary-versus-detail parity in `app/Support/ReasonTranslation/ReasonTranslator.php`
|
|
- [X] T031 [US3] Run the focused cross-surface, RBAC, and reason-translation regression pack in `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php`, `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, `tests/Feature/Filament/TenantDashboardDbOnlyTest.php`, `tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php`, `tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php`, and `tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php`
|
|
|
|
**Checkpoint**: Compact surfaces and canonical drilldowns now share one truthful semantic contract.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final copy alignment, formatting, and focused verification across all stories.
|
|
|
|
- [X] T032 [P] Review and align operator-facing summary copy for compliant, no-drift, limited-confidence, stale, in-progress, unavailable, and next-step wording in `resources/views/filament/widgets/dashboard/baseline-compare-now.blade.php`, `resources/views/filament/widgets/dashboard/needs-attention.blade.php`, `resources/views/filament/widgets/tenant/baseline-compare-coverage-banner.blade.php`, `resources/views/filament/pages/baseline-compare-landing.blade.php`, and `lang/en/baseline-compare.php`
|
|
- [X] T033 Run formatting on touched files with `vendor/bin/sail bin pint --dirty --format agent`
|
|
- [X] T034 Run the final focused verification pack from `specs/165-baseline-summary-trust/quickstart.md` against `tests/Feature/Baselines/BaselineCompareSummaryAssessmentTest.php`, `tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php`, `tests/Feature/Baselines/BaselineCompareStatsTest.php`, `tests/Feature/Baselines/BaselineCompareExplanationFallbackTest.php`, `tests/Feature/Filament/BaselineCompareNowWidgetTest.php`, `tests/Feature/Filament/NeedsAttentionWidgetTest.php`, `tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php`, `tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php`, `tests/Feature/Filament/BaselineCompareCoverageBannerTest.php`, `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php`, `tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php`, `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, `tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php`, and `tests/Feature/Filament/TenantDashboardDbOnlyTest.php`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: Starts immediately and establishes the shared summary contract.
|
|
- **Foundational (Phase 2)**: Depends on Setup and blocks all user story work until summary truth can be derived centrally.
|
|
- **User Story 1 (Phase 3)**: Starts after Foundational and delivers the MVP by removing false calm from the tenant dashboard.
|
|
- **User Story 2 (Phase 4)**: Starts after Foundational and can proceed after the shared summary contract is stable; it hardens landing and banner semantics.
|
|
- **User Story 3 (Phase 5)**: Starts after User Stories 1 and 2 have established the compact summary contract on covered surfaces.
|
|
- **Polish (Phase 6)**: Starts after all desired stories are complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Depends only on the shared summary contract from Phases 1 and 2.
|
|
- **User Story 2 (P2)**: Depends on the same shared contract but can be validated independently on landing and banner surfaces.
|
|
- **User Story 3 (P3)**: Depends on User Stories 1 and 2 because it verifies and finalizes cross-surface semantic consistency.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests should be written or updated before the related implementation tasks and should fail before the feature behavior is considered complete.
|
|
- Support-layer contract changes should land before widget or landing template rewrites that depend on them.
|
|
- Focused story-level test runs should complete before moving to the next story.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T002` and `T003` can run in parallel after the DTO shape in `T001` is clear.
|
|
- `T005` and `T006` can run in parallel after `T004` wires the shared summary seam.
|
|
- `T007` and `T008` can run in parallel for User Story 1.
|
|
- `T015`, `T016`, and `T017` can run in parallel for User Story 2.
|
|
- `T024`, `T025`, `T026`, `T027`, and `T028` can run in parallel for User Story 3.
|
|
- `T032` can run in parallel with the final verification prep once implementation is complete.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Story 1 dashboard tests in parallel:
|
|
Task: T007 tests/Feature/Filament/BaselineCompareNowWidgetTest.php
|
|
Task: T008 tests/Feature/Filament/NeedsAttentionWidgetTest.php
|
|
|
|
# Story 1 implementation split after summary contract wiring:
|
|
Task: T009 app/Filament/Widgets/Dashboard/BaselineCompareNow.php
|
|
Task: T011 app/Filament/Widgets/Dashboard/NeedsAttention.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Story 2 landing and banner tests in parallel:
|
|
Task: T015 tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php
|
|
Task: T016 tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php
|
|
Task: T017 tests/Feature/Filament/BaselineCompareCoverageBannerTest.php
|
|
|
|
# Story 2 implementation split after test expectations are clear:
|
|
Task: T018 app/Filament/Pages/BaselineCompareLanding.php
|
|
Task: T020 app/Filament/Widgets/Tenant/BaselineCompareCoverageBanner.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Story 3 consistency checks in parallel:
|
|
Task: T024 tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
|
|
Task: T025 tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
|
|
Task: T026 tests/Feature/Filament/TenantDashboardDbOnlyTest.php
|
|
Task: T027 tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
|
|
Task: T028 tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php + tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php
|
|
|
|
# Story 3 implementation split after consistency assertions are defined:
|
|
Task: T029 app/Support/Baselines/BaselineCompareSummaryAssessor.php
|
|
Task: T030 app/Support/ReasonTranslation/ReasonTranslator.php
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First
|
|
|
|
- Complete Phase 1 and Phase 2.
|
|
- Deliver User Story 1 as the MVP.
|
|
- Validate that the tenant dashboard no longer issues false compliant or healthy claims when compare evidence is limited.
|
|
|
|
### Incremental Delivery
|
|
|
|
- Add User Story 2 next to harden the landing summary and coverage banner.
|
|
- Add User Story 3 last to guarantee cross-surface semantic consistency against the canonical run detail.
|
|
|
|
### Verification Finish
|
|
|
|
- Run Pint on touched files.
|
|
- Run the focused verification pack from `quickstart.md`.
|
|
- If broader confidence is needed after focused verification, run the wider suite separately.
|