From a46946e2acabfe2226aba854068e71c4986882a7 Mon Sep 17 00:00:00 2001
From: Jeroen Schweitzer <jpmschweitzer@gmail.com>
Date: Sun, 28 Jun 2026 08:15:23 +0200
Subject: [PATCH] docs(meta): read the pql skill before non-trivial
 planning-store ops
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

settled-reach is always a pql repo, so make the rule repo-canonical (CLAUDE.md +
ticket-cli.md): routine ticket/decision CLI is covered by the rules, but the
load-bearing model lives only in the pql skill — changelog is write-through (never
git-restore it), `export` doesn't replicate ticket_idmap, post-checkout rebuilds
pql.db from the changelog, so cross-branch planning moves must re-create via
`pql ticket`, not changelog surgery. Back up pql.db before risky ops.

The clide-side equivalent (read the clide skill when running inside clide) is an
editor choice, not a repo property — it belongs in a clide-owned SessionStart hook,
not here.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .claude/rules/ticket-cli.md | 22 ++++++++++++++++++++++
 CLAUDE.md                   | 10 ++++++++++
 2 files changed, 32 insertions(+)

diff --git a/.claude/rules/ticket-cli.md b/.claude/rules/ticket-cli.md
index cc70a20f4..a54b7f856 100644
--- a/.claude/rules/ticket-cli.md
+++ b/.claude/rules/ticket-cli.md
@@ -105,3 +105,25 @@ pql ticket show T-745 --tree                      # the whole cascade
 - The legacy `tooling/db/{ticket,decision,sqlite-*}` CLI, `SR_DB_PATH`, and the committed
   `settledreach.db` backup were removed in Phase 6 of the migration. The live
   `settledreach.db` file (gitignored, repo-parent) is left on disk as a cold rollback only.
+
+## Changelog & planning-store safety (read the `pql` skill first)
+
+Routine ticket/decision CLI is covered above. For anything **non-routine** —
+hand-touching `.pql/changelog/`, moving planning across branches, or recovering a
+broken store — **load the `pql` skill (`Skill(pql)`) before acting.** The load-bearing
+model is not obvious and is easy to corrupt:
+
+- **The changelog is write-through, not a cache.** `pql ticket`/`pql decisions` mutations
+  write `.pql/changelog/` synchronously. **Never `git restore`, `git checkout --`, or
+  hand-edit the changelog to "reset" it** — you are deleting real data, and it is the
+  git-tracked source of truth (`pql.db` is gitignored and rebuilt from it).
+- **`pql plan export` does NOT replicate `ticket_idmap`** (only tickets/deps/labels/history).
+  So once you discard write-through rows, `export` cannot regenerate the human `T-NNN` ⇄
+  `record_id` mapping — a rebuild then loses or reassigns ids.
+- **`post-checkout`/`post-rewrite` rebuild `pql.db` from the *target branch's* changelog**
+  (`pql plan rebuild`). So a branch switch is governed by the changelog, not the live DB —
+  uncommitted DB-only mutations are dropped on switch.
+- **Therefore: move planning across branches by *re-creating* via `pql ticket`** (write-through
+  repopulates everything, idmap included), not by copying/restoring changelog files.
+- **Back up `.pql/pql.db` before any risky planning-store operation** (`cp .pql/pql.db
+  /tmp/pql_backup.db`) and verify with a `pql plan rebuild` + `pql ticket show <id>` after.
diff --git a/CLAUDE.md b/CLAUDE.md
index 7387b1b0c..61f38aa3a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -102,6 +102,16 @@ binary-DB backup ritual). Decisions are markdown-sourced under
 `governance/{decisions,questions,rejected}/` and synced into the same DB. Ticket ids are
 `T-NNN` (`T-440 == legacy #440`). The pre-commit hook auto-exports + stages the changelog.
 
+**This is a pql repo — read the `pql` skill (`Skill(pql)`) before any *non-trivial*
+planning-store operation**, not just routine ticket/decision CLI. The rules here cover
+day-to-day `pql ticket`/`pql decisions`; the load-bearing model that bites in edge cases
+lives only in the skill: mutations **write through** to `.pql/changelog/` synchronously
+(so **never `git restore`/hand-edit the changelog** — it is data, not a cache), `pql plan
+export` does **not** replicate `ticket_idmap` (so it can't regenerate ids you discarded),
+and **post-checkout/post-rewrite rebuild `pql.db` from the changelog**. Therefore moving
+planning across branches means **re-creating via `pql ticket`**, not changelog surgery;
+back up `.pql/pql.db` before any risky planning-store op.
+
 ### Before starting work
 1. Check active work: `pql ticket list --status in_progress`
 2. Check your ticket: `pql ticket show T-<id> --with-context`