self-evolve-framework 1.2.0 → 1.4.0

package/template/skills/skillopt-sleep/scripts/python/cycle.py

@@ -0,0 +1,291 @@
+"""SkillOpt-Sleep — the nightly cycle orchestrator.
+
+run_sleep_cycle() wires the stages:
+    harvest -> mine -> replay -> consolidate(gate) -> stage  (-> optional adopt)
+
+It is pure-Python and import-light; with backend="mock" it runs with no API
+key and no third-party deps, which is what the deterministic experiment and
+CI use. With backend="anthropic" it spends the user's budget for real lift.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from typing import List, Optional
+
+from skillopt_sleep.backend import get_backend
+from skillopt_sleep.config import SleepConfig, load_config
+from skillopt_sleep.dream import dream_consolidate
+from skillopt_sleep.harvest_sources import harvest_for_config
+from skillopt_sleep.memory import ensure_skill_scaffold
+from skillopt_sleep.mine import mine
+from skillopt_sleep.staging import adopt as adopt_staging
+from skillopt_sleep.staging import write_staging
+from skillopt_sleep.state import SleepState, _now_iso
+from skillopt_sleep.types import SessionDigest, SleepReport, TaskRecord
+
+
+@dataclass
+class CycleOutcome:
+    report: SleepReport
+    staging_dir: str
+    adopted: bool
+    adopted_paths: List[str]
+
+
+def _project_paths(cfg: SleepConfig) -> str:
+    """Where live CLAUDE.md lives + which project we are evolving."""
+    if cfg.get("projects") == "invoked" and cfg.get("invoked_project"):
+        return cfg.get("invoked_project")
+    # default: the invoked cwd
+    return cfg.get("invoked_project") or os.getcwd()
+
+
+def _read(path: str) -> str:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read()
+    except Exception:
+        return ""
+
+
+def _progress(cfg: SleepConfig, message: str) -> None:
+    if cfg.get("progress", False):
+        print(f"[sleep] {message}", file=sys.stderr, flush=True)
+
+
+def _render_report_md(report: SleepReport, cfg: SleepConfig) -> str:
+    lines = [
+        f"# SkillOpt-Sleep — night {report.night} report",
+        "",
+        f"- project: `{report.project}`",
+        f"- backend: `{cfg.get('backend')}`  replay: `{cfg.get('replay_mode')}`",
+        f"- sessions harvested: {report.n_sessions}",
+        f"- tasks mined: {report.n_tasks}  (replayed: {report.n_replayed})",
+        f"- held-out score: {report.baseline_score:.3f} -> {report.candidate_score:.3f}",
+        f"- gate: **{report.gate_action}** (accepted={report.accepted})",
+        f"- tokens used: {report.tokens_used}",
+        "",
+    ]
+    if report.edits:
+        lines.append("## Accepted edits")
+        for e in report.edits:
+            lines.append(f"- [{e.target}/{e.op}] {e.content}  \n  _why: {e.rationale}_")
+        lines.append("")
+    if report.rejected_edits:
+        lines.append("## Rejected by gate (kept as negative feedback)")
+        for e in report.rejected_edits:
+            lines.append(f"- [{e.target}/{e.op}] {e.content}")
+        lines.append("")
+    if report.notes:
+        lines.append("## Notes")
+        for n in report.notes:
+            lines.append(f"- {n}")
+        lines.append("")
+    lines.append("_Review, then run `/sleep adopt` to apply, or discard this folder._")
+    return "\n".join(lines)
+
+
+def run_sleep_cycle(
+    cfg: Optional[SleepConfig] = None,
+    *,
+    seed_tasks: Optional[List[TaskRecord]] = None,
+    dry_run: bool = False,
+    clock: Optional[float] = None,
+) -> CycleOutcome:
+    """Run one full sleep cycle and return the outcome.
+
+    Parameters
+    ----------
+    cfg : SleepConfig
+    seed_tasks : optional pre-built TaskRecords (used by the experiment to
+        inject a known persona instead of harvesting ~/.claude).
+    dry_run : harvest+mine+replay but DO NOT stage/adopt (report only).
+    clock : fixed epoch seconds for deterministic timestamps in tests.
+    """
+    cfg = cfg or load_config()
+    state = SleepState.load(cfg.state_path)
+    night = state.begin_night(clock)
+    project = _project_paths(cfg)
+    started = _now_iso(clock)
+
+    backend = get_backend(
+        cfg.get("backend", "mock"),
+        model=cfg.get("model", ""),
+        codex_path=cfg.get("codex_path", ""),
+        project_dir=project,
+    )
+    _progress(cfg, f"night {night}: project={project} backend={backend.name}")
+
+    # ── live skill/memory docs ───────────────────────────────────────────
+    live_memory_path = os.path.join(project, "CLAUDE.md")
+    live_skill_path = cfg.managed_skill_path()
+    _progress(cfg, f"live skill: {live_skill_path}")
+    raw_skill = _read(live_skill_path)
+    skill = raw_skill
+    memory = _read(live_memory_path)
+    if not skill:
+        skill = ensure_skill_scaffold(
+            "", name=cfg.get("managed_skill_name", "skillopt-sleep-learned"),
+            description="Preferences and procedures learned from past local agent sessions.",
+        )
+    target_filter = bool(
+        cfg.get("target_task_filter", True)
+        and cfg.get("target_skill_path", "")
+        and raw_skill
+    )
+
+    # ── 1+2. harvest + mine (unless seed_tasks injected) ─────────────────
+    digests: List[SessionDigest] = []
+    if seed_tasks is not None:
+        tasks = seed_tasks
+        n_sessions = 0
+        _progress(cfg, f"using {len(tasks)} seeded tasks")
+    else:
+        since = state.last_harvest_for(project)
+        # On first run (no prior harvest), apply lookback_hours so we don't
+        # scan the entire transcript history and trigger massive LLM mining.
+        if since is None:
+            lookback_hours = cfg.get("lookback_hours", 72)
+            if lookback_hours is not None and lookback_hours > 0:
+                import time
+                ref_time = clock if clock is not None else time.time()
+                cutoff = ref_time - lookback_hours * 3600
+                since = _now_iso(cutoff)
+        max_tasks = cfg.get("max_tasks_per_night", 40)
+        max_sessions = cfg.get("max_sessions_per_night", 0) or max_tasks * 3
+        candidate_limit = max_tasks
+        if target_filter:
+            candidate_limit = max(max_tasks, max_tasks * 3)
+        _progress(
+            cfg,
+            f"harvest start: source={cfg.get('transcript_source')} max_sessions={max_sessions}",
+        )
+        digests = harvest_for_config(
+            cfg,
+            since_iso=since,
+            limit=max_sessions,
+        )
+        n_sessions = len(digests)
+        _progress(cfg, f"harvest done: sessions={n_sessions}")
+        # When a real backend is configured, use it to mine checkable tasks from
+        # the transcripts (rubric/rule judges); otherwise fall back to the
+        # heuristic miner (no API, no checkable reference).
+        llm_miner = None
+        if cfg.get("backend", "mock") != "mock" and cfg.get("llm_mine", True):
+            try:
+                from skillopt_sleep.llm_miner import make_llm_miner
+                llm_miner = make_llm_miner(
+                    backend,
+                    max_sessions=max_sessions,
+                    max_tasks=candidate_limit,
+                )
+            except Exception:
+                llm_miner = None
+        _progress(
+            cfg,
+            f"mine start: max_tasks={max_tasks} candidate_limit={candidate_limit} "
+            f"llm_mine={llm_miner is not None} target_filter={target_filter}",
+        )
+        tasks = mine(
+            digests,
+            max_tasks=max_tasks,
+            candidate_limit=candidate_limit,
+            holdout_fraction=cfg.get("holdout_fraction", 0.34),
+            seed=cfg.get("seed", 42),
+            llm_miner=llm_miner,
+            target_skill_text=raw_skill if target_filter else "",
+            target_skill_path=live_skill_path if target_filter else "",
+        )
+        _progress(cfg, f"mine done: tasks={len(tasks)}")
+
+    report = SleepReport(
+        night=night, project=project, started_at=started,
+        n_sessions=n_sessions, n_tasks=len(tasks),
+    )
+
+    if not tasks:
+        report.ended_at = _now_iso(clock)
+        report.notes.append("no tasks mined — nothing to consolidate")
+        state.set_last_harvest(project, started)
+        state.record_night({"night": night, "accepted": False, "n_tasks": 0})
+        if not dry_run:
+            state.save()
+        staging_dir = ""
+        return CycleOutcome(report, staging_dir, False, [])
+
+    # ── 3+4. replay + consolidate (gate), with opt-in dream + recall ──────
+    # recall pulls similar past tasks from the persisted archive; dream_rollouts
+    # / dream_factor enrich the training signal. With the defaults (recall_k=0,
+    # dream_rollouts=1, dream_factor=0) this is exactly the prior single-shot
+    # consolidate — behavior is unchanged unless the user opts in.
+    _progress(cfg, "consolidate start")
+    recall_k = int(cfg.get("recall_k", 0) or 0)
+    history_tasks = []
+    if recall_k > 0:
+        history_tasks = [TaskRecord.from_dict(d) for d in state.task_archive()]
+    result = dream_consolidate(
+        backend, tasks, skill, memory,
+        history_tasks=history_tasks,
+        recall_k=recall_k,
+        dream_rollouts=int(cfg.get("dream_rollouts", 1) or 1),
+        dream_factor=int(cfg.get("dream_factor", 0) or 0),
+        edit_budget=cfg.get("edit_budget", 4),
+        gate_metric=cfg.get("gate_metric", "mixed"),
+        gate_mixed_weight=cfg.get("gate_mixed_weight", 0.5),
+        gate_mode=cfg.get("gate_mode", "on"),
+        evolve_skill=cfg.get("evolve_skill", True),
+        evolve_memory=cfg.get("evolve_memory", True),
+        night=night,
+    )
+    # archive tonight's real (non-dream) tasks so future nights can recall them
+    state.add_to_archive([t.to_dict() for t in tasks if t.origin != "dream"])
+    _progress(
+        cfg,
+        f"consolidate done: gate={result.gate_action} accepted={result.accepted} "
+        f"edits={len(result.applied_edits)} rejected={len(result.rejected_edits)}",
+    )
+
+    report.n_replayed = len(tasks)
+    report.baseline_score = result.baseline_score
+    report.candidate_score = result.candidate_score
+    report.accepted = result.accepted
+    report.gate_action = result.gate_action
+    report.no_edits_reason = getattr(result, "no_edits_reason", "")
+    report.edits = result.applied_edits
+    report.rejected_edits = result.rejected_edits
+    report.tokens_used = backend.tokens_used()
+    report.ended_at = _now_iso(clock)
+
+    # ── 5. stage (unless dry-run) ────────────────────────────────────────
+    staging_dir = ""
+    adopted = False
+    adopted_paths: List[str] = []
+    if not dry_run:
+        _progress(cfg, "staging start")
+        report_md = _render_report_md(report, cfg)
+        proposed_skill = result.new_skill if (cfg.get("evolve_skill") and result.accepted) else None
+        proposed_memory = result.new_memory if (cfg.get("evolve_memory") and result.accepted) else None
+        staging_dir = write_staging(
+            project,
+            report=report,
+            proposed_skill=proposed_skill,
+            proposed_memory=proposed_memory,
+            live_skill_path=live_skill_path,
+            live_memory_path=live_memory_path,
+            report_md=report_md,
+        )
+        state.set_last_harvest(project, started)
+        state.record_night({
+            "night": night, "accepted": result.accepted,
+            "baseline": result.baseline_score, "candidate": result.candidate_score,
+            "n_tasks": len(tasks), "staging": staging_dir,
+        })
+        # ── 6. adopt (opt-in) ────────────────────────────────────────────
+        if cfg.get("auto_adopt") and result.accepted:
+            adopted_paths = adopt_staging(staging_dir)
+            adopted = bool(adopted_paths)
+        state.save()
+
+    return CycleOutcome(report, staging_dir, adopted, adopted_paths)

package/template/skills/skillopt-sleep/scripts/python/dream.py

@@ -0,0 +1,138 @@
+"""SkillOpt-Sleep — dream + associative recall for nightly consolidation.
+
+Two opt-in mechanisms (both default OFF, so the cycle is unchanged unless the
+user enables them) that the deployment experiments validated:
+
+  * dream rollouts  — run each task K times and learn from the good-vs-bad
+    contrast (set ``dream_rollouts > 1``). Stronger signal than one failure.
+  * associative recall — each night, pull the K past tasks most similar to
+    tonight's new ones into the dream (set ``recall_k > 0``). Replays relevant
+    experience without re-running the whole history.
+
+``dream_consolidate`` wires recall + synthetic augmentation + multi-rollout
+consolidation and is called by BOTH the shipped plugin cycle and the benchmark
+experiment harness, so the reported numbers exercise the exact code the plugin
+runs. Pure-stdlib, zero research/private dependency.
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+
+from skillopt_sleep.consolidate import ConsolidationResult, consolidate
+from skillopt_sleep.types import TaskRecord
+
+
+# ── synthetic augmentation ("dream up" variants of today's tasks) ─────────────
+
+_WRAPPERS = [
+    "(quick one) {q}",
+    "Please handle this request: {q}",
+    "For the daily report: {q}",
+]
+
+
+def dream_augment(real_tasks: List[TaskRecord], *, factor: int = 1) -> List[TaskRecord]:
+    """Create synthetic TRAIN variants of real tasks (origin='dream').
+
+    A light, deterministic rephrasing. Dream tasks are training-only — they
+    carry split='train' and never enter the val/test slices the gate scores on.
+    """
+    out: List[TaskRecord] = []
+    for t in real_tasks:
+        for k in range(max(0, factor)):
+            w = _WRAPPERS[k % len(_WRAPPERS)]
+            out.append(TaskRecord(
+                id=f"{t.id}_dream{k}", project=t.project,
+                intent=w.format(q=t.intent), context_excerpt=t.context_excerpt,
+                reference_kind=t.reference_kind, reference=t.reference,
+                judge=dict(t.judge), system=t.system,
+                tags=list(t.tags) + ["dream"], split="train",
+                origin="dream", derived_from=t.id,
+            ))
+    return out
+
+
+# ── associative recall (experience replay of similar past tasks) ──────────────
+
+def _tokens(text: str) -> set:
+    return {w for w in re.findall(r"[a-z0-9]+", (text or "").lower()) if len(w) > 2}
+
+
+def recall_similar(new_tasks: List[TaskRecord], history: List[TaskRecord],
+                   k: int) -> List[TaskRecord]:
+    """Return the ``k`` historical tasks most lexically similar to any of
+    tonight's ``new_tasks`` (max Jaccard token overlap). Recalled tasks are
+    returned as training material (split='train'); deterministic, stdlib-only.
+    """
+    if not history or k <= 0 or not new_tasks:
+        return []
+    new_tok = [_tokens(t.intent) for t in new_tasks]
+    new_ids = {t.id for t in new_tasks}
+    scored = []
+    for h in history:
+        if h.id in new_ids:
+            continue
+        ht = _tokens(h.intent)
+        if not ht:
+            continue
+        sim = max(((len(ht & nt) / len(ht | nt)) if (ht | nt) else 0.0) for nt in new_tok)
+        scored.append((sim, h.id, h))
+    scored.sort(key=lambda x: (-x[0], x[1]))
+    out = []
+    for sim, _id, h in scored[:max(0, k)]:
+        if sim <= 0.0:
+            break
+        # recall as training material; copy so the source archive is untouched
+        out.append(TaskRecord(
+            id=f"recall:{h.id}", project=h.project, intent=h.intent,
+            context_excerpt=h.context_excerpt, reference_kind=h.reference_kind,
+            reference=h.reference, judge=dict(h.judge), system=h.system,
+            tags=list(h.tags) + ["recall"], split="train", origin="real",
+            derived_from=h.id,
+        ))
+    return out
+
+
+# ── the shared nightly consolidation step ─────────────────────────────────────
+
+def dream_consolidate(
+    backend,
+    tasks: List[TaskRecord],
+    skill: str,
+    memory: str,
+    *,
+    history_tasks: Optional[List[TaskRecord]] = None,
+    recall_k: int = 0,
+    dream_rollouts: int = 1,
+    dream_factor: int = 0,
+    edit_budget: int = 4,
+    gate_metric: str = "mixed",
+    gate_mixed_weight: float = 0.5,
+    gate_mode: str = "on",
+    evolve_skill: bool = True,
+    evolve_memory: bool = True,
+    night: int = 1,
+) -> ConsolidationResult:
+    """Recall similar past experience + dream synthetic variants, then run one
+    gated consolidation epoch over the enlarged training pool.
+
+    ``tasks`` is the split-tagged pool for tonight (train + val); recall and
+    augmentation only enlarge the TRAIN split, so the val slice the gate scores
+    on is never polluted. With ``recall_k=0`` and ``dream_rollouts=1`` (the
+    defaults) this is exactly the previous single-shot ``consolidate``.
+    """
+    train = [t for t in tasks if t.split == "train"]
+    enlarged = list(tasks)
+    if recall_k > 0 and history_tasks:
+        enlarged += recall_similar(train, history_tasks, recall_k)
+    if dream_factor > 0:
+        seed = [t for t in enlarged if t.split == "train" and t.origin != "dream"]
+        enlarged += dream_augment(seed, factor=dream_factor)
+    return consolidate(
+        backend, enlarged, skill, memory,
+        edit_budget=edit_budget, gate_metric=gate_metric,
+        gate_mixed_weight=gate_mixed_weight, gate_mode=gate_mode,
+        rollouts_k=dream_rollouts, evolve_skill=evolve_skill,
+        evolve_memory=evolve_memory, night=night,
+    )

