From 4b1f878f34f82a3d59376c979feffe12d2cbd94d Mon Sep 17 00:00:00 2001
From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com>
Date: Tue, 26 May 2026 07:44:13 -0400
Subject: [PATCH 1/2] fix(content-guards): cap markdown validator output to
 prevent context bloat

The validate-markdown.sh PostToolUse hook captured full markdownlint-cli2
stderr/stdout into the blockingError string returned to Claude with no
bound. A noisy markdown file (e.g. README with long mermaid blocks under
default MD013 line-length) emits hundreds of violations per fire; in one
recent session a 15-file scaffold pushed ~500KB of lint output per Write
into context and busted the 1M-token session limit (final transcript:
2,082,547 tokens, 85% markdownlint-attributed).

Cap reporting to the first 20 violation lines plus an overflow-count
summary. Worst-case per-fire payload ~2KB vs ~500KB before. Hook still
exits 2 on failure; blocking behavior unchanged. awk used over
head/wc to avoid SIGPIPE concerns under set -euo pipefail.

Smoke test (120-line noisy file, default MD013): exit 2, 26 lines /
1893 bytes total, footer reads "...and 105 more line(s) (capped at 20;
rerun markdownlint-cli2 manually for the full report)".

Assisted-by: Claude <noreply@anthropic.com>
---
 content-guards/scripts/validate-markdown.sh | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/content-guards/scripts/validate-markdown.sh b/content-guards/scripts/validate-markdown.sh
index f260bcf..6020ab0 100755
--- a/content-guards/scripts/validate-markdown.sh
+++ b/content-guards/scripts/validate-markdown.sh
@@ -153,7 +153,16 @@ EOF
     fi
   } 2>&1 ); then
     errors+=("markdownlint-cli2 failed:")
-    errors+=("$markdownlint_output")
+    # Cap validator output so a noisy run can't flood Claude's context window.
+    max_lines=20
+    total_lines=$(awk 'END{print NR}' <<<"$markdownlint_output")
+    if (( total_lines > max_lines )); then
+      capped=$(awk -v max="$max_lines" 'NR<=max' <<<"$markdownlint_output")
+      capped+=$'\n…and '"$((total_lines - max_lines))"' more line(s) (capped at '"$max_lines"'; rerun markdownlint-cli2 manually for the full report)'
+      errors+=("$capped")
+    else
+      errors+=("$markdownlint_output")
+    fi
   fi
 fi
 

From 4d59640319968a10eeb06e35f78b3c3afad691ce Mon Sep 17 00:00:00 2001
From: JacobPEvans <20714140+JacobPEvans@users.noreply.github.com>
Date: Thu, 28 May 2026 23:36:34 -0400
Subject: [PATCH 2/2] refactor(content-guards): collapse markdown output cap
 into single awk pass

Per review feedback on PR #335: replace the two-awk approach (one for line
count, one for capping) plus bash arithmetic with a single awk invocation
that counts, caps, and formats the overflow footer in its END block. Drops
the extra subprocess spawn and removes bash arithmetic that could error
under set -euo pipefail if awk output were ever non-numeric.

Output is byte-identical: smoke test on a 120-line noisy file still yields
exit 2, 1893 bytes, 26 lines, with the "...and N more line(s)" footer.

Assisted-by: Claude <noreply@anthropic.com>
---
 content-guards/scripts/validate-markdown.sh | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/content-guards/scripts/validate-markdown.sh b/content-guards/scripts/validate-markdown.sh
index 6020ab0..f4f2faf 100755
--- a/content-guards/scripts/validate-markdown.sh
+++ b/content-guards/scripts/validate-markdown.sh
@@ -154,14 +154,18 @@ EOF
   } 2>&1 ); then
     errors+=("markdownlint-cli2 failed:")
     # Cap validator output so a noisy run can't flood Claude's context window.
+    # Single awk pass counts, caps, and formats the overflow footer.
     max_lines=20
-    total_lines=$(awk 'END{print NR}' <<<"$markdownlint_output")
-    if (( total_lines > max_lines )); then
-      capped=$(awk -v max="$max_lines" 'NR<=max' <<<"$markdownlint_output")
-      capped+=$'\n…and '"$((total_lines - max_lines))"' more line(s) (capped at '"$max_lines"'; rerun markdownlint-cli2 manually for the full report)'
+    if [[ -n "$markdownlint_output" ]]; then
+      capped=$(awk -v max="$max_lines" '
+        NR <= max { print }
+        END {
+          if (NR > max) {
+            print "…and " (NR - max) " more line(s) (capped at " max "; rerun markdownlint-cli2 manually for the full report)"
+          }
+        }
+      ' <<<"$markdownlint_output")
       errors+=("$capped")
-    else
-      errors+=("$markdownlint_output")
     fi
   fi
 fi