refactor(sdd): make the feature spec issue-only (no committed spec.md)

The Gitea issue body is the single source of truth for a spec; the only per-feature artifact in git is the RTM row (REQ-ID -> issue # -> test). Drops per-feature spec.md/tasks.md/checklist files from the workflow (the _example stays as a template/reference). Updates the guide, ADR-041, AGENTS.md, CLAUDE.md, templates, the RTM (adds an Issue column), the implement/review-pr skills, and replaces the file-spec CI jobs with an rtm-check. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-13 12:14:32 +02:00
parent fa6677a7c5
commit c160ab3223
13 changed files with 178 additions and 202 deletions
--- a/.claude/skills/implement/SKILL.md
+++ b/.claude/skills/implement/SKILL.md
@@ -54,12 +54,11 @@ Mark each concern with its source: reviewer name + comment excerpt.

 Also read:
 - `CLAUDE.md` for project conventions
- **The feature's SDD artifacts**, if a spec exists for this issue: `.specify/features/<name>/spec.md`
-  (the `REQ-NNN` requirements + acceptance criteria), `tasks.md` (the red/green task list),
-  `api-contract.yaml` (the API shape), and `threat-model.md` (security obligations). If the
-  issue is a well-formed SDD spec but no `.specify/features/<name>/` directory exists yet,
-  create one from [the templates](../../../.specify/templates/) and mirror the spec into it.
- [`.specify/rtm.md`](../../../.specify/rtm.md) — note each `REQ-NNN`'s current Status
+- **The issue body — it IS the spec** (issue-only; there is no committed `spec.md`). Extract its
+  `REQ-NNN` requirements, acceptance criteria, API stub, data-model delta, and any inline
+  STRIDE/threat notes. These are your contract.
+- [`.specify/rtm.md`](../../../.specify/rtm.md) — note each `REQ-NNN`'s current Status (rows are
+  keyed by this issue number)
 - Any relevant existing source files mentioned in the issue/comments
 - The current branch state (`git status`, `git log --oneline -10`)

@@ -101,9 +100,9 @@ Wait for the user to answer before continuing.

 ## Phase 3 — Implementation Plan

-Once clarifications are resolved, present a numbered implementation plan as a task list. **If
-the spec has a `tasks.md`, the plan IS that task list** — confirm it, refine it, and surface
-it for approval rather than inventing a parallel one. Each item must be:
+Once clarifications are resolved, present a numbered implementation plan as a task list,
+**derived from the issue's `REQ-NNN` requirements** (one or more tasks per requirement, in
+red/green order). Each item must be:

 - A single atomic unit of work (one behavior, one file change, one migration)
 - Written as a sentence that implies the test name: "Tag detail page returns 404 when tag does not exist"
--- a/.claude/skills/review-pr/SKILL.md
+++ b/.claude/skills/review-pr/SKILL.md
@@ -8,7 +8,7 @@ description: Multi-persona SDD code review of a Gitea PR. Each persona pairs its
 You will perform a thorough multi-persona code review of the given PR and post each persona's
 findings as a **separate comment**. Under SDD, the review verifies the diff against two
 contracts: the project [constitution](../../../.specify/constitution.md) and the feature's
-spec (`spec.md` — every `REQ-NNN` must be implemented **and** covered by a test).
+spec (the linked **Gitea issue body** — every `REQ-NNN` must be implemented **and** covered by a test).

 ## Argument

@@ -22,9 +22,8 @@ Parse it to extract `owner`, `repo`, and `pull_number`.
 Read before reviewing:
 - [`.specify/constitution.md`](../../../.specify/constitution.md) — rules the code must obey (esp. §4 Do-Not-Touch)
 - [`.specify/AGENTS.md`](../../../.specify/AGENTS.md) — constraints
