Add docstring-macro validation scripts for #314 F15

- validate_file_docstrings.sh: per-file MCRF_* compliance check (PASS/FAIL),
  the completion signal for one-agent-per-file docstring conversion.
- check_frozen_docstrings.sh: strict gate over the frozen (non-3D) binding
  surface; locks F15 against regression (mirrors the API-surface snapshot test).

Both wrap tools/audit_pymethoddef.py (tree-sitter, .venv-audit).

Refs #314

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tools/check_frozen_docstrings.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# check_frozen_docstrings.sh - strict MCRF_* docstring-macro gate over the FROZEN
+# (1.0) Python-binding surface.
+#
+# Part of #314 F15. Mirrors the role of tests/unit/api_surface_snapshot_test.py:
+# once the frozen binding files are converted to MCRF_METHOD/MCRF_PROPERTY, this
+# gate prevents regression to raw docstrings. Experimental 3D/Voxel bindings
+# (src/3d/) are exempt from the 1.0 freeze and intentionally excluded.
+#
+# Usage:
+#   tools/check_frozen_docstrings.sh
+#
+# Exit codes:
+#   0  PASS  - all frozen binding files are 100% MCRF_* compliant
+#   1  FAIL  - one or more raw/missing doc slots remain in a frozen file
+#   2  ERROR - missing tooling
+set -u
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PY="$ROOT/.venv-audit/bin/python3"
+AUDIT="$ROOT/tools/audit_pymethoddef.py"
+
+if [ ! -x "$PY" ]; then
+    echo "ERROR: $PY not found (need .venv-audit with tree-sitter + tree-sitter-cpp)" >&2
+    exit 2
+fi
+
+# Frozen surface = all binding sources EXCEPT experimental 3D/Voxel (src/3d/).
+mapfile -t FILES < <(find "$ROOT/src" -name '*.cpp' -not -path '*/3d/*' | sort)
+if [ "${#FILES[@]}" -eq 0 ]; then
+    echo "ERROR: no source files found under $ROOT/src" >&2
+    exit 2
+fi
+
+"$PY" "$AUDIT" --strict --quiet --paths "${FILES[@]}"
+RC=$?
+if [ "$RC" -eq 0 ]; then
+    echo "FROZEN DOCSTRING GATE: PASS (frozen binding surface is 100% MCRF_* compliant)"
+else
+    echo "FROZEN DOCSTRING GATE: FAIL (raw/missing docstrings remain in frozen files; src/3d/ is exempt)"
+fi
+exit $RC

tools/validate_file_docstrings.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# validate_file_docstrings.sh - per-file MCRF_* docstring-macro compliance check.
+#
+# Part of #314 F15: drives one-agent-per-file docstring standardization. An agent
+# converting a single .cpp runs THIS script repeatedly until it prints
+# "VALIDATION: PASS", which is the completion signal for that file.
+#
+# Usage:
+#   tools/validate_file_docstrings.sh src/SomeFile.cpp
+#
+# Exit codes:
+#   0  PASS  - every PyMethodDef/PyGetSetDef entry uses MCRF_METHOD/MCRF_PROPERTY
+#   1  FAIL  - one or more RAW_STRING / NULL / MISSING doc slots remain
+#   2  ERROR - bad usage / missing tooling
+set -u
+
+FILE="${1:-}"
+if [ -z "$FILE" ]; then
+    echo "usage: tools/validate_file_docstrings.sh <src/file.cpp>" >&2
+    exit 2
+fi
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PY="$ROOT/.venv-audit/bin/python3"
+AUDIT="$ROOT/tools/audit_pymethoddef.py"
+
+if [ ! -x "$PY" ]; then
+    echo "ERROR: $PY not found. Create it with:" >&2
+    echo "  python3 -m venv .venv-audit && .venv-audit/bin/pip install tree-sitter tree-sitter-cpp" >&2
+    exit 2
+fi
+if [ ! -f "$FILE" ]; then
+    echo "ERROR: no such file: $FILE" >&2
+    exit 2
+fi
+
+# A file using MCRF_* macros must include the macro header.
+if ! grep -q 'McRFPy_Doc.h' "$FILE"; then
+    echo "NOTE: $FILE does not yet #include \"McRFPy_Doc.h\" (required for MCRF_* macros)"
+fi
+
+OUT="$("$PY" "$AUDIT" --paths "$FILE" 2>&1)"
+NONCOMP="$(printf '%s\n' "$OUT" | awk '$NF ~ /^(RAW_STRING|MISSING|NULL)$/')"
+
+if [ -z "$NONCOMP" ]; then
+    echo "VALIDATION: PASS ($FILE is 100% MCRF_* compliant)"
+    exit 0
+fi
+
+echo "Remaining non-compliant entries in $FILE:"
+printf '%s\n' "$NONCOMP"
+N="$(printf '%s\n' "$NONCOMP" | wc -l | tr -d ' ')"
+echo "VALIDATION: FAIL ($N non-compliant doc slot(s) remain)"
+exit 1