Policy Packs

Use this page when a platform or operations team wants one rule set to apply across many repos.

Policy packs keep shared rules out of individual ota.yaml files.

• org-wide standards
• repo readiness rules that are shared across teams
• a clear difference between repo contract and policy overlay
• diagnosis that explains why a repo fails policy, not just local validation

The repo contract says what one repo needs.

The policy pack says what the org wants every repo to satisfy on top of that.

• repo contract values are local and repo-specific
• policy values are shared and org-wide
• policy can add requirements or approved defaults, but it does not replace the repo contract
• users should be able to tell which layer asked for a rule by reading the finding

Without policy packs, the same org rules get repeated in repo after repo.

• consistent agent safety rules
• required sections or files across repos
• org-level contract expectations
• an audit trail for policy-driven findings

Most teams do not start with policy authoring. They start when ota doctor shows a policy-backed finding or when the platform team wants one reviewed rule set across many repos.

• platform team: preview a starter with ota policy init --dry-run or one of the explicit presets
• repo owner: run ota doctor and read the policy-backed finding first
• operator: use ota policy review when you need the active policy source and the policy-versus-contract boundary
• fix the repo or adjust policy intentionally; do not copy org rules into every ota.yaml

ota policy init --preset provisioning --dry-runota doctorota policy review

The canonical policy pack lives at .ota/org-policy.yaml.

Use ota policy init --dry-run to preview the conservative starter and ota policy init to write it without guessing org rules.

Use --preset required-sections, --preset provisioning, or --preset agent when the policy owner wants a stronger reviewed starting point.

ota uses OTA_POLICY as an explicit file-path or HTTP(S) URL override.

If that is not set, ota falls back to the nearest ancestor .ota/org-policy.yaml, then to workspace.policy when the workspace declares one.

ota policy init --preset required-sections --dry-runota policy init --preset provisioning --dry-runota policy init --preset agent --dry-run

OTA_POLICY=/path/to/custom-org-policy.yaml ota doctor

OTA_POLICY=https://config.example.com/custom-org-policy.yaml ota doctor

These are the policy fields users are most likely to see in a real repo.

• required_sections means the repo must declare those contract sections
• required_files means the repo must include those files at the governed boundary
• provisioning approves where ota may satisfy runtime and standalone tool prerequisites
• native_packages approves which host package-manager bundles ota may install from native_prerequisites
• agent.require_safe_tasks means agent-facing execution should be explicit about safe tasks
• agent.require_writable_paths means agent-facing execution should spell out what agents may edit
• agent.posture is the repo-declared authority model for automation; policy can require the boundary to be explicit even when posture stays repo-local
• effects.mode controls fallback effect decisions (compatibility warns by default, strict denies by default)
• effects.tasks governs selected task-path effect decisions (network, dependency_hydration, integration_test, external_state)
• Keep external_state policy keys aligned to shipped canonical task tokens like docker, postgres, redis, s3, cloudflare, or kubernetes so the same effect rules can be reused across repos.
• effects.safe_tasks governs selected safe-task-path effects and can be stricter than the general task policy
• exports.require_agents_md means the policy expects generated repo guidance such as AGENTS.md

A policy pack is a shared org rule set.

It does not replace ota.yaml; it adds constraints above it and lets doctor explain the mismatch clearly when a repo falls short.

policies:  required_sections:    - runtimes    - tasks    - agent  required_files:    - AGENTS.md  agent:    require_safe_tasks: true    require_writable_paths: true  effects:    mode: strict    tasks:      network: warn      dependency_hydration: allow      integration_test: warn      external_state_default: warn    safe_tasks:      network: deny      dependency_hydration: allow      integration_test: deny      external_state_default: warn      external_state:        docker: deny  exports:    require_agents_md: true  native_packages:    apt:      approved:        - build-essential        - libpq-dev

• require contract sections
• require repo files
• require safer agent guidance
• require explicit writable-path intent
• approve standalone runtime/tool provisioning sources
• approve host package-manager bundles used by native_prerequisites
• govern task/safe-task side effects with explicit allow/warn/deny decisions
• require generated repo guidance such as AGENTS.md
• produce policy-aware findings that tell the user what changed and why it matters

• define repo readiness on its own
• act as a workflow engine
• replace approvals or ticketing
• silently mutate repo files
• erase the repo contract or make the repo say something it does not say

ota doctor is the main place users see policy packs.

ota policy init creates the conservative starter policy pack, and ota policy review is the policy-authority lens when you need the boundary between repo contract and org policy to stay explicit.

• show what policy asked for
• show what is missing
• show what to change first
• keep policy findings distinct from local contract validation failures
• show enough detail that the user can fix the repo without reading the policy file directly
• use ota policy init when you need a valid starter .ota/org-policy.yaml without guessing org intent
• use the explicit presets when you want reviewed starter sections for required contract sections, provisioning policy, or agent governance
• use ota policy review when you need the active policy source, policy path, and approved-sources boundary before deciding what should change

• read the summary first to see the rule that failed
• read the why line to understand the org expectation
• read the next line to see the smallest safe fix
• use the source or provenance details when ota needs to tell you where the policy came from

• a platform team wants every repo to declare tasks and runtimes
• an org wants agent-safe execution rules across many repos
• a maintainer needs AGENTS.md to exist everywhere
• a compliance team wants policy findings to stay readable and reviewable
• an ops team wants policy to enforce repo hygiene without rewriting every repo contract by hand