docs(adr): add themed versioning, AI workflow and SDD records

.claude/commands/pre-commit.md

@@ -10,12 +10,13 @@ Run the pre-commit checklist for this project:
 2. Run `cargo fmt` — formats code in place.
 3. Run `cargo clippy --all-targets --all-features -- -D warnings` — must pass clean.
 4. Run `cargo test` — all tests must pass.
-5. Run `cargo build` — must succeed.
-6. If Docker is running, run `docker compose build` — must succeed with no
+5. Run `cargo tarpaulin --fail-under 80` — coverage must be ≥80%.
+6. Run `cargo build` — must succeed.
+7. If Docker is running, run `docker compose build` — must succeed with no
    errors. Skip this step with a note if Docker Desktop is not running.
-7. If `coderabbit` CLI is installed, run `coderabbit review --type uncommitted --prompt-only`:
+8. If `coderabbit` CLI is installed, run `coderabbit review --type uncommitted --prompt-only`:
    - If actionable/serious findings are reported, stop and address them before proposing the commit.
    - If only nitpick-level findings, report them and continue to the commit proposal.
    - If `coderabbit` is not installed, skip this step with a note.
 
-Run steps 2–5, run step 6 (docker build), then run step 7 (CodeRabbit review) if available, report the results clearly, then propose a branch name and commit message for my approval using the format `type(scope): description (#issue)` (max 80 chars; types: `feat` `fix` `chore` `docs` `test` `refactor` `ci` `perf`) followed by a co-author line `Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>`. Do not create the branch or commit until I explicitly confirm.
+Run steps 2–6, run step 7 (docker build), then run step 8 (CodeRabbit review) if available, report the results clearly, then propose a branch name and commit message for my approval using the format `type(scope): description (#issue)` (max 80 chars; types: `feat` `fix` `chore` `docs` `test` `refactor` `ci` `perf`) followed by a co-author line `Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>`. Do not create the branch or commit until I explicitly confirm.

CHANGELOG.md

@@ -44,13 +44,14 @@ Release codenames follow an A-Z sequence using Ballon d'Or award nominees surnam
 
 ### Added
 
-- Architecture Decision Records in `adr/`: 8 ADRs (0001–0008) documenting framework selection, four-layer architecture, Diesel/r2d2/SQLite persistence stack, dual-key strategy, PUT semantics, embedded migrations, integration-only testing, and Docker/Compose strategy (`#113`)
+- Architecture Decision Records in `docs/adr/`: 11 ADRs (0001–0011) documenting framework selection, four-layer architecture, Diesel/r2d2/SQLite persistence stack, dual-key strategy, PUT semantics, embedded migrations, integration-only testing, Docker/Compose strategy, Ballon d'Or-themed versioning, AI-assisted development workflow, and Spec-Driven Development (`#113`)
 
 ### Changed
 
 - Replace `cargo install cargo-tarpaulin` with `taiki-e/install-action@v2.81.8` in CI to use a pre-built binary and reduce coverage job runtime
 - Consolidated agent instructions from `.github/copilot-instructions.md` into `CLAUDE.md`; deleted the legacy split-file layout (`#112`)
 - Rewrote all stale `.coderabbit.yaml` path instructions to reflect the current Diesel/r2d2/SQLite architecture; removed all references to the old `Mutex<Vec<Player>>` in-memory design (`#112`)
+- Added `cargo tarpaulin --fail-under 80` to the `/pre-commit` checklist to enforce 80% coverage locally
 
 ### Fixed
 

CLAUDE.md

@@ -70,7 +70,7 @@ cargo test -- --nocapture               # with output
 3. `cargo build` — must succeed
 4. `cargo test` — all tests must pass
 5. Commit message follows Conventional Commits format (enforced by commitlint)
-6. If this commit introduces or changes an architectural decision, update `CLAUDE.md` and create or amend the relevant ADR in `adr/`.
+6. If this commit introduces or changes an architectural decision, update `CLAUDE.md` and create or amend the relevant ADR in `docs/adr/`.
 7. If this commit adds, removes, or changes an endpoint, a dependency, or how the project is run, update `README.md` and the relevant path instructions in `.coderabbit.yaml`.
 
 ### Commits
@@ -148,20 +148,23 @@ Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
 
 ## Architecture Decision Records
 
-Architectural decisions are documented in `adr/`. When proposing structural
+Architectural decisions are documented in [`docs/adr/`](docs/adr/README.md). When proposing structural
 changes, check the ADR index first. When a decision changes, mark the existing
 ADR as `Deprecated` or `Superseded by ADR-XXXX` and write a new one.
 
 Current ADRs:
 
