Decionis Policy Spec v1
Your policy decides whether an action may run. The people who own the risk write it in their own words; PolicyAgent encodes it; a named person accepts every version before it decides anything. This page is the contract for each of those steps.
Overview
A policy is a set of rules for one business domain: payouts, refunds, spec changes, production deploys. A request names the domain policy it needs, and the policy returns one of three outcomes.
| Document | Who works with it | Schema |
|---|---|---|
| Your sources | The people who own the risk: CISO, compliance and risk, business teams. Plain English, or the documents you already have. | None. Any supported format. |
| Authoring document | PolicyAgent writes it from your sources. Reviewers read it. AI assistants propose changes to it. | https://decionis.com/schemas/policy-authoring/v1 |
| Policy bundle | The evaluator runs it. Each published version is identified by its digest, and every decision records the version that made it. | https://decionis.com/schemas/policy/v1 |
PolicyAgent is the only encoder of record. Assistants such as Claude, Copilot or Cursor can encode a candidate with their own model and propose it, but a proposal changes nothing until a person accepts it in the workspace. No assistant can publish, approve, activate or deploy a policy.
Formats
Write in plain English, or upload what you already have. Each source is kept with its digest, so every rule can cite the exact text it came from. Each source is at most 10 MB.
| Direction | Format |
|---|---|
| In: your sources | Plain text, typed or pasted · Markdown · PDF, up to 200 pages. A scan with no text layer is held for review. · Word (.docx) · CSV · Excel (.xlsx) · A web page (HTML) · Jira issues |
| Encoded | JSON: the authoring document, then the policy bundle the evaluator runs |
| Export | YAML, to review a policy or keep it in Git. YAML is never read back in. |
JSON submitted to Decionis must be a single object with no duplicate or ambiguous keys. Anything else is refused rather than guessed at.
The rule card
Every rule is read back in this shape before it is encoded, and the person who owns it confirms it. It is how a rule written in plain English becomes one that can only mean one thing.
When [who] [does what] [to what],
and [condition],
then allow / escalate to [role] / block,
because [source].When an AI agent issues a refund over 500 USD, and the order is older than 30 days, then escalate to the Finance Controller, because Refund Policy §4.2.
| Part | What it needs |
|---|---|
| Who | A person, a team, an AI agent or a service. |
| Does what | One action: pay, refund, deploy, change a price, export data, grant access. |
| Condition | Amounts with a currency, time windows, counts, data classes, environments. Vague words such as large, senior, sensitive or unusual are replaced by a number, a role or a list. |
| Outcome | Allow, escalate to a named role, or block. |
| Because | The clause, ticket or document the rule comes from. |
End every policy with a catch-all rule that has no conditions. Unless you decide otherwise, it blocks.
Outcomes
Every decision has exactly one of three outcomes: ALLOW, ESCALATE or BLOCK. They are never renamed. An approval by a person is an escalation, never an allow.
| Authoring verdict | Policy bundle action | Decision | What happens |
|---|---|---|---|
| ALLOW | AUTO_APPROVE | ALLOW | The action may run, with a single-use grant. |
| ESCALATE | ESCALATE | ESCALATE | The action waits for the approver the rule names, who confirms in Presence. |
| REVIEW_REQUIRED | REQUIRE_REVIEW, REQUEST_INFO | ESCALATE | The action is held for review, with no named approver. |
| BLOCK | AUTO_REJECT | BLOCK | The action does not run. |
A policy can list the facts it needs before any rule is matched. When one is missing, the decision is ESCALATE, never a guess.
Review to enforce
A policy decides nothing until it has been reviewed, tested and run in shadow mode. Each approval is an attestation to an exact, immutable revision, and a high-impact policy also needs a Risk Reviewer at every step.
| State | Meaning |
|---|---|
| DRAFT | Being written. Authors and Policy Owners edit it. |
| REVIEW_READY | Submitted for review as an immutable revision. |
| APPROVED_FOR_TESTING | The Policy Owner and a Technical Reviewer approved it for testing. |
| TESTED | Its test scenarios have run and the results are recorded. |
| APPROVED_FOR_SHADOW | The Test Approver and the Release Approver approved it for shadow mode. |
| SHADOW_ACTIVE | Recording the verdict it would give on live requests. Nothing is blocked. |
| APPROVED_FOR_PRODUCTION | The Policy Owner and the Release Approver approved it for production. |
| PRODUCTION_ACTIVE | Deciding live requests in its business domain. |
| SUPERSEDED | Replaced by a newer version. Kept, with every decision it made. |
| RETIRED | No longer used. Kept, with every decision it made. |
Approving, testing and deploying need someone other than the author. A workspace with a single member can have its owner review, and a registered sole proprietor holds every role and attests to each one separately; the release records which applied. Agents cannot attest.
Roles
Your workspace assigns these roles to people. Approvers named in rules come from the Presence role directory, the one place approvers are defined.
| Role | Duty |
|---|---|
| SOURCE_CUSTODIAN | Uploads and vouches for the source documents. |
| AUTHOR | Writes and edits the rules. |
| POLICY_OWNER | Owns the policy: reviews the sources, scope and assumptions; edits and submits it. |
| RISK_REVIEWER | Reviews control effectiveness and risk. Required at every approval of a high-impact policy. |
| TECHNICAL_REVIEWER | Reviews how each rule maps to its source, the inputs, defaults, ordering and conflicts. |
| TEST_APPROVER | Reviews the test scenarios, expected outcomes and observed results. |
| RELEASE_APPROVER | Reviews the test, shadow and operational evidence for a release, rollback or retirement. |
| DEPLOYER | Puts an approved version live. |
| AUDITOR | Reads revisions, citations and the review record. Changes nothing. |
DECIONIS_POLICY.md
A plain Markdown file at a repository root, reviewed with the code. It is the human statement of the rules: nothing in it is evaluated.
The GitHub Action (decionis/govern) hashes the file and records its path and SHA-256 with each decision, so a Decision Dossier shows which revision the repository held. The policy that decides is the one in your workspace. The file can also be a source: upload it as Markdown and PolicyAgent encodes it like any other document.
Published schemas
JSON Schema (draft 2020-12), public and versioned. Validate your own documents against them, or generate types from them.
| Schema | URL |
|---|---|
| Authoring document | https://decionis.com/schemas/policy-authoring/v1 |
| Policy bundle | https://decionis.com/schemas/policy/v1 |
| Starter packs, authoring form | https://decionis.com/schemas/policy-authoring/v1/packs |
| Starter packs, bundle form | https://decionis.com/schemas/policy/v1/packs |
To draft a policy from your documents through the API, see Policy encoding.
