Skip to content

Policy Engine

The policy engine checks skill extensions and @prompts entries against declarative organizational rules. Policies are evaluated by prs validate and prs check. prs compile does not evaluate them.

Configuration

Define policies in promptscript.yaml:

policies:
- name: adjacent-layers-only
kind: layer-boundary
description: 'Only adjacent layers can extend each other'
severity: error
layers: ['@core', '@team', '@project']
maxDistance: 1
- name: protect-content
kind: property-protection
description: 'Content override requires explicit approval'
severity: warning
properties: ['content', 'description']
- name: approved-registries
kind: registry-allowlist
description: 'Extensions must come from approved registries'
severity: error
allowed: ['@core', '@team']

Policy Kinds

Three kinds check skill extensions: layer-boundary, property-protection and registry-allowlist. Seven more check prompts, see Prompt Policies.

Layer Boundary

Controls which layers can extend which, based on distance in a defined layer hierarchy.

FieldTypeRequiredDescription
layersstring[]YesOrdered list of layers from base to leaf
maxDistancenumberNoMaximum allowed distance (default: 1)

Example: with layers: ['@core', '@team', '@project'] and maxDistance: 1, a @project extension cannot directly modify a @core skill - it must go through @team.

The distance is measured between the registry of the file that defines the skill and the registry of the file that extends it. Sources outside the layers list, like the project’s own .prs files, are not checked.

Property Protection

Prevents overriding specific properties on skills.

