225 lines
16 KiB
Markdown
225 lines
16 KiB
Markdown
# Tasks: Operation Run Detail Hierarchy, Deduplication, and Decision Guidance Hardening
|
|
|
|
**Input**: Design documents from `/specs/164-run-detail-hardening/`
|
|
**Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/`
|
|
|
|
**Tests**: Tests are REQUIRED for this feature. Use Pest coverage in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`, `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, and `tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php`.
|
|
**Operations**: This feature reuses existing `OperationRun` records as a read-only canonical surface. No new run creation, lifecycle transition, notification, or `summary_counts` producer work is introduced.
|
|
**RBAC**: Existing canonical run-view authorization and 404 vs 403 semantics must remain unchanged. Tests must prove no regression for workspace membership, tenant entitlement, and capability enforcement on `/admin/operations/{run}`.
|
|
**Operator Surfaces**: The canonical operation-run detail page must remain operator-first, with one primary decision zone, grouped supporting context, and diagnostics later.
|
|
**Filament UI Action Surfaces**: No new actions are added. Existing view-page actions, row inspection affordances, and confirmation behavior must remain intact while the page hierarchy changes.
|
|
**Filament UI UX-001**: The page remains a custom enterprise detail view with an explicit operator-first hierarchy; diagnostics and JSON stay secondary.
|
|
**Badges**: Execution status, outcome, artifact truth, trust, and lifecycle badges must continue to use centralized badge semantics.
|
|
|
|
**Organization**: Tasks are grouped by user story so each story can be implemented and tested as an independent increment after the shared presentation scaffolding is in place.
|
|
|
|
## Phase 1: Setup (Shared Presentation Contract)
|
|
|
|
**Purpose**: Add the shared enterprise-detail primitives needed by all user stories.
|
|
|
|
- [X] T001 Extend `EnterpriseDetailBuilder` to carry `decisionZone` and `supportingGroups` in `app/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilder.php`
|
|
- [X] T002 [P] Extend the enterprise-detail payload contract for `decisionZone` and `supportingGroups` in `app/Support/Ui/EnterpriseDetail/EnterpriseDetailPageData.php`
|
|
- [X] T003 [P] Add or refine enterprise-detail helpers for decision-zone and grouped-support payload assembly in `app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php`
|
|
- [X] T004 [P] Create the decision-zone rendering partial in `resources/views/filament/infolists/entries/enterprise-detail/decision-zone.blade.php`
|
|
- [X] T005 [P] Extend payload-shape coverage for the new enterprise-detail contract in `tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Layout Prerequisites)
|
|
|
|
**Purpose**: Wire the new shared page shape into the reusable enterprise-detail layout before story-specific behavior changes.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T006 Update enterprise-detail rendering order to `header -> decision zone -> supporting groups -> main sections -> technical sections` in `resources/views/filament/infolists/entries/enterprise-detail/layout.blade.php`
|
|
- [X] T007 [P] Update grouped supporting-card rendering in `resources/views/filament/infolists/entries/enterprise-detail/supporting-card.blade.php`
|
|
- [X] T008 [P] Adjust fact-grid rendering so summary and diagnostic presentations can diverge cleanly in `resources/views/filament/infolists/entries/enterprise-detail/section-items.blade.php`
|
|
|
|
**Checkpoint**: The reusable enterprise-detail shell can now host a first-class decision zone and semantically grouped supporting content.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Triage a Run in One Scan (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make the first visible page area answer what happened, whether the result is usable, and what the operator should do next.
|
|
|
|
**Independent Test**: Open completed-success, partial or completed-with-follow-up, failed, and blocked runs and verify that execution state, outcome, artifact truth, trust meaning, and exactly one primary next step appear before diagnostic sections.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T009 [P] [US1] Extend first-screen hierarchy assertions for completed success, partial or completed-with-follow-up, failed, and blocked runs plus count deduplication in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
|
|
- [X] T010 [P] [US1] Extend artifact-truth versus outcome versus trust assertions and artifact-truth summary-versus-expansion non-duplication coverage in `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T011 [US1] Refactor `enterpriseDetailPage()` to assemble the primary decision-zone payload from status, outcome, artifact truth, and trust sources in `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T012 [US1] Remove or absorb redundant run-summary and equal-priority next-step duplication in `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T013 [US1] Centralize one primary count presentation and one diagnostics-only fallback in `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T014 [US1] Render execution state, outcome, artifact truth, result meaning, result trust, and one primary next step in `resources/views/filament/infolists/entries/enterprise-detail/decision-zone.blade.php`
|
|
- [X] T015 [US1] Ensure later artifact-truth rendering adds deeper explanation instead of restating the decision-zone summary in `resources/views/filament/infolists/entries/governance-artifact-truth.blade.php` and `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T016 [US1] Run the focused P1 regression pack in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` and `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`
|
|
|
|
**Checkpoint**: The canonical run detail page is now a usable decision surface for ordinary completed, partial, failed, and blocked runs.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Understand Special-State Caveats Without Confusion (Priority: P2)
|
|
|
|
**Goal**: Make stale, reconciled, blocked, and artifact-limited states visible and understandable without duplicating the same warning across multiple equal-priority regions.
|
|
|
|
**Independent Test**: Open stale, reconciled, blocked, and artifact-limited runs and verify that caveats are clear, contextual, and do not appear as competing top-level truths.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T017 [P] [US2] Add stale, reconciled, blocked, and artifact-limited hierarchy assertions in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
|
|
- [X] T018 [P] [US2] Add positive and negative tenant-linked related-context, diagnostic-visibility, and canonical deep-link entry regressions for special-state runs in `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T019 [US2] Split current-state facts into semantic `guidance`, `lifecycle`, `timing`, and `metadata` supporting groups in `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T020 [US2] Keep mismatch, blocked, and lifecycle attention contextual and non-duplicative in `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T021 [US2] Update special-state banner and grouped-support copy treatment in `resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php` and `resources/views/filament/infolists/entries/enterprise-detail/supporting-card.blade.php`
|
|
- [X] T022 [US2] Run the focused P2 regression pack in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` and `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`
|
|
|
|
**Checkpoint**: Exceptional lifecycle and artifact-confidence states are visible, decision-grade, and no longer over-repeated.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Keep Deep Detail Without Losing the Decision Hierarchy (Priority: P3)
|
|
|
|
**Goal**: Preserve type-specific detail and diagnostics while forcing them below the canonical decision and supporting layers.
|
|
|
|
**Independent Test**: Open baseline-compare, baseline-capture, verification-heavy, and diagnostic-heavy runs and confirm that type-specific sections remain available only after the decision zone and supporting context.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T023 [P] [US3] Add type-specific ordering, diagnostics-last, and no-duplicate-main-count assertions for baseline-compare, baseline-capture, and verification-heavy runs in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`
|
|
- [X] T024 [P] [US3] Extend enterprise-detail payload and ordering assertions for `decisionZone` and `supportingGroups` in `tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T025 [US3] Reorder failures, reconciliation, baseline compare, baseline capture, verification, and context sections after the canonical summary layers in `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T026 [US3] Keep technical and raw JSON sections progressively disclosed in `resources/views/filament/infolists/entries/enterprise-detail/technical-detail.blade.php` and `resources/views/filament/infolists/entries/snapshot-json.blade.php`
|
|
- [X] T027 [US3] Preserve type-specific coexistence and authorized related-context behavior beneath the decision zone in `resources/views/filament/infolists/entries/enterprise-detail/layout.blade.php` and `resources/views/filament/infolists/entries/related-context.blade.php`
|
|
- [X] T028 [US3] Run the focused P3 regression pack in `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php` and `tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php`
|
|
|
|
**Checkpoint**: Type-specific detail and investigation depth remain intact, but they no longer compete with the top-level operator decision.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final consistency, formatting, and focused verification across all stories.
|
|
|
|
- [X] T029 [P] Review and align operator-facing decision-surface copy in `app/Filament/Resources/OperationRunResource.php` and `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T030 Run formatting for touched implementation files using `vendor/bin/sail bin pint --dirty --format agent` guided by `specs/164-run-detail-hardening/quickstart.md`
|
|
- [X] T031 Run the final focused verification pack from `specs/164-run-detail-hardening/quickstart.md`, including canonical deep-link entry checks, against `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`, `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, `tests/Feature/Operations/TenantlessOperationRunViewerTest.php`, and `tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php`
|
|
|
|
---
|
|
|
|
## Phase 7: Visual Consistency & Enterprise Polish
|
|
|
|
**Purpose**: Address remaining visual and UX inconsistencies identified during browser review. Aligns with FR-164-005, FR-164-007, FR-164-009, FR-164-014, FR-164-016.
|
|
|
|
- [X] T032 Remove identical reason-card description text (`evidence_gap_bucket_help`) and replace with per-reason contextual descriptions in `lang/en/baseline-compare.php` and `resources/views/filament/infolists/entries/evidence-gap-subjects.blade.php`
|
|
- [X] T033 [P] Remove monospace font from `subject_key` column in `app/Livewire/BaselineCompareEvidenceGapTable.php` — values are human-readable labels, not code identifiers
|
|
- [X] T034 [P] Add conditional color treatment to stat-grid items (danger for failed > 0, success for errors = 0) in `resources/views/filament/infolists/entries/enterprise-detail/section-items.blade.php` and `app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php`
|
|
- [X] T035 [P] Standardize grid column count — supporting groups always 2-col, stat grids inside decision zone always 2-col, artifact truth detail 4-col, count diagnostics 4-col — in `resources/views/filament/infolists/entries/enterprise-detail/section-items.blade.php`
|
|
- [X] T036 Add Filament `groups()` to the evidence-gap table to group rows by reason in `app/Livewire/BaselineCompareEvidenceGapTable.php`
|
|
- [X] T037 Run formatting with `vendor/bin/sail bin pint --dirty --format agent`
|
|
- [X] T038 Run focused regression pack against `tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php`, `tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php`, and `tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: Starts immediately and establishes the shared page payload contract.
|
|
- **Foundational (Phase 2)**: Depends on Setup and blocks all story work until the layout can render the new page shape.
|
|
- **User Story 1 (Phase 3)**: Starts after Foundational and delivers the MVP decision surface.
|
|
- **User Story 2 (Phase 4)**: Starts after User Story 1 because it refines the decision zone with special-state caveats.
|
|
- **User Story 3 (Phase 5)**: Starts after User Story 1; it can overlap with User Story 2 once the decision-zone contract is stable.
|
|
- **Polish (Phase 6)**: Starts after the desired user stories are complete.
|
|
- **Visual Consistency (Phase 7)**: Starts after Phase 6; addresses browser-identified visual inconsistencies.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1**: Depends only on Setup and Foundational work.
|
|
- **US2**: Depends on the decision-zone contract from US1 and then focuses on special-state grouping and banner discipline.
|
|
- **US3**: Depends on the decision-zone contract from US1 and then focuses on ordering and coexistence of type-specific detail.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests should be updated before or alongside the relevant implementation tasks and must fail before the behavior change is considered complete.
|
|
- Resource composer changes in `app/Filament/Resources/OperationRunResource.php` should land before Blade partial cleanup for the same story.
|
|
- Focused story-level test runs should complete before moving on to the next story.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T002`, `T003`, `T004`, and `T005` can run in parallel once the builder extension target is clear.
|
|
- `T007` and `T008` can run in parallel after the main layout order is defined.
|
|
- `T009` and `T010` can run in parallel for US1.
|
|
- `T017` and `T018` can run in parallel for US2.
|
|
- `T023` and `T024` can run in parallel for US3.
|
|
- `T029` can run in parallel with final regression execution once all code changes are finished.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Story 1 tests in parallel:
|
|
Task: T009 tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
|
|
Task: T010 tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
|
|
|
|
# Story 1 implementation split after test expectations are clear:
|
|
Task: T011 app/Filament/Resources/OperationRunResource.php
|
|
Task: T014 resources/views/filament/infolists/entries/enterprise-detail/decision-zone.blade.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Story 2 test coverage in parallel:
|
|
Task: T017 tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
|
|
Task: T018 tests/Feature/Operations/TenantlessOperationRunViewerTest.php
|
|
|
|
# Story 2 implementation split after banner rules are locked:
|
|
Task: T019 app/Filament/Resources/OperationRunResource.php
|
|
Task: T021 resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Story 3 regression work in parallel:
|
|
Task: T023 tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
|
|
Task: T024 tests/Unit/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilderTest.php
|
|
|
|
# Story 3 implementation split after ordering assertions are defined:
|
|
Task: T025 app/Filament/Resources/OperationRunResource.php
|
|
Task: T026 resources/views/filament/infolists/entries/enterprise-detail/technical-detail.blade.php
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First
|
|
|
|
- Complete Phase 1 and Phase 2.
|
|
- Deliver User Story 1 as the MVP.
|
|
- Validate that the canonical page now answers the main operator questions within the first visible page height.
|
|
|
|
### Incremental Delivery
|
|
|
|
- Add User Story 2 next to harden stale, reconciled, blocked, and artifact-limited states without duplicate warnings.
|
|
- Add User Story 3 last to preserve deep diagnostic and type-specific detail beneath the new decision hierarchy.
|
|
|
|
### Verification Finish
|
|
|
|
- Run Pint on touched files.
|
|
- Run the focused regression pack from `quickstart.md`.
|
|
- If broader confidence is needed after focused verification, run the wider suite separately.
|