harness-evolve

将上游 metaharness-darwin evolve CLI 封装为 ruflo 技能。 这是与 ADR-150 读取层（score / genome / mcp-scan / threat-model / oia-audit）配套的写入层。当你的 harness 就绪度评分停滞不前，并想找出改变哪个表面能提升评分时使用—— 无需重新训练基础模型。

适用场景

• harness-score 结果低于目标，但你不知道是哪个策略 表面导致的。
• 你正在为新的垂直领域准备 harness，并想通过实证找到良好的 起始配置，而不是手动调优。
• 你正在将手动调优的 harness 与进化后的基线进行比较 （将 darwin 的冠军配置作为比较基准）。

不适用场景

• 用于持续的后台优化。Darwin Mode 由人工发起。 将其接入 CI 进行一次性探索，而不是用于自主自我修改。
• 在 CI 中用于 ruflo 本身。ADR-153 §5 明确拒绝自动进化 ruflo ——CI 门禁验证的是优雅降级，而非收敛。

算法

实现：scripts/evolve.mjs。

1. 验证参数（--repo 存在，--generations 上限 ≤ 50、--children ≤ 20、--concurrency ≤ 8，sandbox/selection/mutator 均为已知值）。
2. 未指定 --confirm 时：打印计划并以 0 退出（与 harness-mint 的安全 约定一致；在上游 safety.ts 检查之外再增加一道防线）。
3. 指定 --confirm 时：通过共享的 _darwin.mjs 异步辅助程序，从已安装的 @metaharness/darwin 运行 metaharness-darwin evolve <repo> ...（版本在 _darwin.mjs 中固定；仅当没有符合条件的已安装副本时，才进行一次性 ~/.ruflo/darwin-cache-<pin> 安装——绝不使用 npx）。每代进度会转发到 stderr；最终冠军 JSON 从 stdout 捕获。
4. 根据 generations × children × 每个变体 计算超时（每个变体实际约 60s，模拟约 2s）。调用方可通过 --timeout-ms 覆盖。
5. 保留上游退出码 99——将其传递为“安全审查未通过”，不要 重新映射。这是有意设计的跳闸机制（某个变体触发了 inspectVariant 对秘密信息、shell 外部调用、网络或动态求值的检查）。参见 ADR-153 §“安全模型”。
6. 可选的 --alert-on-no-improvement：当冠军配置 ≤ 父配置时，以 1 退出。

七个变更表面

表面	负责内容
planner	任务拆解／步骤排序
contextBuilder	输入提示词的内容
reviewer	自我批评／输出验证
retryPolicy	失败时何时以及如何重试
toolPolicy	Agent 可使用哪些工具，以及使用条件
memoryPolicy	持久化、回忆和遗忘的内容
scorePolicy	Agent 如何为自己的输出评分

每个变体只进行一次变更。不允许多表面变更（以保持清晰的因果 归因）。

输出

报告存放在 <repo>/.metaharness/ 下：

.metaharness/
  archive.json         # full lineage tree (sampling next gen draws from this)
  lineage.json         # parent→child edges only
  variants/<id>/       # per-variant code (kept for audit)
  runs/<id>/           # per-variant sandbox test output
  reports/winner.json  # final champion + score delta vs parent

技能 stdout = JSON {success, data: {champion, plan, durationMs, improved}} （传入 --diagnose 时还会包含 data.diagnosis——见下文）。

失败诊断（--diagnose）

GEPA 的关键技巧是根据执行轨迹进行自然语言失败诊断，并将结果用于下一次变异，而不仅仅是标量适应度。--diagnose 会实现其中一小部分功能：进化完成后，将失败或落败变体的记录通过 darwin 的 GEPA 库操作（通过 scripts/_darwin.mjs 中的共享 importGepa 解析器调用 analyzeTranscript + classifyFailure）进行处理，并在输出的 JSON 中追加一个 diagnosis 部分：

"diagnosis": {
  "available": true,
  "scope": "losing-variants",
  "variants": [
    { "id": "g1_v0", "transcripts": 2,
      "failureClasses": { "exploration-loop": 1, "edit-mechanics": 1 },
      "dominantClass": "exploration-loop" }
  ],
  "totals": { "exploration-loop": 1, "edit-mechanics": 1 }
}

上游格式注意事项（已根据 @metaharness/[email protected] 验证）：

• metaharness-darwin evolve --json 输出的是 TEXT 排行榜——标准输出不包含 JSON，也不包含记录。每个变体的运行记录位于 <repo>/.metaharness/runs/<id>.json。
• 这些运行记录保存的是沙盒执行轨迹（{taskId, exitCode, stdout, stderr}），并非 GEPA 格式的 {actionRaw, obs} 记录。因此，诊断会优先使用运行记录中嵌入的 GEPA 格式记录（Agent 沙盒／未来的上游版本），其次使用冠军变体的记录；若两者都没有，则输出 diagnosis: {available: false, reason, traceSummary}，其中 traceSummary 是按变体进行的机械统计（任务数／失败数／超时数／受阻操作数）。
• --diagnose 绝不会导致运行失败——任何内部错误都会降级为 {available: false, reason: "diagnosis-failed: ..."}。

退出代码

代码	含义
0	进化成功、试运行，或降级运行（Darwin 不存在）
1	使用了 --alert-on-no-improvement，且冠军变体未胜过父变体
2	配置错误或进化基础设施故障
99	上游的“安全资格取消”（原样传递，不重新映射）

优雅降级（ADR-150 约束 3 + ADR-153）

未安装 @metaharness/darwin 时，脚本会输出 {degraded: true, reason: 'metaharness-darwin-not-available', hint: ...} 并以 0 退出。ruflo 仍可继续运行。CI 中类似 no-metaharness-smoke.yml 的作业会断言此路径。