Architecture decision records
This directory records the decisions behind redlines 1.0 — the reasoning, the alternatives that were considered and rejected, and the conditions under which each decision should be revisited.
Why these exist
Section titled “Why these exist”docs/PRD.md says what the product is. ROADMAP.md says which release each feature is in. Neither is a good place to keep why a choice was made, because both get rewritten as the product changes, and rewriting erases the reasoning. An ADR is written once, is never edited except to change its status, and is superseded rather than updated. In a year, when someone (including us) asks “why doesn’t redlines write DOCX?”, the answer should be a file, not a memory.
Conventions
Section titled “Conventions”- One decision per file, numbered in the order they were taken:
NNNN-short-title.md. - Status is one of: Proposed (recommended, not yet agreed), Accepted, Superseded by ADR-NNNN, or Deprecated.
- An accepted ADR is not edited when we change our minds. A new ADR is written that supersedes it, and the old one’s status is changed to point at the new one. The trail of superseded decisions is the point.
- Each ADR ends with Revisit when: the concrete signal that should make us reopen it. A decision with no revisit condition is usually a decision that was never really made.
| ADR | Title | Status |
|---|---|---|
| 0001 | Build a format-neutral structural comparison engine | Accepted |
| 0002 | Optimise for LLM and agent pipeline developers | Accepted |
| 0003 | Ship 1.0 with a compatibility facade, not a clean break | Accepted |
| 0004 | Keep a stdlib core with optional extras | Accepted |
| 0005 | Minimal structural core with an open semantic layer | Accepted |
| 0006 | Drive readers with declarative structure profiles | Accepted |
| 0007 | No OCR and no LLM calls inside the library | Accepted |
| 0008 | Align blocks in explainable passes | Accepted |
| 0009 | Detect moves and renumbering in 1.0; splits and merges later | Accepted |
| 0010 | Keep difflib as the leaf differ | Accepted |
| 0011 | JSON as the canonical change format, with an annotated renderer | Accepted |
| 0012 | Address blocks with HTML-like paths and document labels | Accepted |
| 0013 | Limit 1.0 to plain text and markdown | Accepted |
| 0014 | Never write OOXML; delegate tracked changes to appliers | Accepted |
| 0015 | Ship verify mode in 1.0 | Accepted |
| 0016 | Implement the summary renderer in core, deliver it with MCP | Accepted |
| 0017 | Publish the MCP server as a separate package | Accepted |
| 0018 | Use MCP tools, prompts and resources so models can author profiles | Accepted |
| 0019 | Run the demo site entirely in the browser | Accepted |
| 0020 | Ship the MCP server before the site | Accepted |
| 0021 | Make alignment quality measurable with our own benchmark | Accepted |
| 0022 | Keep the name redlines | Accepted |
| 0023 | Keep Python 3.10+ and strict typing | Accepted |
| 0024 | No inline formatting change detection in 1.0 | Accepted |
| 0025 | Treat the CLI and the MCP server as two skins over one function table | Accepted |
| 0026 | Publish the documentation with Astro Starlight, in the same site as the demo | Accepted |
| 0027 | Serve agents with a machine surface and a contract page, not a guide | Accepted |
Evidence base
Section titled “Evidence base”Most of these decisions rest on a survey of the 2026 redlining landscape: competitive-landscape-2026-08.md. Where an ADR cites a competitor’s behaviour, that file has the source.