AutonomyPolicy

Purpose and scopesCopy Anchor Link

AutonomyPolicy sets how far an autonomous change may go. It can be written at any scope. Only an org-scoped kind (or a control pack) may set floors. The loader refuses floors anywhere else.

The levels are the ladder in the types proto:

See Autonomy levels for the concept and Choose autonomy for a decision procedure.

Field referenceCopy Anchor Link

Matching dimensionsCopy Anchor Link

AutonomyMatch has exactly three optional keys.

The two uses differ. 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, so a floor errs toward capping.

Example: organization ladderCopy Anchor Link

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}

Read it top to bottom. The default is PR. A low-risk dependency upgrade may reach MERGE. Any HIGH or PRIVILEGED change is capped at SUGGEST. Anything acting in an environment named production, or with no environment value, is capped at MERGE: the agent can never deploy there on its own authority.

$ numi validate --files schemas/examples/AutonomyPolicy
revision: "files"
ok       file "org-ladder.yaml" AutonomyPolicy "org-ladder"

Explore itCopy 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}

Resolution semanticsCopy Anchor Link

1. Take the lowest level among the matching rules, else the default.
2. Cap it at the lowest max_level among the matching floors (org floors and every control pack's floors).

"Highest level never bypasses a floor" is therefore structural: a rule that says AUTONOMY_LEVEL_OPERATE for a HIGH change resolves to SUGGEST under the example above. Floors from the org and from control packs combine by taking the lowest; pack floors only add caps and never displace the org's. Only org floors displace the shipped floor.

Across scopes: defaults merges field by field; a narrower scope's rules list replaces the wider list; floors are FORBID and cannot be set below the org. SDLCProfile.spec.autonomy is one more layer at the profile's scope, applied after that scope's AutonomyPolicy.

Security implicationsCopy Anchor Link

• An agent cannot widen its own level. A narrower scope cannot lift a floor, and a rule cannot exceed one.
• A repository can always choose a lower level than the org allows.
• The generated repo tree writes no floors block: numi init explains that a floor set below the org scope is refused, and that without an org document the engine applies its shipped floor, which caps every change at PR (HIGH at SUGGEST). Run numi init --org-dir DIR to write explicit org floors.

Common misconfigurationsCopy Anchor Link

$ numi validate --files bad-enum.yaml
revision: "files"
invalid  file "bad-enum.yaml": kind: does not match the kind schema: schema: value does not match (violations: 1): \"/spec/defaults/level\": enum

The same shape appears for a misspelt key (default: for defaults: gives "/spec/default": additionalProperties) and for a short enum such as PR. A floor in a repo-scoped document gives floors is set only at the org scope, shown on Layout and scopes.

What validation checks, and what it does notCopy Anchor Link

Checked: keys, enum names, that rules entries have match and level, that floors.rules is non-empty, org-only floors. Not checked by the open build: whether a rule is shadowed by a floor, whether the named playbook or environment exists, or the resulting level for a given change. numi validate --files runs no resolver.

Next stepsCopy Anchor Link