formatter hooks: nine siblings duplicate the PostToolUse prologue as structure the drift gate cannot see (deepening candidate, top recommendation)

[kyle-sexton]

Context

Nine sibling hooks (go-format, ruff-format, biome-format, bash-format, powershell-format, markdown-format, typos-format, eol-normalizer, actionlint) each re-implement the same PostToolUse prologue: kill-switch, EPOCHREALTIME guard, telemetry emit, stdin buffer (bare cat, never </dev/stdin>), jq-free pre-filter, require_jq, repo-root plus cygpath FILE_REL normalization, build_data_json, emit_skipped. One conceptual change to that prologue costs nine edits with no locality and no gate.

Measured (scan, 2026-08-27): normalized (comments stripped, plugin name tokenized), go/ruff/biome/bash/powershell share 45 code lines, go/ruff/biome share 61, out of 133/142/139 total non-comment lines, i.e. roughly 46% of go-format's code is shared skeleton. The EPOCHREALTIME guard and the fd0 comment appear in 9 of 9 hooks (reproduced by grep before filing).

ADR 0019's drift mechanism cannot reach this: scripts/check-cross-plugin-source-drift.sh clusters by whole-file byte identity at the same path-within-plugin, and scripts/cross-plugin-source-registry.txt lists 5 clusters, none of which can cover a prologue interleaved inside files that legitimately differ. Nothing detects its drift, and the fix history shows the cost: the same class of fix lands one plugin at a time (#3401 powershell, #3394 go-format telemetry, #3405/#3406 still open).

This was the scan's top recommendation because three sibling candidates are facets of the same missing module: the mutation-disclosure protocol (filed separately, with live defects #3405 and #3406), the envelope-schema check, and the triple applicability test.

Proposed work

• Extract the prologue into one vendored module using the existing ADR-0019 cluster mechanism (canonical file, sync script, drift-gate registry entry), so each hook keeps only formatter-specific behavior behind the shared interface. Vendored copies keep per-run cost unchanged, honoring .claude/rules/hook-budget.md.
• One suite over a fake formatter on PATH asserting the prologue contract once: non-matching extension produces no jq notice and no telemetry; jq absent produces exactly one skip notice; EPOCHREALTIME unset still formats and emits no envelope; unwired HOOK_TELEMETRY_SINK spawns zero telemetry-only subprocesses; data.file is repo-relative under both POSIX and a cygpath-shaped root.

Acceptance criteria

• The shared prologue lives in one canonical file registered in cross-plugin-source-registry.txt and synced by the ADR-0019 mechanism.
• Each of the nine hooks consumes the vendored prologue; formatter-specific code remains per plugin.
• The prologue contract is asserted by one suite instead of nine partial transcriptions.
• Hook latency budget is unchanged (no extra subprocess or file sourced at runtime beyond the vendored copy).

References

