chore(hub-client): guardrail for changelog.md qmd parse breakage (bd-q5o7ekzn)

.claude/hooks/changelog-reminder.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+# Post-tool-use hook: remind to run the changelog WASM render test after
+# editing hub-client/changelog.md.
+#
+# The changelog is rendered through the qmd pipeline in the About tab, and
+# `changelogRender.wasm.test.ts` gates it in CI (the TS Test Suite). A stray
+# qmd delimiter (~ _ ^ $) produces a parse error such as
+# "[Q-2-17] Unclosed Subscript", which turns the whole suite red — with the
+# render succeeding for every other file, so it is easy to miss locally.
+#
+# This hook does NOT run the test (that would add latency and needs a built
+# WASM); it injects a reminder with the exact command so the edit is not
+# pushed unverified. See claude-notes/plans/2026-07-07-broken-main-ci-changelog-subscript.md
+# (strand bd-q5o7ekzn) for the incident that motivated it.
+#
+# Receives JSON on stdin with tool_input.file_path.
+
+file_path=$(jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+# Only fire for hub-client/changelog.md (absolute or relative path).
+case "$file_path" in
+    *hub-client/changelog.md) ;;
+    *) exit 0 ;;
+esac
+
+jq -n '{
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse",
+    additionalContext: "Reminder: hub-client/changelog.md is rendered through the qmd pipeline and is gated in CI by changelogRender.wasm.test.ts. A lone qmd delimiter (~ _ ^ $) will fail parsing (e.g. [Q-2-17] Unclosed Subscript) and turn the TS Test Suite red. Before committing this change, run:  cd hub-client && npm run test:wasm  — no WASM rebuild is needed for a changelog-only edit; the test runs against the existing WASM artifact."
+  }
+}'
+
+exit 0

.claude/settings.json

@@ -8,6 +8,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format-rust.sh",
             "timeout": 30000
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/changelog-reminder.sh",
+            "timeout": 10000
           }
         ]
       }

claude-notes/plans/2026-07-07-broken-main-ci-changelog-subscript.md

@@ -119,25 +119,32 @@ just the file you touched, before every push to `main`.*
 
 ### Phase 4 — Guardrail against recurrence (process, not just content)
 
-Options to reduce the chance a lone-delimiter or size-ceiling regression
-reaches `main` again. To be discussed with the user before implementing —
-this phase is a menu, not a commitment:
-
-- [ ] **(cheap, recommended)** Add a `lint`-style check or a note in
-      `hub-client/changelog.md`'s HTML comment header reminding authors
-      that changelog prose is rendered through qmd, so `~`, `_`, `^`, `$`
-      etc. must be escaped or avoided. The `changelogRender.wasm.test.ts`
-      test already enforces this — the gap is *authors not running it*, not
-      missing coverage.
-- [ ] **(process)** Treat "changelog touched" as implying "run
-      `npm run test:wasm`" — because the changelog is a rendered artifact,
-      editing it is a code change, not a docs change.
-- [ ] **(optional, heavier)** Consider whether `cargo xtask verify` should
-      be the default pre-push gate for any `hub-client/**` change, and
-      whether a git pre-push hook or CI-required-status-check on `main`
-      should enforce it. Flag: hooks that run `cargo xtask verify` are slow
-      (full WASM build); may not be worth the friction. **Decision deferred
-      to the user.**
+Chosen (with the user, 2026-07-07): an **active reminder** an agent cannot
+miss, backed by a **passive note** at the point of edit. Deliberately *not*
+auto-running the test or gating pushes — the changelog is edited rarely and
+the fix is a single fast command; a reminder is enough.
+
+- [x] **Active: PostToolUse hook.** `.claude/hooks/changelog-reminder.sh`
+      fires on any `Edit`/`Write` whose `file_path` ends in
+      `hub-client/changelog.md` and injects `additionalContext` (visible to
+      the agent) with the exact command `cd hub-client && npm run test:wasm`
+      and the qmd-delimiter warning. Registered in `.claude/settings.json`
+      next to `format-rust.sh`. Non-blocking, ~0 latency; does **not** run
+      the test (that would add latency and needs a built WASM). Verified: it
+      fired live on the edit that added the header note below, and stays
+      silent for `.rs` files and `docs/changelog.md`.
+- [x] **Passive: changelog header note.** The `<!-- -->` header of
+      `hub-client/changelog.md` now warns that the file is rendered through
+      qmd, that `~ _ ^ $` are delimiters, and to run `npm run test:wasm`
+      after editing. (Delimiters inside the HTML comment are not parsed —
+      confirmed: 129/129 WASM tests still pass with the note in place.)
+- [x] **Process note:** editing the changelog is a *code* change (rendered
+      artifact), not a docs change — captured in both the hook message and
+      the header note.
+- [ ] **(not done, optional/heavier)** A `cargo xtask verify` pre-push gate
+      for all `hub-client/**`, or a required CI status check on `main`.
+      Considered heavier than warranted for this failure mode; **left for
+      the user** to pick up if the lightweight guardrail proves insufficient.
 
 ## Non-goals / notes
 

hub-client/changelog.md

@@ -13,6 +13,14 @@ Changelog entry format:
 Group commits by date under level-three headers. Entries within each date should
 be in reverse chronological order (latest first).
 
+⚠️  This file is rendered through the qmd pipeline in the About tab, and the
+test `changelogRender.wasm.test.ts` gates it in CI. Prose is qmd, not plain
+text: a lone `~`, `_`, `^`, or `$` is a markup delimiter and an unclosed one
+fails the parse (e.g. `[Q-2-17] Unclosed Subscript`), turning the whole TS
+Test Suite red. Escape them (`\~`) or reword (e.g. "about 37 MB", not "~37MB").
+After editing, run `cd hub-client && npm run test:wasm` before committing — no
+WASM rebuild is needed for a changelog-only edit.
+
 -->
 
 ### 2026-07-07