merge: session branch ui naming constitution

.specify/memory/constitution.md

@@ -1,15 +1,11 @@
 <!--
 Sync Impact Report
 
-- Version change: 1.9.0 → 1.10.0
+- Version change: 1.10.0 → 1.11.0
 - Modified principles:
-  - Operations / Run Observability Standard (clarified as non-negotiable 3-surface contract; added lifecycle, summary, guards, system-run policy)
+  - None
 - Added sections:
-  - Operations UX — 3-Surface Feedback (OPS-UX-055) (NON-NEGOTIABLE)
+  - Operator-facing UI Naming Standards (UI-NAMING-001)
-  - 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
@@ -17,7 +13,7 @@
   - ✅ .specify/templates/tasks-template.md
   - N/A: .specify/templates/commands/ (directory not present in this repo)
 - Follow-up TODOs:
-  - Add CI regression guards for “no naked forms” + “view must use infolist” (heuristic scan) in test suite.
+  - None.
 -->
 
 # TenantPilot Constitution
@@ -298,6 +294,44 @@ ### Filament UI — Layout & Information Architecture Standards (UX-001)
 - New resources/pages SHOULD use shared layout builders (e.g., `MainAsideForm`, `MainAsideInfolist`, `StandardTableDefaults`) to keep screens consistent.
 - A change is not “Done” unless UX-001 is satisfied OR an explicit exemption exists with a documented rationale in the spec/PR.
 
+### Operator-facing UI Naming Standards (UI-NAMING-001)
+
+Goal: operator-facing actions, run labels, notifications, audit prose, and related UI copy MUST use consistent,
+enterprise-grade product language.
+
+Naming model
+- Operator-facing copy MUST distinguish four layers: Scope, Source/Domain, Operation, and Target Object.
+- Scope terms (`Workspace`, `Tenant`) describe execution context and MUST NOT be used as the primary action label unless they are the actual target object.
+- Source/Domain terms (`Intune`, `Entra`, `Teams`, future providers) are secondary and MUST NOT lead the primary label unless the current screen presents competing sources that need explicit disambiguation.
+
+Primary action labels
+- Primary buttons, header actions, and menu actions MUST use `Verb + Object`.
+- Preferred examples: `Sync policies`, `Sync groups`, `Capture baseline`, `Compare baseline`, `Restore policy`, `Run review`, `Export review pack`.
+- Forbidden examples: `Sync from tenant`, `Backup tenant`, `Compare tenant`, `Sync from Intune`, `Run tenant sync now`, `Start inventory refresh from provider`.
+
+Domain vocabulary
+- Operator-facing copy MUST prefer product-domain objects such as `policies`, `groups`, `baseline`, `findings`, `review pack`, `alerts`, and `operations`.
+- Primary operator-facing copy MUST NOT use implementation-first terms such as `provider`, `gateway`, `resolver`, `collector`, `contract registry`, or `job dispatch`.
+- Source/domain details MAY appear in modal descriptions, helper text, run metadata, audit metadata, and notifications when needed for precision.
+
+Run, notification, and audit semantics
+- Visible run titles MUST use the same domain vocabulary as the initiating action and SHOULD be concise noun phrases such as `Policy sync`, `Baseline capture`, `Baseline compare`, `Policy restore`, and `Tenant review`.
+- Notifications MUST use either `{Object} {state}` or `{Operation} {result}` and remain short, e.g. `Policy sync queued`, `Policy sync completed`, `Policy sync failed`, `Baseline compare detected drift`.
+- Audit prose MUST use the same operator-facing language, e.g. `{actor} queued policy sync`, `{actor} captured baseline`, `{actor} reopened finding`.
+- The same user-visible action MUST keep the same domain vocabulary across button labels, modal titles, run titles, notifications, and audit prose.
+
+Verb standard
+- Preferred verbs are `Sync`, `Capture`, `Compare`, `Restore`, `Review`, `Export`, `Open`, `Archive`, `Resolve`, `Reopen`, and `Assign`.
+- `Start`, `Execute`, `Trigger`, and `Perform` SHOULD be avoided for operator-facing copy unless there is a deliberate domain reason.
+- `Run` MAY be used only when the object is itself run-like, such as `Run review` or `Run compare`; it MUST NOT be the generic fallback verb for all operations.
+
+Current binding decision
+- The Policies screen primary action MUST be `Sync policies`.
+- The Policies screen modal title MUST be `Sync policies`.
+- The Policies screen success toast MUST be `Policy sync queued`.
+- The visible run label for that action MUST be `Policy sync`.
+- The audit prose for that action MUST be `{actor} queued policy sync`.
+
 Spec Scope Fields (SCOPE-002)
 
 - Every feature spec MUST declare:
@@ -355,4 +389,4 @@ ### Versioning Policy (SemVer)
 - **MINOR**: new principle/section or materially expanded guidance.
 - **MAJOR**: removing/redefining principles in a backward-incompatible way.
 
