Decisions

Architecture decision records: numbered, dated, immutable. Each one records a decision that was actually taken, the situation that forced it, and what the project has to live with as a result.

An ADR is not revised when the project later changes its mind — a decision that is revisited gets a new ADR that supersedes the old one, so the record stays a history rather than a snapshot. To add one, copy the most recent file, take the next sequential number, and ship it in the same change that implements the decision.

The pages under Architecture state what the engine is; these state why it is that. Where an ADR needs more depth than its Consequences section can carry, it links to the relevant explanation page rather than repeating it.

• 0001. zdocs is a Zephyr module, included by name
• 0002. Acceptance tests live in a consumer repository, over one cumulative fixture
• 0003. The engine carries its own unit suite, in the engine repository
• 0004. The registry is the single source of truth for document declarations
• 0005. Remote documents are three kinds, not one
• 0006. The deploy tree is organised by builder, not by document
• 0007. Doxygen XML is engine-managed, and lives outside the servable tree
• 0008. The Doxygen tag file is named doxygen.tag
• 0009. Need types and links are a consumer-supplied role→name mapping
• 0010. The engine payload is split by tool, freeing doc/ for documentation
• 0011. Documentation structure: Diátaxis, arc42-lite, and two documents
• 0012. Cross-document links in the HTML tree are relative