How architecture decisions are recorded

TOVIO records every significant technical decision as an Architecture Decision Record: one document per decision, capturing the context that forced it, the options considered, the choice made, and the consequences accepted. There are several hundred of them in the repository.

For someone evaluating the project, this is the most useful artifact in the tree. It is the difference between "the vendor says the design is sound" and "here is the reasoning, including what it cost, and you can judge it yourself".

Statuses

The rule that makes the archive trustworthy

You reverse a decision by writing a new record that supersedes the old one — never by silently editing an accepted one. Edits to an accepted record are limited to typo fixes and back-references.

That rule is why the archive is worth reading. A superseded record still states what was believed and why, next to the record that replaced it and the reasoning for the change. The licensing history is a good worked example: the original licensing decision assigned one licence to the Forge, a later record retired it entirely and explained precisely which paragraph of the earlier record it superseded and which parts it explicitly reaffirmed. Neither document was rewritten to look consistent in hindsight.

What is enforced mechanically

• Two records may not share a number — a bare citation must resolve to exactly one decision, and a collision is invisible to an ordinary merge, so a check fails integration on it. The record that claimed a number first keeps it.
• Cross-references are resolved, not just linted for shape: a citation naming a record that does not exist, or naming a real record from the wrong path depth, fails integration.

Which specifications a record binds

Some decisions are described as locked at the start of the project — the language and workspace shape, the canonical serialisation, the content-hashing and chunking choices, the three-tier permission model, the CRDT reference model, the change-identity scheme, the absence of a staging area. Every specification is written assuming them. They change by superseding the record, not by patching specifications around it.

How to use the archive when evaluating

• Start from the decision that worries you, not from the beginning. Cryptographic construction, permission enforcement order, key custody, and the licensing split each have their own records with their rejected alternatives written down.
• Read the consequences section. Accepted downsides are recorded there deliberately — that is where you find what the project already knows it gave up.
• Check for a supersession banner before quoting a record. A record can be accepted overall while one row of its decision table has been superseded, and the banner names which.
• Follow the requirement identifiers. Specifications introduce stable requirement IDs, and code and tests cite them, so a normative claim can be traced from a decision through a specification into the test that covers it.

If you want a decision changed

Write a record. The process is: copy an existing record's format, take the next free number, open it as a change proposal, discuss, and merge it as accepted — or as proposed if it is not yet decided. Contributors are expected to reach for this before a large change rather than after review sends them back.