TenantAtlas/specs/220-governance-run-summaries/plan.md

Implementation Plan: Humanized Diagnostic Summaries for Governance Operations

Branch: 220-governance-run-summaries | Date: 2026-04-20 | Spec: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/220-governance-run-summaries/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/220-governance-run-summaries/spec.md

Note: This plan keeps the work inside the existing canonical Monitoring run-detail, artifact-truth, and operator-explanation seams. The intended implementation is a bounded derived summary layer for governance operation runs, not a new persistence model, not a new lifecycle/state family, and not a new action or surface framework.

Summary

Add one operator-first diagnostic summary to canonical governance run detail so baseline capture, baseline compare, evidence snapshot generation, tenant review composition, and review-pack generation runs explain dominant artifact impact, dominant cause, affected scale, artifact trustworthiness, and next action before raw diagnostics. The implementation will reuse TenantlessOperationRunViewer, OperationRunResource, ArtifactTruthPresenter, OperatorExplanationBuilder, ReasonPresenter, OperationUxPresenter, SummaryCountsNormalizer, and the current enterprise-detail builders, and it will introduce one small GovernanceRunDiagnosticSummary value object plus builder under App\Support\OpsUx so the canonical detail page can express affected-scale and multi-cause ranking without inventing a broader UI framework.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12, Filament v5, Livewire v4, Blade
Primary Dependencies: Filament v5, Livewire v4, Pest v4, Laravel Sail, TenantlessOperationRunViewer, OperationRunResource, ArtifactTruthPresenter, OperatorExplanationBuilder, ReasonPresenter, OperationUxPresenter, SummaryCountsNormalizer, and the existing enterprise-detail builders
Storage: PostgreSQL via existing operation_runs plus related baseline_snapshots, evidence_snapshots, tenant_reviews, and review_packs; no schema changes planned
Testing: Pest v4 unit and feature tests, focused Monitoring/Filament/Authorization coverage
Validation Lanes: fast-feedback, confidence Target Platform: Dockerized Laravel web application via Sail locally and Linux containers in deployment Project Type: Laravel monolith web application inside the wt-plattform monorepo
Performance Goals: Preserve DB-only render behavior on canonical run detail, add no render-time external calls, avoid new query breadth, and keep first-pass operator comprehension inside a 10-15 second scan window
Constraints: No new Graph calls, no new routes, no new OperationRun statuses or outcomes, no new summary_counts keys, no new notification surfaces, no new destructive actions, no cross-tenant leakage, and no duplication between decision summary and existing banners
Scale/Scope: One canonical Monitoring detail surface, five governance run families, one bounded derived summary seam, and focused regression coverage for summary ordering, multi-cause explanation, zero-output runs, and authorization safety

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Native vs custom classification summary: native Filament + existing Monitoring detail primitives
• Shared-family relevance: governance run-detail family, operator explanation family, enterprise detail family
• State layers in scope: page, detail, URL-query
• Handling modes by drift class or surface: review-mandatory
• Repository-signal treatment: review-mandatory
• Special surface test profiles: monitoring-state-page
• Required tests or manual smoke: functional-core, state-contract, manual-smoke
• Exception path and spread control: retain the existing diagnostic-detail exception on canonical run detail; do not spread it into new surfaces or action patterns
• Active feature PR close-out entry: Guardrail

Constitution Check

GATE: Passed before Phase 0 research. Re-check after Phase 1 design.

