How do I change what a Provely check does?

Rules are optional. With the two lines and no rules file, Provely builds the checks for each agent at run time (just in time), from the tools it finds. To change one, write a rule in .provely/rules.yaml.

The static compiler (provely rules scan, review and sign) is for when you want more. Audit the plan before it runs. Share it with your team in git, or in your Provely account with provely rules sync. Make exceptions for an agent or a tool: skip a check, mark a read-only tool, or set a timeout. Some exceptions need a signature.

A rule changes one setting for one agent or one tool. Some changes need a signature, and some checks can never change.

What are the three nouns?

• Rule: one change to one setting, for every agent, one agent, or one tool.
• Source: a place that holds rules. Your .provely directory is one, and your organisation is another.
• Signature: the proof that a person approved a change. It lives in .provely/rules.sig.

What does a rules file look like?

The keys are agent names and tool names. all means every agent.

# yaml-language-server: $schema=./.cache/rules.schema.json
all:                       # every agent
  enforce: true
refund-bot:
  get_charge:  { read: true, why: "lookup only" }
  issue_refund:
    timeout: 120s
    skip: [fm.tool_timeout]
    why: "batch refunds take minutes"
    until: 2026-12-31
eval-harness: { off: true, why: "offline eval" }

Which keys can a rule set?

You never type who wrote a rule. The tool records it: your code, the scan, the learner, or a person.

Which checks can never change?

• A retry of a call whose outcome is unknown.
• The key of the first attempt on every retry.
• A write, or a call of unknown effect, that repeats a completed write in the same agent call.

A rule that names one of these gets the status refused. The editor schema and the completions leave them out.

Which changes need a signature?

• A value that the model invented.
• A call to a tool that the agent does not declare.
• A duplicate call, and a reused call id.
• The timeout of a tool.
• The posture of an agent, and the effect of a tool.
• The attempt budget, and the arguments that build the idempotency key.
• An added check of a check that needs a signature, and a repair rule that changes a type or a value.
• Every authority check.

An unsigned change to one of these waits. The default holds until a person signs it with provely rules sign. A signed change applies only while the code it names is unchanged.

Which changes apply at once?

• The syntax repairs.
• The checks that only record, and an added check that only records.
• The wording of a re-ask.

A change to one of these applies from any source, and the decision log records it.

What status does a rule get?

Where do rules come from?

The default sources are .provely and provely. .provely is your local directory. provely is the rules of the account of your API key, at /v1/rules. You configure nothing. A developer with no team holds an organisation in their own name, so the key reads their own rules.

• A later source wins on each setting. provely comes after .provely.
• A remote source never blocks the start. The start reads the last good answer from .provely/.cache/sources/, and a refresh runs after the start.
• A source that fails is skipped with one warning. With no API key, Provely skips provely with one warning.
• Set rules: to a list of sources to change the default. rules: [".provely"] stays local.
• A trailing ! marks a source as required. Under strict, Provely refuses to start when a required source has no answer and no cache.

Can I mark the code instead of writing YAML?

Yes. Four markers make the same rules: provely.read, provely.skip, provely.off and provely.name. Each marker gives back the same object. skip and off need a why, and read, skip and off also take an until. A marker obeys the same signature rule as a line in the file.

Does the scan build the same rules as the runtime?

Yes. provely rules scan reads your code before it runs, and the SDK builds the rules when the agent starts. Both build the same rules from the same code. The runtime needs no rules file.

Which commands manage rules?

Does my editor complete the names?

• The SDKs export typed check ids, so your editor completes the id in a marker.
• The first line of rules.yaml names the generated schema, so the YAML extension completes the keys and the check ids.
• provely completions <shell> prints the shell completions of the CLI.