feat(guardrails): add a PowerShell guard differential; refuse at the budget cap

[kyle-sexton]

Problem

The PowerShell classifier (plugins/guardrails/lib/powershell/ps-command.sh) and the five blocking guards that consume it have no committed way to prove a change never allows what main refuses. The #4303 lane's quote-walk rewrite went green on every suite round and was still withdrawn after four adversarial passes and a CI bot each found a command main blocked and the rewrite allowed. Every fix to the live bypasses in the sibling issue (draft 20260921-164559-b) needs that proof first.

Two smaller defects on current main are buildable now and need no design decision:

1. block-dangerous-git.sh:1451-1456 exits 0 once _ps_sink_attempts passes 4: "Only opaque residue left after bounded blanks, treat as allowed." With all five ps-unparsable-* allow tokens set, a five-trigger command carrying git reset --hard reaches the cap and is allowed with the destructive text still visible (measured by an audit validator on main b877295). This breaks the library's "over-block, never under-block" invariant (ps-command.sh:57-62). It fails open only for operators who configured tokens, so it is not a default-config bypass.
2. block-convention-violation.sh:621 and block-noncanonical-commit.sh:934 refuse only when PS_SINK_TRIGGER == herestring-comment-char. That name is set only when no other trigger fired (ps-command.sh:1755-1757). A flagged command whose first trigger is another construct (for example { raising special-construct) returns under that name, and both guards defer. Keying on the flag (PS_HERESTRING_OPENER_COMMENT_CHAR) instead is a strict superset and only moves rc from 0 to 2.

Evidence

Verified this pass (2026-09-27, main a6ba321):

• git log b877295b7..HEAD over lib/powershell, block-dangerous-git.sh, block-convention-violation.sh, block-noncanonical-commit.sh, block-no-verify.sh: no commits, so the ledger's line citations hold (convention guard line moved 620 to 621).
• Read block-dangerous-git.sh:1406-1460 and ps-command.sh:383-392, 1728-1760.

Carried from the 2026-09-23/24 interview and two-validator audit (not re-measured this pass): the budget-arm measurement above, and the Q10 trace for the commit guards.

Proposed approach

Three slices, in this order, each a draft PR:

1. scripts/check-guardrails-ps-differential.sh plus a check-guardrails-ps-differential.test.sh sibling (repo convention: scripts/check-*.sh with a .test.sh). It extracts the base ref's plugins/guardrails with git archive into a temp dir (no worktree), runs a corpus through the blocking PowerShell consumers on both trees, and exits nonzero on any cell where base refuses (2) and the branch does not. It prints the cell table. Required fixes from the audit:
   • Pin or unset CLAUDE_PLUGIN_ROOT per tree. guard-requires.sh:141 sources ${CLAUDE_PLUGIN_ROOT:-$_GUARD_REQUIRES_DIR/..}/<lib>, so without this both arms load one library and prove nothing.
   • Run the 32-subset allow-token powerset on block-dangerous-git only (the only guard that reads CLAUDE_PLUGIN_OPTION_BLOCK_DANGEROUS_GIT_ALLOW), and only for commands whose token-free result is 2. A full powerset over every guard costs about 20 hours at about 1.5 s per call on Windows.
   • Drive the production path too: run-guards.sh --lib lib/powershell/ps-command.sh ... (hooks.json Bash row), which shares one library load per process.
   • Corpus: commands harvested from the guard suites, plus every payload listed in draft 20260921-164559-b and their literal-git, Set-Content write, and parse-clean variants.
   • Consumers: block-dangerous-git, block-no-verify, block-convention-violation, block-noncanonical-commit, block-hook-bypass. flag-commit-pr-skill-bypass is advisory (always 0) and has no cell to show.
2. Budget arm: change the exit 0 at block-dangerous-git.sh:1452-1456 to a refusal with its own telemetry form token and a message naming budget exhaustion. Audit note: the cap is checked after the increment, so consider one final re-classify of the remainder before refusing.
3. Flag-keyed commit guards: test the flag, not the trigger name, at block-convention-violation.sh:621 and block-noncanonical-commit.sh:934.

Acceptance criteria

• scripts/check-guardrails-ps-differential.sh <base-ref> exists, its .test.sh passes, and it fails when fed a planted branch that allows a base-refused command.
• The script loads each tree's own library (verified by a planted difference between the two trees' ps-command.sh).
• The script exercises both direct hook calls and run-guards.sh --lib.
• With all five ps-unparsable-* tokens set, a command carrying five sink triggers plus git reset --hard exits 2 from block-dangerous-git (main: 0).
• block-convention-violation and block-noncanonical-commit exit 2 whenever PS_HERESTRING_OPENER_COMMENT_CHAR is 1, whatever trigger fired first.
• Each slice's PR body carries the differential's cell table showing zero base-2/branch-non-2 cells under every token subset.
• Guardrails CHANGELOG entry and plugin.json bump per slice; scripts/check-changelog-parity.sh --check-bump passes.

