# Self Evolve

> Self-evolution knowledge lifecycle router — orchestrates run check review → stage → run complete (seal) → promote --resolve（内联裁决+晋升）→ 未来 run search 验证；session 源候选先 session complete 再 promote. Thin coordinator over maestro CLI; never writes spec/knowhow files directly. Arguments: [intent — e.g. 'review-run' | 'stage' | 'seal' | 'promote' | 'health' | 'full-cycle' | '沉淀这段经验']

- Skill: `catlog22/self-evolve` (Agent Skill)
- Install (CLI): `npx skillmds@latest add catlog22/self-evolve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/catlog22/self-evolve/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: catlog22 (https://skillmd.com/u/catlog22)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/catlog22/self-evolve

---


<teammate_contract>

- `background: false` is the default. Use foreground dispatch whenever the result determines the current answer or next action.
- Use `background: true` only for independent work. If this turn must consume a background result, call `observe` exactly once with `action: "wait"` with a bounded timeout before continuing.
- Otherwise end the turn and wait for the automatic `teammate-complete` notification.
- Never silently ignore an unfinished dispatch.
- Never continue independently while a dispatched task's result is still pending.

</teammate_contract>

<required_reading>
docs/self-evolution-plugin-design.md        # v2 设计：双层评审门（§5）、时序铁律（§4）、MVP 验收 V1-V11（§8）
.pi/skills/maestro-knowledge/SKILL.md       # 知识生命周期命令面（stage/review/promote/record/audit）
.pi/skills/maestro-session-seal/SKILL.md    # seal 语义与 session 评审台
</required_reading>

<purpose>
Self-evolve 是**薄 router**：把「run check 评审 → stage → run complete seal → promote --resolve 内联裁决+晋升 → 未来 run search 验证」的时序编排封装成可执行流程（session 源候选先 session complete 再 promote；时序铁律：promote 在 seal 之后），命令面全部复用 maestro CLI（与 maestro-knowledge 共用同一套 `maestro knowledge ...` 生命周期命令，避免双份维护）。本 skill 只做**时序编排与护栏**，不做知识内容生产，也不直接写 spec/knowhow 文件。
</purpose>

<dispatch>
按 `$ARGUMENTS` 中的 intent 分类，映射到具体 CLI 步骤。优先级：显式关键字 > intent 推断。

| Intent | 关键字 | 执行步骤（CLI） |
|--------|--------|------------------|
| `review-run` | `check` / `评审` / `审查` / `finish checklist` / `对账` | `maestro run check <run-id> [--json]` — 扫描 outputs、评估 run gates、刷新 reconciliation receipt；gates clean 时输出注入 finish-checklist 评审清单 |
| `review-signals` | `信号` / `signal` / `review-signals` / `候选评估` / `dry-run` | 读取全局 `~/.maestro/self-evolve/{suggestions,reviews}/` → 按评审 `stage` 判定构建沉淀候选（见「信号沉淀流水线」） |
| `stage` | `stage` / `暂存` / `沉淀` / `候选` / `candidate` / `记录命中` | `maestro knowledge stage <spec\|knowhow> "<title>" --content-file <path\|-> --run <run-id> [--category <cat>] [--evidence <refs>]`；session 源（无需 Run）：`--session <session-id> --evidence <refs>`（evidence 必填；无 Run 时写授权分层解析并自动幂等落 ksyn-* 合成 Session）；归因用 `maestro knowledge record <ids...> --signal <signal> --source search [--run <run-id> \| --session <session-id> \| --channel <name>] [--allow-unknown]`（不产生候选；ID 经 wiki 索引校验，未知默认拒收） |
| `seal` | `seal` / `complete` / `封存` / `封板` | `maestro run complete <run-id> --session {session_id} --verdict done --advance --expected-run-revision {run_rev} --expected-orchestration-revision {rev}`（sealed run）→ `maestro session complete --session {session_id} ... --expected-orchestration-revision {rev}`（seal session） |
| `promote` | `promote` / `晋升` / `发布` / `落库` | happy path 内联裁决+晋升 `maestro knowledge promote <session-id> --resolve <candidate-id> --as <choice> [--target <knowledge-id>] --reason "..."`（fence+resolve+promote 一步）；纯晋升 `--candidate <id>\|--all`；兼容回退 `review <session-id> --resolve` |
| `health` | `health` / `audit` / `健康` / `基线` / `库存` | `node scripts/self-evolve-health.mjs`（生成全局健康 sidecar：health.json + health-<project>.json）→ 读 `health.json`（audit/revalidation/reviewRequired/reviews/approval 段已含所需信息；如需实时明细可选 `maestro knowledge audit --json`）；按 revalidation queue 逐项治理（见「知识健康闭环」） |
| `full-cycle` | `full` / `闭环` / `自进化` / `整条流水线` / `完整流程` | 执行下方「核心时序编排（full-cycle）」全链 |
| `proposal` | `proposal` / `提案` / `skill 演化` / `改 skill` / `skill 变更` | Phase 5 独立 proposal 流程（见「Phase 5 skill 演化」）：`node scripts/self-evolve-phase5.mjs proposal <skill-path> --content <path> --reason "<why>"` → 静态检查/权限差异/签名 → `apply`（reason 非空=批准记录）→ `revert`（--reason 必填；sha256 冲突检测，不一致需 --force；写 skill-revert receipt） |
| `canary` | `canary` / `shadow` / `在线验证` / `影子` / `试用` | Phase 5 高影响知识在线验证（见「Phase 5 在线验证」）：`node scripts/self-evolve-phase5.mjs canary <id> [--window N]` → shadow 观察窗口 → PROMOTE/ROLLBACK 建议 |
| `trajectory` | `trajectory` / `轨迹` / `SOP 盲区` / `工具轨迹` / `phase 6` | Phase 6 工具轨迹深度分析（设计阶段，见「Phase 6 工具轨迹深度分析」）：`node scripts/self-evolve-phase6.mjs analyze <tool> [--window N]` → SOP 覆盖盲区报告 + 补丁候选草稿 + 内嵌/knowhow 差异（不自动写入，走 stage→promote） |
| `hybrid` | `hybrid` / `语义` / `enrichment` / `review pending` / `wrap` / `phase 7` | Phase 7 语义采集与会话收尾（已落地）：`/self-evolve config captureMode=hybrid` 启用受预算语义 enrichment；`/self-evolve review pending [N]` 评审当前 session 未评审信号；`/self-evolve wrap` 手动出会话摘要 |
| `auto` | `auto` / `自动` / `事实型` / `自动晋升` / `settle` | 事实型自动进化（T2）：seal 后 `promote --all` 自动晋升事实候选，review_required 留人工（见「事实型自动进化」） |

规则：

1. 无法分类或意图含糊 → 展示上表并请用户选择。
2. `review-run` 输出中的 finish-checklist 与 reconciliation receipt 是**提示层**（非阻断）：sealed run 拒绝 sidecar 写入，promote 却要求源已 seal —— 评审必须在 seal 之前、promote 在 seal 之后（时序铁律，见 §4）。**双源门禁**：run 源 = 源 run sealed + 新鲜 run receipt；session 源 = Session sealed（session complete）+ 新鲜 session receipt + stage 时非空 `--evidence`（session complete 自动 best-effort 刷 session receipt，缺失/stale 用 `review <session-id> --refresh` 修复）。
3. `stage` / `review` / `promote` / `record` 一律经 `maestro knowledge ...` CLI，**不得翻译成直接写 spec/knowhow 文件**。
4. 保留 stable knowledge ID、Run ID、Session ID、candidate ID、disposition、target、signal、reason 原样传递，不做改写。
</dispatch>

<execution>

### 核心时序编排（full-cycle）

两条路径（run 源 / session 源），happy path 裁决+晋升统一走 `promote --resolve <id> --as <choice> [--target <id>] --reason "<reason>"`（TOCTOU fence + resolve + promote 一步；`review --resolve` 保留为兼容回退）；纯晋升走 `promote --candidate|--all`（时序铁律：**promote 在 seal 之后**）：

```
── run 源 ──────────────────────────────────────────────────
run check（读 finish-checklist 评审清单 + 对账 receipt）
   │  ├─ 复用既有知识 → record --signal validated|contradicted（+evidence 锚点）
   │  ├─ 可复用发现   → stage knowhow/spec --content-file --evidence --signal
   │  └─ 硬结论       → 写 report.md frontmatter decisions/constraints（seal 时自动 stage）
   ▼