Principle	Pre-Research	Post-Design	Notes
Inventory-first / snapshots-second	PASS	PASS	The feature reorders explanation on existing run and artifact truth only; inventory and snapshot ownership remain unchanged
Read/write separation	PASS	PASS	No new writes, previews, confirmations, or audit-log paths are introduced
Graph contract path	PASS	PASS	No new Graph calls or contract-registry changes
RBAC / workspace / tenant isolation	PASS	PASS	Canonical /admin/operations/{run} remains tenant-safe; non-members stay 404; in-scope capability denials remain 403
Run observability / Ops-UX	PASS	PASS	Existing OperationRun lifecycle, feedback surfaces, initiator rules, and summary-count contracts remain unchanged
Ops-UX summary counts	PASS	PASS	Existing flat numeric summary_counts stay canonical; the new summary only interprets them
Proportionality / no premature abstraction	PASS	PASS	One bounded run-summary helper is justified; no new framework, persistence, or state family is needed
Few layers / UI semantics	PASS	PASS	New logic stays downstream of ArtifactTruthEnvelope and OperatorExplanationPattern; no second truth source is introduced
Badge semantics (BADGE-001)	PASS	PASS	Existing badge domains remain canonical; the feature changes order and supporting copy only
Filament-native UI (UI-FIL-001)	PASS	PASS	Existing Filament detail page, sections, and enterprise-detail builders remain the implementation path
Action surface / inspect model	PASS	PASS	Canonical run detail remains the single inspect model; no new row, header, or bulk actions are introduced
Decision-first / OPSURF	PASS	PASS	The page remains a Tertiary Evidence / Diagnostics Surface, but its first read becomes operator-first
Test governance (TEST-GOV-001)	PASS	PASS	Proof stays in focused Monitoring feature coverage plus one narrow unit seam; no browser or heavy-governance expansion
Filament v5 / Livewire v4 compliance	PASS	PASS	The work stays entirely within the current Filament v5 + Livewire v4 stack
Provider registration / global search / assets	PASS	PASS	No panel/provider changes, OperationRunResource stays non-searchable, and no new assets are required

Test Governance Check

• Test purpose / classification by changed surface: Feature for canonical Monitoring run detail and authorization behavior; Unit only for the bounded run-summary builder or ranking helper if introduced
• Affected validation lanes: fast-feedback, confidence
• Why this lane mix is the narrowest sufficient proof: The feature is proven by operator-visible hierarchy, dominant-cause ordering, zero-output handling, and tenant-safe canonical run detail. That needs focused surface tests plus one narrow unit seam, not browser or heavy-governance breadth.
• Narrowest proving command(s):
  • cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php
  • cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php
  • cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php tests/Unit/Support/OperatorExplanation/OperatorExplanationBuilderTest.php
• Fixture / helper / factory / seed / context cost risks: Shared fixture drift is the main risk. BuildsGovernanceArtifactTruthFixtures must stay opt-in, and any multi-cause seeded run helper should remain local to the Monitoring suite instead of becoming a repo-wide default.
• Expensive defaults or shared helper growth introduced?: no; all new scenario builders must require explicit run type, outcome, reason codes, and related artifact context
• Heavy-family additions, promotions, or visibility changes: none
• Surface-class relief / special coverage rule: monitoring-state-page coverage is required; existing standard-native-filament relief is not enough for summary-order assertions on the canonical detail page
• Closing validation and reviewer handoff: Reviewers must confirm summary-first order, no duplicate dominant-cause copy across banners and decision zone, zero-output runs staying non-green, cross-family consistency for shared cause classes, and 404 vs 403 semantics on the canonical route.
• Budget / baseline / trend follow-up: Low-to-moderate assertion growth within Monitoring and one new focused suite; no lane-budget follow-up expected unless helper sprawl begins
• Review-stop questions: Does the change stay inside current Monitoring detail seams? Did any new summary helper become broader than this surface needs? Did shared fixtures remain opt-in? Did any touched view leak inaccessible tenant or artifact hints?
• Escalation path: document-in-feature unless a second shared semantic layer, new persistence, or broad fixture default is proposed; then reject-or-split
• Active feature PR close-out entry: Guardrail
• Why no dedicated follow-up spec is needed: The expected suite cost and abstraction surface stay tightly bounded to one existing canonical detail page and its current governance run families

Project Structure

Documentation (this feature)

specs/220-governance-run-summaries/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── governance-run-summaries.logical.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md

