Enforce every hard stop outside the agent's reach; correct and condense the knowledge base

[espi]

This is the follow-up from reviewing and merging #21–#25. It has three commits, and each can be reviewed or reverted on its own.

1. 46d7214: the loops this repo ships could fail to stop

Two findings from #25 apply to this repo's own templates. I checked both against the primary sources before changing anything.

• Claude Code < v2.1.281 could retry a turn indefinitely while ignoring --max-turns (changelog, Sep 23). templates/ralph/run.sh passed no per-call cap and had no timeout. Its cost meter returned 0 unless you wired one in. Its counter only ticks between calls, so a runaway call would never return to it.
• The ralph-wiggum plugin's iteration cap is in a file the agent can write. It's stored in .claude/ralph-loop.local.md, and stop-hook.sh:51 only enforces it when max_iterations is greater than 0. An agent can remove its own cap. new-loop, first-loop.md, overnight-build.md and ui-audit-overnight.md all recommended the plugin as the cap.

What run.sh does now:

• It refuses to run on Claude Code < 2.1.281, or if there's no timeout/gtimeout.
• Every call gets --max-turns, --max-budget-usd (set to the remaining budget) and a wall-clock timeout.
• Spend is read from the CLI's own --output-format json total_cost_usd. If a call times out or returns no cost, the loop stops instead of guessing.
• PROTECTED_PATHS fingerprints the prompt, harness and tests. If the agent edits its own checks, the loop stops.
• Stall detection hashes the whole worktree, so empty commits don't count as progress.
• It is deny-by-default (--permission-prompts none) with an --allowedTools allowlist.

Tested: every exit path against a stub CLI (old version, done, bad check, stall, tampering, budget, iteration cap, no JSON, timeout), plus one real run on v2.1.284 (it metered $0.043 and exited 0).

Documentation updated to match:

• guardrails/ (README, checklist, budget.env, which gains per-call caps and CLAUDE_CODE_MAX_TURNS)
• the loop-guardrails and new-loop skills
• CLAUDE.md, with the principle "the meter must not live inside the thing it meters"
• three runbooks. The UI-audit runbook now runs headless through run.sh; the plugin is a supervised fallback only.

self-edit-guard now runs on PRs to any base, and on edited. Stacked PRs from the routine (#23, #25) and PRs retargeted to main previously skipped it. You approved this change.

2. 9637d3c: the primer gets a size budget

The primer grew from 559 lines (Jul 21) to 3,303 (Sep 28). Nothing capped it, so a one-off trim would have grown back.

• Step 5 of the update-knowledge skill: the primer changes only when the state of the practice changes, and detail goes to sources.md. This is an unprotected region, and a human-authored change, not a self-edit.
• The new kb-size.yml fails any PR that leaves the primer over 750 lines.

3. 09e3980: knowledge-base corrections and condensed primer

Corrections (verified against primaries):

• claude plugin eval was not "the three hard stops as a CLI flag set". Its caps are per-case frontmatter fields, it has no stall detection, and it wasn't the first turn-plus-dollar cap.
• Three version numbers are fixed.
• SWE-Proof is pinned to v1.
• SaltBench's rule is filed under hard stop knowledge: 2026-06-22 update pass (7-day delta from Jun 15) #3.
• The METR URL is added.
• arXiv:2609.19844 is re-characterised.
• A stale note about the weekly whats-new digest is corrected.

Backlog:

• Two items were dropped without archiving. The CSA/METR "~700 agents" item is restored, because its correction was itself wrong. The OpenAI research-spend caveat is archived.
• Five human calls decided by commit 1 and guardrails: containment as a required companion, verify-the-agent rule, and retiring a subagent cap that no longer exists #21 move to the archive.

Primer: 3,303 → 661 lines.

• The §1–§7 structure is kept, and every load-bearing fact still carries a confidence tag.
• All removed prose is kept verbatim in archive/primer-detail-2026-09.md, and the per-claim records stay in sources.md.
• A line-level check shows that the only old primer lines not present verbatim somewhere in knowledge/ are the ones these corrections replaced.

Worth a closer look

• Behaviour changes in templates/ralph/run.sh.
  • It now stops when a call times out, because the call's spend is unknown.
  • It needs timeout. On macOS, that means brew install coreutils.
  • The default AGENT_CMD is deny-by-default, so a build loop needs an --allowedTools allowlist.
• Open question: review-tool spend caps. The condensing agent flagged a contradiction in the old §5A about which review tools ship enforced spend caps. The new text avoids the contradictory blanket claim; you may want to settle it.
• What CI checks. Both workflows are checked locally (YAML valid; self-edit-guard OK). kb-size will run for the first time on this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YAFQxQa6sakZp18SoDhMP7

---

Generated by Claude Code