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:
+29
-17
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user