From 3c3293aebb7c151782e97d4d0d1a2b65d10bd8f2 Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 12 Jun 2026 12:25:47 +0200 Subject: [PATCH] divergence register -> docs/architecture (living doc) + CLAUDE.md rules: same-commit row discipline, symptom-scan trigger, phase-checklist hook --- CLAUDE.md | 25 +++++++++++++++++++ .../retail-divergence-register.md} | 0 2 files changed, 25 insertions(+) rename docs/{research/2026-06-12-retail-divergence-register.md => architecture/retail-divergence-register.md} (100%) diff --git a/CLAUDE.md b/CLAUDE.md index a41dc517..a7d83157 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -457,6 +457,28 @@ isn't enough, attach cdb to a live retail client (Step -1).** source was safe; replacing the entire transform composition broke everything. +### The divergence register (mandatory bookkeeping) + +[`docs/architecture/retail-divergence-register.md`](docs/architecture/retail-divergence-register.md) +is the single auditable list of every KNOWN place acdream's runtime +behavior can deviate from retail (108 rows at creation, 2026-06-12: +intentional architecture / adaptation / approximation / stopgap / +unclear). Two rules, both binding on subagents too: + +1. **Any commit that introduces a deviation** (an adaptation, an + approximation, a stopgap, a "retail does X but we...") **adds its + register row IN THE SAME COMMIT.** Any commit that ports the retail + mechanism deletes the row in the same commit. A deviation found + without a row is a bug twice over. +2. **Any unexplained visual/physics symptom → scan the register BEFORE + instrumenting.** The "Risk if assumption breaks" column is written as + the symptom you'd observe (the #119 vanishing staircase, the #112 + transparent cottage, and the knife-edge flap all lived in rows of + this register's scope before they had names). + +The register holds one-line rows and pointers — detail lives at the +cited `file:line` and in the digests, never in the register itself. + ### What NOT to do: - **Do not guess** at AC-specific algorithms, formulas, constants, wire @@ -491,6 +513,9 @@ Before marking any phase as done: - [ ] Every AC-specific algorithm has a decompiled reference cited in comments (named symbol + address from `named-retail/symbols.json`, OR function address + chunk file from older `decompiled/` chunks) +- [ ] Every retail deviation this phase introduced has a row in + `docs/architecture/retail-divergence-register.md` (and every + deviation it retired had its row deleted) - [ ] Conformance tests exist for the critical paths - [ ] The code was cross-referenced against at least 2 reference repos - [ ] `dotnet build` green, `dotnet test` green diff --git a/docs/research/2026-06-12-retail-divergence-register.md b/docs/architecture/retail-divergence-register.md similarity index 100% rename from docs/research/2026-06-12-retail-divergence-register.md rename to docs/architecture/retail-divergence-register.md