From 29112225b678c9abebf1a802b93dfd924143d6af Mon Sep 17 00:00:00 2001
From: Ahmed Darrazi <ahmed.darrazi@live.de>
Date: Mon, 23 Feb 2026 22:51:46 +0100
Subject: [PATCH] docs(constitution): codify Ops-UX non-negotiables (3-surface
 + lifecycle + guards)

---
 .specify/memory/constitution.md      | 78 ++++++++++++++++++++++++++--
 .specify/templates/plan-template.md  |  5 ++
 .specify/templates/spec-template.md  |  7 +++
 .specify/templates/tasks-template.md |  7 +++
 4 files changed, 93 insertions(+), 4 deletions(-)

diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index 3b66104..b8d5ecb 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,11 +1,15 @@
 <!--
 Sync Impact Report
 
-- Version change: 1.8.2 → 1.9.0
+- Version change: 1.9.0 → 1.10.0
 - Modified principles:
-  - Filament UI — Action Surface Contract (NON-NEGOTIABLE) (tightened UX requirements; added layout/view/empty-state rules)
+  - Operations / Run Observability Standard (clarified as non-negotiable 3-surface contract; added lifecycle, summary, guards, system-run policy)
 - Added sections:
-  - Filament UI — Layout & Information Architecture Standards (UX-001)
+  - Operations UX — 3-Surface Feedback (OPS-UX-055) (NON-NEGOTIABLE)
+  - OperationRun lifecycle is service-owned (OPS-UX-LC-001)
+  - Summary counts contract (OPS-UX-SUM-001)
+  - Ops-UX regression guards are mandatory (OPS-UX-GUARD-001)
+  - Scheduled/system runs (OPS-UX-SYS-001)
 - Removed sections: None
 - Templates requiring updates:
   - ✅ .specify/templates/plan-template.md
@@ -158,6 +162,72 @@ ### Operations / Run Observability Standard
 - Monitoring pages MUST be DB-only at render time (no external calls).
 - Start surfaces MUST NOT perform remote work inline; they only: authorize, create/reuse run (dedupe), enqueue work,
   confirm + “View run”.
+
+### Operations UX — 3-Surface Feedback (OPS-UX-055) (NON-NEGOTIABLE)
+
+If a feature creates/reuses `OperationRun`, it MUST use exactly three feedback surfaces — no others:
+
+1) Toast (intent only / queued-only)
+- A toast MAY be shown only when the run is accepted/queued (intent feedback).
+- The toast MUST use `OperationUxPresenter::queuedToast($operationType)->send()`.
+- Feature code MUST NOT craft ad-hoc operation toasts.
+- A dedicated dedupe message MUST use the presenter (e.g., `alreadyQueuedToast(...)`), not `Notification::make()`.
+
+2) Progress (active awareness only)
+- Live progress MUST exist only in:
+  - the global active-ops widget, and
+  - Monitoring → Operation Run Detail.
+- These surfaces MUST show only active runs (`queued|running`) and MUST never show terminal runs.
+- Determinate progress is allowed ONLY when `summary_counts.total` and `summary_counts.processed` are valid numeric values.
+- Determinate progress MUST be clamped to 0–100. Otherwise render indeterminate + elapsed time.
+- The widget MUST NOT show percentage text (optional `processed/total` is allowed).
+
+3) Terminal DB Notification (audit outcome only)
+- Each run MUST emit exactly one persistent terminal DB notification when it becomes terminal.
+- Delivery MUST be initiator-only (no tenant-wide fan-out).
+- Completion notifications MUST be `OperationRunCompleted` only.
+- Feature code MUST NOT send custom completion DB notifications for operations (no `sendToDatabase()` for completion/abort).
+
+Canonical navigation:
+- All “View run” links MUST use the canonical helper and MUST point to Monitoring → Operations → Run Detail.
+
+### OperationRun lifecycle is service-owned (OPS-UX-LC-001)
+
+Any change to `OperationRun.status` or `OperationRun.outcome` MUST go through `OperationRunService` (canonical transition method).
+This is the only allowed path because it enforces normalization, summary sanitization, idempotency, and terminal notification emission.
+
+Forbidden outside `OperationRunService`:
+- `$operationRun->update(['status' => ...])` / `$operationRun->update(['outcome' => ...])`
+- `$operationRun->status = ...` / `$operationRun->outcome = ...`
+- Query-based updates that transition `status`/`outcome`
+
+Allowed outside the service:
+- Updates to `context`, `message`, `reason_code` that do not change `status`/`outcome`.
+
+### Summary counts contract (OPS-UX-SUM-001)
+
+- `operation_runs.summary_counts` is the canonical metrics source for Ops-UX.
+- All keys MUST come from `OperationSummaryKeys::all()` (single source of truth).
+- Values MUST be flat numeric-only; no nested objects/arrays; no free-text.
+- Producers MUST NOT introduce new keys without:
+  1) updating `OperationSummaryKeys::all()`,
+  2) updating the spec canonical list,
+  3) adding/adjusting tests.
+
+### Ops-UX regression guards are mandatory (OPS-UX-GUARD-001)
+
+The repo MUST include automated guards (Pest) that fail CI if:
+- any direct `OperationRun` status/outcome transition occurs outside `OperationRunService`,
+- jobs emit DB notifications for operation completion/abort (`OperationRunCompleted` is the single terminal notification),
+- deprecated legacy operation notification classes are referenced again.
+
+These guards MUST fail with actionable output (file + snippet).
+
+### Scheduled/system runs (OPS-UX-SYS-001)
+
+- If a run has no initiator user, no terminal DB notification is emitted (initiator-only policy).
+- Outcomes remain auditable via Monitoring → Operations / Run Detail.
+- Any tenant-wide alerting MUST go through the Alerts system (not `OperationRun` notifications).
 - Active-run dedupe MUST be enforced at DB level (partial unique index/constraint for active states).
 - Failures MUST be stored as stable reason codes + sanitized messages; never persist secrets/tokens/PII/raw payload dumps
   in failures or notifications.
