goal-convergence

Goal Convergence

Goal-oriented autonomous loop with external completion oracle.

Based on Addy Osmani's Loop Engineering principle: "Keep going until a verifiable

stopping condition holds, with a separate small model checking completion."

When to Activate

• User invokes /goal command
• Heartbeat auto-creates a goal from scan failures
• Triage item is promoted to a goal via /triage act <id> goal
• Session resumes with an active goal state file

Core Concept: Maker-Oracle Separation

The model that wrote the code is too nice grading its own homework.

A second model (the oracle) with different instructions and READ-ONLY tools

catches what the first talked itself into.

Maker (primary model, full tools)
  │
  ▼ produces iteration output
  │
Oracle (different model, read-only)
  │
  ├─ ALL conditions pass → CONVERGE (goal done)
  ├─ Some fail + budget remains → nextHint → LOOP (maker iterates)
  └─ Budget exhausted → ESCALATE (triage inbox)

Goal Lifecycle

CREATE → ACTIVE → [iterate] → CONVERGED
                       │
                       ├──── PAUSED (manual /goal pause)
                       └──── ESCALATED (budget exhausted or repeated failure)

States:

• active: Maker-oracle loop is running
• paused: Manually paused, resumes with /goal resume
• converged: All stopping conditions met, goal complete
• escalated: Cannot converge within budget, needs human triage
• failed: Explicitly abandoned

Stopping Conditions

Each goal has one or more stopping conditions. ALL must pass for convergence.

| Type | Command Pattern | Example |

|------|----------------|---------|

| test_pass | Test runner exits 0 | npm test |

| lint_clean | Linter exits 0 | npm run lint -- --quiet |

| coverage_threshold | Coverage >= N% | npm test -- --coverage |

| build_pass | Build succeeds | npm run build |

| custom_command | Any command exits 0 | grep -r "TODO" src/ \| wc -l |

Oracle Protocol

The oracle receives:

1. The goal objective (natural language)
2. All stopping condition commands and their latest output
3. The maker's iteration summary
4. Previous iteration history (last 3)

The oracle returns:

{
  "converged": false,
  "conditionResults": [
    {"type": "test_pass", "passed": false, "output": "2 tests failing"},
    {"type": "lint_clean", "passed": true, "output": ""}
  ],
  "reasons": ["2 tests still failing in auth module"],
  "nextHint": "Focus on src/auth/refresh.test.ts — the token expiry mock is stale",
  "confidence": 0.85
}

Budget Management

Three budget dimensions, any exhaustion triggers escalation:

| Dimension | Default | Rationale |

|-----------|---------|-----------|

| Iterations | 15 | Prevents infinite loops |

| Wall time | 2h | Bounds real-world duration |

| Cost (USD) | $10 | Prevents runaway API spend |

On escalation, the goal:

1. Persists full state to ~/.claude/goals/{goalId}.json
2. Creates a triage inbox item with context
3. Marks state as escalated
4. Reports final status to user

Inter-Session Persistence

Goals survive session restarts:

1. SessionEnd hook serializes active goals
2. SessionStart hook detects active goals and notifies user
3. /goal resume re-enters the loop with oracle's last nextHint

State file: ~/.claude/goals/{goalId}.json (follows schemas/goal.schema.json)

Integration Points

• /heartbeat: Auto-creates goals from scan failures
• /triage: Escalated goals land in triage; triage items can become goals
• /checkpoint: Each iteration implicitly checkpoints
• /verify: Oracle internally uses verification patterns
• wave-execution: Multiple goals can run in parallel waves
• rework-loop: Failed iterations trigger blame-attributed rework

Hard Bans

• Oracle MUST be a different model than maker (eliminates self-grading bias)
• Oracle MUST NOT have write tools (prevents it from "helping" fix issues)
• Goals MUST have at least one stopping condition (no open-ended loops)
• Budget MUST have at least one limit set (no unbounded execution)
• State MUST persist to disk (no goals lost on crash)

Example

User: /goal "make all tests pass"

System infers:
  objective: "make all tests pass"
  stoppingConditions: [{type: "test_pass", command: "npm test"}]
  budget: {maxIterations: 15, maxDuration: "2h", maxDollars: 10}
  oracle: {model: "haiku"}

Iteration 1:
  Maker: reads test output, fixes obvious import error in auth.ts
  Oracle: runs `npm test` → 1 test still failing → {converged: false, nextHint: "..."}

Iteration 2:
  Maker: fixes token refresh logic based on oracle hint
  Oracle: runs `npm test` → all pass → {converged: true}

Result: CONVERGED in 2 iterations, $0.45 spent