# AutomationProfileService Reference

## Overview

The `AutomationProfileService` resolves the effective automation profile
for plan execution using a four-level precedence hierarchy.

## Profile Precedence

Profiles are resolved in order (first non-null wins):

| Priority | Source        | Description                                  |
|----------|---------------|----------------------------------------------|
| 1        | Plan-level    | Explicitly set via `--automation-profile`     |
| 2        | Action-level  | Default profile set on the action template    |
| 3        | Project-level | Set via project configuration                 |
| 4        | Global-level  | Config key or `CLEVERAGENTS_AUTOMATION_PROFILE` env var |

If no profile is set at any level, the global default is `manual`.

## Configuration

### Config Key

```yaml
core:
  automation_profile: "supervised"
```

This sets the global default profile name. The Settings field is
`default_automation_profile`.

### Environment Variable Override

```bash
export CLEVERAGENTS_AUTOMATION_PROFILE=auto
```

The environment variable takes precedence over the config file value
when the config field is empty.

## Legacy Mapping

The `automation_level` setting is retained for backward compatibility.
It is mapped to built-in profiles as follows:

| `automation_level` Value | Built-in Profile |
|--------------------------|------------------|
| `manual`                 | `manual`         |
| `supervised`             | `supervised`     |
| `auto`                   | `auto`           |
| `full_auto`              | `full-auto`      |

When `default_automation_profile` is set, it takes precedence over
`default_automation_level`.

## Auto-Progress Behavior

The `PlanLifecycleService` uses profile thresholds to decide whether
to auto-progress plans:

- **Strategize → Execute**: auto-progresses when `profile.create_tool < 1.0`
- **Execute → Apply**: auto-progresses when `profile.select_tool < 1.0`

A threshold of `0.0` means fully automatic (no human gate required).
A threshold of `1.0` means human approval is always required.

## Built-in Profiles

Eight built-in profiles ship with every installation:

| Profile       | create_tool | select_tool | Behavior                |
|---------------|-------------|------------|-------------------------|
| `manual`      | 1.0         | 1.0        | Human approves all      |
| `review`      | 0.0         | 1.0        | Human reviews before apply |
| `supervised`  | 1.0         | 1.0        | Human reviews strategy + execution |
| `cautious`    | 0.7         | 1.0        | Probabilistic gates     |
| `trusted`     | 0.0         | 1.0        | Auto most, human apply  |
| `auto`        | 0.0         | 1.0        | Fully auto except revert|
| `ci`          | 0.0         | 0.0        | CI pipeline mode        |
| `full-auto`   | 0.0         | 0.0        | No gates at all         |

## Persistence

Custom profiles are stored in the `automation_profiles` table with
the namespaced name as the primary key. The repository supports
list, show (get_by_name), upsert, and delete operations with a
`schema_version` guard for optimistic concurrency.

## API

### `resolve_profile(plan_profile, action_profile, project_profile)`

Resolves the effective profile using the four-level precedence.

### `get_profile(name)`

Looks up a profile by name (built-in first, then repository).

### `map_legacy_level(level)`

Maps a legacy `automation_level` string to a profile name.

### `resolve_legacy_level(level)`

Resolves a legacy `automation_level` to a full `AutomationProfile`.

### `list_profiles()`

Returns all built-in and custom profiles.

### `create_profile(config)`

Creates and persists a custom profile.

### `update_profile(name, config)`

Updates a persisted custom profile.

### `delete_profile(name)`

Deletes a persisted custom profile.