formatter hooks: content-mutation disclosure protocol is maintained by convention in each plugin, not by a module (deepening candidate)

[kyle-sexton]

Context

Six hooks (go-format, ruff-format, biome-format, bash-format, powershell-format, eol-normalizer) hand-write the same four-step protocol: snapshot to mktemp, cmp -s after the formatter runs, name the rewrite on the user channel, release the snapshot on every exit arm. The blocks are near-identical, differing only in variable prefix (_fmt_before, _go_before, _ps_before, _ruff_before, _biome_before, _eol_tmp).

Because the protocol lives in each plugin rather than behind one interface, the same defect recurs plugin by plugin. The rollout itself landed one plugin at a time (f5b8a3d bash, b3e9735 biome, 1b10069 powershell, 3c9351d eol-normalizer, b1b1c22 the rest), then #3401 (a7f9537) fixed powershell's leaked snapshot and undisclosed rewrite, while the identical leak sat unrepaired next door in go-format. Both remaining defect families were verified live on 2026-08-27 and are filed as #3405 (go-format snapshot leak on both error arms) and #3406 (ruff/biome/bash emitting two JSON documents on a rewrite-plus-findings run, against the single-document invariant documented at lib/hook-utils.sh:75-78).

Deletion test: concentrates. A future maintainer would rebuild this module substantially the same way; the protocol (snapshot lifetime, disclosure wording, single-document stdout composition) is exactly the knowledge that should live once. Two adapters exist naturally: the six production hooks and the test suite exercising every exit arm.

Proposed work

• Move the protocol behind one interface (vendored per ADR-0019 alongside the hook-utils cluster) that owns snapshot lifetime and single-document composition, so an exit arm cannot leak and a rewrite-plus-findings run cannot double-print by construction.
• Adopt it in the six hooks, closing go-format: _go_before snapshot temp file leaks on the syntax-error and tool-break arms #3405 and ruff/biome/bash-format: two JSON documents on stdout when one run both rewrites and reports findings #3406 in the process.
• One suite with a stub formatter and an isolated TMPDIR: on every exit arm the scratch is empty afterward (with a during-run probe so the assertion is not vacuous); a rewrite-plus-findings run puts exactly one JSON document on stdout carrying both channels; a no-op run stays silent.

Acceptance criteria

• The snapshot/disclose/release protocol has one implementation consumed by all six hooks.
• go-format: _go_before snapshot temp file leaks on the syntax-error and tool-break arms #3405 and ruff/biome/bash-format: two JSON documents on stdout when one run both rewrites and reports findings #3406 are closed by the adoption (or beforehand by point fixes that the module then locks in).
• Every exit arm of every adopting hook releases the snapshot, asserted once at the module's interface.
• A rewrite-plus-findings run emits exactly one JSON document in every adopting hook.

References

• plugins/{go,ruff,biome,bash,powershell}-format/hooks/*.sh, plugins/eol-normalizer/hooks/eol-normalizer.sh, lib/hook-utils.sh:75-78
• 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 (live defects), fix(powershell-format): release the _ps_before snapshot and disclose a rewrite on the tool-break arm #3401/powershell-format: _ps_before temp file leaks on the trust-gate and tool-break arms, and a rewrite is undisclosed on tool break #3366 (the powershell instance), rollout commits f5b8a3d, b3e9735, 1b10069, 3c9351d, b1b1c22
• Parent candidate: the shared formatter-hook prologue (filed separately, top recommendation); this protocol is its first natural slice.
• Found by the /architecture:improve deepening scan (2026-08-27); shallow-signal and both runtime claims reproduced before filing. Dependency category: local-substitutable. Recommendation: Strong.