feat(claude-blocking-review)!: drop --max-turns cap (v3) - #62
Merged
Conversation
Reviews were getting force-killed mid-run on small/medium diffs because the auto-estimator's turn floor (15) was tighter than reality. The "Review did not complete (likely exceeded turn limit or timed out)" failure mode hit ralph-burndown PR #119 and #122 in the same week. Diagnosis: PR #122 (288 lines, 4 files) hit the failure at ~4 min elapsed against a 9-min wall-clock timeout — well before the timeout could have fired. Max turns was the actual constraint. The estimator's 1.44-compounded buffer was insufficient because the agent's natural rhythm doesn't fit a fixed turn budget; tightening or loosening the floor would just shift the same failure mode. The right shape is to remove the artificial cap entirely and let the agent be bounded by: - the prompt's own scope discipline (soft constraint) - the wall-clock timeout-minutes (hard safety net) - the OAuth subscription quota (hard ceiling on cost) Subscription billing means unused turns are free — only actual elapsed time matters. Generous wall-clock with no turn cap is the right posture. Changes: - Remove `--max-turns` from `claude_args`. Remove the `max_turns` input parameter cleanly (caller workflows passing it now fail validation — intentional; internal-only callers in smartwatermelon/nightowlstudio orgs migrate to v3 deliberately). - Re-base `timeout_minutes` estimation on diff size directly: `10 + lines/100` minutes, floor 10, cap 30. Floor raised from 4 to 10 since the wall-clock is now the only hard backstop. - Tighten the prompt's scope constraints with explicit self-bounding: 3-file ceiling per hypothesis, "tight PASS / thorough BLOCK is a successful review; meandering exploration is wasted." Without a turn cap the prompt does the load-bearing work of keeping reviews focused. - Update example caller snippet `@v1` → `@v3`. - Update README migration table and `with:` example. Caller migration: remove any `max_turns:` input from your caller workflow. v2 remains supported for callers that haven't migrated. BREAKING CHANGE: the `max_turns` input parameter is removed. Callers on @V3 must remove the input from their workflow or workflow validation will fail. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ved --max-turns Codebase review on the v3 commit caught two follow-on misses where the "exceeded turn limit" wording survived in error messages and a comment even though v3 removes the only cause of that error path. Without --max-turns the step can no longer hit a turn cap; the only remaining no-verdict failure modes are wall-clock timeout or a Claude-side agent error. Updated the verdict-fallback messages and the workflow-self-modification skip comment to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codebase review caught the ### Auto-sizing section still documenting the v2 behavior — "Max turns" row, old timeout formula `turns × 30s`, "turn budget is intentionally tight" framing. A v3 caller copying from that table would write `max_turns:` and fail validation. Drop the Max turns row, replace the Timeout row formula with the new `10 + lines/100` direct calc, update the lead paragraph to reflect that wall-clock is now the sole hard bound. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reviews on small/medium diffs were getting force-killed mid-run with "Review did not complete (likely exceeded turn limit or timed out)" — the actual cause was the auto-estimator's max_turns floor (15), not the wall-clock timeout. PR ralph-burndown#119 and #122 both hit it within a week. Tightening or loosening the floor would just shift the same failure mode; the right shape is to remove the artificial cap and let the agent be bounded by:
timeout-minutes(hard safety net)Subscription billing means unused turns are free — only actual elapsed time matters. Generous wall-clock with no turn cap is the right posture.
Changes
--max-turnsfromclaude_argsso the agent runs until the prompt naturally completes (or the wall-clock fires).max_turnsinput parameter cleanly. Caller workflows passing it now fail validation — intentional, since internal-only callers in smartwatermelon/nightowlstudio orgs migrate to v3 deliberately.timeout_minutesestimation on diff size directly:10 + lines/100minutes (floor 10, cap 30). Floor raised from 4 → 10 since the wall-clock is the only hard backstop now. Sample sizing: 100 lines → 11 min, 1,000 lines → 20 min, 2,000+ lines → 30 min cap.Max turnsrow from the Auto-sizing table, update the Timeout row formula, refresh the migration table, bump example caller to@v3.BREAKING CHANGE
Caller workflows passing
max_turns:will fail workflow validation when bumping to@v3. Migration: remove the input. v2 remains supported for callers that haven't migrated.Test plan
yq evalvalidates YAML structurebash -nvalidates all extractedrun:blocks parsev3.0.0, move floatingv3tag, then bump caller repos in a follow-up sweep (ralph-burndown, kebab-tax, financial-agent, kebab-tax-netlify, plus the smaller ones currently on @v2.0.1/v2.0.2 pergh search code)Commits in this PR
0458c4f— drop --max-turns cap (v3) — main behavior change + initial README updateb4b1e09— fix stale "exceeded turn limit" diagnostic in error path0d09ff2— README auto-sizing table follow-on🤖 Generated with Claude Code