refactor(leaks): port working-tree and explicit-file scans to Go #815

Problem

Part of #588. This is the working-tree and explicit-file slice of #329.

At origin/main (a0347a715fab580ece45edfcb3d13509620459a8), private-list parsing and matching remain shell (.devtools/scripts/check-leaks.sh:97, .devtools/scripts/check-leaks.sh:134), as do working-tree selection (.devtools/scripts/check-leaks.sh:289) and skip policy (.devtools/scripts/leak-skip.sh:4). Move this complete user-visible scan boundary to tested Go without changing which values or files it checks.

Acceptance criteria

1. AC1: Every exported *_PRIVATE_STRINGS list retains its current matching results, entry labels and warnings, including comma separation, trimming, case handling, empty entries and entries shorter than four characters.
2. AC2: Built-in and repository pattern checks retain their current matches and rule labels, including address boundaries, documentation-domain exceptions and accepted expression semantics.
3. AC3: Path allowances suppress patterns only; private literals remain detectable, and the built-in exception for the shipped leak test remains limited to that exact path.
4. AC4: A no-argument scan checks tracked and non-ignored untracked working-tree files from the repository root, including binary bytes, link targets as text and paths, with the same selection and results as the frozen shell.
5. AC5: Working-tree skip expressions exclude matching paths before their content is opened, and invalid or unanchored expressions fail with status 2 without disclosing the expression.
6. AC6: Explicit file arguments check exactly the supplied files with the frozen shell's current-directory semantics, including invocation outside a repository; missing or unreadable inputs never pass.
7. AC7: Findings retain their stdout location-and-rule format and stderr summary; sensitive locations retain opaque identifiers, and matched values, sensitive arguments and malformed configuration never appear on either stream.
8. AC8: The result remains 0 for complete clean scans, 1 for findings and 2 for misuse or incomplete reads.
9. AC9: Non-functional: existing consumer entry points end as thin shell wrappers that probe Go subcommand support without writes or consuming input; absent binary or capability uses the frozen shell unchanged, while supported execution runs once and preserves its streams and status without fallback after failure.
10. AC10: Non-functional: the migrated behavior works on Linux, macOS and Windows without new consumer configuration or a higher minimum binary version.
11. AC11: Non-functional: no temporary matched content remains after success or failure.
12. AC12: When no private literals are loaded, the current notice is retained, including its existing local-file hint and GitHub Actions annotation.

Scope and non-goals

In scope: matching, configuration and diagnostics used by these two modes, their task entry points, corresponding Go and wrapper coverage, and consumer help and adoption documentation for their unchanged source, limitations, fallback and rollback. Evidence includes .devtools/scripts/check-leaks.sh:87, .devtools/scripts/check-leaks.sh:99, .devtools/scripts/check-leaks.sh:189, .devtools/scripts/check-leaks.sh:249, .devtools/scripts/check-leaks.sh:808, .devtools/scripts/check-leaks.sh:828 and .devtools/tasks/leaks.toml:2.

Behavior coverage: .devtools/scripts/check-leaks.bats:70 through the configuration and file cases at .devtools/scripts/check-leaks.bats:466; path, disclosure, task-argument and read-failure cases at .devtools/scripts/check-leaks.bats:516, .devtools/scripts/check-leaks.bats:554, .devtools/scripts/check-leaks.bats:606, .devtools/scripts/check-leaks.bats:644, .devtools/scripts/check-leaks.bats:699, .devtools/scripts/check-leaks.bats:709, .devtools/scripts/check-leaks.bats:1429 and .devtools/scripts/check-leaks.bats:1464; skip and basename cases at .devtools/scripts/check-leaks.bats:1508.

Overlap: AC1 and AC12 absorb the exported-list and no-list behavior retained by #501. Its new source discovery, precedence, configured-source refusal and source notices remain in #501, including its provisioning documentation and operator provisioning. This port does not claim to fix or close #501. No #551 scan-selection requirement is absorbed: AC7 preserves private-scanner disclosure behavior only; #551's gitleaks modes, callers and coverage decision stay there.

