ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
44898a98ac
TenantAtlas/specs/174-evidence-freshness-publication-trust/tasks.md
ahmido 44898a98ac feat: harden evidence freshness publication trust (#205) 
## Summary
- harden governance artifact truth propagation so stale or partial evidence downgrades evidence snapshots, tenant reviews, review packs, the canonical evidence overview, and the canonical review register consistently
- add the full Spec 174 artifact set under `specs/174-evidence-freshness-publication-trust/` including spec, plan, research, data model, contracts, quickstart, checklist, and completed tasks
- add focused fixture helpers plus a new browser smoke test for the touched evidence, review, and review-pack trust surfaces

## Testing
- `vendor/bin/sail artisan test --compact 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 tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php tests/Browser/Spec174EvidenceFreshnessPublicationTrustSmokeTest.php`
- manual integrated-browser smoke pass across Evidence Overview, Review Register, tenant review detail, tenant evidence snapshot detail, and review-packs list

## Notes
- Livewire v4 compliance is preserved and no Filament v3/v4 APIs were introduced
- no panel or provider changes were made; Laravel 11+ provider registration remains in `bootstrap/providers.php`
- no new global-search behavior was introduced; existing resource view pages remain the relevant detail endpoints
- destructive actions were not broadened; existing confirmation and authorization behavior remains in place
- no new assets were added, so the current Filament asset strategy and deploy-time `php artisan filament:assets` behavior stay unchanged
- branch `174-evidence-freshness-publication-trust` is pushed at `7f2c82c26dc83bbc09fbf9e732d5644cdd143113` and targets `dev`

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #205
2026-04-04 11:31:27 +00:00

17 KiB
Raw Blame History

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.

  • T001 Extend shared stale and partial governance artifact fixture builders in tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php
  • 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.

  • 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
  • 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

  • T005 [P] [US1] Add fresh-versus-stale snapshot detail assertions in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
  • T006 [P] [US1] Add stale-evidence overview row assertions in tests/Feature/Evidence/EvidenceOverviewPageTest.php
  • 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

  • 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
  • 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
  • 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
  • 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
  • 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

  • T013 [P] [US2] Add partial-evidence and stale-publication-readiness assertions for tenant reviews in tests/Feature/TenantReview/TenantReviewLifecycleTest.php
  • 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

  • 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
  • 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
  • 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
  • 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

  • T019 [P] [US3] Add stale and partial canonical review-register alignment assertions in tests/Feature/TenantReview/TenantReviewRegisterTest.php
  • 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

  • T021 [US3] Align canonical review-register artifact truth, publication, and next-step rows with tenant review detail in app/Filament/Pages/Reviews/ReviewRegister.php
  • 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
  • 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
  • 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.

  • 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
  • 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
  • T027 Run formatting for touched files using vendor/bin/sail bin pint --dirty --format agent
  • 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

# 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

# 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

# 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.