# 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)

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

### Source Code (repository root)

```text
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] |