# P5: Safe Retries and Explicit Mutation Boundaries

## Definition

Every CLI MUST support `--dry-run` so agents can preview any command before committing it. Write operations MUST clearly
separate destructive actions from read-only queries. An agent that cannot distinguish a safe read from a dangerous write
will either avoid the tool or execute mutations blindly — both are failure modes.

## Why Agents Need It

Agents retry failed operations by default. If a write operation is not idempotent, a retry creates duplicates, corrupts
data, or trips rate limits. When destructive operations require explicit confirmation (`--force`, `--yes`) and support
preview (`--dry-run`), an agent can safely explore what a command would do before committing to it. Read-only tools are
inherently safe for retries, but they still benefit from help text that names the mutation contract — "this does not
modify state" is a better sentence to put in `--help` than to assume.

## Requirements

**MUST:**

- Destructive operations (delete, overwrite, bulk modify) require an explicit `--force` or `--yes` flag. Without it, the
  tool refuses the operation or enters dry-run mode — never mutates silently.
- The distinction between read and write commands is clear from the command name and help text alone. An agent reading
  `--help` immediately knows whether a command mutates state.
- A `--dry-run` flag is present on every write command. When set, the command validates inputs and reports what it would
  do without executing. Dry-run output respects `--output json` so agents can parse the preview programmatically.

**SHOULD:**

- Write operations are idempotent where the domain allows it — running the same command twice produces the same result
  rather than doubling the effect.

## Evidence

- `--dry-run` flag on commands that create, update, or delete resources.
- `--force` or `--yes` flag on destructive commands.
- Command names that signal intent: `add`, `remove`, `delete`, `create` for writes; `list`, `show`, `get`, `search` for
  reads.
- Dry-run output that shows what *would* change without executing.

## Anti-Patterns

- A `delete` command that executes immediately without `--force` or confirmation.
- Write commands sharing a name pattern with read commands (e.g., a `sync` that silently overwrites local state).
- No `--dry-run` option on bulk operations, where a preview prevents costly mistakes.
- Operations that fail on retry because the first attempt partially succeeded — non-idempotent writes without rollback.

Measured by check IDs `p5-dry-run`, `p5-destructive-guard`. Run `agentnative check --principle 5 .` against your
CLI to see each.