TenantAtlas/specs/055-ops-ux-rollout/plan.md

Implementation Plan: Ops-UX Constitution Rollout (v1.3.0 Alignment) (055)

Branch: 055-ops-ux-rollout | Date: 2026-01-18 | Spec: specs/055-ops-ux-rollout/spec.md Input: Feature specification from specs/055-ops-ux-rollout/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

Standardize all operation feedback across the app to the Operations UX Constitution (v1.3.0):

• Three surfaces only (queued toast, progress widget for active runs, terminal DB notification for initiator).
• Centralized operation labels via an OperationCatalog.
• Canonical “View run” navigation to Monitoring → Operations → Run Detail.
• Safe, structured summaries sourced only from operation_runs.summary_counts (JSONB), using a single whitelist and numeric-only values.

Primary deliverables are shared presenters/normalizers + regression guards (Pest) that prevent drift.

Technical Context

Language/Version: PHP 8.4.15 (Laravel 12)
Primary Dependencies: Filament v4, Livewire v3
Storage: PostgreSQL (JSONB for operation_runs.summary_counts)
Testing: Pest v4 (Laravel test runner), PHPUnit 12 (via Pest)
Target Platform: Docker/Sail for local dev, container-based deploy (Dokploy)
Project Type: Laravel web application (monolith)
Performance Goals: Not performance-driven; UX consistency and guardrails are primary
Constraints:

• Calm polling rules (no modal polling; pause when tab hidden; stop on terminal)
• No new Graph calls introduced by this feature
• No schema refactor required for rollout; normalize for presentation Scale/Scope: Repo-wide UX migration impacting multiple producers and Monitoring UI

Constitution Check

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

• Inventory-first: N/A (this feature is a UX standardization on existing run records)
• Read/write separation: No new writes; changes are UX/presentation + safe sanitization + tests
• Graph contract path: No Graph calls introduced
• Deterministic capabilities: N/A
• Tenant isolation: All queried runs are tenant-scoped; notifications are initiator-only
• Operations UX (unified system): This feature enforces the three-surface model and canonical navigation
• Automation: N/A (no new scheduling/locks added)
• Data minimization: Summary and failure messages are sanitized; summaries are numeric-only

Gate status: PASS (no violations required)

Post-design re-check: PASS (design artifacts align with Ops-UX three-surface model, DB source-of-truth, canonical navigation, and safe summaries)

Project Structure

Documentation (this feature)

specs/055-ops-ux-rollout/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── ux-contracts.md
└── tasks.md

Source Code (repository root)

app/
├── Filament/
├── Livewire/
├── Models/
├── Notifications/
├── Providers/
├── Services/
└── Support/

resources/
└── views/

routes/
└── web.php

tests/
├── Feature/
└── Unit/

Structure Decision: Laravel web application (monolith) with Filament admin UI in app/Filament/ and Pest tests in tests/.

Phase Outputs

Phase 0 — Research

• specs/055-ops-ux-rollout/research.md

Phase 1 — Design & Contracts

• specs/055-ops-ux-rollout/data-model.md
• specs/055-ops-ux-rollout/contracts/ux-contracts.md
• specs/055-ops-ux-rollout/quickstart.md

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]