TenantAtlas/specs/166-finding-governance-health/quickstart.md

Quickstart: Finding Governance Health & Resolution Semantics Surface Hardening

Goal

Verify that findings, exceptions, and tenant summary surfaces clearly distinguish active work, healthy accepted risk, lapsed or expiring governance, overdue work, and historical resolved or closed workflow states.

Prerequisites

1. Start Sail and ensure the application database is available.
2. Have at least one workspace and one tenant with visible findings in tenant context.
3. Use a seeded dataset that includes at minimum:
   • one active open finding
   • one overdue open finding
   • one risk_accepted finding with valid governance
   • one risk_accepted finding with expiring governance
   • one risk_accepted finding with expired governance
   • one risk_accepted finding with revoked governance
   • one risk_accepted finding with rejected governance where that state is operator-visible
   • one risk_accepted finding with missing-support governance
   • one resolved finding
   • one closed finding
4. Have two user roles available for validation:
   • tenant operator or manager who can inspect findings and exceptions
   • readonly tenant member for capability-safe inspection checks
   • workspace approver with exception-approval scope for canonical queue validation

Findings List Validation

1. Open the tenant findings list.
2. Confirm that the active open finding is visibly distinct from the healthy accepted-risk finding.
3. Confirm that accepted-risk findings with expiring, expired, revoked, rejected where operator-visible, or missing-support governance are visibly distinct from the healthy accepted-risk finding.
4. Confirm that the overdue open finding is visually prioritized relative to non-overdue active work.
5. Confirm that the historical resolved or closed finding does not read like a healthy accepted-risk state.
6. Confirm that list filters and scanability still work while the added governance cues are present.

Finding Detail Validation

1. Open the active finding detail page.
2. Confirm that the first visible zone shows lifecycle state, severity, owner or assignee, due urgency, and next-action context before IDs or raw diagnostics.
3. Open the healthy accepted-risk finding detail page.
4. Confirm that accepted risk remains visible as accepted risk and includes a healthy governance cue.
5. Open the lapsed-governance accepted-risk finding detail page.
6. Confirm that the leading zone surfaces the governance warning before fingerprints, run links, raw evidence, or diff sections.
7. Open the resolved finding detail page.
8. Confirm that the copy reads as workflow or historical state and does not imply technically verified permanent remediation.
9. Confirm that any relevant historical governance warning from the exception trail remains visible as secondary context instead of being erased by the resolved state.
10. Open the closed finding detail page.
11. Confirm that the copy reads as workflow or historical state and does not imply technically verified permanent remediation.
12. Confirm that any relevant historical governance warning from the exception trail remains visible as secondary context instead of being erased by the closed state.

Exception Surface Parity Validation

1. Open the tenant risk-exception register.
2. Confirm that valid, expiring, expired, revoked, rejected where operator-visible, and missing-support governance states remain visibly distinguishable.
3. Navigate from a tenant finding or tenant exception record into the canonical exception queue.
4. Confirm that the canonical queue opens prefiltered to the active tenant.
5. Confirm that the operator can only broaden filters within their authorized tenant set and cannot use filter changes to infer out-of-scope tenants.
6. Open the same records through the canonical exception queue when entitled.
7. Confirm that the queue and the tenant register communicate the same governance truth as the linked finding surfaces.

Summary Surface Validation

1. Open the tenant dashboard.
2. Confirm that NeedsAttention surfaces overdue findings or unhealthy governance even when the tenant has no new findings.
3. Open the baseline-compare landing page.
4. Confirm that the findings summary and no-findings language do not imply an all-clear when overdue findings or unhealthy governance still exist.
5. Confirm that healthy fallback copy appears only when no operator-critical finding or governance attention remains.

Authorization Checks

1. Verify that a readonly tenant member can inspect surfaces they are entitled to see but cannot execute disabled mutation actions.
2. Verify that a non-member or wrong-tenant user receives deny-as-not-found behavior for tenant findings, tenant exceptions, and tenant summary surfaces.
3. Verify that the canonical exception queue remains accessible only to appropriately entitled workspace approvers.

Suggested Focused Test Runs

1. vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsListDefaultsTest.php
2. vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingsListFiltersTest.php
3. vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingRiskGovernanceProjectionTest.php
4. vendor/bin/sail artisan test --compact tests/Feature/Findings/FindingExceptionRegisterTest.php
5. vendor/bin/sail artisan test --compact tests/Feature/Filament/NeedsAttentionWidgetTest.php
6. vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCompareLandingWhyNoFindingsTest.php
7. vendor/bin/sail artisan test --compact tests/Unit/Badges/FindingBadgesTest.php

Timed Acceptance Checks

1. Time SC-166-001 by opening the tenant findings list on a seeded tenant and measuring how long it takes a reviewer to correctly classify healthy accepted risk, lapsed accepted risk, active work, and historical workflow state.
2. Time SC-166-004 by opening finding detail and measuring how long it takes the reviewer to identify lifecycle state, governance health, due urgency, owner or assignee, and next action before interacting with lower diagnostic sections.