docs(ruff-format): add hook-telemetry data schema + registry row

[kyle-sexton]

Summary

plugins/ruff-format/hooks/ruff-format.sh emits telemetry via hook::emit_telemetry("ruff-format", ...) but never shipped the hook-telemetry convention's per-hook data schema or Implementers table row, unlike the markdown-format and typos-format producers. Consumer sinks discovering the ruff-format hook value had no published data schema to validate against.

Fix

• Added docs/conventions/hook-telemetry/data/ruff-format.schema.json, mirroring markdown-format.schema.json's shape (tool, file, findings: string[]) — ruff-format.sh builds data.findings as an array of concise diagnostic lines from ruff check --no-fix --output-format concise, the same shape as markdown-format's lint-line findings (not typos-format's structured {typo, corrections} objects).
• Added the ruff-format row to the Implementers table in docs/conventions/hook-telemetry/README.md.
• Bumped plugins/ruff-format/.claude-plugin/plugin.json to 0.4.3 (patch — conformance fix, no hook behavior change) with a matching CHANGELOG.md entry.

Followed the same pattern as typos-format's schema+registry-row addition (#872): no hook-telemetry/CHANGELOG.md entry, since per-hook data schemas are not separately version-stamped (README "Versioning").

Verification

• jq . docs/conventions/hook-telemetry/data/ruff-format.schema.json and jq . plugins/ruff-format/.claude-plugin/plugin.json — both valid JSON.
• Re-fetched origin/main immediately before opening this PR and confirmed plugins/ruff-format/.claude-plugin/plugin.json was still at 0.4.2 (no collision with the version bump).
• Searched scripts/run-plugin-tests.sh and scripts/aggregate-hygiene-results.sh for an automated Implementers-table/schema-file consistency check — none exists; this gap is exactly what issue docs(ruff-format): missing hook-telemetry data schema + registry row #874 is about, so verification here is manual: diffed against markdown-format.schema.json and typos-format.schema.json field-by-field, and cross-checked data.findings's shape against the actual jq construction in ruff-format.sh's build_data_json.
• gh pr list --state open showed no other open PR touching plugins/ruff-format/ or docs/conventions/hook-telemetry/ — no collision risk.

Related

• Reference templates: markdown-format plugin's data/markdown-format.schema.json + registry row, and typos-format plugin's data/typos-format.schema.json + registry row (feat(typos-format): add per-file typos autofix hook plugin #872).
• Epic: Epic: lint/static-analysis gap closure #830 (docs/topics/lint-static-analysis-gaps/PLAN.md).

Closes #874

[claude]

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

---

PR Review: docs(ruff-format): add hook-telemetry data schema + registry row

• Gather context and read changed files
• Review schema correctness and consistency with peer schemas
• Review README registry row
• Review plugin.json version bump and CHANGELOG
• Post findings

---

Schema correctness

The new schema at docs/conventions/hook-telemetry/data/ruff-format.schema.json accurately describes what ruff-format.sh actually emits. Cross-referencing against build_data_json (lines 102–109 of ruff-format.sh):

jq -n \
  --arg tool "$TOOL" \
  --arg file "$FILE_REL" \
  --argjson findings "$1" \
  '{tool:$tool,file:$file,findings:$findings}'

All three required fields (tool, file, findings) are always present — the fallback path at the end of build_data_json also emits {"tool":"","file":"","findings":[]}, so the required constraint is satisfied in every reachable code path, including RC=2 (Ruff internal error, lines 259–268). findings is always string[] — constructed via jq -R . | jq -s . from the concise output of ruff check --no-fix --output-format concise, one string per diagnostic line, matching "items": { "type": "string" }. The description "Residual Ruff diagnostics remaining after check --fix and format, one concise line per diagnostic. Empty array = clean" is accurate for all three emit paths (clean at line 226–228, findings at lines 244–250, tool-break at lines 266–268).

Structural consistency with peers

Schema	findings item type	Matches ruff-format?
markdown-format	string	Yes — this PR mirrors it exactly
typos-format	object {typo, corrections}	No (intentionally — different shape)

The PR correctly identified that ruff-format's findings are flat concise-format strings (same as markdown-format's markdownlint lines), not typos-format's structured objects. Shape choice is correct.

additionalProperties: true, the $schema draft 2020-12 declaration, and the $id URI pattern are all consistent with the rest of the data/ schemas.

Registry row

The row added to the Implementers table is correctly formatted and the hook value "ruff-format" matches the literal string passed in every emit_tel "ruff-format" ... call in the hook script. Insertion between typos-format and bash-format preserves the existing add-order sequencing.

Version bump and CHANGELOG

Patch bump 0.4.2 → 0.4.3 is appropriate for a conformance-only fix with no behavior change. ### Fixed is defensible — this fills a gap that violated the hook-telemetry convention ("a hook shipping telemetry without a published data schema"). The CHANGELOG entry is accurate and cites the right sibling producers for comparison.

One gap worth a follow-up

examples/markdown-format.json exists as a worked fixture for the first formatter producer, but there is no examples/ruff-format.json here (nor was one added in #872 for typos-format, so this is consistent with that precedent). Since the README calls examples/ part of the convention's source of truth, a follow-up issue to add examples/ruff-format.json and examples/typos-format.json would close that gap — but it isn't blocking this PR, which correctly follows #872's established pattern.

A minimal example would look like:

{
  "schema_version": "1.0",
  "timestamp": "2026-07-21T00:00:00Z",
  "hook": "ruff-format",
  "hook_event": "PostToolUse",
  "status": "ok",
  "duration_ms": 87,
  "data": {
    "tool": "Write",
    "file": "src/app.py",
    "findings": [
      "src/app.py:14:1: E501 Line too long (92 > 88 characters)"
    ]
  }
}

Summary

The schema is correct, the registry row is properly wired, the version bump and CHANGELOG are appropriately scoped. No correctness, security, or structural issues found. The example-fixture gap is pre-existing and out of scope for this PR. Looks good to merge.

[claude]

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

---

Security Review — PR #886

• Gather PR diff and read changed files
• Review ruff-format.schema.json for security issues
• Review README.md changes
• Review plugin.json version bump
• Review CHANGELOG.md entry
• Post security findings

---

Findings

No security issues found.

This PR is a documentation/conformance fix: a new JSON Schema file, a README table row, a patch-version bump in plugin.json, and a CHANGELOG.md entry. None of the four changed files introduce an executable code path or new attack surface.

Specific checks performed:

ruff-format.schema.json — The $id field references the main-branch raw URL rather than a pinned commit SHA. In strict JSON Schema tooling, a validator that auto-fetches schemas by $id would always resolve to the current main HEAD, making the schema identity mutable. In practice this is an accepted convention for $id (it is a URI identifier, not a required fetch target), matches the pattern used by every sibling schema in this repo (markdown-format, typos-format, etc.), and the schema itself is a validation document — not executed code. SUGGESTION-level concern, not unique to this PR, and consistent with existing repo convention. No finding raised.

hook-utils.sh / ruff-format.sh (existing, not changed) — The hook::emit_telemetry dispatch (printf '%s\n' "$envelope" | ("$sink" >/dev/null 2>&1) &, line 455) properly double-quotes $sink. build_data_json uses jq --arg/--argjson for all variable embedding (no shell interpolation into JSON). Ruff diagnostic lines are serialized via jq -R . | jq -s .. These are not changed by this PR and carry no injection surface.

plugin.json — Patch semver bump only (0.4.2 → 0.4.3). No new capabilities, permissions, or dependency pins introduced.

README.md / CHANGELOG.md — Prose/table updates. No security relevance.

[kyle-sexton]

Post-green review classification (work lane):

Finding	Source	Classification	Disposition
Everything substantive	PR review + security review	"Looks good to merge" / "No security issues found"	No action needed
No examples/ruff-format.json fixture (mirrors existing gap — #872/typos-format also lacks one)	PR review	Pre-existing convention gap, not introduced by this PR, correctly follows #872's precedent	Left alone — could be a future follow-up covering both gaps together, not filing now since it's explicitly non-blocking and pre-existing
Schema $id references main HEAD rather than a pinned SHA	Security review (SUGGESTION)	Accepted repo-wide convention across all sibling schemas, not unique to this PR, schema is a validation doc not executed code	Left alone

No DEFER-FORBIDDEN class applies (docs/conformance-only change). No inline review threads to resolve (PR-level comments only).

Flipping to ready, handing off to the babysit lane for ongoing watch.

[claude]

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

---

Security Review — PR #886

• Gather context and identify changed files
• Read changed files and PR diff
• Review for injection, secrets, path traversal, GitHub Actions patterns, supply-chain risk
• Post findings

---

No security issues found.

This PR changes four files, all static documentation/JSON with no executable code paths.

File-by-file analysis

ruff-format.schema.json — Pure JSON Schema document. Not executed, not fetched at runtime by the hook scripts. The $id field references raw.githubusercontent.com/.../main/... (mutable branch pointer rather than pinned SHA), which is consistent with every sibling schema in the repo (markdown-format, typos-format, bash-format, etc.) and was already reviewed and accepted as a repo-wide convention. $id in JSON Schema is a URI identifier, not a required fetch target; validators that auto-resolve it will follow the same mutable-ref pattern already in use everywhere else. No finding raised.

README.md +1 line — One Markdown table row added to the Implementers table. No executable content, no injection surface.

plugin.json version bump — Patch semver 0.4.2 → 0.4.3. No new capabilities, permissions, hooks, or dependency pins introduced. userConfig is unchanged.

CHANGELOG.md — Changelog prose only.

Checks performed

Surface	Result
Command / path / template injection	None — no shell or template code in any changed file
Secrets / credentials	None
GitHub Actions patterns (pull_request_target, script injection via github context, permission widening)	No workflow files changed
Supply-chain risk (loosened or unpinned action/dependency pins)	No dependency pins changed
Authorization / access-control changes	None
New egress or trust delegation	None

[claude]

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

---

PR Review: docs(ruff-format): add hook-telemetry data schema + registry row

• Gather context and read changed files
• Review schema correctness and consistency with peer schemas
• Review README registry row
• Review plugin.json version bump and CHANGELOG
• Post findings

---

Schema correctness

docs/conventions/hook-telemetry/data/ruff-format.schema.json is accurate. Cross-referencing build_data_json in ruff-format.sh (lines 102–109):

jq -n \
  --arg tool "$TOOL" \
  --arg file "$FILE_REL" \
  --argjson findings "$1" \
  '{tool:$tool,file:$file,findings:$findings}'

All three required fields (tool, file, findings) are always emitted — including the fallback path {"tool":"","file":"","findings":[]}, so the required constraint is satisfied in every reachable code path. findings is always string[], built via jq -R . | jq -s . from ruff check --no-fix --output-format concise output, matching "items": { "type": "string" }.

Structural consistency with peers

The schema structure is an exact mirror of markdown-format.schema.json, which is the correct peer — both emit flat string[] diagnostic lines, not typos-format's structured {typo, corrections} objects. Field descriptions, additionalProperties: true, $schema draft declaration, and $id URI pattern are all consistent with the convention.

Registry row

The row in the Implementers table is correctly formatted. The hook value "ruff-format" matches the literal string in every emit_tel "ruff-format" call in the hook script. Insertion between typos-format and bash-format preserves add-order sequencing.

Version bump and CHANGELOG

Patch bump 0.4.2 → 0.4.3 is appropriate — conformance fix with no hook behavior change. The ### Fixed heading and entry text are accurate and consistent with the CHANGELOG's existing style (no release date, matching every prior entry). The entry correctly notes "No hook behavior change."

No issues found

This is a clean, scoped documentation/conformance fix. No correctness, security, or structural issues found. Looks good to merge.