What is Policy Linting?

Linting catches the mistakes that are easy to make and hard to spot in review. A structural error that silently changes what a policy matches. A condition that references a misspelled argument name. Two rules with identical conditions but different actions, making the second unreachable. A numeric comparison against a string value that will always evaluate to false. These are the kinds of errors that pass code review because the document looks correct to the human eye but behaves incorrectly at runtime.

Policy linting is particularly valuable because policy errors fail silently in many cases. A rule with a typo in the tool name simply never matches — no error, no warning, just an unprotected tool that the policy author thought was covered. A condition with a wrong operator allows operations that should be denied, with no indication until someone checks the audit trail (if anyone does). Linting surfaces these issues before the policy is deployed.

The linting process analyses policies statically — without executing them or processing actual tool calls. This makes it fast (milliseconds for a full policy directory), safe (no side effects), and suitable for CI/CD integration. A linting step in your policy deployment pipeline catches errors as early as possible, before they can affect agent behaviour.

PolicyLayer validates every policy against the policy schema when it is saved in the dashboard — structure, field names, and value types are checked before the document can become active, so a malformed policy never reaches the gateway. The visual policy builder narrows the space of possible mistakes further: each tool is set to Allow, Deny, Hide, or Custom, and conditions in require and deny_if are composed rather than hand-typed. Policies pasted into the Raw JSON view go through the same validation on save, so the exact document is always well-formed before it is enforced.