Constraints and gotchas

• Every change may only add refusals: rc may move from 0 or 1 to 2, never the reverse.
• The library stays fork-free (ps-command.sh:150-165): no pwsh spawn on the hook path. perf(guardrails): make the PowerShell guard path fork-free and narrow its fail-close to executable git #4188 took the PowerShell lane from 80 process creations to 3.
• Probes are JSON payloads on stdin only; never execute a probe command. Tests never run a destructive command.
• Related: guardrails: the PowerShell fail-closed sink advertises an allow token that does not clear a mutating block #4252 (the PowerShell sink advertises an allow token that does not clear a mutating block) touches the same token loop at block-dangerous-git.sh:1406-1460.

Context

Source: local handoff item 20260921-164559-guardrails-powershell-classifier-nine-residual-bypasses-measured-on-main.md (retired into this issue and draft 20260921-164559-b). Prior: #4302 / PR #4303. The item's two "also seen" notes are dropped: the block-hook-bypass.test.sh temp-dir leak did not reproduce for either audit validator, and the security-review lane is not defined in this repo's workflows (ci.yml:39 already lists synchronize).

[kyle-sexton]

Posted from the 2026-09-29 audit of the Cursor run (499 PRs, 2026-09-27 to 2026-09-29). The owner authorized fixing the findings; merging is not authorized. Fix PR: #5340 (draft).

The acceptance criterion required a differential cell table; the PR body of #4715 said "(per implementer)" with no table. The audit ran scripts/check-guardrails-ps-differential.sh --jobs 24 <base> from a scratch worktree at each commit (WSL2 Linux, bash 5.3.9; Linux only, no Windows host). The corpus, scripts/guardrails-ps-differential-corpus.jsonl, is 613 commands and unchanged since #4715; each command is run through 6 consumers, plus 10323 block-dangerous-git allow-token-subset cells (14001 cells per run).

run	branch commit	base	cells	base exits 2, branch does not	branch-only refusals	exit
a	048a17b (#4715)	048a17b^ (cccd285)	14001	0	160	0
c	origin/main aebb9bb	048a17b^ (cccd285)	14001	0	186	0

No run had a failing cell and no output contains FAIL. Run c is the cumulative check over every PowerShell guard change since the script landed, on these 613 commands.

Per-consumer cells for run a (base exits 2 / branch exits 2 / base 2, branch not / branch 2, base not): block-dangerous-git 333/333/0/0; block-no-verify 262/262/0/0; block-convention-violation 24/32/0/8; block-noncanonical-commit 27/35/0/8; block-hook-bypass 221/221/0/0; run-guards.sh Bash row 471/471/0/0; block-dangerous-git 31 token subsets 6079/6223/0/144.

Caveats:

• A cell can only fail on a command in the corpus; the corpus has 5 commands with a bare carriage return and 81 with a here-string opener.
• The differential is not gated in CI: ci.yml runs only the script's self-test.
• Option for the owner, not implemented: a CI or ready-flip step that posts this table when guardrails hooks or lib/ change.