ADR 0001 record architecture decisions

ADR-0001: Record architecture decisions with ADRs

fiscalclock records every design decision as an Architecture Decision Record on this wiki, and a change to a decision needs a new ADR with the status Proposed.

Last reviewed: 31 Oct 2026

Status

Accepted on 31 Oct 2026 by maintainer decision. The research documents do not ask for ADRs; the maintainer's brief for the wiki does. This record is Decided.

Context

People use fiscalclock's results for financial reporting dates. A reader needs to know why the library behaves as it does, what evidence supports each behaviour, and whether a behaviour is settled or still open. The research proposal lists eight decisions to make before v0.1 and makes many more implicitly. The gap analysis then changed several of them. Without a record, the reasons stay in two long documents and in commit messages, and a contributor cannot tell a deliberate choice from an accident.

AGENTS.md ("When an ADR is required") lists the changes that need an ADR first: the definition format, the result of any operation for a valid input, the public API or error codes, core dependencies, supported versions, scope or licence.

Decision drivers

• Every behaviour must be traceable to cited evidence or a reproducible check.
• Readers must see at a glance whether a decision is Decided or Proposed.
• Recording a decision must be cheap enough that it actually happens.
• The record must be public and linkable from the README, the spec and issues.

Considered options

Option 1: ADRs as Markdown files in the repository (for example docs/adr/)

Pros:

• Changes go through pull-request review and CI (Markdown lint, spelling, link check).
• The decision and the code that implements it can land in one pull request.

Cons:

• docs/ is reserved for user documentation in the repository map, so ADRs would need a new top-level folder.
• The design documentation (PDR, Analysis, Evidence) already lives on the wiki, so ADRs would be split from the pages they cite.

Option 2: ADRs as wiki pages in MADR layout

Pros:

• They sit next to the PDR, Analysis and Evidence pages they cite, with short wiki links.
• The README already links an ADR index on the wiki.

Cons:

• Wiki edits do not go through this repository's pull-request review, so an ADR can change without a reviewer. The mitigation is that a change to a decision is a new ADR, not an edit.
• CI in this repository does not lint the wiki; the wiki writer must run the same Markdown and spelling checks by hand.

Option 3: Decisions recorded only in GitHub Discussions

Pros:

• Discussion is where the options get argued, so nothing is copied.

Cons:

• A thread mixes argument and outcome; the final decision is hard to find.
• No fixed structure, so the drivers and consequences are often missing.

Option 4: No formal record

Pros:

• No overhead.

Cons:

• Reasons are lost, and the evidence rules in AGENTS.md cannot be checked.

Decision

Option 2. Each decision is a wiki page named ADR-NNNN-short-slug in the MADR layout: Status, Context, Decision drivers, Considered options with honest pros and cons, Decision, Consequences, Links. The ADR index lists them all.

An accepted ADR is not rewritten to change its outcome. To change a decision, write a new ADR with the next number and the status Proposed, link the ADR it would supersede, and open a thread in the Design decisions category of Discussions once the maintainer has created that category. The new ADR is not implemented while it is Proposed. When it is accepted, the old ADR's status becomes Superseded with a link to the new one.

Status values are Proposed, Accepted, Rejected and Superseded, as in the Glossary. Each status line names who decided: the research documents, the maintainer, or the maintainer's delegation (the maintainer asked for the roadmap and 0.1.0 to be decided and built without them).

Consequences

Good:

• Every 0.1.0 behaviour that departs from or fills a gap in the research proposal has a page that says why.
• Contradictions D1 to D12 in the source documents have a place to be named and tracked (see PDR).

Bad:

• Wiki pages are outside the repository's review and CI, so the ADR writer carries the burden of running the checks.
• ADRs and code can drift: an ADR can say one thing while the spec says another. The spec in spec/ is normative for what is built; an ADR that disagrees with it needs a new ADR or a spec fix.

Links

• ADR index, Glossary, PDR, Roadmap
• AGENTS.md, sections "When an ADR is required" and "Design rules"
• CONTRIBUTING.md
• MADR: adr.github.io/madr