docs: verify, consolidate and align project documentation

[nanotaboada]

Context

This repo contains a REST API built with Python 3.13 and FastAPI. Project guidance currently lives in two files: CLAUDE.md (a two-line stub with an @ include) and .github/copilot-instructions.md (the actual content). GitHub Copilot is no longer in use, making the split pointless. ADRs exist in docs/adr/ (10 records). The goal is to establish CLAUDE.md as the single source of truth, verify its content against the code, fix stale ADRs if any, and close gaps in .coderabbit.yaml.

Conflict resolution rule

The code is the source of truth. When copilot-instructions.md contradicts what the code actually does, fix the documentation — do not change the code.

Implementation steps

1. Verify copilot-instructions.md against the code

Before copying any content, read the actual code and confirm these claims are still accurate:

• 422 for Pydantic validation, 400 for semantic mismatch: check routes/player_route.py — POST and PUT validation failures should return 422; squad number mismatch on PUT (URL vs body) should return 400
• Alembic migration-only seed: check alembic/versions/ — seed data should be in migration files, not standalone scripts; check that tools/ legacy scripts are not referenced in any active workflow
• aiocache with 10-minute TTL: check services/player_service.py — cache key should be "players" and TTL should be 600 seconds; X-Cache header should be set
• AsyncSession only: spot-check services — session.query() should not appear; only SQLAlchemy 2.0 select() style
• UUID v4 for API records, UUID v5 for migrated records: check routes/player_route.py and alembic/versions/
• Port 9000: check startup command in copilot-instructions.md and any Docker/compose config

Document any discrepancies found. Correct copilot-instructions.md content before moving to step 2.

2. Review and update ADRs

ADRs are in docs/adr/ (0001–0010). Read each one and verify the decision still matches the code. Pay particular attention to:

• ADR-0010 (Alembic Migration-Based Schema Management): confirm seed data lives in alembic/versions/ and not in tools/ scripts
• ADR-0002 (superseded by ADR-0010): confirm status is Superseded and points to ADR-0010
• ADR-0006 (In-Memory Caching with aiocache): confirm TTL value matches code

If any ADR describes something the code no longer does, update its status to Superseded and create a new ADR for the current decision.

3. Consolidate into CLAUDE.md

Replace the entire content of CLAUDE.md with the (now-verified and corrected) content from .github/copilot-instructions.md. Then add:

## Invariants (never change without explicit discussion)

- Port: 9000
- API contract: endpoints, HTTP status codes, and response shapes are fixed;
  do not change them without explicit discussion
- Commit format: `type(scope): description (#issue)` — max 80 chars
- Conventional Commits types: feat fix chore docs test refactor ci perf
- CHANGELOG.md `[Unreleased]` section must be updated before every commit

## Architecture Decision Records

Significant architectural decisions are documented in `docs/adr/` (ADR-0001–0010).
Load these before proposing structural changes. When a proposal would change an
accepted decision, create a new ADR rather than editing the existing one.

Then update the Pre-commit Checks section to add:

7. If this commit introduces or changes an architectural decision, update
   CLAUDE.md and create or amend the relevant ADR in `docs/adr/`.

Delete .github/copilot-instructions.md.

4. Update .coderabbit.yaml

Fix the verify api contract check — replace the existing "400 for bad input" boilerplate with:

Verify that errors return appropriate HTTP status codes:
  - 422 Unprocessable Entity for Pydantic validation failures (payload shape
    or field constraint violations) — NOT 400
  - 400 Bad Request ONLY for semantic errors (e.g. squad number in the URL
    does not match the body on PUT)
  - 404 Not Found for missing resources
  - 409 Conflict for duplicate squad number on POST

Add a path instruction for alembic/versions/**/*.py:

- path: "alembic/versions/**/*.py"
  instructions: |
    - Migration files are append-only once merged. Fix forward with a new
      migration; never edit existing versions. See ADR-0010.
    - Seed data changes must go in a new migration, not standalone scripts.
      ADR-0010 superseded direct seed scripts (ADR-0002); do not re-introduce
      them.
    - render_as_batch=True must remain enabled for SQLite batch ALTER support.

Acceptance criteria

• Every claim in CLAUDE.md has been verified against the current code
• Any discrepancies found during verification are corrected in CLAUDE.md
• Any stale ADRs found during verification are updated (status Superseded) and replaced with a new ADR
• CLAUDE.md contains all content previously in copilot-instructions.md
• CLAUDE.md has an Invariants section and an ADR reference section
• CLAUDE.md pre-commit checklist includes the ADR/CLAUDE.md update requirement
• .github/copilot-instructions.md is deleted
• .coderabbit.yaml verify api contract check correctly distinguishes 422 from 400
• .coderabbit.yaml has a path instruction for alembic/versions/ enforcing append-only migrations
• CHANGELOG.md [Unreleased] updated
• No regressions in existing tests

References

• ADR-0002: docs/adr/0002-no-alembic-manual-seed-scripts.md (superseded)
• ADR-0010: docs/adr/0010-alembic-migration-based-schema-management.md

[coderabbitai]

🔗 Related PRs

#372 - chore: configure Black as the default Python code formatter [merged]
#492 - feat(api): replace integer PK with UUID v4 for Player entity (#66) [merged]
#510 - docs(readme): refresh structure with Mermaid diagram and new sections [merged]
#535 - docs(adr): initialize Architecture Decision Records [merged]
#563 - feat(migrations): implement Alembic for database migrations (#2) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!