rate-limit-guard: the #2521 perf claim has no committed benchmark harness - its numbers cannot be reproduced or regression-checked

[kyle-sexton]

Summary

PR #2521 (perf(rate-limit-guard): spool the statusline snapshot, drain it on a cadence, merged 2026-08-12) is a performance change whose headline measurement — render.sh alone 234.4 ms vs behind the wrapper 1047.1 ms (Windows/MSYS, n=9, same-window) — was produced by a benchmark harness that lives only in an untracked local scratch directory. git ls-files finds no trace of it on any branch. If that directory is deleted, the marketplace's only perf-sensitive render path has a merged optimization nobody can re-measure and no way to catch a regression that quietly reintroduces the cost.

Evidence

The scratch directory (D:/worktrees/rlg-scratch, not a git repo) holds seven files from the Aug-12 benchmarking session:

file	verdict	why
lib-bench.sh	keep	the methodological core: spawn-floor control (the MSYS process-creation floor that dominates every number and invalidates cross-run comparison when it moves), the canonical statusline payload fixture, now_ms/median helpers
bench-idle.sh	keep	the lane that produced the headline numbers: N sequential renders, floor before/after, median + mean
bench-load.sh	keep	the concurrency lane: N virtual sessions rendering once a second for M seconds — the shape that stresses the spool/drain election
trace-probe.sh	keep	the xtrace probe that verifies the non-elected render path stays fork-free before passthrough — the property #2521 exists to protect
gates.sh	discard	throwaway wrapper around repo CI gates, hardcoded to a worktree path that no longer exists; CI and scripts/run-plugin-tests.sh own this
pr-body.md	discard	byte-identical to #2521's merged body (the PR adds only a ## Related section)
gates.log	discard	empty

The four keepers still reflect the current tee: the spool path, .last-drain stamp, RLG_TEE_DRAIN_INTERVAL override, and {"e":…,"p":…} record shape all match plugins/rate-limit-guard/scripts/statusline-tee.sh at head.

Proposal

Commit the four scripts to plugins/rate-limit-guard/bench/ (sibling to scripts/, matching the tests//tools/ plugin-root precedent elsewhere in the repo), lightly adapted:

• drop the machine-specific STATUSLINE_ENTRY default (~/.claude/statusline/entrypoint.sh) in favor of the repo's own tee in standalone mode, resolved relative to the bench dir — runnable from a clean checkout
• default trace-probe.sh's tee argument to the repo copy the same way
• add bench/README.md recording what perf(rate-limit-guard): spool the statusline snapshot, drain it on a cadence (0.7.0) #2521 measured, on what platform, with what discipline (spawn-floor bracketing), and how to re-run each lane — including how to isolate a run from the machine's live ~/.claude/rate-limit-guard/ contract file

Deliberately no CI wiring: a wall-clock benchmark on shared runners is noise, not a gate, and the repo's test runner discovers only plugins/**/*.test.sh — none of these use that suffix, so nothing new runs in CI. Plugin version bump + changelog entry per repo convention, since the plugin directory's shipped contents change.

[kyle-sexton]

Archive: the one scratch file not committed by #2583

For completeness of the #2582 record. D:/worktrees/rlg-scratch/gates.sh was the seventh file in the
original scratch directory and the only one not carried into plugins/rate-limit-guard/bench/.

Verdict at the time, unchanged: not worth committing. It hardcodes cd /d/worktrees/rlg-statusline-perf
— a worktree that no longer exists — and every gate it wraps is already run by CI and by
scripts/run-plugin-tests.sh. It is preserved here only so the scratch directory holds nothing unique,
not because it should be resurrected.

#!/usr/bin/env bash
# Scratch: run every repo gate this change must clear, recording each RC.
set -uo pipefail
cd /d/worktrees/rlg-statusline-perf || exit 1
run() {
  local label="$1"
  shift
  echo "=== $label ==="
  "$@" 2>&1 | tail -25
  echo "RC[$label]=${PIPESTATUS[0]}"
  echo
}
run "changelog --check" bash scripts/check-changelog-parity.sh --check
run "changelog --check-order" bash scripts/check-changelog-parity.sh --check-order
run "changelog --check-bump" bash scripts/check-changelog-parity.sh --check-bump origin/main
run "changelog --check-preserved" bash scripts/check-changelog-parity.sh --check-preserved origin/main
run "shell portability" bash scripts/check-shell-portability.sh
if command -v shellcheck >/dev/null 2>&1; then
  run "shellcheck" shellcheck -x \
    plugins/rate-limit-guard/scripts/statusline-tee.sh \
    plugins/rate-limit-guard/scripts/statusline-tee.test.sh
else
  echo "=== shellcheck ==="
  echo "shellcheck not installed locally"
  echo
fi
if command -v shfmt >/dev/null 2>&1; then
  run "shfmt -d" shfmt -d plugins/rate-limit-guard/scripts/statusline-tee.sh plugins/rate-limit-guard/scripts/statusline-tee.test.sh
fi
echo "ALL GATES DONE"

The other six files are accounted for: lib-bench.sh, bench-idle.sh, bench-load.sh, and
trace-probe.sh are committed under plugins/rate-limit-guard/bench/; pr-body.md is verbatim in
merged PR #2521's body; gates.log was empty.