settled-reach/pql-requirements.md

---
title: "pql Requirements — gaps surfaced by the Settled Reach migration"
description: "Feature gaps and friction points found while migrating a 1013-ticket + 358-decision project onto pql, for the pql team"
type: requirements
status: draft
created: 2026-06-06
updated: 2026-06-06
tags: [pql, requirements, feedback]
---

# pql Requirements — gaps for the pql team

Compiled while planning a migration of **The Settled Reach** (a Godot+Rust game) off a
SQLite-backed ticket CLI + markdown-decisions-sync onto pql. Scale: **1013 tickets**, 481
dependency edges, 48 labels, 16 history rows; **358 decision records** (237 D / 109 Q / 12 R)
with 1040 cross-refs; a ~4385-file markdown vault (decisions, docs, 22 workshops, ~3500 wiki pages).

pql is a strong fit and most of our system maps cleanly — unsurprisingly, since **pql was
developed off the lessons of this repo's planning structures** (the SQLite ticket+decision
schema, the `decisions/` domain split, the kanban/`whats-next` flow). The enums, the DQR tree,
and the kanban model match almost exactly; pql's deliberate departures (TEXT ids over our
integer ids, a git-tracked text changelog over our binary-DB-plus-backup ritual, and *no*
milestone entity) are the productized lessons. So the items below are best read as **feedback to
a descendant**, not gaps in a foreign tool — and a few are deliberate simplifications we should
adopt rather than ask pql to re-add. Each lists **why**, a **suggested shape**, and a
**priority**; viable workarounds are noted.

---

## 1. Seeded / explicit ticket IDs + id-counter advance — **RESOLVED (non-issue)**

**Why it looked critical.** Our 1013 tickets have integer ids referenced as `#440` in thousands of
immutable git commits, in decision "Ticket: #N" lines, and by PR automation. We need the pql id to
preserve the number — `T-440 ≡ old #440`. The fear was that, since `pql ticket new` has no `--id`
flag and auto-assigns `T-N` sequentially, a post-seed native create would mint `T-1` and collide.

**Why it's actually fine** (verified against pql 1.6.2). Bulk seeding goes through **direct-INSERT
into `pql.db` + `pql plan export`**, not `ticket new`. And pql's id counter is derived from
`max(id)` — exactly the behaviour our own integer-id CLI had. After seeding `T-1…T-1021`, the next
`pql ticket new` minted **T-1022**, not T-1. No collision, no recycling, no held creation. The
`--id` gap only bites the (rare) case of hand-creating a *specific* id via the CLI — irrelevant to
a bulk numbered migration.

**Optional nicety (low priority).** A `pql ticket new --id T-1022` flag would still be convenient
for the occasional manual back-fill, but it is **not** required for a clean migration.

---

## 2. Duplicate-ID detection in `pql decisions sync` / `validate` — **HIGH**

**Why.** Our markdown had a genuine integrity bug: `D-035` defined in two domain files, `R-011`
defined three times. **`pql decisions sync` silently last-writer-wins-collapsed them** (reported
`broken: 0`), so the duplication was invisible. Our legacy Python `check-dupes` errors on it. A
duplicate canonical-ID is almost always a data bug, not an intended merge.

**Suggested shape.** `pql decisions validate` (and `sync --strict`) should **warn or error on
duplicate D/Q/R ids across the vault**, reporting `file:line` for each occurrence.

**Workaround.** Keep our Python `check-dupes` wired into pre-commit alongside pql — extra tooling
we'd like to retire.

---

## 3. `core.hooksPath` awareness in `pql init` — **HIGH**

**Why.** Our repo sets `core.hooksPath = .config/hooks` (so hooks are version-controlled). `pql init`
installs its pre-commit/post-merge/post-checkout hooks into `.git/hooks/`, which git **ignores** when
`core.hooksPath` is set. pql's changelog-staging + replay hooks would be **silently dead** — the whole
durable-versioning model depends on them. This is a quiet, dangerous failure (data appears to work, but
`.pql/changelog/` is never staged).

**Suggested shape.** `pql init`/`pql doctor` should detect `core.hooksPath` and either install into the
configured dir or emit a loud warning with the manual fold-in snippet.

**Workaround.** Manually fold pql's hook logic into `.config/hooks/*` (we will), but `pql doctor`
should flag the mismatch so others don't get bitten.

---

## 4. Document the changelog seed format + `hash`/`canonical_version` algorithm — **HIGH**

**Why.** `pql plan import --legacy` is documented as retired; the real durable artifact is
`.pql/changelog/<table>/<YYYY-MM>.sql`. To migrate 1013 tickets we must emit those SQL rows directly.
We reverse-engineered the UPSERT shape, but the per-row `hash` and `canonical_version` columns +
the LWW guard (`WHERE excluded.updated_at > … OR (… AND excluded.hash > …)`) are opaque. If our seed
hashes don't match pql's scheme, later native edits still win by `updated_at` (so correctness holds),
but the LWW tie-break becomes unpredictable.

**Suggested shape.** Document (a) the canonical changelog row format per table, (b) the `hash`
input + algorithm, (c) how `canonical_version` increments — OR provide a supported one-shot
`pql plan seed <json|csv>` import that computes them.

**Workaround.** Emit our own stable per-row hash; rely on `updated_at` for correctness. Works, but
under-specified.

