Add COMPARISON.md, cross-link all documents, enforce with check-docs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

scripts/check-docs.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Checks the documentation set: every markdown file links to every other one, and every relative link resolves.
+# Usage: scripts/check-docs.sh   (exit 1 on any problem, lists them all)
+set -u
+cd "$(dirname "$0")/.."
+
+DOCS=(README.md SPEC.md COMPARISON.md AGENTS.md CHANGELOG.md docs/ARCHITECTURE.md docs/RESEARCH.md)
+bad=0
+fail() { echo "docs: $*"; bad=$((bad+1)); }
+
+# no markdown file may exist outside the checked set (so a new doc cannot dodge the rule)
+while IFS= read -r f; do
+  f=${f#./}
+  printf '%s\n' "${DOCS[@]}" | grep -qxF "$f" || fail "$f is not in the DOCS list of scripts/check-docs.sh"
+done < <(find . -name '*.md' -not -path './build/*' -not -path './.git/*' -not -path './prompt.md')  # prompt.md: the original task statement, not documentation
+
+for f in "${DOCS[@]}"; do
+  [ -f "$f" ] || { fail "$f is missing"; continue; }
+  dir=$(dirname "$f")
+  # every other document must be linked
+  for g in "${DOCS[@]}"; do
+    [ "$f" = "$g" ] && continue
+    rel=$(realpath --relative-to="$dir" "$g")
+    grep -qE "\]\(${rel//./\\.}(#[^)]*)?\)" "$f" || fail "$f does not link to $g (expected ]($rel))"
+  done
+  # every relative link must point at something that exists
+  while IFS= read -r target; do
+    case "$target" in http://*|https://*|mailto:*|\#*) continue ;; esac
+    path=${target%%#*}
+    [ -z "$path" ] && continue
+    [ -e "$dir/$path" ] || fail "$f links to missing $target"
+  done < <(grep -oE '\]\([^)]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//')
+done
+
+[ "$bad" -eq 0 ] && echo "docs: ${#DOCS[@]} documents, all cross-linked, all links resolve" || { echo "docs: $bad problem(s)"; exit 1; }

scripts/release.sh

@@ -22,6 +22,7 @@ if grep -rl $'\xe2\x80\x94' --exclude-dir=build --exclude-dir=.git . | grep -q .
   echo "em dash found, remove it first" >&2; exit 1
 fi
 
+scripts/check-docs.sh
 echo "$new" > VERSION
 cmake -S . -B build >/dev/null
 cmake --build build