docs/adr/041-sdd-adoption.md

@@ -0,0 +1,87 @@
+# ADR-041 — Adopt Spec-Driven Development (SDD)
+
+**Status:** Accepted
+**Date:** 2026-06-13
+**Issue:** SDD integration (docs/sdd-integration branch)
+
+> This is the "ADR-000" the SDD scaffold refers to, numbered 041 to fit the existing archive
+> sequence rather than starting a parallel one. See [`.specify/adrs/README.md`](../../.specify/adrs/README.md).
+
+## Context
+
+The project already runs a lightweight, multi-persona review loop: feature work is tracked
+as dense Gitea issues, and the `review-issue` / `review-pr` / `deliver-issue` skills dispatch
+the character personas in `.claude/personas/` (requirements engineer, developer, security,
+devops, ui, architect, tester) to comment on issues and PRs. `COLLABORATING.md` already
+mandates a Research → Plan → Implement → Validate cycle, red/green TDD, and a User-Journey +
+E2E-Scenario section on every feature issue. Decisions are captured in this ADR archive.
+
+What is missing is a **machine-readable, uniform front-end to that workflow**:
+
+- Requirements are written in free prose, so two readers (and an AI agent) can interpret the
+  same issue differently. There is no enforced requirement grammar and no stable requirement
+  identifier to trace from spec → code → test.
+- There is no single short file an AI coding agent reads on every invocation; the rules are
+  spread across `CLAUDE.md`, `COLLABORATING.md`, `CODESTYLE.md`, and `CONTRIBUTING.md`.
+- Persona review is valuable but ad-hoc — there is no per-role checklist that gates a spec
+  *before* implementation, so blind spots surface during PR review instead of at spec time.
+- There is no living traceability record and no CI signal that a spec is well-formed.
+
+The project is solo + LLM-driven; spec density and machine-readability are exactly the
+leverage points that make agent output reliable.
+
+## Decision
+
+Adopt Spec-Driven Development, layered **on top of** the existing workflow, not replacing it:
+
+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.
+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).
+6. **Reuse, don't duplicate.** ADRs stay in `docs/adr/`; persona checklists reference
+   `.claude/personas/`; the Gitea issue templates mirror the feature-spec template.
+
+## Alternatives Considered
+
+| 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** |
+| 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 |
+
+## Consequences
+
+- **Cost:** ~30–60 min of spec authoring + structured persona review per feature, before
+  implementation begins.
+- **Gains:** unambiguous, testable requirements; a stable spec→code→test trace; one
+  authoritative agent-facing rules file; review blind spots caught at spec time; better and
+  more consistent AI-agent output (the project's primary delivery mechanism).
+- **Obligations created:**
+  - The constitution is semantically versioned; any change triggers its Sync Impact review.
+  - A new feature follows the workflow in [SPEC_DRIVEN_DEVELOPMENT.md](../../SPEC_DRIVEN_DEVELOPMENT.md).
+  - `rtm.md` is kept in sync as requirements land (CI warns on drift).
+  - The SDD CI jobs start non-blocking and flip to blocking once adoption settles (TODO noted
+    in the workflow).
+- **Non-disruptive:** the existing Gitea-issue, branch/PR, TDD, and persona-review practices
+  are unchanged in spirit — SDD formalises their inputs, it does not replace them.
+
+## References
+
+- [.specify/constitution.md](../../.specify/constitution.md), [.specify/AGENTS.md](../../.specify/AGENTS.md)
+- [SPEC_DRIVEN_DEVELOPMENT.md](../../SPEC_DRIVEN_DEVELOPMENT.md)
+- [COLLABORATING.md](../../COLLABORATING.md), [CONTRIBUTING.md](../../CONTRIBUTING.md)
+- EARS: Mavin et al., "Easy Approach to Requirements Syntax" (2009)
+
+## Revision log
+
+- 2026-06-13 — constitution v1.0.0 ratified with this ADR.