• plugins/{go,ruff,biome,bash,powershell,markdown,typos}-format/hooks/*.sh, plugins/eol-normalizer/hooks/eol-normalizer.sh, plugins/actionlint/hooks/actionlint-check.sh
• scripts/check-cross-plugin-source-drift.sh, scripts/cross-plugin-source-registry.txt, docs/adr/0019-share-code-across-plugins-by-vendoring-with-a-sync-gate.md, .claude/rules/hook-budget.md
• Sibling candidates: mutation-disclosure protocol, envelope schema check, triple applicability (filed separately); live defects go-format: _go_before snapshot temp file leaks on the syntax-error and tool-break arms #3405, ruff/biome/bash-format: two JSON documents on stdout when one run both rewrites and reports findings #3406
• Found by the /architecture:improve deepening scan (2026-08-27); shallow-signal reproduced before filing. Dependency category: local-substitutable. Recommendation: Strong.

[kyle-sexton]

This was generated by AI during triage.

Claimed for triage by autonomous lane instance vm-triage-202609050304. Lease expires 2026-09-06T20:15:00Z. Triage claim only, not an execution claim.

---

Generated by Claude Code

[kyle-sexton]

This was generated by AI during triage.

Triage verdict

Category: Task. State: briefed → human-gated, as the decision carrier for a three-issue cluster. Work class: structural. Priority: medium.

Cluster members: #3410 (envelope-schema check), #3411 (applicability filters). A native blocking edge from #3410 to this issue has been created. #3411 was deliberately left unblocked; see below.

Re-verification against current main (2026-09-06)

The issue was filed 2026-08-27. Ten days on, the premise has moved substantially and the brief in the body is now partly stale. Re-checked rather than assumed:

What has already landed. A shared hook::-namespaced library now exists, is vendored per plugin under the ADR-0019 mechanism, and is registered in the drift registry with its own dedicated sync check. It already provides essentially every primitive the body asks to extract: the enablement check, jq requirement, stdin buffering, raw and parsed file-path extraction, repo-root discovery, repo-relative path normalization, and skip-notice emission. The body's framing, that these need extracting, is no longer accurate.

What is still true, and is the real remaining defect. The primitives are shared; the composition is not. Reading a representative formatter hook on current main, the prologue is still a hand-written sequence of the same shared calls in the same order, plus per-hook copies of the telemetry-emit wrapper, the data-payload builder, and the skip emitter. So the duplication has moved up a level rather than disappearing: the nine hooks no longer duplicate the implementations, they duplicate the order and wiring. One conceptual change to the prologue still costs nine edits, and the drift gate still cannot see it, because it clusters on whole-file byte identity and this is an interleaved sequence inside files that legitimately differ.

That is a narrower and better-posed problem than the one filed, and whoever takes it should re-scope to it rather than working from the body's line counts, which no longer hold.

Why human-gated: this is the cluster's one open decision

Three issues turn on a single question the body itself identifies, and it is genuinely open design space rather than a defaulted choice:

Where does composed shared behavior live, and in what form? The candidates each carry a real cost:

• A shared prologue entry point in the vendored library, which hooks call once. Deepest, but it inverts control: the hook becomes a callback, and the library grows knowledge of the formatter contract.
• A shared prologue fragment the hooks source and continue past. Preserves the straight-line readability of the current hooks, but shared code that assigns into the caller's scope is its own hazard.
• Leave the composition duplicated and instead make it visible to a gate, so drift is caught even though it is not eliminated. Cheapest, and it directly addresses the stated harm (nothing detects the drift) without restructuring nine hot-path hooks.

The third option deserves serious weight and is the reason this is not decision-defaulted. The stated cost is undetected drift, not the duplication itself, and the hook-budget rule constrains anything that adds per-run work. A gate that reads the prologue's shape would close the actual gap at a fraction of the risk.

The same decision governs #3410 (a shared schema-driven envelope check consumed by ten-plus suites, which must be reconciled with the shell-test-helpers convention on where shared test code may live) and constrains part of #3411. Resolving it once here resolves all three, which is why they are clustered rather than gated individually.

Why #3411 was left unblocked

Most of #3411 has already landed independently, and what remains splits cleanly: two plugins still lack declarative manifest filters and one still snapshots before deciding applicability, none of which depends on this decision. It has been routed as autonomous-eligible for that remainder, with its in-script deduplication explicitly deferred here. Blocking it wholesale would have parked shippable work behind an unmade decision.

What resolving this looks like

A comment on this issue naming the chosen form and the reason, at which point #3410 unblocks and this issue itself becomes an ordinary briefed refactor. The scan's own recommendation was Strong, but it was made against the pre-vendoring codebase; weigh it accordingly.

Out of scope

• Re-litigating ADR-0019 itself.
• The live per-plugin defects the body references; those are their own items.
• Any change that adds runtime cost to the hook path, which the budget rule forecloses independently of this decision.

Triage claim released by vm-triage-202609050304.

---

Generated by Claude Code

[kyle-sexton]

This was generated by AI during triage.

Cross-reference: add #3412 to this issue's decision cluster

The triage comment above scopes the cluster as #3410 (envelope-schema check) and #3411 (applicability filters), with this issue as the decision carrier. #3412 belongs in the same cluster and is currently linked only in one direction.

#3412 ("make_sink/wait_for_sink is one drifted helper across 13 suites, contradicting the shell-test-helpers premise") already names this issue and says so from its side: its triage comment concludes that "a single ruling on 'how shared shell test code is owned in this repo' would settle all four, and #3412 is the natural carrier for it." Nothing on this issue points back, so a reader arriving here sees a three-issue cluster rather than a four-issue one.

Why it is the same decision. #3412 asks exactly the question this issue is gated on, one layer over: where composed shared shell behavior lives, and in what form. Its re-measurement found the repo has already answered it twice in practice, with plugin-local *-test-helpers.sh libraries in guardrails and claude-ops, which is direct evidence bearing on the three options enumerated in the triage comment above. It also carries a conflict this issue does not: docs/conventions/shell-test-helpers/README.md declines consolidation on a factual premise that has since gone from 3 shapes to 6 across 13 suites growing to 34.

Recommendation: sequence the four as one effort, or give them a shared container. The natural shape is one ruling on shared-shell-code ownership recorded here, which unblocks #3410, releases the deferred item 2 of #3411, and settles #3412's convention amendment in the same pass. Doing them separately risks three different answers to one question, which is how the repo arrived at 6 variants of a 20-line helper.

Two caveats a decider should keep, both already recorded on the individual issues: #3411's items 1, 3 and 4 are shippable today and should not be parked behind this, and #3412 asks to overturn a written convention, which stays a human call regardless of how the ruling here goes.

No labels, state, or links were changed by this pass. The back-links on #3411 and #3412 already exist and were not duplicated.

---

Generated by Claude Code