TenantAtlas/specs/170-system-operations-surface-alignment/plan.md

Implementation Plan: System Operations Surface Alignment

Branch: 170-system-operations-surface-alignment | Date: 2026-03-30 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/170-system-operations-surface-alignment/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/170-system-operations-surface-alignment/spec.md

Summary

Align the system-panel Operations, Failed operations, and Stuck operations pages to their declared ReadOnlyRegistryReport surface semantics by removing inline triage from the list rows, preserving full-row navigation to the canonical system operation detail page, standardizing visible naming to Operations / Operation, and adding the required list CTA and detail return-path behavior while keeping retry/cancel/mark-investigated ownership on the existing ViewRun page. The implementation stays narrow: no schema, new capability, or service-model changes; only Filament page behavior, visible operator copy, and the associated Pest/Livewire guard coverage are updated.

Technical Context

Language/Version: PHP 8.4, Laravel 12, Livewire v4, Filament v5
Primary Dependencies: laravel/framework, filament/filament, livewire/livewire, pestphp/pest
Storage: PostgreSQL with existing operation_runs and audit_logs tables; no schema changes
Testing: Pest feature tests with Livewire component assertions, executed through Laravel Sail
Target Platform: Laravel web application running in Sail locally and containerized Linux environments in staging/production
Project Type: Laravel monolith with Filament panels
Performance Goals: Preserve current DB-only list rendering, eager loading of tenant and workspace, and existing pagination/sort behavior with no extra remote calls
Constraints: Platform plane only; no new pages/capabilities/persistence; visible naming must align to Operations / Operation; destructive triage stays confirmation-gated; existing queued-toast and audit behavior must remain intact
Scale/Scope: Four existing system-panel pages, one existing detail Blade view, one existing triage service, and the focused feature/guard tests that encode current row-action behavior

Constitution Check

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

• PASS Inventory-first / snapshots-second: the feature does not change inventory, backups, or snapshot truth.
• PASS Read/write separation: no new writes are introduced; existing retry/cancel/mark-investigated flows remain explicit operator actions with confirmation where required.
• PASS Graph contract path: no Microsoft Graph call path is touched.
• PASS Deterministic capabilities: existing PlatformCapabilities::OPERATIONS_VIEW and PlatformCapabilities::OPERATIONS_MANAGE remain the canonical gates.
• PASS RBAC-UX plane separation: the slice is limited to /system surfaces and existing platform guard semantics.
• PASS Destructive confirmation standard: cancel remains ->requiresConfirmation() on the detail header.
• PASS Ops-UX 3-surface feedback: retry continues to use OperationUxPresenter::queuedToast(...); cancel and mark-investigated remain local terminal confirmations without adding queued/running notifications.
• PASS Ops lifecycle ownership: status/outcome mutation continues to flow through OperationRunService inside OperationRunTriageService; no new lifecycle path is introduced.
• PASS Proportionality / bloat: the feature removes duplicated interaction semantics and adds no new persistence, abstraction, state family, or taxonomy.
• PASS Badge semantics: list/detail badge rendering stays on the shared badge catalog and renderer.
• PASS Filament-native UI: the change stays inside existing Filament pages, row navigation, header actions, and confirmations.
• PASS UI surface taxonomy: Runs, Failures, and Stuck remain ReadOnlyRegistryReport; ViewRun remains the detail-first operational surface.
• PASS UI inspect model: each list will expose exactly one primary inspect model, recordUrl() row click.
• PASS UI action hierarchy: registry lists will have no inline triage; detail header remains the single triage owner.
• PASS UI naming scope: the changed system surfaces standardize visible copy to Operations / Operation while keeping internal route stability explicit.
• PASS Empty-state CTA rule: each changed list surface will define exactly one page-appropriate CTA and matching header action.
• PASS Placeholder/empty-group ban: no empty groups are introduced; bulk actions remain absent because there is no real bulk use case.
• PASS OPSURF page contract: the governing spec already defines persona, operator question, default truth, mutation scope, and dangerous actions.
• PASS Testing truth: implementation will update behavior guards, not just declarations.

Project Structure

Documentation (this feature)

specs/170-system-operations-surface-alignment/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── system-ops-surface-contract.yaml
└── tasks.md

Source Code (repository root)

app/
├── Filament/
│   └── System/
│       └── Pages/
│           └── Ops/
│               ├── Runs.php
│               ├── Failures.php
│               ├── Stuck.php
│               └── ViewRun.php
├── Services/
│   └── SystemConsole/
│       └── OperationRunTriageService.php
├── resources/
│   └── views/
│       └── filament/
│           └── system/
│               └── pages/
│                   └── ops/
│                       └── view-run.blade.php
└── Support/
    └── System/
        └── SystemOperationRunLinks.php

tests/
└── Feature/
    ├── Guards/
    │   └── ActionSurfaceContractTest.php
    └── System/
        └── Spec114/
            ├── OpsTriageActionsTest.php
            ├── OpsFailuresViewTest.php
            └── OpsStuckViewTest.php

Structure Decision: This is a single Laravel application. The implementation is confined to existing system-panel Filament pages and existing Pest feature/guard tests. No new application layer or directory is needed.

Complexity Tracking

No constitution waiver is expected. This slice reduces surface complexity instead of introducing a new layer.

Violation	Why Needed	Simpler Alternative Rejected Because
None	Not applicable	Not applicable

Proportionality Review

• Current operator problem: the three system list pages are declared as read-only registry surfaces but still expose direct triage actions, leave empty-state navigation underdefined, and continue to present Runs as a competing visible noun beside the canonical Operations vocabulary.
• Existing structure is insufficient because: the current hybrid model forces operators to choose between acting in-row and opening the richer detail page, while the constitution requires one primary inspect model, stable nouns, and explicit CTA behavior for changed list surfaces.
• Narrowest correct implementation: remove list row triage actions, keep recordUrl() row-click navigation, standardize visible copy to Operations / Operation, add one clear list CTA per changed surface, add a Show all operations return path on the detail page, and update the existing tests to assert the aligned behavior.
• Ownership cost created: low. The change requires focused updates to Filament page classes and the behavior guards that currently encode list-level triage.
• Alternative intentionally rejected: reclassifying the list pages as queue/review surfaces or adding new exception types was rejected because these pages are scan-first registries, not context-preserving decision queues.
• Release truth: current-release truth. The canonical detail page and triage service already exist today; the feature removes duplication rather than preparing speculative future structure.

Post-Design Constitution Re-check

• PASS UI-CONST-001 / UI-SURF-001: the artifacts keep list pages in the registry class and the detail page as the triage owner.
• PASS UI-HARD-001: the target design leaves each system list with exactly one primary inspect model and zero inline destructive actions.
• PASS UI-EX-001: no new exception type or exemption is needed for this slice.
• PASS OPSURF-001: list pages stay scan-first, while the detail page remains the context-rich operational surface.
• PASS RBAC-UX-001 to RBAC-UX-005: view/manage separation, server-side enforcement, and destructive confirmation rules remain unchanged.
• PASS UI-NAMING-001: visible system-surface nomenclature now aligns to Operations / Operation.
• PASS Empty-state CTA requirement: the design now defines a primary CTA for each changed list surface and a return path on the detail page.
• PASS BLOAT-001: no new persistence, abstraction, state family, or taxonomy was introduced during design.
• PASS Filament v5 / Livewire v4 guardrails: the plan keeps changes inside existing Filament pages and does not require provider or asset registration changes.