Why AI agent rules break without OS context

A rule like “run the full test suite before committing” sounds straightforward. In practice, ActPlane argues it is anything but: whether a git commit should be allowed depends on which files changed after the last test run, whether the results are still valid, and what the current task permits.

That is the core finding from an empirical study of 64 popular repositories containing CLAUDE.md and AGENTS.md files, captured on 2026-05-23. Across 84 instruction files and 2,116 individual statements, the paper finds developers already write plenty of rules for agents. The hard part is turning those natural-language instructions into something a system can actually observe and enforce over time.

The researchers classify each statement independently rather than by file or section. They report that 64% of the statements are policies that require, forbid, or condition an agent action, while 36% are descriptive context such as architecture notes or project background. Policy density varies sharply, from 0% to 97% across repositories, and 70.1% of repositories contain more policy statements than descriptive ones.

Of the 1,361 policies identified, only 17% are semantic-only, meaning they depend on model reasoning or output style. The remaining 83% are system-observable:

Recommended reading

AI shrinks SaaS teams as coordination costs fall

• 38% require content inspection
• 29% match a single OS event
• 16% require cross-event state

Only the per-event and cross-event categories — 45% combined — are directly OS-enforceable. Cross-event policies are especially common in Development Process, which accounts for 39.5% of all such policies.

Those rules often depend on sequence and state, not just a single action. The paper highlights recurring patterns including temporal ordering, cross-file consistency, multi-step workflows, and conditional triggers. A system must remember what ran, in what order, and what changed since.

Context is another major obstacle. Of the 1,127 system-observable policies, just 26.4% are self-contained. Most — 64.2% — require project context, and another 9.4% need task context such as explicit approval. The problem gets worse for cross-event rules: 95% of them are context-dependent, compared with 58% for content policies.

ActPlane’s answer is a policy model that the agent can write but the OS can enforce. Its rules combine a governed source, a target operation such as exec, write, or connect, an effect, an optional temporal gate, and a reason string for feedback. The paper’s example is:

kill exec “git” “commit” unless after exec “go” “test” exits 0 since write “*/.go”

That would terminate a git commit unless go test has exited successfully after the most recent relevant source edit.

The implementation is relatively small: roughly 3.2K lines of Rust in userspace and 1.8K lines of BPF C for the eBPF enforcement engine. It supports up to 128 concurrent rules, above the largest observed repository’s 66 policies. In the dataset of 607 policies used to exercise the DSL, 66% of clauses are notify, 29% are block, and 5% are kill. Hooks focus mostly on exec (60%) and write (37%), while network and cleanup operations account for under 1% each.

The paper’s broader point is simple: agent rules are not scarce. What is scarce is enforcement that can carry repository context, track state across events, and still make deterministic decisions at the OS layer.