Check the two facts the README states about itself

It claimed 121 contracts when there were 125, one day after the number was
written, and it documented every panama subcommand except the one added last --
so `panama apps` existed and the README did not mention it.

A number in prose is worth something as a claim somebody relies on and nothing
once it is wrong, so it is either checked or it should not be there. This checks
it, counted the way the runner collects the suite rather than by a second idea
of what a contract is, and checks that every subcommand the README documents is
one the dispatcher actually handles -- a listed command that errors reads as a
broken install rather than a stale document.

Claude-Session: https://claude.ai/code/session_01Q84axqUE5inJhf5Jz9CFy1

tests/setup/readme-contract

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# The README describes this repository accurately.
+#
+# It carries two facts that are cheap to state and easy to leave behind: how
+# many contracts there are, and which `panama` subcommands exist. Both had
+# already drifted -- the count said 121 when the suite had grown to 125, one day
+# after it was written.
+#
+# A number in prose is not worth much on its own. It is worth something as a
+# claim somebody might rely on, and worth nothing once it is wrong, so it is
+# either checked or it should not be there.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+readme="$repo_dir/README.md"
+panama="$repo_dir/bin/panama"
+
+findings=()
+note() { findings+=("$1"); }
+
+# ── The contract count ───────────────────────────────────────────────────────
+#
+# Counted the way `panama test` collects the suite, so the README agrees with
+# what the runner actually reports rather than with a second idea of it.
+
+actual="$(find "$repo_dir/tests" -type f -not -path '*/fixtures/*' -not -path '*__pycache__*' \
+    \( -executable -o -name '*_test.py' \) | wc -l)"
+
+claimed="$(grep -oE '^[0-9]+ of them, under' "$readme" | grep -oE '^[0-9]+')"
+
+if [[ -z "$claimed" ]]; then
+    note 'the README no longer states a contract count in the form this checks'
+elif (( claimed != actual )); then
+    note "the README says $claimed contracts; there are $actual"
+fi
+
+# ── Documented subcommands exist ─────────────────────────────────────────────
+#
+# A README listing a command the dispatcher does not have sends somebody to a
+# 'Unknown command' error, which reads as a broken install rather than a stale
+# document.
+
+while read -r subcommand; do
+    [[ -n "$subcommand" ]] || continue
+    grep -qE "^\s+$subcommand\)" "$panama" \
+        || note "the README documents 'panama $subcommand', which the dispatcher does not handle"
+done < <(sed -n '/^panama [a-z]/s/^panama \([a-z-]*\).*/\1/p' "$readme" | sort -u)
+
+if (( ${#findings[@]} > 0 )); then
+    mapfile -t findings < <(printf '%s\n' "${findings[@]}" | sort -u)
+    printf 'readme contract: %d finding(s)\n' "${#findings[@]}" >&2
+    printf '  - %s\n' "${findings[@]}" >&2
+    exit 1
+fi
+
+printf 'readme contract: PASS (%d contracts, as documented)\n' "$actual"