Conformance wave: prerequisite visibility + cross-platform declarations (incl. shared hook-utils fix)

[kyle-sexton]

Part of the plugin-conformance program — epic #313 (dimensions 9 + 10 of its matrix).

Shared root cause — fix once in the synced hook library: the fleet's hook-utils.sh telemetry-only skip path makes a missing optional CLI a silent no-op in the default no-sink configuration. Doctrine: absence must be surfaced to both the agent and the user; a silently skipped feature is a defect. Land the visible-skip mechanism (e.g. additionalContext note) in the library source and resync all hook plugins.

Silent-skip / undeclared-prereq FAILs (dim 9): actionlint (CLI + jq silent no-op), bash-format (shellcheck skip invisible), desktop-notification (jq ungated), docs-hygiene (markdownlint-cli2 ship gate undeclared + absent-binary unclassified), eol-normalizer (jq disables hook silently), kindle-dedrm (gh undeclared, no fallback), ruff-format (ruff/jq silent), source-control (jq + unzip missing from README), work-items (jq undeclared), review (agents hard-require gh, README has no prerequisites section), biome-format (jq undeclared — noted).

Cross-platform declaration FAILs (dim 10): actionlint, mcp-tools, work-items (bash/jq requirement unstated), ai-briefing, education, prototype (unconditional Bash helper, no Windows path), code-tidying, knowledge (PowerShell gap), event-storming (unconditional rm -rf teardown), repo-hygiene (bare .sh hook command instead of interpreter-named exec form — real Windows spawn risk).

Acceptance: every runtime prerequisite declared at point of use and in the README; absence classified per doctrine (required→stop with remediation, optional→visible warn + skip, N/A→quiet); shell requirements stated with a Windows path; version bump + CHANGELOG per plugin; contract gate green.

🤖 Generated with Claude Code

[kyle-sexton]

Wave complete — three tranches, all merged:

• feat: make missing hook prerequisites skip visibly (10 plugins) #328 (hook channel + shared lib). lib/hook-utils.sh gained the visible-skip mechanism: jq-free JSON emitters (hook::json_escape, hook::emit_channels, hook::emit_skip_notice, hook::emit_system_message), once-per-session dedup (hook::notice_once, markers under ${CLAUDE_PLUGIN_DATA}/skip-notices, session_id regex-parsed without jq), a jq gate (hook::require_jq), and a jq-free hook::raw_file_path applicability pre-filter so a missing-jq notice never fires for out-of-scope edits (Codex catch). All 10 carrying plugins resynced + bumped; every dim-9 silent skip in the hook fleet (actionlint, shellcheck, shfmt, biome, ruff, markdownlint-cli2, jq itself, desktop-notification's jq) now surfaces on both additionalContext and systemMessage. systemMessage/session_id/CLAUDE_PLUGIN_DATA semantics re-verified against the live docs this session. powershell-format's pwsh absence stays quiet as a deliberate not-applicable classification, now stated in its README.
• feat: declare and classify skill-channel runtime prerequisites (5 plugins) #329 (skill channel). docs-hygiene (compress's markdownlint-cli2 ship gate reclassified required→stop-with-remediation), kindle-dedrm (gh declared; pinned-tag fallback that cannot compose malformed URLs, incl. the null-tag case; Key_Finder hard stop; first CHANGELOG), source-control (README declares jq/Bash/unzip; the pull-request skill's loaded surface carries the jq gate), work-items (jq + seam entry-point gates in the loaded tracker-seam reference; honest seam-provisioning remediation), review (Requirements section; ci-log-auditor gh preflight). Four Codex P2 rounds folded in — the recurring theme was putting gates on surfaces skills actually load, not just READMEs.
• fix: state shell requirements with a Windows path across 8 plugins #331 (cross-platform). Shell requirements stated with the Git Bash Windows path across mcp-tools, ai-briefing, education, prototype, code-tidying, knowledge; event-storming teardown phrased shell-agnostically with quoted/-LiteralPath paths; repo-hygiene's destructive-guard hook moved to interpreter-named exec form. CHANGELOGs created for mcp-tools and education (eases Conformance wave: CHANGELOGs + freshness riders (15 + 7 plugins) #316).

Side finding while babysitting: the do-not-merge check fails on every PR since the v0.6.0 selector routes it onto the local runner, whose image lacks the gh CLI — filed as melodic-software/ci-runner#80 (not a required check; merges unaffected).

Deferred (recorded in the #323 thread, reaffirmed here): migrating bare-cat stdin readers onto hook::buffer_stdin — orthogonal stdin-semantics change, not part of this wave.

🤖 Generated with Claude Code