Repository navigation
[DDD/Delivery Gap] Normalize ADR identity and retire per-stack duplicate numbering #437
Description
Problem
Repository-wide ADR identity remains a delivery-integrity concern. ADR numbers are architectural identity, not branch-local labels. Historical duplicate index/file identities and repeated status/maturity authority make ownership and integration ambiguous.
Required outcome
- one immutable repository-wide ADR identity per architectural decision;
- one index row per identity and no duplicate numeric file prefixes or targets;
- deterministic failure for duplicate IDs before set conversion, duplicate targets/files, index/filename mismatch, and Decision-status / Implementation-maturity authority drift;
- adapter/model micro-slices fold into owning bounded-context ADRs rather than minting branch-local architecture authority;
- surviving ADR links,
ARCHITECTURE.md, Context Map, TRACEABILITY, PRD/TRD and landing-vehicle docs stay coherent; - exact surviving-head documentation validation and all live hosted gates GREEN before landing.
Safety / queue policy
Do not independently renumber active stacks, force-push, or close lineage merely to reduce WIP. Normalize through #435 and bounded-context landing vehicles. A predecessor closes only after a verified successor contains every still-valid decision, test, fixture, contract and evidence delta.
Current landing evidence — 2026-09-03 KST
Normalization remains implemented in existing queue-authority vehicle #435 rather than another governance micro-PR. Fresh #435 source head is 137966184f3f34bafbe66e641698d6127ec6d65b against protected main@1bc02f580cf48e1d39da239f0e818453437c31c3. Live queue is 134 open PR / 134 Draft / 0 non-Draft / 16 open issues / 0 releases. docs/product-technical-gap-baseline.md is source-current on that #435 head and intentionally omits #435's self-head from the file body.
#310 is the Longitudinal Modeling landing vehicle at exact head 34fd059aa10c7538f3513b6fb994a9f2972ff5b1. Fresh RED ae5e61f9a829adbfed2ea13c5705d4b85d80b0d6 exposes mixed-sign retained-mean double rounding: minimum-subnormal [-20u, -20u, 9u] has exact mean -31u/3 and must round once to -10u, while the predecessor rounded a retained-only mean before count weighting and produced -11u. Causal repair 39469067aca2fa93e2fa4c914848f7cec8031811 applies the original sample-count denominator directly inside the normalized compensated sum. Contract hardening 201f3900960278cb87d2e6b28176ac0d23e51954 exercises the same boundary through public occasion-mean composition, and research trace 34fd059aa10c7538f3513b6fb994a9f2972ff5b1 makes the algorithm description code-current. This remains Longitudinal numerical repair, not a new ADR identity or reusable static psychometric authority.
#486 remains #310's Draft fold child. Valid Hamaker occasion-mean evidence is preserved owner-correctly; wrong-context psychometric_core temporal source, raw-bit signed-zero identity, naive mean accumulation, and mixed Z KST provenance remain intentionally rejected. It stays open until every remaining valid operational/CHANGELOG delta is inherited or verified redundant.
#416 remains the Validation / Analysis Run landing vehicle at 0b7155cc238defb1e55129ff3000658f04b343cf. #458/#460/#482/#483/#484/#485/#487 are current fold children. #487's RED a2892b6ad4f632882f63da39eed2d4706ddf9213, repair a64020152300232cb3214a66b45d97225b6d2b5b, and predecessor-test correction 6b0c8de64f41bc11f8bf908e0f9cbe854c1e213c preserve the rule that Allen relation classes are observed data, not mandatory production design strata. ADR 0079 remains implementation lineage pending repository-wide normalization, not independent architecture authority.
The #435 branch retains deterministic fitness for duplicate ADR index identities before set conversion, duplicate targets, duplicate numbered root ADR files, index/filename mismatches, duplicate Decision-status / Implementation-maturity authorities, and index-vs-file drift. tests/quality/test_adr_identity_uniqueness.py remains the regression surface.
Live ruleset 18156473 requires one qualifying current-head approval, dismisses stale approvals after push, requires resolved review conversations and extra approval for unattributed changes where applicable, and enforces central required workflows. Merge/squash are allowed; non-fast-forward updates are prohibited. Admin bypass is not normal delivery evidence and is not used by this writer.
At #310 exact head 34fd059a..., Documentation Quality, SAST Semgrep, Rust Foundation CI, Security Scan, Scorecard PR, and OSV-Scanner PR are queued; current check-runs do not yet materialize a CodeQL check, and fresh review submissions contain no qualifying APPROVED. The new #435 source push likewise invalidates predecessor-head check/review evidence for #435. This issue remains open; child-head evidence, self-approval, force push, destructive rebase, or routine bypass cannot satisfy the surviving-head landing bar.
Activity
feat(analysis): fold location-membership into landing vehicle
feat(analysis): fold episode-membership into landing vehicle
feat(analysis): fold subevent-containment into landing vehicle
feat(analysis): fold membership-target into landing vehicle
docs(adr): use an admitted Implementation maturity value on ADR 0079
seonghobae commentedon Sep 15, 2026
The duplicates exist today, and the checker cannot see them
Measured on plain
origin/mainata243f18d.Two ADR numbers are carried by two files each:
0021-deterministic-analysis-run-execution.md,0021-lineageweave-project-history-boundary.md0024-independent-topic-importance-anchor.md,0024-lineage-pair-criterion-and-project-journey-posterior.md29 ADR files, 27 distinct numbers.
python3 scripts/validate_documentation.pyreports passed.Why it passes
validate_adr_graphcollects files into a dict keyed by the number:The second file with a given number overwrites the first. By the time the function reaches
file_numbers = set(adr_files), the duplicate is gone, so the index/file comparison sees 27 numbers on both sides and agrees. The surviving entry is whichever sorts last,0021-lineageweave-project-history-boundary.mdand0024-lineage-pair-criterion-and-project-journey-posterior.md, which also means the metadata checks below only ever inspect one of each pair.This issue's required outcome already names the mechanism: "deterministic failure for duplicate IDs before set conversion". That is exactly where the information is lost.
What I did not do
I did not add the detection, and I did not renumber anything.
Adding the check alone would turn
validate_documentation.pyred onmain, because the two duplicates are real. That would block every open pull request on a condition none of them caused, which is the same shape as the threemaindefects I am already repairing in #517, #526 and #538. The gate and the renumbering have to land together or in that order.Renumbering is explicitly out of my hands under this issue's own safety policy: normalize through #435 and the bounded-context landing vehicles, not independently.
So this is a report, not a change. The detection is a three-line edit once the duplicates are resolved, and I am happy to prepare it as a follow-up branch that a maintainer lands immediately after the renumbering, if that sequencing is wanted.
Related
The same failure mode, a collection that silently discards evidence before the check runs, is what I repaired in #538 for coverage records and in #520 for the database naming contract. It is worth knowing that this repository's gates have had three independent instances of it.