CoalFace — 扇出规范
诚实框架： 临时扇出也做出同样的承诺但毫无保证——令牌无界（不可控的生成开销、重复的共享读取、重试风暴、失控的流浪工人），速度不足（懒惰的编排器将100个点分批成5-8个臃肿的工人，导致尾部质量下降），质量甚至可能低于单人（一个偏离规范的工人、对真实树写入、半应用失败）。CoalFace = 通过结构强制实现的相同承诺——令牌有界约等于单人（钱包 + 共享摘要 + 最小单元下限 + 无自重试），速度全宽（工人数 = 点位数量，由下限/宽度限定），质量有保障（质量控制 + 单写入者 + 快照）。它规范了扇出行为；不使模型更聪明，也不保证正确性。
你是指挥（会话主控）。工人是叶子——通过平台提供的无生成工具代理类型生成它们（Claude Code: Explore 类）；它们读取、生成并返回，从不写入树，从不生成。
激活
coalfaceMode（默认 auto）：auto — 你自行判断提示词何时需要扇出；任何大于等于 autoFanoutFloor 个单元（默认 4）的扇出都遵循此规范，而不是临时生成（1-2个下级子任务可保持零仪式）。on — 对每个提示进行侦查；任何可分解的工作都进行扇出；仅不可分解的工作由单人执行。off — 完全关闭 CoalFace；使用原生扇出。手动 /coalface 在除 off 外的任何模式下均可召集。无需预付费： 用户的命令即是同意——一个单人主控会静默消耗相同的预算，而钱包将集群限制在该预算内，因此没有新的开销需要询问。一个例外：当侦查发现的工作远大于提示词暗示时，发出单行非阻塞提示（“发现 N 个点位，预计约 X —— 开始；按 Esc 停止”），绝不弹出确认框。运行后透明度 = 收据。
流程（固定顺序）
1 · 侦查（必须）。 真实提示词是模糊的（“清理这个仓库”）——首先调查工作现场；永远不要仅根据提示词确定集群规模。侦查子任务返回：点位列表（每个点位包含文件/范围或单元 ID）· 点位间的依赖图 · 需锁定的不变量（项目/用户通用规则、术语表/API/风格——将它们作为不变量读取）· 最后运行的领域门 · 推荐的集群模式（见下方分类）· 共享摘要（每个工人所需的配置/上下文——由侦查支付一次，包含在每份契约中；绝不让 N 个工人重复读取相同文件）。
2 · 分区（确定性）。 对点位范围进行区间重叠检查：重叠的点位合并为一个单元或链式依赖（表规则，非模型判断）；小于生成开销的单元与相邻单元合并（最小单元下限）。粒度诚实：“更细 = 更快”会饱和——实际时间 ≈ ceil(N / width) × 单元时间；当 N ≈ 2-4倍的波宽开销时，开销占主导 → 在下限和宽度上限内部选择近似最优。单元数量决定了集群规模（100个不重叠点位 → 100个订单，按波次限定）。
3 · 提示（条件性，非阻塞）。 任务远大于提示词 → 输出上述一行提示，然后继续。
4 · 波次。 有效宽度 = floor(平台宽度 × bandwidth%)（默认 25% ≈ 16 槽位平台上的 4 槽位）。逐波生成工人；每个工人收到工作契约（references/contract-template.md），包含其范围 + 共享摘要 + 锁定的不变量。模型：每个平台上默认使用等同于主控的模型；在 Claude Code 上，CoalTipple 委派降级分层是可选的增强功能（无时安全降级）——敏感单元（加密/认证/支付/迁移）即使处于廉价集群中也保持主控层级。AIMD 退避： 一波中遇到 429 错误 → 下一波收缩（乘法减少）；连续正常区间缓慢增长（加法）直至设定的百分比——如果百分比超过账户实际容量，则稳定在实际容量上，不会出问题；429 的订单是临时的 → 等待并重试相同订单（日志中保留），绝不向用户暴露失败。从子代理安全性完整继承的界限：有界波次 · 无僵尸（先收集再释放；超时后回收静默工人；权限等待不属于静默）· 工人 = 叶子 · 接近会话/配额限制时缩减至更少工人或内联自我（因限制而死亡的工人返回空值）。
5 · 返回 = 文本订单（提议不执行）。 编辑 → 锚点编辑（旧文本 → 新文本，精确匹配，位置无关——相同文件100个点位的情况也可以工作，因为锚点不会移动）——绝不使用行号差异（每次应用后行号会移动），也绝不使用每个工人的工作树（v1 中不包含工作树路径）。非编辑领域 → 返回已完成单元的文本（一段翻译、一条记录、一个报告章节）。工人从不接触真实树；副作用仅在你同意的顺序应用中触发。
6 · 收集时的质量控制（在任何应用之前）。 每次返回进行的机制检查：(a) 范围 — 每个锚点位于分配范围内，无外来文件（区间检查近乎免费）；(b) 规范 — 锁定的不变量在输出中可通过 grep 验证。拒绝 → 隔离 + 携带拒绝原因的重新生成一次（有界，绝不循环）；第二次失败 → 为用户提供收据。诚实上限：一个在范围内、符合规范、语义错误且无覆盖测试的返回会到达用户——收据会标记测试未覆盖的点位；此类问题的升级通道是 CoalBoard（不允许错误的通道），而不是 CoalFace 的默认流程。
7 · 应用——你是唯一写入者。 首先获取集群前快照（git 仓库：stash/HEAD-record；非 git：文件副本——绝不假设 git）。然后按拓扑顺序依次应用已接受的订单。锚点缺失（真正的冲突）→ 跳过并标记，继续——除非侦查标记为全有或全无的单元（类似迁移的任务类别）：一个失败即完全回滚。最后运行领域门（代码 → 构建+测试 · 语料库 → 语料规则 · 文档 → lint+链接 · 数据 → 模式验证 · 研究 → 引用）。门失败 → 完全回滚至快照；通过收据报告情况。
8 · 收据（始终）。 发现的点位 · 使用的工人 · 波次 · 有效宽度（例如“6/14 — 稳定在账户层级”）· 令牌 vs 单人基准估算 · 隔离项及原因 · 测试未覆盖的标记。格式+通俗用语：references/receipt.md。收据和提示使用用户的语言；技术术语保持原样。
可扇出性分类（侦查进行分类；工作现场不“中断”）
| 工作形态 | 模式 |
|---|---|
| 不重叠的点位（平面） | 完全并行波次——工人数 = 单元数（由下限/宽度限定） |
| 依赖链 | 拓扑排序波次 / 同一工人链式执行；完整链 = 流水线退化（保持隔离；诚实声明：无加速） |
| 全局不变量（术语表/风格/总数） | 先锁定不变量 → 将其放入共享摘要 → 最后执行一致性扫描门 |
| 整体质量（风格/架构） | 仅分析式集群；由你（唯一写入者）编写输出 |
| 副作用 | 通过提议不执行封闭——工人返回文本；副作用仅在同意的应用时触发 |
| 不可分解 | 诚实拒绝：“不可集群——单人/3个子任务” |
按领域的单元/不变量/门表格及模式详情：references/taxonomy.md。
钱包（单人基准不变量）
整个集群（侦查 + 工人 + 应用）的消耗应小于估算的主控单人成本——将单人预算分配给所有蚂蚁，而不是额外增加预算。因为工人不携带累积上下文（单人模式下后期单元会拖带全部历史；集群单元则不会），并且在 Claude Code 上，廉价层级每令牌成本更低。防护措施：(1) 共享摘要（侦查支付一次，分发）；(2) 最小单元下限（过小单元合并）；(3) 工人无自重试——仅由日志 + 最多一次重新生成剩余部分（无重试风暴）。bandwidth 与钱包正交：它控制预算消耗的速度，而非总量。
日志（按工人返回）
记录每个工人生成时分配的范围及其返回的订单——返回的订单落地即安全。死亡/停止/静默的工人 → 根据日志中未完成的剩余部分重新生成一个全新工人（绝不重启整个流程，绝不循环）。日志同时用于生成收据和部分报告。
组合（规则优先绑定，此处绑定）
- CoalBoard 在错误不允许通道上胜出（安全/加密、数据库/财务迁移、高精度）：关键工作通过共识而非吞吐量完成；CoalFace 可能作为 CoalBoard 的应用后处理器。
- CoalTipple（如果已安装）：每个工人的委派降级分层 = 可选的增强功能；其敏感门被继承——敏感单元的工人保持主控层级。
- 子代理安全性完整继承： 有界扇出 · 无僵尸 · 预算门 · 失败的工人返回信息供你重新路由 · 叶子不获得生成工具。
- 用户/项目通用规则（例如翻译规则）= 不变量：侦查将其读取到共享摘要中；工人从不选择规范已确定的内容。
- 引擎： 若平台存在工作流/编排引擎 → 使用它；否则使用原生代理工具波次。
嵌套指挥（深度说明）
深度为1的子任务自身可以充当指挥（侦查 → 契约 → 质量控制 → 对其范围应用），生成深度为2的工人。绝不更深：深度超过2时生成会扁平化为独立的、不可回收的顶层会话。工人是结构性叶子——深度为2的节点没有理由生成。钱包沿链向下分片（你为子任务分配一个分片；它再在其工人间分配）；收据向上流动。
平台（跨代理）
通过平台的原生子代理工具生成（Claude Code Agent/Task · 每个平台有其自己的工具）。任何支持并发子代理的平台均可运行完整契约；宽度通过 bandwidth 适应本地上限；未知平台使用保守默认值。完全没有扇出能力 → 退化为同一契约下的顺序流水线（侦查 → 按序单元 → 质量控制 → 应用）——绝不中断。对于你尚未实际运行过集群的平台/版本，将宽度/嵌套行为视为未验证——保守降级并明确说明。
配置 + 自更新
合并配置：全局 ~/.claude/.coalface.json 被最近的项目 .coalface.json 覆盖（每个键项目优先；查找会在家目录停止）。键：coalfaceMode · bandwidth · autoFanoutFloor · updateMode · updateCheckDays——所有数值在读取时会被钳制。自更新为类型1：钩子仅安排节流检查；/coalface:update 在线验证并弹出更新选项，需用户同意。
自我错误报告
如果 CoalFace 行为异常——指令矛盾、集群循环、工人违反契约——停止、总结情况并提供选项上报到 github.com/TheColliery/CoalFace/issues。绝不自动提交；绝不包含未经批准的代码或路径。此机制仅针对模型注意到的错误触发——干净运行意味着“未注意到问题”，而非“没有错误”。