# Issue Queries — Listing, Filtering, Views

## Listing Issues

```bash
ao ls                                  # Active issues, table view
ao --format json ls                    # JSON output
ao ls --all                            # Include done/blocked issues
ao ls --status todo                    # Filter by status
ao ls --priority high --type bug       # Multiple filters
ao ls --epic "Issue Handling Audit"    # Filter by epic
ao ls --confidence low                 # Filter by confidence
ao ls --owner agent                    # Filter by owner
ao ls --label "security"              # Filter by label
ao ls --text "parser"                 # Text search in title/notes
ao ls --sort updated --limit 5        # Sort and limit
```

### Filter Flags

| Flag | Description |
|------|-------------|
| `--status` | Filter by status |
| `--priority` | Filter by priority |
| `--type` | Filter by issue type |
| `--epic` | Filter by epic name |
| `--owner` | Filter by owner |
| `--confidence` | Filter by confidence level |
| `--label` | Filter by label |
| `--text` | Full-text search |
| `--sort` | Sort: priority (default), updated, id, confidence |
| `--limit` | Max results |
| `--all` | Include done/blocked issues |

### View Modes

```bash
ao ls --view table     # Default table view
ao ls --view kanban    # Kanban board by status
ao ls --view summary   # Summary statistics
ao ls --view counts    # Count by category
ao ls --view ids       # IDs only (for scripting)
ao kanban              # Shortcut for ls --view kanban
```

### Query Tokens (Inline Filters)

```bash
ao ls status:todo priority:high       # Inline filter syntax
ao query status:todo type:bug         # query is an alias for filtered ls
```

## Finding Ready Issues

```bash
ao next                  # Top 10 ready-to-work issues (excludes done/blocked)
ao next --limit 5        # Top 5
ao next --owner agent    # Filter by owner
```

`ao next` ranks issues by priority, then confidence, excluding terminal and blocked statuses.

## Finding Stale Issues

```bash
ao stale                 # Issues not updated in 7+ days
ao stale --days 14       # Issues not updated in 14+ days
```

## Dependency Tree

```bash
ao dep-tree FEAT-0042@abc123    # Show dependency tree with cycle detection
```

## Rebuilding the Index

```bash
ao rebuild    # Rebuild active.jsonl from events.jsonl
```

Use after manual event edits (rare) or to verify index integrity. The rebuild is deterministic — same events always produce the same `active.jsonl`.

## Output Formats

All commands respect `--format`:

```bash
ao --format json ls       # Machine-readable JSON
ao --format jsonl ls      # One JSON object per line
ao --format table ls      # Human-readable table (default)
ao --format plain ls      # Plain text, minimal formatting
```

JSON output always wraps in `{"ok": true, "result": {...}}`.
