# Agent autonomy by repository path

How far an agent may go in a repository depends on **where** it is changing code, not only on how
well it has done before. A payments directory can be capped at root-cause analysis while the UI
directory allows an automatic attempt, and a handful of paths (CI definitions, migrations,
infrastructure) are closed to every agent in every repository.

This sits beside the earned-autonomy ladder (`docs/autonomy-ladder.md`). The two are intersected:
**a run's rung is the lower of its category rung and its path rung.** A demotion on the ladder
applies on top of the path cap, and a loose path cap never lifts a demoted category. **No rung
reaches merge**: the rungs are `RCA_ONLY`, `DRAFT_PR` and `AUTO_ATTEMPT`, and merging stays a
human act.

## The `autonomy` block

In `bucker.yml`, per repository, under `extensions:`:

```yaml
version: 2
extensions:
  autonomy:
    - project: checkout
      repository: acme/checkout        # a repository this organization has connected
      paths:
        - { glob: "src/payments/**", maxRung: RCA_ONLY }
        - { glob: "src/ui/**",       maxRung: AUTO_ATTEMPT }
      deny:
        - "src/secrets/**"
```

| Field | Meaning |
| --- | --- |
| `paths[].glob`, `maxRung` | The highest rung a run may hold when its blast radius touches a matching path. Where several caps match, the **lowest** wins. |
| `deny` | Globs no agent patch may touch, in addition to the defaults. |

Globs are repository-relative, forward-slashed, with `*` and `**`; no leading `/`, no `..`, no `!`.
Matching is **case-insensitive**, so `Infra/x` does not slip past `infra/**` on a case-insensitive
checkout.

### The defaults are not optional

These are denied in every repository whether or not a policy is stored, and a file's `deny` can only
add to them: `.github/**`, `**/migrations/**`, `infra/**`, `**/CODEOWNERS`, `**/bucker.yml`,
`**/bucker.yaml`. They are the paths whose edit changes what runs next with the repository's own
credentials, or who decides what is allowed. An unconfigured project is the defaults, never "no
policy". The policy digest covers the defaults, so a release that changes them changes the digest.

### Several repositories in one project

A run's blast radius comes from stack frames through code mappings, which can span repositories, and
a run that cannot say which repository a path belongs to must not be judged by the most permissive
one. A project's effective policy is therefore the union of every repository's deny globs and the
lowest cap per glob.

## What it does

1. **Before a run is queued.** The evidence radius is intersected with the policy. A denied path is
   dropped from the radius, with the reason recorded where the certificate will carry it. A run left
   with nothing it may touch is refused (`403`, code `AUTONOMY_PATH_DENIED`) before it is queued and
   before anyone is asked. A cap becomes a **risk floor** on the proposal (`RCA_ONLY` is critical,
   `DRAFT_PR` sensitive), so an organization that lets `pr.propose` through automatically still has
   to be asked for a run capped at `RCA_ONLY`. A cap can only make a decision stricter.
2. **For an inbound patch from an outside agent.** A patch touching a denied path is refused (`403`,
   `AUTONOMY_PATH_DENIED`, every offending path named) before validation and long before a sandbox,
   without opening an approval request. The deny globs also travel on the radius the patch is judged
   against, so a denied path cannot come back inside a prefix the run owns (`test/migrations/…`
   inside `test/`). The handoff bundle an outside agent receives carries the same bounded radius.
3. **On the certificate.** The certificate's `pathPermission` claim carries the policy digest, the cap
   and the paths dropped. It is read off the radius the run was bounded by, and it is covered by the
   signature. A certificate without the claim predates path policy: "not attested".

## Who changes it

`autonomy_policy.update` is human-only and maps to `org:admin` (an **owner**), like the other acts that
change what agents may do. An agent, a delegated OAuth client or any non-owner is refused before the
organization or any policy is read. There are two doors, and both write the row and its audit record
in one transaction:

- the dashboard; and
- `bucker config apply`, with the plan hash.

An agent can never apply a change. It can PLAN the `autonomy` kind (so a future `config.propose`
door, which would open a draft pull request only, can carry one), but the apply step re-asserts a
person in their own right, and any pull request is merged by a person and applied by a person. Removing an entry
from the file does not delete its row; narrowing is an edit (set a lower cap), and a policy that
quietly vanished because a line was deleted would be the widest edit there is.

## Reading it

The MCP tool `autonomy_policy_get` (agents toolset, `project:read`, 500 tokens) returns the defaults,
each repository's stored caps and denies with their digests, and the effective combination. Globs and
repository names are text a person typed, so they are sanitized and declared in `trust.untrustedFields`.
