audit: guardrails + source-control hardening — bypass gaps, convention-enforcement SSOT, decoupling

[kyle-sexton]

Tracking issue for the external audit delivered via the melodic plugin handoff-inbox (producer: SW2030, Windows/PowerShell), covering guardrails@0.9.5 + source-control@0.16.0. All findings code-grounded against main.

Findings (grounded)

• f1 [HIGH] guardrails PreToolUse guards are matcher:"Bash"-only → a Windows PowerShell tool bypasses every commit/git guard. Proven live: identical git commit --no-verify blocked via Bash tool, unblocked via PowerShell tool.
• f2 [MED] enablement probe reads only <repo>/.claude/settings.json, ignores user-global scope.
• f3 [LOW] a block message is a bash heredoc, unusable in PowerShell.
• f4 [HIGH] nothing gates commit-subject text or gh pr create --title against the resolved pattern — enforced only by model-skills at draft time.
• f5 [HIGH] convention source hardcoded to .claude/source-control*.md, no relocation config.
• W1 dependency-bot login frozenset non-configurable; W2 branch→issue grammar hardcoded; W3 hook-manager bypass detection lefthook-only; W4 machine-path checkout-root hardcoded repos.

Locked contract (binds all sub-issues — do not diverge)

1. Regex dialect = POSIX ERE for enforcement; the resolver normalizes common PCRE-isms ((?:->(, \d->[0-9], \w->[[:alnum:]_], \s->[[:space:]]); un-normalizable constructs (lookaround) -> pattern is non-enforceable, gate no-ops with a visible note.
2. Unresolved = NO enforcement. If the pattern isn't in the layered .claude/source-control*.md files, gates no-op. Doctrine: Conventional Commits is not lane-1, so never block against the bundled default in a repo that didn't opt in.
3. Policy-floor. Enforcement reads treat the tracked team pattern as a floor; personal/local overlays may tighten, never loosen. Drafting keeps full per-key override.

Design

• SSOT: parse the existing markdown surface (no YAML migration, no consumer format change, no path rename). Shared lib/ resolver; convention becomes a concern-named seam with an owner-doc under docs/conventions/.
• Enforcement: CC-layer gate is the zero-setup default; git commit-msg hook is opt-in depth. Both read one resolver.

Sub-issues (blockers-first)

S1+C1 (seam) is the sequential blocker, then parallel (C2, A2a, B1, W-sc, W-gr), then A1 last (heavyweight trust-surface review).

[kyle-sexton]

Execution order (blockers-first)

Sequential blocker:

• feat(source-control): convention parse-contract + shared enforcement resolver seam #913 — S1+C1 convention parse-contract + shared resolver seam

Parallel (after #913 merges):

• feat(guardrails): CC-layer content gate — commit subject + PR title #914 — C2 CC-layer content gate (depends feat(source-control): convention parse-contract + shared enforcement resolver seam #913)
• fix(guardrails): close PowerShell-tool bypass of Bash-matched guards #915 — A2a PowerShell-tool bypass close
• fix(guardrails): enablement probe honors user-global plugin scope #916 — B1 enablement probe user-global scope
• fix(source-control): externalize hardcoded bot logins + branch-to-issue grammar #917 — W-sc externalize bot logins + branch grammar
• fix(guardrails): configurable hook-manager bypass detection + machine-path roots #918 — W-gr configurable hook-manager bypass + machine-path roots

Last (heavyweight trust-surface review):

• feat(guardrails): opt-in git commit-msg hook for tool-agnostic subject enforcement #919 — A1 opt-in git commit-msg hook (depends feat(source-control): convention parse-contract + shared enforcement resolver seam #913)

Dependency edges: #913 → {#914, #919}. #915/#916/#917/#918 independent.