EPIC: Realign org-level ADRs with platform reality, and make supersession detectable

[Polichinel]

The problem

This repository's organization-level ADRs assert things about the VIEWS platform that are no longer true, and nothing detects it.

A review-base-docs audit on 2026-08-13 checked all 11 org-level ADRs outward — against the five sibling repositories and the live GitHub organization, rather than against themselves. Results:

ADR	Claim	Reality
0007 Transform prefixes	Prefixes are the mechanism preventing silent reconciliation errors	Retired platform-wide. views-models ADR-012 (Active): "This convention is retired across the platform." views-pipeline-core ADR-055 cl. 5: "The lr_/ln_/lx_ prefix scheme is deprecated as a scale signal."
0008 Target naming	[pred_]_[transform]_[name] column grammar	Transform component superseded with 0007; PredictionFrame (pipeline-core ADR-042) is deliberately column-name-free
0002 / 0003 Branching	main renamed to production; releases flow development → production	No production branch exists in any of 33 org repositories
0006 Poetry	All Python packages use Poetry	views-baseline and views-reporting use hatchling
0004 Repo naming	All repos named views-*	6 of 33 non-conforming — including docs itself
0009 Notation	y / ŷ / Ỹ / ỹ	Partially adopted: ŷ in views-frames, views-hydranet, views-models; ỹ in the metric labs; Ỹ nowhere

Two are clean and should stay: ADR-0001 (zero notebooks outside notebooks/ across all five core repos) and ADR-0005 (all checked packages on MAJOR.MINOR.PATCH).

Why this matters

ADR-0007 is actively misleading, not merely stale. It presents the prefix scheme as a safety mechanism against silent numerical corruption. The platform has since concluded the opposite — that inferring scale from a column name is itself the unsafe practice (pipeline-core ADR-003, Authority of Declarations over Inference). A modeller consulting the org-level record today gets guidance the platform has explicitly retired, on the single most consequential contract on the platform.

The mechanism that let this happen is structural, and federation makes it more likely. ADR-0000 moved decision authority out to the repositories that own the code — correctly. But it created a one-way gap: the rule tells authors where to put a new decision, and nothing detects a sibling repository deciding something that supersedes an org-level record. ADR-0007 was superseded around 2026-06-08 and nobody noticed for two months.

The validation tooling cannot catch this and was never going to. scripts/validate_docs.sh passes cleanly on the current corpus — links resolve, IDs are unique, the index is fresh. ADR-0007 is well-formed, correctly linked, properly stamped, and wrong. Link-rot and copy-rot are caught; semantic supersession from a sibling repo is not.

Desired end state

1. Every org-level ADR either matches reality or is explicitly marked Superseded/Withdrawn with a pointer to what replaced it.
2. Every surviving record names an accountable owner and a review date, so staleness surfaces on a schedule instead of at audit time.
3. A mechanical check flags org-level ADRs whose subject matter is touched by a newer sibling ADR — turning supersession from something noticed into something reported.
4. The one genuinely organization-level decision currently governed only at repo level — target scale and transform authority — has a þing opened to lift it to the right altitude.

Scope

In scope

• The 11 records under ADR/
• scripts/validate_docs.sh and scripts/check_adrs.py
• reports/technical_risk_register.md — entries updated as stories land
• Templates/adr_template.md where supersession metadata is needed

Out of scope — these belong to other efforts and must not be duplicated here:

• Onboarding guide and internal_technical_guide.md → views-appwrite#26 epic, story docs#82. See the note below.
• Relocating monthly_run_guide.md → views-models#387
• Relocating the technical setup guide → views-pipeline-core#453
• Editing sibling repositories' ADRs. Under ADR-0000 those are theirs. This epic may cite them, open issues against them, and open a þing — it may not rewrite them.
• The Poetry-vs-hatchling engineering decision. This epic scopes the ADR to reality; it does not migrate build systems.

Known collision — please read before starting S1

Issue #83 was closed NOT_PLANNED arguing that the [Internal Tech Guide] link should not be filled while its target describes a setup that hard-fails (views-models tools/credentials/platform_env.sh exits with FATAL: the Appwrite coordinate registry does not exist). During pre-epic work on 2026-08-13 that link was filled anyway, satisfying the link checker while contradicting #83's reasoning.

That edit is unstaged and out of scope here. It should be reverted or reconciled under docs#82 / views-appwrite#26, not under this epic. Flagged so it is not lost.

Stories

#	Issue	Story	Depends on	Labels
S1	#85	Supersede ADR-0007 — transform prefixes retired platform-wide	—	implementation, adr-drift
S2	#86	Reconcile ADR-0008 with ADR-055 and the column-name-free PredictionFrame	#85	implementation, adr-drift
S3	#87	Supersede ADR-0002 and ADR-0003 — no production branch exists	—	implementation, needs-decision
S4	#88	Scope ADR-0006 to reality: Poetry vs hatchling	—	needs-decision
S5	#89	Add an exemption clause to ADR-0004 for non-code repositories	—	implementation
S6	#90	Reconcile ADR-0009 with its actual partial adoption	—	needs-decision
S7	#91	Backfill owner and review_date, promote check to error	#85–#90	implementation, testing
S8	#92	Detect sibling-repo supersession mechanically	#91	implementation, testing
S9	#93	Open a þing on target-scale and transform authority	#85	planning, blocked

Tracking checklist: #94

Sequencing. S1 first: it is the acute finding and the cheapest high-value fix. S2 follows because it must stay consistent with S1's outcome. S3–S6 are independent adjudications and may run in parallel. S7 comes after S1–S6 so effort is spent only on records that survive. S8 comes last of the mechanical work so it is validated against a corrected corpus rather than immediately firing on drift already being fixed. S9 is long-running, cross-repository, and gated on people rather than code.

Epic acceptance criteria

• No org-level ADR contradicts a sibling ADR without an explicit Superseded by pointer
• ADR-0007 and ADR-0008 reconciled with pipeline-core ADR-055 / ADR-042 and views-models ADR-012
• ADR-0002 and ADR-0003 no longer describe a branch topology that exists in zero of 33 repositories
• ADR-0004, ADR-0006, ADR-0009 either match reality or record a deliberate decision to diverge
• Every surviving org-level ADR carries owner and review_date; scripts/check_adrs.py reports 0 warnings
• scripts/validate_docs.sh flags org-level ADRs superseded by newer sibling records, with a test proving it fires
• ./scripts/validate_docs.sh exits 0 and generate_adr_index.py --check passes
• Register entries C-02, C-03, C-06 updated; C-11 and C-12 registered and dispositioned
• A þing is open on target-scale authority, or a recorded decision explains why not

Source

review-base-docs audit, 2026-08-13. Findings: 1 critical, 3 high, 5 medium, 2 low. Register: reports/technical_risk_register.md (6 open, 4 resolved).