| name | self-evolve |
| description | 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' | '沉淀这段经验'] |
| allowed-tools | Read Write Edit Bash Glob Grep teammate WebFetch maestro observe ask-user-question |
| disable-model-invocation | true |
| session-mode | none |
<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>
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 文件。
按 `$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 |
|
规则：
- 无法分类或意图含糊 → 展示上表并请用户选择。
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 修复）。stage / review / promote / record 一律经 maestro knowledge ... CLI，不得翻译成直接写 spec/knowhow 文件。- 保留 stable knowledge ID、Run ID、Session ID、candidate ID、disposition、target、signal、reason 原样传递，不做改写。
核心时序编排（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（评审清单）
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/换行/前导破折号会错位后续参数）：
maestro knowledge stage knowhow "<title>" --content-file <path|-> --run <run-id> --evidence "<file:line>,<artifact-ref>" [--category <cat>] [--signal validated --signal-ids <ids>]
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 事务）
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}
maestro session complete --session {session_id} --participant {p} --actor {a} --request-id {r} --reason "<reason>" --expected-orchestration-revision {rev}
- verdict 诚实选择：
done（干净）或 done-with-concerns（有 caveat，全部列入 concerns）。
- seal 后 run 不可变（拒绝 sidecar 写入）；frontmatter decisions/constraints 自动物化为 spec 候选。
Step 4 — 呈现 + 裁决（happy path: promote --resolve；review --resolve 兼容回退）
maestro knowledge review <session-id> [--refresh] [--json]
maestro knowledge promote <session-id> --resolve <candidate-id> --as duplicate|related|conflict|supersede|unique [--target <knowledge-id>] --reason "<非空理由>"
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（阻断层硬门，用户确认后执行）
maestro knowledge promote <session-id> --resolve <candidate-id> --as <choice> [--target <knowledge-id>] --reason "<非空理由>"
maestro knowledge promote <session-id> --candidate <candidate-id>[,<id>...]
maestro knowledge promote <session-id> --all
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 + 未来验证
maestro session complete --session {session_id} --participant {p} --actor {a} --request-id {r} --reason "<reason>" --expected-orchestration-revision {rev}
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）。
1. **禁止直接写 spec/knowhow 文件**：一切生命周期写入只走 `maestro knowledge stage|review|promote|record` CLI 或 `run complete` 的 seal 事务；不在 `.workflow/specs|knowhow` 下手动增改条目。
2. **evidence 必填**：stage 与 record 尽量携带 `--evidence `（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 -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 结论只能做「线索候选」，不能证明知识正确。
`run check` 在 gates clean 时注入 finish-checklist：runtime 内置规范 + **workflow 文档 frontmatter `finish:` 数组行**（`extractFinish` 从 run command 关联的 workflow 文档提取）。落点 = 该 run 命令关联的 workflow 文档 frontmatter。文档查找顺序（`stepRegistryDirs`）：项目侧 `/.workflow/workflows/.md`（项目自有，可改）→ 共享 `~/.maestro/workflows/.md`（**不实际修改**，如确需修改须走显式用户请求）→ `/workflows/.md`。
应追加到目标 workflow 文档 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/ 文件保持只读。
信号沉淀流水线（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 — 读取最近信号与评审
LATEST_REVIEW=$(ls -t ~/.maestro/self-evolve/reviews/*.jsonl 2>/dev/null | head -1)
[ -n "$LATEST_REVIEW" ] && tail -1 "$LATEST_REVIEW"
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 匹配信号：
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> 显式隔离：
maestro knowledge stage <knowhow|spec> "<title>" --content-file <evidence-file> --session <session-id> --evidence "<file:line>,<file:line>"
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 前一次性确认）：
maestro knowledge promote <session-id> --all --json
maestro knowledge review <session-id> --json
--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 外部是否存在对应文档。
- 输出（三种产物，全部只读/只建议，不自动写入）：
- SOP 覆盖盲区报告：高频失败 outcome 但无对应
sop_topic 文档的盲区（如 computer_use 的 near_zero 在 coordinates/core 都未覆盖），附出现次数与示例信号 id。
- SOP 补丁候选：每个盲区生成一份带
tools/sop_topic frontmatter 的 evidence 文件草稿 + 对应 maestro knowledge stage knowhow --content-file 命令模板（复用 Phase 2C renderSopFrontmatterHint 逻辑的批量版）。
- 内嵌与 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>
