ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
20b6aa6a32
TenantAtlas/specs/164-run-detail-hardening/tasks.md
ahmido 20b6aa6a32 refactor: reduce operation run detail density (#194) 
## Summary
- collapse secondary and diagnostic operation-run sections by default to reduce page density
- visually emphasize the primary next step while keeping counts readable but secondary
- keep failures and other actionable detail available without dominating the default reading path

## Testing
- vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php tests/Feature/Filament/EnterpriseDetailTemplateRegressionTest.php tests/Feature/Operations/TenantlessOperationRunViewerTest.php
- vendor/bin/sail bin pint --dirty --format agent

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #194
2026-03-26 13:23:52 +00:00

16 KiB
Raw Blame History

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.

  • T001 Extend EnterpriseDetailBuilder to carry decisionZone and supportingGroups in app/Support/Ui/EnterpriseDetail/EnterpriseDetailBuilder.php
  • T002 [P] Extend the enterprise-detail payload contract for decisionZone and supportingGroups in app/Support/Ui/EnterpriseDetail/EnterpriseDetailPageData.php
  • T003 [P] Add or refine enterprise-detail helpers for decision-zone and grouped-support payload assembly in app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php
  • T004 [P] Create the decision-zone rendering partial in resources/views/filament/infolists/entries/enterprise-detail/decision-zone.blade.php
  • 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.

  • 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
  • T007 [P] Update grouped supporting-card rendering in resources/views/filament/infolists/entries/enterprise-detail/supporting-card.blade.php
  • 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

  • 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
  • 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

  • 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
  • T012 [US1] Remove or absorb redundant run-summary and equal-priority next-step duplication in app/Filament/Resources/OperationRunResource.php
  • T013 [US1] Centralize one primary count presentation and one diagnostics-only fallback in app/Filament/Resources/OperationRunResource.php
  • 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
  • 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
  • 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

  • T017 [P] [US2] Add stale, reconciled, blocked, and artifact-limited hierarchy assertions in tests/Feature/Filament/OperationRunEnterpriseDetailPageTest.php
  • 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

  • T019 [US2] Split current-state facts into semantic guidance, lifecycle, timing, and metadata supporting groups in app/Filament/Resources/OperationRunResource.php
  • T020 [US2] Keep mismatch, blocked, and lifecycle attention contextual and non-duplicative in app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • 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
  • 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

  • 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
  • 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

  • T025 [US3] Reorder failures, reconciliation, baseline compare, baseline capture, verification, and context sections after the canonical summary layers in app/Filament/Resources/OperationRunResource.php
  • 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
  • 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
  • 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.

  • T029 [P] Review and align operator-facing decision-surface copy in app/Filament/Resources/OperationRunResource.php and app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • 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
  • 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.

  • 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
  • T033 [P] Remove monospace font from subject_key column in app/Livewire/BaselineCompareEvidenceGapTable.php — values are human-readable labels, not code identifiers
  • 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
  • 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
  • T036 Add Filament groups() to the evidence-gap table to group rows by reason in app/Livewire/BaselineCompareEvidenceGapTable.php
  • T037 Run formatting with vendor/bin/sail bin pint --dirty --format agent
  • 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

# 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

# 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

# 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.