evolve

/evolve — 目标驱动的自主循环

衡量问题所在。修复最严重的问题。再次衡量。修复是否会不断累积，形成持久的知识护城河，是一个持续跟踪的假设，而非承诺——根据 ADR-0004 和 ADR-0011，该假设已被降级为尚未证实。已证实的产品是每个周期的验证（没有结论 = 尚未完成），而非不断累积。不要在标尺之前宣传飞轮。 实验级。 自主长循环；应由人监督运行，或分派到某个运行基底上，绝不可作为仓库内守护进程运行（ADR-0009）。

周期反馈是明确的。 每个已完成的执行单元都会将 Validate -> Learn -> orchestrator 串联起来；证明和记录都不会控制重试或交付。

循环以此技能的形式运行。 evolve 选择工作并调用完整的 /rpi --auto 周期——这就是循环。有实质内容的 Learn 数据包会返回编排器，由编排器通过 Discovery 修改剩余计划，并且只将修改后的计划送入 Premortem。no_change 允许明确决定继续、重试、停止或升级；terminal 则关闭周期。运行基底会将整个循环作为一个单元分派；原有的 RPI CLI 封装器已退役（ADR-0009）。

操作者节奏： 衡量仓库状态 → 选择下一个价值最高的事项 → Discovery → Premortem → Crank → Validate → Learn → 编排器决策 → 重复，直至触发熔断开关、达到最大周期上限、回归保护器生效，或真正进入休眠状态。

约束

• 每个选定事项都运行一个完整的 rpi --auto 周期，随后重新读取工作阶梯，因为阶段不完整和固定待办清单会破坏反馈循环。
• 绝不允许 Validate 或 Learn 推送、关闭工作、修改计划或选择下一个周期；这些属于不同的适配器／编排器决策。
• 熔断器触发后，先进行一轮有界的辅助处理，再升级；只有需要判断、拒绝、预算耗尽或辅助处理失败时才交由人工处理，因为普通阻塞会回到循环中最早失效的步骤。

工作选择阶梯

每次完成有效工作后，都要从顶层重新检查选择阶梯——绝不能只检查一次。各阶梯的完整流程（ao loop next-work 建议、范围筛选器、生成器代码、--quality 级联、休眠硬性门槛）：references/work-selection-ladder.md。

1. 已收集 — .agents/rpi/next-work.jsonl 中最新的未消费后续工作
2. 已开放且就绪的 bead — ao beads exec ready，优先级最高
3. 未达标目标 + 指令缺口 — ao goals measure（若使用 --beads-only 则跳过；跳过已隔离的振荡器）
4. 生成器 — 覆盖率 / 安全 / 性能 / 重构发现 → bead 或队列项（见下文）
5. 复杂度 / TODO / 偏移 / 死代码 / 过期文档 / 过期研究挖掘
6. 功能建议 — 当没有更明确的工作时，根据仓库用途提出建议

--quality 会将顶部顺序反转（先处理发现，再处理目标）。节拍器门槛会阻止选择与上一轮运行的 mode 重复的阶梯（连续次数 ≥3）。休眠是最后手段——队列为空意味着“运行生成器”，而不是“停止”；只有在队列和生成器层连续多轮均无结果后，才进入休眠。

工作生成器（自动调用；使用 --no-lifecycle 跳过，此时会回退到手动扫描）：

• Skill(skill="test", args="coverage") → 覆盖率低于 40% 的文件将成为队列项
• Skill(skill="refactor", args="--sweep all --dry-run") → CC > 20 的函数将成为队列项
• Skill(skill="security", args="audit") → CVSS ≥ 7.0 或落后 2 个及以上主要版本的依赖项
• Skill(skill="perf", args="profile --quick") → 热路径性能发现

**实时技能编辑免疫系统：**如果某轮修改了 skills/<slug>/SKILL.md，则在交接前运行 ao skills edit seal --skill <slug> --actor "${AGENT_NAME:-agent}"——seal 会创建回滚提交，并记录 Skill-Edit trailers，供每日摘要使用。docs/contracts/critical-skills.txt 中的关键技能会拒绝无人监督的编辑；仅在监督下使用 --allow-critical。

标志