run complete（seal 事务：自动 stage frontmatter 草拟 + 自动抑制 exact_duplicate + receipt 固化，run 转不可变）
   ▼
promote --resolve（内联裁决+晋升：--as <choice> --target --reason）
   ▼
promote（fail-closed 硬门，见下方阻断语义）→ 用户确认后执行（run 源候选 run seal 后即可）
   ▼
未来 run：maestro search 命中验证（索引器 mtime 增量感知）

── session 源 ─────────────────────────────────────────────
stage（无 Run 场景；evidence 必填）→ 用户确认
   ▼
promote --resolve（内联裁决+晋升：--as <choice> --target --reason）
   ▼
session complete（sealed 后 session 源候选方可晋升；complete 自动 best-effort 刷 session receipt）
   ▼
promote（fail-closed 硬门；双源门禁：Session sealed + 新鲜 session receipt + stage 时非空 --evidence）
   ▼
未来 run：maestro search 命中验证（索引器 mtime 增量感知）
```

#### Step 1 — run check（评审清单）
```bash
maestro run check <run-id> --json
```
- 读取 finish-checklist（gates clean 时由 runtime 注入：runtime 内置规范 + workflow 文档 frontmatter `finish:` 行扩展）与 reconciliation receipt。
- 逐条核对清单：frontmatter summary 是否为空；候选是否需要 stage；是否有 semantic duplicate/conflict/supersession 待 resolve；是否需要 record 归因。
- **单点依赖预期**：seal 自动 stage 的候选（frontmatter 草拟）只能在 seal **后**被 review——check 阶段找不到自动草拟候选属预期行为，非闭环失效（§4）。

#### Step 2 — stage（按清单沉淀）
可复用发现 → 候选内容**写临时文件**后经 `--content-file <path|->` 传参（stage 参数规则——临时文件、`--evidence`、`--signal-ids` 逗号分隔——见 maestro-knowledge SKILL / SYSTEM.md 知识操作节；绝不 inline 传参，空格/引号/unicode/换行/前导破折号会错位后续参数）：
```bash
# run 源（run 内沉淀）
maestro knowledge stage knowhow "<title>" --content-file <path|-> --run <run-id> --evidence "<file:line>,<artifact-ref>" [--category <cat>] [--signal validated --signal-ids <ids>]
# session 源（无 Run 场景；evidence 必填）——无活跃 run 时写授权分层解析（显式参数 > --channel/MAESTRO_CHANNEL > Pi lease > 单活 hook 通道 > 收窄扫描），什么都没有则自动幂等创建 ksyn-* 合成 Session
maestro knowledge stage knowhow "<title>" --content-file <path|-> --session <session-id> --evidence "<file:line>,<artifact-ref>" [--category <cat>]
```
- `--evidence` 建议必填（证据源可靠性：reconciliation receipt > report.md frontmatter > outputs/工件 file:line 锚点 > session 轨迹）。
- **report.md frontmatter 契约（实测 zod schema：reportVerdictSchema 的 ready 系词表，行号随版本漂移）**：`verdict` 规范词表 `ready|ready_with_concerns|blocked|failed`（**建议写规范词**）；chain 词 `done|done-with-concerns|needs-retry` 也被接受并自动映射（done→ready、done-with-concerns→ready_with_concerns、needs-retry→failed，reportVerdictSchema preprocess）——写 `verdict: done` **不再**校验失败，但仍应写规范词避免歧义。`decisions`/`constraints` 元素为 `{text, status}`，status 分别 ∈ proposed/accepted/rejected 与 locked/open/deferred；**`id` 可省，runtime 自动盖章 `C-001`/`D-001`…，不要手写**（手写不报错但无必要）。CLI `maestro run complete --verdict` 接受 `done|done_with_concerns|needs_retry|blocked` 并反向映射 ready 系别名（done→done、done_with_concerns→ready_with_concerns、needs_retry→failed）——两表双向互通，不再是 seal 失败源。
- **防噪音候选（铁律）**：seal 会把每条 accepted decision / locked constraint 自动草拟成语料候选，因此 frontmatter **只写可复用的规定性决策/约束**（未来工作必须遵守的规则）。严禁写运行状态叙述：只读声明（“Read-only audit…”“Debug investigation remained read-only”）、worktree/审计过程观察（“working tree changed concurrently”）、文件缺失记录、issue 路由备忘——这些是存量分诊实测确认的主要噪音源。
- 归因（不产生候选，仅记账）：`maestro knowledge record <ids...> --signal consumed|cited|validated|contradicted --source search|load|manual [--run <run-id> | --session <session-id> | --channel <name>] [--allow-unknown]`。搜索/注入是 exposure，load 才算 consumed；load 归因三级路由（唯一活跃 run → 无歧义 Session 身份 → 全局账本+warning）不阻塞加载。ID 写入前经 wiki 索引校验，未知 ID 默认拒收，`--allow-unknown` 降级记账留痕。
- `--signal-ids` 逗号分隔规则见 maestro-knowledge SKILL / SYSTEM.md 知识操作节（`--signal-ids spec:project:a,knowhow:b`；空格分隔会泄漏进位置参数）。
- 负知识（失败测试/被拒评审/被推翻实践）同样 stage 为反例候选（scope + 失败原因 + 替代方案）。

#### Step 3 — run complete（seal 事务）
```bash
# 1) 完成当前 Run 并推进链（sealed run；verdict 驱动 --advance）
maestro run complete <run-id> --session {session_id} --verdict done|done_with_concerns|needs_retry|blocked --summary "<text>" [--decision "<text>"] [--reason "<text>"] --advance --expected-run-revision {run_rev} --expected-orchestration-revision {rev}
# 2) 全部 step 完成后封存 Session（session complete = v3 的 seal 面）
maestro session complete --session {session_id} --participant {p} --actor {a} --request-id {r} --reason "<reason>" --expected-orchestration-revision {rev}
# v2 的 session done/session seal 已移除；run complete 即唯一完成面
# CLI --verdict 同时接受 report 层 ready 词表别名并内部映射：ready→done / ready_with_concerns→done_with_concerns / failed→needs_retry（blocked 两表一致）
```
- verdict 诚实选择：`done`（干净）或 `done-with-concerns`（有 caveat，全部列入 concerns）。
- seal 后 run 不可变（拒绝 sidecar 写入）；frontmatter decisions/constraints 自动物化为 spec 候选。

#### Step 4 — 呈现 + 裁决（happy path: promote --resolve；review --resolve 兼容回退）
```bash
maestro knowledge review <session-id> [--refresh] [--json]   # 呈现数据源（只读；--refresh 刷新 receipt = TOCTOU fence）
# happy path：promote 内联裁决+晋升一步（fence + resolve + promote）
maestro knowledge promote <session-id> --resolve <candidate-id> --as duplicate|related|conflict|supersede|unique [--target <knowledge-id>] --reason "<非空理由>"
# 兼容回退（review 仍持有 --resolve，deprecated）：
maestro knowledge review <session-id> --resolve <candidate-id> --as duplicate|related|conflict|supersede|unique [--target <knowledge-id>] --reason "<非空理由>"
```
**呈现协议（铁律，完整规则见 maestro-knowledge SKILL / SYSTEM.md 知识操作节「评审呈现协议」）**：裁决环节 agent 自己跑 `review --json`，逐条向用户呈现：标题、类型与来源（run/session）、内容摘要、evidence 锚点、证据支撑的既有匹配（id+标题）、**推荐处置（五选一 + target）与一行理由**；收集用户逐条决策（或批量采纳推荐）后再执行 `promote --resolve` 内联裁决（或兼容回退 `review --resolve`）。用户只决策，agent 负责读取/呈现/执行——**禁止把 review 命令甩给用户当全部任务**。批量采纳推荐时仅限验证过明确独立的候选（`--as unique`）。

- 裁决 `--resolve` 前建议先 `review <session-id> --refresh`（TOCTOU fence：刷新 run/session receipt，防「校验后、写入前」语料漂移），receipt 缺失/stale 会中止（E005）。
- `--as unique` 时**不得传 `--target`**；duplicate/related/conflict/supersede 必须传 `--target`，且 target 必须来自该候选 evidence-backed match。
- 5 种处置：duplicate / related / conflict / supersede / unique。supersede 要求候选与 target 同 knowledge store。
- exact_duplicate 自动 suppressed（无需 resolve）；semantic_duplicate/conflict/supersession 必须 resolve，否则 **promote fail-closed**。

#### Step 5 — promote（阻断层硬门，用户确认后执行）
```bash
# 未裁决候选 → 内联裁决+晋升一步（happy path）：
maestro knowledge promote <session-id> --resolve <candidate-id> --as <choice> [--target <knowledge-id>] --reason "<非空理由>"
# 已裁决候选 → 纯晋升（--candidate/--all）：
maestro knowledge promote <session-id> --candidate <candidate-id>[,<id>...]  # 显式逐个（裁决过的候选）
maestro knowledge promote <session-id> --all        # 批量晋升全部合格项（observed-only 仅警告）
# 晋升成功后记录 approval receipt（审计轨迹）：
node scripts/self-evolve-approval.mjs record --action promote --session <session-id> \
  --reason "<非空理由>" --candidates <id1,id2> [--actor <name>]
