ahmido
11c73abd1d
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
154 lines
6.8 KiB
Markdown
154 lines
6.8 KiB
Markdown
# Feature Specification: [FEATURE NAME]
|
|
|
|
**Feature Branch**: `[###-feature-name]`
|
|
**Created**: [DATE]
|
|
**Status**: Draft
|
|
**Input**: User description: "$ARGUMENTS"
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
<!--
|
|
IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
|
|
Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
|
|
you should still have a viable MVP (Minimum Viable Product) that delivers value.
|
|
|
|
Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
|
|
Think of each story as a standalone slice of functionality that can be:
|
|
- Developed independently
|
|
- Tested independently
|
|
- Deployed independently
|
|
- Demonstrated to users independently
|
|
-->
|
|
|
|
### 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
|
|
|
|
<!--
|
|
ACTION REQUIRED: The content in this section represents placeholders.
|
|
Fill them out with the right 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.
|
|
|
|
<!--
|
|
ACTION REQUIRED: The content in this section represents placeholders.
|
|
Fill them out with the right functional requirements.
|
|
-->
|
|
|
|
### 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)*
|
|
|
|
<!--
|
|
ACTION REQUIRED: Define measurable success criteria.
|
|
These must be technology-agnostic and measurable.
|
|
-->
|
|
|
|
### 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%"]
|