标志	默认值	说明
--max-cycles=N	unlimited	完成 N 轮后停止
--dry-run	off	显示计划执行的轮次操作，但不执行
--beads-only	off	跳过目标测量，仅从待办列表中选择工作
--skip-baseline	off	跳过首次运行的基线快照
--quality	off	优先处理已收集的事后分析发现
--compile	off	在第 1 轮前运行 ao compile 知识预热
--test-first	on	将严格质量默认值传递给 rpi
--no-test-first	off	明确禁用传递给 rpi 的测试优先设置
--no-lifecycle	off	跳过生命周期工作生成器（回退到手动扫描）
--mode=burst|loop	burst	操作者循环；拒绝 STOP（references/loop-mode.md）

执行步骤

你必须执行此工作流——不要只描述它。 **完全自主：**每次运行 rpi 都使用 --auto；不要向用户询问任何内容（有关狭义的操作者形式例外，请阅读 references/autonomous-execution.md）。每轮 = 一次完整的 3 阶段 rpi 运行。对于广泛的 AgentOps 领域演进（技能、CLI、文档、测试、bead、知识），请先阅读 references/domain-evolution-bootstrap.md——其中包含 BDD/DDD/Hexagonal/TDD/XP 控制面板和 clean-room 技能工厂防护措施。

步骤 0：设置

陈旧检出状态检查（首先运行）： git fetch origin && git status -sb。如果落后或已分叉，且这是一个没有未推送工作的临时编排树，则运行 git reset --hard origin/main。调查流程中绝不要运行 git pull --rebase——如果本地 main 已分叉，该命令会悄无声息地不起作用，导致已合并的文件看起来像是“缺失”。

git fetch origin && git status -sb              # survey guard — never `git pull --rebase` here
mkdir -p .agents/evolve
ao corpus inject --query "autonomous improvement cycle" --limit 5 2>/dev/null || true
# session state (idle_streak + mode_repeat_streak in .agents/evolve/session-state.json) is refreshed inline by the loop

从磁盘恢复周期状态（可在压缩后保留）：从 .agents/evolve/session-state.json 读取 CYCLE、IDLE_STREAK、GENERATOR_EMPTY_STREAK、LAST_SELECTED_SOURCE、CLAIMED_WORK_REF；规范的周期记录文件是 cycle-history.jsonl（两者都仅限本地——嵌套的 .agents/.gitignore 会忽略所有路径，因此也要在提交消息中记录持久里程碑）。**注入先前失败信息（必须）：**读取 cycle-history.jsonl 中最近的 3 条记录；对于任何包含 FAIL|BLOCKED 的 gate，提取失败关键词，并在选择工作前对 .agents/learnings/ 执行 grep——否则循环会在每个周期重复推导相同的经验教训。详情见：references/cycle-history.md、references/convergence-mechanics.md。

**仓库本地约定。**如果 docs/contracts/repo-execution-profile.md 存在，请读取其中有序的 startup_reads，并在选择工作前据此完成引导；缓存 validation_commands、tracker_commands、definition_of_done。如果存在仓库本地的 PROGRAM.md（或 AUTODEV.md 别名）约定（以 PROGRAM.md 为准），rpi 会自动加载；缓存其 mutable_scope、validation_commands、decision_policy、stop_conditions；优先选择可变范围内的工作，绝不要悄然扩大范围以包含不可变文件。PROGRAM.md 约定属于旧版 autodev 流程（仅在 -tags legacy 下构建）；其规范和修复指南位于 docs/contracts/autodev-program.md，可执行规范见 references/autodev.feature 和 references/autodev-cli.feature。

断路器（可调）： 基于时间（60 分钟内没有产生有效进展） · 最大周期数／最大尝试次数上限 · 成本／配额预算 · 振荡。普通的 REFUTED 结果会自动重做；断路器触发后，会进行一次有界的全新上下文辅助处理，只有辅助处理失败或属于跳过类别（拒绝、明确判断、达到上限）时，才会通知人工。阈值可配置（EVOLVE_KILL_TTL_DAYS、--max-cycles、最大尝试次数），不会硬编码。**振荡隔离：**根据周期历史预先填充（目标出现 3 次或更多“改进→失败”转换）。参见 references/oscillation.md。

步骤 0.2 / 0.5：预热 + 基线

**检查点：**仅运行 --compile（--dry-run 时跳过）：按照 references/knowledge-loop-integration.md，在第 1 个周期前运行 ao compile。首次符合条件的运行中，按照 references/fitness-scoring.md 记录适应度基线。

步骤 1：检查终止开关（每个周期的顶部）

