ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
11c73abd1d
TenantAtlas/.specify/templates/spec-template.md
ahmido 11c73abd1d 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: #99
2026-02-08 12:54:33 +00:00

6.8 KiB
Raw Blame History

Feature Specification: [FEATURE NAME]

Feature Branch: [###-feature-name]
Created: [DATE]
Status: Draft
Input: User description: "$ARGUMENTS"

User Scenarios & Testing (mandatory)

User Story 1 - [Brief Title] (Priority: P1)

[Describe this user journey in plain language]

Why this priority: [Explain the value and why it has this priority level]

Independent Test: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]

Acceptance Scenarios:

  1. Given [initial state], When [action], Then [expected outcome]
  2. Given [initial state], When [action], Then [expected outcome]

User Story 2 - [Brief Title] (Priority: P2)

[Describe this user journey in plain language]

Why this priority: [Explain the value and why it has this priority level]

Independent Test: [Describe how this can be tested independently]

Acceptance Scenarios:

  1. Given [initial state], When [action], Then [expected outcome]

User Story 3 - [Brief Title] (Priority: P3)

[Describe this user journey in plain language]

Why this priority: [Explain the value and why it has this priority level]

Independent Test: [Describe how this can be tested independently]

Acceptance Scenarios:

  1. Given [initial state], When [action], Then [expected outcome]

[Add more user stories as needed, each with an assigned priority]

Edge Cases

  • What happens when [boundary condition]?
  • How does system handle [error scenario]?

Requirements (mandatory)

Constitution alignment (required): If this feature introduces any Microsoft Graph calls, any write/change behavior, or any long-running/queued/scheduled work, the spec MUST describe contract registry updates, safety gates (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 (RBAC-UX): If this feature introduces or changes authorization behavior, the spec MUST:

  • state which authorization plane(s) are involved (tenant /admin/t/{tenant} vs platform /system),
  • ensure any cross-plane access is deny-as-not-found (404),
  • explicitly define 404 vs 403 semantics:
    • non-member / not entitled to tenant scope → 404 (deny-as-not-found)
    • member but missing capability → 403
  • describe how authorization is enforced server-side (Gates/Policies) for every mutation/operation-start/credential change,
  • reference the canonical capability registry (no raw capability strings; no role-string checks in feature code),
  • ensure global search is tenant-scoped and non-member-safe (no hints; inaccessible results treated as 404 semantics),
  • ensure destructive-like actions require confirmation (->requiresConfirmation()),
  • include at least one positive and one negative authorization test, and note any RBAC regression tests added/updated.

Constitution alignment (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP (e.g., token exchange) on /auth/* endpoints without an OperationRun. This MUST NOT be used for Monitoring/Operations pages.

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.

Functional Requirements

  • FR-001: System MUST [specific capability, e.g., "allow users to create accounts"]
  • FR-002: System MUST [specific capability, e.g., "validate email addresses"]
  • FR-003: Users MUST be able to [key interaction, e.g., "reset their password"]
  • FR-004: System MUST [data requirement, e.g., "persist user preferences"]
  • FR-005: System MUST [behavior, e.g., "log all security events"]

Example of marking unclear 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]
  • [Entity 2]: [What it represents, relationships to other entities]

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
  • SC-002: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
  • SC-003: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
  • SC-004: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]