grade-iterate 是构建 Claude Managed Agent（CMA）的第三阶段，主题是“评分→迭代”的有界循环。它是该插件的循环机制：CMA 的 outcome 原语会在隔离上下文中对智能体的工作进行自我评分，并将未通过的判定反馈给下一次尝试。该循环始终由 max_iterations（1 到 20）限定，绝不会“永远改进”。
用途
该技能用于为 CMA 智能体定义一个可评分的结果（outcome），通过评分标准（rubric）驱动迭代改进，并在迭代完成后用保留用例评估泛化能力，最终决定是否发布或升级为计划部署。
主要能力
-
定义结果：使用 outcome_builder.py 生成 user.define_outcome 载荷。评分标准是必需的，max_iterations 会被限制在 1 到 20 之间。载荷作为 user.define_outcome 事件发送（追加到运行中的会话）。
-
读取判定：使用 verdict_reader.py 读取评分结果。它会以表格形式呈现评分标准结果并给出建议：SHIP（已满足）、SHARPEN 后重跑（需要修订）、ESCALATE（达到 max_iterations 或失败）、RESUME（被中断）。当剩余迭代次数不超过 1 时，建议会变为“立即做单个最高价值的修复或升级”。
-
循环不变量：每次迭代必须至少让一条评分标准从失败变为通过，否则运行会在上限处停止并升级。不要将预算浪费在表面修改上。
-
保留评估：一旦某个版本通过，运行保留评估。使用 eval_scaffold.py 运行保留用例（迭代期间从未见过的用例），并行执行，并发上限为 CMA 的 25 线程上限，每个用例都按同一评分标准评分。
-
决策：作为 v0 发布，或升级为计划部署（第四阶段）。在目标上记录判定：goal_state.py set --phase run-without-you。
使用方式
定义结果：
python3 scripts/outcome_builder.py
--sheet ./my-agent/build-sheet.json --max-iterations 5
--out ./my-agent/payloads/outcome.json
读取判定： python3 scripts/verdict_reader.py --result ./my-agent/last-verdict.json
运行保留评估：
python3 scripts/eval_scaffold.py
--sheet ./my-agent/build-sheet.json --out ./my-agent/eval.json --concurrency 5
适用场景
适用于需要为 CMA 智能体建立可评分、可迭代改进流程的场景，尤其是希望以有界循环方式提升智能体在特定评分标准上的表现，并在发布前用保留用例验证泛化能力的情况。
限制与硬性规则
- 始终有界：没有 max_iterations 上限就不能定义结果。
- 先读判定再行动：评分器的解释驱动下一步动作。
- 保留用例必须保留：绝不能用智能体已经迭代过的用例来评估泛化能力。
工具
- scripts/outcome_builder.py — 生成 user.define_outcome 载荷（评分标准必需，上限 1 到 20）。
- scripts/verdict_reader.py — 将评分器结果转换为下一步动作。
- scripts/eval_scaffold.py — 保留用例与并行运行计划（不超过 25 线程）。
参考资料
- ../../references/loops-and-workflows.md
- ../../references/cma-primitives.md（outcome 部分）
强制问题库（推荐并引用）
- “3 到 5 条评分标准是什么？”推荐：有依据、可检查的标准。引用：cma-primitives.md（评分标准必需）。
- “在你宁愿自己查看之前，要迭代多少次？”推荐：3 到 5 次。引用：loops-and-workflows.md（有界循环）。
- “失败时，是改进提示还是工具？”推荐：由失败的评分标准指向的那一个。引用：verdict_reader 的下一步动作表。
- “智能体没有见过哪些用例？”推荐：保留至少 3 个用于泛化。引用：本技能（保留评估）。