package/template/skills/skillopt-sleep/scripts/python/experiments/__init__.py

@@ -0,0 +1 @@
+"""SkillOpt-Sleep experiments."""

package/template/skills/skillopt-sleep/scripts/python/experiments/gbrain_bench.py

@@ -0,0 +1,119 @@
+"""SkillOpt-Sleep — gbrain-evals benchmark adapter.
+
+Loads gbrain-evals' `skillopt-v1` benchmark (deficient skills + train/held-out
+task sets with rule-based judges) into our TaskRecord format, so we can run the
+SkillOpt-Sleep cycle against the SAME suite gbrain publishes a scorecard for:
+
+  docs/benchmarks/2026-06-03-skillopt.md  — "4/4 skills 0 -> 1.00"
+
+Each gbrain seed dir has:
+  SKILL.md          — the deliberately deficient starting skill
+  benchmark.jsonl   — training tasks  {task_id, task, judge:{kind:"rule",checks}}
+  held-out.jsonl    — held-out tasks (same judge shape, unseen items)
+
+We map:
+  benchmark.jsonl -> TaskRecords with split="replay"
+  held-out.jsonl  -> TaskRecords with split="holdout"
+  judge           -> TaskRecord.judge (+ reference_kind="rule")
+
+This lets us reproduce gbrain's headline result with our engine and either the
+claude or codex backend, scoring locally via skillopt_sleep.judges (no judge API).
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Dict, List, Optional, Tuple
+
+from skillopt_sleep.types import TaskRecord
+
+
+SEED_DIRS = {
+    "brief-writer": "seed-missing-structure",
+    "thorough-analyst": "seed-verbose",
+    "advisor": "seed-no-verdict",
+    "quick-answerer": "seed-no-brain-first",
+}
+
+
+def _load_jsonl(path: str) -> List[dict]:
+    out: List[dict] = []
+    if not os.path.exists(path):
+        return out
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    out.append(json.loads(line))
+                except Exception:
+                    pass
+    return out
+
+
+def _to_task(rec: dict, *, seed: str, split: str) -> TaskRecord:
+    return TaskRecord(
+        id=f"{seed}:{rec.get('task_id', '')}",
+        project=f"gbrain/{seed}",
+        intent=str(rec.get("task", "")),
+        reference_kind="rule",
+        judge=rec.get("judge", {}) or {},
+        tags=[f"seed:{seed}"],
+        split=split,
+    )
+
+
+def load_seed(data_root: str, seed: str, *, val_fraction: float = 0.34,
+              split_seed: int = 42) -> Tuple[str, List[TaskRecord]]:
+    """Return (deficient_skill_md, tasks) for one gbrain seed.
+
+    Faithful split mapping:
+      * gbrain held-out.jsonl  -> our ``test`` (the true final measure)
+      * gbrain benchmark.jsonl -> split deterministically into ``train`` + ``val``
+        (val gates updates; train drives reflect)
+    All tasks are origin='real' (gbrain provides no synthetic tasks).
+    """
+    import hashlib
+    sub = SEED_DIRS.get(seed, seed)
+    seed_dir = os.path.join(data_root, sub)
+    skill_path = os.path.join(seed_dir, "SKILL.md")
+    skill = ""
+    if os.path.exists(skill_path):
+        with open(skill_path, encoding="utf-8") as f:
+            skill = f.read()
+    tasks: List[TaskRecord] = []
+    # benchmark pool -> train/val
+    val_cut = int(round(val_fraction * 100))
+    for rec in _load_jsonl(os.path.join(seed_dir, "benchmark.jsonl")):
+        t = _to_task(rec, seed=seed, split="train")
+        bucket = int(hashlib.sha256((str(split_seed) + t.id).encode()).hexdigest(), 16) % 100
+        t.split = "val" if bucket < val_cut else "train"
+        tasks.append(t)
+    # held-out -> test
+    for rec in _load_jsonl(os.path.join(seed_dir, "held-out.jsonl")):
+        tasks.append(_to_task(rec, seed=seed, split="test"))
+    # guarantee a non-empty val
+    if not any(t.split == "val" for t in tasks):
+        train_only = [t for t in tasks if t.split == "train"]
+        if train_only:
+            train_only[0].split = "val"
+    return skill, tasks
+
+
+def available_seeds(data_root: str) -> List[str]:
+    return [s for s, sub in SEED_DIRS.items()
+            if os.path.isdir(os.path.join(data_root, sub))]
+
+
+def find_data_root(explicit: str = "") -> Optional[str]:
+    """Locate eval/data/skillopt-v1 from common clone locations."""
+    cands = [explicit] if explicit else []
+    cands += [
+        os.path.expanduser("~/git/gbrain-evals/eval/data/skillopt-v1"),
+        "/tmp/gbrain-evals/eval/data/skillopt-v1",
+        os.path.expanduser("~/gbrain-evals/eval/data/skillopt-v1"),
+    ]
+    for c in cands:
+        if c and os.path.isdir(c):
+            return c
+    return None

package/template/skills/skillopt-sleep/scripts/python/experiments/personas.py

@@ -0,0 +1,86 @@
+"""SkillOpt-Sleep — persona task fixtures for the validation experiment.
+
+Each persona is a list of TaskRecords with EXACT checkable references and a
+`rule:<key>` tag naming the single skill rule that makes the task solvable
+(consumed by MockBackend). This lets the experiment prove — deterministically,
+with no API — that nightly consolidation lifts a held-out score and that the
+gate blocks regressions.
+
+Personas mirror the user's framing: programmer / researcher / analyst.
+"""
+from __future__ import annotations
+
+from typing import List
+
+from skillopt_sleep.types import TaskRecord
+
+
+def _t(i, intent, ref, rule, project="/personas/demo", outcome="fail") -> TaskRecord:
+    return TaskRecord(
+        id=f"persona_{rule}_{i}",
+        project=project,
+        intent=intent,
+        context_excerpt="",
+        attempted_solution="",
+        outcome=outcome,
+        reference_kind="exact",
+        reference=ref,
+        tags=[f"rule:{rule}"],
+        source_sessions=[f"sess_{i}"],
+    )
+
+
+def researcher_persona() -> List[TaskRecord]:
+    """Researcher who always wants arXiv ids wrapped in <answer> tags."""
+    items = [
+        ("Give me the arXiv id for the SkillOpt paper", "arXiv:2605.23904"),
+        ("What's the arXiv id of the Attention paper?", "arXiv:1706.03762"),
+        ("arXiv id for the GAN paper?", "arXiv:1406.2661"),
+        ("arXiv id for BERT?", "arXiv:1810.04805"),
+        ("arXiv id for the ResNet paper?", "arXiv:1512.03385"),
+        ("arXiv id for the Adam optimizer paper?", "arXiv:1412.6980"),
+        ("arXiv id for Dropout?", "arXiv:1207.0580"),
+        ("arXiv id for the Transformer-XL paper?", "arXiv:1901.02860"),
+        ("arXiv id for word2vec?", "arXiv:1301.3781"),
+        ("arXiv id for the VAE paper?", "arXiv:1312.6114"),
+        ("arXiv id for batch norm?", "arXiv:1502.03167"),
+        ("arXiv id for GPT-3?", "arXiv:2005.14165"),
+    ]
+    # Both rules required: format the id (arxiv-id) AND wrap in answer tags.
+    out: List[TaskRecord] = []
+    for i, (q, a) in enumerate(items):
+        t = _t(i, q, a, "wrap-answer")
+        t.tags = ["rule:wrap-answer", "rule:arxiv-id"]
+        out.append(t)
+    return out
+
+
+def programmer_persona() -> List[TaskRecord]:
+    """Programmer who wants imperative-mood commit subjects."""
+    items = [
+        ("commit message for adding a login form", "Add login form"),
+        ("commit message for fixing the null pointer bug", "Fix null pointer in parser"),
+        ("commit message for updating the README", "Update README"),
+        ("commit message for removing dead code", "Remove dead code"),
+        ("commit message for bumping the version", "Bump version to 1.2.0"),
+        ("commit message for refactoring the auth module", "Refactor auth module"),
+        ("commit message for adding tests", "Add unit tests for scheduler"),
+        ("commit message for fixing the CI pipeline", "Fix CI pipeline"),
+    ]
+    return [_t(i, q, a, "commit-imperative") for i, (q, a) in enumerate(items)]
+
+
+def harmful_edit_task() -> TaskRecord:
+    """A task whose 'fix' is a known-bad rule; used to prove the gate rejects
+    regressions. The MockBackend proposes the harmful rule on this failure,
+    but applying it does NOT raise the held-out score, so the gate must reject.
+    """
+    t = _t(99, "answer this freely", "THIS_WILL_NOT_MATCH", "__harmful__")
+    t.reference = "an-answer-that-the-harmful-rule-cannot-produce"
+    return t
+
+
+PERSONAS = {
+    "researcher": researcher_persona,
+    "programmer": programmer_persona,
+}