converge — 双 Agent 迭代收敛器

双 Agent 迭代收敛，专为 AI 生成产物设计。不同于脚本化工作流，converge 使用独立 Agent 之间的对抗式审查循环，通过迭代驱动质量提升——直到 Reviewer 给出 可执行 verdict 或触发停止条件。

框架无关：Reviewer / Executor 的启动和续命通过抽象能力层（Spawn / Continue / Identify）实现，不绑定特定框架 API。核心预算裁决脚本（file-authoritative budget_gate.py）同样宿主无关——reserve/settle/ingest-verdict 的语义在所有框架下一致。

预算执行分 tier：核心 gate 虽宿主无关，但"能否在 spawn 前硬阻断"取决于框架是否提供可阻断的 pre-spawn hook。Claude Code 已落地 best-effort guarded（PreToolUse 总量兜底）；opencode / Codex 当前为 auditable-only；真正的 enforced 仍是未来能力。详见下方「预算执行」。

设计哲学

不要告诉模型该怎么走。告诉它"到达"意味着什么，给它验证工具，让它自己找到路径。

Converge 遵循两条宪法级设计原则：

Bitter Lesson（苦涩教训）：手动注入的工作流结构（规范、脚本、硬编码角色）会随着模型能力的提升而逐渐失效。取而代之的是，它定义验收标准（contract）、验证工具（lint、测试）和对抗式反馈（独立 Reviewer）——然后让模型自主探索，直到通过。机制层硬编码（三角色、对抗循环、契约驱动），领域知识层做成 compiled 产物（反模式注册表由真实收敛日志驱动、随命中频率自动衰减）。

Occam's Razor（如无必要，勿增实体）：每个文件、每条规则、每个字段必须回答"它解决什么具体问题"。解决不了具体问题的抽象一律拒绝。三层分离（机制/宪法/反模式）本身就是 Occam 的应用——不让会变化的反模式知识腐化在不变的机制里；章程瘦身（引用表替代 ~400 行重复模板）同理。已失效的信息（如迁移考古）删除，git log 是它的归宿。

工作原理

Round 0：合同谈判（可选前置）
  Executor 提出验收标准 → Reviewer 挑战 → 形成最终 contract.md

Round 1+：对抗收敛
  Reviewer（fresh 全新上下文）审计产物 → Executor 修复 → 重复

振荡检测：
  Type O（推翻）、Type R（重复）、Type F（翻转）、Type S（摆动）
  → 达到阈值后硬停或上报用户

角色	担任者	关键约束
Orchestrator	主对话 Agent	不兼任 Reviewer/Executor；只管理循环 + 语义判定
Reviewer	每轮 Spawn 的独立 Agent	全新上下文（看不到历史对话）；prompt 自足
Executor	每轮 Spawn 的独立 Agent	全新上下文；prompt 自足

终止状态与收敛判定

产物通过以下五种方式之一终止收敛循环（详见 SKILL.md）：

终止类型	一句话概要
终止-a 严格首轮通过	fresh reviewer 首轮 verdict = `可执行`，零阻断
终止-b 渐近通过	blocking 单调下降至 ≤1 低级项，用户确认
终止-c 主观接受	用户明确说"够了"
预算 gate 阻断	gate 返回 `BLOCK:*`，无有效 extension 不得续 spawn；用户选择扩容 / 接受 / 简化 / 终止
振荡硬停	Type O/R 达阈值，自动硬停

预算执行

收敛的 spawn 预算由确定性脚本 scripts/budget_gate.py 在每次 spawn 前后裁决，不靠 Orchestrator 记忆计数。执行链路：

reserve → Agent spawn → settle → ingest-verdict

reserve：spawn 前申请额度；PROCEED:<rid> 方可 spawn，否则按裁决处置
settle：spawn 后落账（succeeded 须带 instance_id）
ingest-verdict：reviewer verdict 落盘后驱动 mode 记录与边际递减判定

当前能力 tier

模式	能力	当前框架
`auditable-only`	通用；Orchestrator 调用 reserve/settle；ledger + extension 链提供审计，pre-push hook 提供审计（阻断需显式 `CONVERGE_STRICT=1`）	opencode、Codex 及所有框架（缺省）
`best-effort guarded`	Claude Code；在 auditable-only 基础上增加独立、单调的 Agent spawn 总量 hook（= hook-blocked auditable-only）	Claude Code
true `enforced`	尚未实现；需要角色 FSM、角色不可伪造及权限锁定	（deferred）

best-effort guarded 不是 enforced——只强制总 spawn cap：不执行 per-scope reserve/settle（仍由 Orchestrator 驱动）、不防主动删除或篡改 hook/binding、hook 不写 ledger 也不与 ledger 双计。它解决的是漂移、遗忘和 compaction 后失控。

预算阻断处置

