020-agent-audit.mdc

---
title: Agent Workflow & Audit Requirements
description: Enforce explicit authorization for remote mutations, risk-based checkpoints, mandatory verification, and proportional audit reporting for AI agents.
alwaysApply: true
priority: 20
---

# Agent Workflow & Audit Requirements

These rules apply to **AI agents operating in this workspace**. They are designed to make work **reversible**, **verifiable**, and **auditable**.

---

## 1) Remote Mutations: Explicit Authorization; Read-Only Operations Allowed

Read-only operations do not require checkpoints or extra approval. Examples include file reads/searches, API `GET` requests, listing/status/describe commands, plans/diffs, CLI `--help`, and read-only MCP/tool calls.

Remote mutations require user authorization. A user's direct request to perform a specific mutation counts as authorization; do not ask for redundant approval unless the operation is destructive, irreversible, security-sensitive, or materially broader than the request.

For high-risk remote mutations, record:

- the exact authorization (who/when/what),
- the exact commands executed,
- the results and exit codes,
in the audit report.

This includes (non-exhaustive):

- **Git remote**: `git push`, tag pushes, changing remotes, or any operation that writes to `origin`/`upstream`. Plain `git fetch` is read-only with respect to the remote.
- **GitHub remote**: creating/merging PRs, pushing branches, forking repos, editing issues/PRs via write APIs.
- **Cloud / infra / data planes**: `terraform apply`, `kubectl apply`, `helm upgrade`, `aws cloudformation deploy`, database migrations against non-local DBs, or any command that changes remote resources.

**Commits are local-only** and allowed **only after explicit user authorization** (see [130-git.mdc](130-git.mdc)).

**When a push is authorized**, fetch first and inspect branch divergence. Rebase or merge only when needed and permitted by repository policy; do not blindly run `git pull --rebase` against a dirty or shared branch. Use `git push -u origin HEAD` for a brand-new branch. See [130-git.mdc](130-git.mdc), "Inspect remote state, then push." Never use `--force` or `--force-with-lease` unless the user explicitly authorizes that specific update.

---

## 2) Local Git Repository Discipline

These requirements apply only when the agent is modifying files inside a Git repository.

Requirements:

- Inspect `git status --short`, the current branch, and `HEAD` before routine edits.
- Preserve unrelated user changes and do not assume a clean working tree.
- Record the baseline in an audit report only when the task's reporting tier requires one.
- Create a backup branch only when the operation rewrites history or has a difficult rollback.
- Do not rebase or otherwise rewrite shared history unless explicitly authorized.

---

## 3) Risk-Based Backups and Checkpoints

Use the least disruptive safeguard proportional to the operation.

### No checkpoint required

- Read-only work, including repository inspection and API/tool queries.
- Trivial local-only actions that do not change files.
- Small, reversible edits when the current diff is understood and unrelated user changes can be preserved.

### Lightweight baseline for routine edits

Before routine repository edits, inspect:

```bash
git status --short
git branch --show-current
git rev-parse HEAD
```

The existing commit plus the resulting diff is normally sufficient rollback. Do not create a stash or backup branch merely to edit a few files.

### Explicit checkpoint required

Create a suitable checkpoint before operations with difficult rollback, such as:

- history rewrites, repository-wide mechanical changes, mass deletes or renames;
- generated-file replacement across a large tree;
- broad multi-repository changes;
- an operation that requires a clean tree while unrelated user work is present.

Choose the safeguard that fits the risk:

- Create `checkout-point/<id>` before an authorized history rewrite.
- Preserve a patch or targeted file copy when only selected uncommitted work is at risk.
- Use `git stash` only when the operation genuinely requires a clean tree; explain what is being stashed and restore it promptly.

For external API, cloud, infrastructure, or database mutations, Git checkpoints are not a substitute for operational safety. Use system-specific safeguards such as a dry run or plan, current-state capture, narrow scope, idempotency, concurrency/version checks, and a tested rollback path.

> [!IMPORTANT]
> **User edits always take precedence.**
>
> AI agents MUST NOT discard or overwrite a user's manual working-tree changes unless the user explicitly asks.
> Treat these as destructive operations that require explicit user direction:
>
> - `git restore ...` (worktree discard)
> - `git checkout -- ...` (worktree discard)
> - `git reset --hard ...` (index + worktree discard)
> - `git clean -fd ...` (untracked deletion)
>
> If the agent needs to revert *its own* changes, it must propose the exact commands and file list first and wait for approval.

When a checkpoint is warranted, give it a unique identifier (for example, `YYYYMMDD_HHMMSS`) and record it in the audit report if a report is required.

---

## 4) Local Verification Gate (Mandatory)

Before proposing any commit messages (or asking to commit), run local verification **as applicable**:

- **Unit/integration tests**
- **Lint**
- **Formatting**
- **Type checks**
- **Build/package step**

“As applicable” means:

- If the repo/tooling supports it, run it.
- If it cannot be run (missing tool, missing dependency install, platform limitation, no config present), you MUST state:
  - the exact reason,
  - the closest substitute you ran instead (if any),
  - and what evidence you relied on.

Examples (not exhaustive):

