fix(hook): consult the credential floor when the python scanner cannot run

[KbWen]

What this fixes

The opt-in pre-commit credential pre-screen could let a staged secret reach object
history while reporting success. Two independent states, both reproduced end-to-end
on a fresh deploy.sh target with a staged PEM private-key header:

host state	pre-fix	post-fix
real python	blocked	blocked
no python at all	blocked (floor)	blocked (floor)
python on PATH that cannot start	could not run (exit 49); continuing → commit landed	blocked, via the probe
python fine, scanner returns rc=3	could not run (exit 3); continuing, validator green → commit landed	blocked, via the floor fallback

In both landing cases git show HEAD:leak.txt returned the header afterwards.

Root cause is a fix that was applied to two of three call sites. Backlog #144 replaced
existence-only interpreter selection with a startability probe in validate.sh and
validate.ps1; the hook is the third site and was never swept. validate.sh:292-301
names the hazard in its own words — the stock-Windows App Execution Alias exists on
PATH with no Python installed. Separately, the hook turned every non-0/1 scanner exit
into "continuing", so the deployed python-free floor — present, executable, and the
control ADR-008 designated canonical — was never consulted.

Why this is conformance, not a contract change

ADR-008's Alternatives Considered records (A) shell+PS regex canonical + .py optional [CHOSEN], and its tier ledger reads "the shell/PS regex floor blocks before object
history with no Python dependency; .py enriches when present." AC-S4 says the
floor "Replaces the Python-gated screen". The shipped hook inverted that: python
gated, and on failure the canonical control was skipped entirely. dev-flow-hardening
AC-8 — titled "Credential floor cannot fail open silently" — allows a WARN "only when
the native credential floor still ran". It did not. No ADR or spec amendment is needed;
this delivers what both already say. The same repo already applies the correct policy in
CI: security.yml:164-171, "an execution error is NOT a clean scan — fail closed".

A live downstream break, found on the way

While reproducing the fallback's blast radius, a pre-existing adopter break surfaced.
A no-Python adopter following the deploy banner's own instructions verbatim — install
the hook, then the banner's own git add .agentcortex-manifest AGENTS.md ... .agentcortex/ ... —
had their first framework commit blocked and was told to rotate a secret out of
.agentcortex/tools/scan_credentials.py, a core-tier file the framework had just
force-written. The flagged line is the docstring that documents the allowlist escape
hatch, citing AWS's public example key. Exactly one line matched across the 169-file
staged set. The file's own fixtures already avoid this by concatenation; the prose never
applied the file's own convention. Fixed by abbreviating the shape in the two prose
lines. Measured on the identical path: COMMIT_EXIT=1 before, COMMIT_EXIT=0 after.

The deeper asymmetry behind it is not fixed here and is filed as #195: the floor
reads whole staged blobs while the scanner reads only added lines, the scanner
self-excludes two files and the floor excludes none, and their allowlist checks differ
in case sensitivity. Narrowing the floor would contradict AC-S4's per-staged-file and
the deliberate anti-false-negative reason recorded for it, so it needs a spec decision,
not a patch. The hook's header comment now states the fallback is broader, not a drop-in.

What the review caught

A fresh-context reviewer returned NOT READY on the first round and proved each
finding with a mutant rather than asserting it: with the probe deleted but the fallback
kept, the suite still passed 6/6; with the fallback hardcoded to block, it also passed
6/6. Neither half was pinned. The tests now assert the discriminators the hook already
prints, and each half is independently mutation-verified:

mutant	result
probe deleted, fallback kept	1 failed
fallback deleted, probe kept	2 failed
fallback always blocks	2 failed
reduced-assurance line removed	1 failed
example key reintroduced at scan_credentials.py:79	1 failed
clean	8 + 6 passed

A second round found a regression this change introduced, and it is the most useful
thing the review produced. The floor screens 3 credential shapes; the scanner screens 7.
Measured on one staged file: scanner exit 1 with 4 findings (google / slack / openai /
github-pat), floor exit 0. So on the fallback path a clean floor is not a clean
scan -- and the first version of this fix printed "falling back to the no-python floor"
and then went silent, which reads as clean. The old code said "could not run; continuing",
which was honest. On the very path this diff adds, the fix was quieter than what it
replaced, inverting the AC-8 invariant its own new header cites. It now prints an explicit
REDUCED ASSURANCE line when the fallback's floor comes back clean.

A guard was also missing under all of this. test_credential_floor_shell.py's own
docstring promised "no full literal sits in the repo" and had no verifier -- and the
promise was already broken, which is exactly what blocked the adopter above. A new test
runs the floor's own parsed patterns (never a second matcher -- #165 forbids that) over
every tracked file. Reintroducing the shape turns it red; removing it turns it green.

A roundtable seat proposed a smaller remedy — delete the interpreter gate, run the floor
unconditionally — on the strength of AC-S4's "canonical". It was refuted by
measurement: staging the two files the scanner self-excludes gives floor exit 1 and
scanner exit 0, so floor-first-always would block every commit touching the credential
controls on a working-python host, including this PR.

Adopter delta

deploy.sh:283-290 updates an unmodified .sample and sidecars a modified one to
.acx-incoming with merge instructions. But .githooks/pre-commit is a copy the user
made; deploy.sh never writes it. Protection arrives only after an adopter re-runs the
INSTALL copy — filed as #197, since the population this fix exists for is exactly the
population that does not automatically receive it. The scan_credentials.py prose fix is
core tier and force-updates, so the first-commit break above is closed on next deploy
regardless.

Also filed: #196, credential_floor.ps1 ships core-tier with zero runtime callers —
AC-S6 parity-tests the two floors against each other, which proves the twins agree but
never that either is reached.

Not done, deliberately

No CHANGELOG entry: every section is a released version with a release narrative and
there is no Unreleased convention; inventing one is a governance-surface change needing
its own justification. The record goes to SSoT Ship History at ship time.

Evidence

• pytest tests/ci/ tests/guard/ .agentcortex/tests/ -q (CI's own paths): 947 collected, 946 passed, 1 skipped, exit 0.
• bash .agentcortex/bin/validate.sh un-piped: pass=115 warn=7 fail=0 skip=2, exit 0.
• Downstream simulation on fresh deploy.sh targets throughout — the two landing commits above, the four post-fix arms, the benign controls on all four PATH states, and the no-Python adopter's first framework commit before and after.

One judgement call worth flagging

The REDUCED ASSURANCE line quotes concrete counts ("3 credential shapes" / "7"). The
simpler option was vaguer prose with no number to keep honest. The numbers were kept
because "3 vs 7" tells an operator how much the fallback actually gives up, and a test
now pins both to the two tools' own sources — an enforced claim rather than a decaying
one. Reviewers who disagree should say so; dropping the numbers also drops that test.

🤖 Generated with Claude Code