Policies

A policy is not a document. It is a small set of rules — what it watches for — and actions — what happens when a rule fires. Every match is a deterministic string or glob comparison. No model is consulted.

The organization approves policies for use; each workspace enforces them. They are evaluated when a model is resolved, when a change is analysed, and at the evidence gate. YAML is how they are read and shared; the rows are what runs.

What a policy holds

Field	Notes
Name
Key	A stable slug, 2–63 characters, lower-case, starting with a letter or digit. Used in YAML. Cannot be changed after creation.
Severity	low, medium, high or critical. Default high.
Compliance framework	Optional. A category, not a control.
Description
Scope	The whole organization, or one workspace.
Status	active or retired.
Version	Incremented on every edit.

A work session records the policy version it was briefed with.

The six rule kinds

Kind	Label in the dropdown	Value	Fires when
file_trigger	When a changed path matches	A path glob	A changed path matches. Applies the policy; is not itself a breach.
dependency_forbidden	Forbid a dependency	A package name	An added dependency's name contains it. A violation.
secret_pattern	Never commit files matching	A path glob	Any changed file matches and was not deleted. A violation.
provider_allowlist	Only these providers	A comma-separated list	A run on any provider not listed. Refused outright.
model_allowlist	Only these models	A comma-separated list	A run on any model not listed. Refused outright.
client_allowlist	Only these clients	A comma-separated list	A session from any client not listed. Refused outright.

The help text under each kind is worth reading in the interface; the globs one is the most useful:

A glob over changed file paths — ** is any depth, * is within a name. Use it to mark code where a change is never routine (auth, payments, migrations).

Globs support **, * and ?. They are matched case-insensitively, anchored at the end, from any directory depth — so auth/** catches src/auth/Token.cs, and *Authorization* catches src/Auth/PolicyAuthorization.cs.

Every change rule must name a gate

A rule of kind file_trigger, dependency_forbidden or secret_pattern must say what a matching change needs to ship. The form refuses otherwise:

Every path, dependency and secret rule must say what a matching change needs to ship.

The reason: a change rule without a gate is a tripwire with no consequence. The allow-list kinds are exempt because their consequence is stronger than any gate.

The three gates, weakest first: At least a review capsule, A human must review, Security must review.

Defaults when you leave it: a path trigger and a forbidden dependency get human review; a secret pattern gets security review.

The six actions

Action	Label	Evidence it demands
block_merge	Block merge while open	none
require_human_review	Require human review	a human review
require_security_review	Require security review	a security review
require_integration_tests	Require integration tests	an integration test
require_browser_verification	Require browser verification	a browser run
notify	Notify only	none

block_merge never stops an agent writing code. It stops it shipping. The agent is told:

A policy blocks merge until its conditions are met. Nothing stops you writing the code; it will not ship until they are.

A policy with no actions is recorded as a violation only.

How a gate changes risk

A fired rule's required gate raises the change's review gate and adds zero points to the risk score. The factor is recorded so you can see it:

{policy} requires this gate for changes like this one, whatever the score.

An earlier design inflated the number to force the outcome. That taught people the number lies.

Limits

Rules per policy	1 to 40
Actions per policy	at most 10
Key	2–63 characters
Rule value	1–255 characters
Description	up to 20,000 characters
YAML import	up to 20,000 characters

The 15 templates

Start from a template gives you the rules most engineering organizations actually run, with the globs editable afterwards. Each is a multi-select card showing its severity, rule count and actions; one already in use is disabled with an already here badge.

Key	Name	Severity
secrets-management	Secrets management	critical
authentication-and-authorization	Authentication and authorization changes	high
payments-and-billing	Payments and billing	critical
personal-data-handling	Personal data handling	high
database-migrations	Database migrations	high
infrastructure-as-code	Infrastructure as code	high
ci-cd-pipelines	CI/CD pipeline changes	high
public-api-contracts	Public API contracts	medium
dependency-changes	Dependency changes	high
approved-ai-providers	Approved AI providers and clients only	critical
cryptography	Cryptography	critical
ui-verified-in-browser	UI changes verified in the browser	medium
logging-and-observability	Logging and observability	medium
configuration-and-feature-flags	Configuration and feature flags	medium
third-party-integrations	Third-party integrations and webhooks	high

The organization creation wizard's recommended setup picks the first two: secrets management and authentication.

Retiring, reviving and deleting

Retire switches a policy off:

Switches the policy off — it moves to Retired below with its history, and you can bring it back any time.

Retired policies live under a disclosure: "{n} retired policies — switched off, kept with their history; reactivate any time."

Creating a policy whose key belongs to a retired one revives that row rather than erroring. Using a key that belongs to a live one is refused:

A policy with the key "secrets-management" already exists. Edit it, or choose another key.

Delete is permanent, and behind a type-the-name confirmation:

This permanently removes the policy and every rule in it — unlike Retire, there is no bringing it back, and its template becomes takeable again. Violations it already recorded stay in the violations list, labelled "Deleted policy".

YAML

Export YAML renders every applicable policy, separated by ---. Import YAML takes one policy; an existing key is updated and its version bumped.

policy: secrets-management
name: Secrets management
severity: critical
scope: { organization: true }
rules:
  - secret_pattern: ".env"
    required_gate: security_review
required_actions:
  - block_merge
  - require_security_review
description: Secrets never live in the repository.

Import errors name the problem precisely: "The document must be a mapping.", "policy must be a lower-case slug, e.g. secrets-management.", "Rule 3 must name one of: file_trigger, dependency_forbidden, secret_pattern, provider_allowlist, model_allowlist, client_allowlist.", "Unknown action "require_qa". Use: block_merge, require_human_review, …", and "Not valid YAML: {message}".

An older document that used a numeric risk floor is translated: 85 or above becomes security review, 60 or above human review, 25 or above a review capsule.

Which policies a workspace enforces

Workspace → Governance.

A master switch: Enforce everything the organization approves.

State	What it means
On (the default)	"On — all {n} approved policies run here, and new approvals join automatically."
Off	"Off — only your selection under Active runs here. New org approvals wait in the catalog until you add them."

With it off, two tabs appear — Active here and Choose from the catalog — and each policy can be added or removed:

Removes it from this workspace only — the organization keeps it approved for others.

A policy scoped to the workspace itself cannot be excluded. Deleting it is what that means:

This policy is scoped to the workspace itself — delete it under Governance to switch it off.

Changing the mode or the selection needs workspace.update plus the workspace admin flag — or organization owner or admin, who administer every workspace.

The footer points you at the right page for everything else:

The catalog itself — writing policies, approving them for use, retiring them — lives at the organization's Governance. What this workspace's work broke is under its own Violations page.

Policies in the agent's brief

Every applicable policy is in every brief, under ## Policies in force:

These are the organization's rules. They are checked by Madebook on every change you report.

Each renders as its name, severity, what triggers it, what happens, and its description — for example:

Secrets management (critical): content matching the secret pattern .env, or content matching the secret pattern **/*.pem → block merge, require security review — Secrets never live in the repository.

Related

• Violations
• Providers, models and clients
• Evidence and gates