feat(meta): migrate decisions + ticketing to pql #154
Assignees
jpmschweitzer (Jeroen Schweitzer)
Clear assignees
jpmschweitzer (Jeroen Schweitzer)
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: jpmschweitzer/settled-reach#154
Reference in New Issue
Block a user
Summary
Migrates the project's decisions + ticketing system off the bespoke SQLite tooling
(
tooling/db/*,settledreach.db) onto pql — the markdown-vault + planning toolthat was itself productized from this repo's planning structures. Phases 0-5 of
pql-migration.md. Big-bang cutover behind a verification gate; legacy tooling staysintact as the rollback path until a separate Phase-6 follow-up.
What changed
governance/{decisions,questions,rejected}/<domain>.md(pql DQR tree).357 records (237 D / 108 Q / 12 R), sync
broken: 0. Fixed two real id collisions(D-035 dup -> shadowcasting renumbered D-238; R-011 triple -> deduped).
.pql/changelog/(1013 tickets, 481 deps, 16 history, 90labels incl. milestone->
phase:4).T-N == legacy #Nbijection; fullpql plan rebuildparity verified. Replaces the binary-DB-plus-backup ritual.#N -> T-N(283 guarded rewrites; PR refs / hex / non-tickets skipped)..config/hooks/*(pre-commit export+validate;post-merge/checkout/rewrite replay), Makefile +
ticket-cli.md+ CLAUDE.md + skills(
whats-next/ticket/pr-process/bug-report) + settings all onpql.decision_refsfrontmatter on workshop outcomes.tooling/pql-migrate/;pql-requirements.mdis feedback tothe pql team (the "Critical" seeded-id blocker dissolved — pql kept our max-id counter).
Verification
pql decisions validateok; count parity 357; legacy check-dupes 0.Deferred to Phase 6 (post-merge, separate PR)
Delete
tooling/db/*, dropSR_DB_PATH, removedb-backup+ the committedsettledreach.db.backup. Kept now so rollback survives the first live days.🤖 Generated with Claude Code
Phase 1 of the pql migration. Moves the flat decisions/*.md layout into governance/{decisions,questions,rejected}/<domain>.md — the tree pql's `decisions sync` parses natively (record type from subdir, domain from filename stem). Proven against pql 1.6.2: sync reports 357 records (237 D / 108 Q / 12 R), 1057 refs, broken: 0; validate ok. - 6 D-domain files -> governance/decisions/ (git renames) - 5 questions-<domain>.md -> governance/questions/<domain>.md (prefix dropped) - rejected.md split by domain -> governance/rejected/{architecture(R-001..010), economics(R-011),perception(R-012)}.md - decisions/README.md + questions.md index folded into governance/README.md; pql's `decisions sync` now auto-maintains the record index appended below the hand-written domain guidance (no more manual ID-list table upkeep). - .pql/config.yaml: canonical vault config (tracked, not ignored). Link rewrites are token-preserving: only the relative `foo.md` path portion changes (e.g. `rejected.md#r-011` -> `../rejected/economics.md#r-011`); every `[D-NNN]` bracket text and `#anchor` stays byte-identical, so pql's reference extraction is unaffected. The one-shot transform is committed at tooling/pql-migrate/restructure_decisions.py for provenance. Codebase path references to decisions/ (CLAUDE.md, rules, skills, docs) are updated in a follow-up commit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>Phase 1 follow-up: update the active instruction layer (CLAUDE.md, project structure rule, DECISIONS.md redirect, agent personalities, skill docs) to reference governance/{decisions,questions,rejected}/<domain>.md instead of the retired flat decisions/*.md layout. Path references only — command-surface references (tooling/db/decision*, decisions-sync, Makefile targets, clerk) are repointed to the pql CLI in the Phase 4 consumer cutover. Historical archives (docs/sprints, docs/discussions, docs/workshops) keep their point-in-time decisions/ paths; the separate whatsinagame/ template distribution is untouched. Agent-memory is gitignored and out of scope. The agent/skill repath was applied by tooling/pql-migrate/repath_references.py (ordered, meaning-preserving replacements; bare-dir rule uses a negative lookbehind so it can't corrupt a freshly-created governance/decisions/ path), committed for provenance. CLAUDE.md, project-structure.md, and DECISIONS.md were hand-edited (structural tree/table changes). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>Adopts the T-NNN convention (T-N == old #N == pql ticket id) across the active operational layer: governance/ decision records, .claude/{rules,agents,skills}, CLAUDE.md, DECISIONS.md. 283 references rewritten. Guarded against false positives (17 correctly skipped, each logged): - PR references kept (PR #136/#138/... — PRs are a separate #-namespace) - non-ticket numbers kept (#4122; the "#1 process failure" idiom; "task #3") - only #N where N is an actual ticket id is rewritten; the 1-4 digit word-bounded match also excludes 6-digit hex colours in the visual decision records Git history is NOT rewritten (a commit's #N already equals T-N numerically), and historical archives (docs/sprints, docs/discussions, docs/workshops) keep their point-in-time #N. The /pr-process ticket-ID extraction logic moves to T-NNN in the Phase 4 consumer cutover. Verified: pql decisions validate ok; sync 357 records / 1057 refs / broken 0 (the prose edits don't affect decision parsing or the tickets.decision_ref linkage). Transform committed at tooling/pql-migrate/retag_ticket_refs.py. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>Folds pql's planning logic into the version-controlled .config/hooks/* (pql's own .pql/hooks installer is dead under core.hooksPath=.config/hooks): - pre-commit: + `pql decisions validate` (decision-ID/format gate, supersedes the never-built check-decision-ids TODO) and `pql plan export --stage` (flush ticket mutations to the git-tracked changelog and stage them into the commit). Both guarded by `command -v pql`; export is a clean no-op when nothing changed. - post-merge: `pql plan import` + `pql decisions sync` (replay incoming changelog, re-sync markdown decisions). - post-checkout (branch only): `pql plan rebuild` + `decisions sync`. - post-rewrite (rebase/amend): `pql plan rebuild`. - install-hooks chmods the three new hooks. Makefile decision targets repointed to pql: decisions-sync -> `pql decisions sync`, decisions-active -> `pql decisions list --type confirmed`, new decisions-validate -> `pql decisions validate`. Dropped the SQLite-query conveniences (coverage/orphan/ orphan-tickets); per-decision coverage is `pql decisions show <id> --with-tickets`. db-backup/db-install and SR_DB_PATH are intentionally kept until Phase 6 so the legacy SQLite store stays intact as the migration rollback path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>Review: pql-migration → main (type: code)
Multi-agent review — Tyre (architecture) + Hoshe (QA).
Tyre (Architecture): REQUEST_CHANGES
Cutover is architecturally correct — big-bang with preserved rollback, the text
changelog kills the binary-DB conflict class, governance cross-references are sound,
and the hooks are guarded and idempotent. One real bug + one low-severity note:
.gitattributes:1.pql/changelog/*.sqlmatches nothing — changelog files live at.pql/changelog/<table>/<YYYY-MM>.sql, one level deeper.git check-attr merge→unspecified. This defeats the union-merge guarantee that is the core value of the text changelog. Fix:.pql/changelog/**/*.sql merge=union.tooling/pql-migrate/*.pyREPO=.../main— re-runningseed_tickets.pyfrom a worktree writespql.dbto the wrong place (low severity:pql.dbis gitignored, the committed changelog is correct). Derive the root fromgit rev-parse --show-toplevel.Hoshe (QA): APPROVE
All seven QA checks pass: decision parity exact (357 records / 237 confirmed / 108
question / 12 rejected;
validateok; no duplicate IDs), ticket parity exact (1013tickets / 481 deps / 16 history / 90 labels after
plan rebuild; T-N bijectionconfirmed), link integrity clean (correct
../decisions/prefixes; nogovernance/governance/corruption; PR refs + hex colours intact), command cutovercomplete (no residual
tooling/db/*invocations outside labelled rollback prose),all four hooks guarded with
command -v pql, migration scripts ruff-clean +read-only on the source DB + idempotent.
Verdict: CHANGES REQUESTED
Both Tyre comments accepted (no pushback). Fixes incoming on the branch.
Re-review after fixes — APPROVED ✅
Both Tyre comments resolved (commit
f8d9b777b); Hoshe approved on the first pass..gitattributes*.sql→**/*.sql—git check-attr mergenow reportsmerge: unionontickets,ticket_deps, andticket_historychangelog files.The conflict-elimination guarantee that justifies the text changelog is wired up.
seed_tickets.py+add_workshop_provenance.pyderiveREPOfromgit rev-parse --show-toplevel(worktree/clone-safe); the threeone-shot transforms carry an "already-applied, re-running unsupported" provenance note.
Verdict: APPROVED by both reviewers. Rollback path preserved (legacy
tooling/db/*,SR_DB_PATH,settledreach.dbintact until the Phase-6 follow-up); hooks guarded andidempotent; governance cross-references resolve. Ready to merge.
Pull request closed