227 lines
17 KiB
Markdown
227 lines
17 KiB
Markdown
# Tasks: Evidence Temporal Freshness & Review Publication Trust
|
|
|
|
**Input**: Design documents from `/specs/174-evidence-freshness-publication-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 focused Pest coverage in `tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`, `tests/Feature/Evidence/EvidenceOverviewPageTest.php`, `tests/Feature/TenantReview/TenantReviewLifecycleTest.php`, `tests/Feature/TenantReview/TenantReviewRegisterTest.php`, `tests/Feature/ReviewPack/ReviewPackResourceTest.php`, and existing truth-support fixtures.
|
|
**Operations**: This feature reuses existing evidence snapshot, tenant review, and review pack generation flows and their current `OperationRun` types. No new `OperationRun` creation, lifecycle transition, notification, or `summary_counts` producer work is introduced.
|
|
**RBAC**: Existing tenant entitlement, workspace entitlement, and capability gating must remain unchanged. Tests must preserve deny-as-not-found behavior for non-entitled users and manage-action capability gating for view-only users.
|
|
**Operator Surfaces**: Evidence snapshot detail, tenant review detail, review pack detail, evidence overview, and the canonical review register must stay operator-first, with freshness, completeness, publication readiness, and next step visible by default where relevant.
|
|
**Filament UI Action Surfaces**: No new actions are introduced. Existing list inspect affordances, inline safe shortcuts, destructive action placement, and confirmation behavior must remain intact while truth semantics become stricter.
|
|
**Filament UI UX-001**: Existing Infolist and table layouts remain; this feature hardens top-level trust and caveat semantics rather than creating new screens.
|
|
**Badges**: Freshness, completeness, publication-readiness, and artifact-truth semantics must continue to use centralized badge domains and the existing governance truth partial.
|
|
|
|
**Organization**: Tasks are grouped by user story so each story can be implemented and tested as an independent increment after the shared truth scaffolding is in place.
|
|
|
|
## Phase 1: Setup (Shared Test Scaffolding)
|
|
|
|
**Purpose**: Prepare reusable stale and partial evidence fixtures that all stories can build on.
|
|
|
|
- [X] T001 Extend shared stale and partial governance artifact fixture builders in `tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php`
|
|
- [X] T002 [P] Add or refine stale evidence seeding helpers used by evidence and review tests in `tests/Pest.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Truth Propagation Prerequisite)
|
|
|
|
**Purpose**: Tighten the shared trust-propagation seam before any surface-specific story work begins.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T003 Refactor shared freshness-source and evidence-burden inputs used by evidence, review, and pack truth envelopes in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` without introducing a new resolver layer
|
|
- [X] T004 [P] Preserve source-derived stale semantics and required-section blocker behavior without adding a new freshness engine in `app/Services/Evidence/EvidenceCompletenessEvaluator.php` and `app/Services/TenantReviews/TenantReviewReadinessGate.php`
|
|
|
|
**Checkpoint**: The central truth seam is ready for story-specific stale and publication hardening without introducing a second freshness framework.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Detect Stale Evidence Before Reusing It (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make stale evidence visible on snapshot, review, pack, and evidence-overview surfaces before operators reuse the artifact.
|
|
|
|
**Independent Test**: Seed fresh and stale evidence snapshots with the same structural completeness and verify that snapshot, linked review, linked pack, and evidence-overview rows downgrade only for the stale case.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T005 [P] [US1] Add fresh-versus-stale snapshot detail assertions in `tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`
|
|
- [X] T006 [P] [US1] Add stale-evidence overview row assertions in `tests/Feature/Evidence/EvidenceOverviewPageTest.php`
|
|
- [X] T007 [P] [US1] Add stale-evidence trust assertions for linked reviews and packs in `tests/Feature/TenantReview/TenantReviewLifecycleTest.php` and `tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T008 [US1] Surface stale snapshot truth and next-step guidance on tenant evidence detail in `app/Filament/Resources/EvidenceSnapshotResource.php` and `app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php`
|
|
- [X] T009 [US1] Surface stale-evidence burden on tenant review detail without changing action topology in `app/Filament/Resources/TenantReviewResource.php` and `app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php`
|
|
- [X] T010 [US1] Surface stale-evidence burden on review pack list and detail before download in `app/Filament/Resources/ReviewPackResource.php` and `app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php`
|
|
- [X] T011 [US1] Keep canonical evidence freshness rows aligned with snapshot detail in `app/Filament/Pages/Monitoring/EvidenceOverview.php` and `resources/views/filament/pages/monitoring/evidence-overview.blade.php`
|
|
- [X] T012 [US1] Run the focused stale-evidence verification pack in `tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`, `tests/Feature/Evidence/EvidenceOverviewPageTest.php`, `tests/Feature/TenantReview/TenantReviewLifecycleTest.php`, and `tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
|
|
|
**Checkpoint**: Operators can now tell when evidence is stale before relying on snapshots, reviews, packs, or evidence-overview rows.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Distinguish Internal-Use Reviews From Publishable Reviews (Priority: P1)
|
|
|
|
**Goal**: Make partial or stale review evidence degrade review and pack publication posture into internal-only or cautionary states instead of looking publishable.
|
|
|
|
**Independent Test**: Render reviews and packs built from complete evidence, stale evidence, and partial evidence and verify that only the strongest case appears publishable.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T013 [P] [US2] Add partial-evidence and stale-publication-readiness assertions for tenant reviews in `tests/Feature/TenantReview/TenantReviewLifecycleTest.php`
|
|
- [X] T014 [P] [US2] Add internal-only versus publishable pack assertions and download caveat coverage in `tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T015 [US2] Tighten tenant review publication-readiness, next-step, and explanatory trust semantics for stale or partial evidence in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` and `app/Filament/Resources/TenantReviewResource.php`
|
|
- [X] T016 [US2] Tighten review pack publication-readiness and source-review caveat semantics for stale or partial evidence in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` and `app/Filament/Resources/ReviewPackResource.php`
|
|
- [X] T017 [US2] Keep the shared governance truth partial explicit about freshness versus publication readiness without adding page-local status language in `resources/views/filament/infolists/entries/governance-artifact-truth.blade.php`
|
|
- [X] T018 [US2] Verify review and pack detail surfaces stay consistent about internal-only versus publishable trust in `tests/Feature/TenantReview/TenantReviewLifecycleTest.php` and `tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
|
|
|
**Checkpoint**: Review and pack surfaces now distinguish internal-use artifacts from publishable artifacts and no longer imply publication safety from mere downloadability or status alone.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Recover The Evidence Basis Across Review Surfaces (Priority: P2)
|
|
|
|
**Goal**: Keep canonical review and evidence summary surfaces aligned with the tenant-scoped truth they summarize.
|
|
|
|
**Independent Test**: Seed tenants with mixed freshness and review readiness, then verify that the review register and evidence overview rows match the corresponding detail-page trust direction and preserve tenant-safe drill-through.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T019 [P] [US3] Add stale and partial canonical review-register alignment assertions in `tests/Feature/TenantReview/TenantReviewRegisterTest.php`
|
|
- [X] T020 [P] [US3] Add cross-surface drill-through, no-current-review next-step, and tenant-safe evidence-overview alignment assertions in `tests/Feature/Evidence/EvidenceOverviewPageTest.php` and `tests/Feature/TenantReview/TenantReviewRegisterTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T021 [US3] Align canonical review-register artifact truth, publication, and next-step rows with tenant review detail in `app/Filament/Pages/Reviews/ReviewRegister.php`
|
|
- [X] T022 [US3] Preserve tenant-prefilter continuity, truthful drill-through, and the fresh-evidence-with-no-current-review next step between overview, register, and tenant detail surfaces in `app/Filament/Pages/Monitoring/EvidenceOverview.php` and `app/Filament/Pages/Reviews/ReviewRegister.php`
|
|
- [X] T023 [US3] Keep tenant-scoped snapshot, review, and pack resources consistent with canonical summary language in `app/Filament/Resources/EvidenceSnapshotResource.php`, `app/Filament/Resources/TenantReviewResource.php`, and `app/Filament/Resources/ReviewPackResource.php`
|
|
- [X] T024 [US3] Run the focused canonical-summary alignment verification pack in `tests/Feature/TenantReview/TenantReviewRegisterTest.php` and `tests/Feature/Evidence/EvidenceOverviewPageTest.php`
|
|
|
|
**Checkpoint**: Canonical summary surfaces now carry the same trust direction as the tenant-scoped detail pages they summarize.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final consistency, authorization non-regression, formatting, and focused verification across all stories.
|
|
|
|
- [X] T025 [P] Review and align operator-facing truth copy across the shared presenter and truth partial in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php` and `resources/views/filament/infolists/entries/governance-artifact-truth.blade.php`
|
|
- [X] T026 [P] Add manage-action and tenant-entitlement non-regression coverage for touched evidence, review, and pack surfaces in `tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`, `tests/Feature/TenantReview/TenantReviewLifecycleTest.php`, and `tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
|
- [X] T027 Run formatting for touched files using `vendor/bin/sail bin pint --dirty --format agent`
|
|
- [X] T028 Run the final focused verification pack from `specs/174-evidence-freshness-publication-trust/quickstart.md`, including the SC-174-001 10-second manual scan validation, the shared list-surface review checklist in `docs/product/standards/list-surface-review-checklist.md`, the DB-only render and lightweight canonical-row-derivation guardrails in `specs/174-evidence-freshness-publication-trust/plan.md`, and the existing action run-launch semantics in `app/Filament/Resources/EvidenceSnapshotResource.php`, `app/Filament/Resources/TenantReviewResource.php`, and `app/Filament/Resources/ReviewPackResource.php`, against `tests/Feature/Evidence/EvidenceSnapshotResourceTest.php`, `tests/Feature/Evidence/EvidenceOverviewPageTest.php`, `tests/Feature/TenantReview/TenantReviewLifecycleTest.php`, `tests/Feature/TenantReview/TenantReviewRegisterTest.php`, and `tests/Feature/ReviewPack/ReviewPackResourceTest.php`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: Starts immediately and prepares shared stale and partial fixtures.
|
|
- **Foundational (Phase 2)**: Depends on Setup and blocks all story work until the central truth propagation seam is tightened.
|
|
- **User Story 1 (Phase 3)**: Starts after Foundational and delivers the MVP stale-evidence visibility across key surfaces.
|
|
- **User Story 2 (Phase 4)**: Starts after Foundational; it can build on User Story 1 or proceed immediately after the presenter seam is stable, but should follow US1 for the cleanest rollout.
|
|
- **User Story 3 (Phase 5)**: Starts after Foundational and depends on tightened truth semantics from earlier phases to align canonical rows.
|
|
- **Polish (Phase 6)**: Starts after the desired user stories are complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Depends only on the shared truth propagation seam from Phase 2.
|
|
- **User Story 2 (P1)**: Depends on the shared truth propagation seam from Phase 2 and benefits from the stale-surface work in US1.
|
|
- **User Story 3 (P2)**: Depends on the shared truth propagation seam from Phase 2 and should consume the tightened truth semantics delivered by US1 and US2.
|
|
|
|
### Within Each User Story
|
|
|
|
- Shared fixture work must land before story-specific tests rely on new stale or partial scenarios.
|
|
- Tests should be updated before or alongside the related implementation tasks and must fail before the behavior change is considered complete.
|
|
- `ArtifactTruthPresenter` changes should land before downstream Filament resource and page copy cleanup for the same story.
|
|
- Focused story-level test runs should complete before moving to the next story.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T001` and `T002` can run in parallel once the shared stale and partial scenario matrix is agreed.
|
|
- `T005`, `T006`, and `T007` can run in parallel for User Story 1.
|
|
- `T013` and `T014` can run in parallel for User Story 2.
|
|
- `T019` and `T020` can run in parallel for User Story 3.
|
|
- `T025` and `T026` can run in parallel once implementation work is complete.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Story 1 tests in parallel:
|
|
Task: T005 tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
|
|
Task: T006 tests/Feature/Evidence/EvidenceOverviewPageTest.php
|
|
Task: T007 tests/Feature/TenantReview/TenantReviewLifecycleTest.php and tests/Feature/ReviewPack/ReviewPackResourceTest.php
|
|
|
|
# Story 1 implementation split after truth propagation is stable:
|
|
Task: T008 app/Filament/Resources/EvidenceSnapshotResource.php and app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
|
|
Task: T009 app/Filament/Resources/TenantReviewResource.php and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
|
|
Task: T010 app/Filament/Resources/ReviewPackResource.php and app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Story 2 tests in parallel:
|
|
Task: T013 tests/Feature/TenantReview/TenantReviewLifecycleTest.php
|
|
Task: T014 tests/Feature/ReviewPack/ReviewPackResourceTest.php
|
|
|
|
# Story 2 implementation split after failing assertions are in place:
|
|
Task: T015 app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php and app/Filament/Resources/TenantReviewResource.php
|
|
Task: T016 app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php and app/Filament/Resources/ReviewPackResource.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Story 3 tests in parallel:
|
|
Task: T019 tests/Feature/TenantReview/TenantReviewRegisterTest.php
|
|
Task: T020 tests/Feature/Evidence/EvidenceOverviewPageTest.php and tests/Feature/TenantReview/TenantReviewRegisterTest.php
|
|
|
|
# Story 3 implementation split after row-level truth expectations are clear:
|
|
Task: T021 app/Filament/Pages/Reviews/ReviewRegister.php
|
|
Task: T022 app/Filament/Pages/Monitoring/EvidenceOverview.php and app/Filament/Pages/Reviews/ReviewRegister.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**: Verify stale evidence is visible across snapshot, linked review, linked pack, and evidence overview surfaces.
|
|
5. Deploy or demo if the MVP confidence level is sufficient.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Setup + Foundational so the central truth seam is stable.
|
|
2. Add User Story 1 and validate stale-evidence visibility.
|
|
3. Add User Story 2 and validate internal-only versus publishable trust.
|
|
4. Add User Story 3 and validate canonical summary alignment.
|
|
5. Finish with cross-cutting copy, authorization non-regression, formatting, and focused verification.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
With multiple developers:
|
|
|
|
1. Complete Setup + Foundational together.
|
|
2. Once Foundational is done:
|
|
- Developer A: User Story 1
|
|
- Developer B: User Story 2
|
|
- Developer C: User Story 3
|
|
3. Reconcile in Phase 6 with shared copy, authorization non-regression, formatting, and final focused tests.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- [P] tasks indicate different files and no dependency on incomplete predecessor tasks.
|
|
- The same touched file may appear in multiple stories because each story hardens a different user-visible outcome on the same existing surface.
|
|
- No task introduces a new persistence model, a new abstraction layer, or a new reporting subsystem.
|