convergence-monitoring

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

Explicit invocation (/convergence-monitoring): Standalone assessment — 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 Explicit Invocation

If invoked via /convergence-monitoring, 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.

1. 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.

1. 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 in this session

• value = lines changed in latest wave (raw integer, not ratio)
• trend:
• improving — commits or lines increasing (unusual mid-loop; flag for review)
• plateau — < 5 lines + 0 commits in latest wave
• regressing — lines declining (normal trajectory near convergence)
• confidence = min(1.0, completed_waves / 2)

Phase 2: Convergence Decision Table

Aggregate signal trends into a single verdict. Apply the table top-to-bottom; use the first matching row.

| SD trend | PR trend | VEL trend | Verdict | Rationale | |------------|------------|------------|---------------|--------------------------------------------------------------| | plateau | plateau | plateau | STOP | All three signals stable — loop has converged. | | plateau | plateau | regressing | STOP | Velocity decline + stable quality — natural wind-down. | | improving | improving | regressing | CONTINUE | Still making progress. Velocity decline is expected. | | improving | plateau | regressing | CONTINUE | Diff still shrinking; pass-rate already high. | | plateau | improving | regressing | CONTINUE | Pass-rate catching up; diff mostly stable — finishing work. | | regressing | any | improving | INVESTIGATE | Diff growing and velocity up — scope expansion or churn. | | any | regressing | any | INVESTIGATE | Pass-rate declining — regressions introduced. | | plateau | plateau | improving | INVESTIGATE | Stable diff + stable quality but velocity up — odd state. | | any | any | plateau | INVESTIGATE | Velocity zero for 2+ waves — stall or early plateau. |

Confidence gate: If any signal has confidence < 0.5, downgrade STOP → CONTINUE and INVESTIGATE → CONTINUE (not enough data to act confidently on a Stop or Investigate). Emit a note: low-confidence: <signal-names>.

Verdict Output (structured)

{
  "verdict": "STOP | CONTINUE | INVESTIGATE | SKIP",
  "signals": {
    "shrinking_diff": { "trend": "...", "value": 0.0, "confidence": 0.0 },
    "pass_rate":      { "trend": "...", "value": 0.0, "confidence": 0.0 },
    "velocity":       { "trend": "...", "value": 0,   "confidence": 0.0 }
  },
  "low_confidence": [],
  "notes": []
}

Emit verdict JSON to stdout. Append one JSONL record to .orchestrator/metrics/events.jsonl with event_type: convergence.checkpoint.

Phase 3: Non-Convergence Diagnosis

Execute this phase when verdict == INVESTIGATE. Skip if verdict is STOP or CONTINUE.

The core question: ceiling or convergence?

• Convergence — the work is done; signals stabilized at the desired state (pass-rate ~1.0,

diff ~0). Stop is the right action but signals were ambiguous.

• Ceiling — progress has halted but the desired state has NOT been reached. Something

is blocking further improvement.

3.1 Ceiling vs Convergence Dichotomy

| Observable | Classification | |-----------------------------------------------|------------------| | pass-rate plateau ≥ 0.95, diff plateau ≈ 0 | Convergence | | pass-rate p