From 02bc4803fca8f8e13a4b7120ce580b050d905952 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Wed, 3 Jun 2026 10:08:42 +0200 Subject: [PATCH] docs: note the pql README-sync bug in pql-improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds issue #7 — pql decisions sync regenerates governance/README.md and relists resolved questions as open (dropping the Resolved section), which also yields a persistent false-dirty diff. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/pql-improvements.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/pql-improvements.md b/docs/pql-improvements.md index f6c570c8..09d6ae73 100644 --- a/docs/pql-improvements.md +++ b/docs/pql-improvements.md @@ -154,6 +154,36 @@ doesn't have. --- +## 7. Question-index regeneration drops the "Resolved questions" section + +**Observed.** The repo keeps a human-readable index of decisions/questions in +`governance/README.md`, regenerated by `pql decisions sync` (run by the installed +hooks). After a sync, the regenerated index moves every *resolved* question back +into the main (open) list, in numeric order, and deletes the `## Resolved +questions` heading entirely. Concretely, Q-6, Q-19, Q-21, Q-22 are all +`status: resolved` per `pql decisions show`, yet the regenerated README lists +them as if open. + +**Impact.** Two problems: (a) the index mislabels resolved questions as open, so +the doc lies about project state; and (b) because a hook regenerates it on every +sync/commit, it produces a persistent false-dirty diff — `git restore` it and the +next pql operation brings it back, so the working tree never stays clean. + +**Repro.** +```bash +pql decisions show Q-6 # -> status: resolved +pql decisions sync # regenerates governance/README.md +git diff governance/README.md +# Q-6/19/21/22 moved into the open list; "## Resolved questions" section gone +``` + +**Suggested fix.** The index generator should key each question's section off its +`status` (open vs resolved vs withdrawn) and keep resolved/withdrawn entries +under their own heading — i.e. round-trip the same structure it parses, so a +sync is idempotent and doesn't reclassify resolved questions. + +--- + ## Summary The one that matters most is **#1** — a routine `git checkout` can silently erase