Org Policy Baseline

This is the concrete policy file to use when an org wants a baseline that is strict enough to be useful and small enough to be adopted.

It keeps repo contracts separate from org governance while still giving doctor a real policy layer to explain.

• shared repo guardrails
• explicit agent safety surfaces
• strict contract versioning
• adapter bootstrap approval without hiding provisioning policy

policies:  required_sections:    - checks    - tasks    - agent  required_files:    - AGENTS.md  strict_versions: true  exports:    require_agents_md: true

required_sections says which contract sections must exist before the repo can be treated as governed and ready for review.

• Use it when every repo in the org must declare the same minimum readiness surfaces such as tasks, checks, or agent.
• Use it when missing structure should be a policy finding instead of hidden drift.
• Keep this list small and intentional so adoption stays realistic.

policies:  required_sections:    - checks    - tasks    - agent

required_files says which files must exist at the governed boundary in addition to the repo contract.

• Use it when repos must carry shared guidance such as AGENTS.md.
• Use it when the org wants reviewable guidance checked into the repo instead of implied by process.
• Keep file requirements focused on stable artifacts, not temporary workflow files.

policies:  required_files:    - AGENTS.md

strict_versions tells ota whether already-installed runtime and tool versions must also comply with policy instead of only satisfying the repo contract.

• Use it when readiness and provisioning must be deterministic across laptops, CI, and container targets.
• Use it when version drift in an existing environment should be called out as a policy problem, not tolerated implicitly.
• With strict_versions: true, ota doctor reports repo-satisfying but policy-noncompliant installed versions explicitly, and ota run can repair them when the backend opts into fulfillment: run.
• Turn it on when the org cares more about reproducibility than permissive local variation.

policies:  strict_versions: true

agent.require_safe_tasks says agent-facing execution must be explicit about which tasks are safe before ota can treat them as part of the normal automation surface.

• Use it when agent execution must stay bounded and reviewable.
• Use it when a repo should not rely on implied task safety.
• Pair it with agent.safe_tasks in ota.yaml so policy and contract say the same thing clearly.

policies:  agent:    require_safe_tasks: true

agent.require_writable_paths says the contract must declare where an agent may edit before ota treats the repo as safely automatable.

• Use it when broad implicit edit scope would be unsafe.
• Use it when teams need the allowed write surface to be visible in review.
• Pair it with agent.writable_paths in ota.yaml so execution boundaries stay explicit.

policies:  agent:    require_writable_paths: true

exports.require_agents_md says the org expects repo guidance to be generated and kept aligned with the contract as AGENTS.md.

• Use it when the repo should publish one reviewable agent-facing guide instead of ad hoc instructions.
• Use it when contract-backed exports should remain part of the governed baseline.
• Pair it with ota agents or repo export flows so the file stays derived instead of hand-maintained drift.

policies:  exports:    require_agents_md: true

provisioning approves which source ota may use for each runtime or tool, including platform-specific overrides for macOS, Linux, or Windows.

• Use it when the org wants source selection to be policy-driven instead of guessed from the environment.
• Use platform overrides when host and container targets should use different package managers.
• Keep approved versions aligned with the actual versions available in the approved source.
• Semver ranges can authorize version families, but ota only resolves a concrete install version when policy provides an explicit exact candidate.
• When ota does not have a resolved_version, it keeps the original contract version as the backend input instead of inventing one.
• Doctor JSON now records the requested version, normalized semver requirement, matched policy rule, resolved version, and any package mapping when ota can select one deterministically.
• OS package managers (apt, dnf, pacman, winget, choco, scoop) require an explicit package identifier in policy.

policies:  provisioning:    node:      source: apt      package: nodejs      approved_versions:        - "22"      platforms:        macos:          source: brew          approved_versions:            - "22"        linux:          source: apt          package: nodejs          approved_versions:            - "22"        windows:          source: choco          package: nodejs          approved_versions:            - "22"

version_policy defines which runtime and tool versions policy approves.

• Use it when the org wants version governance even if installs stay manual or come from another bootstrap path.
• When strict_versions is off, version_policy constrains what the repo contract may declare.
• When strict_versions is on, the same version_policy rules also constrain the installed versions that ota actually resolves at run or doctor time.
• Keep it separate from provisioning: the contract still declares what the repo needs, version_policy constrains the allowed versions, and provisioning says where installs may come from.
• Use platforms.<os> when the allowed version set differs between Windows, macOS, Linux, or container targets.
• Doctor should explain version-policy failures as contract-versus-policy mismatches, not as missing package-manager rules.

policies:  version_policy:    runtimes:      node:        approved_versions:          - "22"    tools:      pwsh:        platforms:          windows:            approved_versions:              - "7.6.0"

adapter_bootstrap approves how ota may install its own adapter binaries when the adapter is missing from the target environment.

