guardrails: hardcoded-path-check — Windows-aware remediation, inline opt-out for machine-scoped files, document gitignore limitation

[kyle-sexton]

Summary

Enhancements for guardrails hardcoded-path-check surfaced by a real incident (see the companion
bug issue for the false-positive root causes). Even once the false positives are fixed, the hook
leaves a legitimately machine-scoped write with no good workaround and wrong remediation
guidance on Windows.

F3 — Windows-aware remediation guidance

hooks/hardcoded-path-check.sh:155-156 prints Unix-only alternatives (~/, $HOME, $(pwd),
$TMPDIR, git rev-parse --show-toplevel) which are syntactically wrong inside a .cmd/.ps1.
Detection advertises cross-platform; guidance is not.

Fix: when the file context is Windows (extension/path already computed in the lib), surface
Windows equivalents — %LOCALAPPDATA%, %USERPROFILE%, %APPDATA%, or PowerShell
$env:LOCALAPPDATA.

F4 — Granular opt-out for legitimately machine-scoped files

Today the only opt-outs are (a) gitignore the file, (b) the whole-hook kill switch
hardcoded_path_check_enabled=false, (c) OS-context suppression that covers the OS blocks but
not the repo-path branch. None reach an out-of-repo machine-scoped file. Contrast
block-dangerous-git.sh, which ships a per-form allow token, and secret-pattern-detection.sh,
which ships a file allowlist.

Fix: add a granular seam — a recognized inline pragma (e.g. guardrails: allow-hardcoded-path)
and/or a machine-scoped-file convention (treat .cmd/.ps1/scripts/windows/… as also suppressing
the repo-path branch when the path is under $HOME but outside any repo). Prefer warn-over-deny for
that class of file.

F5 — Document the gitignore-hatch limitation

README.md:99-110 presents gitignore as the machine-local escape hatch, but that hatch is
structurally unavailable for files outside any repo (Desktop scripts, provisioning scripts,
runbooks): git check-ignore errors and the guard proceeds. Either document this limitation or
close it via F4.

Context

Surfaced while writing a machine-scoped Docker-vhdx compaction helper .cmd to the Desktop; the
cat > file redirection fallback is itself blocked by sibling block-hook-bypass.sh, so there was
no in-band way to proceed — the write had to be reshaped to dodge the detector.