TenantAtlas/specs/133-detail-page-template/plan.md

# Implementation Plan: View Page Template Standard for Enterprise Detail Screens

**Branch**: `133-detail-page-template` | **Date**: 2026-03-10 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/133-detail-page-template/spec.md`

## Summary

Standardize the four initial enterprise detail targets around one shared read-only detail-page composition contract: a summary-first header, predictable main-and-supporting layout, dedicated related-context treatment, and secondary technical detail. Reuse the repo’s existing Filament v5 sectioned infolists, centralized badge semantics, related-navigation helpers, and existing presenter patterns, while introducing a narrow shared enterprise-detail composition layer so BaselineSnapshot, BackupSet, EntraGroup, and the workspace-context OperationRun viewer stop drifting into page-specific scaffold layouts.

## Technical Context

**Language/Version**: PHP 8.4.15 / Laravel 12  
**Primary Dependencies**: Filament v5, Livewire v4.0+, Tailwind CSS v4  
**Storage**: PostgreSQL via Laravel Sail; no schema change expected  
**Testing**: Pest v4 feature and unit tests on PHPUnit 12  
**Target Platform**: Laravel Sail web application with workspace-plane admin routes under `/admin` and tenant-context routes under `/admin/t/{tenant}/...`
**Project Type**: Laravel monolith / Filament web application  
**Performance Goals**: Detail pages remain DB-only at render time, keep existing bounded queries, avoid new uncontrolled polling, and de-emphasize heavy technical payloads behind secondary sections  
**Constraints**: Preserve existing routes and resource semantics; keep authorization plane separation intact; keep non-member access as 404 and in-scope capability denial as 403; use Infolists instead of disabled edit forms; avoid a one-size-fits-all abstraction that hides domain-specific sections  
**Scale/Scope**: One shared detail-page standard, one shared composition layer, four aligned target pages, reusable Blade or Infolist building blocks, and focused regression coverage for section order, degraded states, action placement, and permission-aware related context

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first: PASS — no inventory semantics change; the feature reorganizes page presentation only.
- Read/write separation: PASS — the template itself is read-only. Existing linked mutations remain governed by their existing confirmation, audit, and test rules.
- Graph contract path: PASS — no Microsoft Graph call path is added or changed.
- Deterministic capabilities: PASS — authorization and visibility continue to flow through existing capability registries and enforcement helpers.
- RBAC-UX planes and isolation: PASS — BaselineSnapshot and OperationRun remain workspace-plane detail surfaces, BackupSet and EntraGroup remain tenant-context detail surfaces, and cross-plane behavior stays deny-as-not-found.
- Workspace isolation: PASS — workspace membership remains the entry rule for workspace-scoped target pages.
- RBAC-UX destructive confirmation: PASS — no new destructive action is introduced; retained destructive actions on touched screens must keep `->requiresConfirmation()`.
- RBAC-UX global search: PASS — BaselineSnapshot and OperationRun are already globally searchable-disabled; BackupSet and EntraGroup already have view pages, so any existing global-search behavior remains compliant.
- Tenant isolation: PASS — tenant-owned detail pages remain tenant-scoped; related context cannot reveal inaccessible tenant records.
- Run observability: PASS / N/A — no new `OperationRun` is created. OperationRun detail remains a read-only consumer of existing run state.
- Ops-UX 3-surface feedback: PASS / N/A — the template standard does not add run lifecycle feedback. Existing run actions retain current Ops-UX behavior.
- Ops-UX lifecycle and summary counts: PASS / N/A — no run transitions or new `summary_counts` producers are introduced.
- Ops-UX guards and system runs: PASS / N/A — existing guard coverage remains relevant but unchanged in scope.
- Automation: PASS / N/A — no queued or scheduled workflow change is required.
- Data minimization: PASS — the standard only reorders existing authorized data and keeps technical detail secondary.
- Badge semantics (BADGE-001): PASS — all elevated state badges continue to use centralized badge domains and renderers.
- UI naming (UI-NAMING-001): PASS — section titles, empty states, and actions will use domain-first operator language and avoid implementation-first terms.
- Filament UI Action Surface Contract: PASS — all touched pages remain sectioned detail surfaces with predictable header actions and no new unsupported action surfaces.
- Filament UI UX-001: PASS — the design explicitly standardizes view pages around Infolists, structured sections, main-and-supporting hierarchy, badge consistency, and explicit empty states.
- Filament v5 / Livewire v4 compliance: PASS — the feature stays inside the existing Filament v5 / Livewire v4 stack.
- Provider registration (`bootstrap/providers.php`): PASS — no new panel or provider is added; existing panel registration remains in `bootstrap/providers.php`.
- Global search resource rule: PASS — BaselineSnapshot global search remains disabled, BackupSet and EntraGroup already have view pages, and OperationRun global search remains disabled.
- Asset strategy: PASS — no heavy asset bundle is needed; existing deploy-time `php artisan filament:assets` behavior remains sufficient.

## Project Structure

### Documentation (this feature)

```text
specs/133-detail-page-template/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── enterprise-detail-pages.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)

