scripts: source states invariants, not history

Comments across this tree name pods, validator ids, clusters, ticket numbers and
measurements taken from running networks. The repository is public, so each one
turns a reader of the code into a reader of our operations, and each ages badly:
the invariant stays true, the anecdote does not.

The check refuses those patterns in tracked Go source so they cannot re-enter.
Rewriting is the fix, not deletion — a comment that says what went wrong should
say instead what must hold and why.

Co-authored-by: Hanzo Dev <[email protected]>

scripts/check_source_prose.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Source is published. It states what the code does and what must hold — never what
+# went wrong, where, or on which host.
+#
+# A comment naming a pod, a node id, a cluster, an incident or a measured outage turns
+# every reader of the public repository into a reader of our operations. It also ages
+# badly: the invariant stays true, the anecdote does not.
+#
+# Rewrite rather than delete. "Measured on host X, N requests produced M results" becomes
+# the rule that made it wrong — "a batch that accepts nothing must descend, because a
+# responder serves the window ending at the id it was asked for".
+#
+# Runs over tracked Go source. Exits non-zero on a match.
+
+set -uo pipefail
+cd "$(dirname "$0")/.." || exit 2
+
+fail=0
+report() { # pattern, what it leaks
+  local hits
+  hits=$(git grep -nE "$1" -- '*.go' 2>/dev/null) || return 0
+  [ -z "$hits" ] && return 0
+  printf '\n%s\n' "$2"
+  printf '%s\n' "$hits" | sed 's/^/  /'
+  fail=1
+}
+
+report 'luxd-[0-9]|zood-[a-z0-9-]*[0-9]|parsd-[a-z0-9-]*[0-9]' \
+  'pod names — these are our hosts'
+report 'NodeID-[A-Za-z0-9]{8}' \
+  'validator node ids'
+report '\b(lux|zoo|pars|hanzo)-(mainnet|testnet|devnet)\b' \
+  'cluster namespaces'
+report '[Ii]ncident-[0-9]|INCIDENT' \
+  'incident references — the ticket is not the reason the rule holds'
+report '[Mm]easured (on|at) (lux|zoo|pars|hanzo|host|prod)' \
+  'outage measurements taken from production'
+report '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}' \
+  'IP addresses'
+report '\b(ghcr\.io/[a-z]+/[a-z-]+:v?[0-9]+\.[0-9]+\.[0-9]+)' \
+  'pinned image references — these belong in manifests, not source'
+
+if [ "$fail" -ne 0 ]; then
+  cat <<'EOF'
+
+Source states invariants, not history. Rewrite each comment above to say what must be
+true and why, with no host, cluster, id, ticket or outage in it.
+EOF
+  exit 1
+fi
+echo "source prose clean"