129Architecture decisions in this project are made implicitly — through code, conversations, and tribal knowledge. When a new contributor (human or AI agent) joins the codebase, there is no record of *why* things are built the way they are. This makes it hard to:
130
131- Understand whether a pattern is intentional or accidental
132- Know if a past decision still applies or has been superseded
133- Avoid relitigating decisions that were already carefully considered
134
135We need a lightweight, version-controlled way to capture decisions where the code lives.
136
137## Decision
138
139Adopt Architecture Decision Records (ADRs) using the MADR 4.0 format, stored in \`${adrDir}/\`.
140
141Conventions:
142- One ADR per file, named \`YYYY-MM-DD-title-with-dashes.md\`
143- New ADRs start as \`proposed\`, move to \`accepted\` or \`rejected\`
144- Superseded ADRs link to their replacement
145- ADRs are written to be self-contained — a coding agent should be able to read one and implement the decision without further context
146
147## Consequences
148
149* Good, because decisions are discoverable and version-controlled alongside the code
150* Good, because new contributors (human or agent) can understand the "why" behind architecture choices
151* Good, because the team builds a shared decision log that prevents relitigating settled questions
152* Bad, because writing ADRs takes time — though a good ADR saves more time than it costs
153* Neutral, because ADRs require periodic review to mark outdated decisions as deprecated or superseded
154
155## Alternatives Considered
156
157* No formal records: Continue making decisions in conversations and code comments. Rejected because context is lost and decisions get relitigated.
158* Wiki or Notion pages: Capture decisions outside the repo. Rejected because they drift out of sync with the code and are not version-controlled.
159* Lightweight RFCs: More heavyweight process with formal review cycles. Rejected as overkill for most decisions — ADRs can scale up to RFC-level detail when needed.
160
161## More Information
162
163* MADR: <https://adr.github.io/madr/>
164* Michael Nygard, "Documenting Architecture Decisions": <https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions>`;
165}
166
167function updateIndexFile(indexFile, { relLink, title, status, date }) {
168 if (!fs.existsSync(indexFile)) return;
169 let content = fs.readFileSync(indexFile, 'utf8');