From 11c73abd1d7c52116da16ea0914458084c108014 Mon Sep 17 00:00:00 2001
From: ahmido <ad88cgn@gmail.com>
Date: Sun, 8 Feb 2026 12:54:33 +0000
Subject: [PATCH] docs: Filament Action Surface Contract (constitution +
 templates) (#99)

Adds the non-negotiable Filament UI Action Surface Contract to the project constitution (v1.7.0) and propagates required gates into Spec Kit templates.

Changes:
- .specify/memory/constitution.md: new contract section + version bump + Sync Impact Report update
- .specify/templates/spec-template.md: adds mandatory UI Action Matrix section for Filament changes
- .specify/templates/plan-template.md: adds contract checks to Constitution Check gate
- .specify/templates/tasks-template.md: adds task/CI enforcement requirements for Filament action surfaces

Notes:
- .specify/templates/commands/ does not exist in this repo, so no command templates were updated.

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@MacBookPro.fritz.box>
Reviewed-on: https://git.cloudarix.de/ahmido/TenantAtlas/pulls/99
---
 .specify/memory/constitution.md      | 36 +++++++++++++++++++++++-----
 .specify/templates/plan-template.md  |  1 +
 .specify/templates/spec-template.md  | 15 ++++++++++++
 .specify/templates/tasks-template.md |  8 +++++++
 4 files changed, 54 insertions(+), 6 deletions(-)

diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index 14ca699..9c087ed 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,13 +1,12 @@
 <!--
 Sync Impact Report
 
-- Version change: 1.5.0 → 1.6.0
+- Version change: 1.6.0 → 1.7.0
 - Modified principles:
-  - Tenant Isolation is Non-negotiable (clarified 404 vs 403 semantics)
-  - RBAC guidance consolidated (RBAC model rules merged into RBAC-UX)
+  - RBAC & UI Enforcement Standards (RBAC-UX) (added Filament action-surface contract gate)
 - Added sections:
-  - RBAC & UI Enforcement Standards (RBAC-UX)
-- Removed sections: None (RBAC-001..009 content consolidated into RBAC-UX)
+  - Filament UI — Action Surface Contract (NON-NEGOTIABLE)
+- Removed sections: None
 - Templates requiring updates:
   - ✅ .specify/templates/plan-template.md
   - ✅ .specify/templates/spec-template.md
@@ -139,6 +138,31 @@ ### Operations / Run Observability Standard
 - Scheduled/queued operations MUST use locks + idempotency (no duplicates).
 - Graph throttling and transient failures MUST be handled with backoff + jitter (e.g., 429/503).
 
+### Filament UI — Action Surface Contract (NON-NEGOTIABLE)
+
+For every new or modified Filament Resource / RelationManager / Page:
+
+Required surfaces
+- List/Table MUST define: Header Actions, Row Actions, Bulk Actions, and Empty-State CTA(s).
+- View/Detail MUST define Header Actions (Edit + “More” group when applicable).
+- Create/Edit MUST provide consistent Save/Cancel UX.
+
+Grouping & safety
+- Max 2 visible Row Actions (typically View/Edit). Everything else MUST be in an ActionGroup “More”.
+- Bulk actions MUST be grouped via BulkActionGroup.
+- Destructive actions MUST NOT be primary and MUST require confirmation; typed confirmation MAY be required for large/bulk changes.
+- Relevant mutations MUST write an audit log entry.
+
+RBAC enforcement
+- Non-member access MUST abort(404) and MUST NOT leak existence.
+- Member without capability: UI visible but disabled with tooltip; server-side MUST abort(403).
+- Central enforcement helpers (tenant/workspace UI enforcement) MUST be used for gating.
+
+Spec / DoD gates
+- Every spec MUST include a “UI Action Matrix”.
+- A change is not “Done” unless the Action Surface Contract is met OR an explicit exemption exists with documented reason.
+- CI MUST enforce the contract (test/command) and block merges on violations.
+
 ### Data Minimization & Safe Logging
 - Inventory MUST store only metadata + whitelisted `meta_jsonb`.
 - Payload-heavy content belongs in immutable snapshots/backup storage, not Inventory.
@@ -174,4 +198,4 @@ ### Versioning Policy (SemVer)
 - **MINOR**: new principle/section or materially expanded guidance.
 - **MAJOR**: removing/redefining principles in a backward-incompatible way.
 
-**Version**: 1.6.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-01-28
+**Version**: 1.7.0 | **Ratified**: 2026-01-03 | **Last Amended**: 2026-02-08
diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md
index 3a9e510..e3207c0 100644
--- a/.specify/templates/plan-template.md
+++ b/.specify/templates/plan-template.md
@@ -43,6 +43,7 @@ ## 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, 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
 
 ## Project Structure
 
diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md
index 1ae7c69..3c728bd 100644
--- a/.specify/templates/spec-template.md
+++ b/.specify/templates/spec-template.md
@@ -100,6 +100,10 @@ ## 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 (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.
+
 <!--
   ACTION REQUIRED: The content in this section represents placeholders.
   Fill them out with the right functional requirements.
@@ -118,6 +122,17 @@ ### Functional Requirements
 - **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
 - **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
 
+## UI Action Matrix *(mandatory when Filament is changed)*
+
+If this feature adds/modifies any Filament Resource / RelationManager / Page, fill out the matrix below.
+
+For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?),
+RBAC gating (capability + enforcement helper), and whether the mutation writes an audit log.
+
+| Surface | Location | Header Actions | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
+|---|---|---|---|---|---|---|---|---|---|
+| Resource/Page/RM | e.g. app/Filament/... |  |  |  |  |  |  |  |  |
+
 ### Key Entities *(include if feature involves data)*
 
 - **[Entity 1]**: [What it represents, key attributes without implementation]
diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md
index 63d9c10..bc0e683 100644
--- a/.specify/templates/tasks-template.md
+++ b/.specify/templates/tasks-template.md
@@ -24,6 +24,14 @@ # 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.
+**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),
+- enforcing the “max 2 visible row actions; everything else in More ActionGroup” rule,
+- grouping bulk actions via BulkActionGroup,
+- adding confirmations for destructive actions (and typed confirmation where required by scale),
+- adding `AuditLog` entries for relevant mutations,
+- adding/updated tests that enforce the contract and block merge on violations, OR documenting an explicit exemption with rationale.
 **Badges**: If this feature changes status-like badge semantics, tasks MUST use `BadgeCatalog` / `BadgeRenderer` (BADGE-001),
 avoid ad-hoc mappings in Filament, and include mapping tests for any new/changed values.