• Use it when repo provisioning depends on an adapter such as brew or sdkman and the adapter itself may not exist yet.
• Keep bootstrap approval separate from repo provisioning approval so the trust boundary stays clear.
• Approve only the bootstrap methods your org is willing to allow on developer machines or execution targets.

policies:  adapter_bootstrap:    brew:      source: brew-bootstrap      approved_versions:        - "4.4"    choco:      source: choco-bootstrap      approved_versions:        - "2.0.0"    sdkman:      source: sdkman-bootstrap      approved_versions:        - "1.0"  native_packages:    apt:      approved:        - build-essential        - libpq-dev    brew:      approved:        - pkg-config

Copy this into .ota/org-policy.yaml and tune versions to match the approved versions in your fleet.

policies:  required_sections:    - checks    - tasks    - agent  required_files:    - AGENTS.md  strict_versions: true  version_policy:    runtimes:      node:        approved_versions:          - "22"  agent:    require_safe_tasks: true    require_writable_paths: true  exports:    require_agents_md: true  adapter_bootstrap:    brew:      source: brew-bootstrap      approved_versions:        - "4.4"    choco:      source: choco-bootstrap      approved_versions:        - "2.0.0"    sdkman:      source: sdkman-bootstrap      approved_versions:        - "1.0"  native_packages:    apt:      approved:        - build-essential        - libpq-dev    brew:      approved:        - pkg-config

Use this when the org wants a single policy pack that keeps macOS on Homebrew, Linux containers on apt, and Java on sdkman.

This is the shape that teaches the split clearly: the policy chooses the approved source per platform, and ota resolves against the selected execution target.

policies:  required_sections:    - runtimes    - tools    - tasks    - checks    - agent  required_files:    - AGENTS.md  strict_versions: true  version_policy:    runtimes:      node:        approved_versions:          - "24"    tools:      pwsh:        platforms:          windows:            approved_versions:              - "7.6.0"  agent:    require_safe_tasks: true    require_writable_paths: true  exports:    require_agents_md: true  provisioning:    curl:      source: brew      approved_versions:        - "8.13.0"      platforms:        macos:          source: brew          approved_versions:            - "8.13.0"        linux:          source: apt          package: curl          approved_versions:            - "8.13.0"        windows:          source: choco          package: curl          approved_versions:            - "8.13.0"    jq:      source: brew      approved_versions:        - "1.8.1"      platforms:        macos:          source: brew          approved_versions:            - "1.8.1"        linux:          source: apt          package: jq          approved_versions:            - "1.8.1"        windows:          source: choco          package: jq          approved_versions:            - "1.8.1"    java:      source: sdkman      approved_versions:        - "21"      platforms:        macos:          source: sdkman          approved_versions:            - "21"        linux:          source: sdkman          approved_versions:            - "21"        windows:          source: choco          package: java          approved_versions:            - "21"    maven:      source: brew      approved_versions:        - "3.9.14"      platforms:        macos:          source: brew          approved_versions:            - "3.9.14"        linux:          source: apt          package: maven          approved_versions:            - "3.9.14"        windows:          source: choco          package: maven          approved_versions:            - "3.9.14"    node:      source: brew      approved_versions:        - "24.14.1"      platforms:        macos:          source: brew          approved_versions:            - "24.14.1"        linux:          source: apt          package: nodejs          approved_versions:            - "24.14.1"        windows:          source: choco          package: nodejs          approved_versions:            - "24.14.1"    yq:      source: brew      approved_versions:        - "4.52.5"      platforms:        macos:          source: brew          approved_versions:            - "4.52.5"        linux:          source: apt          package: yq          approved_versions:            - "4.52.5"        windows:          source: choco          package: yq          approved_versions:            - "4.52.5"  adapter_bootstrap:    brew:      source: brew-bootstrap      approved_versions:        - "4.4"    choco:      source: choco-bootstrap      approved_versions:        - "2.0.0"    sdkman:      source: sdkman-bootstrap      approved_versions:        - "1.0"

• macOS uses brew for the tools that are meant to be installed from Homebrew.
• Linux or container execution uses apt for the same tools when the container image is apt-based.
• Windows uses choco for the same repo tools, including java, when the org wants a Windows-native source-manager path.
• The policy decides the approved source; ota resolves that source against the execution target, not by guessing from the host shell.

• ota doctor becomes a governance check, not just a local readiness scan
• repos stay explicit instead of drifting into scripts
• agent safety remains visible and reviewable
• adapter bootstrap stays separate from repo provisioning
• the policy is strong enough to matter without forcing every repo to declare provisioning rules it does not use

• you want a shared org rule set for many repos
• you want AGENTS.md to be present everywhere
• you want safe-task and writable-path declarations enforced
• you want bootstrap approval to stay explicit