ahmido
bd06b479e1
Some checks failed
Main Confidence / confidence (push) Failing after 43s
## Summary - add the Spec 220 governance run diagnostic summary seam and wire it through the canonical operation run detail presenter - render summary-first decision guidance for covered governance run families while keeping technical diagnostics secondary - add focused Pest coverage, spec artifacts, and complete the integrated-browser smoke validation for canonical run detail ## Testing - cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent - 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 - integrated browser smoke pass on localhost:8081 covering summary-first hierarchy, zero-output runs, multi-cause runs, cross-family parity, workspace-wide visibility, and deny-as-not-found tenant safety Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #257
147 lines
13 KiB
Markdown
147 lines
13 KiB
Markdown
# Tasks: Humanized Diagnostic Summaries for Governance Operations
|
|
|
|
**Input**: Design documents from `/specs/220-governance-run-summaries/`
|
|
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/governance-run-summaries.logical.openapi.yaml`, `quickstart.md`
|
|
|
|
**Tests**: Required. This feature changes runtime behavior on a Filament-backed Monitoring detail surface, so Pest feature and unit coverage must ship with the implementation.
|
|
|
|
**Test Governance Checklist**
|
|
|
|
- Lane assignment stays `fast-feedback` plus `confidence` and remains the narrowest sufficient proof for this surface change.
|
|
- New tests stay in focused Monitoring and unit suites; no heavy-governance or browser family is introduced.
|
|
- Shared helpers and fixtures remain opt-in, especially `BuildsGovernanceArtifactTruthFixtures`.
|
|
- Validation commands stay limited to the focused run-detail suites listed in `specs/220-governance-run-summaries/quickstart.md`.
|
|
- The declared surface profile remains `monitoring-state-page`.
|
|
- Any budget or escalation note stays inside this feature instead of becoming a follow-up spec.
|
|
|
|
## Phase 1: Setup (Shared Test Scaffolding)
|
|
|
|
**Purpose**: Create the focused test seams and fixture hooks the implementation will use.
|
|
|
|
- [X] T001 [P] Create the focused canonical run-detail feature suite and local scenario helpers for zero-output and multi-cause runs in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php`
|
|
- [X] T002 [P] Create the focused summary-derivation unit suite in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php`
|
|
- [X] T003 [P] Extend only generic opt-in shared governance fixture builders for blocked, stale, and internal-only artifact cases in `apps/platform/tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Establish the shared derived-summary seam that all user stories build on.
|
|
|
|
**⚠️ CRITICAL**: No user story work should start until this phase is complete.
|
|
|
|
- [X] T004 Create the derived summary value object in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummary.php`
|
|
- [X] T005 Create the shared summary builder with canonical `OperationRun`, artifact-truth, reason, and explanation inputs in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php`
|
|
- [X] T006 Wire memoized governance summary access into `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`
|
|
- [X] T007 [P] Add guard coverage that summary derivation preserves canonical `summary_counts` meaning and does not invent new count keys in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php`
|
|
- [X] T008 [P] Extend canonical operator-language assertions and explicit next-step category matrix coverage for `retry later`, `resume capture or generation`, `refresh prerequisite data`, `review scope or ambiguous matches`, `manually validate`, and `no further action` in `apps/platform/tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php` and `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php`
|
|
|
|
**Checkpoint**: The shared summary seam exists, is memoized through the current Ops UX presenter, and is guarded against count-contract drift.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Understand the dominant problem fast (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make the canonical governance run-detail page explain the dominant problem, affected scale, and next step before any raw diagnostics.
|
|
|
|
**Independent Test**: Open seeded baseline-capture and baseline-compare runs on `/admin/operations/{run}` and confirm the default-visible summary answers what happened and what to do next without opening diagnostic sections.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T009 [P] [US1] Add feature scenarios for baseline-capture and baseline-compare summary-first hierarchy, no new header actions, and zero-output messaging in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php`
|
|
- [X] T010 [P] [US1] Add unit cases for dominant headline, supporting reason, affected-scale cue, and next-step selection for baseline-capture and baseline-compare runs in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T011 [US1] Implement `baseline.capture` and `baseline.compare` summary mappings in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php`
|
|
- [X] T012 [US1] Expose baseline summary facts through the memoized presenter API in `apps/platform/app/Support/OpsUx/OperationUxPresenter.php`
|
|
- [X] T013 [US1] Render the default-visible summary block before technical diagnostics in `apps/platform/app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T014 [US1] Keep canonical context, lifecycle, and restore banners specialized without duplicating the dominant explanation in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T015 [US1] Preserve summary-first page-shell order for canonical run detail in `apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php`
|
|
- [X] T016 [US1] Update summary fallback expectations for the new first-read hierarchy in `apps/platform/tests/Feature/Monitoring/GovernanceRunExplanationFallbackTest.php`
|
|
- [X] T017 [US1] Update run-detail hierarchy assertions so diagnostics stay secondary in `apps/platform/tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php`
|
|
|
|
**Checkpoint**: Baseline capture and baseline compare runs are readable from the summary block alone, with diagnostics preserved but no longer leading the page.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Separate processing success from artifact trust (Priority: P2)
|
|
|
|
**Goal**: Keep execution completion visible while clearly separating whether the resulting artifact is trustworthy, limited, stale, or internal-only.
|
|
|
|
**Independent Test**: Open seeded evidence-snapshot and review-pack runs where processing completed but the artifact is not decision-grade, and confirm the page shows those truths as separate visible statements.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T018 [P] [US2] Add feature scenarios for evidence-snapshot and review-pack runs that separate processing completion from artifact trust in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php`
|
|
- [X] T019 [P] [US2] Add regression assertions for execution-outcome versus artifact-impact separation in `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
|
- [X] T020 [P] [US2] Add positive and negative authorization coverage for tenant-safe summary rendering and related links in `apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T021 [US2] Implement `tenant.evidence.snapshot.generate` and `tenant.review_pack.generate` summary mappings with distinct execution and artifact-impact facts in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php`
|
|
- [X] T022 [US2] Render separated execution outcome and artifact-impact facts in `apps/platform/app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T023 [US2] Keep related artifact navigation and tenant-context continuity aligned with summary copy in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T024 [US2] Extend canonical route isolation assertions for deny-as-not-found and in-scope `403` behavior in `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`
|
|
|
|
**Checkpoint**: A technically completed run can no longer read like unconditional success when the artifact itself is stale, limited, or internal-only.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Read multi-cause degraded runs without flattening (Priority: P3)
|
|
|
|
**Goal**: Keep degraded governance runs understandable by showing one dominant cause first while preserving secondary causes and affected-scale context.
|
|
|
|
**Independent Test**: Open a seeded multi-cause tenant-review run on `/admin/operations/{run}` and confirm the page shows one dominant cause first, preserves secondary causes, and keeps the same ordering across reloads.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T025 [P] [US3] Add feature scenarios for tenant-review multi-cause degraded runs, stable dominant-cause ordering, and cross-family parity for the same cause class across at least two covered governance families in `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php`
|
|
- [X] T026 [P] [US3] Add unit cases for dominant-cause ranking, secondary causes, and affected-scale confidence in `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T027 [US3] Implement `tenant.review.compose` multi-cause summary mapping and shared ranking rules across covered governance families in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php`
|
|
- [X] T028 [US3] Render secondary-cause breakdown and affected-scale detail without flattening the dominant explanation in `apps/platform/app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T029 [US3] Suppress inaccessible tenant and artifact hints in summary text and related-navigation branches in `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php`
|
|
- [X] T030 [US3] Keep canonical run-detail banners and page-shell copy free of duplicated multi-cause messaging in `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T031 [US3] Extend authorization surface assertions so inaccessible related context never leaks through summary or navigation output in `apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`
|
|
|
|
**Checkpoint**: Multi-cause degraded runs stay human-readable, deterministically ordered, and tenant-safe.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final guardrail review, formatting, focused validation, and manual smoke.
|
|
|
|
- [X] T032 [P] Review monitoring-state-page guardrail coverage, lane assignment, and fixture-cost notes against `specs/220-governance-run-summaries/plan.md` and `specs/220-governance-run-summaries/quickstart.md`
|
|
- [X] T033 [P] Format changed PHP and Blade files including `apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php`, `apps/platform/app/Filament/Resources/OperationRunResource.php`, `apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`, and `apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php`
|
|
- [X] T034 Run the canonical proving commands for `apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php`, `apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, `apps/platform/tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php`, `apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php`, `apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php`, `apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php`, and `apps/platform/tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php`
|
|
- [X] T035 [P] Execute the manual smoke checks for summary-first hierarchy, zero-output runs, multi-cause runs, cross-family parity, and tenant-safe related links in `specs/220-governance-run-summaries/quickstart.md`
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
- Setup tasks `T001-T003` can begin immediately.
|
|
- Foundational tasks `T004-T008` depend on setup and block all story work.
|
|
- User Story 1 depends on Phase 2 and is the MVP slice.
|
|
- User Story 2 depends on Phase 2 and the shared summary rendering established in User Story 1 because it extends the same builder and canonical detail surface.
|
|
- User Story 3 depends on Phase 2 and should follow User Story 1 because it extends the same ranking and rendering seams; it can overlap with late User Story 2 test work once the shared builder contract is stable.
|
|
- Polish tasks depend on all user stories being complete.
|
|
|
|
## Parallel Execution Examples
|
|
|
|
- **US1**: Run `T009` and `T010` together; after `T011-T012`, split `T013`, `T014`, and `T015` across different files.
|
|
- **US2**: Run `T018`, `T019`, and `T020` together; after `T021`, split `T022`, `T023`, and `T024` across resource, page, and authorization files.
|
|
- **US3**: Run `T025` and `T026` together; after `T027`, split `T028`, `T029`, and `T030` while keeping `T031` as the final authorization proof.
|
|
|
|
## Implementation Strategy
|
|
|
|
- Finish Setup and Foundational phases first so the derived summary seam and opt-in fixtures are stable.
|
|
- Deliver User Story 1 as the MVP because it provides the first operator-visible improvement on canonical run detail.
|
|
- Extend the same seam through User Story 2 to separate execution success from artifact trust across additional governance families.
|
|
- Finish with User Story 3 to lock deterministic multi-cause ranking and no-leak summary behavior.
|
|
- Close with formatting, focused proving commands, and the manual smoke pass documented in `quickstart.md`.
|