Not only is this the only way to have a chance that they stay in sync with the code it also is the right way to make them easy for agents.
Y-statements are a nice way to practically do this.
Not only is this the only way to have a chance that they stay in sync with the code it also is the right way to make them easy for agents.
Y-statements are a nice way to practically do this.
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).
For change justifications, so far we have told the AI to strip change statements from code, and leave that kind of thing to the PR and commit messages. Making that more accessible than hammering git, GitHub can make sense. I'm hoping git protocol and tools catch up to make that more agent friendly, vs the trend of folks making their own new protocols and tools!
Can you clarify what "load the spec hierarchy in as context" as I am not sure if you mean "the files rooted here and below" (which makes sense to me, as intuitively that's a near-decomposable, decoupled description of your hierarchical system); or do you mean "the files above us in the hierarchy" (which describe supersets of context that live above the feature and help inform it)?
I'm not sure what you mean by "hammering" git — git is a robust version control and the overhead for commits is not big.
I don't think it makes sense for git to be overloaded with process information, rather I think it makes sense that, in the same way we have different mechanized programming languages (structured around compilers), we are going to have various standards of deliberative programming (structured around ???) — if you go on WakaTime, you'll see that a growing share of programming is done in Markdown.
It's ultimately AI-controlled, so this is more about hints for inclusion, vs being overly prescriptive nor imperative.