Source Code (repository root)

apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   └── Operations/
│   │   │       └── TenantlessOperationRunViewer.php
│   │   └── Resources/
│   │       └── OperationRunResource.php
│   └── Support/
│       ├── OpsUx/
│       │   ├── OperationUxPresenter.php
│       │   ├── SummaryCountsNormalizer.php
│       │   ├── GovernanceRunDiagnosticSummary.php
│       │   └── GovernanceRunDiagnosticSummaryBuilder.php
│       ├── ReasonTranslation/
│       │   └── ReasonPresenter.php
│       └── Ui/
│           ├── EnterpriseDetail/
│           ├── GovernanceArtifactTruth/
│           │   └── ArtifactTruthPresenter.php
│           └── OperatorExplanation/
│               ├── OperatorExplanationBuilder.php
│               └── OperatorExplanationPattern.php
├── resources/
│   └── views/
│       └── filament/
│           └── pages/
│               └── operations/
│                   └── tenantless-operation-run-viewer.blade.php
└── tests/
    ├── Feature/
    │   ├── Authorization/
    │   │   └── OperatorExplanationSurfaceAuthorizationTest.php
    │   ├── Monitoring/
    │   │   ├── ArtifactTruthRunDetailTest.php
    │   │   ├── GovernanceOperationRunSummariesTest.php
    │   │   └── GovernanceRunExplanationFallbackTest.php
    │   ├── Filament/
    │   │   └── OperationRunBaselineTruthSurfaceTest.php
    │   └── RunAuthorizationTenantIsolationTest.php
    └── Unit/
        ├── Support/
        │   ├── OpsUx/
        │   │   └── GovernanceRunDiagnosticSummaryBuilderTest.php
        │   └── OperatorExplanation/
        │       └── OperatorExplanationBuilderTest.php

Structure Decision: Standard Laravel monolith. The work stays concentrated in the current Monitoring detail files, existing Support/OpsUx and UI helper seams, and focused Pest suites. No new base directory, panel, or package is needed.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
Bounded run-summary helper/value object	Needed to keep dominant-cause ranking, affected-scale mapping, and summary ordering out of OperationRunResource and page templates	Extending the resource/page inline would bury operation-family logic in Filament schema code and make regression coverage brittle

Proportionality Review

• Current operator problem: Canonical governance run detail is still too technical for first-pass operator decisions, especially when execution succeeded but artifact usability did not, or when several degraded causes exist together.
• Existing structure is insufficient because: Existing badges, explanation patterns, and raw payload sections require operators to synthesize impact, trust, and next action themselves. The missing piece is a first-pass run-detail summary that ranks cause and scale for this single surface.
• Narrowest correct implementation: Add one run-detail-specific summary object and builder inside Support/OpsUx, derived entirely from OperationRun, ArtifactTruthEnvelope, OperatorExplanationPattern, and existing count/context payloads.
• Ownership cost created: One small builder/value-object pair, one local set of dominance rules, and focused Monitoring/unit tests.
• Alternative intentionally rejected: Page-local copy patches and ad-hoc Filament facts only. That would duplicate operation-type logic, make hierarchy drift likely, and fail to protect cross-family consistency.
• Release truth: Current-release truth. This plan improves an existing trust surface now rather than preparing a future platform abstraction.

Phase 0 Research

Research outcomes are captured in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/220-governance-run-summaries/research.md.

Key decisions:

• Keep canonical Monitoring run detail on OperationRunResource + TenantlessOperationRunViewer; do not create a second run-detail page.
• Treat ArtifactTruthPresenter, OperatorExplanationBuilder, and ReasonPresenter as the canonical semantic inputs.
• Introduce one bounded GovernanceRunDiagnosticSummary seam so the decision zone can express affected scale, dominant-cause ranking, and secondary-cause detail without overloading the Filament resource schema.
• Derive affected-scale cues from existing summary_counts, run context, and related artifact metadata; do not add schema or summary_counts contract changes.
• Keep lifecycle/context banners specialized and let the decision zone own the dominant explanation to avoid duplicated operator copy.
• Extend current Monitoring and authorization suites and keep multi-cause fixture helpers local or opt-in.

