From 67a3c50ac74abe2d81eabbf044d6f3a6a56e21c2 Mon Sep 17 00:00:00 2001 From: seal Date: Sun, 16 Aug 2026 18:49:23 -0400 Subject: [PATCH] docs(hooks): document the pre-push temp-worktree tool-drift hazard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The pre-push gate runs `moon ci` inside jj-vine's throwaway hook worktree (`/tmp/jj-hooks-worktree-*`), which has the checked-out tree but no direnv activation. So `moon ci` there resolves biome/moon from the ambient system PATH instead of the devenv pins — a system biome that is not the biome.json pin (2.5.4) reformats files the pinned biome leaves clean and reds the gate falsely. Extend the `hk.pkl` header comment with the hazard, a never-`--write`-from-the-worktree warning, the interim workaround (verify in the devenv shell, push with hooks skipped, confirm GitHub CI green), and a pointer that the durable fix — propagating the repo's devenv env into the hook worktree, one fix fleet-wide — is tracked in the zireael/jj-hp lane. Comment-only; the `check = "moon ci"` step is untouched and `hk validate` passes. Spec-impact: none. Refs SEA-2006 Co-authored-by: Matt Wilkinson --- hk.pkl | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/hk.pkl b/hk.pkl index 5e359508..99eb01d7 100644 --- a/hk.pkl +++ b/hk.pkl @@ -15,6 +15,24 @@ // Bypass knobs: // HK=0 git push // skip all hooks (emergency) // git push --no-verify // hk respects this too +// +// Temp-worktree tool drift (jj-vine push). +// jj-vine runs this hook in a throwaway worktree (/tmp/jj-hooks-worktree-*) +// that has the checked-out tree but no direnv activation, so `moon ci` +// resolves biome/moon from the ambient system PATH instead of the devenv +// pins. A system biome that is not the biome.json pin (2.5.4) reformats +// files the pinned biome leaves clean, producing a false-red gate. NEVER +// run biome `--write` from this worktree: an off-version biome's output +// breaks main CI, which runs the pinned 2.5.4. +// +// Interim workaround (until the durable fix ships): verify in the devenv +// shell of your source checkout (`moon ci` there uses the pinned tools), +// then push with hooks skipped (the Bypass knobs above; via jj-vine, its +// --no-hooks path) and confirm GitHub CI green — CI installs the pinned +// toolchains itself and never has the drift. +// +// The durable fix — propagate the repo's devenv env into the hook worktree, +// one fix fleet-wide — is tracked in the zireael/jj-hp lane, not here. amends "package://github.com/jdx/hk/releases/download/v1.45.0/hk@1.45.0#/Config.pkl" // Pin the default-branch reference. Without this, hk's auto-detect reads