guardrails:flag-commit-pr-skill-bypass: advisory false-fires on canonical `git commit -F -` with inline heredoc Co-Authored-By trailer (requires BOTH markers, contradicting documented "either marker -> stay quiet" intent)

[kyle-sexton]

Category: bug

Summary

The flag-commit-pr-skill-bypass.sh PreToolUse advisory fires on a hand-typed git commit -F - that already replicates the canonical /commit mechanic, contradicting the hook's own documented intent.

Observed

During PR babysitting (worker on #527), this well-formed commit triggered the advisory:

git commit -F - <<'EOF'
test(work-items): add needs-info eval for raw-marker clearing
...
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
EOF

Emitted additionalContext:

Commit/PR skill composition (advisory): direct git commit (missing the canonical -F - stdin form + --trailer Co-Authored-By line) ...

The message claims the -F - stdin form is missing — but it was used verbatim, and a Co-Authored-By trailer was present in the heredoc body.

Root cause

plugins/guardrails/hooks/flag-commit-pr-skill-bypass.sh lines 180-181:

if ! [[ "$COMMAND_LC" =~ (^|[[:space:]])(-f|--file)[[:space:]]+-([[:space:]]|$) ]] ||
  ! [[ "$COMMAND_LC" =~ --trailer ]]; then

!(A) || !(B) is !(A AND B) — it fires unless BOTH -F - AND --trailer are present. But the documented intent is the opposite:

• Header (lines 16-22): "A manual git commit that already replicates the canonical shape (e.g. a hand-typed heredoc form) stays quiet — the guard targets the anti-pattern (git commit -m "...")".
• Inline comment (line 178): "Either marker present -> the caller already replicates the skill's mechanic; stay quiet."

To stay quiet when EITHER marker is present (fire only when NEITHER is), the condition must be !(A) AND !(B). The || should be &&.

Secondary issue

strip_literals() (lines 141-166) drops heredoc bodies wholesale, and the canonical /commit mechanic carries Co-Authored-By inside the -F - heredoc body, not via a --trailer flag. So --trailer is both (a) undetectable in the intended canonical form and (b) not actually the marker the canonical mechanic uses. The -F - / --file - stdin marker alone is the reliable signal that the caller replicated the canonical shape; requiring --trailer on top guarantees a false positive for the very heredoc form the header cites as "stays quiet."

Impact

False-positive advisory noise on well-formed commits; nudges toward /commit when the commit already replicates the canonical shape. Non-blocking (exits 0), so cosmetic — but it fires on the exact form the header documents as exempt.

Suggested fix

Change the fire condition to !(A) && !(B) (stay quiet when either -F - or --trailer is present), and consider dropping the --trailer requirement in favor of the -F - stdin marker alone, since the canonical mechanic passes the trailer through the heredoc body.

Filed by an automated PR-babysitting worker (self-observation). Not refiling #484/#465/#473/#499/#504/#511/#512/#524.

[kyle-sexton]

This was generated by AI during triage. · Category: bug · Priority: priority: high (guardrails false-fires on the CANONICAL commit path — friction on every hand-typed heredoc commit that already does the right thing). Routed status: ready. T1 — one-operator fix, root cause pinpointed by the reporter.

Plan

flag-commit-pr-skill-bypass.sh fires the advisory on a well-formed git commit -F - <<'EOF' … Co-Authored-By: … EOF — the exact canonical shape it's documented to stay quiet on.

Root cause (reporter-confirmed): the guard condition is

if ! [[ ... (-f|--file) ... - ... ]] || ! [[ ... --trailer ]]; then

!(A) || !(B) == !(A AND B) → fires unless BOTH the -F - stdin form AND --trailer are present. Documented intent (header + inline comment) is the opposite: stay quiet when EITHER marker is present, fire only when NEITHER is → the condition must be !(A) && !(B).

Fix: change the || to && in that condition.

Acceptance

• git commit -F - with a heredoc body containing a Co-Authored-By trailer → advisory stays quiet (either-marker satisfied).
• git commit --trailer "Co-Authored-By: …" → stays quiet.
• Bare git commit -m "…" (neither marker) → still fires (anti-pattern preserved).
• Note: the reporter flags a secondary issue (body truncated in the report) — pull the full issue body and address it in the same change if it's part of this hook's logic.

Decision defaulted: change || → && so the advisory stays quiet when EITHER the -F - stdin form OR a --trailer/inline Co-Authored-By marker is present — veto before merge