达预算上限时 gate 返回 BLOCK:budget_exhausted / blind_exhausted / ultraverge_exhausted / total_spawn_cap：停止，无有效 budget_extension（须关联真实 BLOCK decision 事件 + 用户原话）不得续 spawn。用户选择：扩容续跑 / 接受当前产物（终止-c）/ 简化 plan / 终止。

适用场景

计划、规范或代码产物，在执行前需要独立交叉验证
复杂产物，单次审查不足以保障质量
质量关键型交付物，要求零阻断
可组合为 Dynamic Workflows 中的质量门控（L1 信号检测 + L2 单轮对抗审查）

不适用场景

单次快速审查（使用更轻量的 skill）
Lint 级别的检查（使用实际的 lint 工具）
足够简单、不需要对抗验证的任务

目录结构

converge/
├── SKILL.md                  # 入口：Orchestrator 工作流 + 抽象能力层
├── CONSTITUTION.md           # 宪法级设计原则、Orchestrator 行为边界、治理文档清单与修改程序
├── GOVERNANCE-DECISIONS.md   # 具名治理决策记录（GD-N）
├── docs/                     # 开发侧记录（不随 skill 加载，但入库）
│   ├── CHANGELOG.md               # 变更记录
│   ├── plans/{active,done}/       # 计划文件——CONSTITUTION §四 要求的修改程序凭据
│   ├── problems/bugfix/           # 具体缺陷的排查记录
│   └── dogfood/                   # 端到端自用验证记录
├── scripts/
│   ├── budget_gate.py             # 预算 gate（file-authoritative，reserve/settle/ingest-verdict/bind + PreToolUse hook）
│   ├── archive_convergence.py     # Archive Contract v1 CLI（begin/complete/record/archive/check）
│   ├── archive_contract/          # 契约实现：model / capture / presentation / transaction
│   ├── ocsr_spawn_adapter.py      # 把 OCSR dispatch 包装为 Spawn 实现（见 refs/framework-adapters.md §A.2）
│   ├── l1_gate.py                 # L1 信号检测（非 LLM，零 token 成本）
│   ├── distill_antipatterns.py    # 反模式蒸馏器（全量编译 retrospective → status）
│   └── hooks/
│       ├── pre-commit             # 提交前检查
│       ├── pre-push               # 推送前检查（含孤儿 reservation / stale 检测）
│       └── stale-check.py         # active/ stale 项检测
├── tests/
│   └── test_budget_gate.py        # 预算 gate 验收用例（49 tests，stdlib only）
└── refs/
    ├── contract-negotiation.md    # Round 0：合同谈判流程 + contract.md 格式
    ├── decomposition-protocol.md  # 层级式并行收敛：分解协议、分阶段管控
    ├── orchestrator-guide.md      # 循环管理、振荡检测、状态跟踪
    ├── reviewer-prompt.md         # Reviewer prompt 模板 + 硬性规则
    ├── executor-prompt.md         # Executor prompt 模板 + 反模式防御
    ├── rubrics.md                 # 主观质量评分维度库
    ├── state-schema.md            # 跨轮状态持久化 schema
    ├── testing-toolbox.md         # 外部验证工具（lint、测试、hooks）
    ├── quality-gate.md            # 质量门控协议，用于 Dynamic Workflows 集成
    ├── design-review-prompt.md    # 收敛后设计审查：7 维骨架，单轮咨询式
    ├── framework-adapters.md      # 附录 A：各框架的 Spawn/Continue/Identify 实现与诚实边界
    ├── model-tiers.md             # 家族档位对照（数据层，随模型换代更新）
    ├── run-specs/                 # OCSR 确定性运行器的 spec 模板（如终局链路）
    ├── executor-discipline.md     # Executor 纪律
    ├── reviewer-discipline.md     # Reviewer 纪律
    └── antipatterns.md            # 反模式注册表（compiled 产物，status 由 distill 维护）

.converge/ 的三个子目录分别对待（2026-08-10 起）：

目录	入库	理由
`.converge/done/`	是	已归档的收敛证据。内容寻址、可用 `check` 机械复验，是这套治理机制唯一的事后凭据
`.converge/active/`	否	在飞的收敛现场，随时变化
`.converge/tmp/`	否	临时产物

docs/ 同样入库——它是开发侧的长期记录，且 CONSTITUTION.md 第四部要求的计划文件就在里面。

.gitattributes 里的 .converge/done/** -text 是必需的，不是装饰。
归档的 manifest 按字节记录 sha256 + size；* text=auto eol=lf 的换行归一化会改字节。
实测去掉那行，done/ 下 14 个 CRLF 文件的索引字节即与工作树不一致。
用 archive_convergence.py check-git-ref <repo> <slug> --from-index 可以直接
从 git 索引复验哈希，而不是只验工作树。

验证

python -W always::ResourceWarning tests/test_budget_gate.py
python -m py_compile scripts/budget_gate.py tests/test_budget_gate.py
git diff --check

期望：49 tests OK，无 ResourceWarning。预算 gate 不依赖外部库（stdlib only）。

converge-skill