Never Trust a Single Pass: Convergence-Loop for Agents

Where this fits

Your agent runs the test suite, sees one failure, fixes it, reruns green, and reports done. Then the fix breaks something else. convergence-loop makes "truly passed" mean surviving N rounds of FAIL→FIX→re-verify, and it escalates to a structural redesign if the loop cannot converge.

Why agents benefit

• Stops treating the first green run as success; re-runs after every fix to expose newly introduced failures.
• Uses a finite round budget: no premature "done", no infinite retry; if N rounds fail, it escalates to redesign.
• Applies to any gate—tests, lint, schema validation, security checks—so verification behavior is consistent.
• Recognizes natural language triggers like "run until it passes" or "suspicious of single-pass", so it is easy to invoke.
• Leaves an explicit FAIL→FIX→re-verify trace, making agent output easier to audit and debug.

Practical scenarios

CI gate after a refactor

After a refactor, the first test run fails, and the agent's patch breaks a dependent test. The loop keeps going until the full suite passes for N rounds, so the PR isn't merged on a fragile single run.

Data pipeline validation

A schema migration passes syntax validation but fails integrity checks. The agent fixes transforms, then re-validation catches a second mismatch. Only repeated convergence marks the pipeline clean.

Docs and code review gate

Generated docs show broken anchors. The agent adds them, but the new headings violate style rules. Round two catches that; otherwise the docs would ship with a false clean signal.

Add it to your agent workflow

Install from the forge-harness library:

npx skills add chrono-meta/forge-harness --skill convergence-loop

Then invoke it directly:

/convergence-loop Verify the auth service after adding rate limiting.
Keep fixing until all tests pass for three rounds.

Compare before adopting

Compare quality signals: repo maintenance, release cadence, issue responses, and whether the skill is compatible with your agent runtime. Also compare alternatives—a shell script, a CI gate, or another skill—and ask if your workflow actually suffers from single-pass false positives. If not, the extra loop may be overhead.

Why it is worth tracking

convergence-loop is small (14 stars), but it speaks to a common agent failure: declaring victory too early. The idea of a universal convergence gate is likely to grow as multi-step agents move toward production. Track it when "single pass isn't enough" becomes a regular phrase in your reviews. For a maintained view of releases and community signals, see its page on OpenAgentSkill.