session-orchestrator 3.16.0

package/skills/claude-md-drift-check/checker.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# checker.sh — POSIX wrapper for claude-md-drift-check.
+#
+# Usage:
+#   bash checker.sh [VAULT_DIR] [--mode warn|hard|off] [--include-path <glob>]... [--skip-* ...]
+#   VAULT_DIR=/path/to/vault bash checker.sh [--mode warn]
+#
+# Exit codes mirror checker.mjs:
+#   0 — no errors, or warn mode, or skipped
+#   1 — errors present and mode=hard
+#   2 — invocation or infra error
+#
+# Output: JSON report on stdout.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECKER_MJS="${SCRIPT_DIR}/checker.mjs"
+
+if [[ $# -ge 1 && -n "${1:-}" && "${1:-}" != --* ]]; then
+  export VAULT_DIR="$1"
+  shift
+fi
+: "${VAULT_DIR:=$PWD}"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo '{"status":"infra-error","reason":"node not found in PATH"}' >&2
+  exit 2
+fi
+
+if [[ ! -f "$CHECKER_MJS" ]]; then
+  echo "{\"status\":\"infra-error\",\"reason\":\"checker.mjs not found at $CHECKER_MJS\"}" >&2
+  exit 2
+fi
+
+export VAULT_DIR
+exec node "$CHECKER_MJS" "$@"

package/skills/claude-md-drift-check/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@session-orchestrator/claude-md-drift-check",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Narrative drift checker for CLAUDE.md and _meta/*.md. Path-resolver + project-count-sync + issue-reference-freshness + session-file-existence. Pure Node, no runtime deps.",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.0"
+  }
+}

package/skills/convergence-monitoring/README.md

@@ -0,0 +1,39 @@
+# convergence-monitoring
+
+Monitors iterative improvement loops (autoresearch, multi-wave sessions) for convergence.
+Answers: **"should this loop keep running?"** — distinct from `/evolve` (retrospective
+learning) and `quality-gates` (correctness verification).
+
+## 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.
+
+## File Inventory
+
+| File         | Purpose                                                                          |
+|--------------|----------------------------------------------------------------------------------|
+| `SKILL.md`   | Full skill spec — phases, decision table, diagnosis, recovery suggestions         |
+| `SIGNALS.md` | Signal reference — computation, thresholds, false positives, event schema         |
+| `README.md`  | This file                                                                         |
+
+## Invocation
+
+**Explicit:** `/convergence-monitoring` — standalone assessment from current session history.
+
+**Embedded:** Set `convergence-monitoring: true` in Session Config. `wave-executor` and
+`/autoresearch` will call this skill automatically after each Impl-Core/Impl-Polish wave.
+
+## Verdicts
+
+| Verdict       | Meaning                                       |
+|---------------|-----------------------------------------------|
+| `STOP`        | Loop has converged — declare done             |
+| `CONTINUE`    | Still making progress — run next wave         |
+| `INVESTIGATE` | Signals ambiguous or degrading — diagnose     |
+| `SKIP`        | Not enough data or monitoring disabled        |
+
+## See Also
+
+`skills/wave-executor/wave-loop.md` · `skills/evolve/SKILL.md` ·
+`skills/quality-gates/SKILL.md`

package/skills/convergence-monitoring/SIGNALS.md

