Each file is a short ADR (Architecture Decision Record) capturing why a non-obvious design choice was made. Numbered chronologically.
ADRs are the cheapest way to keep a future contributor (human or AI) from undoing a decision that was made for a real reason that didn't make it into the code comments.
| ADR | Title | Status |
|---|---|---|
| 0001 | tldextract for PSL-aware SLD/TLD parsing |
Accepted |
| 0002 | Band as (str, Enum) rather than StrEnum |
Accepted |
| 0003 | TLD risk as a JSON bundle with embedded fallback | Accepted |
| 0004 | Wayback queries: 3 small calls, count capped at 2000 | Accepted |
| 0005 | Bot-walled platforms return unknown, not available |
Accepted |
| 0006 | Trademark check defaults to OFF (opt-in) | Accepted |
| 0007 | All score weights centralised in score.py |
Accepted |
| 0008 | LLMO check is permanently marked experimental | Accepted |
| 0009 | Trademark check is deeplink-only (supersedes part of 0006) | Accepted |
When you make a design choice that future readers might want to undo, write a short ADR:
# ADR NNNN: <title>
- **Status**: Accepted | Superseded by ADR NNNN
- **Date**: YYYY-MM-DD
## Context
What problem are we solving? What constraints are in play?
## Decision
What did we choose to do?
## Consequences
What does this make easier? What does this make harder? What is now hard to undo?
## Alternatives considered
What did we look at and rule out, and why?Keep ADRs under 1 page. They are cheap to add but expensive to maintain at length.