/convergence-monitoring

name: convergence-monitoring
user-invocable: false
tags: [autoresearch, convergence, loop-control, wave-executor]
model: haiku
model-preference: sonnet
model-preference-codex: gpt-5.4-mini
model-preference-cursor: claude-sonnet-4-6
description: >
  Monitor iterative improvement loops for convergence. Three signals — shrinking diff,
  pass-rate plateau, velocity — drive a Stop/Continue/Investigate decision at each
  inter-wave checkpoint. Distinct from /evolve (retrospective) and session-reviewer
  (wave output review): convergence-monitoring answers "are we making progress?" not
  "was the last wave correct?". Primary consumer: /autoresearch loops and wave-executor
  inter-wave checkpoints.
attribution: >
  Inspired by cavekit's documented convergence-monitoring concept (MIT, Julius Brussee).
  Implemented from spec since upstream skill not yet published as of 2026-04-30.

> **Platform Note:** State files use the platform's native directory: `.claude/` (Claude Code), > `.codex/` (Codex CLI), or `.cursor/` (Cursor IDE). Shared metrics live in > `.orchestrator/metrics/`. See `skills/_shared/platform-tools.md`.

Convergence-Monitoring Skill

Platform-native (CC 2.1.105+)

This skill's watcher is registered as a plugin monitor via `.claude-plugin/plugin.json`'s `experimental.monitors` reference to `monitors/monitors.json`. Each session that loads this plugin auto-starts the watcher in the background (see `scripts/lib/convergence-monitor.mjs`). Each NDJSON stdout line from the watcher becomes a `<task_notification>` event Claude sees mid-session.

For harness < 2.1.105 (no monitor support), the skill's manual probes documented below serve as the fallback path.

When to Invoke

This skill is `user-invocable: false` — there is no `/convergence-monitoring` slash command. It is reached two ways:

**Platform-native monitor (primary path, CC 2.1.105+):** the background watcher below auto-starts on `wave-executor` invocation and streams verdicts as it tails `events.jsonl` — no explicit call needed.

**Direct/model invocation (fallback, harness < 2.1.105, or a standalone assessment):** the model dispatches this skill by name — reads wave history from `.orchestrator/metrics/events.jsonl`, computes all three signals, reports verdict + recovery options.

**Embedded (loop context):** `/autoresearch` and `wave-executor` invoke this skill after each Impl-Core or Impl-Polish wave when `convergence-monitoring: true` is set in Session Config. The skill returns a structured verdict that the caller uses to gate the next wave.

**NOT a substitute for quality gates.** Quality-gates verify correctness (typecheck, test, lint). Convergence-monitoring verifies *progress direction* — whether the work is moving toward done or oscillating/stalling.

---

Phase 0: Activation Gate

0.1 Direct Invocation

If invoked directly (not embedded from `wave-executor` or `/autoresearch`), skip to Phase 1 unconditionally.

0.2 Embedded Invocation

When called from `wave-executor` or `/autoresearch`, check:

1. Read Session Config per `skills/_shared/config-reading.md`. Store as `$CONFIG`. 2. Check `$CONFIG."convergence-monitoring"`. If the field is absent or `false`, return verdict `SKIP` immediately — the caller MUST NOT block on a skipped monitoring call. 3. Require `$WAVE_NUMBER` (integer, current wave) and `$SESSION_START_REF` (git SHA) to be provided by the caller. If either is absent, emit warning and return `SKIP`. 4. Require at least **2 completed waves** of history. If `$WAVE_NUMBER < 2`, return `SKIP` — not enough data to assess trend.

---

Phase 1: Signal Collection

Read wave history from `.orchestrator/metrics/events.jsonl`. Filter to records matching `$SESSION_START_REF` and `event_type` in `{wave.start, wave.end, quality.incremental}`.

Compute the three signals in parallel. Each signal produces:

{ signal: "<name>", value: <float>, trend: "improving" | "plateau" | "regressing", confidence: 0.0-1.0 }

Signal 1 — Shrinking Diff (SD)

Measures: is the diff still shrinking, or has it reached noise level?

**Computation:**

diff_sizes[] = [git diff --stat $wave_N_start_ref $wave_N_end_ref | tail -1 | grep -oE '[0-9]+ insertion' | awk '{print $1}']
  for each completed wave in this session

• `value` = ratio of latest wave diff to peak diff (0.0 = unchanged, 1.0 = as large as ever)
• `trend`:
• `improving` — diff_sizes shrinking monotonically for last 2 waves (value < 0.6)
• `plateau` — diff_sizes stable within ±15% for 2+ consecutive waves (value 0.0–0.15)
• `regressing` — diff_sizes growing (value > 1.0 relative to prior wave)
• `confidence` = min(1.0, completed_waves / 3) — unreliable below 3 waves

**False positive flag:** A plateau on diff size with a *large* diff is not convergence — it may be an oscillation. Cross-check with Signal 3 (velocity) before concluding.

Signal 2 — Pass-Rate Plateau (PR)

Measures: has the test pass-rate stabilized at a level (high or low)?

**Computation:** Read `quality.incremental` events from `events.jsonl` for this session. Extract `test.passed / test.total` per wave where the field is present.

• `value` = latest pass-rate (0.0–1.0)
• `trend`:
• `improving` — pass-rate strictly increasing across last 2 waves
• `plateau` — pass-rate within ±2% for 2+ consecutive waves
• `regressing` — pass-rate decreasing
• `confidence` = min(1.0, quality_events_count / 2)

**False positive flag:** A plateau at 1.0 (100% pass) is the desired end-state. A plateau at < 0.9 with no improving trend is a ceiling signal — see Phase 3.

Signal 3 — Velocity (VEL)

Measures: commits and modified-line count per wave — declining velocity is normal as work nears completion; zero velocity for 2+ waves is a stall.

**Computation:**

commits_per_wave[] = [git rev-list --count $wave_N_start_ref..$wave_N_end_ref]
lines_per_wave[]   = [git diff --shortstat $wave_N_start_ref $wave_N_end_ref | awk '{print $4+$6}']
  for each completed wave