-- [ADR-0001](adr/0001-adopt-rocket-as-rest-api-framework.md) — Rocket 0.5 as HTTP framework
-- [ADR-0002](adr/0002-four-layer-architecture.md) — Routes → Services → Repositories → State
-- [ADR-0003](adr/0003-diesel-r2d2-bundled-sqlite.md) — Diesel + r2d2 + bundled libsqlite3
-- [ADR-0004](adr/0004-uuid-surrogate-squad-number-natural-key.md) — UUID surrogate key + squad number natural key
-- [ADR-0005](adr/0005-full-replace-put-no-patch.md) — Full-replace PUT, no PATCH
-- [ADR-0006](adr/0006-embed-migrations-startup-schema.md) — `embed_migrations!()` at startup
-- [ADR-0007](adr/0007-integration-only-test-strategy.md) — Integration-only tests with in-memory SQLite
-- [ADR-0008](adr/0008-docker-compose-strategy.md) — Multi-stage Dockerfile + Compose
+- [ADR-0001](docs/adr/0001-adopt-rocket-as-rest-api-framework.md) — Rocket 0.5 as HTTP framework
+- [ADR-0002](docs/adr/0002-four-layer-architecture.md) — Routes → Services → Repositories → State
+- [ADR-0003](docs/adr/0003-diesel-r2d2-bundled-sqlite.md) — Diesel + r2d2 + bundled libsqlite3
+- [ADR-0004](docs/adr/0004-uuid-surrogate-squad-number-natural-key.md) — UUID surrogate key + squad number natural key
+- [ADR-0005](docs/adr/0005-full-replace-put-no-patch.md) — Full-replace PUT, no PATCH
+- [ADR-0006](docs/adr/0006-embed-migrations-startup-schema.md) — `embed_migrations!()` at startup
+- [ADR-0007](docs/adr/0007-integration-only-test-strategy.md) — Integration-only tests with in-memory SQLite
+- [ADR-0008](docs/adr/0008-docker-compose-strategy.md) — Multi-stage Dockerfile + Compose
+- [ADR-0009](docs/adr/0009-ballon-dor-themed-versioning.md) — Ballon d'Or-themed release codenames
+- [ADR-0010](docs/adr/0010-ai-assisted-development-workflow.md) — Claude Code as primary workflow tool
+- [ADR-0011](docs/adr/0011-spec-driven-development.md) — Spec-Driven Development (SDD)
 
 ## Claude Code
 

docs/adr/0009-ballon-dor-themed-versioning.md

@@ -0,0 +1,56 @@
+# ADR-0009: Use Ballon d'Or-Themed Semantic Versioning
+
+Date: 2026-06-10
+
+## Status
+
+Accepted
+
+## Context
+
+The project uses Semantic Versioning (MAJOR.MINOR.PATCH) for release numbers.
+Release codenames — appended as a suffix to the version tag — need a convention
+that is memorable, consistent within this repository, and thematically
+appropriate for a football-domain project.
+
+Options considered: standard semver only (no names), animal names (arbitrary,
+no thematic link), city names (too generic), and names drawn from the football
+domain (players, clubs, tournaments).
+
+Each of the six sibling repositories in the cross-language comparison series
+adopts its own football-themed naming category. This repository uses Ballon
+d'Or award nominees — one of the sport's most prestigious individual honours.
+
+## Decision
+
+Append an alphabetically ordered Ballon d'Or nominee surname to every release
+tag. Format: `v{MAJOR}.{MINOR}.{PATCH}-{surname}` (e.g. `v1.0.0-aguero`).
+
+The full A–Z list is documented in `CHANGELOG.md`. Surnames are assigned
+sequentially; the current position is tracked by the last released tag.
+The CD pipeline validates the codename against the sequence before publishing.
+
+## Consequences
+
+### Positive
+
+- Alphabetical progression makes release ordering unambiguous at a glance,
+  independent of dates.
+- The Ballon d'Or theme is instantly recognisable in a football-domain project
+  and carries cultural weight: nominees include multiple World Cup winners and
+  the sport's most celebrated players.
+- The convention is deterministic — the next codename is always known in advance.
+
+### Negative
+
+- Non-standard: tooling that expects pure semver tags must be configured to
+  ignore the suffix.
+- The A–Z sequence has 26 slots before a wrap-around or convention change is
+  needed.
+- The CD pipeline must validate codenames, adding a step not present in pure
+  semver workflows.
+
+### Neutral
+
+- The full A–Z list and current position are maintained in `CHANGELOG.md`.
+- The codename is purely cosmetic — semver carries the semantic meaning.

docs/adr/0010-ai-assisted-development-workflow.md

