self-evolve-framework 1.2.0 → 1.4.0

package/template/skills/ponytail/scripts/hooks/ponytail-runtime.js

@@ -0,0 +1,68 @@
+const fs = require('fs');
+const path = require('path');
+const { getClaudeDir } = require('./ponytail-config');
+
+const STATE_FILE = '.ponytail-active';
+const isCopilot = Boolean(process.env.COPILOT_PLUGIN_DATA);
+const isCodex = !isCopilot && Boolean(process.env.PLUGIN_DATA);
+
+let stateDir = getClaudeDir();
+if (isCodex) stateDir = process.env.PLUGIN_DATA;
+if (isCopilot) stateDir = process.env.COPILOT_PLUGIN_DATA;
+
+const statePath = path.join(stateDir, STATE_FILE);
+
+function setMode(mode) {
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, mode);
+}
+
+function clearMode() {
+  try { fs.unlinkSync(statePath); } catch (e) {}
+}
+
+// Live mode written by activate/mode-tracker. Absent flag = ponytail off.
+function readMode() {
+  try {
+    return fs.readFileSync(statePath, 'utf8').trim() || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function writeHookOutput(event, mode, context = '') {
+  if (isCopilot) {
+    // Copilot reads additionalContext on SessionStart; ignores output elsewhere.
+    process.stdout.write(JSON.stringify(
+      event === 'SessionStart' && context ? { additionalContext: context } : {}));
+    return;
+  }
+  if (isCodex) {
+    const output = { systemMessage: `PONYTAIL:${mode.toUpperCase()}` };
+    if (context) {
+      output.hookSpecificOutput = {
+        hookEventName: event,
+        additionalContext: context,
+      };
+    }
+    process.stdout.write(JSON.stringify(output));
+    return;
+  }
+  // Native Claude: SessionStart accepts raw stdout, but SubagentStart needs the
+  // hookSpecificOutput JSON form or the context is dropped.
+  if (event === 'SubagentStart') {
+    process.stdout.write(JSON.stringify(
+      { hookSpecificOutput: { hookEventName: event, additionalContext: context } }));
+    return;
+  }
+  process.stdout.write(context);
+}
+
+module.exports = {
+  clearMode,
+  isCodex,
+  isCopilot,
+  readMode,
+  setMode,
+  writeHookOutput,
+};

package/template/skills/ponytail/scripts/hooks/ponytail-statusline.ps1

@@ -0,0 +1,21 @@
+# CLAUDE_CONFIG_DIR overrides ~/.claude, matching where the hooks write the flag (issue #34)
+$ClaudeDir = if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $HOME ".claude" }
+$Flag = Join-Path $ClaudeDir ".ponytail-active"
+if (-not (Test-Path $Flag)) {
+    exit 0
+}
+
+$Mode = ""
+try {
+    $Mode = (Get-Content $Flag -ErrorAction Stop | Select-Object -First 1).Trim()
+} catch {
+    exit 0
+}
+
+$Esc = [char]27
+if ([string]::IsNullOrEmpty($Mode) -or $Mode -eq "full") {
+    [Console]::Write("${Esc}[38;5;108m[PONYTAIL]${Esc}[0m")
+} else {
+    $Suffix = $Mode.ToUpperInvariant()
+    [Console]::Write("${Esc}[38;5;108m[PONYTAIL:$Suffix]${Esc}[0m")
+}

package/template/skills/ponytail/scripts/hooks/ponytail-statusline.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# CLAUDE_CONFIG_DIR overrides ~/.claude, matching where the hooks write the flag (issue #34)
+flag="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.ponytail-active"
+[ -f "$flag" ] || exit 0
+
+mode=$(head -n1 "$flag" | tr -d '[:space:]')
+
+if [ -z "$mode" ] || [ "$mode" = "full" ]; then
+    printf '\033[38;5;108m[PONYTAIL]\033[0m'
+else
+    printf '\033[38;5;108m[PONYTAIL:%s]\033[0m' "$(printf '%s' "$mode" | tr '[:lower:]' '[:upper:]')"
+fi

package/template/skills/ponytail/scripts/hooks/ponytail-subagent.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// ponytail — Claude Code SubagentStart hook
+//
+// SessionStart context is parent-thread only and never reaches subagents, so
+// without this every Task-spawned agent runs ponytail-unaware (issue #252).
+// When ponytail mode is active, inject the same ruleset into each subagent.
+
+const { getPonytailInstructions } = require('./ponytail-instructions');
+const { readMode, writeHookOutput } = require('./ponytail-runtime');
+
+const mode = readMode();
+
+// Absent flag or off → ponytail isn't active; inject nothing.
+if (!mode || mode === 'off') {
+  process.exit(0);
+}
+
+try {
+  writeHookOutput('SubagentStart', mode, getPonytailInstructions(mode));
+} catch (e) {
+  // Silent fail — a stdout error at hook exit must not surface as a hook failure.
+}

package/template/skills/ponytail/scripts/mcp/README.md

@@ -0,0 +1,46 @@
+# ponytail-mcp
+
+An MCP server that serves Ponytail's lazy-senior-dev instructions. It exposes
+the same ruleset the Claude hooks and Pi extension use, so every host emits
+identical rules.
+
+It is not a replacement for the always-on adapters. Ponytail normally lives in
+the system context every turn. MCP prompts are user-invoked, and there is no
+portable MCP primitive for "inject this into every turn" across hosts. So this
+server is the clean option for MCP hosts whose only injection point is the
+prompt menu, or that pull context through tools. See issue #70.
+
+## What it exposes
+
+- Prompt `ponytail`, returns the ruleset as a user message. Optional `mode`
+  argument: `lite`, `full`, or `ultra`. Omit it to use the configured default.
+- Tool `ponytail_instructions`, same text, plus `structuredContent`
+  (`{ mode, instructions }`), for hosts that pull context via tools or code
+  execution. Read-only.
+
+Mode resolution reuses `hooks/ponytail-config.js`, so `PONYTAIL_DEFAULT_MODE`
+and `~/.config/ponytail/config.json` work the same as everywhere else.
+
+## Run it
+
+```bash
+cd ponytail-mcp
+npm install
+node index.js        # speaks MCP over stdio
+```
+
+Point an MCP host at that command. Example client entry:
+
+```json
+{ "mcpServers": { "ponytail": { "command": "node", "args": ["ponytail-mcp/index.js"] } } }
+```
+
+## Test
+
+```bash
+npm test
+```
+
+Covers mode resolution and the instruction text. The MCP wiring in `index.js`
+is intentionally thin: it just maps the prompt and tool onto
+`buildInstructions`.

package/template/skills/ponytail/scripts/mcp/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Ponytail MCP server: serves the lazy-senior-dev ruleset over stdio as a
+// prompt (user-invoked) and a tool (for hosts that pull context via tools).
+// It does NOT replace the always-on adapters; it's the clean option for hosts
+// whose only injection point is the prompt menu (see #70).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { MODES, buildInstructions, resolveMode } from "./instructions.js";
+
+const server = new McpServer({ name: "ponytail", version: "0.1.0" });
+
+const modeArg = z
+  .enum(MODES)
+  .optional()
+  .describe("Ponytail intensity: lite, full, or ultra. Omit for the configured default.");
+
+server.registerPrompt(
+  "ponytail",
+  {
+    title: "Ponytail mode",
+    description: "Lazy senior dev instructions: YAGNI, stdlib first, the smallest correct change.",
+    argsSchema: { mode: modeArg },
+  },
+  ({ mode }) => ({
+    messages: [{ role: "user", content: { type: "text", text: buildInstructions(mode) } }],
+  }),
+);
+
+server.registerTool(
+  "ponytail_instructions",
+  {
+    title: "Ponytail instructions",
+    description: "Return the Ponytail ruleset for the given intensity (lite, full, or ultra).",
+    inputSchema: { mode: modeArg },
+    outputSchema: { mode: z.string(), instructions: z.string() },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  ({ mode }) => {
+    const resolvedMode = resolveMode(mode);
+    const instructions = buildInstructions(resolvedMode);
+    const structuredContent = { mode: resolvedMode, instructions };
+    return { content: [{ type: "text", text: instructions }], structuredContent };
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/template/skills/ponytail/scripts/mcp/instructions.js

@@ -0,0 +1,26 @@
+// Pure instruction selection for the Ponytail MCP server. No MCP/SDK imports,
+// so this stays unit-testable on its own. Reuses the same builder the Claude
+// hooks and Pi extension use, so every host emits identical rules.
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const { getPonytailInstructions } = require("../hooks/ponytail-instructions.js");
+const { getDefaultMode, normalizeMode } = require("../hooks/ponytail-config.js");
+
+// The three intensities the server offers. "off" has no instructions to serve.
+export const MODES = ["lite", "full", "ultra"];
+
+// Resolve a requested mode to a runtime intensity. Unknown, empty, or "off"
+// falls back to the configured default, then to "full".
+// ponytail: keep the surface to these three; "off"/"review" aren't served here.
+export function resolveMode(requested) {
+  const asked = normalizeMode(requested);
+  if (asked && asked !== "off") return asked;
+
+  const fallback = normalizeMode(getDefaultMode());
+  return fallback && fallback !== "off" ? fallback : "full";
+}
+
+export function buildInstructions(requested) {
+  return getPonytailInstructions(resolveMode(requested));
+}

package/template/skills/ponytail/scripts/mcp/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "ponytail-mcp",
+  "version": "4.8.3",
+  "description": "MCP server that serves Ponytail's lazy-senior-dev instructions as a prompt and a tool.",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "scripts": { "test": "node --test ./test/*.test.js" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  }
+}

package/template/skills/ponytail/scripts/mcp/test/instructions.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MODES, resolveMode, buildInstructions } from "../instructions.js";
+
+test("resolveMode keeps valid intensities", () => {
+  for (const mode of MODES) assert.equal(resolveMode(mode), mode);
+});
+
+test("resolveMode falls back to a runtime intensity for off/unknown/empty", () => {
+  // PONYTAIL_DEFAULT_MODE could be anything in CI, so just assert the contract:
+  // never returns "off", "review", or junk — always one of the served modes.
+  for (const input of ["off", "review", "nonsense", "", undefined, null]) {
+    assert.ok(MODES.includes(resolveMode(input)), `resolveMode(${input}) must be a served mode`);
+  }
+});
+
+test("buildInstructions returns the ruleset tagged with the resolved mode", () => {
+  const text = buildInstructions("ultra");
+  assert.match(text, /PONYTAIL MODE ACTIVE/);
+  assert.match(text, /ultra/);
+});

package/template/skills/ponytail-audit/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ponytail-audit
+description: >
+  Whole-repo audit for over-engineering. Like ponytail-review, but scans the
+  entire codebase instead of a diff: a ranked list of what to delete, simplify,
+  or replace with stdlib/native equivalents. Use when the user says "audit this
+  codebase", "audit for over-engineering", "what can I delete from this repo",
+  "find bloat", "ponytail-audit", or "/ponytail-audit". One-shot report, does
+  not apply fixes.
+---
+
+ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank
+findings biggest cut first.
+
+## Tags
+
+Same as ponytail-review:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Hunt
+
+Deps the stdlib or platform already ships, single-implementation interfaces,
+factories with one product, wrappers that only delegate, files exporting one
+thing, dead flags and config, hand-rolled stdlib.
+
+## Output
+
+One line per finding, ranked: `<tag> <what to cut>. <replacement>. [path]`.
+End with `net: -<N> lines, -<M> deps possible.` Nothing to cut: `Lean already. Ship.`
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass. Lists findings, applies nothing. One-shot.
+"stop ponytail-audit" or "normal mode" to revert.

package/template/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ponytail-debt
+description: >
+  Harvest every `ponytail:` comment in the codebase into a debt ledger, so the
+  deliberate shortcuts and deferrals ponytail leaves behind get tracked instead
+  of rotting into "later means never". Use when the user says "ponytail debt",
+  "/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail
+  ledger", or "what did we mark to do later". One-shot report, changes nothing.
+---
+
+Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
+its ceiling and upgrade path. This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
+output:
+
+`grep -rnE '(#|//) ?ponytail:' .`  (add other comment prefixes if your stack uses them)
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `ponytail: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any `ponytail:` comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No ponytail: debt. Clean ledger.`
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot. "stop ponytail-debt" or
+"normal mode" to revert.

package/template/skills/ponytail-gain/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ponytail-gain
+description: >
+  Show ponytail's measured impact as a compact scoreboard: less code, less
+  cost, more speed, from the benchmark medians. One-shot display, not a
+  persistent mode, and not a per-repo number. Trigger: /ponytail-gain,
+  "ponytail gain", "what does ponytail save", "show ponytail impact",
+  "ponytail scoreboard".
+---
+
+# Ponytail Gain
+
+Display this scoreboard when invoked. One-shot: do NOT change mode, write flag
+files, or persist anything.
+
+The figures are the published benchmark medians (5 everyday tasks: email
+validator, debounce, CSV sum, countdown timer, rate limiter; three models:
+Haiku, Sonnet, Opus). They are measured, not computed from the current repo.
+Source: `benchmarks/` and the README.
+
+## Scoreboard
+
+Render plain ASCII bars. The bar length shows the measured range; the label
+carries the exact figure:
+
+```
+  ponytail gain                     benchmark median · 5 tasks · 3 models
+
+  Lines of code   no-skill  ████████████████████  100%
+                  ponytail  ██▌·················    6–20%   ▼ 80–94%
+  Cost            no-skill  ████████████████████  100%
+                  ponytail  █████▌··············   23–53%  ▼ 47–77%
+  Speed           ponytail  ▸ 3–6× faster
+
+  This repo:  /ponytail-debt  (shortcuts you deferred)
+              /ponytail-audit (what's still cuttable)
+```
+
+## Honesty boundary
+
+These are benchmark medians, not this repo. NEVER print a per-repo savings
+number ("you saved X lines/tokens here"): the unbuilt version was never
+written, so there is no real baseline to subtract from in a live repo. The
+only real per-repo figures come from `/ponytail-debt` (a counted ledger), and
+this card points there instead of inventing one.
+
+## Boundaries
+
+One-shot display. Edits nothing, changes no mode.
+"stop ponytail" or "normal mode": revert.

package/template/skills/ponytail-help/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ponytail-help
+description: >
+  Quick-reference card for all ponytail modes, skills, and commands.
+  One-shot display, not a persistent mode. Trigger: /ponytail-help,
+  "ponytail help", "what ponytail commands", "how do I use ponytail".
+---
+
+# Ponytail Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/ponytail lite` | Build what's asked, name the lazier alternative in one line. |
+| **Full** | `/ponytail` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
+| **Ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **ponytail** | `/ponytail` | Lazy mode itself. Simplest solution that works. |
+| **ponytail-review** | `/ponytail-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
+| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
+| **ponytail-help** | `/ponytail-help` | This card. |
+
+Codex uses `@ponytail`, `@ponytail-review`, and `@ponytail-help`; Claude Code
+and OpenCode use the slash-command forms above (OpenCode ships `/ponytail` and
+`/ponytail-review`).
+
+## Deactivate
+
+Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
+`/ponytail off` also works.
+
+## Configure Default Mode
+
+Default mode = `full`, auto-active every session. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export PONYTAIL_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start, activate manually
+with `/ponytail` when wanted.
+
+Resolution: env var > config file > `full`.
+
+## Update
+
+Enable auto-update once: open `/plugin`, go to Marketplaces, pick ponytail, Enable auto-update. Claude Code then pulls new versions at startup (run `/reload-plugins` when it prompts). Manual refresh: `/plugin marketplace update ponytail` then `/reload-plugins`.
+
+If `/plugin` is not recognized, your Claude Code is out of date. Update it (`npm install -g @anthropic-ai/claude-code@latest`, or `brew upgrade claude-code`) and restart. Other hosts use their own update flow.
+
+## More
+
+Full docs + examples: https://github.com/DietrichGebert/ponytail

package/template/skills/ponytail-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ponytail-review
+description: >
+  Code review focused exclusively on over-engineering. Finds what to delete:
+  reinvented standard library, unneeded dependencies, speculative abstractions,
+  dead flexibility. One line per finding: location, what to cut, what replaces
+  it. Use when the user says "review for over-engineering", "what can we
+  delete", "is this over-engineered", "simplify review", or invokes
+  /ponytail-review. Complements correctness-focused review, this one only
+  hunts complexity.
+---
+
+Review diffs for unnecessary complexity. One line per finding: location, what
+to cut, what replaces it. The diff's best outcome is getting shorter.
+
+## Format
+
+`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
+multi-file diffs.
+
+Tags:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Examples
+
+❌ "This EmailValidator class might be more complex than necessary, have you
+considered whether all these validation rules are needed at this stage?"
+
+✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`
+
+✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
+
+✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
+
+✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
+
+✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`
+
+## Scoring
+
+End with the only metric that matters: `net: -<N> lines possible.`
+
+If there is nothing to cut, say `Lean already. Ship.` and stop.
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass, not this one. A single smoke test or `assert`-based
+self-check is the ponytail minimum, not bloat, never flag it for deletion.
+Does not apply the fixes, only lists them.
+"stop ponytail-review" or "normal mode": revert to verbose review style.

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 文档训练框架。