Thanks for your interest, and thanks for agreeing that decision records like ADRs belong in version control.
I think it can make sense to have them next to the source code, but this introduces a couple problems like fragmentation of these records (perhaps mitigated if they follow naming conventions like test records do in certain languages/frameworks), and it introduces guesswork to know where cross-section work is documented: I would be curious how you've resolved that?
In this framework, the records live in docs/adr, and we've solved the problem of tight integration with deep-linking (adr://v1/repo/<owner>/<repo>/adr/<n>#<anchor>) and path-independent references. These, or shortcuts (like "adr-0002#qst-how-do-we-do-X"), are used in the code to avoid the problem you're correctly referencing of epistemic drift.
Re: Y-statements, thanks for the reminder, I forgot about those (for other readers, it's a template sentence: "In the context of …, facing …, we decided …, to achieve …, accepting …"). They are completely compatible and complementary with the decision section ORRCF format (I noticed the acronym is explained in the top comment so I won't keep explaining it).
I think it can make sense to have them next to the source code, but this introduces a couple problems like fragmentation of these records (perhaps mitigated if they follow naming conventions like test records do in certain languages/frameworks), and it introduces guesswork to know where cross-section work is documented: I would be curious how you've resolved that?
In this framework, the records live in docs/adr, and we've solved the problem of tight integration with deep-linking (adr://v1/repo/<owner>/<repo>/adr/<n>#<anchor>) and path-independent references. These, or shortcuts (like "adr-0002#qst-how-do-we-do-X"), are used in the code to avoid the problem you're correctly referencing of epistemic drift.
Re: Y-statements, thanks for the reminder, I forgot about those (for other readers, it's a template sentence: "In the context of …, facing …, we decided …, to achieve …, accepting …"). They are completely compatible and complementary with the decision section ORRCF format (I noticed the acronym is explained in the top comment so I won't keep explaining it).