```
- **promote 前必须 `ask-user-question` 确认**（晋升全部合格项 / 逐个选择 / 暂不晋升）。
- **receipt fence**：promote 强依赖源 receipt 新鲜（run 源 = sealed run receipt；session 源 = sealed Session + 新鲜 session receipt）；缺失/stale 先 `review <session-id> --refresh` 修复（失败则中止，E005）——防「校验后、写入前」语料漂移。
- **approval receipt**：每次 promote/supersede/deprecate/conflict-mark 后经 `scripts/self-evolve-approval.mjs record` 落全局 `~/.maestro/self-evolve/approvals/<date>.jsonl`（actor+reason+timestamp+候选），审计轨迹独立于 maestro ledger。
- **阻断语义（实测 CLI throw）**：
  | 条件 | 行为 |
  |---|---|
  | run 源：源 run 未 seal | throw `Knowledge candidates require sealed source Runs before promotion` |
  | session 源：Session 未 seal | throw `Session-source candidates require Session <sid> to be sealed before promotion` |
  | session 源：session receipt 缺失/stale | throw（缺失：`no session knowledge reconciliation receipt`；seal 时自动 best-effort 刷新，失败留缺口 → `review <session-id> --refresh` 修复后放行） |
  | `review_required` 未裁决 | `--all` 跳过（skipped_review_required）；显式 `--candidate` throw |
  | 与既有 spec 同 title 不同 content | throw —— 需先 `--as supersede` resolve 或 `spec supersede <old-sid> --by <new>` / `spec conflict mark <file> <line> --note "<reason>"` |
  | `--candidate` 与 `--all` 同时给 | throw |
  | 空选择 / 未知 candidate id | throw |
- supersede 谱系：`maestro spec supersede <old-sid> --by <new-sid>` + `maestro spec history <sid>` 可查链。

#### Step 5.5 — 回退操作（错误 promote 后的处置）

- **候选级处置（错误 promote 的候选）**：`maestro knowledge review <session-id> --resolve <candidate-id> --as rejected|supersede --reason "<原因>"` 裁决回退，随后补 `node scripts/self-evolve-approval.mjs record --action supersede --session <session-id> --reason "<原因>" --candidates <id>`（审计留痕）。
- **knowhow snapshot restore（仅限生命周期迁移场景）**：知识条目没有 CLI 快照回滚——快照恢复只存在于 Phase 5 skill proposal 的 `revert`（`proposals/<id>/backup.md`）；knowhow 错误晋升一律走上面的 promote --resolve（或兼容回退 review --resolve）/supersede 处置。
- **spec 已晋升内容回滚 = 手工（已知限制）**：已晋升/已发布的 spec 内容无 CLI 回滚，建议 `maestro spec supersede <sid> --by <修正版sid>` 到修正版，而不是直接改写已晋升条目。

#### Step 6 — session complete + 未来验证
```bash
maestro session complete --session {session_id} --participant {p} --actor {a} --request-id {r} --reason "<reason>" --expected-orchestration-revision {rev}
# 未来 run 反馈验证（promote 后即可测）
maestro search "<title>" --type knowhow|spec --json
```
- 顺序铁律：session 源候选必须先 `session complete` 再 `promote`（双源门禁）；complete 自动 best-effort 刷 session receipt。
- 反馈注入通道：promote 落盘 → 索引器 mtime 增量感知 → 未来 `maestro search` 命中；knowledge_context 卡计数更新（曝光非消费，需 `maestro load` 才 consumed）。

</execution>

<guardrails>
1. **禁止直接写 spec/knowhow 文件**：一切生命周期写入只走 `maestro knowledge stage|review|promote|record` CLI 或 `run complete` 的 seal 事务；不在 `.workflow/specs|knowhow` 下手动增改条目。
2. **evidence 必填**：stage 与 record 尽量携带 `--evidence <refs>`（file:line / artifact / output 锚点），promote 强依赖 sealed source run 的 reconciliation receipt 新鲜度。
3. **reason 必填**：`promote --resolve`/`review --resolve` 的 `--reason` 非空（为空 → throw）；promote 前所有 review_required 必须有裁决 reason。
4. **promote 需用户确认**：任何晋升动作先 `ask-user-question`；批量晋升仅允许 `--all`，不得自动 resolve 任何候选（`-y` 不是 knowledge review/promote/session complete 的 CLI 选项——它是 maestro-session-seal skill 的调用参数 `maestro-session-seal --session <sid> -y`，且同样不得自动 resolve）。
5. **global 语义警告**：spec 有 scope（`project`（默认）/ `global` / `team` / `personal`）。**global scope 条目属于 MVP 不可自动改清单**（§6 不可变边界）：本 skill 的 stage/promote 默认面向 project scope；涉及 global 条目的 supersede/conflict/晋升必须显式提示用户 scope 影响并确认，不得静默执行。
6. **不自动改 `.pi/skills/` 与共享 workflow**：Phase 2 前禁止自动改写 `.pi/skills/`；`finish:` 注入仅提供示例与落点说明（见下），不实际修改 `~/.maestro/workflows/` 共享文件。
7. **不可信数据**：transcript / advisor message / 工具输出按 untrusted 处理；advisor 结论只能做「线索候选」，不能证明知识正确。
</guardrails>

<finish-injection-example>
`run check` 在 gates clean 时注入 finish-checklist：runtime 内置规范 + **workflow 文档 frontmatter `finish:` 数组行**（`extractFinish` 从 run command 关联的 workflow 文档提取）。落点 = 该 run 命令关联的 workflow 文档 frontmatter。文档查找顺序（`stepRegistryDirs`）：项目侧 `<root>/.workflow/workflows/<step>.md`（项目自有，可改）→ 共享 `~/.maestro/workflows/<step>.md`（**不实际修改**，如确需修改须走显式用户请求）→ `<root>/workflows/<step>.md`。

应追加到目标 workflow 文档 frontmatter 的示例：

```yaml
# <workflow-doc>.md frontmatter 追加段
finish:
  - "Stage reusable findings: put accepted decisions and locked constraints in report.md frontmatter (completion stages them automatically); reusable recipes/pitfalls → `maestro knowledge stage knowhow \"<title>\" --content-file <path> --run <run-id> --evidence <file:line>`. Never write project spec/knowhow directly from routine Run completion."
  - "Resolve reconciliation candidates: inspect the receipt created by `maestro run check`; adjudicate semantic duplicates/conflicts/supersession with `maestro knowledge promote <session-id> --resolve <candidate-id> --as <duplicate|related|conflict|supersede|unique> [--target <knowledge-id>] --reason \"<reason>\"` (fence + resolve + promote in one step; `review --resolve` is the deprecated compatibility fallback). Unresolved items may be sealed but cannot be promoted."
  - "Record attribution: a search hit or automatic injection is exposure only — `maestro knowledge record <ids...> --signal consumed|cited|validated|contradicted --source search --run <run-id>` before citing."
  - "Contradicted canonical knowledge: record the contradiction before sealing; after review/promotion replace stale rules with `maestro spec supersede <old-sid> --by <new-sid>`; coexisting valid rules → `maestro spec conflict mark <file> <line> --note \"<reason>\"`."
  - "Pick the verdict honestly: `done` (clean) or `done-with-concerns` (works but carries caveats — list every caveat in concerns)."