- The feature's spec, if the PR references one: `.specify/features/<name>/spec.md`, plus its
-  `api-contract.yaml`, `threat-model.md`, and `tasks.md`. Find the `REQ-NNN` ids it claims to
-  satisfy (from the PR description, `Closes #n`, or the spec's Traceability table).
+- The feature's spec — the **Gitea issue** the PR closes (`Closes #n`). Read its body for the
+  `REQ-NNN` requirements, acceptance criteria, inline API stub, and any STRIDE/threat notes.
 - [`.specify/rtm.md`](../../../.specify/rtm.md) — the requirement→test→status matrix

 ## Step 1 — Gather PR context
--- a/.gitea/ISSUE_TEMPLATE/feature.md
+++ b/.gitea/ISSUE_TEMPLATE/feature.md
@@ -9,10 +9,9 @@ assignees: []
 ---

 <!--
-  This is a Spec-Driven feature spec. Mirror it to .specify/features/<name>/spec.md once the
-  feature has a working name. Every requirement uses an EARS pattern + a REQ-NNN id.
-  Reference: .specify/templates/feature-spec.md and the worked example .specify/features/_example/.
-  Delete the placeholder hints as you fill each section.
+  This issue body IS the spec (issue-only — there is no committed spec.md). Every requirement
+  uses an EARS pattern + a REQ-NNN id. Reference: .specify/templates/feature-spec.md and the
+  worked example .specify/features/_example/. Delete the placeholder hints as you fill each section.
 -->

 ## Context & Why
@@ -46,7 +45,7 @@ assignees: []

 ## API / Contract Stub

-<Inline stub or link to .specify/features/<name>/api-contract.yaml. Name new paths/methods/status codes and the @RequirePermission on each mutating endpoint.>
+<Inline OpenAPI stub (use .specify/templates/api-contract-stub.md as a writing aid). Name new paths/methods/status codes and the @RequirePermission on each mutating endpoint.>

 ## Data Model Changes

--- a/.gitea/workflows/sdd-gate.yml
+++ b/.gitea/workflows/sdd-gate.yml
@@ -1,78 +1,64 @@
 name: SDD Gate

-# Spec-Driven Development quality gate. Runs on PRs and validates the SDD artifacts that
-# the PR touches. The first three jobs are NON-BLOCKING for now (continue-on-error) so the
-# team can adopt the workflow without CI immediately failing.
+# Spec-Driven Development quality gate. Runs on PRs.
 #
-# TODO: flip spec-lint, contract-validate, and traceability-check to BLOCKING
-#       (remove `continue-on-error: true`) once SDD adoption has settled — target: after the
-#       first 5 real features have shipped through the .specify/ workflow. Tracked in ADR-041.
+# This project is ISSUE-ONLY: a feature's spec lives in its Gitea issue body, not a committed
+# spec.md (see ADR-041). So CI cannot lint the spec text itself — instead it validates the SDD
+# artifacts that DO live in git: the RTM, any committed OpenAPI contract, and the constitution.
+#
+# The first two jobs are NON-BLOCKING for now (continue-on-error) so the team can adopt the
+# workflow without CI immediately failing.
+#
+# TODO: flip rtm-check and contract-validate to BLOCKING (remove `continue-on-error: true`)
+#       once SDD adoption has settled — target: after the first 5 features have shipped through
+#       the workflow. Tracked in ADR-041.

 on:
  pull_request:

 jobs:
-  # ─── Spec structure lint ──────────────────────────────────────────────────────
-  # Every modified .specify/features/*/spec.md must contain the required SDD sections
-  # and at least one REQ-NNN requirement. Pure grep — no external tooling.
-  spec-lint:
-    name: Spec Lint
+  # ─── RTM check ────────────────────────────────────────────────────────────────
+  # The Requirements Traceability Matrix is the one per-feature SDD artifact in git. Every
+  # data row must point at a Gitea issue (`#n`) and name at least one test. Warn otherwise.
+  # Pure awk — no external tooling. Columns: | REQ-ID | Summary | Issue | Feature | Impl | Test | Status |
+  rtm-check:
+    name: RTM Check
    runs-on: ubuntu-latest
    continue-on-error: true   # TODO: remove to make blocking (see header)
    steps:
      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0

-      - name: Lint changed spec.md files
+      - name: Validate .specify/rtm.md rows
        shell: bash
        run: |
          set -uo pipefail
-          base="origin/${{ github.event.pull_request.base.ref }}"
-          git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
+          rtm=".specify/rtm.md"
+          test -f "$rtm" || { echo "::error::$rtm is missing"; exit 1; }

-          required=(
-            "## Context & Why"
-            "## Requirements"
-            "## Acceptance Criteria"
-            "## Out of Scope"
-            "## Security Considerations"
-            "## Traceability"
-          )
+          # Self-test: a good row passes, a row with an empty Issue or Test is flagged.
+          check_row() { awk -F'|' '{
+            issue=$4; test_col=$7;
+            gsub(/^[ \t]+|[ \t]+$/,"",issue); gsub(/^[ \t]+|[ \t]+$/,"",test_col);
+            if (issue !~ /#/ || test_col=="") exit 1; else exit 0 }'; }
+          echo '| REQ-001 | x | #42 | f | impl | SomeTest#works | Done |'  | check_row \
+            || { echo "FAIL: rtm-check self-test rejected a valid row"; exit 1; }
+          echo '| REQ-002 | x |     | f | impl |               | Planned |' | check_row \
+            && { echo "FAIL: rtm-check self-test accepted an empty row"; exit 1; }

-          # Self-test: a fixture with all sections + a REQ id must pass the section check.
-          fixture="$(mktemp)"
-          { for s in "${required[@]}"; do echo "$s"; done; echo "- **REQ-001** (Ubiquitous) — The x shall y."; } > "$fixture"
-          for s in "${required[@]}"; do
-            grep -qF "$s" "$fixture" || { echo "FAIL: spec-lint self-test missing '$s'"; exit 1; }
-          done
-
-          changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/spec.md' || true)"
-          if [ -z "$changed" ]; then
-            echo "No spec.md files changed — nothing to lint."
-            exit 0
-          fi
-
-          rc=0
-          for f in $changed; do
-            [ -f "$f" ] || continue   # deleted file
-            echo "── linting $f"
-            for s in "${required[@]}"; do
-              if ! grep -qF "$s" "$f"; then
-                echo "::error file=$f::missing required section '$s'"
-                rc=1
-              fi
-            done
-            if ! grep -qE 'REQ-[0-9]{3}' "$f"; then
-              echo "::error file=$f::no REQ-NNN requirement found"
-              rc=1
-            fi
-          done
-          exit $rc
+          bad=0
+          while IFS= read -r line; do
+            echo "$line" | check_row || {
+              req=$(echo "$line" | awk -F'|' '{gsub(/^[ \t]+|[ \t]+$/,"",$2); print $2}')
+              echo "::warning file=$rtm::row $req is missing an Issue (#n) or a Test"
+              bad=$((bad+1))
+            }
+          done < <(grep -E '^\| REQ-[0-9]{3} ' "$rtm")
+          echo "$bad RTM row(s) incomplete (warning only)."

  # ─── Contract validation ──────────────────────────────────────────────────────
-  # Validate any modified api-contract.yaml with Spectral (OpenAPI 3.1). REST stack —
-  # no GraphQL. Skips cleanly when no contract changed.
+  # Validate any committed OpenAPI contract with Spectral (OpenAPI 3.1). REST stack — no
+  # GraphQL. Contracts are optional and ride a feature branch when present; the _example one
+  # is always linted. Skips cleanly when none changed.
  contract-validate:
    name: Contract Validate
    runs-on: ubuntu-latest
@@ -92,9 +78,10 @@ jobs:
          set -uo pipefail
          base="origin/${{ github.event.pull_request.base.ref }}"
          git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
-          changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/api-contract.yaml' || true)"
+          # Any *.yaml under .specify/ or any file named like a contract.
+          changed="$(git diff --name-only "$base"...HEAD -- '.specify/**/*.yaml' '**/api-contract.yaml' '**/*.openapi.yaml' || true)"
          if [ -z "$changed" ]; then
-            echo "No api-contract.yaml changed — nothing to validate."
+            echo "No OpenAPI contract changed — nothing to validate."
            exit 0
          fi
          rc=0
@@ -105,39 +92,6 @@ jobs:
          done
          exit $rc

-  # ─── Traceability check ───────────────────────────────────────────────────────
-  # Warn (non-blocking) when a changed spec.md references a REQ-NNN that is absent from
-  # .specify/rtm.md. Keeps the matrix honest without hard-failing during adoption.
-  traceability-check:
-    name: Traceability Check
-    runs-on: ubuntu-latest
-    continue-on-error: true   # TODO: remove to make blocking (see header)
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Cross-check spec REQ-IDs against rtm.md
-        shell: bash
-        run: |
-          set -uo pipefail
-          base="origin/${{ github.event.pull_request.base.ref }}"
-          git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
-          changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/spec.md' || true)"
-          [ -z "$changed" ] && { echo "No spec.md changed."; exit 0; }
-          test -f .specify/rtm.md || { echo "::warning::.specify/rtm.md missing"; exit 0; }
-          missing=0
-          for f in $changed; do
-            [ -f "$f" ] || continue
-            for req in $(grep -oE 'REQ-[0-9]{3}' "$f" | sort -u); do
-              if ! grep -qF "$req" .specify/rtm.md; then
-                echo "::warning file=$f::$req is not present in .specify/rtm.md"
-                missing=$((missing+1))
-              fi
-            done
-          done
-          echo "$missing REQ-ID(s) missing from rtm.md (warning only)."
-
  # ─── Constitution change impact ───────────────────────────────────────────────
  # When .specify/constitution.md is modified, list every file that references it (and so
  # may need a Sync Impact update) and post it as a PR comment. Best-effort: if no token is
@@ -164,7 +118,6 @@ jobs:
          fi
          echo "changed=true" >> "$GITHUB_OUTPUT"
          echo "Files referencing constitution.md (review for Sync Impact):"
-          # rg-free: grep recursively, excluding the file itself and VCS/build dirs.
          grep -rIl --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=target \
            -e 'constitution.md' -e 'constitution §' . \
            | grep -v '^\./.specify/constitution.md$' | sort > /tmp/refs.txt || true
@@ -183,7 +136,6 @@ jobs:
        if: steps.impact.outputs.changed == 'true'
        shell: bash
        env:
-          # Gitea Actions exposes the repo token as GITHUB_TOKEN; the API is Gitea-compatible.
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SERVER: ${{ github.server_url }}
          REPO: ${{ github.repository }}
--- a/.specify/AGENTS.md
+++ b/.specify/AGENTS.md
@@ -69,8 +69,9 @@ App port `8080`; management port `8081`. Backend app id: `org.raddatz.familienar

 ## Spec-Driven Development

-Before implementing a feature, read its spec at `.specify/features/<name>/spec.md` and its
-contract at `.specify/features/<name>/api-contract.yaml` if present. The spec's EARS
-requirements (`REQ-NNN`) are the contract; each maps to a test. Worked reference:
-[`.specify/features/_example/`](./features/_example/). Full workflow:
+A feature's spec is its **Gitea issue body** — there is no committed `spec.md`. The issue's
+EARS requirements (`REQ-NNN`) and acceptance criteria are the contract; each maps to a test,
+traced in [`.specify/rtm.md`](./rtm.md) (`REQ-ID → issue # → test`). Read the issue before
+implementing. The committed [`.specify/features/_example/`](./features/_example/) is a
+template/reference showing the full artifact set, not a live feature. Full workflow:
 [SPEC_DRIVEN_DEVELOPMENT.md](../SPEC_DRIVEN_DEVELOPMENT.md).
--- a/.specify/personas/developer.md
+++ b/.specify/personas/developer.md
@@ -19,12 +19,12 @@ structures or hand-wave the hard integration points.
 4. Are new error conditions expressed as named `ErrorCode`s, with the four-site update (`ErrorCode.java`, `errors.ts`, `getErrorMessage()`, `messages/{de,en,es}.json`) called out as tasks?
 5. Does every entity/DTO field the spec adds get `@Schema(requiredMode = REQUIRED)` where always-populated, and is `npm run generate:api` listed as a task after backend changes?
 6. Are frontend changes inside the correct `$lib/<domain>/` boundary, with any cross-domain import either pre-allowed in `eslint.config.js` or flagged for an explicit allow-entry?
-7. Does each `REQ-NNN` map to a concrete test at the right level (unit / `@WebMvcTest` slice / Playwright E2E per COLLABORATING.md's table) in `tasks.md`?
+7. Does each `REQ-NNN` imply a concrete test at the right level (unit / `@WebMvcTest` slice / Playwright E2E per COLLABORATING.md's table) — i.e. is it specified concretely enough to write that test?
 8. Is lazy-loading handled — does any returned entity with a lazy collection get a view (ADR-036) instead of being serialized raw?
 9. Does the design avoid premature abstraction (KISS over DRY) — no new base class/util introduced before a third caller exists?
 10. Are data-model changes expressed as a single forward-only Flyway migration with the next free `V<n>` number verified against disk?
 11. Does the spec avoid backwards-compat shims for code paths that have no existing callers?
-12. Is the `tasks.md` decomposition red/green-ordered — a failing test task precedes each implementation task?
+12. Are the requirements decomposable into a red/green-ordered task list — each behavior small enough that a failing test can precede its implementation?

 ## EARS patterns to watch for

--- a/.specify/rtm.md
+++ b/.specify/rtm.md
@@ -1,19 +1,22 @@
 # Requirements Traceability Matrix (RTM)

-> Living document. One row per `REQ-NNN` across all in-flight and shipped features. It links
-> a requirement to the design that realises it, the code that implements it, and the
-> test(s) that prove it — so any requirement can be traced end to end, and any orphan
-> (a requirement with no test, or a test with no requirement) is visible.
+> Living document. One row per `REQ-NNN` across all in-flight and shipped features. The spec
+> itself lives in the **Gitea issue** (issue-only — there is no committed `spec.md`); this
+> matrix is the part of the spec that *is* committed: it links each requirement to its issue,
+> the code that implements it, and the test(s) that prove it — so any requirement traces end
+> to end, and any orphan (a requirement with no test) is visible on `main`.

 ## How to update

-1. When a `spec.md` is approved, copy its `## Traceability` rows here with `Status: Planned`.
-2. As tasks land, fill `Implementation File(s)` and flip `Status` → `In progress` → `Done`.
-3. `REQ-ID`s are **scoped per feature**, so always qualify with the Feature column — `REQ-001`
-   in *avatar* is not `REQ-001` in another feature.
-4. The `sdd-gate.yml` CI job (`traceability-check`) warns (non-blocking, for now) when a
-   `spec.md` contains a `REQ-NNN` that does not appear in this file. Keep it in sync to keep
-   the warning quiet; it flips to blocking once adoption settles (see the workflow's TODO).
+1. When a feature's issue is approved (via `/review-issue`), add one row per `REQ-NNN` with the
+   `Issue` set to the Gitea issue number and `Status: Planned`. Commit these rows on the feature
+   branch (they merge with the feature's PR).
+2. As tasks land, fill `Implementation File(s)` + `Test(s)` and flip `Status` →
+   `In progress` → `Done`.
+3. `REQ-ID`s are **scoped per feature**, so always read them together with the `Issue` column —
+   `REQ-001` for issue #142 is not `REQ-001` for issue #150.
+4. The `sdd-gate.yml` CI job (`rtm-check`) warns (non-blocking, for now) when a row is missing
+   its `Issue` or `Test(s)`. It flips to blocking once adoption settles (see the workflow's TODO).

 ## Status legend

@@ -21,16 +24,16 @@

 ## Matrix

-| REQ-ID | Requirement Summary | Feature | Design Artifact | Implementation File(s) | Test(s) | Status |
+| REQ-ID | Requirement Summary | Issue | Feature | Implementation File(s) | Test(s) | Status |
 |---|---|---|---|---|---|---|
-| REQ-001 | Store avatar at `avatars/{userId}`, overwrite | profile-picture-upload (_example) | features/_example/design.md; adr-001 | `UserService` (planned) | `UserServiceAvatarTest#storesUnderUserKey`, `#replaceLeavesNoOrphan` | Planned |
-| REQ-002 | Upload self avatar → 200 + avatarUrl | profile-picture-upload (_example) | features/_example/design.md; api-contract.yaml | `UserAvatarController`, `UserService` (planned) | `UserAvatarControllerTest#uploadReturnsAvatarUrl` | Planned |
-| REQ-003 | Delete self avatar → avatarUrl null | profile-picture-upload (_example) | features/_example/api-contract.yaml | `UserAvatarController` (planned) | `UserAvatarControllerTest#deleteClearsAvatar` | Planned |
-| REQ-004 | No avatar → null + initials placeholder | profile-picture-upload (_example) | features/_example/design.md | `UserProfileView`, avatar component (planned) | `avatar-placeholder.svelte.spec.ts` | Planned |
-| REQ-005 | ADMIN_USER may delete others' avatar | profile-picture-upload (_example) | features/_example/api-contract.yaml | `UserAvatarController` (planned) | `UserAvatarControllerTest#adminDeletesOthersAvatar` | Planned |
-| REQ-006 | Unauthenticated → 401, store nothing | profile-picture-upload (_example) | features/_example/threat-model.md | `SecurityConfig`, controller (planned) | `UserAvatarControllerTest#unauthenticatedReturns401` | Planned |
-| REQ-007 | Non-image → 400 UNSUPPORTED_FILE_TYPE | profile-picture-upload (_example) | features/_example/design.md | `UserService` (planned) | `UserAvatarControllerTest#rejectsNonImage` | Planned |
-| REQ-008 | Over 2 MB → 400 AVATAR_TOO_LARGE | profile-picture-upload (_example) | features/_example/design.md | `UserService`, `ErrorCode` (planned) | `UserAvatarControllerTest#rejectsOversize` | Planned |
-| REQ-009 | Non-admin on others → 403 FORBIDDEN | profile-picture-upload (_example) | features/_example/threat-model.md | `UserAvatarController` (planned) | `UserAvatarControllerTest#nonAdminForbiddenOnOthers` | Planned |
+| REQ-001 | Store avatar at `avatars/{userId}`, overwrite | #example | profile-picture-upload (_example) | `UserService` (planned) | `UserServiceAvatarTest#storesUnderUserKey`, `#replaceLeavesNoOrphan` | Planned |
+| REQ-002 | Upload self avatar → 200 + avatarUrl | #example | profile-picture-upload (_example) | `UserAvatarController`, `UserService` (planned) | `UserAvatarControllerTest#uploadReturnsAvatarUrl` | Planned |
+| REQ-003 | Delete self avatar → avatarUrl null | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#deleteClearsAvatar` | Planned |
+| REQ-004 | No avatar → null + initials placeholder | #example | profile-picture-upload (_example) | `UserProfileView`, avatar component (planned) | `avatar-placeholder.svelte.spec.ts` | Planned |
+| REQ-005 | ADMIN_USER may delete others' avatar | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#adminDeletesOthersAvatar` | Planned |
+| REQ-006 | Unauthenticated → 401, store nothing | #example | profile-picture-upload (_example) | `SecurityConfig`, controller (planned) | `UserAvatarControllerTest#unauthenticatedReturns401` | Planned |
+| REQ-007 | Non-image → 400 UNSUPPORTED_FILE_TYPE | #example | profile-picture-upload (_example) | `UserService` (planned) | `UserAvatarControllerTest#rejectsNonImage` | Planned |
+| REQ-008 | Over 2 MB → 400 AVATAR_TOO_LARGE | #example | profile-picture-upload (_example) | `UserService`, `ErrorCode` (planned) | `UserAvatarControllerTest#rejectsOversize` | Planned |
+| REQ-009 | Non-admin on others → 403 FORBIDDEN | #example | profile-picture-upload (_example) | `UserAvatarController` (planned) | `UserAvatarControllerTest#nonAdminForbiddenOnOthers` | Planned |

-<!-- Append real features below this line. Keep the header row above. -->
+<!-- Append real features below this line, one row per REQ-NNN, with the real issue number. Keep the header row above. -->
--- a/.specify/templates/api-contract-stub.md
+++ b/.specify/templates/api-contract-stub.md
@@ -6,19 +6,21 @@ TypeScript client from it with `npm run generate:api` (`openapi-typescript` →
 `frontend/src/lib/generated/api.ts`). There is no GraphQL in this stack.

 > **The live spec is generated from the Java controllers — it is the source of truth.** A
-> hand-written contract under `.specify/features/<name>/api-contract.yaml` is a *design
-> artifact*: it pins the intended shape during spec review and is checked against the
-> generated spec once the endpoint exists. Keep it OpenAPI **3.1**, and keep
-> `@Schema(requiredMode = REQUIRED)` on the Java side as the real driver of `required`.
+> hand-written stub is a *design artifact*: it pins the intended shape during spec review.
+> Issue-only: paste the stub inline into the issue's `## API / Contract Stub` section. Keep it
+> OpenAPI **3.1**, and keep `@Schema(requiredMode = REQUIRED)` on the Java side as the real
+> driver of `required`.

 ## How to use this stub

-1. Copy the skeleton below to `.specify/features/<name>/api-contract.yaml`.
-2. Fill in the paths/methods/schemas your feature adds. Every mutating path documents the
-   `403`/`401` responses and the `cookieAuth` security requirement (matching the real
-   `@RequirePermission` gate).
-3. The `sdd-gate.yml` CI job lints any changed `api-contract.yaml` with Spectral
-   (`npx @stoplight/spectral-cli lint`). Run it locally the same way before pushing.
+1. Fill in the skeleton below with the paths/methods/schemas your feature adds, and paste it
+   into the issue's `## API / Contract Stub` section.
+2. Every mutating path documents the `403`/`401` responses and the `cookieAuth` security
+   requirement (matching the real `@RequirePermission` gate).
+3. If you prefer a standalone, lintable file (e.g. for a large contract), commit it on the
+   **feature branch** as `<feature>.openapi.yaml` — the `sdd-gate.yml` CI job lints any
+   committed OpenAPI contract with Spectral (`npx @stoplight/spectral-cli lint`). It never
+   needs to predate the issue.
 4. After the endpoint ships, run `npm run generate:api` and diff the generated types against
   this contract; reconcile any drift (the generated spec wins — update the contract).

--- a/.specify/templates/feature-spec.md
+++ b/.specify/templates/feature-spec.md
@@ -1,10 +1,10 @@
 <!--
-  Feature Spec template — copy this into a Gitea issue body (or .specify/features/<name>/spec.md).
-  Replace every <placeholder>. Delete this comment block before submitting.
+  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).
-  Companion artifacts live beside this file: design.md, api-contract.yaml, threat-model.md,
-  adr-NNN-*.md, tasks.md, checklist-results.md.
+  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>">
@@ -13,10 +13,10 @@

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

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

-Related: <links to prior issues / ADRs / specs>.
+Related: <links to prior issues / ADRs>.

 ## User Journey

@@ -51,7 +51,7 @@ Related: <links to prior issues / ADRs / specs>.

 ## API / Contract Stub

-<Inline stub OR link to `./api-contract.yaml`. Name the new/changed paths, methods, request/response shapes, status codes, and `@RequirePermission`.>
+<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

@@ -59,7 +59,7 @@ Related: <links to prior issues / ADRs / specs>.

 ## Security Considerations

-<STRIDE categories touched (Spoofing/Tampering/Repudiation/Information disclosure/DoS/Elevation). For AI-agent/tool features, also ASTRIDE. Link to `./threat-model.md` if the feature has a non-trivial attack surface.>
+<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

@@ -75,7 +75,7 @@ Related: <links to prior issues / ADRs / specs>.
 | REQ-001 | <T-1> | <test name> | Planned |
 | REQ-002 | <T-2> | <test name> | Planned |

-<Mirror these rows into [.specify/rtm.md](../../rtm.md). Fill Task/Test IDs as work progresses.>
+<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

--- a/.specify/templates/threat-model.md
+++ b/.specify/templates/threat-model.md
@@ -1,12 +1,14 @@
 <!--
-  Threat model template — STRIDE + ASTRIDE. Lives at .specify/features/<name>/threat-model.md.
-  Required when a feature adds a new trust boundary, handles uploads, exposes a new mutating
-  endpoint, or invokes an AI agent/tool. The Security persona gates this file. Delete this comment.
+  Threat model template — STRIDE + ASTRIDE. WRITING AID: fill this in and paste the result into
+  the issue's "## Security Considerations" section (issue-only — the threat model lives in the
+  issue body, not a committed file). Required when a feature adds a new trust boundary, handles
+  uploads, exposes a new mutating endpoint, or invokes an AI agent/tool. The Security persona
+  gates it during /review-issue. Delete this comment.
 -->

 # Threat Model — <Feature name>

-**Feature spec:** [./spec.md](./spec.md)
+**Feature spec:** Gitea issue #<n>
 **Date:** <YYYY-MM-DD>
 **Author:** <name>

--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -18,7 +18,7 @@ See [CODESTYLE.md](./CODESTYLE.md) for coding standards: Clean Code, DRY/KISS tr

 ## Spec-Driven Development

-This project uses Spec-Driven Development. **Before implementing a feature, read [`.specify/AGENTS.md`](./.specify/AGENTS.md)** (the short, machine-readable agent rules) and obey the [`.specify/constitution.md`](./.specify/constitution.md) it references. A feature's contract is its `.specify/features/<name>/spec.md` (EARS `REQ-NNN` requirements) plus any `api-contract.yaml`. Full workflow: [SPEC_DRIVEN_DEVELOPMENT.md](./SPEC_DRIVEN_DEVELOPMENT.md); worked example: [`.specify/features/_example/`](./.specify/features/_example/). The LLM reminders below restate constitution rules — the constitution and AGENTS.md are authoritative if they ever diverge.
+This project uses Spec-Driven Development. **Before implementing a feature, read [`.specify/AGENTS.md`](./.specify/AGENTS.md)** (the short, machine-readable agent rules) and obey the [`.specify/constitution.md`](./.specify/constitution.md) it references. A feature's contract is its **Gitea issue body** (EARS `REQ-NNN` requirements) — there is no committed `spec.md`; the RTM ([`.specify/rtm.md`](./.specify/rtm.md)) traces each `REQ-ID → issue # → test`. Full workflow: [SPEC_DRIVEN_DEVELOPMENT.md](./SPEC_DRIVEN_DEVELOPMENT.md); template/reference: [`.specify/features/_example/`](./.specify/features/_example/). The LLM reminders below restate constitution rules — the constitution and AGENTS.md are authoritative if they ever diverge.

 ---

--- a/SPEC_DRIVEN_DEVELOPMENT.md
+++ b/SPEC_DRIVEN_DEVELOPMENT.md
@@ -17,17 +17,28 @@ multi-persona review → red/green TDD). It does not replace any of that — see
 | # | Step | Who | Artifacts created / touched |
 |---|---|---|---|
 | 1 | **Idea → Gitea issue** using the Feature template | author | Gitea issue (labels `spec-required`, `needs-review`) from `.gitea/ISSUE_TEMPLATE/feature.md` |
-| 2 | **Write the spec** — Context, User Journey, EARS `REQ-NNN` requirements, measurable acceptance criteria, Out of Scope | author | issue body **and** `.specify/features/<name>/spec.md` |
-| 3 | **Add design artifacts** as needed | author | `design.md`; `api-contract.yaml` (any new endpoint); `threat-model.md` (uploads / new mutating endpoint / AI tool); feature-local `adr-NNN-*.md` or a `docs/adr/` entry for project-wide decisions |
-| 4 | **Persona spec review** — the six checklists gate the spec | RE, Developer, Security, DevOps, UI/UX, Architect | `checklist-results.md` + the `## Persona Review Results` table; findings folded into the spec |
-| 5 | **Resolve Open Questions & blocking FAILs** — spec does not proceed while any remain | author | spec updated; `Open Questions` emptied |
-| 6 | **Decompose into tasks** in red/green order; seed the RTM | author | `tasks.md`; rows added to [`.specify/rtm.md`](./.specify/rtm.md) (`Status: Planned`) |
-| 7 | **Implement** in a worktree, TDD per task (failing test → green → refactor → commit); agent reads `AGENTS.md` + `spec.md` + `api-contract.yaml` | implementer (often an AI agent) | code + tests; `npm run generate:api` after backend changes; RTM `Status` → `Done` |
-| 8 | **PR → multi-persona PR review → merge**; archive the feature | reviewers | PR (`Closes #n`); on merge, move the feature dir under `.specify/features/_archive/<name>/` (or tag it shipped) |
+| 2 | **Write the spec _in the issue body_** — Context, User Journey, EARS `REQ-NNN` requirements, measurable acceptance criteria, Out of Scope | author | the Gitea issue body **is** the spec (single source of truth — no committed `spec.md`) |
+| 3 | **Capture durable design decisions** as needed | author | a `docs/adr/` ADR for any project-wide/irreversible decision; an OpenAPI contract and a STRIDE threat model inline in the issue (use the `.specify/templates/` as the writing aid) |
+| 4 | **Persona spec review** — the six checklists gate the spec | RE, Developer, Security, DevOps, UI/UX, Architect | `/review-issue` posts each persona's checklist verdict as a Gitea comment; findings folded into the issue body |
+| 5 | **Resolve Open Questions & blocking FAILs** — spec does not proceed while any remain | author | issue body updated; `Open Questions` emptied |
+| 6 | **Seed the RTM** — one row per `REQ-NNN`, pointing at the issue | author | rows added to [`.specify/rtm.md`](./.specify/rtm.md) (`Issue: #n`, `Status: Planned`) — committed with the feature branch |
+| 7 | **Implement** in a worktree, TDD per task (failing test → green → refactor → commit); agent reads `AGENTS.md` + the **issue body** (the spec) | implementer (often an AI agent) | code + tests; `npm run generate:api` after backend changes; RTM `Status` → `Done` |
+| 8 | **PR → multi-persona PR review → merge** | reviewers | PR (`Closes #n`); the closed issue is the archived spec, the RTM rows record what shipped |

-The personas at step 4 review the **spec**; the same personas at step 8 (via the existing
-`review-pr` / `deliver-issue` skills) review the **code**. Step 4 catches at spec time what
-used to surface only at step 8.
+The personas at step 4 review the **spec (the issue)**; the same personas at step 8 (via the
+existing `review-pr` / `deliver-issue` skills) review the **code**. Step 4 catches at spec time
+what used to surface only at step 8.
+
+**Skills that drive this:** `/draft-spec` (requirements engineer authors steps 1–2 → creates
+the issue) → `/review-issue` (step 4 gate) → `/implement` (steps 6–7) → `/review-pr` (step 8).
+`/deliver-issue` runs review → discuss → implement → review-loop end-to-end.
+
+> **Why issue-only?** The Gitea issue body is the single source of truth for a spec — there is
+> no committed per-feature `spec.md` to drift out of sync with it. The only SDD artifact that
+> lives in git per feature is the RTM row (`REQ-ID → issue # → test`). The worked example under
+> [`.specify/features/_example/`](./.specify/features/_example/) is a **template/reference**, not
+> a live feature — it shows the full artifact set in one place; real features keep the spec in
+> the issue.

 ## 2. How a Gitea issue becomes a spec

@@ -63,7 +74,7 @@ measurable acceptance criterion. See the full version in
 ## 3. How to run a persona review

 Each persona reads the spec, walks its checklist in `.specify/personas/<persona>.md`, and
-posts a Gitea comment (or fills `checklist-results.md`) with **PASS / FAIL / QUESTION** per
+posts a Gitea comment with **PASS / FAIL / QUESTION** per
 item and a verdict. A `FAIL` from Security or Architect is a hard block. Concrete example:

 > ### Security — Spec Review
@@ -86,15 +97,16 @@ empties the finding, and the persona re-reviews until `APPROVE`. This mirrors th
 Once the spec is `APPROVE`d and tasks are seeded, the implementer points the agent at the
 artifacts. Example prompt:

-> Implement `.specify/features/profile-picture-upload/`. Read `.specify/AGENTS.md` and obey
-> the constitution it references. The contract is `spec.md` (REQ-001…REQ-009) and
-> `api-contract.yaml`. Work through `tasks.md` in order, red/green TDD — write the failing
-> test named in each task first, confirm it fails, then make it pass. After backend model
-> changes run `npm run generate:api`. Each REQ has a test in the Traceability table; do not
-> mark a task done until its test is green. Update `.specify/rtm.md` Status as you go.
+> Implement Gitea issue #142 (profile picture upload). Read `.specify/AGENTS.md` and obey the
+> constitution it references. The contract is the issue body — its EARS requirements
+> REQ-001…REQ-009 and acceptance criteria. Build a red/green task list from them, write the
+> failing test for each REQ first, confirm it fails, then make it pass. After backend model
+> changes run `npm run generate:api`. Do not mark a REQ done until its test is green; flip its
+> row in `.specify/rtm.md` to Done as you go.

-The agent now has: the rules (`AGENTS.md` → constitution), the exact requirements with ids,
-the API shape, and a test-first task list — so its output is bounded and verifiable.
+The agent now has: the rules (`AGENTS.md` → constitution) and the exact requirements with ids
+from the issue — so its output is bounded and verifiable. (The `/implement` skill fetches the
+issue body for you via the Gitea API.)

 ## 5. Maintenance rules

@@ -105,13 +117,14 @@ the API shape, and a test-first task list — so its output is bounded and verif
  in ADR-041's revision log (or a superseding ADR for MAJOR).
 - **AGENTS.md** — keep it under 200 lines. It cross-references the constitution; it must never
  duplicate or contradict it.
- **ADRs** — project-wide decisions go in [`docs/adr/`](./docs/adr/) (next free `NNN`, verify
-  on disk). Immutable once `Accepted`; supersede, don't edit. Feature-local decisions stay
-  beside the feature spec.
- **Feature specs** — archive on merge: move `.specify/features/<name>/` to
-  `.specify/features/_archive/<name>/`. The spec stays as the record of what shipped.
- **RTM** ([`.specify/rtm.md`](./.specify/rtm.md)) — append rows when a spec is approved;
-  flip `Status` as tests go green; never delete a shipped requirement's row. CI warns on drift.
+- **ADRs** — project-wide/irreversible decisions go in [`docs/adr/`](./docs/adr/) (next free
+  `NNN`, verify on disk). Immutable once `Accepted`; supersede, don't edit.
+- **Feature specs** — the spec is the Gitea issue body; there is no committed `spec.md`.
+  "Archiving" is just closing the issue (`Closes #n` on merge). The closed issue + the RTM
+  rows are the record of what shipped.
+- **RTM** ([`.specify/rtm.md`](./.specify/rtm.md)) — append one row per `REQ-NNN` when a spec
+  is approved, each pointing at its issue (`#n`); flip `Status` as tests go green; never delete
+  a shipped requirement's row.
 - **Personas** — update `.specify/personas/*.md` checklists when a recurring blind spot
  appears; keep them aligned with the richer `.claude/personas/`.

@@ -133,11 +146,11 @@ the API shape, and a test-first task list — so its output is bounded and verif
 |---|---|
 | Non-negotiable rules | `.specify/constitution.md` |
 | Agent rules (read every time) | `.specify/AGENTS.md` |
-| Templates | `.specify/templates/{feature-spec,adr,threat-model,api-contract-stub}.md` |
+| Templates (writing aids) | `.specify/templates/{feature-spec,adr,threat-model,api-contract-stub}.md` |
 | Persona checklists | `.specify/personas/*.md` |
-| In-flight feature | `.specify/features/<name>/{spec,design,tasks,checklist-results}.md` + `api-contract.yaml` + `threat-model.md` |
-| Worked example | `.specify/features/_example/` |
-| Traceability matrix | `.specify/rtm.md` |
+| In-flight feature spec | the **Gitea issue body** (not a committed file) |
+| Worked example (template/reference) | `.specify/features/_example/` |
+| Traceability matrix | `.specify/rtm.md` (`REQ-ID → issue # → test`) |
 | ADR archive | `docs/adr/NNN-*.md` |
 | Issue templates | `.gitea/ISSUE_TEMPLATE/{feature,bug}.md` |
 | CI gate | `.gitea/workflows/sdd-gate.yml` |
@@ -149,8 +162,8 @@ the API shape, and a test-first task list — so its output is bounded and verif
 **Commands:**

 ```bash
-# validate a contract locally (same as CI)
-npx @stoplight/spectral-cli lint .specify/features/<name>/api-contract.yaml
+# validate an OpenAPI contract locally (if you drafted one — same as CI)
+npx @stoplight/spectral-cli lint <your-contract>.yaml

 # regenerate the TS client after a backend model/endpoint change
 cd frontend && npm run generate:api   # backend must run with --spring.profiles.active=dev
--- a/docs/adr/041-sdd-adoption.md
+++ b/docs/adr/041-sdd-adoption.md
@@ -36,17 +36,23 @@ Adopt Spec-Driven Development, layered **on top of** the existing workflow, not

 1. **EARS requirements.** Every feature requirement is written in one of the five EARS
   patterns and carries a per-feature `REQ-NNN` id. (constitution §3; templates/feature-spec.md)
-2. **OpenSpec-style delta artifacts.** Each in-flight feature gets a `.specify/features/<name>/`
-   directory holding `spec.md`, `design.md`, optional `api-contract.yaml` / `threat-model.md`
-   / feature-local ADRs, `tasks.md`, and `checklist-results.md`. Artifacts are deltas focused
-   on one change, archived when the feature ships.
+2. **The spec lives in the Gitea issue body — issue-only, no committed `spec.md`.** A feature's
+   spec (EARS requirements, acceptance criteria, scope) is authored and reviewed in the Gitea
+   issue, the single source of truth (consistent with the established "issue body is the source
+   of truth / don't commit standalone spec files" practice). The only per-feature artifact in
+   git is the RTM row (`REQ-ID → issue # → test`). Durable design decisions still get a
+   `docs/adr/` ADR; an OpenAPI contract or STRIDE threat model is drafted inline in the issue
+   using the `.specify/templates/` as writing aids. `.specify/features/_example/` is a committed
+   template/reference, not a live feature.
 3. **A constitution + AGENTS.md.** `.specify/constitution.md` records the few non-negotiable
   rules (semantically versioned); `.specify/AGENTS.md` is the short machine-readable file AI
   agents read every invocation, cross-referencing the constitution rather than duplicating it.
 4. **Persona checklists.** `.specify/personas/*.md` turn the existing rich personas into
   concise, EARS-aware, pass/fail spec-review checklists that gate a spec before code.
-5. **Living RTM + CI gate.** `.specify/rtm.md` traces every `REQ-NNN`; `.gitea/workflows/sdd-gate.yml`
-   lints spec structure, validates contracts, and checks traceability (non-blocking initially).
+5. **Living RTM + CI gate.** `.specify/rtm.md` traces every `REQ-NNN` to its issue and test;
+   `.gitea/workflows/sdd-gate.yml` validates any committed OpenAPI contract, lints any committed
+   spec (e.g. the `_example`), reports constitution-change impact, and surfaces RTM drift
+   (non-blocking initially).
 6. **Reuse, don't duplicate.** ADRs stay in `docs/adr/`; persona checklists reference
   `.claude/personas/`; the Gitea issue templates mirror the feature-spec template.

@@ -54,7 +60,7 @@ Adopt Spec-Driven Development, layered **on top of** the existing workflow, not

 | Option | Pros | Cons | Reason rejected |
 |---|---|---|---|
-| Adopt SDD (EARS + delta artifacts + AGENTS.md), integrated with existing docs | Adds requirement rigor & machine-readability; reuses ADR archive and personas; incremental | Per-feature spec authoring overhead | **Chosen** |
+| Adopt SDD (EARS requirements in the issue + AGENTS.md + constitution), integrated with existing docs | Adds requirement rigor & machine-readability; reuses ADR archive, personas, and the issue-as-spec practice; incremental | Per-feature spec authoring overhead | **Chosen** |
 | No change (keep free-prose issues + persona review) | Zero new process | Ambiguous requirements; no traceability; no single agent-facing file; blind spots found late | Leaves the exact gaps that hurt agent output |
 | Full GitHub Spec Kit | Mature, opinionated tooling | Heavy, opinionated structure that fights the existing Gitea/skill/persona workflow; redundant ADR/persona machinery | Too much to retrofit; conflicts with what already works |
 | BMAD-METHOD | Rich agent-role framework | Large conceptual surface for a solo project; overlaps the existing persona system | Over-engineered for this team size |