111 lines
3.9 KiB
Markdown
111 lines
3.9 KiB
Markdown
# 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] |
|