jpmschweitzerandClaude Opus 4.8
5a399c7924
The pql cutover is stable, so remove the superseded SQLite planning tooling. Surgical
— only the ticket/decision/raw-SQL scripts (all settledreach.db-bound and replaced by
pql) are deleted; the asset/audio/wiki connectors and shared common.py stay.
Removed:
- tooling/db/{ticket,decision,decisions-sync,decisions_sync.py,sqlite-query,sqlite-exec,
sqlite-init,sqlite-seed,sqlite_connector.py}
- tooling/{db-backup,db-install} + docs/backups/settledreach.db.backup (the binary-DB
backup ritual; tickets now live in the git-tracked .pql/changelog/)
- tooling/check-decision-ids (dead stub, superseded by `pql decisions validate`)
- Makefile db-backup/db-install targets; SR_DB_PATH + tooling/db/{ticket,sqlite-*,
decision*} entries from .claude/settings.json (audio entries kept)
Updated docs to pql: DEVOPS.md (SQLite Access + Decisions System → pql), project
structure, ticket-cli closing note, asset-pipeline raw-SQL warning.
Kept (verified still imported by the asset connectors via common.ensure_venv): common.py,
config.json, audio/image/trellis/wiki connectors. The live settledreach.db file
(gitignored, repo-parent) is left on disk as a cold rollback only.
ruff clean; pql decisions validate ok (357 decisions / 1013 tickets).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
108 lines
4.7 KiB
Markdown
108 lines
4.7 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 (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.
|