# Ticket & Decision CLI (pql)

**Use `pql`** for all ticket and decision operations. Tickets live in `.pql/pql.db`
(rebuildable from the git-tracked `.pql/changelog/`); decisions are markdown-sourced
under `governance/{decisions,questions,rejected}/` and synced into the same DB.

Ticket ids are **`T-NNN`** (`T-440 == legacy #440`). The legacy `tooling/db/ticket`
+ `sqlite-query`/`sqlite-exec` path is retired — do not use it, and never invoke the
`sqlite3` CLI (it crashes in Claude Code).

## Positional arguments — not flags

`pql ticket new` uses **positional** arguments for `type` and `title`. There is no
`--title` flag.

```bash
# CORRECT — type and title are positional
pql ticket new story "My ticket title" --description "Details here" --team server --priority low

# WRONG — --title is absorbed into the title string
pql ticket new story --title "My ticket title"
```

## Tickets

```bash
# Create  (type: initiative|epic|story|task|bug ; priority: critical|high|medium|low)
pql ticket new <type> <title> [--parent T-N] [--priority P] [--decision D-NNN] [--team T] [--description TEXT] [--assign agent] [--id-only]

# Read
pql ticket show T-440 [--with-context] [--with-children] [--with-blockers] [--tree] [--depth N]
pql ticket list [--status S] [--team T] [--label L] [--assigned A] [--decision D-NNN] \
                [--unblocked] [--leaf] [--under T-N]
pql ticket board [--team T]                 # kanban view

# Update
pql ticket status T-440 in_progress         # backlog|ready|in_progress|review|done|cancelled
pql ticket assign T-440 dudley
pql ticket team   T-440 server
pql ticket setparent T-9 T-2                 # (clear with no parent arg)
pql ticket append T-440 "extra context"      # also --file PATH / --stdin

# Dependencies
pql ticket show T-440 --with-blockers         # what blocks this
pql ticket block   T-7 --by T-440             # T-440 blocks T-7
pql ticket unblock T-7 --from T-440           # remove that edge

# Labels  (action is add | rm)
pql ticket label T-440 add needs-refinement
pql ticket label T-440 rm  needs-refinement

# Refinement (tickets with no description are "unrefined")
pql ticket refine list
pql ticket refine next [--skip N]
pql ticket refine write T-5 '{"description":"..."}'
```

Most subcommands batch with comma-separated ids: `pql ticket status T-1,T-2,T-3 done`.

## Planning dashboard

```bash
pql plan status        # decision counts, open questions, ticket summary
pql plan whatsnext     # next ticket to work on
pql plan review        # next ticket awaiting review
pql plan export        # flush ticket mutations to .pql/changelog/ (--stage to git-add)
pql plan import        # replay changelog into pql.db (post-merge)
pql plan rebuild       # drop + replay changelog from scratch (post-checkout/rewrite)
```

## Decisions

```bash
pql decisions claim D <domain> "title"   # next free id, no side effects (D | Q | R)
pql decisions list [--type confirmed|question|rejected] [--domain X]
pql decisions show D-010 [--with-tickets]
pql decisions read D-238                   # full markdown body
pql decisions refs D-010                    # cross-references
pql decisions sync                          # parse governance/*.md -> pql.db
pql decisions validate                      # malformed-record gate (pre-commit)
```

## Phases → the cascade hierarchy (no milestone entity)

pql has **no milestone entity** (the legacy one was vestigial). Phase gating is the
**ticket hierarchy**: the initiative `T-745` (Development Cascade) holds the six phases
as epics; a ticket is in a phase by being parented under that phase epic — self-maintaining,
no label to apply or forget. The active phase is the phase epic with status `in_progress`
(sequential per D-166 → the lowest-numbered non-`done` phase epic; currently `T-750`, Phase 4).

```bash
pql ticket list --under T-750 --unblocked        # the kanban "what's ready in this phase"
pql ticket setparent T-990 T-750                  # put a ticket in the phase (re-parent)
pql ticket show T-745 --tree                      # the whole cascade
```

## Key rules

- **Type and title are positional** on `pql ticket new` — everything else is a flag.
- **Quote the title** — wrap in double quotes to handle spaces.
- **Ids are `T-NNN`** — `T-N == legacy #N`. PR numbers (`PR #138`) are a separate namespace.
- **Don't hand-edit `.pql/pql.db`** — it's rebuildable. Mutations go through `pql ticket …`;
  the pre-commit hook exports + stages `.pql/changelog/` automatically.
- **Verify after create** — `pql ticket show <id>` to confirm the title is clean.
- The legacy `tooling/db/{ticket,decision,sqlite-*}` CLI, `SR_DB_PATH`, and the committed
  `settledreach.db` backup were removed in Phase 6 of the migration. The live
  `settledreach.db` file (gitignored, repo-parent) is left on disk as a cold rollback only.