AGENTS.md Is Advisory. Here's How to Make It Enforceable

AGENTS.md has become the standard place for coding agents to learn a project's build commands, style rules, and boundaries, with over 60,000 open-source repos already using it. Yet the format's own FAQ admits it's just markdown that agents parse as text—nothing verifies whether the claims are true, and nothing fails when an agent ignores them. A document that lies looks identical to one that doesn't.

getff proposes three mechanical properties to make AGENTS.md genuinely enforceable: every claim must carry an enforcement line naming which gate and toolchain enforces it, with an explicit status (a live-verified checkmark or a specific error code where enforcement isn't possible); claims must be live-fired by real tests, not merely asserted, running both a negative example that should trigger the rule and a positive one that should stay silent; and the document body itself must be generated from source and byte-gated, so any drift on push fails the build.

The approach is demonstrated concretely in getff's own root AGENTS.md: a rule banning direct process.env access is backed by a test that runs the actual ESLint rule against real code samples, and the rule index table is regenerated from the rule files on disk and wired into a pre-push hook. When a rule is edited or removed, a single audit command names exactly which claim no longer matches reality—inverting the usual relationship so the document is derived from live checks rather than describing them from memory.

The honest caveat: this discipline currently works only on getff's own repository. Automatically generating an executable AGENTS.md from an arbitrary team's conventions is a future milestone, not something shipped yet.