guardrails: hardcoded-path-check false positives — repo-path branch flags all paths under home; percent-env interpolations flagged

[kyle-sexton]

Summary

guardrails hardcoded-path-check has two independent false-positive bugs that hard-deny
(exit 2) legitimate writes. Both were hit/confirmed this session while writing a machine-scoped
Windows helper script.

F1 (primary — root cause of the incident): repo-path branch flags every path under $HOME when the project dir is home

• lib/path-detection/hardcoded-path-patterns.sh:147-159 (repo-path branch) matches PROJECT_ROOT
  as a substring via grep -nFi, and per the comment at :144-146 it is never
  OS-context-suppressed.
• hooks/hardcoded-path-check.sh:110-117 resolves PROJECT_ROOT from CLAUDE_PROJECT_DIR.

When CLAUDE_PROJECT_DIR is an ancestor of the target — most acutely when it is the user's
home — every absolute path under home (AppData\..., Desktop\..., Documents\...) matches the
checkout-root literal and is blocked as a "leak." The scope pre-gate (:66-74) does not help: the
target is inside the "project," so the hook proceeds to deny.

Repro (confirmed by audit): session rooted at home; write any file whose body contains a real
absolute path under home → exit 2, "Machine-specific repo path detected." In this session that
blocked a Desktop .cmd that legitimately referenced a vhdx under AppData\Local\Docker\....

Suggested fix: gate the repo-path branch on PROJECT_ROOT being a real git checkout AND not
$HOME (nor a home-adjacent ancestor). That removes the false positive without loosening
leak-detection inside genuine repos. Keep existing DETECT test cases green.

F2 (independent): Windows env-var interpolations flagged as hardcoded

• lib/path-detection/machine-path-patterns.sh:40,43,47 — the negative char class [^/\\$<{~]+
  excludes $, <, {, ~ (so $HOME, ${...}, <placeholder> correctly break the match) but
  not %.

So a legitimately portable interpolation — a percent-env token (USERPROFILE, USERNAME,
LOCALAPPDATA) used as the user segment of a Windows user path — is matched as a hardcoded path.
The LOCALAPPDATA percent-form only survives by accident (it contains no Users/repos literal),
not by recognition.

Meta-confirmation: this very issue body was blocked on first write because an earlier draft
contained a percent-interpolated user path in a fenced example; it had to be reworded to file.
That is F2 reproducing live.

Suggested fix: add % to the excluded class, or add a grep -v exclusion stage for segments
that are %...% (or $env:...) tokens, mirroring the existing macOS exclusion stages.

Impact

On any session whose project dir is (or is under) the user's home, the hook blocks routine writes
of machine-scoped scripts (Desktop helpers, provisioning .cmd/.ps1, runbooks) that correctly use
absolute or percent-env paths. The documented escape hatches don't reach these cases (see the
companion enhancement issue).

Environment

guardrails@melodic-software 0.7.0, Claude Code 2.1.215, Windows 11, session cwd = user home.

[kyle-sexton]

Claimed by A1 burn lane (main-thread orchestrated). Both fixes per issue body (F1 repo-path branch gated on real-checkout-and-not-home; F2 percent-env token exclusion), DETECT cases kept green. PR to follow after #757 (guardrails 0.9.1) merges — version bump serialized behind it.

[kyle-sexton]

Split landing per the sync-manifest ownership seam:

• F1 (repo-path branch home-gate): PR fix(guardrails): gate hardcoded-path repo branch on real non-home checkout #759 (this repo) — hook + tests, guardrails 0.9.2.
• F2 (percent-env exclusion): fix(path-detection): exclude percent-env interpolations from Windows path bodies standards#219 — the pattern library is upstream-owned (distribution/sync-manifest.yml marks the guardrails copy managed); the fix distributes back here via the reviewed sync PR. The downstream copy was verified byte-identical to upstream before F1 shipped (no skew).

This issue stays open until the F2 sync materializes in plugins/guardrails/lib/path-detection/.

[kyle-sexton]

Closing per the ladder-climb roadmap standing lane (standards→plugins sync watch: F2 materialization → close #389). Both findings verified fixed in the live tree on main (3962e8f):

• F1: repo-path branch now gated on the enclosing checkout not being home nor a home ancestor — plugins/guardrails/hooks/hardcoded-path-check.sh:130-141 (native-Windows %USERPROFILE% fallback included; missing home leaves the branch active, failing toward detection).
• F2: machine-path negative char classes now exclude % — plugins/guardrails/lib/path-detection/machine-path-patterns.sh:40-43 ([^/\$%<{~]+), so %LOCALAPPDATA%-style interpolations no longer flag.