Good breakdown of why code alone doesn't carry intent. One thing worth adding: documentation drifts, and an agent has no way to tell a stale decisions.md from a current one -- it just reads as ground truth either way. A missing README makes the agent guess, which at least reads as uncertain; a wrong one makes it confidently walk the wrong direction, which is worse. Might be worth treating docs the same way you'd treat tests -- some way to check them against the current code, even something crude like a last-verified date next to each doc, or a check that fails when a path a doc references no longer exists -- so an agent isn't trusting a decision that was reversed six months ago.