TRACKING — Epic #84: realign org-level ADRs with platform reality

[Polichinel]

Epic: #84

Checklist for epic #84. Work the stories top to bottom and tick them off. Each links to a fully specified issue — context, work, acceptance criteria, and validation commands live there, not here.

Phase 1 — Retire what is wrong (no dependencies between these three)

• S1 — Supersede ADR-0007: the transform-prefix convention was retired platform-wide #85 · S1 — Supersede ADR-0007: transform-prefix convention retired platform-wide
  Start here. The one actively misleading record. Blocks S2 — Reconcile ADR-0008 with ADR-055 and the column-name-free PredictionFrame #86 and S9 — Open a þing on target-scale and transform authority #93.
• S2 — Reconcile ADR-0008 with ADR-055 and the column-name-free PredictionFrame #86 · S2 — Reconcile ADR-0008 with ADR-055 and the column-name-free PredictionFrame
  Depends on S1 — Supersede ADR-0007: the transform-prefix convention was retired platform-wide #85. Half supersedes, half survives — pred_ is still live in code.
• S3 — Supersede ADR-0002 and ADR-0003: no 'production' branch exists in any of 33 repos #87 · S3 — Supersede ADR-0002 and ADR-0003: no production branch in any of 33 repos
  Independent of S1 — Supersede ADR-0007: the transform-prefix convention was retired platform-wide #85/S2 — Reconcile ADR-0008 with ADR-055 and the column-name-free PredictionFrame #86. The Contribution Guides are already right — do not "fix" them.

Phase 2 — Adjudicate the rest (fully parallel; each needs a human call)

• S4 — Scope ADR-0006 to reality: Poetry vs hatchling #88 · S4 — Scope ADR-0006 to reality: Poetry vs hatchling
  ⚠️ needs-decision. Scopes the ADR only; migrating build systems is out of scope.
• S5 — Add an exemption clause to ADR-0004 for non-code repositories #89 · S5 — Add an exemption clause to ADR-0004 for non-code repositories
  Smallest story in the epic. .github cannot be renamed; docs violates its own rule.
• S6 — Reconcile ADR-0009 with its actual partial adoption #90 · S6 — Reconcile ADR-0009 with its actual partial adoption
  ⚠️ needs-decision. Note the audit correction: ŷ and ỹ are adopted; only Ỹ is not.

Phase 3 — Make staleness visible (strictly sequential)

• S7 — Backfill owner and review_date, then promote the check from warning to error #91 · S7 — Backfill owner and review_date, then promote the check to error
  Depends on S1 — Supersede ADR-0007: the transform-prefix convention was retired platform-wide #85–S6 — Reconcile ADR-0009 with its actual partial adoption #90. Only assign accountability for records that survive. Ends with check_adrs.py at 0 warnings.
• S8 — Detect sibling-repo supersession mechanically #92 · S8 — Detect sibling-repo supersession mechanically
  Depends on S7 — Backfill owner and review_date, then promote the check from warning to error #91. The capstone. Must be tested against a reconstructed ADR-0007 case — a detector that would not have caught it is not done.

Parallel track — open early, runs long

• S9 — Open a þing on target-scale and transform authority #93 · S9 — Open a þing on target-scale and transform authority
  Depends on S1 — Supersede ADR-0007: the transform-prefix convention was retired platform-wide #85. blocked on seat-holders across five repositories. Open it early; do not let it gate Phases 1–3.

---

Epic acceptance — verify before closing #84

• No org-level ADR contradicts a sibling ADR without an explicit Superseded by pointer
• Every surviving record carries owner and review_date; check_adrs.py reports 0 warnings and 0 errors
• Supersession detection exists, is wired into validate_docs.sh, and has a passing offline test
• ./scripts/validate_docs.sh exits 0
• python3 scripts/generate_adr_index.py --check passes
• grep -c '_unassigned_' ADR/index.md returns 0
• Register: C-02, C-03, C-06 updated; C-11 and C-12 registered and dispositioned
• þing open on target-scale authority, or a recorded decision explaining why not

Run after every story

./scripts/validate_docs.sh
python3 scripts/generate_adr_index.py && python3 scripts/generate_adr_index.py --check

Regenerate ADR/index.md whenever a status changes — it is generated, and CI checks it is current.

---

Out of scope — do not pick these up here

Work	Belongs to
Onboarding guide, internal_technical_guide.md	#82 · epic views-platform/views-appwrite#26
Relocating monthly_run_guide.md	views-platform/views-models#387
Relocating the technical setup guide	views-platform/views-pipeline-core#453
Editing sibling repositories' ADRs	Their repositories — ADR-0000 cl. 2
Migrating build systems	Follow-on issues from #88, if the decision requires them

⚠️ Known collision — read before touching the onboarding guide

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 (lines 75, 114, 125, 149 on origin/development).

During pre-epic work on 2026-08-13 that link was filled anyway. It satisfies the link checker and contradicts #83's reasoning. The change is unstaged and belongs to #82, not this epic. Reverting or reconciling it is a decision for that epic's owner.

Source

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

[Polichinel]

Phases 1–3 complete. 8 of 9 stories closed.

• S1 — Supersede ADR-0007: the transform-prefix convention was retired platform-wide #85 · S1 — ADR-0007 superseded
• S2 — Reconcile ADR-0008 with ADR-055 and the column-name-free PredictionFrame #86 · S2 — ADR-0008 narrowed, Target Naming Catalog resolved (it never existed)
• S3 — Supersede ADR-0002 and ADR-0003: no 'production' branch exists in any of 33 repos #87 · S3 — ADR-0002/0003 superseded by new ADR-0011
• S4 — Scope ADR-0006 to reality: Poetry vs hatchling #88 · S4 — ADR-0006 scoped tool-neutral (provisional)
• S5 — Add an exemption clause to ADR-0004 for non-code repositories #89 · S5 — ADR-0004 exemptions closed; all 33 repos classified
• S6 — Reconcile ADR-0009 with its actual partial adoption #90 · S6 — ADR-0009 kept, Ỹ scoped to prose
• S7 — Backfill owner and review_date, then promote the check from warning to error #91 · S7 — owner/review_date backfilled; check promoted to error
• S8 — Detect sibling-repo supersession mechanically #92 · S8 — supersession detector, 8 offline tests, ADR-0007 regression proven
• S9 — Open a þing on target-scale and transform authority #93 · S9 — þing opened, awaiting G1 → þingit/03_target_scale_authority/

Epic acceptance: all criteria met except the two that depend on #93. validate_docs.sh exits 0 · --check passes · check_adrs.py 0/0 · unittest 8/8 · _unassigned_ = 0 for active records · register 12 total / 6 open / 6 resolved.

Two corrections landed during execution, both against my own earlier findings: ADR-0009 was called zero-adoption on a four-repo grep for its rarest symbol (it's widely used); and C-01 was recorded as resolved when the record it 'fixed' had already been retired platform-wide. Both are written into the artifacts, not just here.

Next: G1 on the þing — confirm roster and weight, then open a session in views-pipeline-core and run /thingit.