-**Version**: 1.10.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-02-23
+**Version**: 1.11.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-03-10

.specify/templates/plan-template.md

@@ -49,7 +49,9 @@ ## Constitution Check
 - 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
-- Filament UI Action Surface Contract: for any new/modified Filament Resource/RelationManager/Page, define Header/Row/Bulk/Empty-State actions, ensure every List/Table has a record inspection affordance (prefer `recordUrl()` clickable rows; do not render a lone View row action), keep max 2 visible row actions with the rest in “More”, group bulk actions, require confirmations for destructive actions (typed confirmation for large/bulk where applicable), write audit logs for mutations, enforce RBAC via central helpers (non-member 404, member missing capability 403), and ensure CI blocks merges if the contract is violated or not explicitly exempted- Filament UI UX-001 (Layout & IA): Create/Edit uses Main/Aside (3-col grid, Main=columnSpan(2), Aside=columnSpan(1)); all fields inside Sections/Cards (no naked inputs); View uses Infolists (not disabled edit forms); status badges use BADGE-001; empty states have specific title + explanation + 1 CTA; max 1 primary + 1 secondary header action; tables provide search/sort/filters for core dimensions; shared layout builders preferred for consistency
+- UI naming (UI-NAMING-001): operator-facing labels use `Verb + Object`; scope (`Workspace`, `Tenant`) is never the primary action label; source/domain is secondary unless disambiguation is required; runs/toasts/audit prose use the same domain vocabulary; implementation-first terms do not appear in primary operator UI
+- Filament UI Action Surface Contract: for any new/modified Filament Resource/RelationManager/Page, define Header/Row/Bulk/Empty-State actions, ensure every List/Table has a record inspection affordance (prefer `recordUrl()` clickable rows; do not render a lone View row action), keep max 2 visible row actions with the rest in “More”, group bulk actions, require confirmations for destructive actions (typed confirmation for large/bulk where applicable), write audit logs for mutations, enforce RBAC via central helpers (non-member 404, member missing capability 403), and ensure CI blocks merges if the contract is violated or not explicitly exempted
+- Filament UI UX-001 (Layout & IA): Create/Edit uses Main/Aside (3-col grid, Main=columnSpan(2), Aside=columnSpan(1)); all fields inside Sections/Cards (no naked inputs); View uses Infolists (not disabled edit forms); status badges use BADGE-001; empty states have specific title + explanation + 1 CTA; max 1 primary + 1 secondary header action; tables provide search/sort/filters for core dimensions; shared layout builders preferred for consistency
 ## Project Structure
 
 ### Documentation (this feature)

.specify/templates/spec-template.md

@@ -119,6 +119,14 @@ ## Requirements *(mandatory)*
 **Constitution alignment (BADGE-001):** If this feature changes status-like badges (status/outcome/severity/risk/availability/boolean),
 the spec MUST describe how badge semantics stay centralized (no ad-hoc mappings) and which tests cover any new/changed values.
 
+**Constitution alignment (UI-NAMING-001):** If this feature adds or changes operator-facing buttons, header actions, run titles,
+notifications, audit prose, or related helper copy, the spec MUST describe:
+- the target object,
+- the operator verb,
+- whether source/domain disambiguation is actually needed,
+- how the same domain vocabulary is preserved across button labels, modal titles, run titles, notifications, and audit prose,
+- and how implementation-first terms are kept out of primary operator-facing labels.
+
 **Constitution alignment (Filament Action Surfaces):** If this feature adds or modifies any Filament Resource / RelationManager / Page,
 the spec MUST include a “UI Action Matrix” (see below) and explicitly state whether the Action Surface Contract is satisfied.
 If the contract is not satisfied, the spec MUST include an explicit exemption with rationale.

.specify/templates/tasks-template.md

@@ -32,6 +32,12 @@ # Tasks: [FEATURE NAME]
 - destructive-like actions use `->requiresConfirmation()` (authorization still server-side),
 - cross-plane deny-as-not-found (404) checks where applicable,
 - at least one positive + one negative authorization test.
+**UI Naming**: If this feature adds or changes operator-facing actions, run titles, notifications, audit prose, or helper copy, tasks MUST include:
+- aligning primary action labels to `Verb + Object`,
+- keeping scope terms (`Workspace`, `Tenant`) out of primary action labels unless they are the actual target object,
+- using source/domain terms only where same-screen disambiguation is required,
+- aligning button labels, modal titles, run titles, notifications, and audit prose to the same domain vocabulary,
+- removing implementation-first wording from primary operator-facing copy.
 **Filament UI Action Surfaces**: If this feature adds/modifies any Filament Resource / RelationManager / Page, tasks MUST include:
 - filling the spec’s “UI Action Matrix” for all changed surfaces,
 - implementing required action surfaces (header/row/bulk/empty-state CTA for lists; header actions for view; consistent save/cancel on create/edit),