settled-reach/.claude/rules/ticket-cli.md

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.

# 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

# 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

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

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).

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.