ADR 0001: Documentation and architecture decision records
ADR 0001: Documentation and architecture decision records
- Status: Accepted; superseded in part by ADR 0016
- Date: 2026-11-03
Context
The project needs a discoverable architecture entry point and a traceable process for decisions. The repository is intended to host its own documentation and must distinguish verified language facts from planning assumptions.
Decision
- Keep normative architecture documentation under
docs/architecture/. - Link to the architecture index from the root README.
- Record consequential decisions in numbered ADR Markdown files.
- Use the status vocabulary defined in the architecture index.
- Keep source provenance for GFA BASIC language and API claims in
docs/reference-sources.md. - Keep Markdown as the human-readable source format and adopt Google's OKF v0.2 bundle conventions as specified by ADR 0016.
Alternatives considered
- A single root-level architecture document: rejected because the planned architecture spans distinct topics and needs independently reviewable decisions.
- An external documentation website: rejected as the canonical source because repository-local documentation must remain usable without a hosted service.
- Unnumbered free-form decision notes: rejected because they do not provide stable references or a clear supersession history.
Consequences
- Documentation changes are reviewable in Git.
- Decisions can be linked from issues and implementation changes.
- Claim only the OKF v0.2 structure and checks actually enforced by the repository validator; do not claim ASD-STE100 certification without identifying and validating the applicable standard/tooling.
- Subsequent ADRs may supersede this decision, but must preserve its historical record.