```text
app/
├── Filament/
│   ├── Pages/
│   │   └── Operations/
│   │       └── TenantlessOperationRunViewer.php                # MODIFY — adopt shared detail shell
│   └── Resources/
│       ├── BaselineSnapshotResource.php                        # MODIFY — align infolist contract and action-surface notes
│       ├── BaselineSnapshotResource/
│       │   └── Pages/
│       │       └── ViewBaselineSnapshot.php                    # MODIFY — adopt shared detail shell
│       ├── BackupSetResource.php                               # MODIFY — replace flat infolist with enterprise sections
│       ├── BackupSetResource/
│       │   └── Pages/
│       │       └── ViewBackupSet.php                           # MODIFY — align header actions and supporting layout
│       ├── EntraGroupResource.php                              # MODIFY — add related-context and technical-detail separation
│       ├── EntraGroupResource/
│       │   └── Pages/
│       │       └── ViewEntraGroup.php                          # MODIFY — adopt shared detail shell
│       └── OperationRunResource.php                            # MODIFY — expose shared section composition for run detail
├── Services/
│   └── Baselines/
│       └── SnapshotRendering/
│           └── BaselineSnapshotPresenter.php                  # MODIFY — map to shared summary and technical-detail slots
└── Support/
    ├── Badges/
    │   └── BadgeRenderer.php                                  # reference-only centralized badge semantics
    ├── Navigation/
    │   └── RelatedNavigationResolver.php                      # reference-only related-context assembly
    └── Ui/
        ├── ActionSurface/                                     # reference-only action contract helpers
        └── EnterpriseDetail/                                  # NEW shared detail-page composition classes/value objects/builders
resources/
└── views/
    └── filament/
        ├── infolists/
        │   └── entries/
        │       ├── related-context.blade.php                  # reference-only existing related-context partial
        │       └── enterprise-detail/                         # NEW shared summary/supporting/technical partials if needed
        └── pages/
            └── operations/                                    # reference-only current operation-run viewer Blade page
tests/
├── Feature/
│   ├── Filament/
│   │   ├── BaselineSnapshot*Test.php                          # MODIFY existing structure/degraded-state tests
│   │   ├── BackupSetEnterpriseDetailPageTest.php              # NEW detail hierarchy and action-placement coverage
│   │   ├── EntraGroupEnterpriseDetailPageTest.php             # NEW detail hierarchy and degraded-state coverage
│   │   ├── OperationRunEnterpriseDetailPageTest.php           # NEW layout and contextual-action coverage
│   │   └── EnterpriseDetailTemplateRegressionTest.php         # NEW cross-target reading-order regression coverage
│   └── Guards/
│       └── ActionSurfaceContractTest.php                      # reference-only guard coverage for changed pages
└── Unit/
    └── Support/
        └── Ui/
            └── EnterpriseDetail/                              # NEW page-composition and section-visibility tests
```

**Structure Decision**: Keep the feature inside the existing Laravel/Filament monolith. Introduce a narrow shared composition layer under `app/Support/Ui/EnterpriseDetail` and shared Blade or Infolist partials under `resources/views/filament/infolists/entries/enterprise-detail`, while refactoring the four target detail surfaces in place rather than creating a new panel, new data model, or standalone page system.

## Complexity Tracking

> No Constitution Check violations. No justifications needed.

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| — | — | — |

## Phase 0 — Research (DONE)

Output:
- `specs/133-detail-page-template/research.md`

Key findings captured:
- The repo already has reusable building blocks for badge semantics, related-context assembly, action-surface declarations, and sectioned Infolists, but it does not yet have a shared main-and-supporting enterprise detail builder.
- BaselineSnapshot already uses a presenter-driven, sectioned view, making it the strongest reference for the standard.
- BackupSet and EntraGroup still expose flatter view-page structures, and OperationRun relies on a separate tenantless viewer that reuses `OperationRunResource::infolist()`.
- The existing test suite already covers baseline snapshot rendering, operation-run Livewire behavior, related-navigation helpers, and action-surface guards, so the new standard can extend proven patterns instead of inventing a new testing approach.

## Phase 1 — Design & Contracts (DONE)

Outputs:
- `specs/133-detail-page-template/data-model.md`
- `specs/133-detail-page-template/contracts/enterprise-detail-pages.openapi.yaml`
- `specs/133-detail-page-template/quickstart.md`

Design highlights:
- Define a shared enterprise detail-page read model with explicit header, main sections, supporting cards, related context, technical detail, and empty-state handling.
- Reuse existing `BadgeRenderer`, `RelatedNavigationResolver`, and page-specific presenters instead of introducing duplicate status or navigation logic.
- Apply the shared shell first to OperationRun as the operational reference implementation, then BaselineSnapshot, BackupSet, and EntraGroup.
- Keep technical metadata present but secondary, and keep domain-specific sections inside the shared structural shell.

