Policy concepts

Policy is the governance layer above ota.yaml. It decides what is required, what is approved, and how ota explains a mismatch when the repo and the org disagree.

If you need the supported fields, read Policy Packs. If you need a copyable baseline, view Org Policy Baseline.

Policy is not a second contract. It is the rule layer above ota.yaml.

• Repo policy stays in ota.yaml.
• Org policy packs live in .ota/org-policy.yaml, are discovered by walking ancestor directories from the contract path, and can therefore apply shared rules across a workspace tree.
• The canonical policy pack lives at .ota/org-policy.yaml, so users know exactly where to put shared org rules today.
• doctor, run, up, and explain should show the rule source that won.

# ota.yaml (repo contract)runtimes:  node: "22" # .ota/org-policy.yaml (org layer)policies:  version_policy:    runtimes:      node:        approved_versions:          - "22"  agent:    require_safe_tasks: true

• posture is the primary authority model; use readiness_strict for normal readiness slices, contract_authoring for repo-contract authoring, and infra_authoring for CI/runtime-topology authoring.
• safe_tasks are the tasks an AI agent can run without broad risk; use them when you want a safe default set for AI-agent automation.
• effects.writes makes durable task writes explicit so agent-safe tasks can be checked against writable and protected boundaries.
• effects.network makes connectivity dependence explicit for tasks that fetch dependencies or call remote services during setup or verification.
• effects.network_kind can narrow that signal when the task is lockfile-backed dependency hydration, real integration testing, or another network lane that should not be flattened into generic remote-call execution.
• effects.external_state marks out-of-repo mutation such as Docker, database, or hosted-service state so automation can see that blast radius before execution; prefer shipped canonical tokens like docker, postgres, redis, s3, cloudflare, or kubernetes instead of repo-local aliases.
• writable_paths are the paths an AI agent may edit; use them when you want the edit boundary explicit instead of implied.
• protected_paths are the paths an AI agent should avoid changing casually; use them for contracts, locks, or other sensitive files.
• exceptions.sensitive_writes is for narrow exceptions after posture is already correct; use it only when the sensitive path is already writable and that authority is intentional.
• Do not use exceptions.sensitive_writes just to mark a file as important; if the agent should not edit it, keep it in protected_paths instead.
• ota init starter contracts protect ota.yaml by default. If a contract-authoring slice intentionally makes ota.yaml writable, pair that with exceptions.sensitive_writes: [ota.yaml] so the authority is explicit.
• verify_after_changes are the tasks to rerun after edits; use them when you want the review loop to be obvious and repeatable.

tasks:  setup:    internal: true    safe_for_agent: true    effects:      writes:        - .venv      network: true  services:up:    effects:      external_state:        - docker  test:    safe_for_agent: trueagent:  posture: readiness_strict  safe_tasks:    - setup    - test  writable_paths:    - src    - docs    - .venv  protected_paths:    - ota.yaml    - package-lock.json  verify_after_changes:    - test

A policy pack is a shared org rule set. It does not replace ota.yaml; it adds constraints above it.

Use it when you want every repo to follow the same rules without rewriting those rules into each repo contract.

policies:  required_sections:    - runtimes    - tasks    - agent  required_files:    - AGENTS.md  agent:    require_safe_tasks: true    require_writable_paths: true  exports:    require_agents_md: true

• use safe_tasks when you want a safe default set for AI agents and CI tooling
• use writable_paths when you want to tell AI agents exactly what they may edit
• use protected_paths when certain files should not be casually rewritten by AI agents
• use verify_after_changes when you want an obvious post-edit verification step
• use policy packs when the same rule should apply to many repos
• use one ancestor .ota/org-policy.yaml when a workspace should share policy across multiple repos

# Repo-level first, then org policy overlayota doctor --jsonota upota workspace up

• not a ticketing system
• not a waiver workflow
• not a hidden control plane
• not a replacement for ota.yaml

# Avoid: putting run scripts or task bodies in policypolicies:  tasks:    test: ./scripts/test.sh