docs(guardrails): README labels six Bash|PowerShell guards as PreToolUse Bash only

[kyle-sexton]

Found while surveying PreToolUse matchers for #1598; out of scope there, filed so it does not evaporate.

plugins/guardrails/README.md L13-20 documents six guards as PreToolUse · Bash, but
plugins/guardrails/hooks/hooks.json L22 and L51 register both groups as "matcher": "Bash|PowerShell".
The JSON is authoritative, so the README understates the matcher — a reader on a PowerShell-primary
machine would conclude the guards do not apply to them.

Affects: block-no-verify, block-dangerous-git, block-hook-bypass, flag-commit-pr-skill-bypass,
block-noncanonical-commit, block-convention-violation.

Fix is the README table only; no behavior change.

Related

• docs(claude-config): required-permissions.md recommends Read(...) deny globs for secrets without stating their scope #1598 / docs(claude-config): state the scope of a Read deny in the audit permission baseline #1599 — the claude-config Read-deny scope work whose matcher survey surfaced this.

[kyle-sexton]

This was generated by AI during triage.

Triage: verified → briefed, delegable.

Verification: the claim holds, and the affected-guard list is exactly right. The guardrails plugin's
hook manifest registers two PreToolUse groups under the matcher Bash|PowerShell. Enumerating the
guard scripts inside those two groups yields precisely the six named in this issue —
block-no-verify, block-dangerous-git, block-hook-bypass, block-noncanonical-commit,
block-convention-violation, flag-commit-pr-skill-bypass — while the plugin README's guard table
lists each of the six as PreToolUse · Bash. The manifest is authoritative, so the README understates
the matcher for all six and no others. The remaining matchers in the manifest
(Write|Edit|NotebookEdit, Workflow, Write|Edit) match their README rows already.

Agent Brief

Type: Bug
Summary: The guardrails plugin README's guard table documents six PreToolUse guards as
matching Bash only, while the hook manifest registers them against Bash|PowerShell. Correct the
table so the documented matcher matches the registered one.

Current behavior:
The README's guard table renders the trigger column for six guards as PreToolUse · Bash. A reader
on a PowerShell-primary machine concludes those guards do not apply to their tool calls. They do —
the manifest matches both tools.

Desired behavior:
Each of the six affected rows states the matcher the manifest actually registers, in the table's
existing escaped-alternation style (the same style already used by the Write | Edit | NotebookEdit
and Write | Edit rows). Rows whose documented matcher already agrees with the manifest are left
untouched. No hook, script, or manifest behavior changes.

Key interfaces:

• The guardrails plugin README's guard table — the trigger column for the six guards registered
  under the Bash|PowerShell matcher groups.
• The plugin's hook manifest is the authority for the correct values and is not edited by this
  work.
• Derive the affected row set from the manifest at implementation time rather than from this brief's
  list, so the fix is correct even if group membership has shifted since filing.

Acceptance criteria:

• Every guard row's documented matcher matches the matcher its hook manifest group registers, for
  all rows in the table — verified by reading the manifest, not by trusting the prior text.
• The six affected rows read as matching both tools, in the table's existing escaped-alternation
  style so the Markdown table still renders correctly.
• No change to any hook script, the manifest, or guard behavior.
• The repository's Markdown lint passes.

Out of scope:

• Changing which tools any guard actually matches — this aligns documentation to behavior, never the
  reverse.
• Restructuring or rewording the guard table beyond the trigger column.
• The prose sections around the table, except where a sentence restates the Bash-only claim and
  would be left contradicting the corrected rows.

Note on classification: this repository's runtime-surface boundary treats every tracked *.md as
behavior-loaded, so despite the issue's "README table only; no behavior change" framing this is not a
mechanical doc fix — the table is the operator-facing statement of which tool calls are guarded, and
it is currently wrong in the direction that under-reports coverage. Route it as a scoped change.

[kyle-sexton]

This was generated by AI during triage.

Admission gate: carries agent-ready but no work-class: label and no body-recorded class trailer — unclassified → fail-closed human-gated per the work-loop lane's admission table. Routed to human-gated; not dispatched. (See #1610 — this is a recurring pattern this cycle, not a one-off.)

[kyle-sexton]

Verified fixed on origin/main at 93b5f696: plugins/guardrails/README.md lines 13–20 now label all six guards as PreToolUse · Bash | PowerShell, matching hooks/hooks.json matchers. No further change needed.