docs(hook-observability): refresh statusMessage adoption (30/31) + define dim-9; cover buffer_stdin timeout & EPOCHREALTIME skip (F4, F3, F2-shared)

[kyle-sexton]

Closes #1169.

Fleet-scope findings surfaced by the bash-format consumer audit (handoff-inbox item 20260723-095036), re-verified and rescoped against current source. No runtime behavior change — a fleet-doc correction plus shared-lib test coverage.

Changes

• F4 — statusMessage adoption doc was badly stale. The doc claimed "no hooks.json in the fleet declares statusMessage yet — all 27 wired type: command handlers across 12 plugins need it added." Scripted count of current source (jq over every plugins/*/hooks/hooks.json): 31 command-type handlers across 15 hook-bearing plugins, 30 declare statusMessage; sole holdout plugins/disk-hygiene (a PreToolUse destructive-guard). Doc now records near-complete adoption, names the holdout, and states the feat(conventions): hook-observability fleet convention + fleet adoption #836 close condition.
• F3 — dim-9 doctrine defined. Grounding refuted the "bash-format-local" premise: the label is fleet vocabulary cited in 9 hook scripts (actionlint, bash-format, biome-format, desktop-notification, eol-normalizer, go-format, powershell-format, ruff-format, typos-format) with no central glossary (verified — no dimensions registry exists). Defined it authoritatively in the visible-skip (systemMessage) section it names, and noted the broader undefined dim-N scheme as a separate follow-up. Not stripped from bash-format — that would fragment a fleet-wide convention (reuse-or-replace).
• F2-shared — shared-lib test coverage. Added lib/hook-utils.test.sh cases for hook::buffer_stdin's timeout path (return 2 / BLOCKED on stderr) and hook::emit_telemetry's EPOCHREALTIME-absent (Bash < 5.0) skip-fail-open. Shared-lib behavior → tests live centrally, not duplicated into a plugin.

Verification

• bash lib/hook-utils.test.sh → PASS=85 FAIL=0 (2 new cases green) on bash 5.3.
• shellcheck -x -S warning lib/hook-utils.test.sh → clean.
• Only lib/hook-utils.sh's test was touched (not the SSOT lib itself), so no sync-hook-utils.sh run and no plugin version bumps are needed.

Notes

• F1's original "add a membership-guard test" was already satisfied by lib/hook-utils.test.sh Test 12 — see sibling bash-format: docs/tests polish — out-of-project scope docs, opt-in/shfmt test coverage, setup Gotchas (F1, F2-local, F6) #1168 (bash-format docs/tests, PR docs(bash-format): document project scope + setup gotchas; add opt-in/shfmt-fallback test coverage (F1, F2, F6) #1171).
• The disk-hygiene holdout is left as the documented remaining item; adding its statusMessage (or marking it a deliberate exception) would close feat(conventions): hook-observability fleet convention + fleet adoption #836 but pulls a third plugin into this PR, so it is deferred per the group-by-plugin boundary.

🤖 Generated with Claude Code

Related

• docs(bash-format): document project scope + setup gotchas; add opt-in/shfmt-fallback test coverage (F1, F2, F6) #1171 — sibling PR for the bash-format-local findings (F1, F2-local, F6) from the same audit item.
• bash-format: verify setup skill '--config only applies on fresh install' claim (F5) #1170 — HITL follow-up (F5, --config fresh-install claim), not closed here.
• feat(conventions): hook-observability fleet convention + fleet adoption #836 — statusMessage fleet-adoption tracking issue this PR updates (not closed; one holdout remains).
• Handoff-inbox item 20260723-095036-bash-format-audit-docs-tests-polish (producer SW2030).

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 2m 34s —— View job

---

Code Review

• Gather context and understand the request
• Review PR diff
• Read changed files
• Analyze findings
• Post review feedback

---

Overall: Clean, well-scoped doc correction + test additions. No runtime behavior changes. Two minor observations and one question worth addressing before merge.

---

docs/conventions/hook-observability/README.md

F4 count update — accurate and well-grounded. The transition from the stale "27 handlers / 12 plugins / 0 adopters" to "31 handlers / 15 plugins / 30 adopters / 1 holdout" is clearly sourced and the #836 close condition is precisely stated.

F3 dim-9 definition — well-placed co-location with the rule it names. The parenthetical noting the broader dim-N scheme lacks a central registry is helpful context. One minor note:

Note

The dim-8 / dim-11 examples embedded in the parenthetical are themselves undefined to a reader unfamiliar with the fleet's history. They illustrate that dim-N is informal, but a reader landing on this doc cold gets no meaning from dim-8 = uniform setup-skill wave. If the follow-up item to document the full dim-N scheme is tracked, consider just noting the label count ("the scheme covers at least 11 numbered dimensions") without naming undefined dimensions. Not blocking, but worth a thought.

---

lib/hook-utils.test.sh

Both tests are structurally sound and correctly exercise the target paths.

Test 18 (hook::buffer_stdin timeout):

permalink

{ printf '{"incomplete":'; sleep 1; } | {
  CLAUDE_PLUGIN_OPTION_STDIN_READ_TIMEOUT=0.4 hook::buffer_stdin >/dev/null 2>"$bs_err_file"
  echo "$?" >"$bs_rc_file"
}

The exit-code capture idiom (write to a temp file from within the pipe's right-side subshell) is correct under pipefail — the right-side subshell exits 0 from echo, so the pipeline doesn't trip the error trap.

[!QUESTION]
The test comment notes that jq must be present for return 2 rather than return 1 ("without it the branch fails open to return 1"). Should there be an explicit jq availability guard at the top of this test, or is jq availability guaranteed by the CI environment contract? If a future CI runner drops jq, this test will silently report a different failure path without a clear diagnosis. Consider adding a guard: command -v jq >/dev/null || skip "jq absent — timeout-path test requires jq" (or whatever the file's skip idiom is). Fix this →

Test 19 (emit_telemetry EPOCHREALTIME-absent):

permalink

rc19=$(
  unset EPOCHREALTIME
  start=${EPOCHREALTIME:-}
  HOOK_TELEMETRY_SINK="$sink19" hook::emit_telemetry "t" "PostToolUse" "ok" "$start" '{"tool":"x","file":"y","findings":[]}'
  echo $?
)
sleep 0.1

The early-return guard in emit_telemetry ([[ -n "$start_epoch" && -n "$now" ]] || return 0) fires before any background dispatch when $start is empty, making the sleep 0.1 reliable rather than racy — the 100 ms is dead time but not a flakiness risk. This is fine.

The $() subshell captures echo $? (stdout) while stderr goes to the terminal — there's no stderr redirection here, so any unexpected stderr output from emit_telemetry would be visible in CI logs. That's fine for a test.

Note

Minor consistency nit: earlier tests in this file use echo "$?" >"$some_rc_file" with a quoted $?; this test uses echo $? (unquoted). The value is always numeric so it doesn't matter, but the inconsistency stands out. Not blocking.

---

Summary

Finding	Severity	Verdict
Test 18 missing jq guard	Minor / Low	Worth addressing
Unquoted $? in Test 19	Cosmetic	Not blocking
Dim-8/dim-11 examples in parenthetical	Cosmetic	Author's call

No correctness bugs, no security issues, no CLAUDE.md violations. The shared-lib test approach (central coverage, no plugin duplication) is correct per the repo's structure. The documentation state is now accurate and the dim-9 anchor is a genuine improvement for future readers.

Ready to merge after addressing (or explicitly deferring) the jq guard question.

[claude]

Claude finished @kyle-sexton's task in 1m 30s —— View job

---

Security Review — PR #1172

• Gather context (PR diff, changed files)
• Review docs/conventions/hook-observability/README.md
• Review lib/hook-utils.test.sh
• Report findings

---

No security issues found.

This PR touches two files. Neither introduces exploitable risk.

docs/conventions/hook-observability/README.md

Pure documentation — updates adoption counts, names the disk-hygiene holdout, and authoritatively defines the dim-9 label in the visible-skip section. No code execution, no configuration, no secrets, no attack surface.

lib/hook-utils.test.sh (Test 18, lines 816–837; Test 19, lines 839–861)

Test 18 — hook::buffer_stdin timeout path:

• Temp files (bs_rc_file, bs_err_file) are created via mktemp — race-free and safely quoted throughout.
• The pipe producer { printf '{"incomplete":'; sleep 1; } is a static string literal with no interpolation.
• CLAUDE_PLUGIN_OPTION_STDIN_READ_TIMEOUT=0.4 is a literal value scoped to the command invocation.
• Cleanup via rm -f "$bs_rc_file" "$bs_err_file" is correct.

Test 19 — hook::emit_telemetry EPOCHREALTIME-absent skip:

• tel19 and sink19 are both mktemp-sourced paths — no metacharacter risk.
• unset EPOCHREALTIME and the start= assignment are scoped inside a command-substitution subshell; they do not leak into the surrounding suite.
• HOOK_TELEMETRY_SINK="$sink19" is an env-var override for a single command invocation, and $sink19 is a mktemp-derived absolute path with no special characters.
• rm -f "$tel19" "$sink19" correctly removes both the output file and the generated sink script.

Pre-existing make_sink note (out of scope for this PR): The existing helper embeds its argument directly into an unquoted heredoc, which would allow injection if called with an attacker-controlled path. All callers — including the two new tests — pass mktemp output exclusively, so no path is exploitable. This predates the PR and is flagged only for awareness.