TenantAtlas/specs/174-evidence-freshness-publication-trust/quickstart.md

Quickstart: Evidence Temporal Freshness & Review Publication Trust

Goal

Validate that stale and partial evidence now degrade review and pack trust consistently across tenant-scoped detail pages and canonical summary pages, without changing routes, authorization semantics, or the current action inventory.

Prerequisites

1. Start Sail if it is not already running.
2. Ensure the acting user is a valid workspace member and entitled to the target tenant or tenants.
3. Prepare representative fixtures for these cases:
   • fresh and complete evidence snapshot
   • stale evidence snapshot
   • partial evidence snapshot or review with partial sections
   • review with publication blockers
   • ready review pack derived from a fresh review
   • ready review pack derived from a stale or partial review

Focused Automated Verification

Run the smallest existing test set that guards the affected surfaces first:

vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewLifecycleTest.php
vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackResourceTest.php
vendor/bin/sail artisan test --compact tests/Feature/TenantReview/TenantReviewRegisterTest.php
vendor/bin/sail artisan test --compact tests/Feature/Evidence/EvidenceOverviewPageTest.php

If implementation extends shared truth helpers or run-detail truth copy, also run:

vendor/bin/sail artisan test --compact tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php

Manual Validation Pass

Use one fresh tenant and one stale or partial tenant, or equivalent seeded records in the same tenant.

1. Evidence snapshot detail trust

Open the tenant-scoped evidence snapshot detail page for a fresh snapshot and a stale snapshot.

Confirm that:

• both snapshots can still exist structurally,
• the stale snapshot is clearly shown as stale or cautionary,
• the fresh snapshot remains current,
• next-step guidance differs appropriately,
• and no raw JSON is required to understand why the stale snapshot is less trustworthy.

2. Review detail trust

Open tenant reviews anchored to:

• fresh complete evidence,
• stale evidence,
• partial evidence.

Confirm that:

• review freshness and publication readiness remain separate concepts,
• stale or partial reviews can still be useful internally,
• but they do not present the same calm publishable posture as fresh complete reviews,
• and next-step guidance points toward refresh or completion work when needed.

3. Review pack trust

Open the review pack list and review packs linked to the reviews above.

Confirm that:

• the review-pack list row already surfaces the same internal-only or publishable caveat before the operator opens detail or clicks Download,
• a pack generated from stale or partial evidence no longer looks calmer than the source review,
• any internal-only or cautionary posture is visible before download,
• and the pack points back to the source review when corrective action is needed.

4. Canonical summary alignment

Open:

• /admin/evidence/overview
• /admin/reviews

Confirm that:

• stale or partial artifacts are visible as such in the row summaries,
• the next-step language is directionally the same as on detail pages,
• a tenant with fresh evidence but no current review shows a next step that points toward review creation rather than implying review readiness already exists,
• and drill-through links preserve tenant context and do not reveal non-entitled tenants.

5. Ten-second scan validation

Timebox the first visible scan of one snapshot detail page, one tenant review detail page, and one review pack detail page to 10 seconds each.

Confirm that within that time an operator can tell:

• whether the artifact is fresh enough,
• whether it is only internally useful or publishable,
• and what the next action is.

6. Authorization and action non-regression

Confirm that:

• view-only users can still inspect truth but not execute manage actions,
• non-entitled users still receive deny-as-not-found behavior,
• existing destructive actions still require confirmation,
• touched refresh, publish, export, regenerate, or create-next-review handlers still dispatch the existing services and current OperationRun types where applicable,
• and no new actions or route changes were introduced as part of the hardening.

7. Shared list-surface review checklist

Review docs/product/standards/list-surface-review-checklist.md against the touched list and report surfaces.

Confirm that:

• /admin/evidence/overview and /admin/reviews still use row click as the primary inspect model,
• the tenant-scoped review-pack list keeps its row-level trust caveat visible before drill-through or download,
• existing inline safe shortcuts and header actions remain in their established positions,
• empty and filtered states still read clearly without hiding trust truth,
• and default-visible row summaries still surface freshness, publishable posture, and next step without requiring drill-through.

8. Performance and render guardrails

Confirm from the implementation diff and final surface behavior that:

• the touched detail and canonical surfaces still render from existing database-backed truth inputs,
• no new render-time external calls, background dispatches, or route changes were introduced,
• and canonical row truth remains lightweight enough for a normal operator scan without adding a new per-row derivation layer.

Formatting And Final Verification

Before finalizing implementation work:

vendor/bin/sail bin pint --dirty --format agent

Then rerun the smallest affected test set. If the user wants broader confidence afterward, offer the full suite.