hook-telemetry: actionlint schema hook id must match emitted envelope (emit_tel "actionlint")

[kyle-sexton]

Lane: merge-drive (review-deferral, rule 7 / rule 11b standalone stream)

Deferred from a codex P2 review thread on PR #945 (docs/conventions/hook-telemetry/data/actionlint-check.schema.json), so the deferral can cite a tracked issue.

Finding (codex P2)

"Point actionlint telemetry at the emitted hook id" — the actionlint producer emits telemetry envelopes with hook: "actionlint" on every path (actionlint-check.sh calls emit_tel "actionlint"), but the new hook-telemetry schema keys/validates against a different hook id, so real emitted envelopes would not validate against the schema as written.

Classification

P2, non-DEFER-FORBIDDEN: schema-vs-producer consistency in the hook-telemetry convention data. Not data-loss, not a fail-open safety/merge gate, not security-posture, not silently-wrong output feeding an irreversible action. Telemetry-schema validation only.

Deferral rationale

Deferred (not fixed-on-branch in #945) to end the codex re-review treadmill on the schema cluster (repeated fix-pushes each drew fresh P2 schema findings). #945's exec-bit + closed-enum findings were already fixed; this remaining consistency item is tracked here so #945 can land and the schema/producer alignment is followed up independently.

Fix direction

Align the actionlint hook-telemetry schema's hook id with what actionlint-check.sh's emit_tel actually emits ("actionlint"), or adjust the producer — whichever the hook-telemetry convention intends as canonical.

Category: bug (schema/producer consistency) · priority: needs-triage.

[kyle-sexton]

This was generated by AI (triage-lane planning subagent).

Implementation plan — #959: align actionlint telemetry hook id

Decision defaulted: canonical id is actionlint-check; the PRODUCER (plugins/actionlint/hooks/actionlint-check.sh) + its test change, not the schema/README — veto before merge

The decision, resolved from evidence

The one-token misalignment must be fixed in the producer, emitting "actionlint-check" — not by rekeying the schema to "actionlint". Three authoritative artifacts already agree on actionlint-check; only the producer and its own test diverge.

Deciding precedent — the guardrails plugin. The convention's emitted envelope hook id is the hook-script basename, not the plugin name. The format hooks alone don't prove this (there plugin name == hook basename == schema name, so they're ambiguous), but guardrails is decisive: one plugin ships many hooks, each emitting its own basename:

Producer (path)	emit_tel id emitted	Schema file	Match
plugins/guardrails/hooks/block-no-verify.sh:102	"block-no-verify"	data/block-no-verify.schema.json	✓
plugins/guardrails/hooks/secret-pattern-detection.sh:147	"secret-pattern-detection"	data/secret-pattern-detection.schema.json	✓
plugins/guardrails/hooks/block-dangerous-git.sh:84	"block-dangerous-git"	data/block-dangerous-git.schema.json	✓
plugins/bash-format/hooks/bash-format.sh:218	"bash-format"	data/bash-format.schema.json	✓
plugins/actionlint/hooks/actionlint-check.sh:105,136,142	"actionlint"	data/actionlint-check.schema.json	✗ (this bug)

The guardrails rows prove the id is per-hook basename, not plugin name — structurally it must be, since one plugin ships multiple hooks that cannot share a single id. Under that rule, actionlint-check.sh must emit "actionlint-check", matching its schema data/actionlint-check.schema.json.

Corroborating authorities (all say actionlint-check):

• README declares itself source of truth and keys discovery on the hook value: "Its shape per producer is published at data/<hook>.schema.json, discovered by the envelope's hook value." (docs/conventions/hook-telemetry/README.md)
• README Implementers table: actionlint plugin → hook value actionlint-check → data/actionlint-check.schema.json.
• Schema title/description: "Discovered from the envelope hook value "actionlint-check"" (docs/conventions/hook-telemetry/data/actionlint-check.schema.json).

Rekeying the schema to "actionlint" would instead break the basename convention, contradict the Implementers table, and mint an id that no longer matches the hook script. Rejected.

The fix — 4 sites across 2 files (producer-side only)

plugins/actionlint/hooks/actionlint-check.sh — 3 emit sites, "actionlint" → "actionlint-check":

• L105 (actionlint-absent → skipped)
• L136 (findings → ok)
• L142 (clean → ok)

plugins/actionlint/hooks/actionlint-check.test.sh — L204, flip the assertion and its success-message string:

• [[ "$(jq -r '.hook' "$TEL")" == "actionlint" ]] → == "actionlint-check"
• ok "envelope: hook is actionlint" → ok "envelope: hook is actionlint-check"

The test currently locks in the wrong value; omitting it ships a partial fix that the test would then fail on. All three emit sites must change together or divergent envelopes persist.

No change to docs/conventions/hook-telemetry/data/actionlint-check.schema.json or README.md — they are already canonical.

Explicitly out of scope (scoped intentionally)

• No schema_version bump, no CHANGELOG.md entry. The published envelope/data contract is unchanged; this is a producer-conformance bugfix bringing emitted output into line with the existing contract.
• examples/actionlint-check.json fixture — optional, not a gap. The examples/ dir is already partial (14 fixtures for ~27 implementers; the other format hooks are absent too), so its omission is not anomalous. May be added as a consistency nicety, but it is not an acceptance criterion and should not gate the fix.
• No prose in plugins/actionlint/README.md, skills/setup/SKILL.md, hooks.json, or plugin.json asserts the telemetry hook id as "actionlint" (verified) — nothing else joins the change set.

Acceptance

1. A real emitted envelope carries hook: "actionlint-check" on all three paths (skipped / ok-with-findings / ok-clean), so it discovers and validates against data/actionlint-check.schema.json per the README discovery rule.
2. plugins/actionlint/hooks/actionlint-check.test.sh passes with the flipped assertion (run where actionlint is on PATH; it self-skips otherwise).
3. git grep 'emit_tel "actionlint"' plugins/actionlint/ returns nothing (all three converted; no bare-actionlint id remains).

Parallelism

Single fork, decision-defaulted. One trivial edit set (4 lines, 2 files) + one test run. No decomposition warranted.

[kyle-sexton]

This was generated by AI (triage-decide lane — intake routing).

Routed status: ready per T2 (ready-with-noted-decision). The planning subagent's plan (above) is high-confidence and resolves the canonical-direction fork from evidence: the envelope hook id is the hook-script basename (proven decisively by the guardrails plugin, where one plugin ships many hooks each emitting its own basename — so the id cannot be the plugin name), corroborated by the README Implementers table and the schema's own description. Three authoritative artifacts already say actionlint-check; only the producer + its test diverge.

Decision defaulted: canonical id is actionlint-check — fix the PRODUCER (plugins/actionlint/hooks/actionlint-check.sh, 3 emit_tel sites + the test assertion/message in actionlint-check.test.sh), NOT the schema/README — veto before merge. The examples/ fixture is a non-gating nicety.

No open prerequisite (producer, schema, README all on origin/main).

[kyle-sexton]

Claim (work lane, T3) — dispatching an implementation subagent this cycle. 2026-07-22T17:18:45Z

[kyle-sexton]

[kyle-sexton]

Done (2026-07-22): Fixed the 3 emit_tel sites in plugins/actionlint/hooks/actionlint-check.sh ("actionlint" → "actionlint-check") + flipped the test assertion, per the planning comment's evidence-resolved direction (per-hook-basename convention, proven by guardrails' many-hooks-per-plugin precedent). No schema/README change needed (already canonical). CI green (35/35), no review threads. Will auto-close when PR #1044 merges.