gitreins-tier2-iteration-cap-exceeded

Answer 1

Done. Deliverable is at /workspace/SOLUTION.md (with the two runnable helpers at /workspace/gitreins-fix-cap.py and /workspace/gitreins-fix-cap.sh).

Root cause

The tier-2 iteration ceiling is enforced at two layers, and the binding value is:

effective_cap = MIN(stage.max_iterations, evaluator.max_iterations)

So raising only one knob (the usual "obvious" stage edit) leaves MIN(...) unchanged and the next gitreins task complete re-caps with the same INCOMPLETE — Cap exceeded message. The neighboring input-token knob must also be re-sized from measured burn:

tpi = Σ input_tokens / Σ iterations   (from .gitreins/usage.jsonl)
new_token_budget = ceil(tpi × new_cap × 1.15)

Fix

Raise max_iterations one rung (400 -> 600) in both blocks, scale the token neighbor, commit as chore, re-run gitreins task complete. The wrapper does all of it and hard-fails if MIN(stage,evaluator) did not strictly increase; the config fixer is a comment/format-preserving regex editor (works with max_iterations/iterations/iteration_cap and auto-detects the token key).

Verification

I reproduced the exact proven transition against a stub judge on a synthetic repo:

INCOMPLETE Cap exceeded: Iteration cap (400) reached  verdict=788c0b69
        ↓  effective cap 400 -> 600, token neighbor 120000 -> 206000, chore commit
verdict=3bd6a682 result=PASS evidence=complete tier1=PASS tier2=PASS

Also verified edge cases: per-iteration usage.jsonl records (tpi=300), missing usage.jsonl (cap still raised, token knob untouched), off-ladder caps (falls back to +200), and comments preserved in the YAML.

The markdown includes both the automated fast path and an equivalent no-script manual path, plus acceptance criteria and a rollback/troubleshooting section.

Answer 2

Wrote the solution to ~/gitreins-tier2-iteration-cap-exceeded.md.

What I did

I found the environment had a broken gitreins symlink, so I installed the exact pinned gitreins==0.15.0, then verified the mechanism directly against its source and a real repo rather than just restating the brief.

Key findings (verified, not assumed)

• -1 means "defer", not "unlimited". In engine/pipeline.py::_run_ai_eval (0.15.0), the stage's max_iterations is only added to explicit_caps when it is not None/-1. A -1 stage constructs AgenticEvaluator(...) with no explicit cap, which then loads evaluator.max_iterations (default 100).
• The MIN framing is correct: MIN(∞ from stage -1, 100) = 100. I also verified a finite stage cap (50) still binds over a larger evaluator cap (300).
• The fix works: bumping only evaluator.max_iterations 100 → 300 raises the effective cap to 300 (confirmed with a harness on the installed engine).
• GITREINS_MAX_ITERATIONS=300 is a verified one-off override that wins over YAML.
• Re-run requires task start: start() sets in_progress; re-running complete on an already-complete task never resets state (confirmed with the real CLI state machine).

Contents of the document

1. TL;DR
2. Symptom (exact Iteration cap (100) reached … message)
3. Root cause with 0.15.0 source snippets, MIN semantics, and the task-state no-op
4. Exact fix (comment-preserving Python patcher for the evaluator: block) + diff + re-run commands + CI env alternative
5. Verification (cap-resolution harness output, task state-machine transcript, acceptance checks)
6. Gotchas (defaults vs evaluator, token/time caps, task start requirement)

The /tmp/gr_repo setup remains if you want to inspect the live reproduction; the generated gitreins init default was 15 iterations, which I patched to 300 to validate the script.

Answer 3

Wrote the solution to /workspace/solution.md. Summary:

Diagnosis: gitreins Tier-2 judge is an agentic verification loop bounded by an iteration budget defaulting to 100. Doc-heavy tasks (DOC-004: ~50 citation tests) need more verification rounds than that, so the loop aborts with INCOMPLETE — iteration cap (100) exceeded. The verdict reflects budget exhaustion, not a code/test failure.

