AGENTS.md is advisory. Here's what it takes to make it executable

The pain: your agent file is a polite suggestion

AGENTS.md is a great convention: one predictable place where a coding agent learns your build commands, style, and boundaries. Over 60k open-source projects ship one.

But look at what the format actually promises. From the official FAQ at agents.md: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." And: "Treat AGENTS.md as living documentation."

Parses the text. Nothing checks whether the text is true, and nothing fails when the agent ignores it. Every claim in your AGENTS.md ("we never read process.env directly", "these rules auto-load", "run make self-audit") is prose. Prose drifts. Agents skip prose under context pressure, and nobody notices, because a document that lies looks exactly like a document that doesn't.

Docs lie; tests don't. So what does it take to make an AGENTS.md that can't lie?