- Python: `pytest`, `ruff`, `black`, `mypy`/`pyright`
- JS/TS: `npm test`, `npm run lint`, `npm run build`, `tsc --noEmit`
- General: `pre-commit run --all-files` (if configured)

---

## 5) Verifiable Audit Report (Tiered - mandatory for critical tasks)

Audit reports are useful, but writing a full command-by-command report for every task can slow down work.
Use the following tiers.

### Critical tasks (MANDATORY - full report)

Write/append a full report when the task has meaningful blast radius or risk, including:

- **History rewriting or force updates**: `git rebase`, `git filter-repo`, `git push --force-with-lease`
- **Remote state changes**: `terraform apply`, `kubectl apply` (non-local clusters), `helm upgrade`, CloudFormation deploys, DB migrations
- **Security / identity / access** changes: auth, IAM, KMS, OIDC, secrets handling
- **Destructive actions** (even if explicitly requested): `git restore` (discard), `git reset --hard`, `git clean -fd`, mass deletes
- **Multi-repo** operations or broad refactors where rollback is non-trivial

### Routine tasks (OPTIONAL - lightweight entry)

For small, routine changes (especially docs-only), an audit report is optional.
If you want a record, append a lightweight entry:

- timestamps
- commit SHA + subject
- file list
- push command + result (if applicable)

### Trivial local-only tasks (NO report)

No report is needed for trivial local-only actions with no commit/push and no risk (for example: reading files, answering questions, exploring options).

### Repo root identifier (required)

Agents MUST resolve the absolute repository root path:

- `export GIT_REPO_ROOT="$(git rev-parse --show-toplevel)"`

### Path rules

- If `<GIT_REPO_ROOT>/tmp/` exists **and** it is gitignored, write to:
  - `<GIT_REPO_ROOT>/tmp/agent_reports/$(date +%F)-agent-report-<repo>-<branch>.md`
- Otherwise write to:
  - `/tmp/$(date +%F)-agent-report-<repo>-<branch>.md`

### Append vs create (required)

- If the report file already exists for the day, **append** a new session section (include start/end timestamps, commands, results, etc.)
- If it does not exist, **create** it and then append the session content

### Required contents (critical tasks)

The report MUST include:

- Start and end timestamps (**local time and UTC**)
- Repo name, branch name, `HEAD` SHA
- Every command executed (copy-pasteable) with **exit codes**
- Summary of changes:
  - `git status`
  - `git diff --stat`
  - list of changed files
- Verification outputs: test/lint/format/type-check/build summaries
- Planned commits and proposed messages, if applicable
- Checkpoint decision and any checkpoint identifiers
- Any explicitly authorized remote-write operations (if any) with timestamps, commands, and exit codes

### Optional: Terminal Recordings (asciinema)

For complex debugging sessions or demos, agents MAY create terminal recordings using `asciinema`.

**When to record:**

- Complex debugging where timing/flow matters
- Sessions that would benefit from visual playback
- When user explicitly requests a recording

**Recording path:**

- Save to: `<GIT_REPO_ROOT>/tmp/agent_reports/recordings/$(date +%F)-agent-recording-<repo>-<branch>-$(date +%H%M%S).cast`
- Reference the recording path in the markdown audit report

**How to record:**

```bash
# Start recording
asciinema rec -q "<GIT_REPO_ROOT>/tmp/agent_reports/recordings/session.cast"

# ... perform commands ...

# Stop recording (Ctrl+D or exit)
```

**Important:**

- Recordings are a **supplement**, not a replacement for markdown reports
- The markdown report remains the **primary audit artifact** (searchable, structured)
- Recordings are for **understanding flow**, not for audit compliance

---

## 6) If Commits Are Authorized Later

Only after the user explicitly authorizes commits:

- Commit **locally** with the agreed messages. Respect **commit signing** ([130-git.mdc](130-git.mdc), **Commit signing**): do not bypass signing (for example `--no-gpg-sign`) unless the user explicitly requested an unsigned commit and the reason is recorded.
- If an audit report is required or already exists, append:
  - commit SHAs and commit messages
  - `git log --date=iso-strict -n <N>` output (where `<N>` covers the new commits)
  - signature verification output, e.g. `git log -n <N> --show-signature`, or an explicit note if commits are unsigned and why

---

## 7) GitHub CLI (`gh`) Mutation Policy

Allowed without mutation authorization:

- `gh repo view`
- `gh issue list` / `gh issue view`
- `gh pr list` / `gh pr view`
- `gh api` **GET requests only**

Allowed only when the user's request authorizes the specific mutation:

- `gh pr create`, `gh pr merge`
- `gh repo fork`
- any `gh api` mutation (POST/PATCH/PUT/DELETE)

Preview target repository, branch, title/body, or affected resource before executing the mutation. Require a separate confirmation for destructive, irreversible, privileged, or materially broader actions.

---

## 8) Method to the Madness (Required Sequence)

Understand task -> classify risk and mutation type -> inspect baseline when editing ->
take a checkpoint only if warranted -> make the minimal change -> verify proportionally ->
report according to tier -> obtain authorization for commits or remote mutations

---