Root cause: The cap is read from the GITREINS_MAX_ITERATIONS env var by the judge loop; the default is too low for doc-heavy verification workloads.

Fix (no config/code change):

GITREINS_MAX_ITERATIONS=300 gitreins task start <id>
GITREINS_MAX_ITERATIONS=300 gitreins judge --async <id>

(Or export GITREINS_MAX_ITERATIONS=300 first so every async child process inherits it.)

Verification: On DOC-004, the default-budget run returned INCOMPLETE (cap 100); the rerun with GITREINS_MAX_ITERATIONS=300 returned PASS, verdict id 81d0d79a, in ~2 min — with the tree unchanged, isolating the budget as the only cause.

Note: the live environment here has no working gitreins install (broken pipx symlink) and no digest repo, so the verification is documented from the supplied context rather than re-executed in this sandbox. The document includes a log-grep check and explicit acceptance criteria so it can be re-verified wherever gitreins is installed.

Answer 4

Wrote the solution to ~/gitreins-tier2-iteration-cap-exceeded.md.

What I did

I found the environment had a broken gitreins symlink, so I installed the exact pinned gitreins==0.15.0, then verified the mechanism directly against its source and a real repo rather than just restating the brief.

Key findings (verified, not assumed)

• -1 means "defer", not "unlimited". In engine/pipeline.py::_run_ai_eval (0.15.0), the stage's max_iterations is only added to explicit_caps when it is not None/-1. A -1 stage constructs AgenticEvaluator(...) with no explicit cap, which then loads evaluator.max_iterations (default 100).
• The MIN framing is correct: MIN(∞ from stage -1, 100) = 100. I also verified a finite stage cap (50) still binds over a larger evaluator cap (300).
• The fix works: bumping only evaluator.max_iterations 100 → 300 raises the effective cap to 300 (confirmed with a harness on the installed engine).
• GITREINS_MAX_ITERATIONS=300 is a verified one-off override that wins over YAML.
• Re-run requires task start: start() sets in_progress; re-running complete on an already-complete task never resets state (confirmed with the real CLI state machine).

Contents of the document

1. TL;DR
2. Symptom (exact Iteration cap (100) reached … message)
3. Root cause with 0.15.0 source snippets, MIN semantics, and the task-state no-op
4. Exact fix (comment-preserving Python patcher for the evaluator: block) + diff + re-run commands + CI env alternative
5. Verification (cap-resolution harness output, task state-machine transcript, acceptance checks)
6. Gotchas (defaults vs evaluator, token/time caps, task start requirement)

The /tmp/gr_repo setup remains if you want to inspect the live reproduction; the generated gitreins init default was 15 iterations, which I patched to 300 to validate the script.

Answer 5

Written to ~/gitreins-tier2-iteration-cap-fix.md.

Diagnosis summary

The tier‑2 INCOMPLETE / Cap exceeded: Iteration cap (N) reached is a judge-loop ceiling, not a task failure. It comes from .gitreins/config.yaml:evaluator.max_iterations, with precedence:

GITREINS_MAX_ITERATIONS (env) > .gitreins/config.yaml:evaluator.max_iterations > default 100

Two traps: -1 means defer to default (100), not unlimited; and env overrides silently win over YAML edits.

Fix (gitreins 0.15.0)

cd /path/to/repo
export GITREINS_MAX_ITERATIONS=300   # env override, wins over YAML
gitreins task start <task-id>
gitreins judge --async <task-id>
gitreins judge --status <job-id>

Resume via task start + judge — not task complete, since complete on an already-complete task never resets state. Use judge --async + judge --status because foreground/background complete re-runs are SIGTERM-prone at ~96 minutes.

Verification: gitreins config get evaluator.max_iterations reports 300; a re-run converges to VERIFIED/PASS (or, if it still fails, reports the new 300 cap, proving the override applied).

Note: on this host the gitreins symlink is broken (~/.local/share/pipx/venvs/gitreins missing) and no .gitreins/ tree exists, so the commands could not be executed here — the document is based on the verified 0.15.0 behavior given in the task context.