[LAT-1878] Add pre-push hook — the CI gate cannot run (org billing lock)

.github/workflows/docs-drift.yml is correct but cannot execute: GitHub Actions
is locked org-wide. Every job returns "the job was not started because your
account is locked due to a billing issue". 100/100 runs on
mcpanalytics-operations are startup_failure, its link-check.yml has not run
since 2026-05-02, and the last successful run on any org repo was 2026-06-20.

A gate that cannot execute is not a gate, so this adds the mechanism that works
today: a pre-push hook, the same pattern that has kept api-mcp-prod's SSOT
invariants honest (LAT-1686). The workflow stays for when billing is restored.

Splits the exit codes, because this check needs NETWORK where api-mcp-prod's
invariant hook deliberately does not:
  1 = drift (or nothing found to compare) -> BLOCKS the push
  3 = platform unreachable                -> WARNS, allows the push
Blocking every push made offline would just teach everyone to reach for
--no-verify, and then the gate is gone for the case that actually matters.

Verified end-to-end: with README set back to "2,000 welcome credits", the
installed hook blocks a real `git push` and names the file and line.

Install: ./scripts/hooks/install.sh

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Mark Shors

scripts/check-docs-drift.py

@@ -39,7 +39,13 @@
 
 Exit codes:
     0  docs agree with the platform
-    1  drift found, or nothing found to compare, or the platform was unreachable
+    1  DRIFT — a doc claim disagrees with the platform, or nothing was found to
+       compare (the check has gone blind). Both are real problems.
+    3  COULD NOT VERIFY — the platform was unreachable. Distinct from 1 on
+       purpose: CI treats any non-zero as failure (a green check on an
+       unreachable API would be a lie), but the pre-push hook lets 3 through
+       with a warning. A gate that blocks every push made on a train gets
+       disabled with --no-verify, and then it is not a gate at all.
 """
 
 from __future__ import annotations
@@ -92,10 +98,12 @@ def fetch_platform(api_base: str) -> dict:
             return json.load(r)
     except (urllib.error.URLError, urllib.error.HTTPError,
             TimeoutError, OSError, ValueError) as e:
-        print(f"FATAL: could not read {url}: {e}", file=sys.stderr)
+        print(f"COULD NOT VERIFY: {url}: {e}", file=sys.stderr)
         print("       Refusing to pass — an unreachable platform is not "
               "evidence that the docs are correct.", file=sys.stderr)
-        raise SystemExit(1)
+        print("       (exit 3, distinct from drift; see the module docstring)",
+              file=sys.stderr)
+        raise SystemExit(3)
 
 
 def main() -> int:

scripts/hooks/install.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Install this repo's git hooks (LAT-1878).
+#
+# Hooks live in scripts/hooks/ (tracked) and are symlinked into .git/hooks/
+# (untracked). Symlink rather than copy, so an updated hook takes effect on the
+# next pull instead of silently running a stale version — a hook that everyone
+# has a different copy of is worse than no hook.
+set -euo pipefail
+
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SRC="$REPO/scripts/hooks"
+DST="$REPO/.git/hooks"
+
+[ -d "$DST" ] || { echo "no .git/hooks — not a git checkout?" >&2; exit 1; }
+
+for hook in pre-push; do
+    if [ -e "$DST/$hook" ] && [ ! -L "$DST/$hook" ]; then
+        echo "backing up existing $hook -> $hook.bak"
+        mv "$DST/$hook" "$DST/$hook.bak"
+    fi
+    ln -sf "../../scripts/hooks/$hook" "$DST/$hook"
+    chmod +x "$SRC/$hook"
+    echo "installed: .git/hooks/$hook -> scripts/hooks/$hook"
+done
+
+echo
+echo "Verify with:  python3 scripts/check-docs-drift.py"
+echo "Bypass once:  git push --no-verify"

scripts/hooks/pre-push

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Pre-push gate: this repo's public claims must match the live platform.
+#
+# WHY A HOOK AND NOT (ONLY) CI — LAT-1878/LAT-1883:
+#   .github/workflows/docs-drift.yml exists and is correct, but GitHub Actions
+#   cannot run in this org at all: every job returns "the job was not started
+#   because your account is locked due to a billing issue". 100/100 runs on
+#   mcpanalytics-operations are startup_failure; the last successful run on any
+#   org repo was 2026-06-20. A gate that cannot execute is not a gate.
+#   This hook works today, locally, with no billing dependency. The workflow
+#   stays for when billing is restored — belt and braces, not either/or.
+#
+# WHY IT IS SAFE TO GATE ON:
+#   One HTTPS GET to a public, cached endpoint and a regex over five markdown
+#   files. ~1s. It needs NETWORK, which the api-mcp-prod invariant hook
+#   deliberately does not — so unreachable (exit 3) WARNS and lets the push
+#   through, while actual drift (exit 1) blocks. Blocking a push made on a
+#   plane would just teach everyone to type --no-verify, and then the gate is
+#   gone for the case that matters.
+#
+# INSTALL:  ./scripts/hooks/install.sh
+# BYPASS:   git push --no-verify   (consciously, not reflexively)
+
+set -uo pipefail
+REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO" || exit 0
+
+# Nothing to check on an old branch / fresh clone that predates the script.
+[ -f scripts/check-docs-drift.py ] || exit 0
+
+PY="$(command -v python3 || true)"
+if [ -z "$PY" ]; then
+    echo "pre-push: python3 not found — skipping docs-drift check" >&2
+    exit 0
+fi
+
+echo "pre-push: docs drift vs live platform…"
+OUT="$("$PY" scripts/check-docs-drift.py 2>&1)"
+RC=$?
+
+case "$RC" in
+    0)
+        echo "pre-push: docs drift OK"
+        ;;
+    3)
+        # Could not reach the platform. Warn, do not block — see header.
+        echo "pre-push: ⚠️  could not verify docs against the platform (offline?)" >&2
+        echo "$OUT" | sed 's/^/  /' >&2
+        echo "pre-push: allowing push — re-run manually when back online:" >&2
+        echo "            python3 scripts/check-docs-drift.py" >&2
+        ;;
+    *)
+        echo "$OUT" | sed 's/^/  /' >&2
+        echo >&2
+        echo "pre-push: BLOCKED — this repo's public docs disagree with the live" >&2
+        echo "          platform. These files are read by prospects deciding" >&2
+        echo "          whether we are real; shipping a wrong number here has" >&2
+        echo "          already happened twice (LAT-1680, LAT-1876)." >&2
+        echo "          Fix the docs, or 'git push --no-verify' if you are sure." >&2
+        exit 1
+        ;;
+esac
+
+exit 0