@@ -274,4 +344,4 @@ ### Versioning Policy (SemVer)
 - **MINOR**: new principle/section or materially expanded guidance.
 - **MAJOR**: removing/redefining principles in a backward-incompatible way.
 
-**Version**: 1.9.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-02-19
+**Version**: 1.10.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-02-23
diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md
index 17afc7a..9a0328d 100644
--- a/.specify/templates/plan-template.md
+++ b/.specify/templates/plan-template.md
@@ -41,6 +41,11 @@ ## Constitution Check
 - RBAC-UX: global search is tenant-scoped; non-members get no hints; inaccessible results are treated as not found (404 semantics)
 - Tenant isolation: all reads/writes tenant-scoped; cross-tenant views are explicit and access-checked
 - Run observability: long-running/remote/queued work creates/reuses `OperationRun`; start surfaces enqueue-only; Monitoring is DB-only; DB-only <2s actions may skip runs but security-relevant ones still audit-log; auth handshake exception OPS-EX-AUTH-001 allows synchronous outbound HTTP on `/auth/*` without `OperationRun`
+- Ops-UX 3-surface feedback: if `OperationRun` is used, feedback is exactly toast intent-only + progress surfaces + exactly-once terminal `OperationRunCompleted` (initiator-only); no queued/running DB notifications
+- Ops-UX lifecycle: `OperationRun.status` / `OperationRun.outcome` transitions are service-owned (only via `OperationRunService`); context-only updates allowed outside
+- Ops-UX summary counts: `summary_counts` keys come from `OperationSummaryKeys::all()` and values are flat numeric-only
+- Ops-UX guards: CI has regression guards that fail with actionable output (file + snippet) when these patterns regress
+- Ops-UX system runs: initiator-null runs emit no terminal DB notification; audit remains via Monitoring; tenant-wide alerting goes through Alerts (not OperationRun notifications)
 - Automation: queued/scheduled ops use locks + idempotency; handle 429/503 with backoff+jitter
 - Data minimization: Inventory stores metadata + whitelisted meta; logs contain no secrets/tokens
 - Badge semantics (BADGE-001): status-like badges use `BadgeCatalog` / `BadgeRenderer`; no ad-hoc mappings; new values include tests
diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md
index ce057d6..ecbf6fa 100644
--- a/.specify/templates/spec-template.md
+++ b/.specify/templates/spec-template.md
@@ -94,6 +94,13 @@ ## Requirements *(mandatory)*
 (preview/confirmation/audit), tenant isolation, run observability (`OperationRun` type/identity/visibility), and tests.
 If security-relevant DB-only actions intentionally skip `OperationRun`, the spec MUST describe `AuditLog` entries.
 
+**Constitution alignment (OPS-UX):** If this feature creates/reuses an `OperationRun`, the spec MUST:
+- explicitly state compliance with the Ops-UX 3-surface feedback contract (toast intent-only, progress surfaces, terminal DB notification),
+- state that `OperationRun.status` / `OperationRun.outcome` transitions are service-owned (only via `OperationRunService`),
+- describe how `summary_counts` keys/values comply with `OperationSummaryKeys::all()` and numeric-only rules,
+- clarify scheduled/system-run behavior (initiator null → no terminal DB notification; audit is via Monitoring),
+- list which regression guard tests are added/updated to keep these rules enforceable in CI.
+
 **Constitution alignment (RBAC-UX):** If this feature introduces or changes authorization behavior, the spec MUST:
 - state which authorization plane(s) are involved (tenant/admin `/admin` + tenant-context `/admin/t/{tenant}/...` vs platform `/system`),
 - ensure any cross-plane access is deny-as-not-found (404),
diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md
index 6fdcde6..c6d6220 100644
--- a/.specify/templates/tasks-template.md
+++ b/.specify/templates/tasks-template.md
@@ -14,6 +14,13 @@ # Tasks: [FEATURE NAME]
 If security-relevant DB-only actions skip `OperationRun`, include tasks for `AuditLog` entries (before/after + actor + tenant).
 Auth handshake exception (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP on `/auth/*` endpoints
 without an `OperationRun`.
+If this feature creates/reuses an `OperationRun`, tasks MUST also include:
+- enforcing the Ops-UX 3-surface feedback contract (toast intent-only via `OperationUxPresenter`, progress only in widget + run detail, terminal notification is `OperationRunCompleted` exactly-once, initiator-only),
+- ensuring no queued/running DB notifications exist anywhere for operations (no `sendToDatabase()` for queued/running/completion/abort in feature code),
+- ensuring `OperationRun.status` / `OperationRun.outcome` transitions happen only via `OperationRunService`,
+- ensuring `summary_counts` keys come from `OperationSummaryKeys::all()` and values are flat numeric-only,
+- adding/updating Ops-UX regression guards (Pest) that fail CI with actionable output (file + snippet) when these patterns regress,
+- clarifying scheduled/system-run behavior (initiator null → no terminal DB notification; audit via Monitoring; tenant-wide alerting via Alerts system).
 **RBAC**: If this feature introduces or changes authorization, tasks MUST include:
 - explicit Gate/Policy enforcement for all mutation endpoints/actions,
 - explicit 404 vs 403 semantics: