# Autonomy envelope tracker

The per-agent per-task-type approval-state record. Referenced from every operator's CLAUDE.md framing block.

## The mechanism

Each PA agent maintains an autonomy envelope at `agents/<paName>/autonomy-envelope.md`. The file is a markdown document with a YAML frontmatter block carrying the machine-readable state and a body that renders the state for human consumption plus a per-task-type history log.

The envelope is the durable record of what the operator has approved the PA to do without asking, on a per-task-type basis. The PA's day-to-day judgement calibrates from operator reactions; the envelope is the persistent state you check when the reflex is unclear.

## The three states

| State | Meaning | PA behaviour |
|---|---|---|
| `fullyApproved` | Operator has said "just do this class of task; don't ask." | Act. Don't ask. If the reflex is to check, resist; the envelope is telling you not to. |
| `checkBeforeCommitting` | Operator wants sign-off on the durable action but not on the drafting. | Draft, get sign-off before commit / push / publish / ship. Read-only exploration is fine without asking. |
| `needsFullSupervision` | Operator hasn't approved this class yet, or has explicitly demoted it. | Do not act. Escalate every step. |

The envelope's authority is above the PA's own inclination. If the envelope says a category is `needsFullSupervision` but the PA thinks the operator would be fine with autonomous action, the PA does NOT act; the operator can promote the category via `pa autonomy set` when they're ready.

## Task-type taxonomy

**Core does not enforce a specific task-type taxonomy**; every operator's surface types are different. An example taxonomy the operator might seed with:

- `li-comment-draft`; drafting a LinkedIn comment reply.
- `li-post-draft`; drafting a full LinkedIn post.
- `article-draft`; drafting a long-form article.
- `code-dispatch`; dispatching a code implementer.
- `code-inline`; writing code in the main thread.
- `git-commit-push`; committing and pushing.
- `secret-access`; reading operator secrets from the vault.
- `contact-outreach`; reaching out to a contact on the operator's behalf.

The operator seeds their own taxonomy per their surface types. The schema (`packages/core/schema/autonomy-envelope.schema.json`) enforces field shape but not the specific set of `taskTypes.id` values.

## CLI

`pa autonomy`; four subcommands.

| Subcommand | Purpose |
|---|---|
| `pa autonomy init <agent>` | Create an empty envelope for a new agent. Idempotent; errors if envelope already exists. |
| `pa autonomy get <agent> [<task-type>]` | Print current state. Task-type optional (prints full table if omitted). |
| `pa autonomy set <agent> <task-type> <state> [--note <text>]` | Update state. Adds timestamped history entry to the body. Validates state against the enum. |
| `pa autonomy list [<agent>]` | List envelopes across all agents (or one), with staleness signals (envelope untouched for >30 days → warning). |

Exit codes:
- `0` ok
- `1` usage error
- `2` invalid state or unknown agent
- `3` IO error

## Session-boot integration

The PA reads the autonomy envelope on every session boot (per CLAUDE.md.template Startup routine). The envelope is one of the small set of files loaded before the first user response.

**Injection surface (per OQ-A1).** The core ships the read-side of the mechanism (schema + CLI + docs); the core does not ship a `SessionStart` hook. Operator-side hook infrastructure (e.g. an operator's `boot-context` tool) can invoke `pa autonomy get <agent> --format json` at session boot and inject the resulting summary into `additionalContext` alongside other live-state blocks.

The `pa autonomy get <agent> --format json` output is stable JSON that a boot-context tool can consume without parsing the markdown file directly.

## Difference from the three-zone role envelope standard

**Related but separate.** The three-zone ROLE envelope is a standard for how ROLES calibrate autonomy across their whole surface; informational, decision-support, decision-authority. That's a property of the role definition.

This tracker is a PER-AGENT, PER-TASK-TYPE record that the operator sets and demotes/promotes dynamically. Different granularity, different lifecycle. Both patterns coexist.

## File shape

Example `agents/<paName>/autonomy-envelope.md`:

```markdown
---
agent: dave
owner: barry
updated: 2026-07-05T14:30:00Z
taskTypes:
  - id: li-comment-draft
    label: LinkedIn comment draft
    state: checkBeforeCommitting
    stateSince: 2026-07-04T09:00:00Z
    operatorNote: Voice restarts are cheap mid-draft; post-publication corrections are expensive.
  - id: code-dispatch
    label: Code implementation dispatch
    state: fullyApproved
    stateSince: 2026-07-05T14:30:00Z
---

# Autonomy envelope; dave

## Current state

| Task type | State | Since | Note |
|---|---|---|---|
| LinkedIn comment draft | checkBeforeCommitting | 2026-07-04 | Voice restarts are cheap mid-draft. |
| Code implementation dispatch | fullyApproved | 2026-07-05 |; |

## History

### 2026-07-05T14:30:00Z; code-dispatch promoted to fullyApproved
Operator note: none.

### 2026-07-04T09:00:00Z; li-comment-draft demoted to checkBeforeCommitting
Operator note: Voice restarts are cheap mid-draft; post-publication corrections are expensive.
```

## Related

- `packages/core/schema/autonomy-envelope.schema.json`; canonical schema.
- CLAUDE.md.template framing block; the operator-facing pointer.
- `packages/core/knowledge/operator-interface/escalation-and-correction.md`; how the envelope interacts with escalation.
- `packages/cli/src/autonomy/`; CLI implementation.