decisions

Decision records

This directory holds Architecture Decision Records (ADRs): short, numbered notes that capture a non-obvious choice, why it was made, and what follows from it. They keep the reasoning from being lost and stop settled questions from being relitigated.

How to propose a decision

1. Copy TEMPLATE.md to NNNN-short-title.md, using the next free number (zero-padded, sequential, never reused).
2. Fill in Context / Decision / Consequences and set Status: Proposed.
3. Open a pull request. The decision is discussed and approved on the PR.
4. On approval a maintainer changes the status to Accepted and merges.

Rules that keep the log trustworthy

• One decision per file.
• Append-only. Once a record is accepted, its substance is not edited. Numbers are never reused and records are not deleted.
• Supersede, do not overwrite. To change a past decision, write a new record that replaces it: set the old one to Superseded by NNNN, and note Supersedes MMMM in the new one. The old record stays as history.
• Decision status, not implementation status. A record's status describes the standing of the decision, not whether it has been built. Implementation progress lives in the issue tracker, so an accepted but unbuilt decision links to its tracking issue rather than inventing a status for it.

Status values

Status	Meaning
Proposed	Drafted and under review; not yet agreed.
Accepted	Agreed and in effect; the choice the project currently follows.
Superseded by NNNN	Replaced by a later decision; kept for history.
Deprecated	No longer applies, with no direct replacement.
Rejected	Considered and decided against; kept to record why not.

Records

#	Decision
0001	Diff a structured model of the bill, not document text
0002	Use pypdfium2 (PDFium) as the single PDF text engine
0003	Client-side PDF.js extraction is viable for published bills
0004	Fetch discovery and text from govinfo bulk data, not the Congress.gov API
0005	Keep DeltaTrack a contained two-version tool; put analysis in BillTrax
0006	Make a versioned JSON document the contract between the diff engine and its consumers
0007	Render every diff with one renderer, whatever source pipeline produced it
0008	Deterministic Diff Engine
0009	Validate the parser against independently-authored committee reports
0010	Support a PDF pipeline for pre-publication bills; prefer XML once published
0011	Process user-provided bill content only on the user's machine; no channel may send it off-device
0012	Recover PDF heading levels from deterministic geometry; accept the prose-leading agency gap
0013	Bill identity is the slug; version is a per-bill ordinal, not a universal one
0014	Ship the recoverable heading levels as a conservation-checked tree; defer semantic rollup
0015	Commit a curated corpus fixture set and collect the gates from a manifest
0016	Separate the product, the acquisition tooling, and the delivery channel in the layout
0017	Ship the diff engine as an installable src/deltatrack package