Non-goals: staged, range, publication and push producers, hook installation and gitleaks orchestration; broadening detection to transformed or split values, comma-containing entries or literals shorter than four characters; recursive submodule scanning. These are the existing detection boundaries at .devtools/scripts/check-leaks.sh:53 and .devtools/scripts/check-leaks.sh:289. Other scan modes retain their frozen behavior. Removing the compatibility fallback is deferred until the N-2 window permits it, with a dedicated follow-up under D9.

Approach

Move the scoped behavior to tested Go, with failing cases first. The mechanism is the implementer's choice within these outcomes. Preserve the shell as a frozen compatibility path; add no new scanning logic to it.

Dependencies

Blocked by #753 before activating replacement enforcement; the implementation PR must cite its merged protection evidence. #329 tracks the containing migration. #501 and #551 retain the exclusions stated above. #661 governs N-2 compatibility; #333 supplies binary distribution without making it a new consumer prerequisite.

Size

M. One pull request for two scan modes and their shared matching contract.

Verify plan

Start with failing Go tests for an omitted file, a disclosed sensitive location and an incomplete read; then port every scoped Bats behavior before reducing its shell coverage.

• AC1: table cases for multiple exported lists in discovery order, whitespace, empty and short entries, mixed ASCII case and non-ASCII bytes; compare results, entry numbering, warnings and streams with the pinned shell.
• AC2, AC3: positive and boundary-negative cases for every built-in category, repository expressions and invalid expressions; test the exact built-in exception, allowed versus ordinary paths and literals under both. Compare frozen results, including expression case semantics.
• AC4, AC5: tracked, untracked, ignored and deleted files; binary and empty files; symlinks without following their targets; paths with spaces, tabs, newlines and backslashes; a nested invocation; and skipped unreadable content. Invalid skip fixtures must return 2 without expression bytes.
• AC6: several explicit files, relative and absolute file arguments, a spaced filename, an unrelated leaky file that must remain unchecked, a missing or unreadable file, a directory, symlinks to readable and missing targets, and execution outside Git; compare selection, status and streams. Explicit symlink arguments retain their existing target-content behavior, distinct from tree mode's link-text scan. Confirm skip configuration is not consulted for explicit files.
• AC7, AC8: compare stdout and stderr separately for clean, finding, misuse and injected read/configuration/discovery failures, including partial producer output. Search both streams for every synthetic private value and escaped form.
• AC12: exercise absent, empty and short-only lists, with and without the local settings file and Actions annotation environment; compare each notice and stream with the frozen shell.
• AC9: actual task and script entry points with missing binary, older binary lacking capability, supported success, findings, and output-then-failure. Assert probe side effects are absent, one execution, exact argument boundaries and no fallback after supported execution. An operational probe failure must refuse rather than claim absent capability. Unmigrated modes must retain their frozen transcript.
• AC10: native Go tests on Linux, macOS and Windows; shell comparisons where Bash is available; unchanged N-2 consumer fixtures. Record before/after process timings over the same fixed 100-file fixture, with 20 warm runs and build time excluded; investigate any regression before acceptance.
• AC11: inspect the fixture temporary area after clean scans, findings and each injected failure; no matched content may remain. As D6 evidence, compare help/adoption text with the actual entry points and verify the documented rollback in a disposable fixture.
• Run the branch binary through mise run test-leaks, then mise run check, fresh Go and Python coverage and mise run cover-go-check and mise run cover-py-check. Verify build(agents): protect replacement Go enforcement paths #753's protection applies to the replacement enforcement and command registration. Any changed skill sources require ordered generation, token measurement, deployment and mise run check-generated-skills.
• 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 changed expression dialect or path allowance can weaken scanning. Differential cases must preserve accepted configuration, including quirks. The fallback deliberately retains #501's present limitation for older binaries. Undo: revert this PR to restore the original entry points and frozen behavior.

Operator authority

standing rule names the operator: the replacement enforcement must have #753's protection before activation; satisfy its exact-head owner-review requirements without changing approval authority.