FieldTypeRequiredDescription
propertiesstring[]YesProperties that cannot be overridden
targetPatternstringNoGlob pattern to match target skills (e.g., @core/*)

When targetPattern is specified, the policy only applies to skills that were composed from matching registries.

Registry Allowlist

Restricts which registries can provide extensions.

FieldTypeRequiredDescription
allowedstring[]YesAllowed registry prefixes

Any extension sourced from a registry not in the allowed list produces a violation.

Prompt Policies

Seven kinds read the @prompts entries of the resolved program: required-metadata, risk-floor, model-allowlist, content-rules, required-approvals, required-evals and max-experiment-weight.

What a policy sees

For each valid entry a policy sees:

  • the id <@meta.id>/<key>;
  • the effective governance: risk, owner and domain from the entry, else from @meta, the dataClasses of both joined, and entry reviewers instead of the @meta ones. These are the values the prompt bundle carries, see Application Prompts;
  • model.ref, and the inputs with their types;
  • the entry’s own system and user text. Composed blocks are not part of it. Only the project’s own rules PS005, PS010-PS012 and PS014 scan them, with the project’s rule settings.

A finding is a PS030 message at the location of the entry, so prs validate --format json gives the file and the line.

The release gates see a prompt version the other way round: the bundle that ships, with its composed messages, model and governance, see Release gates.

Policy risk and match

Every prompt kind except risk-floor takes an optional match:

KeySelects a prompt when
minRiskits policy risk is at or above this level
domainsits effective domain is one of these
dataClassesany of its effective data classes is listed

Keys combine with AND. A policy without match selects every prompt. Domains and data classes compare lowercased.

When governance.dataClasses is set, every data class in a match or in a risk-floor row must be in it. Another value is a PS030 error that names the closest one, because a typo would make the selector or the floor match nothing. Without governance.dataClasses these values are not checked, and a typo matches no prompt.

Policy risk is the higher of the effective risk and the floor of every risk-floor policy, whatever the severity of that policy. A prompt without risk counts as low.

Keep in mind who controls what. The author of a prompt writes its risk and domain, and a child file can lower risk or change domain of what it inherits. Use them to select prompts, not as the boundary. Data classes in @meta are joined through @inherit, so a child file cannot drop them. Data classes on an entry are not safe the same way: a child file that replaces the whole entry with @override sets its own. So the boundary is a risk-floor on data classes set in the @meta of the parent, plus required-metadata, which makes the fields a floor reads mandatory, plus review of the files that can override entries.

Required Metadata

Matched prompts must set governance fields.

FieldTypeRequiredDescription
matchobjectNoPrompts the policy applies to
fieldsstring[]YesAny of risk, owner, domain, dataClasses, reviewers

An empty list or an empty string counts as missing.

policies:
- name: governance-fields
kind: required-metadata
severity: error
match: { minRisk: high }
fields: [owner, reviewers]

Risk Floor

Derives a minimum risk from what a prompt handles. Each row lists conditions and a minimum. A row matches when any of its conditions matches, and the floor is the highest minimum of the matching rows. The policy reports a prompt whose effective risk is below its floor. It takes no match.

Row keyTypeMatches when
dataClassesstring[]any effective data class is listed
domainsstring[]the effective domain is listed
inputTypesstring[]any input has one of the types (a string input is free text, an enum is not)
minimumstringrequired: low, medium, high or critical

A row needs at least one condition. A starter table, not built in:

ConditionMinimum
phi or credentialscritical
pii or financialhigh
internal, or a free-text inputmedium
public or no data classlow
policies:
- name: data-floor
kind: risk-floor
severity: error
floors:
- { dataClasses: [phi, credentials], minimum: critical }
- { dataClasses: [pii, financial], minimum: high }
- { dataClasses: [internal], minimum: medium }
- { inputTypes: [string], minimum: medium }

Model Allowlist

Matched prompts must run on one of the listed models.

FieldTypeRequiredDescription
matchobjectNoPrompts the policy applies to
modelsstring[]YesCatalog ids or aliases, resolved like models.supported

An entry that is not in the model catalog is a policy error that names the closest id, and so is inherit. A prompt without a model, or with inherit, fails: the application would pick the model. PS042 still makes a floating alias an error when the effective risk is high or critical. It does not read the policy risk, so a floor that raises a prompt to high does not make PS042 stricter; list pinned ids in models for that.

policies:
- name: high-risk-models
kind: model-allowlist
severity: error
match: { minRisk: high }
models: [claude-opus-5-5]

Content Rules

Runs content checks and denied phrases on the text of matched prompts.

FieldTypeRequiredDescription
matchobjectNoPrompts the policy applies to
checksstring[]checks or denyContent rules to run, by name or id
denystring[]checks or denyPhrases the text must not contain
allowstring[]NoBlocked-pattern sources exempt for matched prompts

checks takes blocked-patterns (PS005), suspicious-urls (PS010), authority-injection (PS011), obfuscated-content (PS012) and unicode-security (PS014). path-traversal (PS013) is refused, it checks @inherit and @use paths, not prompt text. A check runs on the entry’s own system and user text and reports at the policy severity, also when the project turns that rule off with validation.rules or validation.disableRules. Turning off PS030 itself, with policy-compliance: off under validation.rules or with policy-compliance or PS030 in validation.disableRules, stops every policy, its content checks included. validation.allowedPatterns still applies. allow removes blocked patterns for the matched prompts by exact source text, like allowedPatterns.

deny matches after normalization of both the phrase and the text: NFKC, default-ignorable code points (such as zero-width characters) removed, whitespace collapsed, lowercase. It is a tripwire, not a filter. It catches a plain copy of a phrase, but anyone who writes the prompt can phrase around it. It also does not read the sentence, so “Never promise a guaranteed refund” contains “guaranteed refund”.

policies:
- name: payments-content
kind: content-rules
severity: error
match: { domains: [payments] }
checks: [suspicious-urls, obfuscated-content]
deny: ['guaranteed refund']

Required Approvals and Required Evals

required-approvals and required-evals describe what a prompt needs before release. prs validate, prs check and prs release build check the definitions only. The release gates evaluate them: prs release promote, prs release split, prs release rollback and prs release status --base refuse a prompt version whose required-approvals policy finds no committed approval record for that hash and environment, see Release gates. required-evals is unavailable in the gates, because they do not read eval results in this version: at severity error it blocks every matching release, at warning it only warns. A record binds only through review: CODEOWNERS from Governance gives each approval role directory to its team.

KindFieldTypeRequiredDescription
bothmatchobjectNoPrompts the policy applies to
bothenvironmentsstring[]NoNames from releases.environments. Absent means all
required-approvalsapprovalslistYes{ role, count } rows. role must be a key of governance.roles

count is optional and only 1 is accepted: approval records are unsigned, so two records cannot prove two different approvers under one review.

On an experiment arm, required-approvals counts a record that has maxWeight too, up to its ceiling. For the entry hash, the control arm, a promote, prs release split --end --keep and a plain rollback, only a record without maxWeight counts. See Max Experiment Weight.

governance:
roles:
legal: ['@acme/legal']
releases:
environments: [staging, prod]
policies:
- name: high-risk-signoff
kind: required-approvals
severity: error
match: { minRisk: high }
environments: [prod]
approvals: [{ role: legal }]

Max Experiment Weight

max-experiment-weight limits how much traffic a non-control arm of a label experiment may get, see Experiments. The gates judge it for every arm with traffic in an environment the policy covers. The entry hash and the control arm are promotions, so the policy never judges them, and neither an arm at weight 0.

FieldTypeRequiredDescription
matchobjectNoPrompts the policy applies to
environmentsstring[]NoNames from releases.environments. Absent means all
maxWeightnumberYesPercent of traffic an arm gets without approvals, at most two decimals
approvalslistNo{ role } rows. An arm above maxWeight needs one record of each role
ceilingnumberNoPercent above which no arm passes, whoever approved. Needs approvals, at least maxWeight

Percents run from 0 to 100 with at most two decimals. ceiling needs approvals, and it is at least maxWeight. count is 1, as in required-approvals. Without approvals the cap is hard: maxWeight is the most an arm may get.

For an arm at weight w:

CaseResult
w is at most maxWeightpassed, no record needed
above maxWeight, no approvalsfailed: the cap is hard
above ceilingfailed, with or without records
above maxWeight, at most ceiling (or no ceiling)passed when every role has a record for this hash and environment that covers w

A record covers w when it has no maxWeight, or its maxWeight is at least w. Create one with prs approve ... --env prod --max-weight 10, see Release gates. Several policies stack: each one judges the arm on its own, and every policy that matches must pass. At severity warning a failed check only warns.

governance:
roles:
legal: ['@acme/legal']
releases:
environments: [staging, prod]
policies:
- name: high-risk-exposure
kind: max-experiment-weight
severity: error
match: { minRisk: high }
environments: [prod]
maxWeight: 5
approvals: [{ role: legal }]
ceiling: 25

An arm of a high risk prompt may run up to 5 % in prod. Between 5 % and 25 % it needs a legal record that covers its weight. Above 25 % it never passes.

A record without maxWeight counts as a full approval, so it covers any arm weight. A record with maxWeight never approves the entry hash, even at 10000 (100 %): a capped approval is about traffic, not about a promotion. That holds under required-approvals as well. Neither a promote, prs release split --end --keep nor a plain rollback counts it.

prs release status --base <ref> reads the policies from <ref>, and the weights and the records from HEAD. A pull request can add a record with a high maxWeight next to the weight it asks for, so the review of approvals/<role>/ by CODEOWNERS is what stops it.

The limits are the ones of Required Approvals: records are unsigned, count is 1, and two people mean two roles.

Typos and unknown kinds

Prompt kinds reject unknown keys with the closest key, at every level, because a typo such as minrisk would quietly change what a policy selects. An unknown kind is a PS030 error, so a policy this version cannot evaluate never passes in silence. A __proto__ key is refused in every policy. policies must be a list: written as a mapping, without the - before name, it is a PS030 error and not a project without policies.

Starter configuration

governance:
roles:
legal: ['@acme/legal']
dataClasses: [pii, phi, financial, credentials, internal, public]
policies:
- name: risk-set
kind: required-metadata
severity: error
fields: [risk, dataClasses]
- name: data-floor
kind: risk-floor
severity: error
floors:
- { dataClasses: [phi, credentials], minimum: critical }
- { dataClasses: [pii, financial], minimum: high }
- { dataClasses: [internal], minimum: medium }
- { inputTypes: [string], minimum: medium }
- name: governance-fields
kind: required-metadata
severity: error
match: { minRisk: high }
fields: [owner, reviewers]

risk-set makes every prompt state its risk and data classes, so unset risk does not quietly count as low.

Example

A prompt that handles pii but says risk: "medium". The project uses data-floor, governance-fields, high-risk-models and payments-content from above, and the governance section of the starter configuration:

@meta {
id: "acme"
syntax: "1.6.0"
owner: "Support team"
}
@prompts {
refund-reply: {
description: "Answer a refund request"
domain: "payments"
dataClasses: ["pii"]
risk: "medium"
model: { ref: "claude-sonnet-5-5" }
system: "You answer refund requests. Policy: http://acme.example/refunds"
user: "Customer wrote: {{input.message}}. Never promise a guaranteed refund."
inputs: {
message: { type: "string", description: "Customer message" }
}
}
}
Try in Playground
$ prs validate
- Loading configuration...
✖ Validation failed
Errors (5):
✗ [data-floor] Prompt "acme/refund-reply" has risk "medium", below "high" required for data class "pii"
at .promptscript/project.prs:8:3
✗ [governance-fields] Prompt "acme/refund-reply" has risk "high" but no reviewers
at .promptscript/project.prs:8:3
✗ [high-risk-models] Prompt "acme/refund-reply" uses "claude-sonnet-5-5", which is not allowed at risk "high"
at .promptscript/project.prs:8:3
✗ [payments-content] Prompt "acme/refund-reply": suspicious-urls: Insecure HTTP URL detected: http://acme.example/refunds in the system message
at .promptscript/project.prs:8:3
✗ [payments-content] Prompt "acme/refund-reply" contains the denied phrase "guaranteed refund" in the user message
at .promptscript/project.prs:8:3
Warnings (2):
⚠ PS047: @meta: owner "Support team" is not a Git host identity
at .promptscript/project.prs:1:1
suggestion: Use a user (@jane), a team (@acme/legal) or an email address.
⚠ PS010: Insecure HTTP URL detected: http://acme.example/refunds
at .promptscript/project.prs:7:10
suggestion: Use HTTPS instead of HTTP for secure communication

The floor lifts the policy risk to high, so governance-fields and high-risk-models select the prompt although it says medium. Paths are shortened here, the CLI prints absolute paths.

Governance Values (PS047)

PS047 (governance-values) runs when promptscript.yaml has a governance section and the program has @prompts entries. It warns on values authored on an entry or in @meta:

  • an owner or a reviewer that is not a Git host identity: a user (@jane), a team (@acme/legal, GitLab subgroups allowed) or an email address of at most 254 characters;
  • when governance.dataClasses is set, a data class outside that list, with the closest match. Values compare lowercased. Without governance.dataClasses data classes are not checked.

Owners and reviewers stay free strings in the language, so PS047 is a warning. Prefer teams: they change less often, and governance values are part of the content hash of a prompt bundle, so a changed owner changes the hash. A team also keeps personal data out of the bundle.

A recommended data class vocabulary:

Data classMeaning
piiData about an identifiable person
phiHealth information
financialPayment, account or card data
credentialsPasswords, keys and tokens
internalCompany information that is not public
publicInformation that is already public

Severity

  • error: Validation fails (non-zero exit code)
  • warning: Reported but does not fail validation (unless --strict)

Policies in Extended Configs

When promptscript.yaml uses extends, the policies of the base file are kept and the project’s own policies are appended after them:

shared/org.yaml
policies:
- name: approved-registries
kind: registry-allowlist
severity: error
allowed: ['@core', '@team']
app/promptscript.yaml
id: app
extends: ../shared/org.yaml
policies:
- name: protect-content
kind: property-protection
severity: warning
properties: ['content']

The project is validated against both approved-registries and protect-content. A base policy cannot be removed or redefined from the extending file: a policy with the same name as a base policy is a config error, and so is a policies value that is not a list, such as policies: null (a bare policies: key is accepted only when the base has no policies). See Extending Configuration for the other merge rules.

Skipping Policies

For development, use --skip-policies:

Terminal window
prs validate --skip-policies

The flag skips policies for one run of prs validate. A skipPolicies key under validation in promptscript.yaml is ignored by both commands. Setting validation.rules.policy-compliance to off still turns PS030 off, including from an extending file.

Note: Never use --skip-policies in CI pipelines.

Runnable Walkthrough

This scenario is fully self-contained - no Git host, no network. Create the files below in an empty directory, run prs validate, and watch PS030 fire.

policy-demo/
├── promptscript.yaml
├── .promptscript/
│ └── project.prs
└── registry/
├── @core/
│ └── skills.prs # Layer 1: base skill definition
└── @team/
└── overlay.prs # Layer 2: overrides content, not in the allowlist
promptscript.yaml
registry:
path: ./registry
policies:
- name: protect-content
kind: property-protection
description: 'Content override requires explicit approval'
severity: warning
properties: ['content', 'description']
- name: approved-registries
kind: registry-allowlist
description: 'Extensions must come from approved registries'
severity: error
allowed: ['@core']
# registry/@core/skills.prs
@meta {
id: "@core/skills"
syntax: "1.5.0"
}
@skills {
"code-review": {
description: "Base code review skill"
content: """
Review code for quality, correctness, and security.
"""
}
}
Try in Playground
# registry/@team/overlay.prs
@meta {
id: "@team/overlay"
syntax: "1.5.0"
}
@use @core/skills
@extend skills.code-review {
content: """
Team-specific review checklist with banking compliance steps.
"""
}
Try in Playground
.promptscript/project.prs
@meta {
id: "demo-project"
syntax: "1.5.0"
}
@use @team/overlay
Try in Playground

Run validation from the policy-demo directory:

$ prs validate
- Loading configuration...
✖ Validation failed
Errors (1):
✗ [approved-registries] Skill 'code-review' was modified by registry '@team' which is not in the allowed list
Warnings (1):
⚠ PS030: [protect-content] Skill 'code-review' has a protected property 'content' that was overridden by '/home/you/policy-demo/registry/@team/overlay.prs'
suggestion: Property 'content' is protected and must not be overridden by downstream layers.
$ echo $?
1

Two things to read from this output:

  • The registry-allowlist violation is an error, so validation fails with exit code 1 - exactly what a CI pipeline needs.
  • The property-protection violation is a warning, so it is reported (with its suggestion line) but does not fail the run. With prs validate --strict it becomes an error.

Fix the violation by allowing the @team registry:

- name: approved-registries
kind: registry-allowlist
description: 'Extensions must come from approved registries'
severity: error
allowed: ['@core', '@team']

Re-run and the error is gone - validation succeeds with exit code 0, leaving only the protect-content warning.

How It Works

Prompt kinds read the @prompts entries as described in What a policy sees. The skill kinds work as follows.

The policy engine operates on the resolved AST after all @extend and @use declarations have been applied. It inspects the __layerTrace metadata that the resolver attaches to each skill during composition. This trace records which property was modified, by which source file, and with which merge strategy. The resolver also records __baseSource, the file that first defined the skill, which layer-boundary uses as the base layer.

For each configured policy, the engine:

  1. Iterates all skills in the @skills block
  2. Reads the __layerTrace entries
  3. Extracts the source registry from each trace entry (e.g., @team from @team/overlay.prs)
  4. Evaluates the policy rules against the trace data
  5. Produces violations with the policy’s configured severity

Enterprise Example

A three-layer enterprise setup:

promptscript.yaml
# Layer 1: Core platform (managed by platform team)
# Layer 2: Team configurations
# Layer 3: Project-level customizations
policies:
- name: layer-governance
kind: layer-boundary
description: 'Enforce layer hierarchy'
severity: error
layers: ['@platform/core', '@teams', '@projects']
maxDistance: 1
- name: core-immutability
kind: property-protection
description: 'Core skill content cannot be overridden'
severity: error
properties: ['content', 'description']
targetPattern: '@platform/core/*'
- name: approved-sources
kind: registry-allowlist
description: 'Only approved registries can contribute extensions'
severity: error
allowed: ['@platform/core', '@teams']

This ensures:

  • Layer governance: Projects can only extend team configs (not core directly)
  • Core immutability: Core skill content and descriptions cannot be overridden
  • Source control: Only approved registries can contribute extensions

Validation Rule

The policy engine is implemented as validation rule PS030 (policy-compliance), for skill and prompt kinds alike. It can be configured like any other rule:

validation:
rules:
policy-compliance: error # default

Set to off to disable all policy checks, prompt kinds included:

validation:
rules:
policy-compliance: off

Programmatic API

The policy engine is available as a standalone API. @promptscript/resolver and @promptscript/validator are not published to npm, so this works inside the PromptScript repository only. To run policies on your own project, use prs validate. This snippet runs against the walkthrough project above - config and the resolved AST are both loaded here, so it is executable as-is:

import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { parse as parseYaml } from 'yaml';
import { Resolver } from '@promptscript/resolver';
import { parsePolicies, evaluatePolicies } from '@promptscript/validator';
// Parse and validate policy definitions from promptscript.yaml. The context lets
// the parser check the roles, environments and model ids of prompt policies.
const config = parseYaml(readFileSync('promptscript.yaml', 'utf-8'));
const context = {
governance: config.governance,
releases: config.releases,
models: config.models,
allowedPatterns: config.validation?.allowedPatterns,
};
const { policies, errors } = parsePolicies(config.policies, context);
if (errors.length > 0) {
throw new Error(`Policy definition errors:\n${errors.join('\n')}`);
}
// Resolve the project AST (imports and @extend applied)
const resolver = new Resolver({
registryPath: resolve('./registry'),
localPath: './.promptscript',
});
const resolved = await resolver.resolve(resolve('./.promptscript/project.prs'));
if (resolved.errors.length > 0 || !resolved.ast) {
throw new Error(`Resolution failed: ${resolved.errors.map((e) => e.message).join('; ')}`);
}
// Evaluate policies against the resolved AST
const violations = evaluatePolicies(policies, resolved.ast);
for (const violation of violations) {
console.log(`[${violation.policyName}] ${violation.message}`);
}

Prompt kinds have their own evaluator (same note: repository only, prs validate does this for you). It takes the same context, for the model catalog and allowedPatterns. Give it the canonical AST, so each finding points at its entry and not at the @prompts block:

import { evaluatePromptPolicies, promptPolicySubjects } from '@promptscript/validator';
const subjects = promptPolicySubjects(resolved.canonicalAst ?? resolved.ast);
for (const violation of evaluatePromptPolicies(policies, subjects, context)) {
const where = violation.location ? `${violation.location.file}:${violation.location.line}` : '';
console.log(`${where} [${violation.policyName}] ${violation.message}`);
}

config, context, policies and resolved are the ones of the snippet above.

promptPolicyRisk(subject, policies) returns the policy risk of one subject, and promptPolicyMatches(match, subject, risk) whether a match selects it. A fourth argument of evaluatePromptPolicies, { risk, selects }, replaces the subject’s own risk and selection; the release gates use it to judge a bundle with the higher risk of bundle and source.

Requires the workspace packages (@promptscript/resolver, @promptscript/validator) and yaml (v2) as dependencies.