convergence-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

# convergence-loop — Universal Convergence Loop Gate Reinforcement

> A single pass declaration is hard to trust. A fix exposes new FAILs, and round 2 catches what round 1 missed. convergence-loop assigns a "truly passed" criterion to any gate.

## Triggers

- `/convergence-loop`
- "convergence-loop", "how many rounds do we need", "not sure if it really passed"
- "suspicious of single-pass", "run until it passes", "keep verifying until clean"
- "single pass isn't enough", "need another round", "the fix might have introduced new issues"
- Auto-proposed: when the same artifact receives a FAIL verdict 2+ times in the same session (observable: 2nd FAIL on identical scope)

---

## Origin

Extracted from a recurring "single-pass gate is hard to trust" pattern observed across multiple hub workflows. The canonical reference is:
- `harvest-loop` extract→attack→synthesize cycle: pattern extraction → attack → synthesis → the repeating structure must run until convergence

When the same structure recurs across gates, it is a skill.

## Applicable Targets

| Applicable Gate | Example |
|---|---|
| Skill diagnostic gate | harness-doctor + apex-review |
| Session harvest loop | harvest-loop extract→attack→synthesize cycle |
| External asset audit | steel-quench Wave 1~N |
| Domain-specific quality gate | Plug in any project-defined FAIL→FIX checkpoint |
| Any FAIL→FIX repeating structure | User-defined gate |

---

## Pipeline Structure

```
[Input] gate name + pass criteria + max rounds N (default 3)
    │
    ▼
Round 1
    │  Execute gate
    │  → All items pass: ✅ Round 1 passed → Round 2 (verification)
    │  → FAIL occurs: List FAIL items → Execute FIX → Round 2
    │
    ▼
Round N (N ≥ 2)
    │  Re-execute same gate (with FIX applied + search for new FAILs)
    │  → All items pass AND no FIX was applied in response to THIS round:
    │        ✅ Declare truly passed  ← the only terminating exit
    │  → All items pass BUT you fixed something this round (any severity):
    │        the fix is unverified → Round N+1
    │  → New FAIL: List → FIX → Round N+1
    │
    ▼
    │  → FAILs remain after N rounds: "Structural redesign required" → Escalate
    │  → Rounds clean but each keeps producing fixes: the fixes are manufacturing the
    │    findings → REDUCE THE DESIGN, then re-run (steel-quench §Convergence Criteria 4)
    │
    ▼ (if not converged within N rounds)
Escalation
    → Classify root cause: ambiguous criteria / FIX capability limit / gate design flaw
    → Output recommended action
```

**Core principle**: A fix exposing new FAILs is not a failure — it is a **signal that the gate is working correctly**. The deeper the round, the more fundamental the FAILs it uncovers.

---

## Execution Guidelines

### Setup (confirm before running)

```
Gate name:       [what checkpoint is this]
Pass criteria:   [specify pass condition — "all items ✅" or concrete criteria]
Max rounds:      [default 3; simple gates 2; complex gates up to 5]
FIX owner:       [auto-fixable / requires human / mixed]
Escalation:      [who to escalate to / how, if not converged within N rounds]
```

### Per-Round Execution Rules

**What must stay constant across rounds**:
- Pass criteria are immutable (no relaxing criteria per round)
- Cumulative tracking of FAIL items (verify that prior-round FAILs were fixed)
- New FAILs explicitly labeled (distinguish newly surfaced items from fix chain)

**What changes across rounds**:
- FIX-applied targets (revised TCs, skills, documents)
- FAIL list (should shrink; growth is also acceptable — it means items are surfacing)

### Convergence Judgment

```
Convergence = a round returns 0 new FAILs AND no FIX was applied in response to it
Conditions to declare truly passed:
  1. All items pass AND
  2. Nothing was changed in response to THIS round, at any severity
     (a FAIL you accept as residual is terminal; a FAIL you fix is not — the fix is unverified) AND
  3. At least 2 rounds executed (a single clean round is "provisionally passed" only)
     ← condition 3 is NOT redundant with 2 and was nearly lost when 2 replaced it: freezing answers
       "did the artifact change under the audit", min-2 answers "is one look enough". Independent
       questions, both still open. Done When and the pipeline diagram enforce min-2 as well.
NOT "0 new FAILs across 2 consecutive rounds": while every round ships fixes that can never fire,
so it reads as permanently not-converged and gets shipped past anyway. Stricter form for quench
waves: steel-quench §Convergence Criteria.
```

### Escalation Root Cause Classification

| Cause | Signal | Recommended Action |
|---|---|---|
| Ambiguous pass criteria | Same item judged differently each round | Restate criteria explicitly, then restart |
| FIX capability limit | FAILs detected but fix method unknown | Bring in expert or reduce scope |
| Gate design flaw | Same FAIL repeats after N rounds | Redesign the gate itself → meta-prompt-builder |

---

## Output Format

From chrono-meta/forge-harness, MIT.

More from chrono-meta/forge-harness