<!--
  Feature Spec template — paste this into the Gitea issue body (issue-only: this IS the spec;
  there is no committed spec.md). The .gitea/ISSUE_TEMPLATE/feature.md mirror gives the same
  structure with the right labels. Replace every <placeholder>. Delete this comment before submitting.
  EARS = Easy Approach to Requirements Syntax. Every requirement uses one of the five patterns
  shown in ## Requirements and carries a unique REQ-NNN id (three-digit, scoped to THIS feature).
  Use plain code-path references (not relative markdown links) — links don't resolve inside a Gitea issue.
-->

# <Feature title — match the Gitea issue: "As a <role> I want <capability> so <reason>">

## Context & Why

<Business motivation in 2–4 sentences: who needs this and why now.>

Constitution principles this feature depends on (see `.specify/constitution.md`):
- §<n> <principle name> — <why it applies>

Related: <links to prior issues / ADRs>.

## User Journey

<Plain-prose steps the user takes to get value, from the user's perspective — per COLLABORATING.md. Anything not in this journey is out of scope.>

## Requirements

> One requirement per line, each with a `REQ-NNN` id and one EARS pattern. Include the
> patterns the feature actually needs — do not force all five, but a mutating feature almost
> always needs at least one Event-driven and one Unwanted-behavior requirement.

- **REQ-001** (Ubiquitous) — The `<system component>` shall `<always-true behavior>`.
- **REQ-002** (Event-driven) — When `<trigger / endpoint receives X>`, the `<system component>` shall `<response>`.
- **REQ-003** (State-driven) — While `<system is in state X>`, the `<system component>` shall `<behavior>`.
- **REQ-004** (Optional-feature) — Where `<the caller has Permission.X / a feature flag is set>`, the `<system component>` shall `<behavior>`.
- **REQ-005** (Unwanted-behavior) — If `<undesired condition, e.g. caller is unauthenticated / input invalid>`, then the `<system component>` shall `<safe response, e.g. return 401 / ErrorCode.X>`.

## Acceptance Criteria

> One measurable criterion per REQ-NNN. Numbers, limits, status codes — never adjectives.

- **REQ-001** — <measurable, e.g. "the response always includes a non-null `id` (UUID)">.
- **REQ-002** — <measurable, e.g. "POST returns 201 and the persisted row within the same request">.
- **REQ-003** — <measurable>.
- **REQ-004** — <measurable, e.g. "a caller without Permission.X receives 403 with ErrorCode.FORBIDDEN">.
- **REQ-005** — <measurable, e.g. "an unauthenticated request receives 401 and nothing is persisted">.

## Out of Scope

- <Explicit boundary statement — the nearest tempting scope creep, named and excluded.>
- <…>

## API / Contract Stub

<Inline OpenAPI stub. Name the new/changed paths, methods, request/response shapes, status codes, and `@RequirePermission`. Use the `.specify/templates/api-contract-stub.md` skeleton as a writing aid.>

## Data Model Changes

<Entity/schema delta: new tables/columns, constraints, the next free Flyway `V<n>`, and the rollback note. Write "none" if not applicable.>

## Security Considerations

<STRIDE categories touched (Spoofing/Tampering/Repudiation/Information disclosure/DoS/Elevation). For AI-agent/tool features, also ASTRIDE. Include an inline STRIDE table (use `.specify/templates/threat-model.md`) if the feature has a non-trivial attack surface.>

## Open Questions

> Each item is a BLOCKER until resolved. Empty this list before implementation starts.

- [ ] <question> — owner: <name>
- [ ] <question> — owner: <name>

## Traceability

| REQ-ID | Task ID(s) | Test ID(s) | Status |
|---|---|---|---|
| REQ-001 | <T-1> | <test name> | Planned |
| REQ-002 | <T-2> | <test name> | Planned |

<After approval, add one committed row per REQ-NNN to `.specify/rtm.md` with this issue's number. Fill Task/Test IDs as work progresses.>

## Persona Review Results

| Persona | Status | Key Findings | Resolved |
|---|---|---|---|
| Requirements Engineer | PENDING | | |
| Developer | PENDING | | |
| Security | PENDING | | |
| DevOps | PENDING | | |
| UI/UX | PENDING | | |
| Architect | PENDING | | |
