fix: Phase 1 skill evolution is non-functional (GEPA output discarded, sessiondb mines 0 Hermes messages)

[josuedpinedad]

Summary

Phase 1 (skill evolution) cannot currently produce an evolved skill. I hit four
independent blocking defects trying to evolve a single skill end to end, plus a
Windows-only test failure. Each fix is a separate commit; the suite goes from
144 passed / 1 failed → 156 passed / 0 failed.

The headline bug is #1: GEPA works, and its output is discarded.

1. The skill text is not an optimizable parameter (skill_module.py)

SkillModule passed the skill body as a dspy InputField (skill_instructions).
DSPy optimizers only rewrite a predictor's signature instructions — they
never touch input values. So the skill text was never mutated.

On a real 6-iteration run, GEPA logged 7 accepted proposals for
predictor.predict:

INFO dspy.teleprompt.gepa.gepa: Iteration 1: Proposed new text for predictor.predict: ...
INFO dspy.teleprompt.gepa.gepa: Iteration 2: Proposed new text for predictor.predict: ...

…and the result was:

{ "baseline_score": 0.4302521929824561,
  "evolved_score":  0.4302521929824561,
  "improvement": 0.0,
  "baseline_size": 5433,
  "evolved_size":  5433 }

diff baseline_skill.md evolved_skill.md → byte-identical. Every proposed
improvement was thrown away.

Fix: seed the signature via TaskWithSkill.with_instructions(skill_text) so the
skill body is the optimizable parameter, and expose skill_text as a property
reading it back. Callers are unchanged.

SkillModule had no tests, which is why this went unnoticed. Added
TestSkillModuleIsOptimizable, which fails on the old wiring.

2. --eval-source sessiondb mines 0 messages from Hermes (external_importers.py)

HermesSessionImporter only reads ~/.hermes/sessions/*.json. Modern Hermes
stores transcripts in a single SQLite state.db (sessions + messages
tables), so the richest of the three importers silently contributed nothing:

Importing from Claude Code...
  Found 857 messages
Importing from Copilot...
  Found 0 messages
Importing from Hermes Agent...
  Found 0 messages      # <-- 8,240 messages / 52 sessions sat in state.db

After the fix: 424 user/assistant pairs from the same machine.

• _candidate_db_paths() honors HERMES_HOME, then per-platform defaults
  (Windows %LOCALAPPDATA%\hermes, XDG, macOS Application Support, ~/.hermes).
• _extract_from_sqlite() opens the DB read-only (file:...?mode=ro) so a
  live Hermes process is never disturbed; pairs each user turn with the next
  assistant turn within the same session; skips compacted rows so
  compression artifacts don't become training data.
• Cron-injected preambles are skipped — agent scaffolding, not user tasks.
• Legacy JSON reader retained as a fallback.
• STATE_DB added for explicit override (also lets tests pin the DB rather than
  picking up whatever install exists on the host).

3. dspy.GEPA(max_steps=...) doesn't exist in dspy 3.x (evolve_skill.py)

Every run raised TypeError: GEPA.__init__() got an unexpected keyword argument
and fell through to the MIPROv2 fallback — GEPA never ran. The fallback then
died on ImportError: MIPROv2 requires optional dependency 'optuna', taking the
whole run with it.

Now uses max_full_evals=iterations plus the reflection_lm GEPA requires, and
declares optuna under a mipro extra so the documented fallback works.

Also added _gepa_metric, an arity-tolerant wrapper: GEPA calls metrics as
(gold, pred, trace, pred_name, pred_trace) while Evaluate uses
(gold, pred), and skill_fitness_metric accepts only three positional args.

4. The structural constraint can never pass, blocking deploys (evolve_skill.py)

_check_skill_structure asserts YAML frontmatter exists, but was handed
skill["body"] — which load_skill() has already stripped of frontmatter:

✗ skill_structure: Skill missing: YAML frontmatter (---), name field, description field

On the baseline that's a spurious warning; on the evolved artifact it triggers
✗ Evolved skill FAILED constraints — not deploying, discarding good variants.
Now validates the full artifact (skill["raw"] / evolved_full).

5. Windows-only test failure (test_config_repo_path.py)

test_resolve_expands_user_home monkeypatched only HOME, but
Path.expanduser() reads USERPROFILE on Windows. Fails on main on any
Windows machine, independent of this PR.

Test Plan

• pytest tests/ -q → 156 passed (from 144 passed / 1 failed on main)
• 11 new tests: SQLite importer (pairing, session isolation, secret
  filtering, limit, cron skip, legacy fallback, unrelated schema) +
  SkillModule optimizability
• TestSkillModuleIsOptimizable verified to fail against the old
  InputField wiring — it is a real regression guard, not a tautology
• Existing legacy-JSON importer tests isolated from the host's real
  state.db and still passing
• Full end-to-end run on a real skill after the fixes: 6 iterations, 441s,
  completes and produces a genuinely different evolved skill, correctly
  gated by growth_limit (+22.9% vs the +20% cap) instead of silently
  returning the baseline

Notes

Verified against dspy 3.3.1 / gepa 0.1.4 on Windows with Python 3.14. Fixes
1 and 2 are the load-bearing ones — without them Phase 1 either evolves nothing
or has nothing to evolve against.

One observation worth flagging for anyone using this: with a small mined dataset
(11 examples, mostly one input shape) GEPA overfits hard — in my run it
replaced a general ## Diagnosis Workflow section with a narrow variant
specific to the dominant input type. The growth_limit guardrail happened to
catch it. Reviewing the diff before adopting evolved_skill.md is essential;
that might be worth a line in the README.