[stephrobert]

Summary

Closes #203. Architecture reasoning that lived in code comments, READMEs and pyproject.toml moves to docs/decisions/: one ADR per decision, in EN (.md) and FR (.fr.md), with an index.

Each ADR has a fixed format:

• Status
• Date
• Context
• Decision
• Consequences
• What would reverse it

The code keeps one line and a link (docs/decisions/NNNN-….md). Behaviour does not change.

#	Decision	Source of the text
0001	Two runtimes, providers underneath	models/runtime.py, CONTRIBUTING, README, design-principles, CHANGELOG 0.1.26
0002	Per-catalogue flock lock, file never deleted (0.1.55)	locking.py docstring, copied in full
0003	ansible-core declared despite its 100 MB (0.1.42)	pyproject.toml
0004	Mutable upstream images (0.1.84)	templates/terraform/README.md
0005	Non-blocking first-boot packages (#178)	templates/cloud-init/README.md, copied in full, counts re-measured on 2026-11-14
0006	The log is in English (#140)	test_journal_en_anglais.py
0007	--json is a contract distinct from schema_version (0.1.46)	reporting/machine.py, models/schema_version.py
0008	Explicit Ruff rule set (0.1.49)	pyproject.toml, with the dated counts
0009	A missing fixture fails run (#177)	CHANGELOG, runtimes/shell.py
0010	degraded lab when the engine is unreachable (#179)	services/lab_state.py
0011	Three outcomes for a check, exit codes 9 and 10 (#172, #176)	doctor_controles/modele.py
0012	Optional hosts: stable index, removal by an apply without -target (#365)	infra/terraform.py, CHANGELOG 0.9.0 / 0.9.1
0013	Refuse out-of-contract hosts, exit code 12 (#357)	CHANGELOG 0.9.1, cli/infrastructure.py
0014	Catalogue table measured on the published repositories (0.9.2)	scripts/gen-catalogues.py docstring

The issue requires that the reasoning is not summarised when it moves. Measurements are copied with their dates.

To review: what is not from a source

• "What would reverse it": most of these sections are new writing. Only 0004 and 0005 had this in their source, and 0001 partly. Some rejected alternatives are also deduced rather than quoted: 0003, 0006, 0007, 0011 and 0014. They are worded cautiously, but they are new text and the maintainer should reread them.
• 0001 carries the date of the first publication (2026-07-15). No text from that time motivates it; only later statements do.
• Two candidates left out on purpose: zero-bash and the mandatory cloud bastion. Their reasoning points to a "REFACTORING-PLAN" that is not in the repository. Writing an ADR would have meant inventing the reasoning.
• One fact corrected: the old gen-catalogues.py docstring said "eight" catalogues were missing in 0.9.2. It was seven, as the CHANGELOG says, and 0014 follows the CHANGELOG.

Type of change

• Bug fix
• New feature
• Refactor
• Documentation
• Chore / tooling
• Security / supply chain

Checklist

Always

• ruff check src/dsoxlab tests tests_e2e fuzz scripts: passed
• mypy src/dsoxlab: no issues in 123 files
• pytest: 2,252 passed
  • tests/test_decisions.py (12 tests) checks four things:
    • each ADR has its sections and its twin in the other language;
    • the numbering is contiguous;
    • the index lists every ADR;
    • every docs/decisions/… link resolves.
  • It fails when a link is broken: renaming the locking.py link gives 1 failed, 11 passed.
  • Two existing tests were adapted. They looked for the decision text in the template READMEs; they now read the ADR and require the link.
• pytest tests_e2e: not run; no packaged code changed except comments
• scripts/generer-doc.py --verifier and scripts/complexite.py --verifier: passed
• Domain-agnostic, no hardcoded path

When behavior changes

N/A for behaviour. CHANGELOG.md / CHANGELOG.fr.md get an [Unreleased] section, Documentation, to ship in 0.9.3.

Commands / workflows / contract

N/A.

🤖 Generated with Claude Code