HANDOFF.md

@@ -1,7 +1,12 @@
-# HANDOFF — woodpecker-trigger-discipline (round 1)
+# HANDOFF — woodpecker-trigger-discipline (round 2)
 
-**Written 2026-08-13.** Verified against live state immediately before writing:
-every commit hash, issue state and version below was read back, not recalled.
+**Written 2026-08-13, updated after round 2 the same day.** Verified against
+live state immediately before writing: every commit hash, issue state and
+version below was read back, not recalled.
+
+**Round 2 changed items 2 and 4 of the priority list; item 1 is unchanged and
+still the only thing that needs a human.** Everything under "Most likely to
+mislead you" still holds and was re-confirmed — read it anyway.
 
 Delete this file when SC-003 and oleks/claude-plugin-cicd-insights#1 close — it
 is a resume note, not a plugin artifact.
@@ -56,11 +61,27 @@ uvx --with mdformat-gfm --with mdformat-frontmatter mdformat --wrap 80 <path>
 then has no name and never loads. It does not error. Knowing about the tables
 gotcha is exactly what makes the truncated command look correct.
 
-**4. In `../cluster`, `bin/check-routing.sh` and `bin/generate-descriptions.sh`
-give a confident FALSE GREEN on this machine.** emmett has `yq` 3.4.3 (the
-Python one); CI pins mikefarah/yq v4.53.3. Different programs, same binary name.
-Local reported "no drift detected" on the exact tree CI had just failed. **Trust
-CI, not those scripts.** Tracked as oleks/claude-plugin-cluster#252.
+**4. ~~In `../cluster`, both routing scripts give a confident FALSE GREEN.~~
+CORRECTED in round 2 — this was half wrong, and the wrong half is the one that
+would waste your time.** Reproduced directly with BOTH yq flavours installed
+locally (`nix shell nixpkgs#yq-go` gives you CI's exact v4.53.3 — cheap, it is a
+substituted binary, not a build):
+
+- **`check-routing.sh` does NOT false-green.** Under kislyuk 3.4.3 and mikefarah
+  v4.53.3 it produces byte-identical output and agrees with CI. That is
+  expected: oleks/claude-plugin-cluster#196 deliberately made its expression
+  flavour-agnostic. The local/CI disagreement recorded in #252 is better
+  explained by the known-flaky `lint-routing` (oleks/claude-plugin-cluster#232)
+  — one of its two cited findings is the exact `registry-pins.txt` stale claim
+  documented there as appearing once and vanishing on rerun.
+- **`generate-descriptions.sh` was worse than reported: it could not run at
+  all** under v4, exiting 3 with "mikefarah v3? upgrade to v4" *while running on
+  v4*. Fixed in PR oleks/claude-plugin-cluster#253 (0.85.1).
+
+**The lesson worth keeping**: "local tooling lies to you" and "a known-flaky
+check fired" call for opposite responses, so don't merge them into one story.
+And do not assert `yq` *is* mikefarah v4 — that breaks the kislyuk path #196
+went out of its way to support and that emmett actually uses.
 
 ______________________________________________________________________
 
@@ -68,13 +89,26 @@ ______________________________________________________________________
 
 **In `cicd-insights`: nothing.** `git status` clean and HEAD == `origin/main` —
 verify with `git status --short && git ls-remote origin main`. The last CODE
-commit is `d77e7f7`; anything after it touches only this file.
+commit is `d77e7f7`; anything after it touches only this file. **Round 2 made no
+code change in this repo at all.**
 
 **In `../cluster`: one untracked file that is NOT mine** —
-`specs/.markdownlint-cli2.jsonc`, from another session's spec-kit run. It was
-deliberately left alone (I staged only my own files). Do not commit or delete it
+`specs/.markdownlint-cli2.jsonc`, from another session's spec-kit run. Still
+present after round 2, still deliberately left alone. Do not commit or delete it
 without checking whose it is.
 
+**Round 2's work is banked on remote branches, in two OTHER repos, as open PRs**
+— nothing is stranded, and both worktrees were removed only after
+`git ls-remote` confirmed each branch head server-side:
+
+| Repo                          | Branch                                   | Head      | PR                                           |
+| ----------------------------- | ---------------------------------------- | --------- | -------------------------------------------- |
+| `oleks/claude-plugin-cluster` | `fix/252-generate-descriptions-yq-probe` | `9c72c1f` | #253, CI green, **unmerged**                 |
+| `oleks/emmett`                | `fix/387-ccl-skip-visible`               | `ffe6928` | #388, **unmerged**, needs deploy after merge |
+
+Both are left unmerged on purpose (this session does not merge). Neither primary
+checkout was touched; both are clean on `main`.
+
 ______________________________________________________________________
 
 ## What landed
@@ -137,16 +171,35 @@ ______________________________________________________________________
      `cicd-insights:woodpecker-trigger-discipline`. If any loads the sibling
      instead, the lever is narrowing the *sibling's* description further, not
      widening this one — the phrase set here is already exhaustive.
-1. **oleks/emmett#387** — install `claudecode-linter` on emmett *and* make the
-   `if which(...)` skip visible. The second half matters independently: a guard
-   whose absence is indistinguishable from success is how this went undetected.
-   Until it lands, all 30 plugin repos are unguarded against the mdformat
-   corruption.
-1. **oleks/claude-plugin-cicd-insights#1** — blocked on #387; nothing further to
-   do in this repo.
-1. **oleks/claude-plugin-cluster#252** — the yq false-green. Suggested fix is a
-   flavour/version assert in both scripts so they fail loudly rather than pass
-   wrongly.
+1. **oleks/emmett#387** — *partly done in round 2.* Acceptance item **3** (make
+   the skip visible) is committed in PR oleks/emmett#388 (`ffe6928`), labelled
+   `nixos-deploy-pending`, queued on the rolling tracker oleks/emmett#120. **Two
+   things remain:** merge + deploy that PR (it ships via `nixos/wp.nix` as a Nix
+   derivation, so it is inert until deploy-rs activates it), and then acceptance
+   items **1–2** — package `claudecode-linter` (npm, `dist/`, v2.1.228 at
+   `~/projects/claudecode-linter`) with `buildNpmPackage` and install it
+   declaratively. That derivation build belongs on a **remote builder**, not on
+   emmett. **After the deploy but before the linter is installed, the correct
+   output is `CCL ⏭`, not `CCL ✅`.** The skip token appearing is the fix working
+   — do not "fix" it back. Until items 1–2 land, all 30 plugin repos remain
+   unguarded against the mdformat corruption.
+1. **oleks/claude-plugin-cicd-insights#1** — still blocked on #387; nothing
+   further to do in this repo.
+1. **oleks/claude-plugin-cluster#252** — *fixed in round 2, PR open.*
+   oleks/claude-plugin-cluster#253 (0.85.1) ports check-routing.sh's proven yq
+   probe into `generate-descriptions.sh` and adds
+   `bin/generate-descriptions.sh --check` to the `lint-routing` CI step — the
+   root cause was that CI pinned yq for the CHECK script and never once ran the
+   FIX script it tells you to use, so the two diverged silently. CI pipeline 445
+   is green and its log shows both scripts passing under v4.53.3. **The PR is
+   open, not merged** (this session does not merge).
+1. **oleks/emmett#389** — *new in round 2.* The silent-skip failure mode is
+   **systemic**, not specific to `claudecode-linter`: `SHC`/`HDL`/`YML`/`TPL`/
+   `CPV` all still use the same `if which(...)` shape, so each one's absence is
+   still indistinguishable from success. PR #388 fixes only the CCL slot but
+   adds the reusable `skip_lint()` helper, so the remaining work is mechanical —
+   apply it to each guard, deciding scope before availability so out-of-scope
+   repos stay quiet rather than turning the summary line into noise.
 
 ______________________________________________________________________