CYCLE_START_SHA=$(git rev-parse HEAD)
# Mechanical pre-cycle gate: KILL/STOP/DORMANT/HANDOFF markers (TTL + non-sticky),
# goal-regression, prior-cycle-FAIL. A SCRIPT the loop MUST run, not skippable prose.
if [ -x scripts/evolve/halt-check.sh ]; then
  if ! HALT_OUT=$(bash scripts/evolve/halt-check.sh --json); then
    REASON=$(printf '%s' "$HALT_OUT" | jq -r '.halt_reason // "unknown"')
    if [ "$REASON" = "prior_cycle_fail" ]; then
      export EVOLVE_RESTORATIVE=1   # not terminal: Step 1.5 restricts scope to CI-red reduction
    else
      echo "halt: $REASON"; exit 0  # kill/user_halt/dormant/goal_regression -> stop this cycle
    fi
  fi
fi

**敏捷优先的休眠策略：**只要存在就绪的 beads，DORMANT 就绝不会保持生效——当 ao beads exec ready 返回就绪项或存在已收集的工作时，halt-check.sh 会自动清除它。KILL/STOP 遵循 EVOLVE_KILL_TTL_DAYS（默认值为 7）；过期标记会被显示并绕过。goal_regression（goals_passing_after < before）会停止流程，以便操作员介入。

步骤 1.5：修复优先分类器

ao ci recent --limit 1（类型化的 BC2 CIStatusPort）→ 如果上次推送的 CI 结果为 failure，本周期将仅用于修复：步骤 3 只处理能减少 CI 红灯的工作（已收集的 Bug、门禁修复 beads、生成器 Bug 输出）——在 CI 变绿之前，不进行晋升、功能开发或新形态工作。周期历史中的 gate=FAIL 会自动触发此逻辑，使其应用于下一个周期 N+1。收敛检查：ao loop converged --green-streak <n> --unconsumed-high-medium <n> [--fitness-baseline]（类型化的 BC3 ConvergenceCheckPort）；根据 .converged 分支处理（默认条件：CI 连续变绿 ≥ 3 次，HIGH+MEDIUM 的后续工作 ≤ 1，且已记录基线）——如果为真，则发出 teardown，且不要重新启用。参见 references/convergence-mechanics.md。

第 2 步：测量适配度

如果使用 --beads-only，则跳过。运行 ao goals measure → .agents/evolve/fitness-latest.json。完整测量、基线采集和周期后回归检测：references/fitness-scoring.md。

第 3 步：选择工作

运行上面的阶梯；阅读 references/work-selection-ladder.md 了解各阶的代码。敏捷不变量： ao beads exec ready ≥ 1 ⇒ 循环绝不写入 DORMANT，也绝不退出——进入 DORMANT 的唯一途径是待办列表完全为空且生成器无结果（3 次检查）；上下文耗尽 → HANDOFF，而非 DORMANT。如果使用 --dry-run：报告将要处理的工作，然后进入拆除阶段。

第 4 步：执行

主要引擎：/rpi（必须完成全部 3 个阶段）。仅当某个 bead 的范围已足以直接执行时，才使用 /implement 或 /crank。

Invoke /rpi "{normalized work title}" --auto --max-cycles=1     # harvested / goal / gap / testing / bug / drift / feature
Invoke /rpi "Complete {issue_id}: {title}" --auto --max-cycles=1 # a bead (fallback: /implement {issue_id})
Invoke /crank {epic_id}                                         # epic with children

如果第 3 步创建了持久化工作，而非直接执行，则重新进入第 3 步，让新 bead 通过正常选择流程胜出。**机械批处理提示：**超过 20 个统一的逐文件编辑 → 使用脚本（awk/sed/for），而非调用 N 次 Edit（references/mechanical-batches.md）。**预检模式检查：**如果消费者读取的字段比目标端口投影的字段多出 > 20%，则中止，并改为端口扩展周期（references/pre-flight-schema-check.md）。**操作员决策形态例外：**仅当形态决策影响 > 50 个文件或涉及架构／契约表面时，才允许使用 AskUserQuestion（references/autonomous-execution.md）。

第 4.5 步：同步源代码表面（门禁前）

在门禁前同步二进制文件和生成的表面：Go CLI 变更需要构建／安装；Codex 技能变更需要重新生成哈希；技能清单变更需要执行完整的一次性重新生成。使用门禁卫生和新技能落地，切勿分步重新生成。

第 5 步：回归门禁

