Skip to content

Canonical Hierarchy

When two sources of truth disagree, the higher one wins. This page records the hierarchy and explains why each layer exists.

The hierarchy has accumulated organically — there are now more layers than when the project started, and the order has shifted as the architecture matured. This page is the consolidated record.

The hierarchy (priority order)

  1. ADRs (docs/adr/NNNN-*.md)
  2. Design note (docs/design/DESIGN_NOTE_v2_two_stage.md)
  3. Migrations (src/db/migrations/*.sql)
  4. v0.4 workbook (data/seed/ESG_Screening_Framework_v0.4.xlsx)

Slack handoffs and this ops site are rendered surfaces of these, not authority in themselves. (Exception: this site's /glossary and /operating-model/* pages are canonical and have no upstream.)

Why each layer exists

1. ADRs

Standing design decisions. Read these first if you need to understand why the system is shaped the way it is. ADRs may explicitly supersede design-note content where they say so.

Each ADR is one decision: context, decision, alternatives, consequences. The ADR README (docs/adr/README.md) covers conventions.

2. Design note

The v0.5 architecture rationale — the move from banks-only single-stage to two-stage universal. Decisions, open questions, the journey.

The design note is broader-stroke than an ADR. ADRs may pin specific decisions called out as open in the design note (ADR-0001 pins the score-inflation question, for example).

3. Migrations

The DB is what it is; migrations are the canonical record of how it got there. Notable:

  • 003_schema_v2_two_stage.sql — the v0.5 architecture in schema form
  • 004_seed_non_financial_rules.sql — non-financial rule catalogue
  • 005_seed_pilot_institutions.sql — 8 pilot institutions
  • 009_score_coverage_columns.sql — coverage_pct at all four grains
  • 010_prb_signatories.sql — PRB framework membership
  • 011_coverage_weighted_scoring.sql — per ADR-0001 (pending)
  • 012_source_register_columns.sql — per ADR-0003 (pending)

When schema state and any other source disagree, the DB wins. Migrations are the canonical schema record.

4. v0.4 workbook

The historical framework specification. Documents the original banks-only single-stage design. Remains the framework reference but is not the implementation spec.

A v0.5 workbook refresh is deferred until the pilot validates the design. The current workbook is at data/seed/ESG_Screening_Framework_v0.4.xlsx; see v0.4 workbook reference for what's still true and what's been superseded.

How conflicts get resolved in practice

Example 1 — Scoring methodology

The v0.4 workbook specifies scores computed over all applicable rules, including base-valued ones. ADR-0001 says headline scores are computed only over rules with live signals.

Who wins: ADR-0001 (highest layer). Implementation follows the ADR.

Example 2 — Schema column name

A chat session drafted SQL referencing signal.rule_id. The actual column is signal.rule_id (confirmed by inspection). No conflict, but where chat-side drafts disagree with the live schema, the live schema wins (and the chat artefact gets corrected during apply).

Example 3 — Terminology

ADR-0003 uses source in prose; migrations use signal_source as the table name. The ADR is the higher layer, but terminology in code follows the migration (because that's where the table actually is). The Glossary records both meanings.

Example 4 — Session conduct

Project instructions on claude.ai and .claude/CLAUDE.md both specify session protocol. If they disagree, this site's session-protocol page wins (and the other two get updated to defer to it).

When the hierarchy itself needs to change

If you find yourself wishing a different layer were higher, that's a real signal. The hierarchy was last revised on 19 May 2026 to include ADRs at the top (they didn't exist before). The next likely revision is when the v0.4 workbook drops out entirely — at that point the layer becomes ADRs > design note > migrations.

Changes to the hierarchy itself should be ADR'd. (The decision to introduce this ops site as a rendered-surface layer is ADR-0006.)

What's NOT in the hierarchy

  • Slack handoffs. Event log. The handoff records what happened in a session, not what is true.
  • Chat conversations. Working artefacts, not authority.
  • Prior versions of this site. Git history is the version log; the current state of the site is what's authoritative.
  • Memory / claude.ai project memories. Operational convenience, not authority. Always check the canonical sources for anything that matters.