Phase 1 Design

Design artifacts are created under /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/220-governance-run-summaries/:

• research.md: implementation-seam decisions, risks, and rejected alternatives
• data-model.md: logical model for the derived governance run summary, dominant-cause breakdown, and affected-scale cues
• contracts/governance-run-summaries.logical.openapi.yaml: internal logical contract for canonical operations list/detail rendering requirements
• quickstart.md: focused verification workflow for manual and automated validation

Design decisions:

• No schema migration is required; all summary state remains derived.
• The primary implementation seam is canonical run detail plus a small helper under App\Support\OpsUx, not a new cross-domain UI framework.
• Existing Filament action topology, route shape, authorization behavior, and destructive-action semantics remain unchanged.
• OperationUxPresenter remains the façade for memoized governance explanation state on run detail.
• Existing technical sections such as count diagnostics, failure payloads, evidence-gap detail, and artifact-truth detail remain available but must become secondary to the new summary block.

Phase 1 Agent Context Update

Run:

• .specify/scripts/bash/update-agent-context.sh copilot

Constitution Check — Post-Design Re-evaluation

• PASS — the design remains read-surface focused and does not introduce new write paths, Graph calls, assets, or authorization semantics.
• PASS — Livewire v4.0+ and Filament v5 constraints remain unchanged, no provider registration move is required, OperationRunResource remains non-searchable, and no new destructive actions or assets are introduced.

Implementation Strategy

Phase A — Introduce One Bounded Governance Run Summary Seam

Goal: Derive one operator-first run-detail summary without creating a second truth source.

Step	File	Change
A.1	apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummary.php	Add a small value object carrying headline, dominant cause, affected scale, trust statement, secondary causes, and next action
A.2	apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php	Derive the summary from OperationRun, ArtifactTruthPresenter, OperatorExplanationBuilder, ReasonPresenter, summary_counts, and run context
A.3	apps/platform/app/Support/OpsUx/OperationUxPresenter.php	Reuse existing memoization to expose the summary on canonical run detail without adding a new cache family

Phase B — Rewire Canonical Run Detail Around The First Decision

Goal: Make the decision zone lead with humanized diagnostic summaries and push raw diagnostics down.

Step	File	Change
B.1	apps/platform/app/Filament/Resources/OperationRunResource.php	Update the enterprise-detail decision zone to render the new summary, affected-scale cue, and processing-versus-artifact split ahead of technical sections
B.2	apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php	Keep scope, lifecycle, and restore banners specialized while removing duplicated dominant-cause copy from banner-level messaging
B.3	apps/platform/resources/views/filament/pages/operations/tenantless-operation-run-viewer.blade.php or existing enterprise-detail view partials	Ensure the default reading order is summary first, supporting facts second, diagnostics third

Phase C — Add Stable Rules For Covered Governance Run Families

Goal: Keep summary language and affected-scale cues stable across the five scoped governance families.

Step	File	Change
C.1	apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php	Add baseline-capture rules for blocked prerequisite, zero-subject capture, and unusable snapshot outcomes
C.2	apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php	Add baseline-compare rules for suppressed output, ambiguous matches, evidence gaps, and strategy failures
C.3	apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php	Add evidence snapshot, tenant review, and review-pack generation rules using existing related artifact truth plus run context
C.4	apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php	Add one stable dominant-cause ranking rule so tied degraded runs do not reorder arbitrarily between renders

Phase D — Preserve Tenant Safety, Related Links, and Existing Action Topology

Goal: Improve explanation without changing route, RBAC, or action behavior.

