jpmschweitzerandClaude Opus 5.5
c597ec9131
A script scanned every tracked doc, rule, skill, agent, hook and source file for tooling/ paths that no longer exist, skipping historical records (sprints, discussions, workshops, governance, generated wiki pages). It found 62. The ones that tell a reader what to RUN now name the reach verb: - The atlas skill still sent agents to tooling/atlas, atlas-verify, atlas-update-field and atlas-commit-and-sync — about forty lines, all retired in T-1285. They now name the `reach atlas` verbs, and the skill records that commit-and-sync STAGES by default (--commit to commit) and takes --corridor as an option. - The clerk agent named tooling/clerk-review (now `reach dev clerk`). The Si and clerk briefings sent those agents to the retired tooling/db/decision and sqlite-query CLIs and to decisions/*.md paths that moved to governance/ in the pql migration. They now name pql. - The ticket-cli rule documented `pql decisions read`, which does not exist; `show` already includes the body. - The culture authoring guide and the RON sources name `reach validate ron`, with the same arguments as before. - The 41 Blender payloads' usage lines ran the retired tooling/blender wrapper, and the docstrings still cited pre-carve-out paths. They now read `reach blender run <payload>`. - Doc comments in server/, client/, wiki TOMLs and the domain modules. What is left is deliberate: "Formerly …" provenance, dated plans and findings docs, the retired-pipeline doc, and a build-artefact path. project.yaml 0.4.14 (mirrored to the client). Comment-only, but four touched files are in the canvas-version registry (trait_catalog_reader.rs, since T-1289, canvas_sources.py itself, and two client files). The gate is path-based and has no override. The previous push was rejected on exactly this. Three of the edits are stamped ledger sources, so systems.db is regenerated and the stamp is fresh. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
130 lines
6.3 KiB
Markdown
130 lines
6.3 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: setparent T-9 none)
|
|
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 show D-238 # includes the full markdown body (there is no `read` verb)
|
|
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.
|
|
|
|
## Changelog & planning-store safety (read the `pql` skill first)
|
|
|
|
Routine ticket/decision CLI is covered above. For anything **non-routine** —
|
|
hand-touching `.pql/changelog/`, moving planning across branches, or recovering a
|
|
broken store — **load the `pql` skill (`Skill(pql)`) before acting.** The load-bearing
|
|
model is not obvious and is easy to corrupt:
|
|
|
|
- **The changelog is write-through, not a cache.** `pql ticket`/`pql decisions` mutations
|
|
write `.pql/changelog/` synchronously. **Never `git restore`, `git checkout --`, or
|
|
hand-edit the changelog to "reset" it** — you are deleting real data, and it is the
|
|
git-tracked source of truth (`pql.db` is gitignored and rebuilt from it).
|
|
- **`pql plan export` does NOT replicate `ticket_idmap`** (only tickets/deps/labels/history).
|
|
So once you discard write-through rows, `export` cannot regenerate the human `T-NNN` ⇄
|
|
`record_id` mapping — a rebuild then loses or reassigns ids.
|
|
- **`post-checkout`/`post-rewrite` rebuild `pql.db` from the *target branch's* changelog**
|
|
(`pql plan rebuild`). So a branch switch is governed by the changelog, not the live DB —
|
|
uncommitted DB-only mutations are dropped on switch.
|
|
- **Therefore: move planning across branches by *re-creating* via `pql ticket`** (write-through
|
|
repopulates everything, idmap included), not by copying/restoring changelog files.
|
|
- **Back up `.pql/pql.db` before any risky planning-store operation** (`cp .pql/pql.db
|
|
/tmp/pql_backup.db`) and verify with a `pql plan rebuild` + `pql ticket show <id>` after.
|