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
217 lines
14 KiB
Markdown
217 lines
14 KiB
Markdown
# Tasks: Operator Explanation Layer
|
|
|
|
**Input**: Design documents from `/specs/161-operator-explanation-layer/`
|
|
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/openapi.yaml, quickstart.md
|
|
|
|
**Tests**: Tests are REQUIRED because this feature changes runtime behavior on governance read surfaces, reason translation, artifact-truth presentation, and operator-facing interpretation.
|
|
**Operations**: This feature does not introduce new long-running operations. Existing governance `OperationRun` flows remain canonical, and tasks below preserve queued-only toast behavior, progress-only active surfaces, terminal `OperationRunCompleted`, service-owned run transitions, and numeric-only `summary_counts`.
|
|
**RBAC**: Existing workspace, tenant, and canonical Monitoring authorization behavior is preserved. Non-members remain 404, members without capability remain 403, and no new destructive actions are introduced.
|
|
**Badges**: Any changed status-like semantics must stay centralized in `app/Support/Badges/BadgeCatalog.php`, `app/Support/Badges/OperatorOutcomeTaxonomy.php`, and related support classes; no ad-hoc Filament mappings are allowed.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Create the reusable explanation-layer scaffolding before story-specific adoption begins.
|
|
|
|
- [X] T001 Create the core operator explanation value object in `app/Support/Ui/OperatorExplanation/OperatorExplanationPattern.php`
|
|
- [X] T002 [P] Create the count descriptor value object in `app/Support/Ui/OperatorExplanation/CountDescriptor.php`
|
|
- [X] T003 [P] Add reusable explanation test fixtures in `tests/Feature/Concerns/BuildsOperatorExplanationFixtures.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Add the shared semantic and translation infrastructure required by all user stories.
|
|
|
|
**⚠️ CRITICAL**: No user story work should start until this phase is complete.
|
|
|
|
- [X] T004 Create shared explanation-family and trustworthiness enums in `app/Support/Ui/OperatorExplanation/ExplanationFamily.php` and `app/Support/Ui/OperatorExplanation/TrustworthinessLevel.php`
|
|
- [X] T005 [P] Extend translated reason envelopes with trust-impact and absence-pattern fields in `app/Support/ReasonTranslation/ReasonResolutionEnvelope.php`
|
|
- [X] T006 [P] Add the shared explanation builder in `app/Support/Ui/OperatorExplanation/OperatorExplanationBuilder.php`
|
|
- [X] T007 [P] Create the baseline compare explanation registry in `app/Support/Baselines/BaselineCompareExplanationRegistry.php`
|
|
- [X] T008 [P] Extend baseline compare reason semantics in `app/Support/Baselines/BaselineCompareReasonCode.php` and `app/Support/Baselines/BaselineReasonCodes.php`
|
|
- [X] T009 [P] Register centralized outcome and badge semantics for explanation-layer states in `app/Support/Badges/OperatorOutcomeTaxonomy.php` and `app/Support/Badges/BadgeCatalog.php`
|
|
- [X] T010 Add foundational unit and translation coverage in `tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php` and `tests/Feature/ReasonTranslation/ReasonTranslationExplanationTest.php`
|
|
|
|
**Checkpoint**: Shared explanation composition, reason enrichment, and badge semantics are ready for story-level adoption.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Understand Degraded Results Without Diagnostics (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Baseline Compare explains degraded, partial, suppressed, and no-result states in operator language without requiring diagnostics.
|
|
|
|
**Independent Test**: Open Baseline Compare for a case with `0 findings` and evidence gaps, then verify the page explains incomplete evaluation, result trust, and next action from default-visible content alone.
|
|
|
|
### Tests for User Story 1 ⚠️
|
|
|
|
> **NOTE: Write these tests first and confirm they fail before implementation.**
|
|
|
|
- [X] T011 [P] [US1] Extend baseline compare reason-code regression coverage in `tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php`
|
|
- [X] T012 [P] [US1] Add baseline compare explanation-surface coverage in `tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php`
|
|
- [X] T013 [P] [US1] Add tenant-surface authorization regression coverage for Baseline Compare in `tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T014 [US1] Add explanation-oriented count classification and trust-state helpers in `app/Support/Baselines/BaselineCompareStats.php`
|
|
- [X] T015 [US1] Build baseline compare explanation payloads from translated reasons in `app/Services/Baselines/BaselineCompareService.php` and `app/Jobs/CompareBaselineToTenantJob.php`
|
|
- [X] T016 [US1] Refactor page state mapping to explanation-first rendering in `app/Filament/Pages/BaselineCompareLanding.php`
|
|
- [X] T017 [US1] Rework the baseline compare primary explanation and diagnostics layout in `resources/views/filament/pages/baseline-compare-landing.blade.php`
|
|
- [X] T018 [US1] Prefer operator explanation fields over raw reason-message fallbacks in `app/Support/ReasonTranslation/ReasonPresenter.php`
|
|
|
|
**Checkpoint**: Baseline Compare no longer lets `0 findings` or absent output read as implicit all-clear when evaluation was limited.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Separate Execution Success From Result Trust (Priority: P2)
|
|
|
|
**Goal**: Governance-oriented Monitoring run detail and baseline-capture result presentation show execution outcome, result trust, dominant cause, and next action as distinct visible concepts.
|
|
|
|
**Independent Test**: Open a governance run detail page and a Baseline Snapshot result surface for technically completed but limited-confidence outcomes, then verify both surfaces separate execution success from decision confidence without relying on JSON.
|
|
|
|
### Tests for User Story 2 ⚠️
|
|
|
|
- [X] T019 [P] [US2] Extend governance run-detail truth coverage in `tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php`
|
|
- [X] T020 [P] [US2] Extend operation-run explanation-surface assertions in `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
|
- [X] T021 [P] [US2] Add operation-run explanation builder unit coverage in `tests/Unit/Support/OperatorExplanation/OperationRunExplanationTest.php`
|
|
- [X] T022 [P] [US2] Add baseline-capture result explanation coverage in `tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php`
|
|
- [X] T023 [P] [US2] Extend canonical-surface authorization regression coverage for run detail and Baseline Snapshot result presentation in `tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T024 [US2] Compose operation-run and baseline-capture explanation patterns from artifact truth in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
|
|
- [X] T025 [US2] Align Monitoring run-detail explanation sections and count semantics in `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T026 [US2] Route canonical tenantless run viewing through explanation-first rendering in `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T027 [US2] Normalize governance run summaries and next-action wording in `app/Support/OpsUx/OperationUxPresenter.php`
|
|
- [X] T028 [US2] Render baseline-capture result explanation-first state in `app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php` and `app/Filament/Resources/BaselineSnapshotResource.php`
|
|
|
|
**Checkpoint**: Monitoring run detail and Baseline Snapshot result presentation answer what happened, how reliable the result is, why it looks this way, and what to do next before diagnostics.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Reuse One Explanation Pattern Across Domains (Priority: P3)
|
|
|
|
**Goal**: At least one additional governance artifact family reuses the same explanation pattern and next-action semantics beyond baseline compare and run detail.
|
|
|
|
**Independent Test**: Compare a tenant-review surface to the baseline compare reference case and verify both use the same reading order and explanation-family semantics for degraded or missing-input states.
|
|
|
|
### Tests for User Story 3 ⚠️
|
|
|
|
- [X] T029 [P] [US3] Add tenant review detail and Review Register explanation reuse coverage in `tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php`
|
|
- [X] T030 [P] [US3] Extend shared governance-artifact explanation unit coverage in `tests/Unit/Badges/GovernanceArtifactTruthTest.php`
|
|
- [X] T031 [P] [US3] Extend secondary-governance authorization regression coverage for Tenant Review detail and Review Register in `tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T032 [US3] Map tenant review artifact truth into shared explanation patterns in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
|
|
- [X] T033 [US3] Render explanation-first tenant review detail state in `app/Filament/Resources/TenantReviewResource.php`
|
|
- [X] T034 [US3] Align Review Register row outcome and next-step columns with shared explanation patterns in `app/Filament/Pages/Reviews/ReviewRegister.php`
|
|
|
|
**Checkpoint**: The explanation layer is proven reusable on a non-baseline governance surface without inventing a new state dialect.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Harden regression coverage, confirm centralized semantics, and validate the rollout against the documented surface rules.
|
|
|
|
- [X] T035 [P] Refresh centralized taxonomy and badge regression coverage in `tests/Unit/Badges/OperatorOutcomeTaxonomyTest.php`
|
|
- [X] T036 [P] Add absent-output and suppressed-output fallback coverage in `tests/Feature/Baselines/BaselineCompareExplanationFallbackTest.php` and `tests/Feature/Monitoring/GovernanceRunExplanationFallbackTest.php`
|
|
- [X] T037 [P] Review changed operator surfaces against `docs/product/standards/list-surface-review-checklist.md` and record any approved implementation notes in `specs/161-operator-explanation-layer/plan.md`
|
|
- [X] T038 Run focused verification commands from `specs/161-operator-explanation-layer/quickstart.md`
|
|
- [X] T039 Run formatting for changed files with `vendor/bin/sail bin pint --dirty --format agent` after updating `specs/161-operator-explanation-layer/quickstart.md`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: Starts immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user stories.
|
|
- **User Stories (Phases 3-5)**: All depend on Foundational completion.
|
|
- **Polish (Phase 6)**: Depends on all implemented user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Starts after Foundational and delivers the MVP reference implementation on Baseline Compare.
|
|
- **User Story 2 (P2)**: Starts after Foundational and reuses the same explanation infrastructure on Monitoring run detail.
|
|
- **User Story 3 (P3)**: Starts after Foundational and proves the explanation layer is reusable on a second governance domain.
|
|
|
|
### Within Each User Story
|
|
|
|
- Write tests first and confirm they fail before implementation.
|
|
- Update shared builders or presenters before wiring them into Filament surfaces.
|
|
- Finish the main support-layer logic before page-resource rendering changes.
|
|
- Validate each story against its independent checkpoint before moving to the next priority.
|
|
|
|
## Parallel Opportunities
|
|
|
|
- `T002` and `T003` can run in parallel after `T001`.
|
|
- `T005` through `T009` can run in parallel once `T004` establishes the shared explanation-state vocabulary.
|
|
- Story test tasks marked `[P]` can run in parallel within each user story.
|
|
- Surface adoption work in different files can split after the shared explanation infrastructure lands.
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Write and run Baseline Compare tests in parallel:
|
|
T011 tests/Feature/Baselines/BaselineCompareWhyNoFindingsReasonCodeTest.php
|
|
T012 tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php
|
|
T013 tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php
|
|
|
|
# After shared explanation primitives are ready, split story files:
|
|
T014 app/Support/Baselines/BaselineCompareStats.php
|
|
T016 app/Filament/Pages/BaselineCompareLanding.php
|
|
T017 resources/views/filament/pages/baseline-compare-landing.blade.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Prepare run-detail coverage together:
|
|
T019 tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
|
|
T020 tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
|
|
T021 tests/Unit/Support/OperatorExplanation/OperationRunExplanationTest.php
|
|
T022 tests/Feature/Filament/BaselineCaptureResultExplanationSurfaceTest.php
|
|
T023 tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php
|
|
|
|
# Then split implementation by layer:
|
|
T024 app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
|
|
T025 app/Filament/Resources/OperationRunResource.php
|
|
T026 app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
|
|
T028 app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Reuse coverage can be written together:
|
|
T029 tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php
|
|
T030 tests/Unit/Badges/GovernanceArtifactTruthTest.php
|
|
T031 tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php
|
|
|
|
# Then split the second-domain rollout:
|
|
T032 app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
|
|
T033 app/Filament/Resources/TenantReviewResource.php
|
|
T034 app/Filament/Pages/Reviews/ReviewRegister.php
|
|
```
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First
|
|
|
|
1. Complete Phase 1 and Phase 2.
|
|
2. Deliver User Story 1 on Baseline Compare as the first shippable explanation-layer slice.
|
|
3. Validate the motivating `0 findings` plus evidence-gap case before moving on.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Add User Story 2 to align governance Monitoring run detail and Baseline Snapshot capture-result presentation with the same reading model.
|
|
2. Add User Story 3 to prove the pattern is reusable across governance domains on Tenant Review detail and Review Register.
|
|
3. Finish Phase 6 for regression hardening, checklist review, and verification.
|
|
|
|
### Suggested MVP Scope
|
|
|
|
- Phase 1: Setup
|
|
- Phase 2: Foundational
|
|
- Phase 3: User Story 1 only |