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/memory.py

@@ -0,0 +1,130 @@
+"""SkillOpt-Sleep — skill/memory document manipulation.
+
+Applies bounded EditRecords to a skill (SKILL.md body) or memory (CLAUDE.md)
+document, and provides Dream-style consolidation helpers (dedup near-identical
+lines, drop contradictions). All edits live inside a protected, clearly-marked
+region so the sleep cycle never clobbers the user's hand-written content.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Tuple
+
+from skillopt.sleep.types import EditRecord
+
+
+LEARNED_START = "<!-- SKILLOPT-SLEEP:LEARNED START -->"
+LEARNED_END = "<!-- SKILLOPT-SLEEP:LEARNED END -->"
+_BANNER = (
+    "_This block is maintained by SkillOpt-Sleep. Edits here are proposed "
+    "offline, validated against your past tasks, and adopted only after you "
+    "approve them. Hand-edits outside this block are never touched._"
+)
+
+
+def extract_learned(doc: str) -> str:
+    s = doc.find(LEARNED_START)
+    e = doc.find(LEARNED_END)
+    if s == -1 or e == -1:
+        return ""
+    return doc[s + len(LEARNED_START):e].strip()
+
+
+def _strip_learned(doc: str) -> str:
+    while True:
+        s = doc.find(LEARNED_START)
+        if s == -1:
+            break
+        e = doc.find(LEARNED_END, s)
+        if e == -1:
+            doc = doc[:s]
+            break
+        doc = doc[:s] + doc[e + len(LEARNED_END):]
+    while "\n\n\n" in doc:
+        doc = doc.replace("\n\n\n", "\n\n")
+    return doc.rstrip()
+
+
+def set_learned(doc: str, learned_lines: List[str]) -> str:
+    """Replace the protected learned region with the given bullet lines."""
+    base = _strip_learned(doc)
+    body = "\n".join(f"- {ln.strip().lstrip('- ').strip()}" for ln in learned_lines if ln.strip())
+    block = (
+        f"\n\n{LEARNED_START}\n"
+        f"## Learned preferences & procedures\n\n{_BANNER}\n\n{body}\n"
+        f"{LEARNED_END}\n"
+    )
+    return (base + block).lstrip("\n")
+
+
+def current_learned_lines(doc: str) -> List[str]:
+    inner = extract_learned(doc)
+    lines: List[str] = []
+    for ln in inner.splitlines():
+        ln = ln.strip()
+        if ln.startswith("- "):
+            lines.append(ln[2:].strip())
+    return lines
+
+
+def _norm(s: str) -> str:
+    return re.sub(r"\s+", " ", (s or "").lower()).strip()
+
+
+def apply_edits(doc: str, edits: List[EditRecord]) -> Tuple[str, List[EditRecord]]:
+    """Apply add/delete/replace edits to the protected learned region.
+
+    Returns (new_doc, applied_edits). Dedups: an `add` whose content already
+    exists (normalized) is skipped. `delete`/`replace` match on normalized
+    anchor substring.
+    """
+    lines = current_learned_lines(doc)
+    norm_set = {_norm(l) for l in lines}
+    applied: List[EditRecord] = []
+
+    for e in edits:
+        op = (e.op or "add").lower()
+        if op == "add":
+            if _norm(e.content) in norm_set or not e.content.strip():
+                continue
+            lines.append(e.content.strip())
+            norm_set.add(_norm(e.content))
+            applied.append(e)
+        elif op == "delete":
+            anchor = _norm(e.anchor or e.content)
+            keep = [l for l in lines if anchor not in _norm(l)]
+            if len(keep) != len(lines):
+                lines = keep
+                norm_set = {_norm(l) for l in lines}
+                applied.append(e)
+        elif op == "replace":
+            anchor = _norm(e.anchor)
+            new_lines = []
+            changed = False
+            for l in lines:
+                if anchor and anchor in _norm(l):
+                    new_lines.append(e.content.strip())
+                    changed = True
+                else:
+                    new_lines.append(l)
+            if changed:
+                lines = new_lines
+                norm_set = {_norm(l) for l in lines}
+                applied.append(e)
+
+    return set_learned(doc, lines), applied
+
+
+def ensure_skill_scaffold(doc: str, *, name: str, description: str) -> str:
+    """Ensure a SKILL.md has YAML frontmatter so Claude Code loads it."""
+    if doc.lstrip().startswith("---"):
+        return doc
+    fm = (
+        "---\n"
+        f"name: {name}\n"
+        f"description: {description}\n"
+        "---\n\n"
+        f"# {name}\n\n"
+        "Preferences and procedures learned from your past Claude Code sessions.\n"
+    )
+    return fm + doc