Decisions

ADR-0001 Terminal documents are frozen A specification repository holds RFCs and ADRs as a record of what was proposed and decided. Each moves through a lifecycle that ends in one of three terminal s... Decided 13 Sep 2026 ADR-0002 Identity is the filename number RFCs, ADRs and refs are referred to from other documents, from the index and from links in prose, and those references have to name something that does not chan... Decided 13 Sep 2026 ADR-0003 Reverse relationships are derived Updated by ADR-0014 A document names the documents it rests on, amends or replaces, and a spec page names the documents it reflects. Every one of those relationships has a reverse:... Decided 13 Sep 2026 ADR-0004 The front matter schema only gains optional keys Every document opens with a front matter block, and the tooling checks that block against a schema for the document's type. Under ADR-0001 a terminal document i... Decided 13 Sep 2026 ADR-0005 The dependency list is closed The tool is a single binary that reads and rewrites Markdown files with YAML front matter, prompts at a terminal, and shells out to git. Each of those needs is... Decided 13 Sep 2026 ADR-0006 Markdown is handled with the standard library The tool reads Markdown to find headings, HTML comments, fenced code blocks and links, and it rewrites Markdown in place: a status in front matter, a heading, a... Decided 13 Sep 2026 ADR-0007 Masking never moves a byte Under ADR-0006 the tool rewrites a file by offset into it as written. Before it searches a body for a heading, a link or a glossary term, it has to set aside th... Decided 13 Sep 2026 ADR-0008 Whether a frozen document changed is decided by git Updated by ADR-0024 Under ADR-0001 a terminal document is never modified, and the tooling has to report any change to one. That means comparing the document in the working tree aga... Decided 13 Sep 2026 ADR-0009 A lint error names something the user may change Updated by ADR-0023 Lint reports findings at two severities, and an error fails the build. Under ADR-0001 a terminal document is never modified. A rule whose subject is the body of... Decided 13 Sep 2026 ADR-0010 Reference rules are monotonic A document names other documents in depends, updates, obsoletes and includes, and lint checks what it names. Under ADR-0001 the naming document may be frozen. I... Decided 13 Sep 2026 ADR-0011 Only the command package imports cobra The tool is a command-line program, and cobra provides its command tree, flags and help. Everything the tool does, reading a repository, checking it, rewriting... Decided 13 Sep 2026 ADR-0012 The licence is AGPL-3.0-or-later The tool is to be open source, and nobody is to be able to freely make money from it. Those two requirements conflict as stated: the Open Source Definition forb... Decided 13 Sep 2026 ADR-0013 The specification is linted by the binary built from the same commit Raised on 2026-09-16, when archdoc init scaffolded this specification directory inside ArchDoc's own repository and wrote a workflow that downloads the release... Decided 20 Sep 2026 ADR-0014 The glossary does not count as implementation Under ADR-0003 a document is implemented when it is accepted and some spec page includes it. The glossary is a spec page, and its includes list is filled in by... Decided 16 Sep 2026 ADR-0015 The former repository names are never reused Raised on 2026-09-20, when the project moved from a personal account to the archdochq organisation. ollieread/archdoc became archdochq/archdoc, and ollieread/ho... Decided 20 Sep 2026 ADR-0016 The scaffolded workflow uses the published actions Raised on 2026-09-21, when archdochq/setup and archdochq/lint were published. The workflow archdoc init writes has carried a thirty-line shell block that resolv... Decided 21 Sep 2026 ADR-0017 The configuration is written at the repository root Raised on 2026-09-21, when ArchDoc's own archdoc.json was found in spec/ with a root of . rather than at the root of the repository it documents. Nothing had de... Decided 21 Sep 2026 ADR-0018 The module path is the project's own domain Raised on 2026-09-21, when archdoc.dev became the project's site. The module path was github.com/archdochq/archdoc, which names the host the code sits on rather... Decided 21 Sep 2026 ADR-0019 The export shape is held stable from 1.0 Raised on 2026-10-14, when a change was weighed that would leave the export's JSON structure as it is but change what one of its fields means. RFC-0004 applied... Decided 14 Oct 2026 ADR-0020 Questions and the Changelog are published as structured data Updated by ADR-0021 Raised on 2026-10-14, while a structured form for a document's questions in the export was being designed. The Changelog was named at the same time as sharing t... Decided 14 Oct 2026 ADR-0021 The rejection rationale is published as structured data Raised on 2026-10-17, while the gate on reject was being changed to judge a document with its rationale in place. Under ADR-0020 a document's questions and its... Decided 18 Oct 2026 ADR-0022 The export schemas are identified by archdoc.dev URLs Raised on 2026-10-15, before any tagged release had emitted schema: 3. Under RFC-0004 a schema's $id is the URL of its published copy, the file in the source re... Decided 18 Oct 2026 ADR-0023 Every finding no permitted edit can clear is a warning ADR-0009 makes a finding that no permitted edit to the named document could clear a warning, and applies it to the rules whose subject is the document's own bod... Decided 3 Nov 2026 ADR-0024 Git is given every path as a name ADR-0008 decides whether a frozen document changed by asking git diff, with pathspecs anchored to the repository root and diff.relative forced off, so the answe... Decided 3 Nov 2026