@@ -0,0 +1,246 @@
+# Convergence-Monitoring — Signal Reference
+
+Companion to `SKILL.md`. Defines each signal precisely: how to compute it, what threshold
+means what, and what false positives look like. Consume this when implementing callers or
+debugging unexpected verdicts.
+
+---
+
+## Signal 1: Shrinking Diff (SD)
+
+**What it measures:** Is the volume of change still decreasing wave-over-wave?
+
+A well-converging loop should produce progressively smaller diffs — large changes early
+(scaffold, core logic), shrinking to fixes and polish, approaching zero at completion.
+
+### Computation
+
+```bash
+# For wave N (run after wave completes):
+WAVE_START_REF="<git SHA of wave N start>"
+WAVE_END_REF="<git SHA of wave N end>"
+
+# Lines added in this wave (insertions only — deletions tracked separately)
+INSERTIONS=$(git diff --shortstat "$WAVE_START_REF" "$WAVE_END_REF" \
+  | grep -oE '[0-9]+ insertion' | awk '{print $1}')
+DELETIONS=$(git diff --shortstat "$WAVE_START_REF" "$WAVE_END_REF" \
+  | grep -oE '[0-9]+ deletion' | awk '{print $1}')
+WAVE_DIFF_SIZE=$((${INSERTIONS:-0} + ${DELETIONS:-0}))
+
+# Ratio against peak diff (peak = max diff_size across all waves in session)
+PEAK_DIFF_SIZE=$(jq -s 'map(.diff_size) | max' <<< "$WAVE_HISTORY_JSON")
+SD_VALUE=$(echo "scale=3; $WAVE_DIFF_SIZE / $PEAK_DIFF_SIZE" | bc)
+```
+
+### Thresholds
+
+| SD value  | Interpretation                                         |
+|-----------|--------------------------------------------------------|
+| > 1.0     | This wave is larger than any previous — churn alert    |
+| 0.6–1.0   | Still substantial work; loop is active                 |
+| 0.15–0.6  | Shrinking — healthy progression                        |
+| 0.0–0.15  | Near-zero change — plateau (convergence or stall)      |
+
+### Trend Mapping
+
+| Condition                                              | Trend        |
+|--------------------------------------------------------|--------------|
+| SD_VALUE < 0.6 AND less than prior wave's value        | `improving`  |
+| SD_VALUE within ±15% of prior wave for 2+ waves       | `plateau`    |
+| SD_VALUE > prior wave's SD_VALUE                       | `regressing` |
+
+### False Positives
+
+- **Refactor-heavy waves** produce large diffs (file moves, renames) that look like
+  regressions. Mitigation: if `git diff --name-only | grep -c '/dev/null'` is high
+  (files deleted/renamed), discount the diff size by 40%.
+- **Test-only waves** often produce large line counts with zero functional change.
+  The quality-gates pass-rate signal compensates for this.
+- **Plateau at large diff** does NOT mean convergence — it means oscillation. Always
+  cross-check velocity before issuing a STOP verdict on a large-diff plateau.
+
+### Confidence Formula
+
+```
+SD_confidence = min(1.0, completed_waves / 3)
+```
+
+Minimum 3 waves before the ratio is meaningful. Below 3 waves: `confidence < 1.0`,
+verdict is downgraded per Phase 2 confidence gate.
+
+---
+
+## Signal 2: Pass-Rate Plateau (PR)
+
+**What it measures:** Has the test pass-rate stabilized?
+
+Pass-rate is the most direct quality signal. An improving trend confirms the loop is
+fixing real defects. A plateau at ≥ 0.95 is the desired end-state. A plateau below
+0.90 is a ceiling — the loop cannot fix what it's breaking.
+
+### Computation
+
+Read from `.orchestrator/metrics/events.jsonl`, filtering `event_type: quality.incremental`
+for the current session:
+
+```bash
+# Extract pass-rate per wave:
+PASS_RATES=$(jq -s --arg session "$SESSION_START_REF" '
+  [.[] | select(.session_start_ref == $session and .event_type == "quality.incremental")
+       | (.test.passed // 0) / ((.test.total // 1) | if . == 0 then 1 else . end)]
+' events.jsonl)
+
+# Latest value:
+PR_VALUE=$(echo "$PASS_RATES" | jq 'last')
+# Prior value:
+PR_PRIOR=$(echo "$PASS_RATES" | jq '.[length - 2] // 0')
+```
+
+If `quality.incremental` events are absent (test runner not configured), set
+`PR_confidence = 0.0` and trend = `plateau` (neutral; do not block on missing data).
+
+### Thresholds
+
+| PR value  | Interpretation                                             |
+|-----------|------------------------------------------------------------|
+| ≥ 0.95    | Target zone — loop should stop unless diff still large     |
+| 0.90–0.95 | Acceptable; continue if improving                          |
+| < 0.90    | Below target — investigate if no improving trend           |
+| Δ > +0.05 | Large improvement — continue regardless of other signals   |
+| Δ < -0.03 | Regression — issue INVESTIGATE regardless of other signals |
+
+### Trend Mapping
+
+| Condition                                                  | Trend        |
+|------------------------------------------------------------|--------------|
+| PR_VALUE > PR_PRIOR by > 0.02                              | `improving`  |
+| PR_VALUE within ±0.02 of PR_PRIOR for 2+ consecutive waves | `plateau`   |
+| PR_VALUE < PR_PRIOR by > 0.03                              | `regressing` |
+
+### False Positives
+
+- **New tests added mid-loop** temporarily lower pass-rate as they're written before
+  the implementation is complete. Look for `test.total` growing while `test.passed` is
+  stable — this is healthy, not a regression.
+- **Flaky tests** produce oscillating pass-rate without real quality change. If pass-rate
+  alternates between two values (e.g., 0.97 / 0.94 / 0.97), classify as plateau at the
+  higher value and emit a `flaky-tests-suspected` note.
+- **Missing test runner** produces no events; default to neutral (plateau at 1.0 with
+  confidence 0.0) — never block the loop on missing instrumentation.
+
+### Confidence Formula
+
+```
+PR_confidence = min(1.0, quality_events_count / 2)
+```
+
+Minimum 2 `quality.incremental` events in this session before the trend is meaningful.
+
+---
+
+## Signal 3: Velocity (VEL)
+
+**What it measures:** Is the agent still producing commits and changes?
+
+Declining velocity is *expected and healthy* as a loop nears completion — early waves
+scaffold and wire, later waves polish and fix. Zero velocity for 2+ waves means the loop
+has stopped making progress, whether or not quality gates pass.
+
+### Computation
+
+```bash
+# Commits in this wave:
+VEL_COMMITS=$(git rev-list --count "$WAVE_START_REF".."$WAVE_END_REF")
+
+# Lines changed in this wave:
+VEL_LINES=$(git diff --shortstat "$WAVE_START_REF" "$WAVE_END_REF" \
+  | awk '{gsub(/[^0-9 ]/,"",$0); print $1+$3}')
+
+# Prior wave lines (for trend):
+VEL_LINES_PRIOR=<read from events.jsonl for wave N-1>
+```
+
+### Thresholds
+
+| Condition                        | Interpretation                                 |
+|----------------------------------|------------------------------------------------|
+| VEL_COMMITS = 0, VEL_LINES < 5  | Stall — loop made no progress this wave         |
+| VEL_LINES < 20, declining       | Normal wind-down — approaching completion       |
+| VEL_LINES stable (not declining) | Oscillation risk — check for churn              |
+| VEL_LINES increasing             | Scope expansion or churn — flag for review      |
+
+### Trend Mapping
+
+| Condition                                          | Trend        |
+|----------------------------------------------------|--------------|
+| VEL_LINES > prior wave by > 20% for 2+ waves      | `improving`  |
+| VEL_COMMITS = 0 AND VEL_LINES < 5                 | `plateau`    |
+| VEL_LINES declining monotonically                  | `regressing` |
+
+### False Positives
+
+- **Finalization waves** (git commit, SSOT updates, CHANGELOG) produce velocity after
+  an implementation plateau. This looks like `improving` but is actually loop close-out.
+  If `git log --oneline | head -5` shows only chore/docs commits, classify as `plateau`.
+- **Empty waves** (all agents dispatched but none committed) show zero velocity. This is
+  a hard stall, not a convergence — always cross-check with PR signal.
+- **Large refactor waves** appear as high velocity with SD also high — the loop is
+  rewriting, not progressing. The SD + VEL combination triggers INVESTIGATE in the
+  decision table.
+
+### Confidence Formula
+
+```
+VEL_confidence = min(1.0, completed_waves / 2)
+```
+
+---
+
+## Composite Confidence
+
+When producing the final verdict, the composite confidence is:
+
+```
+composite_confidence = (SD_confidence + PR_confidence + VEL_confidence) / 3
+```
+
+If `composite_confidence < 0.5`:
+- STOP → downgraded to CONTINUE
+- INVESTIGATE → downgraded to CONTINUE
+
+The caller must surface `low_confidence: [<signal>, ...]` in the report so the user
+can decide whether to trust the CONTINUE verdict or force a decision.
+
+---
+
+## Event Schema (convergence.checkpoint)
+
+Written to `.orchestrator/metrics/events.jsonl` after each Phase 2 evaluation:
+
+```json
+{
+  "schema_version": 1,
+  "ts": "<ISO 8601 UTC>",
+  "session_start_ref": "<git SHA>",
+  "wave_number": 3,
+  "event_type": "convergence.checkpoint",
+  "verdict": "CONTINUE",
+  "signals": {
+    "shrinking_diff": { "trend": "improving", "value": 0.42, "confidence": 0.67 },
+    "pass_rate":      { "trend": "plateau",   "value": 0.97, "confidence": 1.0  },
+    "velocity":       { "trend": "regressing","value": 48,   "confidence": 1.0  }
+  },
+  "composite_confidence": 0.89,
+  "low_confidence": [],
+  "notes": []
+}
+```
+
+All fields required. `notes` is a string array (empty when no anomalies detected).
+
+---
+
+## See Also
+
+`skills/convergence-monitoring/SKILL.md` · `skills/wave-executor/wave-loop.md` ·
+`.orchestrator/metrics/events.jsonl` schema

