Skip to content

Decision Log

Architecture Decision Records (ADRs) for the ESG Screening system. Each ADR records one standing design decision: context, what was decided, alternatives, consequences.

The canonical files live in the main repo at docs/adr/. This site renders them for navigability.

For ADR conventions, see the ADR README in the main repo.

ADR index

# Title Status Date
0001 Coverage-Weighted Scoring Superseded by ADR-0012 2026-05-19
0002 UI Architecture — Server-Rendered Read Interface Accepted 2026-05-19
0003 Source Register and Methodology Page Accepted 2026-05-19
0004 RAG Thresholds for Score and Coverage Accepted 2026-05-19
0005 Rule Grouping in the Institution Detail UI Accepted 2026-05-19
0006 Ops Site as Rendered Standing-Reference Surface Accepted 2026-05-19
0007 score_value Deprecation + Data-Model Column-Naming Hygiene Accepted 2026-05-22
0008 Universal hard-exclusion flag semantics Accepted 2026-05-19
0009 Amendment 1: GICS code corrections (cycle 3) Accepted 2026-05-20
0009 GICS classification for pilot institutions Accepted 2026-05-20
0010 Amendment 1 — UN-S1 fallback chain and universal-rule source discipline Accepted 2026-05-20
0010 Amendment 2 — Deduction-rule signal-state labelling Accepted 2026-05-21
0010 Amendment 3 — UN-G4 / G7 overlap: scope differentiation Accepted 2026-05-21
0010 Universal rule layer (UN-prefixed rules) Accepted 2026-05-20
0011 Per-scraper inheritance via parent_lei / operating_arm_lei Accepted 2026-05-20
0012 Scoring methodology: neutral-prior baseline Superseded 2026-05-21
0013 Seed compilation scope for seed-backed scrapers Accepted 2026-05-21
0014 CHRB source instrument clarification Accepted 2026-05-21
0015 FOREST500 source-instrument clarification and scoring decisions Accepted 2026-05-22
0016 INFLUENCEMAP + CA100PLUS source scoping accepted —
0017 SBTi dashboard status taxonomy: "Commitment Removed" ≠ withdrawn_commitment Accepted 2026-05-22
0018 SFDR / EU-Taxonomy signal: assessed and declined for Phase 1; not built Accepted 2026-05-23
0019 NGO-TARGETS broad-roster (ShareAction) pass — assessed and declined for Phase 1; seed complete at cycle-15a high-confidence state Accepted 2026-05-23
0020 Auto-render plumbing for universe page, ADR index, and CLAUDE.md Accepted 2026-05-23
0021 Post-close universe addition: Alcon, Assa Abloy, Novartis (holdings reconciliation) Accepted 2026-05-23
0022 Neutral-prior fix A(ii) — positive rule scraped-negative → OMIT, not zero Accepted 2026-05-23
0023 Neutral-prior fix A(iii) — deduction rule baseline re-anchored to 50 Superseded —
0024 Remove G5.3 and G7.4 documentary +5 sub-rule rows Accepted 2026-05-23
0025 TPI Management Quality — seed-backed, identity map via staircase Accepted 2026-05-24
0026 Baseline anchor → 100; deduction formula k=45; composite fallback fix Accepted 2026-05-24
0027 CORP-WEBSITE and IFRS-S2-CORP: permanent drop, external-only screen Accepted 2026-05-24
0028 Lever B: per-sub-industry denominator exclusion for asset managers Accepted 2026-05-24
0029 BHRRC→NF-S4 severity-modelled wiring Accepted 2026-05-24
0030 Deferred-but-non-viable source: treated as dropped for rule-retirement purposes Accepted 2026-05-24
0031 Symmetric baseline-100 scoring model; weapons hard-floor Accepted 2026-05-25

When to write a new ADR

Per the ADR README, write one when a decision:

  • affects how the system is built, displayed, or scored, AND
  • is non-trivial to reverse, AND
  • a future contributor (including future-you) would benefit from understanding the reasoning.

Examples that should be ADRs:

  • Scoring methodology choices
  • UI architecture
  • Source-register conventions
  • Schema decisions of structural importance
  • Authentication model
  • Framework structure

Examples that should not be ADRs:

  • Bug fixes
  • Individual scraper implementations (those follow the add-a-scraper runbook)
  • Copy edits
  • Dependency upgrades

ADR conventions

  • Numbering: sequential, 4-digit, zero-padded. Never reused.
  • Filename: NNNN-kebab-case-slug.md
  • Status values: Proposed · Accepted · Superseded by NNNN · Deprecated
  • Length: aim for one page, max two. If longer, the decision is probably two decisions — split.
  • Tone: plain language. Audience is a future engineer, not a methodology committee.

ADR process

  1. Decisions surfaced in chat sessions are captured as ADR drafts in that session's outputs (/mnt/user-data/outputs/).
  2. The session-end Slack handoff names the new ADRs.
  3. The next CC-on-VM session commits the ADRs to docs/adr/ as its first action of the cycle.
  4. Code that implements an ADR should reference the ADR number in a comment or PR description.
  5. When an ADR is superseded, both files are updated in the same commit: the old one's status changes to Superseded by NNNN, the new one references it under Supersedes.

Cross-references

ADR Implemented by Referenced by
0001 Migration 011, scoring engine modules 0002 (hero panel design), 0004 (coverage colour)
0002 src/ui/, Express routes 0003 (Methodology page route), 0004 (palette), 0005 (rule table)
0003 Migration 012, /methodology route 0002 (page slot), 0001 (scoring explainer content)
0004 src/config/rag.js, base stylesheet 0002 (where colour is applied), 0001 (coverage band)
0005 src/config/rule-themes.js, detail page template 0002 (rule evaluation section)
0006 This site, Cloudflare Pages deployment All of the above (rendered surface)