@@ -0,0 +1,76 @@
+# ADR-0010: Adopt AI-Assisted Development Workflow
+
+Date: 2026-06-10
+
+## Status
+
+Accepted
+
+## Context
+
+Software development has historically relied on three successive layers
+of knowledge:
+
+1. **Official documentation** — authoritative but static; describes the
+   intended API but not how real projects apply it
+2. **Community collaboration** — Stack Overflow, GitHub Discussions, blog
+   posts; describes how practitioners actually solve problems, but requires
+   the developer to synthesize and apply that knowledge themselves
+3. **AI synthesis** — models trained on both layers above, capable of
+   applying idiomatic, stack-specific knowledge directly to a given
+   codebase
+
+Agentic AI tools represent a qualitative shift: instead of consulting
+knowledge and applying it manually, the developer delegates implementation
+to an agent that has absorbed the collective idioms of a stack — "the
+Microsoft way", "the Rocket way" — and can apply them consistently.
+
+For a cross-language REST API comparison project, this matters
+particularly: each implementation should reflect how an experienced
+practitioner in that stack would structure the same problem, not a
+generic approach that happens to compile.
+
+Prior to Claude Code, AI assistance was used ad-hoc — pasting code into
+web interfaces (ChatGPT, DeepSeek) or via IDE-integrated assistants
+(GitHub Copilot). Both approaches lack persistent codebase context and
+the ability to act autonomously across a project.
+
+## Decision
+
+We adopt Claude Code as the primary development workflow tool for this
+project.
+
+A `CLAUDE.md` file at the repository root serves as the workflow
+specification: it documents architecture, coding conventions, invariants,
+and explicit boundaries for autonomous operation — what the agent may do
+freely, what requires human approval, and what must never be changed.
+
+CodeRabbit provides an additional automated code review layer
+independent of the primary workflow.
+
+## Consequences
+
+### Positive
+
+- Stack-specific idioms are enforced by the agent's collective knowledge
+  rather than individual developer discipline
+- `CLAUDE.md` is living architectural documentation: it must stay
+  accurate for the workflow to function, creating a natural incentive to
+  keep it current
+- Explicit autonomy boundaries make human oversight intentional rather
+  than incidental
+
+### Negative
+
+- Token economics: long-running work may exceed context limits, requiring
+  active session management and continuation prompts to resume work
+  across sessions
+- The global `~/.claude/CLAUDE.md` and per-repo `CLAUDE.md` must stay
+  aligned; drift between them produces inconsistent agent behavior
+
+### Neutral
+
+- Development workflow moves to the terminal/CLI rather than an IDE;
+  this has no impact on the codebase itself
+- `CLAUDE.md` is specific to Claude Code; a different tool would require
+  a different workflow specification format

docs/adr/0011-spec-driven-development.md

@@ -0,0 +1,61 @@
+# ADR-0011: Adopt Spec-Driven Development (SDD)
+
+Date: 2026-06-10
+
+## Status
+
+Accepted
+
+## Context
+
+In an agentic development workflow, it is easy to begin implementation
+before requirements are fully understood. An AI assistant will produce
+working code from a vague prompt — but working and correct are not the
+same thing. Without a forcing function that requires requirements to be
+stated explicitly before implementation begins, scope creep, rework, and
+misaligned implementations are likely outcomes.
+
+GitHub Issues provide a natural spec artifact: persistent, linkable,
+and — critically — they survive session boundaries. In a workflow where
+context is lost between sessions, an Issue that captures the agreed
+approach and acceptance criteria before implementation begins serves as
+the durable contract between intent and implementation.
+
+## Decision
+
+All new features and non-trivial changes follow a three-step workflow:
+
+1. **Discuss** — describe the requirement in Claude Code Plan mode;
+   explore alternatives and consequences before committing to an approach
+2. **Specify** — create a GitHub Issue as the spec artifact, capturing
+   the agreed approach, acceptance criteria, and any constraints
+3. **Implement** — work against the Issue; commits reference it via
+   the `(#issue)` suffix in the Conventional Commits format
+
+Trivial changes (documentation updates, formatting fixes, dependency
+bumps) may skip the Issue step at the developer's discretion.
+
+## Consequences
+
+### Positive
+
+- Requirements are stated explicitly before implementation; the agent
+  works against a written spec rather than an interpreted prompt
+- Issues survive session boundaries — a new session can resume from
+  the Issue rather than reconstructing intent from scratch
+- The implementation trail (Issue → branch → PR → commit) is traceable
+  without relying on session memory
+
+### Negative
+
+- Adds upfront overhead for changes that feel small; the Issue step can
+  seem bureaucratic for straightforward work
+- The line between "spec-worthy" and "trivial" is judgment-dependent
+  and not enforced by tooling
+
+### Neutral
+
+- GitHub Issues double as the project backlog; SDD and backlog
+  management share the same artifact
+- Plan mode discussion is ephemeral — not persisted outside the session;
+  the Issue is the only durable record of the pre-implementation reasoning

adr/README.md → docs/adr/README.md

@@ -19,6 +19,9 @@ marked `Deprecated` or `Superseded by ADR-XXXX` and a new ADR is written.
 | [0006](0006-embed-migrations-startup-schema.md) | Embedded Migrations at Startup | Accepted |
 | [0007](0007-integration-only-test-strategy.md) | Integration-Only Test Strategy | Accepted |
 | [0008](0008-docker-compose-strategy.md) | Docker and Compose Strategy | Accepted |
+| [0009](0009-ballon-dor-themed-versioning.md) | Use Ballon d'Or-Themed Semantic Versioning | Accepted |
+| [0010](0010-ai-assisted-development-workflow.md) | Adopt AI-Assisted Development Workflow | Accepted |
+| [0011](0011-spec-driven-development.md) | Adopt Spec-Driven Development (SDD) | Accepted |
 
 ## Creating a New ADR