feat(sleep): nightly offline self-evolution engine + Claude Code plugin

Add skillopt/sleep — a deployment-time companion to SkillOpt that gives a
local Claude agent a nightly "sleep cycle":

  harvest ~/.claude transcripts -> mine recurring tasks -> replay offline
    -> consolidate (reflect -> bounded edit -> held-out GATE) -> stage -> adopt

Synthesizes SkillOpt (validation-gated bounded text optimization, reusing
skillopt.evaluation.gate verbatim), Claude Dreams (offline consolidation;
input never mutated; review-then-adopt), and the agent-sleep paper
(short-term experience -> long-term competence).

Engine (skillopt/sleep/, import-light, py>=3.10):
  - harvest.py   read-only parse of session JSONL + history.jsonl
  - mine.py      sessions -> TaskRecords (heuristic miner + LLM hook)
  - backend.py   MockBackend (deterministic, no API) + AnthropicBackend
  - replay.py    offline re-run -> (hard, soft) scores
  - consolidate.py  one SkillOpt epoch behind a held-out gate
  - memory.py    protected-region edits to SKILL.md / CLAUDE.md
  - staging.py   stage proposals; adopt with backup (Dreams safety contract)
  - cycle.py + __main__.py  orchestrator + CLI (run/dry-run/status/adopt/harvest)

Plugin (skillopt-sleep-plugin/): plugin.json, /sleep command, skillopt-sleep
skill, SessionEnd hook, bundled runner + cron generator.

Validation (deterministic, no API): persona experiment proves held-out lift
(researcher 0.33->1.0, programmer 0.32->1.0) AND that the gate rejects an
injected harmful edit. 13 stdlib-unittest tests pass, incl. full cycle +
adopt-with-backup and parsing of real on-disk transcripts.

Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>

skillopt-sleep-plugin/scripts/install-cron.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Print (does NOT install) a crontab line that runs SkillOpt-Sleep nightly.
+# The user copies the line into `crontab -e` if they want it.
+set -euo pipefail
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+RUNNER="$PLUGIN_ROOT/scripts/sleep.sh"
+PROJECT="${1:-$(pwd)}"
+BACKEND="${2:-mock}"
+
+# 3:17am local — deliberately off the :00 mark so many users don't all hit the
+# API at once (and we leave room for jitter).
+MIN=17
+HOUR=3
+
+cat <<EOF
+# ── SkillOpt-Sleep nightly cycle ────────────────────────────────────────────
+# Review past sessions, replay tasks, stage validated memory/skill updates.
+# Runs at ${HOUR}:$(printf '%02d' $MIN) local every day. Output goes to the project's
+# .skillopt-sleep/ dir; nothing live is changed until you run '/sleep adopt'
+# (unless you pass --auto-adopt below).
+#
+# Copy the next line into 'crontab -e':
+${MIN} ${HOUR} * * *  "${RUNNER}" run --project "${PROJECT}" --scope invoked --backend ${BACKEND} >> "${PROJECT}/.skillopt-sleep/cron.log" 2>&1
+#
+# For fully-autonomous adoption (power users), append: --auto-adopt
+# To spend real API budget for genuine lift, set BACKEND=anthropic above.
+# ────────────────────────────────────────────────────────────────────────────
+EOF

skillopt-sleep-plugin/scripts/sleep.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# SkillOpt-Sleep runner — invokes the skillopt.sleep engine with a suitable
+# Python interpreter, from the repo that contains this plugin.
+#
+# Usage: sleep.sh <run|dry-run|status|adopt|harvest> [extra args...]
+set -euo pipefail
+
+# Resolve the repo root: the plugin lives at <repo>/skillopt-sleep-plugin,
+# so the engine package is at <repo>/skillopt/sleep. CLAUDE_PLUGIN_ROOT points
+# at the plugin dir when run by Claude Code; fall back to this script's dir.
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+REPO_ROOT="$(cd "$PLUGIN_ROOT/.." && pwd)"
+
+# Pick an interpreter that satisfies SkillOpt's 3.10+ requirement.
+PY=""
+for cand in python3.12 python3.11 python3.10 python3; do
+  if command -v "$cand" >/dev/null 2>&1; then
+    ver="$("$cand" -c 'import sys; print("%d%d" % sys.version_info[:2])' 2>/dev/null || echo 0)"
+    if [ "${ver:-0}" -ge 310 ]; then PY="$cand"; break; fi
+  fi
+done
+if [ -z "$PY" ]; then
+  echo "[sleep] ERROR: need Python >= 3.10 (found none). Install one and retry." >&2
+  exit 1
+fi
+
+if [ "$#" -eq 0 ]; then set -- status; fi
+
+cd "$REPO_ROOT"
+exec "$PY" -m skillopt.sleep "$@"