evolve

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/ (v2) with fallback to <state-dir>/metrics/ for pre-v2.0 legacy data. See skills/_shared/platform-tools.md.

Evolve Skill

Phase 0: Bootstrap Gate

Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to skills/_shared/bootstrap-gate.md for the full HARD-GATE constraints. </HARD-GATE>

Phase 1: Config & Data Loading

1.1 Read Session Config

Read and parse Session Config per skills/_shared/config-reading.md. Store result as $CONFIG.

1.2 Check Persistence

Extract persistence from $CONFIG. If persistence is false, abort with message:

"Learnings require persistence to be enabled in Session Config. Add persistence: true to your Session Config block (CLAUDE.md for Claude Code, AGENTS.md for Codex CLI)."

1.3 Determine Mode

Read mode from $ARGUMENTS:

• If empty or not provided, default to analyze
• Valid modes: analyze, review, list, dialectic
• If invalid mode provided, report error and list valid modes

1.4 Load Data

Lazy-create defensive (#185): If .orchestrator/metrics/learnings.jsonl does not exist (pre-#185 repo or bootstrap skipped), create an empty file and emit an info log — do NOT hard-fail:

LEARNINGS_FILE=".orchestrator/metrics/learnings.jsonl"
if [[ ! -f "$LEARNINGS_FILE" ]]; then
  mkdir -p "$(dirname "$LEARNINGS_FILE")"
  : > "$LEARNINGS_FILE"
  echo "info(#185): auto-created $LEARNINGS_FILE (was missing)" >&2
fi

This defensive step is idempotent and cheap — it ensures /evolve analyze|review|list never fails because of a missing artifact file.

1. Read .orchestrator/metrics/sessions.jsonl (session history). If it does not exist, check <state-dir>/metrics/sessions.jsonl as a legacy fallback (where <state-dir> is .claude/, .codex/, or .cursor/ per platform). If neither exists, warn: "No session history found. Run at least one session first."
2. Read .orchestrator/metrics/learnings.jsonl if it exists. If not found, check <state-dir>/metrics/learnings.jsonl as a legacy fallback.
3. Count existing learnings, note any where expires_at < current date (expired)

Phase 2: Mode Dispatch

Route based on mode:

• analyze → Phase 3
• review → Phase 4
• list → Phase 5
• dialectic → Phase 6

Phase 3: Analyze Mode (default)

Extract learnings from session history.

Vault Integration: If vault-integration.enabled is true in Session Config, confirmed learnings are mirrored to the configured Obsidian vault after the atomic write (Step 3.5, step 9). See docs/session-config-reference.md for the vault-integration config block.

Step 3.1: Read Session Data

• Read all entries from .orchestrator/metrics/sessions.jsonl (or <state-dir>/metrics/sessions.jsonl if the v2 path does not exist — see Phase 1.4 fallback)
• Parse each JSONL line as JSON
• Sort by completed_at descending (most recent first)
• If no sessions found, abort: "No session data available. Complete at least one session before running evolve."

Step 3.2: Pattern Extraction

For each of the 8 learning types, apply these heuristics:

1. fragile-file (type: fragile-file)

• Look at wave data: if the same file appears in 3+ waves' files_changed within a session, it is fragile
• Cross-session: if a file appears in 3+ different sessions' files_changed, flag it
• Subject = file path (relative to project root)

2. effective-sizing (type: effective-sizing)

• Compare total_agents and total_waves across session types
• Calculate average agents per wave for each session type
• Subject = canonical identifier like deep-session-sizing or feature-session-sizing
• Insight = "Deep sessions average X agents across Y waves" or "Feature sessions work well with X agents/wave"

3. recurring-issue (type: recurring-issue)

• Look at agent_summary — if failed or partial > 0 across multiple sessions, flag
• Check wave quality fields — repeated failures indicate recurring issues
• Subject = issue pattern identifier (e.g., "test-failures-in-wave-execution", "lint-regressions")

4. scope-guidance (type: scope-guidance)

• Cross-reference effectiveness.planned_issues vs effectiveness.completion_rate
• Skip sessions that lack the effectiveness field (early sessions may not have it)
• If completion_rate is consistently 1.0 with N issues, note "N issues per session works well"
• If completion_rate < 0.7, note "scope was too large"
• Subject = optimal-scope-per-session-type

5. deviation-pattern (type: deviation-pattern)

Ownership Reference: See skills/_shared/state-ownership.md. evolve has read-only access to STATE.md.

• Read <state-dir>/STATE.md if it exists and check ## Deviations section
• Cross-reference with session duration vs planned waves
• Subject = pattern name (e.g., "scope-creep-in-feature-sessions", "underestimated-complexity")

6. stagnation-class-frequency (type: stagnation-class-frequency)

• Read stagnation_events from the most recent 5 sessions in sessions.jsonl (skip sessions lacking the field — they predate #84).
• For each (file, error_class) pair appearing in ≥2 sessions, extract a candidate:
• Subject = <file>:<error_class> (e.g., skills/wave-executor/wave-loop.md:edit-format-friction)
• Insight = "File <X> has <error_class> stagnation in <N> recent sessions — candidate for pre-edit grounding (#85)."
• Evidence = "<N> sessions with stagnation_events for this file/class"
• These learnings feed #85 (pre-edit grounding injection) when it ships — high-frequency pairs trigger grounding.

7. hardware-pattern (type: hardware-pattern)

v3.1.0 / Sub-Epic #160 (C2, issue #171). Keyed on host_class rather than project — surfaces hardware-bound problems that affect the user across every repo on the same machine. Complements the project-keyed types above.

• Read .orchestrator/metrics/events.jsonl (session + wave events) and the registry sweep.log at ~/.config/session-orchestrator/sessions/sweep.log. Both are optional — missing files produce no candidates.
• Invoke scripts/lib/hardware-pattern-detector.mjs → detectHardwarePatterns({events, sweepLogEntries, thresholds}). Thresholds come from Session Config resource-thresholds when present, falling back to DEFAULT_THRESHOLDS.
• Five detection signals (aggregated per (signal, host_class) pair, ≥2 occurrences required):
• oom-kill — orchestrator.session.stopped with exit_code: 137 or OOM-marker in error
• heartbeat-gap — registry sweep-log entries with gap_minutes above resource-thresholds.zombie-threshold-min
• concurrent-session-pressure — session-start events with peer_count ≥ concurrent-sessions-warn
• disk-full — events whose error matches ENOSPC / "no space left"
• thermal-throttle — events whose resource_snapshot.cpu_load_pct crosses cpu-load-max-pct
• Each candidate is piped through candidateToLearning() → validateLearning(). Default scope is private (in-repo only). To promote to public, the user runs npm run share:hw-learnings -- --promote (C3 export). This anonymizes each private hardware-pattern entry, validates via the privacy contract, and appends a public twin to learnings.jsonl (original preserved). Use --dry-run to preview without writing.
• Subject convention: <signal>::<host_class> (e.g., oom-kill::macos-arm64-m3pro). The :: separator avoids colliding with project-keyed subjects.
• Confidence starts at 0.5 like other learning types, but decay is slower in practice: hardware stays