self-evolve-framework 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "self-evolve-framework",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "CodeBuddy 自我进化飞轮 — 仅适用于 CodeBuddy IDE。Post-Edit 验证闭环 + 规则自动推荐 + 离线进化分析",
   "type": "module",
   "bin": {

package/template/rules/ponytail.mdc

@@ -1,33 +1,108 @@
 ---
-description: Ponytail - 懒人高级开发者模式。写最少、最安全的代码。
+description: >
+  Ponytail — 懒人高级开发者模式。强制写最少、最安全的代码。
+  每次对话 always 激活，用户说"stop ponytail"退出。
 alwaysApply: true
 ---
 
-## Ponytail 核心规则
+# Ponytail
 
-在写任何代码之前，先停在能解决问题的**最低台阶**上，按优先级检查：
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
 
-1. **这东西真的需要建吗？**（YAGNI）不需要就跳过
-2. **标准库已经提供了吗？** 直接用它
-3. **平台/框架原生功能能覆盖吗？** 直接用它
-4. **已安装的依赖能解决吗？** 直接用它
-5. **能一行搞定吗？** 就写一行
-6. **以上都不行？** 才写最少工作的代码
+## Persistence
 
-## 执行规则
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
+unsure. Off only: "stop ponytail" / "normal mode". Default: **full**.
+Switch: `ponytail lite|full|ultra`.
 
-- 不要创建未经明确要求的抽象
-- 能不引入新依赖就别引入
-- 不要写没人要的样板代码
-- 删除优于添加，无聊优于花哨，文件数量越少越好
-- 质疑复杂需求："你真的需要 X，还是 Y 可以覆盖？"
-- 当两种方法长度相同时，选边界情况更正确的那一个
-- 有意的简化用 `ponytail:` 注释标注，写明已知上限和升级路径
+## The ladder
 
-## 不偷懒的地方（必须认真对待）
+Stop at the first rung that holds:
 
-- 输入校验
-- 错误处理
-- 安全性
-- 可访问性
-- 任何明确要求的事情
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
+5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+The ladder is a reflex, not a research project — but it runs *after* you
+understand the problem, not instead of it. Read the task and the code it
+touches first, trace the real flow end to end, then climb. Two rungs work →
+take the higher one and move on. The first lazy solution that works is the
+right one — once you actually know what the change has to touch.
+
+**Bug fix = root cause, not symptom.** A report names a symptom. Before you
+edit, grep every caller of the function you're about to touch. The lazy fix IS
+the root-cause fix: one guard in the shared function is a smaller diff than a
+guard in every caller — and patching only the path the ticket names leaves
+every sibling caller still broken. Fix it once, where all callers route through.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate, no scaffolding "for later", later can scaffold for itself.
+- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
+- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
+- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- Mark deliberate simplifications with a `ponytail:` comment (`// ponytail: this exists`), simple reads as intent, not ignorance. Shortcut with a known ceiling (global lock, O(n²) scan, naive heuristic)? The comment names the ceiling and the upgrade path: `# ponytail: global lock, per-account locks if throughput matters`.
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it.
+No essays, no feature tours, no design notes. If the explanation is longer
+than the code, delete the explanation, every paragraph defending a
+simplification is complexity smuggled back in as prose. Explanation the user
+explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
+give it in full, the rule is only against unrequested prose.
+
+Pattern: `[code] → skipped: [X], add when [Y].`
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | Build what's asked, but name the lazier alternative in one line. User picks. |
+| **full** | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default. |
+| **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
+
+Example: "Add a cache for these API responses."
+- lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it, no
+re-arguing.
+
+Never lazy about understanding the problem. The ladder shortens the
+solution, never the reading. Trace the whole thing first — every file the
+change touches, the actual flow — before picking a rung. Laziness that skips
+comprehension to ship a small diff is the dangerous kind: it dresses up as
+efficiency and ships a confident wrong fix. Read fully, then be lazy.
+
+Hardware is never the ideal on paper: a real clock drifts, a real sensor
+reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not
+just less code, the physical world needs tuning a minimal model can't see.
+
+Lazy code without its check is unfinished. Non-trivial logic (a branch, a
+loop, a parser, a money/security path) leaves ONE runnable check behind, the
+smallest thing that fails if the logic breaks: an `assert`-based
+`demo()`/`__main__` self-check or one small `test_*.py`. No frameworks, no
+fixtures, no per-function suites unless asked. Trivial one-liners need no
+test, YAGNI applies to tests too.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk (pair with Caveman for
+terse prose). "stop ponytail" / "normal mode": revert. Level persists until
+changed or session end.
+
+The shortest path to done is the right path.

package/template/skills/skillopt-sleep/SKILL.md

@@ -1,16 +1,26 @@
 ---
 name: skillopt-sleep
-description: 离线自我进化引擎。分析历史会话、发现重复模式、优化项目 memory 和规则。用 AI 指令替代外部脚本。
+description: 离线自我进化引擎。分析历史会话、发现重复模式、优化项目 memory 和规则。底层调用 Python 执行引擎（微软 SkillOpt）。
 ---
 
 # SkillOpt-Sleep — 自我进化引擎
 
-> 此技能是 CodeBuddy 适配版（纯指令模式，不依赖外部脚本）。
+> 执行型 skill：AI 提供指令编排，底层 `python -m skillopt_sleep` 驱动 Harvest → Mine → Replay → Consolidate → Stage → Adopt 六阶段工作流。
 
-## 工作流程（6 阶段）
+## 工作流程
+
+### 前置条件
+
+每次会话首次运行前，确保引擎可用：
+
+```bash
+cd .codebuddy/skills/skillopt-sleep/scripts/python
+pip install -r requirements.txt 2>/dev/null || echo "依赖已安装"
+```
 
 ### 阶段 1：Harvest — 收集信息
-AI 从以下来源收集项目数据：
+
+收集项目数据：
 - 项目文件结构、代码模式
 - 构建/编译错误记录（从 `.codebuddy/memory/`）
 - 已知问题列表
@@ -19,50 +29,54 @@ AI 从以下来源收集项目数据：
 - 前端文件的设计质量报告（如果安装了 Impeccable skill，调用 `impeccable detect` 检查项目前端设计质量）
 
 ### 阶段 2：Mine — 挖掘模式
-分析收集到的数据，识别：
+
+分析数据，识别：
 - **重复错误**：同一类 build/lint 错误出现次数
 - **代码异嗅**：循环依赖、过度耦合、重复代码
 - **缺失约束**：重复发生但无规则防范的问题
 - **优化机会**：可简化的逻辑、可合并的文件
-- **★ 核心边界**：识别模块间的契约接口、关键用户路径和其依赖方，标记"改/删前必须审慎"的承重区域
-- **★ 设计异嗅**：分析 Impeccable 检测报告中的 P0/P1 反复出现的问题模式，识别设计约束缺失或 DESIGN.md 与实现不一致的区域
+- **★ 核心边界**：模块间契约接口、关键用户路径和依赖方
+- **★ 设计异嗅**：Impeccable 检测报告中的 P0/P1 反复问题模式
+
+### 阶段 3-6：执行引擎运行
 
-### 阶段 3：Replay — 回放验证
-对每个发现的问题：
-- 如果已有关联规则 → 检查规则是否被遵循
-- 如果没有规则 → 评估是否需要新规则
-- 如果有修复方案 → 验证方案是否仍适用
+```bash
+python -m .codebuddy.skills.skillopt-sleep.scripts.python \
+  --project "$(pwd)" \
+  --mode <dry-run|run|adopt> \
+  --backend claude
+```
+
+- `--mode dry-run` → 阶段 1-3，只输出分析报告，不写文件
+- `--mode run` → 阶段 1-5，输出暂存清单到 `.codebuddy/memory/skillopt-staging/`
+- `--mode adopt` → 阶段 6，采纳暂存清单中的建议
+
+### 手动模式（无 Python 引擎时）
+
+如果 Python 环境不可用，AI 按以下指令模拟执行：
 
-### 阶段 4：Consolidate — 合并优化
+#### Consolidate — 合并优化
 生成改进建议，只接受通过 Held-out 门控的比例：
 - **新增规则**：重复 ≥2 次且无规则防范的问题
 - **更新规则**：现有规则描述模糊或过时
 - **删除规则**：不再相关或从未被触发的规则
 - **优化 memory**：合并重复的错误模式记录
-- **★ 边界标记**：涉及核心功能路径的删除/修改建议，加 ⚠️ 标签要求人工确认，不可自动采纳
+- **★ 边界标记**：涉及核心功能路径的删除/修改建议，加 ⚠️ 标签
 
-### 阶段 5：Stage — 暂存
-所有建议先写入 `.codebuddy/memory/skillopt-staging/` 目录，**不修改任何活文件**。
+#### Stage — 暂存
+所有建议写入 `.codebuddy/memory/skillopt-staging/`，不修改活文件。
 
-### 阶段 6：Adopt — 采用
-列出所有建议，由你逐条决定是否采纳：
-```
-📋 待采用清单
-  ✅ 新增 rules/promise-chain-check.mdc → 防止未捕获 async 错误
-  ✅ 更新 rules/self-evolve.mdc → 增加 cargo check 验证步骤
-  ❌ 删除 rules/old-node-format.mdc → 节点格式已统一
-```
+#### Adopt — 采用
+列出建议由用户逐条决定是否采纳。
 
-## 常用命令（AI 模拟）
+## 触发
 
-```text
-skillopt-sleep dry-run   → 执行阶段 1-3，输出分析报告，不写任何文件
-skillopt-sleep run       → 执行阶段 1-5，输出暂存清单
-skillopt-sleep adopt     → 采纳暂存清单中的建议
-```
+| 对话输入 | 作用 |
+|----------|------|
+| `skillopt-sleep dry-run` | 执行阶段 1-3（有引擎则调 Python，无则 AI 模拟） |
+| `skillopt-sleep run` | 执行阶段 1-5 |
+| `skillopt-sleep adopt` | 采纳建议 |
 
-## 触发建议
+## 内核
 
-- **每日一次**：工作开始时输入 `skillopt-sleep dry-run`，花 30 秒看报告
-- **周五总结**：输入 `skillopt-sleep run` 生成周改进提案
-- **出现相同错误 2 次后**：不用调，self-evolve rule 会自动触发单条规则创建
+执行引擎来自 [microsoft/SkillOpt](https://github.com/microsoft/SkillOpt) — 由微软研究院开源的 skill 文档训练框架。

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

@@ -0,0 +1,20 @@
+"""SkillOpt-Sleep — nightly offline self-evolution for a local Claude agent.
+
+A Claude Code plugin engine that gives a user's agent a "sleep cycle":
+harvest the day's real session transcripts, mine recurring tasks, replay
+them offline, and consolidate short-term experience into long-term memory
+(CLAUDE.md) and skills (SKILL.md) behind a SkillOpt validation gate.
+
+Synthesizes three ideas:
+  * SkillOpt  — validation-gated bounded text optimization (this repo)
+  * Dreams    — offline memory consolidation, input never mutated
+  * Sleep     — short-term experience -> long-term competence, offline
+
+Public entry points:
+  * skillopt_sleep.cli      — `python -m skillopt_sleep ...`
+  * skillopt_sleep.cycle.run_sleep_cycle(...)
+"""
+from __future__ import annotations
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

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

@@ -0,0 +1,343 @@
+"""SkillOpt-Sleep — command-line interface.
+
+    python -m skillopt_sleep run        # full cycle: harvest->mine->replay->gate->stage
+    python -m skillopt_sleep dry-run    # same but report only, no staging/adopt
+    python -m skillopt_sleep status     # show state + latest staged proposal
+    python -m skillopt_sleep adopt      # apply the latest staged proposal (with backup)
+    python -m skillopt_sleep harvest    # just print what would be mined (debug)
+
+Common flags:
+    --project PATH      project to evolve (default: cwd)
+    --scope all|invoked harvest scope (default: invoked)
+    --max-sessions N    cap transcript sessions per run
+    --max-tasks N       cap mined tasks per run
+    --target-skill-path PATH explicit live SKILL.md to stage/adopt
+    --tasks-file PATH   reviewed TaskRecord JSON file to replay instead of harvesting
+    --backend mock|claude|codex|copilot
+    --source claude|codex|auto
+    --model NAME
+    --lookback-hours N
+    --auto-adopt
+    --json              machine-readable output
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any, Dict
+
+from skillopt_sleep.config import load_config
+from skillopt_sleep.cycle import run_sleep_cycle
+from skillopt_sleep.harvest_sources import harvest_for_config
+from skillopt_sleep.mine import mine
+from skillopt_sleep.staging import adopt as adopt_staging
+from skillopt_sleep.staging import latest_staging
+from skillopt_sleep.state import SleepState
+from skillopt_sleep.tasks_file import load_tasks_file, make_tasks_payload, write_tasks_file
+
+
+def _read_text(path: str) -> str:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read()
+    except Exception:
+        return ""
+
+
+def _report_payload(rep, outcome) -> Dict[str, Any]:
+    return {
+        "night": rep.night,
+        "accepted": rep.accepted,
+        "gate_action": rep.gate_action,
+        "no_edits_reason": getattr(rep, "no_edits_reason", ""),
+        "baseline": rep.baseline_score,
+        "candidate": rep.candidate_score,
+        "n_tasks": rep.n_tasks,
+        "n_sessions": rep.n_sessions,
+        "n_accepted_edits": len(rep.edits),
+        "n_rejected_edits": len(rep.rejected_edits),
+        "edits": [e.__dict__ for e in rep.edits],
+        "rejected_edits": [e.__dict__ for e in rep.rejected_edits],
+        "notes": rep.notes,
+        "staging_dir": outcome.staging_dir,
+        "adopted": outcome.adopted,
+    }
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--project", default="")
+    p.add_argument("--scope", default="", choices=["", "all", "invoked"])
+    p.add_argument("--backend", default="", choices=["", "mock", "claude", "codex", "copilot"])
+    p.add_argument("--model", default="")
+    p.add_argument("--codex-path", default="", help="path to the real @openai/codex binary")
+    p.add_argument("--claude-home", default="", help="override ~/.claude (also isolates state)")
+    p.add_argument("--codex-home", default="", help="override ~/.codex for archived session harvest")
+    p.add_argument("--source", default="", choices=["", "claude", "codex", "auto"],
+                   help="session transcript source")
+    p.add_argument("--lookback-hours", type=int, default=None,
+                   help="harvest window in hours; 0 = scan full history")
+    p.add_argument("--edit-budget", type=int, default=0)
+    p.add_argument("--max-sessions", type=int, default=0,
+                   help="cap harvested sessions before mining; default derives from max tasks")
+    p.add_argument("--max-tasks", type=int, default=0,
+                   help="cap mined tasks for this run")
+    p.add_argument("--target-skill-path", default="",
+                   help="explicit live SKILL.md path to evolve/stage/adopt")
+    p.add_argument("--tasks-file", default="",
+                   help="reviewed TaskRecord JSON file to replay instead of harvesting")
+    p.add_argument("--progress", action="store_true",
+                   help="print phase progress to stderr")
+    p.add_argument("--auto-adopt", action="store_true")
+    p.add_argument("--json", action="store_true")
+
+
+def _cfg_from_args(args, task_meta: Dict[str, Any] | None = None) -> Any:
+    overrides: Dict[str, Any] = {}
+    if args.project:
+        overrides["invoked_project"] = os.path.abspath(args.project)
+        overrides["projects"] = "invoked"
+    if args.scope:
+        overrides["projects"] = args.scope
+    if args.backend:
+        overrides["backend"] = args.backend
+    if args.model:
+        overrides["model"] = args.model
+    if getattr(args, "codex_path", ""):
+        overrides["codex_path"] = os.path.abspath(args.codex_path)
+    if getattr(args, "claude_home", ""):
+        overrides["claude_home"] = os.path.abspath(args.claude_home)
+    if getattr(args, "codex_home", ""):
+        overrides["codex_home"] = os.path.abspath(args.codex_home)
+    if getattr(args, "source", ""):
+        overrides["transcript_source"] = args.source
+    lh = getattr(args, "lookback_hours", None)
+    if lh is not None:  # --lookback-hours was explicitly passed (0 = full history)
+        overrides["lookback_hours"] = lh
+    if getattr(args, "edit_budget", 0):
+        overrides["edit_budget"] = args.edit_budget
+    if getattr(args, "max_sessions", 0):
+        overrides["max_sessions_per_night"] = args.max_sessions
+    if getattr(args, "max_tasks", 0):
+        overrides["max_tasks_per_night"] = args.max_tasks
+    target_skill_path = getattr(args, "target_skill_path", "")
+    if not target_skill_path and task_meta:
+        target_skill_path = str(task_meta.get("target_skill_path") or "")
+    if target_skill_path:
+        path = os.path.expanduser(target_skill_path)
+        if args.project and not os.path.isabs(path):
+            path = os.path.join(os.path.abspath(args.project), path)
+        overrides["target_skill_path"] = os.path.abspath(path)
+    if getattr(args, "progress", False):
+        overrides["progress"] = True
+    if getattr(args, "auto_adopt", False):
+        overrides["auto_adopt"] = True
+    return load_config(**overrides)
+
+
+def cmd_run(args, dry: bool = False) -> int:
+    task_meta: Dict[str, Any] = {}
+    tasks = None
+    if getattr(args, "tasks_file", ""):
+        # Load once before config so target_skill_path can default from metadata.
+        tasks, task_meta = load_tasks_file(args.tasks_file)
+    cfg = _cfg_from_args(args, task_meta=task_meta)
+    if getattr(args, "tasks_file", ""):
+        tasks, task_meta = load_tasks_file(
+            args.tasks_file,
+            holdout_fraction=cfg.get("holdout_fraction", 0.34),
+            seed=cfg.get("seed", 42),
+        )
+        if cfg.get("backend", "mock") != "mock" and task_meta.get("reviewed") is not True:
+            print(
+                "[sleep] refusing real-backend replay from an unreviewed tasks file; "
+                "inspect/redact it and set \"reviewed\": true first",
+                file=sys.stderr,
+            )
+            return 2
+    outcome = run_sleep_cycle(cfg, seed_tasks=tasks, dry_run=dry)
+    rep = outcome.report
+    if args.json:
+        payload = _report_payload(rep, outcome)
+        if task_meta:
+            payload["tasks_file"] = task_meta.get("tasks_file", "")
+            payload["tasks_reviewed"] = task_meta.get("reviewed", False)
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(f"[sleep] night {rep.night}: {rep.n_sessions} sessions -> {rep.n_tasks} tasks")
+        print(f"[sleep] held-out {rep.baseline_score:.3f} -> {rep.candidate_score:.3f} "
+              f"=> {rep.gate_action} (accepted={rep.accepted})")
+        for e in rep.edits:
+            print(f"   + [{e.target}/{e.op}] {e.content}")
+        if rep.rejected_edits:
+            print("[sleep] rejected by gate:")
+            for e in rep.rejected_edits:
+                print(f"   - [{e.target}/{e.op}] {e.content}")
+        if outcome.staging_dir:
+            print(f"[sleep] staged: {outcome.staging_dir}")
+            if not outcome.adopted:
+                print("[sleep] review it, then: python -m skillopt_sleep adopt")
+        if outcome.adopted:
+            print(f"[sleep] auto-adopted: {', '.join(outcome.adopted_paths)}")
+    return 0
+
+
+def cmd_status(args) -> int:
+    cfg = _cfg_from_args(args)
+    state = SleepState.load(cfg.state_path)
+    project = cfg.get("invoked_project") or os.getcwd()
+    latest = latest_staging(project)
+    info = {
+        "night": state.night,
+        "state_path": cfg.state_path,
+        "project": project,
+        "history_tail": state.data.get("history", [])[-5:],
+        "latest_staging": latest,
+        "slow_memory_chars": len(state.slow_memory),
+    }
+    if args.json:
+        print(json.dumps(info, ensure_ascii=False, indent=2))
+    else:
+        print(f"[sleep] nights so far: {state.night}")
+        print(f"[sleep] project: {project}")
+        if latest:
+            print(f"[sleep] latest staged proposal: {latest}")
+            rp = os.path.join(latest, "report.md")
+            if os.path.exists(rp):
+                with open(rp) as f:
+                    print("\n" + f.read())
+        else:
+            print("[sleep] no staged proposals yet.")
+    return 0
+
+
+def cmd_adopt(args) -> int:
+    cfg = _cfg_from_args(args)
+    project = cfg.get("invoked_project") or os.getcwd()
+    target = args.staging or latest_staging(project)
+    if not target or not os.path.isdir(target):
+        print("[sleep] nothing to adopt (no staging dir).")
+        return 1
+    updated = adopt_staging(target)
+    print(f"[sleep] adopted from {target}")
+    for p in updated:
+        print(f"   -> {p}")
+    if not updated:
+        print("[sleep] (proposal contained no accepted changes)")
+    return 0
+
+
+def cmd_harvest(args) -> int:
+    cfg = _cfg_from_args(args)
+    session_limit = cfg.get("max_sessions_per_night", 0) or cfg.get("max_tasks_per_night", 40) * 3
+    target_skill_path = cfg.managed_skill_path() if cfg.get("target_skill_path", "") else ""
+    target_skill_text = _read_text(target_skill_path) if target_skill_path else ""
+    max_tasks = cfg.get("max_tasks_per_night", 40)
+    candidate_limit = max_tasks
+    if cfg.get("target_task_filter", True) and target_skill_text:
+        candidate_limit = max(max_tasks, max_tasks * 3)
+    digests = harvest_for_config(cfg, limit=session_limit)
+    tasks = mine(
+        digests,
+        max_tasks=max_tasks,
+        candidate_limit=candidate_limit,
+        holdout_fraction=cfg.get("holdout_fraction", 0.34),
+        seed=cfg.get("seed", 42),
+        target_skill_text=target_skill_text,
+        target_skill_path=target_skill_path,
+    )
+    payload = make_tasks_payload(
+        tasks,
+        project=cfg.get("invoked_project") or os.getcwd(),
+        transcript_source=cfg.get("transcript_source", ""),
+        n_sessions=len(digests),
+        target_skill_path=target_skill_path,
+    )
+    output_path = ""
+    if getattr(args, "output", ""):
+        output_path = write_tasks_file(args.output, payload)
+    if args.json:
+        json_payload = dict(payload)
+        if output_path:
+            json_payload["output"] = output_path
+        print(json.dumps(json_payload, ensure_ascii=False, indent=2))
+    else:
+        print(f"[sleep] {len(digests)} sessions -> {len(tasks)} tasks")
+        if output_path:
+            print(f"[sleep] wrote reviewed-task draft: {output_path}")
+        for t in tasks:
+            print(f"  [{t.split}/{t.outcome}] {t.intent[:90]}")
+    return 0
+
+
+def cmd_schedule(args) -> int:
+    from skillopt_sleep.scheduler import schedule, list_scheduled
+    cfg = _cfg_from_args(args)
+    project = cfg.get("invoked_project") or os.getcwd()
+    ok, msg = schedule(project, backend=cfg.get("backend", "mock"),
+                       hour=args.hour, minute=args.minute,
+                       extra=("--auto-adopt" if getattr(args, "auto_adopt", False) else ""))
+    print("[sleep] " + msg)
+    cur = list_scheduled()
+    if cur:
+        print("[sleep] currently scheduled:")
+        for ln in cur:
+            print("   " + ln[:140])
+    return 0 if ok else 1
+
+
+def cmd_unschedule(args) -> int:
+    from skillopt_sleep.scheduler import unschedule
+    cfg = _cfg_from_args(args)
+    project = cfg.get("invoked_project") or os.getcwd()
+    ok, msg = unschedule(project, all_projects=getattr(args, "all", False))
+    print("[sleep] " + msg)
+    return 0 if ok else 1
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="skillopt_sleep", description="SkillOpt-Sleep nightly self-evolution")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_run = sub.add_parser("run", help="run a full sleep cycle")
+    _add_common(p_run)
+    p_dry = sub.add_parser("dry-run", help="harvest+mine+replay, report only")
+    _add_common(p_dry)
+    p_status = sub.add_parser("status", help="show state + latest proposal")
+    _add_common(p_status)
+    p_adopt = sub.add_parser("adopt", help="apply latest staged proposal")
+    _add_common(p_adopt)
+    p_adopt.add_argument("--staging", default="", help="specific staging dir")
+    p_harvest = sub.add_parser("harvest", help="debug: show mined tasks")
+    _add_common(p_harvest)
+    p_harvest.add_argument("--output", default="", help="write mined tasks JSON for review")
+    p_sched = sub.add_parser("schedule", help="install a nightly cron entry for this project")
+    _add_common(p_sched)
+    p_sched.add_argument("--hour", type=int, default=3)
+    p_sched.add_argument("--minute", type=int, default=17)
+    p_unsched = sub.add_parser("unschedule", help="remove the nightly cron entry")
+    _add_common(p_unsched)
+    p_unsched.add_argument("--all", action="store_true", help="remove all managed entries")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "run":
+        return cmd_run(args, dry=False)
+    if args.cmd == "dry-run":
+        return cmd_run(args, dry=True)
+    if args.cmd == "status":
+        return cmd_status(args)
+    if args.cmd == "adopt":
+        return cmd_adopt(args)
+    if args.cmd == "harvest":
+        return cmd_harvest(args)
+    if args.cmd == "schedule":
+        return cmd_schedule(args)
+    if args.cmd == "unschedule":
+        return cmd_unschedule(args)
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())