refactor(tools): move script hygiene checks to Go #809

Problem

Script hygiene is still enforced by shell discovery, textual checks and structural-checker result handling. The boundaries are tools/check-script-hygiene.sh:56, tools/check-script-hygiene.sh:92, tools/check-script-hygiene.sh:112 and tools/check-script-hygiene.sh:137, on origin/main at a0347a715fab580ece45edfcb3d13509620459a8. Discovery and diagnostic-processing failures already have regression coverage and must not become a clean gate during the port.

This is the script-hygiene split of #332. Part of #588.

Acceptance criteria

1. AC1: Default discovery checks the frozen command's owned scripts and local-only skill scripts, including nonignored untracked files and excluding duplicate deployed mirrors.
2. AC2: Explicit-file checks preserve the frozen command's file selection, missing-file skips and reasoned hygiene-exemption behavior.
3. AC3: Each checked script receives the same locale-pin and GitHub-retargeting findings as the frozen command.
4. AC4: Structural findings retain the current rule decisions, path, one-based line, rule ID and message.
5. AC5: Findings retain the frozen command's ordering, formatting, total and exit status, with silence on a clean run.
6. AC6: Failed discovery, an unusable structural-checker result or failed diagnostic processing produces failure rather than a clean verdict, including when partial output was returned.
7. AC7: Non-functional: running the hygiene check changes no repository content or Git state.
8. AC8: Existing entry points end as thin shell wrappers that probe the Go subcommand without side effects and use frozen shell only when that capability is absent.
9. AC9: A supported Go failure never invokes shell fallback or repeats a check to obtain success.
10. AC10: Non-functional: release N-2 invocations retain their findings and behavior without requiring configuration changes or a raised binary floor.
11. AC11: Equivalent inputs produce the same diagnostics on supported Linux, macOS and Windows environments.

Scope and non-goals

Preserve both default discovery sets, explicit targets, non-file skips and the whole-file hygiene-exempt opt-out (tools/check-script-hygiene.sh:62, tools/check-script-hygiene.sh:75, tools/check-script-hygiene.sh:93). Preserve the existing comment filtering and textual command detection, including what the current unset predicate actually recognizes (tools/check-script-hygiene.sh:103, tools/check-script-hygiene.sh:121).

Preserve the existing structural rules: bare Git output commands (.ast-grep/rules/bare-git-output.yml:14), diff without its required flag (.ast-grep/rules/diff-without-no-ext-diff.yml:10), and newline-losing field-separator construction (.ast-grep/rules/ifs-command-substitution.yml:15). Preserve checker statuses 0/1 as ordinary outcomes and statuses above 1 as tool failures with diagnostics; retain file/line sorting and literal message characters (tools/check-script-hygiene.sh:150, tools/check-script-hygiene.sh:160).

The existing failure coverage is tests/tools/masked-status.bats:98. Add the rule and discovery fixtures that this suite does not currently provide.

Non-goals: changing exemptions, adding or weakening rules, replacing the structural rules' semantics, broadening the scripts being checked, or porting unrelated cases in the shared masked-status suite. The fallback remains until a separate D9 follow-up establishes N-2 retirement eligibility.

Approach

Write the discovery and diagnostic-failure regressions first. Move the gate behavior to Go, comparing findings and failure transcripts with the frozen shell over the same fixtures. Keep the existing lint task (mise.toml:442). No new checker design or library is prescribed.

Dependencies

None blocking. The probe-and-fallback wrappers let this split land without waiting for #542, the #333 → #544 → #382 → #545 → #546 chain or the #359 delivery chain. Removing the fallback later waits for #333, #544 and the N-2 window, and is filed as a follow-up. Script hygiene is repository lint tooling, not merge, commit or pull request enforcement, so it does not wait for #753. #332 and #588 track this migration.

Size

S. One pull request for a single gate, its compatibility wrappers and rule-parity coverage.

Verify plan

• AC6: first reproduce both discovery failures and the diagnostic-parser failure at tests/tools/masked-status.bats:98. Add checker startup/configuration failure, malformed diagnostics and partial output followed by nonzero status; assert failure, diagnostic preservation and no clean result. Check that ordinary checker status 1 still yields findings rather than a tool-failure report.
• AC1: fixtures cover packaged scripts, local-only skills, deployed mirrors, tracked and nonignored untracked scripts and ignored files; compare the selected files with frozen shell.
• AC2: explicit targets include a missing file, an ordinary file, and a reasoned exemption; assert that exempt files reach neither rule pass, while nonexempt files without Git/GitHub calls still reach structural checks.
• AC3: shell/Go transcript comparisons cover comments, quoted command text, Git-only scripts, GitHub calls, absent/present locale pins and absent/present unset lines, preserving the current predicates rather than assuming stronger rules.
• AC4: positive and negative fixtures for each of the three structural rules compare rule decisions, literal messages and line numbers, including quoted flag text versus a real argument and harmless field-separator assignment.
• AC5: mixed textual/structural findings across several files compare full stdout, stderr, order, totals and status; a clean fixture is silent.
• AC7: filesystem, index and ref snapshots are unchanged after successful and failed checks; use mutation traps for subprocesses.
• AC8: absent binary and older binary without the capability run the frozen command once with unchanged arguments; verify the capability probe is read-only.
• AC9: supported-command failure, partial-output failure and an indeterminate capability probe all refuse without shell fallback or repetition.
• AC10: run unchanged tasks and direct entry points over the N-2 corpus with absent, older and new binaries; compare findings, streams and statuses.
• AC11: run the Go corpus on Linux, macOS and Windows, retaining wrapper smoke coverage where Bash is supported. Run focused suites, mise run lint and mise run test on the reviewed head.
• Definition of done: D1 each AC is verified at the merged head, with the commands and results cited in the pull request's Verification. D2 an independent review approves the exact merged head, and every finding has a recorded disposition. D3 required checks pass with no gate loosened. D4 the leak scans the repository specifies are clean, and every post made for this work (comments, descriptions) passes the per-post leak review before it is posted. D5 every commit is signed. D6 the documentation matches, or the description says No doc impact with the reason. D7 every commit carries an Assisted-by trailer and the pull request carries the provenance:agent-assisted label. D8 the change stays within the pull request size limits. D9 follow-up work, including deferred review findings, is filed as issues, each with a Problem section and numbered acceptance criteria and linking this issue; the pull request's Related section lists them, and any code that defers work links its issue. D10 the merge closes this issue through a closing reference, the project board shows the state Done, and a final Status: comment names the merge commit.

Risks

A discovery omission can hide an unchecked script; a swallowed checker error can report false success. Broader text interpretation can also change current rule decisions. File-selection, rule-parity and failure-first evidence cover these risks. Undo: revert the port.

Operator authority

None.