Skip to content

docs(adr): reconstruct ADR-009 from the code that cites it - #47

Merged
aurascoper merged 1 commit into
mainfrom
a0/adr-009-generation-runtime-semantics
Jul 28, 2026
Merged

docs(adr): reconstruct ADR-009 from the code that cites it#47
aurascoper merged 1 commit into
mainfrom
a0/adr-009-generation-runtime-semantics

Conversation

@aurascoper

Copy link
Copy Markdown
Owner
head:  3ba774e
base:  main@bc55d6c
lane:  A0  (prerequisite for A; blocks the runtime's 22 citations)
files: 1

The finding

Twenty-two references across eleven files invoke "ADR-009 invariant #N" as normative authority. No ADR-009 file has ever existed on any branch. The decision was made and enforced; only the record was missing.

That's a provenance defect, not a documentation gap: a citation reads as an appeal to a review decision, and eleven files' worth appealed to nothing a reader could open.

Each citation states inline the invariant it relies on, so the document is reconstructible from them. It carries exactly those five and nothing more:

# invariant citations
1 prompt profiles are repository resources; app owns semantic intent, runtime owns transport 2
2 a runtime transmits the prompt without re-instruction or provider-specific reinterpretation 12
3 a new model behind an existing transport is configuration, not a Swift type 3
4 optional behaviour is capability-advertised, not method-mandatory 4
5 canonical benchmark inputs and identities are immutable 1

Invariant 2 dominating is not an accident: it's what lets a recorded promptHash attest the bytes that actually left the process, and 1 and 5 are what keep that hash meaningful over time.

Scope discipline

Commit H's configured/ready split is classified as a later compatible refinement, not reconstructed evidence about original scope. A document inferred from code is already inference; folding in a subsequent decision would be inference presented as history.

Locators are symbols, not lines. Lines move as lane A integrates the runtime, and a locator that rots is worse than none. Historical line numbers appear only as a snapshot pinned to 0dfae3c.

Landed alone, ahead of the runtime

So the registry is provably valid before the citations arrive, and the reconstruction gets its own review surface rather than riding along with 23 runtime files.

Proof

In a scratch export outside the repository — nothing pushed:

11 citing files imported from 0dfae3c, no ADR-009
  hard mode   FAIL, 22 errors
  reported locations set-compared against harvested citations:  EQUAL
  (a count can coincide while the set differs)

same tree + this document
  hard mode   PASS, 0 warnings

On this branch:

check_adr_references.py --mode hard   PASS, 0 warnings
check_adr_references.py --mode all    PASS, 1 warning (historical, preserved)
Tests/eval/test_adr_references.py     16/16
filename ↔ heading                    agree
registry                              contiguous 001–010
git diff --check                      clean

This is the first time D0-R's gate has been exercised against the defect it was built for: lane A cannot now land those 22 citations without this document.

Twenty-two references across eleven files invoke "ADR-009 invariant #N" as
normative authority. No ADR-009 file has ever existed on any branch. The
decision was made and enforced; only the record was missing — a provenance
defect rather than a documentation gap, since a citation reads as an appeal to a
review decision and eleven files' worth appealed to nothing a reader could open.

Each citation states inline the invariant it relies on, so the document is
reconstructible. It carries exactly those five and nothing more:

    1  prompt profiles are repository resources; app owns semantic intent,
       runtime owns transport
    2  a runtime transmits the selected prompt without re-instruction or
       provider-specific reinterpretation
    3  a new model behind an existing transport is configuration, not a type
    4  optional behaviour is capability-advertised, not method-mandatory
    5  canonical benchmark inputs and identities are immutable

Invariant 2 accounts for twelve of the twenty-two: it is what lets a recorded
promptHash attest the bytes that actually left the process, and 1 and 5 are what
keep that hash meaningful over time.

**Commit H's configured/ready split is classified as a later compatible
refinement**, not reconstructed evidence about original scope. Reading it back
into this document would be inference presented as history.

The provenance appendix locates each citation by **symbol**, not line: lines will
move as lane A integrates the runtime, and a locator that rots is worse than
none. Historical line numbers appear as a snapshot pinned to 0dfae3c.

Landed alone, ahead of the runtime, so the registry is provably valid before the
citations arrive and the reconstruction gets its own review surface.

Proof, in a scratch export outside the repository — nothing pushed:

    11 citing files imported from 0dfae3c, no ADR-009
      hard mode  FAIL, 22 errors
      reported locations set-compared against the harvested citations: EQUAL
      (a count can coincide while the set differs)
    same tree + this document
      hard mode  PASS, 0 warnings

On this branch: hard PASS, all mode PASS with the one preserved historical
warning, 16/16 reference tests, filename and heading agree, registry contiguous
001–010.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@aurascoper
aurascoper merged commit cbe511f into main Jul 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant