feat: add scan_evolution_opportunities MCP tool for agent-driven skill evolution

[xzq-xu]

Summary

Add a new MCP tool scan_evolution_opportunities that bridges the gap between fully automatic evolution (inside execute_task) and manual repair (fix_skill).

The current MCP tool set lacks a way for host agents to proactively inspect which skills could benefit from evolution and make their own decisions. The data already exists in SkillStore (evolution candidates, execution analyses, skill usage stats) — this PR simply exposes it through a new MCP tool.

What it does

• Loads ExecutionAnalysis records marked as evolution candidates
• Enriches each with SkillRecord usage statistics (completion rate, fallback rate, effective rate, selection/applied/completion/fallback counts)
• Returns a structured JSON report with prioritized suggestions and a human-readable summary

Return shape

{
  "candidates": [
    {
      "skill_id": "weather__imp_a1b2c3d4",
      "skill_name": "weather",
      "description": "...",
      "stats": {
        "total_selections": 10,
        "completion_rate": 0.6,
        "fallback_rate": 0.3
      },
      "suggestions": [
        { "type": "fix", "direction": "...", "target_skills": ["..."] }
      ],
      "source_task_id": "...",
      "task_completed": false,
      "execution_note": "...",
      "analyzed_at": "..."
    }
  ],
  "total_candidates": 5,
  "total_active_skills": 42,
  "scan_summary": "Found 5 evolution candidate(s) across 42 active skill(s): 3 FIX, 1 DERIVED, 1 CAPTURED"
}

Use case: agent-in-the-loop evolution

This enables a pattern for all host agents (Claude Code, Codex, nanobot, Cursor, etc.):

1. Call scan_evolution_opportunities periodically (e.g. via cron)
2. Agent reviews the report — each candidate has stats and actionable suggestions
3. Agent decides which to act on and calls fix_skill (or defers)

This is the "agent-in-the-loop" complement to the fully automatic evolution pipeline, filling the gap in the README's "Quality monitoring — Tracks skill performance, error rates, and execution success across all tasks" promise.

Implementation

• Pure composition of existing APIs: SkillStore.load_evolution_candidates(), load_record(), count()
• Follows the same patterns as other MCP tools (_get_openspace(), _get_store(), _auto_register_skill_dirs)
• No new dependencies
• Error responses follow existing _json_error() convention (no traceback leakage)

Test plan

• Tool appears in MCP tool listing
• Returns empty candidates array when no evolution candidates exist
• Returns enriched candidates with skill stats when candidates exist
• skill_dirs parameter triggers registration before scanning
• max_candidates limits output correctly
• scan_summary includes correct type counts

Closes #24

Made with Cursor