Architecture Decision Records
Index of operational decisions for the LLMO project.
The Architecture Decision Records (ADR) directory captures operational decisions about how the LLMO project is built and run: infrastructure choices, key custody, CI/CD configuration, deployment topology, organizational structure. Each ADR is a permanent, numbered record of one decision and the context that produced it.
ADRs differ from LIPs in scope. LIPs propose changes to the LLMO specification itself: claim types, schema, signature semantics, normative requirements that apply to all conforming implementations. ADRs propose changes to the project’s operational practice: AWS account structure, signing key custody, build pipeline configuration, hosting choices. As a practical rule, a decision that changes content/spec/ is a LIP candidate; a decision that changes infrastructure/ or operational practice is an ADR candidate. ADR-0000 establishes the practice and discusses the LIP-vs-ADR boundary in more detail.
Format
ADRs follow Michael Nygard’s format: Status, Context, Decision, Consequences. Each ADR states one decision in the present tense. The Consequences section documents both the benefits and the costs honestly; an ADR with no negatives is not credible.
About this directory
The ADR directory is append-only. Numbers, once committed, are never reused. A decision that has been overturned is not edited; a new ADR is added that supersedes the old one, and the old one’s status is updated to Superseded with a pointer to the replacement. The history of what was decided, by whom, and when remains intact.
This append-only property mirrors the LIP registry and exists for the same reason: operational decisions accumulate context that future contributors need to understand even after the decision is overturned.
- ADR-0000 : Bootstrap entry establishing the ADR practice for operational decisions.
- ADR-0001 : Records the structural separation between Diverse.org (501(c)(3) stewarding the LLMO protocol) and Greyfront (Delaware C-corporation pursuing commercial activity).
- ADR-0002 : Records the decision to enforce branch protection on main with no admin bypass, requiring all changes to land via PR with passing CI.
- ADR-0003 : Records the decision to maintain a structured BACKLOG.md with explicit Track tags and CI-enforced conventions for project memory.
- ADR-0004 : Records the decision to authenticate scheduled-workflow PR creation via a GitHub App rather than a Personal Access Token or pull_request_target trigger swap.
- ADR-0005 : Publisher domain control is proven by serving `/.well-known/llmo.json`, not by DNS TXT records. Same model as RFC 9116 security.txt; redundant with file-serving requirement; DNS TXT is reserved for LIP namespace proof.
- ADR-0006 : Within v0.1, patch bumps update the canonical schema file in place, must be back-compatible, and keep llmo_version at 0.1. Releases are cut from the Unreleased section by an explicit run of scripts/cut-release.sh, not by side effect of merging.
- ADR-0007 : LLMO documents are assembled by an LLM agent on the publisher's behalf, not authored by the publisher. The publisher contributes their email of record and consent; the agent derives the rest from public sources, normalizes via the controlled vocabulary, structures under the schema, and tags each claim with provenance markers before the publisher reviews and signs.
- ADR-0008 : The /updates/ surface on llmo.org is auto-generated from the changelog by a Monday weekly pipeline. Empty weeks produce no entry. Human-curated long-form moves to a separate blog.llmo.org surface (planned). The two surfaces have different authoring models and different cadences; conflating them produces drift.
- ADR-0009 : The /llmo Claude Code skill bundled with the open-source llmo CLI emits only the artifacts defined by the LLMO v0.1 specification — llmo.json, the JWKS, the verification TXT records. Companion well-known files (security.txt, llms.txt, robots.txt hygiene) and aggregate "publisher trust" tooling are explicitly out of scope on the llmo.org side and belong to a separate Trust Pack product at llmo.com per the two-entity firewall.
- ADR-0010 : Operational decisions for running the LLMO Key Transparency (KT) registry specified by LIP-4. Records the storage backend, write-path architecture, snapshot signing infrastructure, signing-key custody, availability posture, scaling trigger from flat append-only log to Merkle tree, and the v0.2 federation roadmap.
- ADR-0011 : When a publisher's signing key is observed in any system log the key-holder does not control, the operational response is to generate a fresh keypair, add the new public key to the JWKS alongside the compromised one, re-sign published documents under the new key, and deliberately omit the compromised key from the Key Transparency log. The 90-day JWKS overlap window per spec §4.2 keeps cached documents verifiable during transition; the KT-log omission makes the steward's silence into a meaningful signal.
- ADR-0012 : During the pre-announcement period before the v0.1 public launch, the editor abbreviates or skips self-imposed governance windows (LIP-1 §10 14-day substantive-change window, in-LIP grace periods) under authorship privilege. The choice is recorded in each affected LIP's transitions log so the abbreviation is documented and auditable. Full window observance resumes for substantive normative changes after the v0.1 public announcement.
- ADR-0013 : Resolvers SHOULD attempt a single fixed-subdomain fallback location (`llmo.<primary_domain>/.well-known/llmo.json`) when the primary path is structurally absent. The signed document is unchanged; resolver behavior and rule S3 are amended additively. Subdomain takeover is mitigated by signature verification, not by the discovery mechanism.