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} --actor {a} --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 + 未来验证