jpmschweitzerandClaude Opus 4.8
8f4194982e
Rewrites the canonical command reference (.claude/rules/ticket-cli.md) and CLAUDE.md to the pql CLI: `pql ticket`/`pql plan`/`pql decisions` replace `tooling/db/ticket`, `sqlite-query`/`sqlite-exec`, and `tooling/db/decision`. Documents T-NNN ids, the markdown-sourced governance decision tree, the rebuildable changelog-backed pql.db, and labels-as-milestones (phase:4) in place of the removed milestone entity. Maps the old surface accurately: ticket new (positional type+title), show --with-context/--with-blockers, block --by / unblock --from, label add/remove, decisions claim/list/show/validate/sync, plan whatsnext/review/status. Behavioral/command cutover only — the legacy tooling/db/* and SR_DB_PATH stay as the rollback path until Phase 6. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
103 lines
4.2 KiB
Markdown
103 lines
4.2 KiB
Markdown
# 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 (also used as milestones — see below)
|
|
pql ticket label T-440 add phase:4
|
|
pql ticket label T-440 remove phase:4
|
|
|
|
# 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)
|
|
```
|
|
|
|
## Milestones → labels
|
|
|
|
pql has **no milestone entity** (the legacy milestone subsystem was vestigial). Phase
|
|
gating is expressed with **labels**: the active phase is `phase:4`.
|
|
|
|
```bash
|
|
pql ticket list --label phase:4 --unblocked # the kanban "what's ready in this phase"
|
|
pql ticket label T-950 add phase:4 # put a ticket in the phase
|
|
```
|
|
|
|
## 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/*` CLI and `SR_DB_PATH` remain only as a migration rollback path
|
|
and are removed once the cutover is stable.
|