dehlakandClaude
f0fa602ff4
Running newest-first log of install and environment friction, seeded with the pql hooks issue: pql init wrote delegators into .git/hooks while core.hooksPath was unset, silently disabling the repo's pre-push gate. Documents the make-hooks fix and the pql-init pitfall. Co-Authored-By: Claude <noreply@anthropic.com>
47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# friction.md
|
|
|
|
A running log of install / setup / environment friction — the papercuts that
|
|
cost time getting clide (and its tooling) working on a machine. Newest first.
|
|
|
|
Each entry: **symptom → root cause → fix**, with enough detail that the next
|
|
person (or the next clone) can recognise and resolve it fast.
|
|
|
|
---
|
|
|
|
## 2026-06-06 — pql hooks disabled the repo's pre-push gate
|
|
|
|
**Symptom**
|
|
- "pql setup is broken." On the surface pql worked (`pql schema`,
|
|
`pql decisions sync`, `pql plan status` all fine), but the git hook wiring
|
|
was in a split-brain state.
|
|
|
|
**Root cause**
|
|
- The repo's intended setup is `git config core.hooksPath .githooks` (run via
|
|
`make hooks`). `.githooks/` is the committed, canonical hook set: it carries
|
|
**both** pql's planning delegators (pre-commit / post-merge / post-checkout /
|
|
post-rewrite, each sourcing `.pql/hooks/*`) **and** the repo's own `pre-push`
|
|
gate (`make push-check`).
|
|
- `core.hooksPath` was **unset** in every scope, so git fell back to the
|
|
default `.git/hooks/`. `pql init` had populated *that* directory with only
|
|
the pql delegators — **no `pre-push`**.
|
|
- Net effect: the pre-push gate (decisions + core + fast tests + a11y) was
|
|
silently **not running** on push, while pql's automation ran only by accident
|
|
from the default dir. CLAUDE.md requires the gate to always run and forbids
|
|
`--no-verify`, so this was a real (silent) regression, not cosmetic.
|
|
|
|
**Fix**
|
|
- `make hooks` → restores `core.hooksPath = .githooks` (now `pre-push` and the
|
|
pql delegators all fire from one canonical, git-tracked source).
|
|
- Removed the stray pql-only delegators from `.git/hooks/`
|
|
(`pre-commit`, `post-merge`, `post-checkout`, `post-rewrite`). They became
|
|
inert once hooksPath pointed elsewhere, and leaving them created a dangerous
|
|
partial fallback — a hook set that runs pql but silently skips the pre-push
|
|
gate if `core.hooksPath` ever gets unset again. The real hook logic lives in
|
|
`.pql/hooks/` and was untouched.
|
|
|
|
**Watch out for**
|
|
- `pql init` installs into the default `.git/hooks/` and does **not** respect an
|
|
existing `core.hooksPath`. After running it, re-run `make hooks` and verify
|
|
with `git rev-parse --git-path hooks` (should print `.githooks`) and confirm
|
|
`.githooks/pre-push` is present & executable.
|