# Issue Handling — AO CLI Reference

> **All issue operations MUST use the `ao` CLI.** Never edit JSONL files directly.

AO uses an append-only JSONL event store. The source of truth is `events.jsonl`; `active.jsonl` is a deterministic snapshot rebuilt via `ao rebuild`.

## Data Model

```
.agent/ops/issues/
├── events.jsonl     # Append-only event log (source of truth, never mutated)
├── active.jsonl     # Deterministic snapshot (rebuilt via ao rebuild)
├── .counter         # Monotonic issue number counter
└── references/      # Reference docs for complex issues
```

## Issue ID Format

All issue IDs use the form `TYPE-NNNN@HHHHHH`:
- `TYPE` — issue type (uppercase): FEAT, BUG, REFAC, PERF, DOCS, TEST, CHORE, SEC, IDEA, ENH, PLAN
- `NNNN` — zero-padded monotonic number
- `HHHHHH` — 6-char hash from `active.jsonl`

Example: `FEAT-0042@abc123`

## Global Flags

Global flags go **before** the subcommand:

```bash
ao add "Title" --type feat              # ✅ no flags needed
ao --yes compact apply                  # ✅ --yes before subcommand
ao <subcommand> --yes                   # ❌ wrong
```

| Flag | Description |
|------|-------------|
| `--root PATH` | Override `.agent/ops/` auto-detection |
| `--format table\|json\|jsonl\|plain` | Output format (default: table) |
| `--yes` | Non-interactive mode, no prompts |
| `--quiet` | Minimal output |
| `--progress auto\|rich\|none` | Progress display |
| `--in TEXT` | Read JSON input from file or stdin (`-`) |
| `--out TEXT` | Write output to file or stdout (`-`) |
| `--sandbox` | Sandbox mode: no background processes, direct JSONL I/O |

## Sub-Documents

| Document | Contents |
|----------|----------|
| [issue-handling-lifecycle.md](issue-handling-lifecycle.md) | Create, update, close, complete workflow |
| [issue-handling-queries.md](issue-handling-queries.md) | ls, query, next, stale, kanban, filtering |
| [issue-handling-organization.md](issue-handling-organization.md) | Epics, labels, links, dependencies, acceptance criteria |
| [issue-handling-focus.md](issue-handling-focus.md) | Focus commands, iteration tracking, session state |
| [issue-handling-advanced.md](issue-handling-advanced.md) | Ref docs, event, export, import, merge, validate, gate, admin |
| [issue-handling-cli-reference.md](issue-handling-cli-reference.md) | Full command reference with all flags |

## Mandatory Rules

1. **Use `ao` directly** (not `uv run ao`): `ao <command>`
2. **Global flags before subcommand** (when needed): `ao --yes compact`
3. **Never edit JSONL directly**: Use `ao` CLI for all mutations
4. **Rebuild after manual event edits**: `ao rebuild` (should never be needed)
5. **Use `--yes` for non-interactive agent use**
