--- title: Policy description: "The rules of the world: invariants, source hierarchy, conventions, and anti-patterns, and how policy weighs conflicting sources." status: new --- ## What Policy Is Before an agent acts, it needs an answer to a question most agents never ask: what must I respect here? Policy is that answer, written down. It holds the rules of the world, declared once per domain and read on every turn. A codebase has invariants that must never break. A finance book has filings that outrank a stray Slack message. A research domain draws a line between a primary source and a secondhand summary. Same engine, different rules, and policy is where the developer states them. The belief state tells the agent what is true. Intent tells it what it is after. Policy draws the boundaries the work happens inside. Drop it, and the agent treats every source as equally credible and every action as equally safe to take, which is how a model talks itself into shipping the wrong thing with full confidence. Policy comes in four buckets, all of them plain natural language: - **Invariants.** Properties that must always hold. "Migrations are reversible." "Every read goes through the scope check." "Net debt reconciles to the balance sheet." - **Source hierarchy.** Which channels outrank which when they disagree, ordered from most authoritative down. - **Conventions.** How work is done here. "Prefer composition over inheritance." "Cite the filing, not the press release." - **Avoid.** Named anti-patterns to steer clear of. "No raw SQL in route handlers." "Don't quote forward-looking guidance as settled fact." ## The Source Hierarchy Of the four, the source hierarchy is the one that earns its keep when evidence collides. Two sources say different things about the same claim. Average them and you land on a confident nothing. The hierarchy says which one to lean on. A code diff outranks a chat message on a claim about what the code does. An audited filing outranks an analyst's inference on a claim about the numbers. The developer writes the ordering once; the world model applies it every time those channels disagree. ```ts { sourceHierarchy: [ 'audited filing', 'primary document', 'analyst inference', 'chat message', ], } ``` This is how the world model adjudicates disagreement instead of papering over it. A flat store hands back every source at the same weight and leaves the agent to re-litigate credibility on every read. The hierarchy settles it once, in the open, where you can read the ordering, hand it to a teammate, and change it. ## Policy Is Guidance, Not a Score Each bucket is human-readable text the developer writes for the domain. No opaque weighting matrix sits behind it, no learned credibility model the agent has to trust on faith. The agent reads the rules as prose and reasons over them, the way a new engineer reads the team's conventions doc on day one. That legibility is the whole point. You can see exactly what the world model treats as a rule, and edit it in one place. When the agent opens a turn, the policy slice of its worldview surfaces all four buckets at once, so it acts already knowing the invariants it can't break, the sources it should weight, the conventions it should follow, and the patterns to avoid. ```ts const { prompt, beliefs, goals, gaps, clarity, moves } = await beliefs.before(userMessage) // The worldview the agent reads carries the policy slice: // invariants, source hierarchy, conventions, avoid. ``` ## Where Policy Meets the Action Set Policy does more than weight evidence. When a worldview is projected, the declared rules run over the action surface and stamp each affordance `allowed`, `flagged`, or `blocked`, with the rule that did the stamping named alongside. An action that trips an active hard constraint comes back `flagged`, the constraint named so the agent knows why. An action a constraint calls out by name comes back `blocked`. Everything else stays `allowed`. So the agent never reads a flat list of verbs; it reads a list already filtered by the rules of the world, each flag carrying its reason. That is the moment policy stops being a note in the prompt and becomes part of the choice. [Actions](/dev/core/actions) covers the action surface itself, its safety classes, and the gating rules in full. ## What Ships Today, and What Doesn't Here is the honest boundary. Policy is a modeling lens the developer encodes in the world definition. It shapes how the worldview is projected and how moves and actions are framed to the agent. It is declarative config: text the developer authors, that the engine reads and surfaces. It is not engine-enforced. The engine does not halt a `mutates` action because an invariant forbids it; it surfaces the rule and the flag, and the agent (or the code wiring the agent) decides what to do with that. An enforced policy surface, where rules are checked and gate execution directly, is on the roadmap, not shipped. There is no `policy.define()` call to reach for, because policy lives in the world definition rather than a runtime registry. Treat the four buckets as the contract the agent is asked to honor, and write your own enforcement around the flags until the declarative surface lands. ## One World, One Set of Rules Because policy is per domain, one engine runs a codebase, a finance book, and a research domain on rules that share nothing. Nothing in the engine presumes what a credible source is or what an invariant looks like. The developer declares it for each world, and the world model adjudicates conflicts and frames actions against exactly those rules. Change the domain, change the policy, and what the agent respects changes with it.