Choose an autonomy level

When to use thisCopy Anchor Link

Use this guide before you raise any repository above the pull-request level, and again when you add a new playbook. The decision is policy, written as a reviewed document. "Your policy decides. Not the model."

The ladderCopy Anchor Link

AutonomyLevel has eight values, in this order:

A level is a ceiling on what a change may do. It is not a grant on its own: a grant is derived per step from the profile, the playbook step, the risk class and the level, and an agent cannot widen it. See Autonomy levels.

Defaults, rules and floorsCopy Anchor Link

An AutonomyPolicy spec has three parts, and they play different roles.

A match has three optional keys: playbook, risk and environment. An absent key matches every value. The semantics differ between the two uses:

• In a rule, risk matches exactly, and a key the change has no value for does not match.
• In a floor, risk matches that class and every higher one, and a key the change has no value for counts as a match.

Resolution is two steps. The level is the lowest level among the matching rules, else the default. Then no level may exceed the lowest max_level among the matching floors. That ordering is the whole safety argument: the highest configured level never bypasses a matching floor.

Org, repository and component scopeCopy Anchor Link

Resolution loads org, then repository, then component. Two properties follow from the contract.

• Rules narrow or replace. A narrower scope's rule list replaces the wider one. A repository can therefore lower its own level, or choose a different level than the org rule, for its own changes.
• Floors only come from above. A floor set below the org scope is refused. No rule of any scope, including a component, resolves a change above the org floors or any control pack's floors. If the org sets none, the engine's shipped floor applies: Suggest for HIGH and PRIVILEGED, PR for the rest. Pack floors only add caps.

The practical rule: put ceilings in the organization policy repository, put aspirations in repository or component rules, and let the floors arbitrate.

Validate the organization exampleCopy Anchor Link

The spec ships an organization-scoped ladder. Validate it with the open CLI:

go run ./cli/numi validate --files schemas/examples/AutonomyPolicy

revision: "files"
ok       file "org-ladder.yaml" AutonomyPolicy "org-ladder"

apiVersion: numinance.dev/v1
kind: AutonomyPolicy
metadata: {name: org-ladder, scope: SCOPE_ORG}
spec:
  defaults: {level: AUTONOMY_LEVEL_PR}
  rules:
    - {match: {playbook: dependency-upgrade, risk: RISK_CLASS_LOW}, level: AUTONOMY_LEVEL_MERGE}
  floors:
    rules:
      - {match: {risk: RISK_CLASS_HIGH}, max_level: AUTONOMY_LEVEL_SUGGEST}
      - {match: {environment: production}, max_level: AUTONOMY_LEVEL_MERGE}

--files checks the schema and the loader only. It does not resolve levels for a change, so the table below is derived by reading the rules above under the match semantics, not by running a resolver.

Worked resolutionCopy Anchor Link

Low-risk examples are reversible, narrowly scoped changes with strong automated checks: a lockfile bump, a documentation fix. High-risk examples affect production or are hard to reverse. The ladder lets you be generous in the first group and strict in the second without writing exceptions into agent behavior.

Explore the policyCopy Anchor Link

1apiVersion: numinance.dev/v1
2kind: AutonomyPolicy
3metadata: {name: org-ladder, scope: SCOPE_ORG}
4spec:
5  defaults: {level: AUTONOMY_LEVEL_PR}
6  rules:
7✓    - {match: {playbook: dependency-upgrade, risk: RISK_CLASS_LOW}, level: AUTONOMY_LEVEL_MERGE} (matched)
8  floors:
9    rules:
10      - {match: {risk: RISK_CLASS_HIGH}, max_level: AUTONOMY_LEVEL_SUGGEST}
11      - {match: {environment: production}, max_level: AUTONOMY_LEVEL_MERGE}

Promotion is human-acceptedCopy Anchor Link

Raising a playbook's level is a promotion. The design is that qualification statistics from past runs propose it, thresholds come from the playbook's qualification block, and a human accepts it by approving a policy change. An agent cannot promote its own autonomy, cannot edit .numinance/policy/, and cannot lower a floor. See Qualify autonomy.

Failure modes and safeguardsCopy Anchor Link

• A floor in a repository document. Refused at load. Move it to the org policy repository.
• A rule above the floor. Not an error: the rule is simply capped. Check the floors when a level is lower than expected.
• An empty floor match. A floor match may not be empty, so to cap everything name the lowest risk class, as the generated org policy does with RISK_CLASS_READ.
• Level versus breaker. PR_ONLY is a breaker position, not a ladder level. See Circuit breaker.

Next stepsCopy Anchor Link