Files

Gabriel Radureau a24b4fdb3b 📝 docs(adr): homogenize 23 ADRs + rewrite README (Tâche 7 migration) (#18 )

## Summary

Homogenize all 23 ADRs to a single canonical header format, and rewrite `adr/README.md` to match the actual state of the corpus.

This is **Tâche 7** of the ARCODANGE Phase 1 migration (Claude Code → Mistral Vibe). Independent from PR #17 (Tâche 6 — restructure AGENTS.md) — both can merge in any order. No code changes; only documentation.

## Changes

### 1. Homogenize 21 ADR headers (commit `db09d0a`)

The audit (Tâche 6 Phase A, Mistral intent-router agent, 2026-05-02) had identified **3 inconsistent header formats** :

- **F1** — list bullets (`* Status:` / `* Date:` / `* Deciders:`) : 11 ADRs (0001-0008, 0011, 0014, 0023)
- **F2** — bold fields (`**Status:**` / `**Date:**` / `**Authors:**`) : 9 ADRs (0009, 0010, 0012, 0013, 0015, 0016, 0017, 0018, 0019)
- **F3** — dedicated section (`## Status\n**Value** ✅`) : 5 ADRs (0020, 0021, 0022, 0024, 0025)

Plus mixed metadata names (Authors / Deciders / Decision Date / Implementation Date / Implementation Status / Last Updated) and decorative emojis on status values made the corpus hard to scan or template against.

**Canonical format adopted** (see `adr/README.md` for full template) :

```markdown
# NN. Title

**Status:** <Proposed | Accepted | Implemented | Partially Implemented | Approved | Rejected | Deferred | Deprecated | Superseded by ADR-NNNN>
**Date:** YYYY-MM-DD
**Authors:** Name(s)

[optional **Field:** ... lines]

## Context...
```

**Transformations applied** (via `/tmp/homogenize-adrs.py` script, 23 files scanned, 21 modified — 0010 and 0012 were already conform) :

- F1 list bullets → bold fields
- F2 cleanup : `**Deciders:**` → `**Authors:**`, strip status emojis
- F3 sections : `## Status\n**Value** ✅` → `**Status:** Value` (single line)
- Strip decorative emojis from `**Status:**` and `**Implementation Status:**`
- Convert `* Last Updated:` / `* Implementation Status:` / `* Decision Drivers:` / `* Decision Date:` to bold
- Date typo fix : `2024-04-XX` → `2026-04-XX` for ADRs 0018, 0019 (off-by-2-years in original)
- Normalize multiple blank lines after header (max 1)

**ADR body content is preserved unchanged.** Only headers transformed.

### 2. Rewrite `adr/README.md` (commit `d64ab02`)

Previous README had multiple inconsistencies :

- Index table listed wrong titles for ADRs 0010-0021 (looked like an aspirational forecast that never matched reality — e.g. "0011 = Trunk-Based Development" but real 0011 is absent and Trunk-Based Development is actually 0017)
- Listed entries for ADRs 0011 (validation library) and 0014 (gRPC) but **these files do not exist** in the repo
- 0024 (BDD Test Organization) was missing from the detail list
- Template still showed the obsolete F1 format (`* Status:`)
- Decorative emojis on every status entry

Rewrite :

- Index table **regenerated from actual file contents** (title from H1, status from `**Status:**` line) — emoji-free, accurate
- Notes that 0011 / 0014 are not currently in use (reserved)
- Updated template block matches the canonical format
- Status Legend extended with `Approved`, `Partially Implemented`, `Deferred`
- Added note that 0026 is the next free number for new ADRs

## Test plan

- [x] All 23 ADRs follow `**Status:**` / `**Date:**` / `**Authors:**` (verified via grep)
- [x] No more occurrences of `* Status:` (F1) or `## Status` (F3) in any ADR header
- [x] No more emojis on `**Status:**` lines
- [x] `adr/README.md` index links resolve to existing files (no more 0011 / 0014 dead links)
- [x] Pre-commit hooks pass (`go mod tidy`, `go fmt`, `swag fmt`)

## Migration context

Part of Phase 1 of the ARCODANGE migration from Claude Code to Mistral Vibe. Tâche 7 of the curriculum.

Independent from PR #17 (which restructures `AGENTS.md`). The two PRs touch disjoint files — no merge conflict expected when both are merged.

🤖 Generated with [Claude Code](https://claude.com/claude-code) (Opus 4.7, 1M context). Mistral Vibe (intent-router agent / mistral-medium-3.5) did the original audit identifying the 3 formats during Tâche 6 Phase A.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Mistral Vibe (devstral-2 / mistral-medium-3.5)
Reviewed-on: #18
Co-authored-by: Gabriel Radureau <arcodange@gmail.com>
Co-committed-by: Gabriel Radureau <arcodange@gmail.com>

2026-05-03 11:01:13 +02:00

5.1 KiB

Raw Blame History

Architecture Decision Records (ADRs)

This directory contains the Architecture Decision Records (ADRs) for the dance-lessons-coach project. Each ADR captures a structurally important decision, its context, and its consequences.

Index

ADR	Title	Status
0001	Use Go 1.26.1 as the standard Go version	Accepted
0002	Use Chi router for HTTP routing	Accepted
0003	Use Zerolog for structured logging	Accepted
0004	Adopt interface-based design pattern	Accepted
0005	Implement graceful shutdown with readiness endpoints	Accepted
0006	Use Viper for configuration management	Accepted
0007	Integrate OpenTelemetry for distributed tracing	Accepted
0008	Adopt BDD with Godog for behavioral testing	Accepted
0009	Combine BDD and Swagger-based testing	Partially Implemented
0010	API v2 Feature Flag Implementation	Accepted
0012	Git Hooks: Staged-Only Formatting	Accepted
0013	OpenAPI/Swagger Toolchain Selection	Partially Implemented
0015	CLI Subcommands and Flag Management with Cobra	Implemented
0016	CI/CD Pipeline Design for Multi-Platform Compatibility	Accepted
0017	Trunk-Based Development Workflow for CI/CD Safety	Approved
0018	User Management and Authentication System	Proposed
0019	PostgreSQL Database Integration	Proposed
0020	Docker Build Strategy: Traditional vs Buildx	Accepted
0021	JWT Secret Retention Policy	Proposed
0022	Rate Limiting and Cache Strategy	Proposed
0023	Config Hot Reloading Strategy	Proposed
0024	BDD Test Organization and Isolation Strategy	Proposed
0025	BDD Scenario Isolation Strategies	Proposed

Note

: numbers 0011 and 0014 are not currently in use. Reserved for future ADRs or representing previously deleted entries.

What is an ADR?

An ADR is a document capturing one significant architectural decision: the context that motivated it, the decision itself, and its consequences. ADRs are append-only — once published, an ADR is not edited (except for typo / status updates). New decisions that supersede previous ones are recorded as new ADRs that explicitly link back.

Canonical Format

All ADRs follow the canonical format below (homogenized 2026-05-03):

# NN. Short title summarising the decision

**Status:** <Proposed | Accepted | Implemented | Partially Implemented | Approved | Rejected | Deferred | Deprecated | Superseded by ADR-NNNN>
**Date:** YYYY-MM-DD
**Authors:** Name(s)

[Optional fields, all in `**Field:** value` format:]
**Decision Drivers:** ...
**Implementation Status:** ...
**Implementation Date:** ...
**Last Updated:** ...

## Context and Problem Statement

[Describe the context and problem statement.]

## Decision Drivers

* Driver 1
* Driver 2

## Considered Options

* Option 1
* Option 2

## Decision Outcome

Chosen option: "Option 1" because [justification].

## Pros and Cons of the Options

### Option 1

* Good, because [argument].
* Bad, because [argument].

### Option 2

* Good, because [argument].
* Bad, because [argument].

## Links

* Related ADR: [ADR-NNNN](NNNN-slug.md)
* Issue: [#NN](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/NN)

Status Legend

Status	Meaning
Proposed	Decision is being discussed; no implementation yet.
Accepted	Decision has been made; implementation may be pending or in progress.
Approved	Same as Accepted; alternative term used in some legacy ADRs.
Implemented	Decision is fully implemented and in production.
Partially Implemented	Decision is partly implemented; remainder is deferred or pending.
Rejected	Decision considered and explicitly rejected. The ADR documents why.
Deferred	Decision postponed; revisit later.
Deprecated	Decision is no longer relevant; system has moved on.
Superseded by ADR-NNNN	Decision has been replaced by another ADR. Always include the link.

How to Add a New ADR

Pick the next available number (currently next would be 0026).
Copy an existing ADR (e.g., 0001-go-1.26.1-standard.md) as a starting template.
Edit the title, status, date, authors, and content.
Update this README.md index with the new ADR.
Commit using gitmoji convention (e.g., 📝 docs(adr): add ADR-0026 about ...).
Open a PR for review.

5.1 KiB Raw Blame History