fix(hooks): resolve PATH-dependent bare python3 false-deny (#1697, #1581)

[tvna]

Summary

Fixes a PATH-dependent bare python3 false-deny in
hooks/check-pr-skill-audit-disclosure.sh's precondition probe (issue
#1697, a regression from #1566/PR #1675) and extends the same
deterministic-interpreter fix to the other nine hooks/*.sh bare-python3
call sites, closing out #1581's own residual scope on this defect class.
Also hard-fails a durable gate that previously could not have caught
this.

Facts

• Live reproduction, before this PR (git worktree at pre-fix commit
  f274bda): piping a real create_pull_request-shaped PreToolUse
  payload into hooks/check-pr-skill-audit-disclosure.sh under this
  session's own ambient PATH (which has uv but not this checkout's own
  .venv/bin) denies with exit 2, "python3 cannot import: pydantic" --
  even though uv sync --group dev had already installed pydantic into
  .venv.
• Live reproduction, after this PR, same ambient PATH: the identical
  payload now allows with exit 0.
• Root cause, confirmed by direct inspection:
  hooks/check-pr-skill-audit-disclosure.sh invoked its precondition
  probe (hooks/gitapex_check_python_precondition.py) and its tier-1
  gate script as bare python3 "$var", which resolves from the calling
  PreToolUse hook's own ambient PATH rather than this checkout's
  uv-managed .venv. is_importable()'s own python argument
  additionally defaulted to the literal string "python3" (a second,
  independent PATH lookup), rather than sys.executable.
• Scope check on the other 9 hooks/*.sh bare-python3 call sites
  (issue gate-proposal: PATH-dependent bare python3 in check-pr-skill-audit-disclosure.sh's precondition probe blocks create_pull_request in some sessions #1697's own Facts section lists them): every script they invoke
  is stdlib-only (verified by reading each file's own top-level import
  statements) -- so this is a preventive/consistency fix for those nine,
  not a currently-observable-failure fix. Stated here as fact, not
  assumed.
• Fact-check on issue gate-proposal: retro #1576 repair 1: PATH-dependent pre-push hook interpreter #1581: its own stated target
  (.pre-commit-config.yaml's local-preflight entry) was already fixed
  by commit 7002c8965e104c60a0a2ff9806d3d6bb2aee149e (PR fix(hooks): route local-preflight through uv run, not bare python3 #1486, merged
  2026-08-29T23:54:26Z) -- roughly 22 hours before gate-proposal: retro #1576 repair 1: PATH-dependent pre-push hook interpreter #1581 was even filed
  (2026-08-30T21:40:02Z). Confirmed directly against the current
  .pre-commit-config.yaml and git log. See the comment left on gate-proposal: retro #1576 repair 1: PATH-dependent pre-push hook interpreter #1581
  for the full timeline. gate-proposal: retro #1576 repair 1: PATH-dependent pre-push hook interpreter #1581's own body never itself enumerated the
  nine other call sites this PR fixes -- those came from gate-proposal: PATH-dependent bare python3 in check-pr-skill-audit-disclosure.sh's precondition probe blocks create_pull_request in some sessions #1697's own
  Facts section.
• Durable-gate live proof: gitapex_gate_bare_python3_invocation.py
  previously WARNED (report-only) on a .github/scripts/*.py target and
  never inspected hooks/*.py targets at all. Run against a git-worktree
  checkout of the pre-fix hooks/ directory with this PR's own fixed
  .gitapex/ssot.json (which registers
  hooks/gitapex_check_python_precondition.py under the
  skill-audit-disclosure gate), the extended gate correctly flags all
  three original bare invocations in
  check-pr-skill-audit-disclosure.sh (precondition_script:255,
  full_gate:301, check_script:366) -- proving it would have caught this
  defect before merge.
• Full test suite: 8005 passed as of the current head (grew from 7994 at
  PR open as commits added new tests), 1 pre-existing failure unrelated
  to this change (test_repository_workflows_are_drift_free, caused by
  this session's own shallow git clone lacking full history for an
  unrelated harden-checkout pin-drift check -- confirmed via
  git rev-parse --is-shallow-repository = true).

Assumptions

• The nine other call sites' preventive fix is worth doing now rather
  than deferring (see Scope decision below) -- a judgment call, not a
  fact.
• A consumer plugin install of this repository (only skills/ is
  currently deployed, per docs/repository-layout.md, with hooks/
  deployment stated there as planned for a future release) genuinely
  carries no uv toolchain or lockfile; I did not test an actual
  consumer install, only inferred this from that doc and from
  hooks/check-issue-acm-disclosure.sh's own existing comment making the
  same claim.

Scope decision: all 10 call sites in one PR (not split with #1581)

Issue #1697 asked me to decide and state reasoning rather than pick
silently. Chose to fix all ten hooks/*.sh bare-python3 call sites in
this one PR, and to close out #1581 alongside #1697, because:

1. All ten are the same defect class (PATH-dependent interpreter
   resolution) -- fixing nine of them now, with the pattern and tests
   already built for the tenth, costs little extra.
2. Each of the nine gets a command -v uv + lockfile-gated fallback to
   bare python3 (not an unconditional uv run), so none of them can
   newly break a consumer plugin install that has no uv toolchain --
   the same fail-safe direction hooks/check-post-review-obligation-tracker.sh
   and hooks/check-stop-review-obligation.sh already use for a missing
   python3 itself.
3. gate-proposal: retro #1576 repair 1: PATH-dependent pre-push hook interpreter #1581's own stated target was already resolved by PR fix(hooks): route local-preflight through uv run, not bare python3 #1486 before
   gate-proposal: retro #1576 repair 1: PATH-dependent pre-push hook interpreter #1581 was even filed (see Facts) -- so gate-proposal: retro #1576 repair 1: PATH-dependent pre-push hook interpreter #1581's only remaining live
   value was the same defect-class awareness gate-proposal: PATH-dependent bare python3 in check-pr-skill-audit-disclosure.sh's precondition probe blocks create_pull_request in some sessions #1697 already carries
   forward. Closing it here avoids leaving a stale, already-resolved
   issue open indefinitely.

Risk / blast radius

• Primary fix (tier-1 block in check-pr-skill-audit-disclosure.sh):
  scoped to a block that only runs when .github/scripts/ is present
  (this repository's own dev checkout) -- never reaches a consumer
  install.
• The other 9 call sites + tier-2: each has a fallback to the
  pre-existing bare-python3 behavior when uv/lockfile are absent, so
  a consumer install with no uv toolchain is unaffected. If the fallback
  condition itself has a bug, the worst case is falling back to the
  pre-existing behavior (unchanged), not a new failure mode.
• Gate hard-fail promotion: could newly block a future PR that adds a
  bare-python3 hooks/*.sh call site of a .github/scripts/*.py or a
  registered third-party-dependent hooks/*.py target -- this is the
  intended effect (issue gate-proposal: PATH-dependent bare python3 in check-pr-skill-audit-disclosure.sh's precondition probe blocks create_pull_request in some sessions #1697 item 3).

Rollback

git revert the commits on this branch. No schema, data, or
external-service change; a plain revert restores the exact pre-PR
behavior (including the original bug in check-pr-skill-audit-disclosure.sh).

Verification

Restating issue #1697's own re-verified Acceptance Criteria Map:

Criterion	Interpretation	Planned ops	Proof method	Residual risk
check-pr-skill-audit-disclosure.sh's precondition probe resolves the same interpreter regardless of the calling context's own PATH	Change its python3 "$precondition_script" invocation (and the probe subprocess's own default inside gitapex_check_python_precondition.py) to uv run --frozen python3 (tier-1 gate invocation too), and default is_importable()'s own python argument to sys.executable instead of a fresh PATH lookup	Edited hooks/check-pr-skill-audit-disclosure.sh (tier-1 precondition-probe and full_gate invocations); edited is_importable()/find_missing_modules() in hooks/gitapex_check_python_precondition.py	Live reproduction via git worktree at the pre-fix commit: same ambient PATH, pre-fix denies (exit 2), post-fix allows (exit 0); plus new unit tests and the existing shell-level regression suite, all passing	A .venv that itself lacks the required package still correctly denies -- this fix narrows which interpreter is resolved, not the precondition's own pass/fail logic
Every other hooks/*.sh bare-python3 call site gets the same deterministic-interpreter treatment	uv run --frozen python3 when uv is on PATH and this checkout has its own pyproject.toml/uv.lock, falling back to bare python3 otherwise	Edited all nine remaining hooks/*.sh files plus check-pr-skill-audit-disclosure.sh's tier-2 call site, each with a command -v uv+lockfile-gated fallback	Existing shell-level regression suite passing; live-verified the fallback still exits 0 with uv removed from PATH on multiple hooks	All nine plus tier-2 are stdlib-only today, so this is a preventive/consistency fix, not a currently-observable-failure fix, for those -- disclosed here rather than left implicit
The precondition probe's own subprocess default (is_importable(..., python="python3")) is also fixed	Default to sys.executable, falling back to the literal "python3" only if sys.executable is itself empty (documented CPython edge case)	Edited is_importable()/find_missing_modules() signatures in hooks/gitapex_check_python_precondition.py	New unit tests intercepting subprocess.run's own argv to assert the default equals sys.executable, the empty-fallback, and that an explicit python= still overrides the default	None identified -- sys.executable is the process's own known-good interpreter path by construction

Commands run (re-verified against the current head):

uv run --frozen python3 -m pytest -q --no-cov          # 8005 passed, 1 pre-existing/unrelated
uv run --frozen ruff check .                            # All checks passed
uv run --frozen mypy                                    # Success: no issues found
uv run --frozen python3 .github/scripts/gitapex_gate_bare_python3_invocation.py   # exit 0

Skill audit evidence

• checker-script-adversarial-review: RAN -- against
  .github/scripts/gitapex_gate_bare_python3_invocation.py's own new
  load_python_dependent_hook_script_names/_scan_hook changes, across
  three rounds as findings surfaced (see Merge gate section below):
  decoy hooks/*.py names as both a substring-prefix and a
  substring-suffix of a registered target, the python3_cmd=(...)
  array-fallback shape confirmed NOT misdetected as a new bare
  invocation, a malformed/missing .gitapex/ssot.json, and a single
  malformed gates entry naming a real hooks/*.py target.
• deterministic-gate-quality: RAN -- iteratively, as the independent
  review below progressed, read against
  skills/evaluating-deterministic-gate-quality/references/dimensions.md
  with dimension 15 (fail-closed default) as the focus throughout. Two
  genuine dimension-15 violations were found and fixed during this PR's
  own lifecycle (see Merge gate section below for the full account)
  rather than merely disclosed as accepted risk.
• defeat-test-disclosure: RAN -- the defeat-case tests cited above are
  bundled in tests/test_gitapex_gate_bare_python3_invocation.py and
  tests/test_gitapex_gate_bare_python3_invocation_properties.py.

Checklist

• Tests pass locally
• Docs updated if behavior changed (no user-facing docs describe this internal hook wiring; an ADR was added -- see below)
• Issue number cited in every commit
• N/A: no SKILL.md/design-doc/security-relevant-skill change in this PR
• N/A: no evals/*/split.md change in this PR
• N/A: no SKILL.md Stop-boundary/branch change in this PR

Architecture decision record

docs/adr/0003-prefer-uv-resolved-python3-in-hooks-scripts.md -- retrofit
ADR recording this PR's own uv-preferred/bare-python3-fallback decision.
Approved by @tvna, 2026-09-03.

Merge gate: independent review

Outer layer (GitHub-native reviewer): requested
copilot-pull-request-reviewer[bot] via request_copilot_review twice
(once earlier in this PR's lifecycle, once against the current head) --
no review was returned either time within this session's own wait
window. The repository's other two configured checks, Devin Review
and CodeRabbit, both report as skipped by their own configuration
("trial expired and no credits remaining"; "manual review required for
this OSS repository"). This layer did not run.

Inner layer (reviewing-an-artifact, deferred at its own Step 0 to
evaluating-deterministic-gate-quality since this PR's diff is almost
entirely deterministic-gate/hook files, not ordinary application code):
run via a fresh, isolated subagent dispatch (no prior context on this
diff) across three rounds as the branch's head evolved:

• Round 1 (against commit faab3c1): found 2 confirmed defects in
  .github/scripts/gitapex_gate_bare_python3_invocation.py --
  (a) a dimension-15 fail-closed violation: load_python_dependent_hook_script_names
  silently degraded to "nothing registered" instead of failing closed on
  a missing/unreadable/malformed .gitapex/ssot.json, live-reproduced
  (a crafted malformed registry alongside a real bare invocation of a
  registered target produced a false "clean" exit 0); (b) a missing
  path-boundary anchor in the registered-target regex, letting an
  unregistered file whose name merely ends with a registered name as a
  substring false-positive. Both fixed and pushed.
• Round 2 (against commit f6bed27's predecessor, re-verifying both
  round-1 fixes live plus a full-diff re-review): confirmed both fixes
  hold in both directions, found a third, narrower mirror of finding
  (a) -- a single gates entry naming a hooks/*.py script but with a
  malformed preconditions/requires_python_packages field also
  silently skipped instead of failing closed, live-reproduced the same
  way. Fixed and pushed (commit f6bed27).
• Round 3 (re-verification against f6bed27 after the round-2 fix,
  plus an ADR factual-accuracy pass): confirmed the round-2 fix live in
  both directions (malformed shapes now return None/hard-fail;
  legitimate no-op shapes still correctly contribute nothing, no
  overcorrection), and found 3 factual errors in the newly-added ADR
  (docs/adr/0003) -- a stale "not yet fixed" Consequence describing an
  already-fixed bug, a 9-vs-10 call-site count inconsistency between two
  of the ADR's own sections, and a present-tense claim about hooks/
  deployment that docs/repository-layout.md (the doc the ADR itself
  cites) actually states as future/planned. All three corrected and
  pushed. This round's own verdict: "the gate code itself ... is now
  well-formed and well-placed for this defect class."

No further findings against the current head (commit 99ed17d). Per
drafting-a-pr-to-merge's own Step 8 disclosure requirement: this
recorded verdict is disclosure for a human reader, not a self-certifying
signal for an automated downstream consumer.

Independent review verdict

• Verdict: CLEAN
• Verified commit: 99ed17d

Related Issue

Closes #1697
Closes #1581

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: f729fc21-3466-489b-ba38-5ac4d0a88ad2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.66%. Comparing base (f274bda) to head (99ed17d).
⚠️ Report is 10 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1701   +/-   ##
=======================================
  Coverage   99.66%   99.66%           
=======================================
  Files         152      152           
  Lines       24725    24792   +67     
  Branches     2967     2981   +14     
=======================================
+ Hits        24643    24710   +67     
  Misses         82       82           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.