Skip to content

Trust the policy and the profiles only after they are validated

Prove that the canonical policy parses with every key it needs declared, that every profile parses and the default exists, and that what the policy declares as enforced is what actually runs.

described Policy and enforcementbasicmaintainerread-only

Situation

The policy is the one file everything else is derived from. If it carries a key nobody reads, a typo becomes a silent default; if a profile is missing, the worker runs under nothing; if the policy says a hook enforces something and the hook does not exist, the enforcement is a sentence. None of that is visible by reading the files.

What you run

  • doctor: the policy and every profile parsed with unknown keys refused, every value the code reads declared, the default profile present, and each declared enforcement reconciled against what actually runs
  • check: outside a task, exit 12 rather than a run that checked nothing

Scenario

setup: installed-wired
given:
  - 'installed, and the two enforcements the policy declares are actually in place as hooks'
steps:
  - id: policy
    run: ['doctor']
    note: 'the policy parses, every value the code reads is declared with no reader-side default, every profile parses and the default profile exists, and every declared enforcement is reconciled against a hook that calls the tool'
    expect:
      exit: 0
      stdout_contains: ['^OK   policy      .ai/repo/policy.yaml — parsed', 'no reader-side default', '^OK   profiles', "default 'implementation' exists", '^OK   wiring      doctor-on-commit', '^OK   wiring      finish-on-push', 'doctor: 0 failure']
  - id: no-task
    run: ['check']
    note: 'outside a task the same contract answers with a precondition code, not a green run that checked nothing'
    expect:
      exit: 12
      stdout_contains: ['no active task']
then:
  - 'an unknown key in the policy or a profile is a parse failure, not an ignored line'
  - 'a policy value the code reads without a declaration is a failure'
  - 'exit 12 means a precondition is missing; it is never confused with a clean run'

Outcome

What the policy says is what the tool does, and both are proven before any worker reads them. The exit code is the answer: 0 clean, 10 a failing finding, 12 a missing precondition.

No scenario yet

This use case is described, not proved: it names its commands and rules, and nothing executes it. It cannot be more than described until a scenario is added.

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

The rules that make it hold

Guarantees exercised

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

The moments this answers