```

注意：示例仅作落点说明，**不实际写入任何文件**；共享 `~/.maestro/workflows/` 文件保持只读。
</finish-injection-example>

### 信号沉淀流水线（self-evolve 扩展联动）

把 dry-run 信号与评审判定转成真实知识候选（仍人工确认）。

**启用与命令面（默认禁用）**：启用三选一——`/self-evolve on`（写 `.pi/self-evolve.json`）/ `PI_SELF_EVOLVE=1`（env，强制覆盖）/ `.pi/self-evolve.json` `{ "enabled": true }`。命令面：`/self-evolve signals [N] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--project <p>]` 查看候选信号 → `/self-evolve review [N]` 评审（默认 5）→ `/self-evolve reviews [N]` 查历史评审；`signals delete <se-id-prefix...>` / `clear` / `export`（导出到 `~/.maestro/self-evolve/exports/signals-<ts>.jsonl`）管理记录。输出位置 `~/.maestro/self-evolve/{suggestions,reviews,evidence,archive,exports}/`（env `SELF_EVOLVE_OUTPUT_DIR` 覆盖根）；旧日文件修剪 = **归档**到 `archive/`，不删除。

**质量门槛（铁律，实测教训：未提炼的原始信号 86% 无分类价值，候选标题出现 "TOOL read: …" "grep: No matches" 类轨迹碎片即管道失控；完整规则见 maestro-knowledge SKILL / SYSTEM.md 知识操作节「写入质量门槛」）**：信号必须先语义提炼成教训形态（“做 X 时小心 Y，因为 Z”：范围+根因+预防/替代方案）才可 stage；**工具调用轨迹、日志/报错片段本身永远不是候选**；一批信号提炼不出可复用教训时，正确产出是 **0 候选**（合法结果，不为管道产量硬造候选）。

```
全局输出（跨项目，不污染 git）：
  ~/.maestro/self-evolve/suggestions/<date>.jsonl   # 候选信号（agent_end/compact，dryRun:true）
  ~/.maestro/self-evolve/reviews/<date>.jsonl       # /self-evolve review 的评审记录（dryRun:true）
  ~/.maestro/self-evolve/evidence/<se-id>.md        # 信号证据文件（suggestion 直接引用，写信号时生成）
  每条信号含 id/title/summary/evidence + 可执行 suggestion 模板，视配置含 project / skill / model
