docs(meta): reframe pql-requirements as feedback to a descendant tool

pql was developed off the lessons of this repo's own planning structures, so the
"requirements" are feedback to a descendant, not gaps in a foreign tool — and some
items are deliberate simplifications to adopt rather than ask pql to re-add.

- Item #1 (seeded ids) downgraded Critical -> Resolved: Phase 2 proved direct-INSERT
  seeding + pql's max-id counter (inherited from our own CLI) mints T-1022 after
  T-1021, so there is no recycling/collision. The --id flag is a low-priority nicety.
- Item #9 (milestones): pql's omission of the milestone entity validates our
  vestigial finding; labels-as-milestones is the right call and we adopt it.
- Intro reframed around the lineage.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-06 12:35:00 +02:00
co-authored by Claude Opus 4.8
parent 88d9be070e
commit 83bb18b385
+29 -17
View File
@@ -15,28 +15,34 @@ SQLite-backed ticket CLI + markdown-decisions-sync onto pql. Scale: **1013 ticke
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. The items below are the gaps we hit.
Each lists **why we need it**, a **suggested shape**, and a **priority**. Where we have a viable
workaround, it's noted — but the workaround is friction we'd rather not ship.
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 — **CRITICAL**
## 1. Seeded / explicit ticket IDs + id-counter advance — **RESOLVED (non-issue)**
**Why.** Our 1013 tickets have integer ids referenced as `#440` in thousands of immutable git
commits, in decision "Ticket: #N" lines, and by our PR automation. We need the pql id to preserve
the number — `T-440 ≡ old #440` — so the mapping stays a trivial bijection. pql's `id` is a TEXT
column, so we can seed `'T-440'` directly into the changelog. **But `pql ticket new` auto-assigns
`T-N` sequentially starting at `T-1`** — after seeding `T-1…T-1013`, the next native create would
mint `T-1` and collide.
**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.
**Suggested shape.**
- `pql ticket new --id T-1014` (accept an explicit id), AND/OR
- on `pql plan rebuild`/import, **advance the internal id counter past the max existing id** so
native creates never recycle a seeded id.
**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.
**Workaround.** None safe — we'd have to hold all native ticket creation until this lands, or
hand-manage a sentinel. This is the one true blocker for a clean 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.
---
@@ -154,13 +160,19 @@ queries / rollups), or offer an optional lightweight milestone entity (M:N ticke
ordering, done/total rollups) for projects that actually use phase gating. We'd only need the latter
if we later adopt real cross-phase dependency gating.
**Lineage note.** pql dropping the milestone entity that this very repo carried is almost certainly
*deliberate* — it productized the lesson that our milestone subsystem was vestigial. So this is less
a gap than a confirmation: labels-as-milestones is the right call, and our migration adopts it
(active milestone → `phase:4`, the completed one → `milestone:process-rewire`). Documenting the
pattern (point 1 above) is the only ask.
---
## Summary
| # | Requirement | Priority | Have workaround? |
|---|-------------|----------|------------------|
| 1 | Seeded/explicit ticket id + counter-advance | **Critical** | No (real blocker) |
| 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 |