diff --git a/pql-requirements.md b/pql-requirements.md index e24d7823f..ec77ffe29 100644 --- a/pql-requirements.md +++ b/pql-requirements.md @@ -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 |