```

#### Step A — 读取最近信号与评审
```bash
LATEST_REVIEW=$(ls -t ~/.maestro/self-evolve/reviews/*.jsonl 2>/dev/null | head -1)
[ -n "$LATEST_REVIEW" ] && tail -1 "$LATEST_REVIEW"   # 最新评审记录（含 verdicts）
ls -t ~/.maestro/self-evolve/suggestions/*.jsonl | head -1  # 最近信号文件
```

#### Step B — 提取 `stage` 判定的候选
评审记录已含**评审门统计**：score 阈值（默认 0.6）已把低分 `stage` 自动降级为 `uncertain`、幻觉 verdict id 已丢弃（`droppedInvalid`）、无 suggestion 的非可行动信号已跳过（`nonActionableSkipped`）——`stage` 判定即合格，可直接进入 Step C。用 python 解析最新评审，过滤 `action == "stage"`，按 `id` 匹配信号：
```bash
python - <<'EOF'
import json, glob, os
review = json.loads(open(sorted(glob.glob(os.path.expanduser('~/.maestro/self-evolve/reviews/*.jsonl')))[-1], encoding='utf-8').read().strip().split('\n')[-1])
sigs = {}
for f in sorted(glob.glob(os.path.expanduser('~/.maestro/self-evolve/suggestions/*.jsonl')))[-1:]:
    for line in open(f, encoding='utf-8'):
        s = json.loads(line); sigs[s['id']] = s
for v in review['verdicts']:
    if v['action'] == 'stage' and v['id'] in sigs:
        s = sigs[v['id']]
        print(f"{s['id']} | {v['candidateType']} | {v['score']} | {s['title']}")
        print(f"  evidence: {', '.join(e['ref'] for e in s.get('evidence', []))}")
EOF
```

#### Step C — 构建并确认 stage 命令
evidence 文件已由扩展在写信号时生成于 `~/.maestro/self-evolve/evidence/<se-id>.md`，信号自带的 suggestion 模板**可直接执行**（session 源形式）；有活跃 run 时可用 `maestro run brief` 解析 `run_id`，把模板换成 `--run <run-id>` 形式。归属优先级：有活跃 run 时用 `--run <run-id>`；**无活跃 run 时直接用 session 源 stage——写授权分层解析（`--channel`/MAESTRO_CHANNEL → Pi host lease → 单活 hook 通道 → 收窄扫描），什么都没有则自动幂等创建 ksyn-* 合成 Session，无需用户提供或创建 run**；并发多会话工作区用 `--channel <name>` 显式隔离：
```bash
# session 源（无活跃 run；evidence 必填）——直接复用信号 suggestion 模板：
maestro knowledge stage <knowhow|spec> "<title>" --content-file <evidence-file> --session <session-id> --evidence "<file:line>,<file:line>"
# 有活跃 run 时（`maestro run brief` 解析 run-id）：
maestro knowledge stage <knowhow|spec> "<title>" --content-file <evidence-file> --run <run-id> --evidence "<file:line>,<file:line>"
```
执行前 `ask-user-question` 逐条确认（全部 stage / 逐个选择 / 暂不处理）；评审为 `skip`/`uncertain` 的信号不 stage，`uncertain` 可展示理由供用户决策。

#### Step D — 收尾
stage 后走常规 review/promote 流程（见 full-cycle Step 4-5）。全局信号/评审文件**保留**（跨项目聚合，Phase 3 健康闭环消费），勿删。

### 事实型自动进化（T2）

按知识来源可验证性分层（设计 v2 §5）：**事实型知识可全自动，推断型留人工**。

| 层 | 覆盖 | 机制 |
|---|---|---|
| T0 自动抑制 | exact_duplicate | reconciliation 自动 suppressed（无需动作） |
| T1 自动草拟 | frontmatter decisions/constraints（run 声明的**事实**） | seal 事务自动 stage（无需动作） |
| T2 事实型自动晋升 | unique/eligible 候选 | `promote --all`（sealed 源 + receipt 新鲜时晋升全部 eligible；observed-only 仅警告） |
| T3 推断型人工 | review_required（semantic_duplicate/conflict/supersede） | `promote` fail-closed 直到人工 `resolve` |

**T2 执行**（seal 后默认步骤，`--all` 前一次性确认）：
```bash
maestro knowledge promote <session-id> --all --json
# → 自动晋升全部事实候选；review_required 被跳过（skipped_review_required）
maestro knowledge review <session-id> --json   # 收尾：剩余 review_required 人工 resolve
```
- `--all` 晋升的是**机器可验证的事实候选**（决策/约束/唯一候选），非 LLM 推断——幻觉防线在 T3（推断型必须 resolve）。
- observed-only 警告：单 run 事实候选晋升时提示但**不阻塞**（corroboration 是置信信号非门槛）。
- 全局 scope / 已晋升 active 条目 / conflict 标记条目**不在**自动晋升范围（护栏 5）。

### 知识健康闭环（Phase 3）

健康 sidecar 生成器（`scripts/self-evolve-health.mjs`，可重建）把确定性健康数据聚合到全局（双文件输出）：

```
~/.maestro/self-evolve/health.json            # 跨项目健康快照（git 干净）
~/.maestro/self-evolve/health-<project>.json  # 同内容项目双写（per-project twin）
  specHealth: total/active/deprecated/contested/stale/freshness/chains
  audit: findings 计数与优先级分布 / prune_plan / safety
  revalidation: 治理队列（contest / review-required-stale / candidate-expired /
                approval-missing-candidates / stale/contested/ghost-reference/坏链 → 建议动作+命令）
  reviewRequired: 按 session 分组统计 review_required 候选（滞留 >7 天 → SE-RR-<session> 队列项）
  reviews: stage/skip/uncertain 计数 + score 分布 + unknown 占比
  approvalReconcile: promote receipt 统计 + 空 candidates 告警（SE-NO-CANDIDATES-<session>）
  signals.entries: 全量信号条目（不再 top-N 截断）
```

**健康 intent 用法**：`node scripts/self-evolve-health.mjs` → 直接读 `health.json`（audit/revalidation/reviewRequired/reviews/approval 段已含所需信息）；如需实时明细可选 `maestro knowledge audit --json`。

**治理循环**（逐项处理 revalidation，全部用既有 CLI）：

| 队列项 | 建议动作 | 命令 |
|---|---|---|
| stale active spec | 重审 freshness | `maestro spec health --json` 定位 → review 内容 |
| contested spec | 冲突处置 | `maestro spec conflict mark <file> <line> --note "<reason>"` |
| ghost-code-reference | 失效知识退役 | `maestro knowledge review <session-id> --resolve <candidate-id> --as supersede --target <id> --reason "ghost reference"` → `promote --candidate <id>` |
| missing-required-metadata | 修 frontmatter | 编辑目标文件 title/type |
| invalid-knowledge-ledger | 查 run 账本 | 检查对应 run 的 knowledge-delta |
| missing-stable-id | 补 sid | `maestro spec backfill-sid` |
| 坏链（dangling/cyclic） | 修复谱系 | `maestro spec health` 定位 → 修复 supersede 链 |
| review-required 滞留 >7 天（SE-RR-） | 裁决滞留候选 | `maestro knowledge review <session-id> --resolve <candidate-id> --as rejected\|supersede --reason "review required stale"` |
| 候选 TTL >30 天无佐证（SE-EXPIRED-） | 过期候选裁决（advisory） | `maestro knowledge review <session-id> --resolve <candidate-id> --as rejected\|supersede --reason "candidate expired"`（或保持 pending 审计） |
| promote receipt 空 candidates（SE-NO-CANDIDATES-） | 补回执 | `node scripts/self-evolve-approval.mjs record --action promote --session <sid> --candidates <id> --reason "<why>"` |

**治理闭环标记**：`node scripts/self-evolve-health.mjs mark <item-id> [--action <a>]` / `unmark <item-id>` 读写 `~/.maestro/self-evolve/health-handled.json`（0o600），已处理的队列项在下次生成时被过滤。

**闭环语义**：健康快照是可重建事实（非模型推断）→ 队列生成自动；处置（supersede/deprecate/conflict-mark）按护栏仍需用户确认。这完成「知识使用→健康衰减→退役」的闭环——与 T0-T2 事实型自动进化同一哲学：**事实自动采集，治理人工确认**。

<error_codes>
| Code | Severity | Condition | Recovery |
|------|----------|-----------|----------|
| E001 | error | promote：源 run 未 seal | 先 `maestro run complete <run-id> --session {session_id} --verdict done --advance ...` 再重试 |
| E002 | error | promote：review_required 未裁决 | `knowledge promote <sid> --resolve <id> --as <choice> --reason "..."` 内联裁决（或回退 `review --resolve`）后重试 |
| E003 | error | promote：spec title 冲突（同 title 异 content） | `--as supersede` resolve 或 `spec supersede` / `spec conflict mark` 后重试 |
| E004 | error | promote --resolve / review --resolve：reason 为空 / target 缺失 / target 非 evidence-backed | 补全参数重试 |
| E005 | error | 候选源 run 无 reconciliation receipt 或 receipt stale | `knowledge review <session-id> --refresh` 后重试 |
| E006 | warning | check 阶段无自动草拟候选 | 预期行为（seal 后物化），非闭环失效 |
| E007 | warning | `--all` 晋升 observed-only 候选并警告（实测 CLI 行为，非跳过） | 如需显式逐个，用 `--candidate <id>`（先 resolve） |
| E008 | error | `maestro run check` 失败 | 确认 run-id 存在、run gates 可读后重试 |
| E009 | error | approval record 落盘失败 | 检查 `~/.maestro/self-evolve/approvals` 可写性；修复后重跑 record（receipt 可后补） |
| E010 | error | canary 传入未知 knowledge id | 先 `maestro knowledge review <session-id> --json` / `maestro knowledge audit --json` 确认 id 后重试 |
</error_codes>

### Phase 5 在线验证与 skill 演化（受控自动化）

- **canary/shadow 对照（高影响知识）**：`node scripts/self-evolve-phase5.mjs canary <knowledge-id> [--window N]`。
  将候选置为 shadow 观察态；观察前校验 health 快照新鲜度（>1 天过期或非本项目 → 警告且**不递增 observedRuns**）；
  首次 observe 只记 `signalsBaseline`（增量窗口），重复 observe 同一快照不递增；窗口内用**增量**信号判定：
  validated+cited ≥ 1 → PROMOTE 建议；contradicted>0 或窗口到期无佐证 → ROLLBACK 建议。
  脚本只出**建议命令（需按会话实际 session-id/candidate-id/target 补全后执行）**：
  - PROMOTE → `maestro knowledge promote <session-id> --resolve <id> --as <choice> --reason "<reason>"`（内联裁决+晋升；纯晋升用 --candidate；session-id 经 `maestro knowledge review <session-id> --json` 或 run brief 解析）
  - ROLLBACK → ①候选未晋升：`maestro knowledge review <session-id> --resolve <candidate-id> --as rejected --reason "canary rollback: 无佐证"`；②已晋升为知识条目：`maestro spec supersede <sid> --by <修正版sid>`
  promotion 仍需经 Step 5 显式 `promote`（fail-closed 门不变）。
- **ROLLBACK 执行链**：canary ROLLBACK 建议 → 呈现协议（展示证据与 target 候选，见 Step 4）→ 用户确认（护栏：涉及 global 条目必须显式确认）→ `promote --resolve --as rejected|supersede`（补全 session-id/candidate-id/target；回退 `review --resolve`）→ `node scripts/self-evolve-approval.mjs record --action supersede --session <session-id> --reason "canary rollback" --candidates <id>`。窗口到期无佐证走同一链条（`--as rejected`）。
- **skill 修改独立 proposal（不复用 knowhow promotion）**：
  `proposal` 生成快照（sha256）+ diff + 权限差异审查（allowed-tools 增删，敏感工具变更标注）+ 静态检查
  （frontmatter 完整、execution/success_criteria 标签配对）→ 全局 `proposals/<id>/`（id 带时间后缀）；
  `apply` 需非空 `--reason`（= 显式批准记录，同时落 approvals 审计回执），应用后重校验失败**自动回滚**；
  `revert` 恢复快照（--reason 必填，写 skill-revert receipt；sha256 冲突检测，与快照不一致需 `--force`）。
  **遵守 `.pi/SYSTEM.md` 知识操作节治理规则（Review, resolution, promotion, supersession, conflict marking, and pruning require an explicit user request or confirmed governance step）：skill 变更必须有显式请求/确认的 governance step，绝不静默 apply。**

### Phase 6 工具轨迹深度分析与 SOP 治理闭环（设计阶段，未实施）

- **背景**：Phase 2C 已让 `agent_end` 信号携带结构化 `toolCalls` 证据（`buildToolCallEvidence`，覆盖 browser/computer_use 的 action/topic/outcome），`signalEvidenceContent` 在证据文件头部输出 SOP frontmatter hint（`tools`/`sop_topic`）。SopLoader/SopRegistry 已能从 `.workflow/knowhow/` 自动发现带 `tools`+`sop_topic` 字段的文档并合并内嵌基线。Phase 6 在此之上加一层「跨会话聚合某工具轨迹，发现 SOP 覆盖盲区与内嵌/外部漂移」的治理面。
- **入口**（二选一）：`/self-evolve trajectory <tool> [--window N] [--since YYYY-MM-DD]`（TUI/命令），或 `node scripts/self-evolve-phase6.mjs analyze <tool> [--json]`（CI/脚本）。复用 `~/.maestro/self-evolve/` 下的 suggestions/reviews/deposits 聚合通道。
- **输入**：从 suggestions（含 `toolCalls` 字段）+ reviews 聚合指定工具的信号，按 outcome 分桶统计失败率、按 action/topic 统计 SOP 命中与未命中、按 `sop_topic` 检查内嵌基线与 knowhow 外部是否存在对应文档。
- **输出**（三种产物，全部只读/只建议，不自动写入）：
  1. **SOP 覆盖盲区报告**：高频失败 outcome 但无对应 `sop_topic` 文档的盲区（如 `computer_use` 的 `near_zero` 在 coordinates/core 都未覆盖），附出现次数与示例信号 id。
  2. **SOP 补丁候选**：每个盲区生成一份带 `tools`/`sop_topic` frontmatter 的 evidence 文件草稿 + 对应 `maestro knowledge stage knowhow --content-file` 命令模板（复用 Phase 2C `renderSopFrontmatterHint` 逻辑的批量版）。
  3. **内嵌与 knowhow 差异**：对比 `sop/embedded/*.ts` 基线与 `.workflow/knowhow/` 外部文档的 topic 集合，标出「外部已覆盖但内嵌未同步」「内嵌有但外部无」「order 冲突」三类。
- **治理**：产物仍走 `stage → review → promote`，不自动 stage/不自动 promote（与 Phase 2B 纪律一致）；`analyze` 只生成报告与草稿，用户显式执行 stage。与 Phase 5 canary 互补：Phase 5 验证已晋升知识，Phase 6 发现待晋升的 SOP 盲区。
- **与 SopLoader 契约**：Phase 6 不直接读 `SopRegistry`，而是读 `.workflow/knowhow/` 目录与 `sop/embedded/*.ts` 导出的 baseline map（同 `sop-registry-singleton.ts` 的 `EMBEDDED_BASELINES`），保证盲区判定与运行时加载器使用同一份基线与外部来源。
- **实施时机**：Phase 2C 信号累积≥50 条含 `toolCalls` 的信号后，作为独立 Run 启动；本节为设计阶段，不落代码。

### Phase 7 语义采集、智能证据与会话收尾（已落地）

解决 Phase 2A 的四个残余局限：关键词决定是否 evol、信息提取机械、工具轨迹覆盖窄、会话结束无收尾。

- **P0 数据契约**（`src/self-evolve/enrichment.ts`）：`EnrichmentRecord` 独立 ledger（不回写 suggestions JSONL）；`resolveSignal(raw, enrichment)` 统一投影；完整 `traceHash+sessionId` join，12 位 id 碰撞 fail-closed；`evidenceIdFor` 为证据生成稳定内容哈希 id。
- **P1 通用轨迹**（`src/self-evolve/trajectory.ts`）：`collectToolCallTimeline` 保序时间线 + 工具 adapter registry（bash/edit/grep/lsp/read/delegate/ask/sop）+ `buildTrajectoryEpisodes`（failure_recovery/repeated_failure/empty_then_refined/permission_block/success）+ `projectSopToolCalls`（SOP 兼容投影）。
- **P2 受预算语义 enrichment**：`/self-evolve config captureMode=hybrid` 启用（默认 `heuristic`，现有用户无感）；fire-and-forget LLM 生成 title/summary/knowledge，受 per-session 预算约束（≤2 次/6 候选/每批 ≤3/30s）；证据先编号后供 LLM 选择，未知 evidence id → `heuristic_fallback`；失败永不阻塞收集。
- **P3 接回治理链**：`/self-evolve review pending [N]` 评审当前 session 未评审且 terminal-resolved 的信号；`SelfEvolveReview` 加 `sessionId`/`signalIds`；rescued unknown 信号补写 evidence 后可 stage；review gate 不变。
- **P4 会话收尾**（`src/self-evolve/session-summary.ts` + `session_shutdown` handler）：`reload` 写 checkpoint，`quit`/`new`/`resume`/`fork` 写 final summary；`/self-evolve wrap` 手动出摘要（幂等）；pending-review ≥3 时提示。shutdown 是 state-only，不启动 LLM/review/stage。
- **治理纪律不变**：只 stage 不 promote；不新增采集事件；SopLoader 只读；旧信号无迁移。
- **验证**：se-e2e 91、se-deep-sim 25、semantic 31、tool-trajectory 31、session-summary 17；tsc 0 错误。

<success_criteria>
- [ ] intent 正确分类并映射到对应 CLI 步骤，命令参数与 `maestro <cmd> --help` 一致
- [ ] full-cycle：run check 评审清单已读 → stage（evidence 锚点）→ run complete --advance（sealed run）→ promote --resolve 内联裁决+晋升（reason 非空）→ search 命中验证；session 源候选需先 session complete 再 promote（session complete 仅 session 源候选需要）
- [ ] 所有知识写入均经 `maestro knowledge ...` CLI 或 seal 事务，未直接写 spec/knowhow 文件
- [ ] 阻断条件（未 seal / 未裁决 / 冲突 / 空 reason / stale receipt）被显式报告而非绕过
- [ ] global scope 影响已提示用户并确认；共享 workflow 文件未被修改
</success_criteria>