ahmido
1f0cc5de56
## Summary - add the shared operator explanation layer with explanation families, trustworthiness semantics, count descriptors, and centralized badge mappings - adopt explanation-first rendering across baseline compare, governance operation run detail, baseline snapshot presentation, tenant review detail, and review register rows - extend reason translation, artifact-truth presentation, fallback ops UX messaging, and focused regression coverage for operator explanation semantics ## Testing - vendor/bin/sail bin pint --dirty --format agent - vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationsTenantScopeTest.php tests/Feature/Operations/OperationRunBlockedExecutionPresentationTest.php - vendor/bin/sail artisan test --compact ## Notes - Livewire v4 compatible - panel provider registration remains in bootstrap/providers.php - no destructive Filament actions were added or changed in this PR - no new global-search behavior was introduced in this slice Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #191
58 lines
2.9 KiB
Markdown
58 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
vendor/bin/sail up -d
|
|
```
|
|
|
|
Run the most relevant focused suites:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
vendor/bin/sail artisan test --compact --filter=Explanation
|
|
vendor/bin/sail artisan test --compact --filter=ReasonTranslation
|
|
```
|
|
|
|
Format changed files:
|
|
|
|
```bash
|
|
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. |