From 2e548ede804a472892d3b00a107fd2e9aa720fca Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 21 Jun 2026 13:50:36 +0000
Subject: [PATCH] feat(coordinator-boundary): advisory tier for prose /
 pasted-spec leakage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The structural guard catches language *files* and re-vendored language dirs, but
not a grammar, typing rules, or a whole language spec pasted into a narrative doc
(how "TypeFix Zero" ended up inside README.adoc). This adds a NON-blocking advisory
scan to hooks/validate-coordinator-boundary.sh:

- Scope: the coordinator's narrative surface (top-level *.md/*.adoc + docs/, minus
  docs/disambiguation/). It does NOT scan wiki/ (where rust/ocaml/agda/ebnf teaching
  snippets legitimately live) or extraction-queue/ (staged content).
- Flags: grammar/proof code fences (agda/lean/coq/idris/ebnf/bnf/antlr/g4),
  implementation-language fences (rust/ocaml/reason/rescript), and unfenced spec
  tells (BNF ::=, sequents, universe/fixpoint typing judgments).
- WARNS only — never fails the build (heuristic; false positives must not block).
  Emits GitHub Actions ::warning:: annotations so findings surface on PRs.

Verified: passes clean on the current tree; flags a planted TF0-style spec
(fix : (A -> A), an agda fence, a ::= production) as 3 warnings while staying exit 0;
structural leaks still hard-fail.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWPX7iyvHf5AuwBAn1sJPy
---
 hooks/validate-coordinator-boundary.sh | 49 ++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/hooks/validate-coordinator-boundary.sh b/hooks/validate-coordinator-boundary.sh
index 71168d3..e282202 100755
--- a/hooks/validate-coordinator-boundary.sh
+++ b/hooks/validate-coordinator-boundary.sh
@@ -57,6 +57,55 @@ for lang in $LANGS; do
   fi
 done
 
+# ---------------------------------------------------------------------------
+# Advisory tier (NON-blocking): catch *prose* language-spec leakage that the
+# structural checks above cannot — a grammar, typing rules, or a whole language
+# spec pasted into a narrative doc (how "TypeFix Zero" ended up inside README).
+# This is heuristic, so it only WARNS; it never fails the build.
+#
+# Scope = the coordinator's NARRATIVE surface (top-level *.md/*.adoc + docs/,
+# minus the cross-language disambiguation notes). It deliberately does NOT scan
+# wiki/, where illustrative rust/ocaml/agda/ebnf *teaching* snippets legitimately
+# live, nor extraction-queue/ (content already staged for relocation).
+# ---------------------------------------------------------------------------
+WARN=0
+in_gha() { [ -n "${GITHUB_ACTIONS:-}" ]; }
+
+narrative_files() {
+  find . -maxdepth 1 -type f \( -name '*.md' -o -name '*.adoc' \)
+  find docs -type f \( -name '*.md' -o -name '*.adoc' \) ! -path 'docs/disambiguation/*' 2>/dev/null
+}
+
+advise() { # $1=regex  $2=message
+  local f ln
+  while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    while IFS= read -r ln; do
+      [ -n "$ln" ] || continue
+      in_gha && echo "::warning file=${f#./},line=${ln}::$2"
+      printf '  WARN %s:%s — %s\n' "${f#./}" "$ln" "$2"
+      WARN=$((WARN + 1))
+    done < <({ grep -nE "$1" "$f" 2>/dev/null || true; } | cut -d: -f1)
+  done < <(narrative_files)
+}
+
+# grammar/proof code blocks have no place in a coordinator narrative doc
+advise '^[[:space:]]*(```|----)[[:space:]]*(agda|lean|coq|idris2?|ebnf|bnf|antlr|g4)\b' \
+  'grammar/proof code block in a coordinator narrative doc — belongs in the language repo'
+# implementation-language code blocks: a coordinator describes, it does not implement
+advise '^[[:space:]]*(```|----)[[:space:]]*(rust|ocaml|reason|rescript)\b' \
+  'implementation-language code block in a coordinator narrative doc — describe, do not implement here'
+# unfenced spec tells: BNF productions, sequents, universe/fixpoint typing judgments
+advise '::=|⊢|Type[[:space:]]+[0-9a-z][[:space:]]*:[[:space:]]*Type|(^|[^A-Za-z])fix[[:space:]]*:[[:space:]]*\(' \
+  'typing-judgment / grammar-production notation — looks like a pasted language spec'
+
+if [ "$WARN" -gt 0 ]; then
+  echo ""
+  echo "coordinator-boundary: $WARN advisory warning(s) — possible prose/spec leakage (NON-blocking)."
+  echo "  If a language spec was pasted in, move it to that language's hyperpolymath/<lang> repo."
+  echo "  If it is legitimate cross-language prose, ignore — advisory checks never fail the build."
+fi
+
 if [ "$ERRORS" -gt 0 ]; then
   echo ""
   echo "Coordinator-boundary check FAILED ($ERRORS violation(s))."