---

## 5. Bare-text reference detection / auto-link for `D-NNN` / `T-NNN` — **MEDIUM**

**Why.** Across ~4385 vault files (esp. ~3500 *generated* wiki pages), decision/ticket references are
mostly **bare text** (`D-117`, `#440`) rather than markdown/wikilinks. `pql search` finds them, but
`pql backlinks`/`related` only follow real links — so "what references D-117?" is incomplete. Rewriting
3500+ generated files to add links is impractical (they're regenerated from a pipeline).

**Suggested shape.** Optional **reference recognizers** (configurable regex → entity, e.g.
`D-\d+`→decision, `T-\d+`→ticket) so `backlinks`/`related` treat bare-text mentions as edges without
requiring link syntax in source.

**Workaround.** Adopt a link convention in *authored* files only; accept that generated files are
search-only.

**Related gap — frontmatter list-membership in the DSL.** Our Phase-5 provenance puts the decisions
each workshop touches in a `decision_refs: [D-010, …]` frontmatter list. pql indexes the list and
`SELECT fm.decision_refs` round-trips it, but we found no DSL operator that filters by membership:
`fm.decision_refs ~ 'D-010'` and `… contains …` are lex/parse errors, and `'D-010' in fm.decision_refs`
parses but matches nothing. So "which workshops touch D-010?" needs a `SELECT` + client-side filter or
a `pql search`. A documented list-membership operator (or making `in` work against frontmatter arrays)
would close this.

---

## 6. WIP-limit enforcement (advisory) on `ticket status … in_progress` — **MEDIUM**

**Why.** Our kanban flow enforces a WIP limit (max 5 in_progress); our activation step relied on the
CLI warning when exceeded. pql has no forced state machine / WIP concept.

**Suggested shape.** An optional config (`wip_limit: 5`) that makes `pql ticket status <id> in_progress`
emit an advisory warning (not a hard block) when the in_progress count would exceed it.

**Workaround.** Compute `pql ticket list --status in_progress | count` in our skill and warn there.

---

## 7. Fan-out / downstream-unblock count on `ticket show` — **MEDIUM**

**Why.** Our batch-selection ranks ready tickets partly by **fan-out** — how many downstream tickets a
ticket unblocks. We currently compute it from the dependency graph. pql has `--unblocked` (great — it
replaced our manual blocker walk) but no "how many does this unblock" signal.

**Suggested shape.** A `blocks_count` / `unblocks_count` field on `pql ticket show`/`list`, or a
`pql ticket list --orders-by fanout`.

**Workaround.** Compute client-side from `ticket show --with-context` dep data.

---

## 8. Multi-team / array team field — **LOW**

**Why.** One ticket carries a comma-separated `team` (`client,server`). pql treats `team` as a single
string. (1 of 1013 — genuinely low.)

**Suggested shape.** Accept an array/comma team, or document the single-team constraint.

**Workaround.** Pick the primary team for the one affected ticket.

---

## 9. No milestone entity needed — the ticket hierarchy IS the milestone — **RESOLVED (no ask)**

**Why it looked like a gap.** Our old schema had a milestones subsystem (milestones,
ticket_milestones, milestone_deps, cascade_phase) — but it was **vestigial** (2 milestones,
`milestone_deps` empty, 42/1013 linked, cascade ordering never exercised). The migration first
mapped the active milestone to a **label** (`phase:4`).

**What we landed on — and it's better.** The labels-as-milestones pattern immediately drifted
(66 tickets lived under the Phase-4 epic but only 42 carried the label). The fix wasn't a milestone
entity *or* a label convention: it was to use pql's **native initiative/epic hierarchy**, which
already modelled this. The repo has an initiative `T-745` (Development Cascade) with the six phases
as epics under it; a ticket belongs to a phase by being **parented under that phase epic**
(`pql ticket list --under <phase-epic>`), and the active phase is the `in_progress` phase epic. This
is self-maintaining — parent a ticket and it's in the phase; no label to apply, forget, or let rot.

**Net for the pql team:** dropping the milestone entity was the *right* call — don't add one back, and
don't bless labels-as-milestones either. The initiative→epic→story→task tree already expresses phase
gating cleanly. The only nice-to-have is a documented "active node" convention (status `in_progress`
on a grouping ticket) and maybe a `--under` done/total rollup. **Not blocking; no entity needed.**

---

## Summary

| # | Requirement | Priority | Have workaround? |
|---|-------------|----------|------------------|
| 1 | Seeded/explicit ticket id (`--id` flag) | ~~Critical~~ **Resolved** | N/A — direct-INSERT + max-id counter already works |
| 2 | Duplicate-ID detection in sync/validate | High | Yes (keep our checker) |
| 3 | `core.hooksPath` awareness | High | Yes (manual fold-in) |
| 4 | Documented changelog seed format + hash algo | High | Partial |
| 5 | Bare-text ref detection for backlinks | Medium | Partial (authored files only) |
| 6 | WIP-limit advisory | Medium | Yes (skill-side) |
| 7 | Fan-out / unblocks count | Medium | Yes (client-side) |
| 8 | Multi-team field | Low | Yes |
| 9 | Milestone entity / labels-as-milestones | ~~Low~~ **Resolved** | N/A — use the initiative/epic hierarchy |