package/skills/convergence-monitoring/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: convergence-monitoring
+user-invocable: true
+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
+
+**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.
+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 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)
+
+```json
+{
+  "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 plateau < 0.90 with no trend        | Ceiling          |
+| diff growing (SD regressing) for 2+ waves     | Churn / Ceiling  |
+| velocity plateau with large outstanding diff  | Stall / Ceiling  |
+| velocity plateau with near-zero diff          | Convergence      |
+
+### 3.2 Ceiling Root-Cause Probes
+
+Run these read-only probes to characterize the ceiling. Each probe takes < 5 seconds.
+
+1. **Recurring failures:** `git log --oneline $SESSION_START_REF..HEAD -- '*.test.*' | wc -l`
+   — high churn in test files with no new commits to production files suggests a test-fix loop.
+
+2. **Oscillating files:** identify files that appear in 3+ wave diffs in this session.
+   These are the **fragile modules** (see architecture.md Module/Seam vocabulary) — their
+   seam is leaking complexity into the loop.
+
+3. **Stagnation events:** read `stagnation_events` from the latest session record in
+   `sessions.jsonl`. A non-empty list confirms the loop is repeating edit-format-friction
+   rather than making functional progress.
+
+4. **Scope drift:** compare `$CONFIG."plan-prd-location"` PRD's in-scope items against
+   `git diff --name-only $SESSION_START_REF..HEAD`. Files outside PRD scope indicate
+   the loop has expanded beyond its brief.
+
+Report the probe results in Phase 4.
+
+---
+
+## Phase 4: Recovery Suggestions
+
+Present options based on the Phase 3 diagnosis. Do NOT auto-apply any recovery action —
+present to the user and await confirmation.
+
+| Diagnosis        | Recovery Option                                               | When to Use                                               |
+|------------------|---------------------------------------------------------------|-----------------------------------------------------------|
+| Convergence      | **Accept and stop** — declare loop done                      | pass-rate ≥ 0.95, all scope items addressed               |
+| Ceiling / Stall  | **Rollback to last-known-good wave** — `git reset --soft`   | Loop is chasing a regression it introduced                |
+| Ceiling / Churn  | **Scope reduction** — remove non-PRD files from agent brief  | Loop has drifted outside its brief                        |
+| Stall (fragile)  | **Agent-count adjustment** — reduce agents per wave by 50%  | Too many agents editing the same fragile module           |
+| Stall (format)   | **Stagnation break** — inject pre-edit grounding prompt      | `stagnation_events` present; loop repeating format errors |
+| Ceiling (test)   | **Test-fix isolation** — spawn dedicated fix wave**          | Pass-rate < 0.90 but diff near zero                       |
+
+**Rollback caveat:** Present the exact command (`git reset --soft <wave_N-1_end_ref>`)
+and require explicit user confirmation. Never execute it automatically.
+
+### 4.1 Recovery Report Format
+
+```
+## Convergence Report — Wave N
+
+Verdict: INVESTIGATE
+Diagnosis: Ceiling (pass-rate stuck at 0.82, 3 oscillating files)
+
+Oscillating modules: src/lib/parser.ts, src/lib/tokenizer.ts, tests/parser.test.ts
+Stagnation events: 2 (edit-format-friction in src/lib/parser.ts)
+
+Recovery options:
+  [A] Scope reduction — remove src/lib/tokenizer.ts from agent brief (outside PRD scope)
+  [B] Agent-count adjustment — reduce from 6 to 3 agents next wave (shared fragile module)
+  [C] Rollback — git reset --soft <wave_3_end_ref> (destructive, requires confirmation)
+  [D] Continue anyway — override monitoring and proceed to next wave
+
+Select option or type 'continue' to override.
+```
+
+---
+
+## Anti-Patterns
+
+- **Treating STOP as a quality gate.** Convergence-monitoring answers "are we done making
+  progress?" not "is the code correct?" Full Gate quality checks are required separately
+  even when verdict is STOP.
+- **Acting on low-confidence verdicts without the confidence note.** Below 3 waves of
+  history the signals are unreliable. The confidence gate in Phase 2 exists for this reason.
+- **Conflating convergence with correctness.** A loop can converge to a broken state
+  (pass-rate plateau at 0.6). Always cross-check the pass-rate value, not just the trend.
+- **Auto-applying rollback.** Phase 4 recovery options are presented to the user, never
+  auto-applied. Rollback is destructive and may discard valid work across parallel sessions
+  (PSA-003).
+- **Confusing convergence-monitoring with /evolve.** evolve is retrospective (what patterns
+  should we learn from finished sessions?). convergence-monitoring is prospective (should the
+  current loop continue?).
+
+---
+
+## See Also
+
+- `skills/wave-executor/wave-loop.md` — intended consumer (inter-wave hook integration pending in a follow-up issue)
+- `skills/evolve/SKILL.md` — retrospective learning; complements but does not replace
+- `skills/quality-gates/SKILL.md` — correctness gate; runs independently of convergence verdict
+- `convergence-monitoring/SIGNALS.md` — signal computation reference + threshold rationale