**检查点：**运行项目测试，以及有序的仓库配置文件／PROGRAM.md validation_commands 和接线闭环检查。应用 decision_policy、不可变范围和 stop_conditions；重新测量并写入 fitness-latest-post.json，然后回滚回归。周期成功前，将已认领的工作保持为 consumed: false；之后重新读取 .agents/rpi/next-work.jsonl。详情：适配度评分、门禁卫生、知识整合。

第 6 步：记录周期并提交

有产出（改进／回归／收获）：将周期记录追加到 .agents/evolve/cycle-history.jsonl，提交实际变更。空闲（即使生成器运行后仍未发现工作）：追加一条 result: "unchanged" 的记录；不执行 git add，不提交。如果周期处理了产品或目标支持的缺口，则在周期记录的 trace 字段中记录 XP/BDD/TDD 轨迹（目标假设 → 缺口 → Gherkin → 失败证明 → 红／绿 → 重构 → 验证 → 加固 → 目标调整）；简单的一次性周期则记录 trace.exemption_reason。轨迹完整性仅供参考，绝不作为门禁。参见 references/cycle-history.md、references/quality-mode.md。

第 7 步：可选的确定性交付

不可变的 Validate 证明通过 Learn 且编排器接受周期后，仅当仓库策略或操作员授权交付时，才调用仓库选定的确定性 /push 适配器。传入确切的源 SHA、目标位置和确定性检查结果。Push 不得更改判定结果、关闭跟踪器状态或完成生命周期；若未获得交付授权，则返回准备好的 SHA 和证据。交付失败时，将未更改的证明返回给编排器。

步骤 7：循环／停止

调用方记录交付或准备移交的结果后，将 CYCLE 加 1，并返回步骤 1。

仅在以下情况停止（所有情况都必须有充分理由，绝不能仅仅因为上下文大小）：(1) KILL/STOP 标记——操作员覆盖；(2) --max-cycles 上限；(3) 确实停滞——ao beads exec ready=0 AND harvested=0 AND failing-goals=0 AND GENERATOR_EMPTY_STREAK ≥ 2 AND IDLE_STREAK ≥ 2 → 写入 DORMANT；当 ao beads exec create 添加一个就绪 bead 时，DORMANT 会自动清除；(4) 回退后的回归熔断器。上下文耗尽不是停止条件——写入 .agents/evolve/HANDOFF（非持久），记录 result: "context-handoff"，结束本轮；下一次触发时会在步骤 1 清除 HANDOFF 并恢复运行（references/context-budget.md）。

**强制检查点——会话 PR 阈值（控制下一轮，不是终止条件）：**当 session_pr_count >= 5 时，调用 /postmortem --deep 并等待判定文件。PASS → 继续；WARN → 继续，并在下一轮的 notes 中注明注意事项；FAIL／无法收敛 → 写入 STOP。Agent 不得自行评定或自行写入 STOP——没有判定结果就写入 STOP，是 2026-05-20 反模式（references/postmortem-checkpoint.md）。

清理

提交所有已暂存的 cycle-history.jsonl，运行 /postmortem "evolve session: N cycles"（轻量的会话结束回顾——不能替代由评审委员会把关的阈值检查点），仅在获得授权时调用 /push 推送尚未推送的提交，并报告摘要（循环次数、有效／回归／空闲次数、停止原因）。完整流程：references/knowledge-loop-integration.md、references/teardown.md。绝不要将 .agents/evolve/STOP 用作检查点判定文件的替代品。

具有发布形态的分支必须遵循发布清理契约：绝不要根据每轮的 --fast 建议运行 /release，将未经检查的清单带入移交，并在打标签前要求通过完整发布门禁。

输出规范

• **路径：**将循环摘要输出到 stdout；追加到 .agents/evolve/cycle-history.jsonl；写入 .agents/evolve/{fitness-latest.json,session-state.json} 和控制文件 {STOP,DORMANT,HANDOFF}。
• **文件名：**循环历史文件为 cycle-history.jsonl；当前适应度和可恢复状态使用上述固定文件名。
• **格式：**stdout 使用 Markdown；状态和适应度使用 JSON；循环历史使用遵循 references/cycle-history.md 的 JSONL。
• **验证命令：**运行仓库／配置文件测试和 ao gate check --fast --scope head（该命令已涵盖连线闭包）；如果选择交付，还必须运行 bash skills/push/scripts/validate.sh。
• **下游移交：**返回循环次数、适应度变化、结果、停止原因、变更路径、不可变的 Validate 判定结果，以及任何确定性的交付结果；下一轮会使用持久化状态和未消费的工作。

