ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
c6cc58e1f3
TenantAtlas/specs/220-governance-run-summaries/tasks.md
Ahmed Darrazi c6cc58e1f3
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 43s
Details
feat: add governance run summaries
2026-04-20 22:43:30 +02:00

13 KiB
Raw Blame History

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.

  • 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
  • T002 [P] Create the focused summary-derivation unit suite in apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php
  • 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.

  • T004 Create the derived summary value object in apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummary.php
  • T005 Create the shared summary builder with canonical OperationRun, artifact-truth, reason, and explanation inputs in apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php
  • T006 Wire memoized governance summary access into apps/platform/app/Support/OpsUx/OperationUxPresenter.php
  • 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
  • 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

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

  • T011 [US1] Implement baseline.capture and baseline.compare summary mappings in apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php
  • T012 [US1] Expose baseline summary facts through the memoized presenter API in apps/platform/app/Support/OpsUx/OperationUxPresenter.php
  • T013 [US1] Render the default-visible summary block before technical diagnostics in apps/platform/app/Filament/Resources/OperationRunResource.php
  • T014 [US1] Keep canonical context, lifecycle, and restore banners specialized without duplicating the dominant explanation in apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • 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
  • T016 [US1] Update summary fallback expectations for the new first-read hierarchy in apps/platform/tests/Feature/Monitoring/GovernanceRunExplanationFallbackTest.php
  • 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

  • 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
  • T019 [P] [US2] Add regression assertions for execution-outcome versus artifact-impact separation in apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php
  • 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

  • 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
  • T022 [US2] Render separated execution outcome and artifact-impact facts in apps/platform/app/Filament/Resources/OperationRunResource.php
  • T023 [US2] Keep related artifact navigation and tenant-context continuity aligned with summary copy in apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
  • 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

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

  • 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
  • T028 [US3] Render secondary-cause breakdown and affected-scale detail without flattening the dominant explanation in apps/platform/app/Filament/Resources/OperationRunResource.php
  • T029 [US3] Suppress inaccessible tenant and artifact hints in summary text and related-navigation branches in apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php
  • 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
  • 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.

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