Step	File	Change
D.1	apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php	Keep canonical back-link lineage, active-tenant continuity, and grouped related navigation intact
D.2	apps/platform/app/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilder.php	Ensure summary output suppresses inaccessible artifact or tenant hints when related navigation is not allowed
D.3	Existing authorization tests and related-link helpers	Keep 404 vs 403 semantics unchanged and verify no new mutation affordances appear

Phase E — Protect The Surface With Focused Regression Coverage

Goal: Add the smallest test set that locks summary order, multi-cause behavior, zero-output runs, and authorization safety.

Step	File	Change
E.1	apps/platform/tests/Unit/Support/OpsUx/GovernanceRunDiagnosticSummaryBuilderTest.php	Add unit coverage for dominant-cause ranking, affected-scale derivation, and next-step category mapping
E.2	apps/platform/tests/Feature/Monitoring/GovernanceOperationRunSummariesTest.php	Add end-to-end run-detail coverage for multi-cause degraded runs, all-zero runs, cross-family parity, and diagnostics-secondary ordering
E.3	apps/platform/tests/Feature/Filament/OperationRunBaselineTruthSurfaceTest.php and apps/platform/tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php	Update existing assertions to match final summary-first wording and remove brittle duplication gaps
E.4	apps/platform/tests/Feature/Authorization/OperatorExplanationSurfaceAuthorizationTest.php and apps/platform/tests/Feature/RunAuthorizationTenantIsolationTest.php	Extend canonical route coverage for tenant-safe summary rendering and inaccessible related navigation
E.5	cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent plus focused Pest runs	Run formatting and the narrowest proving commands before implementation close-out

Key Design Decisions

D-001 — Canonical run detail remains the only detailed run-inspection surface

The feature improves the current canonical Monitoring detail page instead of creating a second run viewer or a special governance-only route.

D-002 — Existing truth and explanation envelopes remain canonical

ArtifactTruthEnvelope and OperatorExplanationPattern remain the semantic source of truth. The new summary layer only ranks and presents them for this one surface.

D-003 — Affected scale stays derived from existing persisted signals

summary_counts, run context, failure summaries, and related artifact truth are sufficient inputs. The plan explicitly avoids schema changes or new count contracts.

D-004 — Banners stay specialized; the decision zone owns the main explanation

Context, lifecycle, or restore-continuation banners may still appear, but the dominant cause and next-step explanation must live in the decision zone so the page does not say the same thing twice.

D-005 — Shared fixtures stay opt-in

Multi-cause or zero-output scenario builders should remain local to the Monitoring suite unless a second real consumer proves they belong in a shared concern.

Risk Assessment

Risk	Impact	Likelihood	Mitigation
The new summary duplicates existing banner copy and makes the page louder instead of calmer	High	Medium	Keep banners specialized and let the decision zone own dominant explanation text
Dominant-cause ranking changes arbitrarily between equivalent multi-cause runs	High	Medium	Encode one explicit ranking rule and cover it with unit tests plus one multi-cause feature test
Affected-scale cues drift by operation family and become inconsistent	Medium	Medium	Centralize scale mapping in the builder and reuse it across all covered run families
Shared fixtures or helper defaults silently hide required run context	Medium	Medium	Require explicit type, outcome, reason, and related artifact context in new scenario builders
Summary copy leaks inaccessible tenant or artifact hints on canonical /admin routes	High	Low	Keep authorization tests on related links and summary rendering together and suppress inaccessible context

Test Strategy

• Add one new focused feature suite for governance run summaries and keep it scoped to canonical Monitoring run detail.
• Add one narrow unit suite for dominant-cause and affected-scale derivation only if a dedicated builder is introduced.
• Reuse existing Monitoring and authorization suites for regression coverage instead of creating browser or heavy-governance breadth.
• Keep BuildsGovernanceArtifactTruthFixtures opt-in and add any multi-cause builder locally to the Monitoring suite first.
• Preserve DB-only rendering guarantees on canonical run detail while adjusting the visible summary hierarchy.