TenantAtlas/specs/161-operator-explanation-layer/quickstart.md

Quickstart: Operator Explanation Layer

Goal

Implement and verify a shared operator explanation layer so degraded, partial, suppressed, and missing-input governance results become understandable without opening diagnostics.

Implementation sequence

1. Add the shared explanation-pattern builder in the support layer.
2. Extend reason translation outputs with trust-impact and next-action semantics where missing.
3. Define count-role taxonomy and wire it into baseline compare stats or presenters.
4. Refactor Baseline Compare to render the explanation pattern before diagnostics.
5. Refactor governance-oriented Operation Run detail and Baseline Snapshot result presentation to render the same reading order.
6. Apply the pattern to Tenant Review detail and Review Register to prove reuse.
7. Add focused regression coverage for degraded, suppressed, absent-output, and authorization-preservation cases.
8. Run focused tests and format changed files.

Focused verification commands

Start services if needed:

vendor/bin/sail up -d

Run the most relevant focused suites:

vendor/bin/sail artisan test --compact tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Unit/Badges/OperatorOutcomeTaxonomyTest.php
vendor/bin/sail artisan test --compact tests/Unit/Badges/GovernanceArtifactTruthTest.php

Run any new focused explanation or reason-translation tests added during implementation:

vendor/bin/sail artisan test --compact --filter=Explanation
vendor/bin/sail artisan test --compact --filter=ReasonTranslation

Format changed files:

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

Manual smoke checklist

1. Open Baseline Compare with a case that has 0 findings and evidence gaps, and verify the page reads as incomplete or limited rather than healthy.
2. Open a Baseline Snapshot result surface after capture and verify the primary explanation, trustworthiness statement, and next action appear before low-level truth details.
3. Open a governance Operation Run detail page for a technically successful but limited-confidence result, and verify run completion and result trust are clearly separated.
4. Open a case with missing input or suppressed output and verify the primary explanation says why no normal result exists before diagnostics.
5. Confirm raw JSON, raw reason codes, and low-level counters are still reachable but visually secondary.
6. Confirm Tenant Review detail and Review Register reuse the same explanation family and next-action wording.