Add update_head_reference.sh: automate the head_reference checkpoint ritual, so it actually happens instead of being forgotten.

Refreshing head_reference/ (rebuild release binary, sd10+sn5m sweep
across all three curated suites, copy logs, tag the commit, archive
the binary) was, until now, a several-minute manual dance repeated by
hand every time a commit became the new comparison baseline -- exactly
the kind of multi-step ritual an AI assistant with no persistent
memory across sessions will reliably forget to fully repeat. Scripted
the mechanical parts: build, 6-way sweep, log copy, git tag (head-
reference-<date>, the durable/versioned source of truth for "which
commit was checkpoint N" -- see head_reference/README.md's new
"Checkpoint history convention" section), and binary archive (a
rebuild-avoidance cache alongside the tag, not a replacement for it).
Does NOT write the README's prose sections (what changed, why, how to
read the net score) -- that still needs a human/Claude actually
looking at the diff and the numbers this script prints at the end,
not a template trying to guess at them.

Checks for a dirty working tree and warns rather than silently tagging
something that doesn't correspond to a real commit -- the intended
sequence is still git commit first, then this script, same as
precommit_check.sh's gate runs before a commit rather than replacing
it.

precommit_check.sh: two lines printing the actual next-step commands
("git commit", "./update_head_reference.sh") after a passing check, so
the two scripts' relationship is visible right where the first one
succeeds.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01M9ZDiJhiUajUxh95mTXCFJ

1 files changed, 94 insertions, 0 deletions

diff --git a/src/update_head_reference.sh b/src/update_head_reference.sh
new file mode 100755
index 0000000..1303080
--- /dev/null
+++ b/src/update_head_reference.sh
@@ -0,0 +1,94 @@
+#!/bin/sh
+# Refresh ../head_reference/ (binary + logs + git tag + binary archive)
+# to point at the current commit. Run by hand after deciding a commit is
+# the new comparison baseline -- NOT automatic, same reasoning as
+# precommit_check.sh (rebuild cost, binary-clobbering risk).
+#
+# Automates the mechanical part of what was, until 2026-08-29, a several-
+# minute manual dance repeated by hand every time: rebuild release,
+# sd10+sn5m sweep across all three curated suites (6 runs), copy logs,
+# tag the commit so "match_play current head vs. last head" is actually
+# possible later, archive the binary so that comparison doesn't require
+# a rebuild-from-tag first. Does NOT write head_reference/README.md's
+# prose sections (what changed, why, net-score interpretation) -- that
+# needs a human/Claude actually looking at the diff and the numbers this
+# script prints, not a template.
+#
+# Usage: ./update_head_reference.sh
+
+cd "$(dirname "$0")" || exit 1
+HEADREF=../head_reference
+TESTS=../tests
+LOGDIR=/tmp/typhoon/update_head_reference
+mkdir -p "$LOGDIR" "$HEADREF/logs" "$HEADREF/archive"
+
+if [ ! -d "$HEADREF" ]; then
+    echo "ERROR: $HEADREF doesn't exist (expected sibling of src/)"
+    exit 1
+fi
+
+HASH=$(git rev-parse --short HEAD)
+if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "WARNING: working tree has uncommitted changes -- the binary/tag"
+    echo "         below will still be built from the working tree as-is,"
+    echo "         but the tag will point at HEAD ($HASH), which won't"
+    echo "         match what actually got built. Commit first if you"
+    echo "         want the tag to be trustworthy."
+    echo
+fi
+
+echo "=== [1/3] Building release binary ($HASH) ==="
+STEP_START=$(date +%s)
+gmake clean > "$LOGDIR/clean.log" 2>&1
+gmake -j5 GENETIC=1 PERF_COUNTERS=1 MP=1 SIXTYFOUR=1 > "$LOGDIR/build.log" 2>&1
+if [ $? -ne 0 ]; then
+    echo "    BUILD FAILED -- see $LOGDIR/build.log"
+    exit 1
+fi
+cp typhoon "$HEADREF/typhoon"
+echo "    [$(( $(date +%s) - STEP_START ))s]"
+
+echo "=== [2/3] sd10 + sn5M sweep, 3 curated suites (6 runs, parallel) ==="
+STEP_START=$(date +%s)
+for suite in ecm_ringers ecm_confident_quick ecm_hard_quick; do
+    ./typhoon --cpus 1 --hash 256m --logfile "$LOGDIR/sd10_${suite}.log" \
+        --batch --command "force; book name /nonexistent.book.bin; sd 10; script $TESTS/${suite}.ep_" \
+        > "$LOGDIR/sd10_${suite}.out" 2>&1 &
+    ./typhoon --cpus 1 --hash 256m --logfile "$LOGDIR/sn5m_${suite}.log" \
+        --batch --command "force; book name /nonexistent.book.bin; sn 5000000; script $TESTS/${suite}.ep_" \
+        > "$LOGDIR/sn5m_${suite}.out" 2>&1 &
+done
+wait
+echo "    [$(( $(date +%s) - STEP_START ))s]"
+
+cp "$LOGDIR"/sd10_*.log "$LOGDIR"/sd10_*.out "$LOGDIR"/sn5m_*.log "$LOGDIR"/sn5m_*.out "$HEADREF/logs/"
+
+echo "=== [3/3] Tagging + archiving ==="
+TAGNAME="head-reference-$(date +%Y%m%d)"
+if git rev-parse -q --verify "refs/tags/$TAGNAME" >/dev/null; then
+    echo "    tag $TAGNAME already exists (probably re-run same day) -- leaving it, not overwriting"
+else
+    git tag -a "$TAGNAME" -m "head_reference checkpoint (see head_reference/README.md)" "$HASH"
+    echo "    tagged $TAGNAME -> $HASH (local only -- push with 'git push origin $TAGNAME' if wanted)"
+fi
+cp "$HEADREF/typhoon" "$HEADREF/archive/typhoon-$HASH"
+echo "    archived $HEADREF/archive/typhoon-$HASH"
+
+echo
+echo "=== Summary (fold into head_reference/README.md by hand) ==="
+printf "%-22s %10s %10s\n" "Suite" "sd10" "sn5M"
+sd10_total_s=0; sd10_total_n=0; sn5m_total_s=0; sn5m_total_n=0
+for suite in ecm_ringers ecm_confident_quick ecm_hard_quick; do
+    s10=$(grep -c "solved in" "$LOGDIR/sd10_${suite}.out")
+    n10=$(grep -c "not solved" "$LOGDIR/sd10_${suite}.out")
+    s5m=$(grep -c "solved in" "$LOGDIR/sn5m_${suite}.out")
+    n5m=$(grep -c "not solved" "$LOGDIR/sn5m_${suite}.out")
+    printf "%-22s %4s/%-5s %4s/%-5s\n" "$suite" "$s10" "$((s10+n10))" "$s5m" "$((s5m+n5m))"
+    sd10_total_s=$((sd10_total_s+s10)); sd10_total_n=$((sd10_total_n+s10+n10))
+    sn5m_total_s=$((sn5m_total_s+s5m)); sn5m_total_n=$((sn5m_total_n+s5m+n5m))
+done
+printf "%-22s %4s/%-5s %4s/%-5s\n" "TOTAL" "$sd10_total_s" "$sd10_total_n" "$sn5m_total_s" "$sn5m_total_n"
+echo
+echo "Reminder: head_reference/README.md still needs manual editing --"
+echo "commit hash/message, what changed and why, net-score interpretation."
+echo "This script only refreshed the binary, logs, tag, and archive."