## Phase 1 — Agent Context Update (DONE)

Run:
- `.specify/scripts/bash/update-agent-context.sh copilot`

## Phase 2 — Implementation Outline (tasks created in `/speckit.tasks`)

### Step 1 — Introduce the shared enterprise detail composition layer

Goal: implement FR-133-01 through FR-133-05, FR-133-08, FR-133-09, FR-133-12, and FR-133-13.

Changes:
- Add a shared read model and builder contract for enterprise detail pages under `app/Support/Ui/EnterpriseDetail`.
- Add shared presentation partials or builder methods for summary header, supporting cards, related context, empty states, and technical-detail treatment.
- Define a reusable section taxonomy and reading-order contract that target pages can compose explicitly.

Tests:
- Add unit coverage for page composition, section visibility, technical-detail demotion, and empty-state fallback behavior.

### Step 2 — Refactor OperationRun detail as the first reference implementation

Goal: implement FR-133-02 through FR-133-11 and FR-133-18 for the workspace-context run detail surface.

Changes:
- Refactor `TenantlessOperationRunViewer` and `OperationRunResource::infolist()` around the shared enterprise detail shell.
- Elevate run identity, outcome, target scope, and quick actions into the summary or supporting regions.
- Move failure and technical payload detail behind secondary sections while preserving existing contextual actions and Ops-UX rules.

Tests:
- Extend or add Livewire feature tests for summary ordering, related context, degraded target-scope states, and preserved contextual actions.

### Step 3 — Refactor BaselineSnapshot detail onto the shared shell

Goal: implement FR-133-15 and reinforce FR-133-06, FR-133-07, and FR-133-11.

Changes:
- Adapt `BaselineSnapshotPresenter` and `ViewBaselineSnapshot` to emit the shared page model.
- Keep snapshot capture identity, fidelity, coverage, and governance context in the primary reading path.
- Preserve the current technical-detail section as a collapsed or secondary region inside the shared shell.

Tests:
- Reuse and extend existing BaselineSnapshot feature tests to assert summary-first structure, degraded-state handling, and related-context placement.

### Step 4 — Refactor BackupSet detail onto the shared shell

Goal: implement FR-133-16 and reinforce FR-133-06 through FR-133-10.

Changes:
- Replace the current flat BackupSet infolist with structured lifecycle, scope, related-operations, and technical-detail sections.
- Keep existing mutation actions grouped and confirmation-gated where already required.
- Introduce a clearer supporting region for status, timestamps, retention or scope summary, and recent operational context.

Tests:
- Add feature coverage for summary-first rendering, related-context visibility, action placement, and low-data empty states.

### Step 5 — Refactor EntraGroup detail onto the shared shell

Goal: implement FR-133-17 and reinforce FR-133-07, FR-133-08, and FR-133-11.

Changes:
- Replace the current two-section group view with a structured identity summary, classification, governance relevance, related context, and secondary provider detail treatment.
- Keep raw provider arrays or low-signal metadata in a clearly secondary technical section.

Tests:
- Add feature coverage for identity-first rendering, empty related-context behavior, and tenant-scope authorization semantics on the detail page.

### Step 6 — Add cross-target regression protection and polish

Goal: implement FR-133-14, FR-133-19, FR-133-20, and FR-133-21.

Changes:
- Add cross-target regression checks proving technical detail never renders above summary content, related context remains structured, and pages do not regress into flat schema-order field walls.
- Review labels, action placement, and empty-state language against UI-NAMING-001, BADGE-001, and UX-001.

Tests:
- Add one cross-target feature regression test and any needed guard updates for the changed action surfaces.
- Run focused Sail-based Pest coverage for the four aligned pages plus relevant unit tests and existing guards.

## Constitution Check (Post-Design)

Re-check result: PASS.

- Livewire v4.0+ compliance: preserved because every aligned screen remains inside the existing Filament v5 / Livewire v4 stack.
- Provider registration location: unchanged; existing panel providers remain registered in `bootstrap/providers.php`.
- Globally searchable resources: BaselineSnapshot is globally search disabled, BackupSet has a view page, EntraGroup has a view page, and OperationRun is globally search disabled.
- Destructive actions: no new destructive actions are introduced by the template; any retained destructive actions on touched screens continue to require confirmation and existing authorization.
- Asset strategy: no new heavy assets are planned; existing Tailwind and Filament view composition is sufficient, and deploy-time `php artisan filament:assets` remains unchanged.
- Testing plan: add or update focused Pest feature tests for each target page’s summary-first structure, related-context rendering, degraded-state handling, and action placement, plus unit coverage for the shared composition layer and existing action-surface guards where needed.