质量检查清单

• 所选工作遵循阶梯，并处于声明的可变范围内。
• 有效循环包含确定性验证，以及不可变的、针对当前候选项的 Validate 判定结果。
• 回归会回退；队列项在获准交付成功或调用方释放之前不会被消费；熔断器处理遵循先助手、后人工的策略。

故障排除

问题	解决方案
循环立即退出	移除 ~/.config/evolve/KILL 或 .agents/evolve/STOP
多次空运行后停滞	多次运行中，队列层和生产者层均为空——休眠是兜底结果
ao goals measure 挂起	使用 --timeout 30 --total-timeout 75，或使用 --beads-only 跳过
回归门禁执行回退	检查已回退的变更，缩小范围后重新运行；将已认领的工作释放回可用状态

参考资料

• 循环机制 — work-selection-ladder.md（逐级选择）、fitness-scoring.md（基线／回归／回退）、convergence-mechanics.md（优先修复分类器）、cycle-history.md（JSONL、恢复、追踪）、oscillation.md、metronome-gate.md、scout-mode.md、long-loop-discipline.md
• 门控 + 交付准备 — gate-hygiene.md（源代码面、红色问题分诊）、new-skill-landing.md（六个派生界面）、ao-command-landing.md、postmortem-checkpoint.md、pre-flight-schema-check.md、mechanical-batches.md、snapshot-pattern-for-long-cycle-gates.md
• 自主性 + 知识 — autonomous-execution.md（循环规则 + 操作者形态例外）、context-budget.md、knowledge-loop-integration.md（认领／释放、拆除）、compounding.md（根据 ADR-0004/0011 确立假设立场）、domain-evolution-bootstrap.md、quality-mode.md、parallel-execution.md、teardown.md、artifacts.md

行为契约锚点（由 scripts/validate.sh 验证）

精简后，流程已移至 references/，但这些不变量仍保留在此处——该技能自己的验证器会搜索它们，它们也是循环的关键行为支柱：

• 连续值，而非布尔值： 每项适应度指标都要报告相对于阈值的连续值（value/threshold），不能只给出简单的通过／失败结果。

• 振荡扫描（始终启用，第 0 步）： 在选择目标前，根据 ao compile 的振荡报告预先填充隔离列表。

• 接线预检（第 5 步）： if ao gate check --fast --scope head; then proceed; else fix wiring first; fi — 接线损坏时绝不交付循环（always.wiring-closure 元门控已退役，接线闭合检查已并入门控）。

• 适应度测量必须使用 CLI — ao goals measure 是测量工具；文字自评不算适应度。

• 先采集，再选择： 已采集的 .agents/rpi/next-work.jsonl 工作优先于生成的候选项；先处理完采集项，再生成候选项。

• 生成器阶梯（采集项已清空时）： 改进测试 → 收紧验证并进行缺陷搜寻 → 提出具体的功能建议。

• 消费前先认领队列项： 先认领它（设置认领标记），在授权交付成功或调用方完成交接前，保持 consumed: false；认领后、消费前发生崩溃时，该行必须仍可重新运行。

• 立即重新读取队列： 每次 /rpi 轮次结束后，立即重新读取 .agents/rpi/next-work.jsonl — 该轮次可能采集了新工作。

• 仓库执行配置文件： 如果存在，请遵循 docs/contracts/repo-execution-profile.md（startup_reads、validation_commands）。

• 规范 + 架构： evolve.feature（受门控的循环、阶梯、永不自行停止）、goals-schema.md、loop-mode.md、examples.md、autodev.feature + autodev-cli.feature（旧版 autodev 通道，-tags legacy）

示例

/evolve 会持续运行，直到真正停止；/evolve --max-cycles=3 会限制运行周期；/evolve --dry-run 会报告选择结果，但不进行修改。完整演练：references/examples.md。

• skills/rpi/SKILL.md — 完整生命周期编排器（每个周期调用一次）
• skills/crank/SKILL.md — 专题执行（针对 beads 专题调用）
• skills/postmortem/SKILL.md — 学习提取与挖掘入口；吸收了已弃用的 /curate、/compile 和 /flywheel 技能（机械操作入口是 ao compile 和 ao flywheel status CLI，而不是技能）
• docs/contracts/autodev-program.md — 仓库本地的 PROGRAM.md 契约（旧版 autodev 通道）
• GOALS.yaml — 此仓库的适应度目标
• 测试 · 重构 · 安全 · 验证 — 工作生成器