docs(guardrails): document after-block continuation and PS over-blocks (#4236)

[kyle-sexton]

Closes #4236

Summary

Document that the dispatcher keeps running after a deny, name the PowerShell over-blocks with the rewrite that already passes, and pin that a dual-blocked PowerShell sink prints both denials.

Fix

• README states that after-block continuation is deliberate: a dual-blocked PowerShell sink prints both denials. The over-length short-circuit (guardrails: Bash|PowerShell PreToolUse row takes 30+s on a ~70 KB command; its 60s timeout fails open #4528) stays the one exception.
• Scope notes: unroll foreach { git … } (and other untokenizable {} / () grouping) into flat git -C <path> …; statements; rewrite & $var script arg1 arg2 as a quoted literal path or a flag-first call (& $sh -File …). Binding-to-literal relief remains guardrails: & $var script record dir blocked as a file write; block reason names the wrong cause #4234; grouping interrogation relief remains guardrails: read-only git inside {} blocked by two guards, with irrelevant commit guidance, Bash-lane advice, and no narrow lever #4235 / fix(guardrails): PowerShell read-only git grouping + ps-computed-positional (#4235) #4817 (open; this PR does not claim that relief).
• run-guards.test.sh pins Invoke-Command -ScriptBlock { git reset --hard } through block-no-verify + block-dangerous-git and asserts both block_no_verify_enabled and block_dangerous_git_enabled on stderr.

Verification

cd plugins/guardrails/hooks
bash run-guards.test.sh

PASS=311 FAIL=0, including PS dual sink: block-no-verify reason is on stderr and PS dual sink: block-dangerous-git reason is on stderr too.

Decision

• Claim: KEEP the full guard chain after a block. Do not stop at the first exit 2.
• Basis: The dual-sink PowerShell path this issue recorded (Invoke-Command { git reset --hard }) is refused by both block-no-verify and block-dangerous-git. Ending the chain at the first deny would hide the second lever. The over-length ceiling (guardrails: Bash|PowerShell PreToolUse row takes 30+s on a ~70 KB command; its 60s timeout fails open #4528) remains the documented short-circuit.
• As of: 2026-09-28
• Recheck: if a later dispatcher change makes after-block continuation the dominant cost on the PowerShell allow path, or if guardrails: read-only git inside {} blocked by two guards, with irrelevant commit guidance, Bash-lane advice, and no narrow lever #4235 lands and the dual-sink shape no longer hits both guards.

needs-human

• Claim: Windows RUN_GUARDS_PROFILE=1 cost of the kept full chain on Git Bash PowerShell allow is unmeasured here.
• Basis: This environment is Linux CI. The issue's Windows profile numbers cannot be reproduced on this host.
• As of: 2026-09-28
• Recheck: run RUN_GUARDS_PROFILE=1 on Windows Git Bash against the PowerShell allow path and compare to the README budget table.

Related

• guardrails: read-only git inside {} blocked by two guards, with irrelevant commit guidance, Bash-lane advice, and no narrow lever #4235 / fix(guardrails): PowerShell read-only git grouping + ps-computed-positional (#4235) #4817 (read-only git grouping, separate; overlap checked — this PR documents the rewrite that already works on main).
• guardrails: & $var script record dir blocked as a file write; block reason names the wrong cause #4234 (computed-call literal binding).
• guardrails: Bash|PowerShell PreToolUse row takes 30+s on a ~70 KB command; its 60s timeout fails open #4528 (over-length first-block short-circuit).

guardrails 0.39.3 (serialized above origin/main 0.38.13 and in-flight 0.39.2 on #4251).