Decisions

Decision Notes

Decision notes record important technical and product choices made during Waste Plus development. They preserve the reasoning behind a choice so that future contributors can understand the context without repeating the original investigation.

Purpose

Write a decision note when a choice has a lasting effect on the system, creates a meaningful trade-off, or would otherwise be difficult to reconstruct later. Examples include:

• selecting a library, framework, database, or integration approach;
• accepting a security, performance, compatibility, or operational trade-off;
• choosing how components or services communicate; and
• recording a deliberate deprecation, migration, or deferral.

Do not use a decision note for routine implementation details, temporary debugging notes, or changes already explained by a short code comment.

Format

Each note uses a unique, zero-padded ADR-NNN number and a short, specific title. Use these sections:

1. Status — Proposed, Accepted, Deprecated, or Superseded.
2. Context — the problem and relevant background.
3. Decision — the selected approach and why it was chosen.
4. Consequences — benefits, costs, risks, migration concerns, and rollback options.
5. Alternatives Considered — realistic options and why they were not selected.
6. Follow-up — remaining work, validation, and ownership.
7. Sources — links to code, issues, pull requests, evidence, or related pages.

Keep notes factual. When a decision changes, update its status and add a new note if a separate decision is made. Do not rewrite an old note to make history appear current.

Decision notes

• ADR 001: Deferred-Bind ConnectionProvider for Transaction-Local GUC — Deferred binding for propagating B3 trace IDs into PostgreSQL audit records.
• ADR 002: Gate 1222 — Monaco + mathjs Security and Parity Verdict — Conditional approval and implementation constraints for Monaco and mathjs evaluation.
• ADR 003: District Average Parity Fixture Contract — External expected-value fixtures, provenance, residual allocation, and the DB-only formula policy.
• ADR 004: District Average Schema Design Decisions — Schema design choices for reporting units, status events, comments, submitters, blocks, and code table deferral.