Policies

Each YAML file in this directory declares one policy. The Policy Engine reads every file at step 4 of the autonomous loop, aggregates the ones whose triggered_by clauses match the work the AI is about to do, and outputs the union of required agents, gates, risk score, and human- approval conditions.

Schema: schema.json. Authoring guide: README.md. Event names live in events/vocabulary.md. Validator: pnpm validate:policies (CI runs it automatically).

Current catalog

Policy	Risk	Required agents	When it fires
api-contract-change.yaml	8	backend-developer, code-reviewer	api/**, openapi.yaml, contracts/**, controllers
schema-migration.yaml	9	database, backend-developer, devops-infra, code-reviewer	**/migrations/**, *.migration.{ts,sql}
auth-touch.yaml	8	auth-security, code-reviewer	**/auth/**, **/cognito/**, **/rbac/**, *.jwt.*, auth.touched event
legacy-php-change.yaml	7	legacy-php-guide, code-reviewer	superco-consumer/**, **/yii2/**, **/*.php
frontend-i18n.yaml	4	i18n-localization, frontend-developer	**/i18n/**, **/locales/**, i18n.string_added event
production-deploy.yaml	10	devops-infra	deploy.requested event
secret-rotation.yaml	10	auth-security, devops-infra	**/.env*, **/secrets/**, secret.referenced event
large-refactor.yaml	6	architect, code-reviewer	PR diff > 20 files
cross-repo-impact.yaml	5	code-reviewer	pr.cross_repo_overlap event

Approval categories

Policy	Approval
production-deploy	Hard Floor — always requires human approval (autonomy/defaults.yaml)
secret-rotation	Hard Floor — always requires human approval
auth-touch	Always — second pair of eyes mandatory
schema-migration	Conditional — required on data_loss_detected or production_target == true
legacy-php-change	Conditional — required on touches.auth_path or touches.payment_path
api-contract-change	Conditional — required on breaking change
large-refactor	Conditional — required when diff > 50 files
frontend-i18n	None — gates only
cross-repo-impact	None initially — warn-only

Adding a policy

1. Create policies/<id>.yaml from the schema (or copy an existing policy and edit).
2. Run pnpm validate:policies — should pass before opening a PR.
3. If the policy uses a new event, add it to events/vocabulary.md.
4. If the policy references an agent that doesn't exist yet, that's fine: the engine will log a warning at runtime until the agent lands. Don't gate the policy on an agent existing — that creates ordering deadlocks during migration.

Agents referenced but not yet authored

These names appear in required_agents and will resolve once their files land under .claude/agents/:

• backend-developer
• frontend-developer
• code-reviewer
• architect
• database
• devops-infra
• auth-security
• i18n-localization
• legacy-php-guide