P5: Safe Retries and Explicit Mutation Boundaries

Definition

Every CLI with write operations MUST support --dry-run so agents can preview a mutation before committing it. Commands MUST make the read-vs-write distinction visible from name and --help alone, and destructive writes MUST require explicit confirmation. 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

Agent harnesses commonly retry failed operations. 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

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 audit IDs p5-dry-run, p5-destructive-guard. Run anc audit --principle 5 . against the CLI under test to see each.