Autonomy Model

The autonomy model decides when the AI pauses for human approval and when it proceeds without asking. It is the most opinionated piece of the platform — every other gate is downstream of a decision about whether the action belongs in the Hard Floor, the configurable middle, or the autonomous bottom.

This page is the focused explainer. The full strategic context is in ai-engineering-strategy.md §10. The live configuration is in autonomy/defaults.yaml.

The three categories

The default is autonomous action. The AI proceeds without asking unless a specific gate stops it. Three categories of action, ordered by descending strictness:

1. always_require_approval (Hard Floor) — always requires explicit human approval. Cannot be disabled by any user override. 6 items.
2. configurable_gates — default off (autonomous) at the platform level. Each developer can opt in via ~/.claude/user-overrides.yaml to require approval for specific action classes. 6 items.
3. never_ask — the AI never pauses, regardless of any configuration. Reversible, low-risk, high-frequency. 8 items.

The four criteria for Hard Floor

The Hard Floor list is intentionally short. An action belongs there if and only if it meets all four of the following criteria. The criteria exist so the floor stays meaningful — adding everything that "feels risky" would turn the autonomous loop back into approval theater.

1. Irreversibility. Undoing the action requires significantly more effort than performing it, or is impossible. A production deploy of a broken build requires a rollback procedure. A DROP TABLE cannot be undone without a backup restore.
2. Blast radius beyond the current actor. The action affects users, systems, or developers outside the person running Claude. A force-push to a shared branch affects every colleague on that branch.
3. No effective recovery via tooling. If a CI gate already catches the action downstream — for example, breaking-contract changes caught by a contract gate before merge — the action is not a Hard Floor item. The CI gate is the safety net.
4. Reasonable developers do not disagree about the default. If reasonable developers all agree the action should be autonomous (creating a branch) or all agree it should require approval (production deploy), the answer is clear. If they disagree, the action belongs in the configurable middle.

Adding to the Hard Floor requires an ADR demonstrating all four.

The six Hard Floor items

Item	Why it qualifies (criteria 1+2 always; 3+4 noted where decisive)
production_deploy	Irreversible (rollback is recovery, not undo). Affects all customers. No CI catches a bad deploy after it ships.
force_push_to_shared_branch	Destroys history irreversibly. Affects every colleague on the branch. No recovery past local reflog windows.
secret_rotation	Invalidates running sessions across services. Requires coordinated reissue.
destructive_db_operation	DROP TABLE, TRUNCATE, unrestricted DELETE in production. Irreversible without backup restore.
public_communication	Confluence publish to non-draft pages, customer-facing email, public Slack channels. Retraction does not unsend.
codeowners_modification	Changes who can approve PRs across the repo. Affects every future PR. Recovery requires a counter-PR with the same approval.

The six configurable gates

Default: off (autonomous). Each developer can flip any of these to on in their personal override file to require approval before the AI proceeds.

Gate	What it controls
clickup_comment_post	Posting a comment to a ClickUp task on the user's behalf.
clickup_status_to_done	Moving a ClickUp task to "Done" status. ("In Progress" moves are in never_ask.)
cross_repo_pr_creation	Opening a PR in a different repo than the one the current session is rooted in.
schema_migration	Generating or applying a database migration in any environment.
api_contract_breaking	Making a breaking change to a contract in a consumer repo's /contracts/ (convention defined in policies/api-contract-change.yaml).
large_refactor	Changing more than threshold_files: 20 files in a single PR.

The eight never-ask items

These are reversible, low-risk, and constant. Pausing for them would add friction without safety value.

branch_creation
commit_to_feature_branch
push_to_feature_branch
test_execution
lint_autofix
type_check
clickup_status_to_in_progress
state_sync_update

Per-user overrides

Each developer maintains a personal override file at ~/.claude/user-overrides.yaml. This file lives in the developer's home directory, not in any repo — it is personal and not committed.

# Example: ~/.claude/user-overrides.yaml
user: ariel
overrides:
  clickup_comment_post: on      # I want approval before AI comments
  schema_migration: on          # I want approval on schema changes
  # The other 4 gates use the platform default (off / autonomous).

The override file is validated against autonomy/schema.json — a JSON Schema draft-07 that:

• Restricts keys to the six configurable gates (typos like clickup_comment_psot are rejected).
• Restricts values to the literal strings "on" / "off" (booleans true/false are rejected).
• Rejects any attempt to override Hard Floor or never-ask items via the schema, not just by convention.

A senior engineer can run mostly autonomous. A new hire can crank up the gates. Both work inside the same architectural framework. The configuration is visible — every developer can read the platform defaults and their own override and predict the AI's behavior. There is no hidden state.

Enforcement (three layers)

The Hard Floor is enforced in three places, not one — a single layer would be one missing prompt away from a production incident.

1. The autonomy YAML. Items live in always_require_approval in autonomy/defaults.yaml. The Policy Engine reads this on every action (step 4 of /continue).
2. Git hooks and CI workflows. Several items are physically blocked at the tooling level. no-master-edit.sh prevents direct commits to shared branches; block-edit-on-master.sh is the Claude-Code-specific equivalent that intercepts Edit/Write tool calls. block-dangerous-git.sh prevents force-push. The deploy script requires a manual confirmation flag the AI cannot synthesize.
3. The expert agents. The auth-security, devops-infra, and database agents each reference the relevant Hard Floor items in their "Hard Rules" section. Agents that touch these domains remind the AI explicitly.

See also

• ai-engineering-strategy.md §10 — the strategic case, the criteria in full, and the worked examples.
• deterministic-ai.md principle 3 — the philosophical framing.
• autonomy/defaults.yaml — the live configuration.
• autonomy/schema.json — the user-override schema.
• autonomy/examples/user-override.example.yaml — example override file.