TenantAtlas/specs/220-governance-run-summaries/quickstart.md

Quickstart: Humanized Diagnostic Summaries for Governance Operations

Goal

Validate that canonical governance operation run detail now answers the first operator question with one dominant summary, one short reason, one affected-scale cue where available, and one next step, while keeping raw diagnostics secondary and preserving current authorization and navigation semantics.

Prerequisites

1. Start Sail if it is not already running.
2. Ensure the acting user is a valid workspace member and is entitled to the target tenant where the run is tenant-bound.
3. Prepare representative runs for these cases:
   • blocked baseline capture with no usable inventory basis
   • baseline compare with ambiguous matches or evidence gaps
   • evidence snapshot generation with stale or incomplete output
   • tenant review composition with missing sections or stale evidence
   • review-pack generation with internal-only or blocked outcome
   • one multi-cause degraded run
   • one zero-output or all-zero run that must not read as green

Focused Automated Verification

Run formatting first:

cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Then run the smallest proving set:

cd apps/platform && ./vendor/bin/sail artisan test --compact \
  tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php \
  tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php \
  tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php \
  tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php \
  tests/Feature/RunAuthorizationTenantIsolationTest.php \
  tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php \
  tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php

If the new focused suite is not yet isolated, run the Monitoring subset instead:

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/

Manual Validation Pass

1. Canonical run detail entry path

Open /admin/operations and drill into a governance run.

Confirm that:

• row navigation remains the inspect model,
• no new row or header action appears,
• and arriving from tenant context does not silently widen back to all-tenant semantics.

2. Baseline capture blocked by prerequisite

Open a blocked baseline-capture run.

Confirm that:

• the page leads with no baseline was captured-style meaning,
• the missing prerequisite appears before raw payloads,
• execution status and artifact usability are visible as separate facts,
• and raw diagnostics remain lower on the page.

3. Baseline compare with ambiguity or suppressed output

Open a baseline-compare run with evidence gaps, ambiguous matches, or suppressed output.

Confirm that:

• the first summary names the compare outcome and its trust limitation,
• the dominant cause is understandable without raw JSON,
• any affected-scale cue is visible when supported by stored counts or gap detail,
• and 0 findings or zero-output does not read as an all-clear.

4. Evidence snapshot generation

Open a run that produced stale or incomplete evidence.

Confirm that:

• processing success does not imply trustworthy evidence,
• the page states the evidence limitation before technical payloads,
• and next-step guidance points to the right recovery action.

5. Tenant review composition and review-pack generation

Open one review-compose run and one review-pack-generation run.

Confirm that:

• review generation can explain missing sections or stale evidence without JSON,
• pack generation can explain internal-only or blocked shareability outcomes,
• and related artifact links remain available only when the actor is entitled to them.

6. Multi-cause degraded run

Open a run with two or more stored degraded causes.

Confirm that:

• one dominant cause is shown first,
• at least one secondary cause is still discoverable,
• and the ordering is stable across reloads.

7. Cross-family parity

Open two covered governance runs from different families that share the same dominant cause class.

Confirm that:

• the same cause class keeps the same primary reading direction,
• the next-step category stays consistent where the persisted truth supports the same operator action,
• and cross-family wording does not drift into conflicting operator guidance.

8. Authorization and tenant safety

Confirm that:

• non-members still receive deny-as-not-found behavior,
• in-scope members lacking capability still receive 403 where expected,
• summary text does not leak inaccessible tenant or artifact hints,
• and OperationRun remains non-searchable.

9. Ten-second scan check

Timebox the first visible scan of one blocked, one degraded, and one zero-output governance run detail page.

Confirm that within 10-15 seconds an operator can determine:

• what happened,
• whether the resulting artifact is trustworthy enough to act on,
• what was affected when the stored data supports that cue,
• and what the next step is,

without opening diagnostic sections.

Final Verification Notes

• Keep diagnostics present but secondary.
• Do not add retry, cancel, force-fail, or other intervention controls as part of this slice.
• If a manual reviewer sees the same dominant-cause copy both in a banner and in the decision zone, treat that as a regression and tighten the summary ownership.