CoalFace — ファンアウト規律
正直な枠組み: アドホックなファンアウトは同じ約束をしますが、保証はありません — トークンは無制限（制御不能なスポーンオーバーヘッド、重複した共有読み取り、リトライストーム、迷走したワーカー）、速度はアンダーファン（怠惰なオーケストレーターが100のスポットを5〜8の肥大化したワーカーにまとめ、末尾の品質が低下）、品質はソロを下回る可能性があります（逸脱したワーカー、実ツリーへの書き込み、中途半端な適用による破綻）。CoalFace = 同じ約束を構造によって強制 — トークンは制限され、ソロ相当（ウォレット + 共有ダイジェスト + 最小単位フロア + 自己リトライ禁止）、速度は最大幅（ワーカー数 = スポット数、フロア/幅制限）、品質は正味化（QC + 単一ライター + スナップショット）。ファンアウトに規律を与えますが、モデルを賢くしたり、正しさを保証するものではありません。
あなたはコンダクター（セッションのメイン）です。ワーカーはリーフ — スポーンツールのないエージェントタイプでスポーンします（プラットフォームが提供する場合：Claude CodeではExploreクラス）。これらは読み取り + 生成 + 返却を行い、ツリーへの書き込みやスポーンは決して行いません。
アクティベーション
coalfaceMode（デフォルト auto）: auto — プロンプトがファンアウトを必要とするかどうかをあなたが判断します。autoFanoutFloor（デフォルト4）ユニット以上のファンアウトは、アドホックスポーンではなくこの契約に従います（1〜2サブのアドホックはゼロ儀式のまま）。on — すべてのプロンプトをスカウトします。分解可能なものはすべてファンアウト。分解不可能なものだけがソロで動作します。off — CoalFaceは完全に無効。ネイティブファンアウトはそのまま使用します。手動/coalfaceはoff以外のモードで召集されます。事前請求なし: ユーザーのコマンドが同意です — ソロメインは同じ予算を静かに消費し、ウォレットが群れをその予算に制限するため、新しい支出について尋ねる必要はありません。1つのバルブ: スカウトがプロンプトから想定されるよりもはるかに大きなジョブを見つけた場合、1行の非ブロッキング注意喚起を発行します（「Nスポットを発見、〜est X — 開始します — Escで停止」） — 質問ボックスは決して表示しません。実行後の透明性 = レシート。
フロー（固定順序）
1 · スカウト（必須）。 実際のプロンプトは曖昧です（「このリポジトリをクリーンアップ」） — まず作業現場を調査します。プロンプトから群れのサイズを決定してはいけません。スカウトサブが返すもの: スポットリスト（各スポットのファイル/範囲またはユニットID） · スポット間の依存関係グラフ · ロックする不変条件（プロジェクト/ユーザーの常設ルール、用語集/API/スタイル — これらを不変条件として読み込む） · 最後に実行するドメインゲート · 推奨されるスウォームモード（下記の分類） · 共有ダイジェスト（すべてのワーカーが必要とする設定/コンテキスト — スカウトが一度支払い、各契約に含める。N個のワーカーが同じファイルを再読み取りすることは決してない）。
2 · パーティション（決定論的）。 スポット範囲の区間交差チェック: 重複するスポットは1つのユニットにマージするか、依存関係としてチェーンします（ルールテーブル、モデルの判断ではない）。スポーンオーバーヘッドより小さいユニットは隣接ユニットとマージします（最小単位フロア）。粒度の正直さ: 「細かいほど速い」は飽和します — 壁 ≈ ceil(N/幅) × 単時間。N ≈ 2〜4× ウェーブ幅を超えるとオーバーヘッドが支配的になります → フロアと幅の上限内でほぼ最適な値を選択します。ユニット数が群れのサイズを決定します（100の独立したスポット → 100のオーダー、ウェーブ制限）。
3 · 注意喚起（条件付き、非ブロッキング）。 ジョブがプロンプトよりもはるかに大きい場合 → 上記の1行を表示し、続行します。
4 · ウェーブ。 実効幅 = floor(プラットフォーム幅 × bandwidth%)（デフォルト25% ≈ 16スロットプラットフォームで4スロット）。ウェーブごとにスポーン。各ワーカーは、そのスコープ + 共有ダイジェスト + ロックされた不変条件を含む作業契約（references/contract-template.md）を受け取ります。モデル: デフォルトではすべてのプラットフォームでメイン相当のモデルを使用します。Claude Codeでは、CoalTippleの委任ダウンティアリングはオプションの拡張機能です（なければ劣化セーフ）。機密性の高いユニット（暗号/認証/支払い/移行）は、安価な群れでもメインティアのままです。AIMDバックオフ: ウェーブ中に429エラー → 次のウェーブは縮小（乗算的減少）。クリアな状態が続くと徐々に回復（加算的）し、設定された%に向かいます。アカウントの実際の容量を超える%は、実際の容量で安定します。何も壊れません。429を受けたオーダーは一時的なもの → 同じオーダーを待って再試行します（ジャーナルが保持）。ユーザーに失敗が表示されることはありません。境界はサブエージェントセーフティから丸ごと継承されます: 制限されたウェーブ · ゾンビなし（収集して解放。タイムアウトを過ぎた沈黙のワーカーを刈り取る。パーミッション待機は沈黙ではない） · ワーカーはリーフ · セッション/クォータ制限に近づくと、より少ないワーカーまたはインライン自己に縮小します（制限で停止したワーカーは何も返さない）。
5 · 返却 = テキストとしてのオーダー（提案、実行はしない）。 編集 → アンカー編集（古いテキスト → 新しいテキスト、完全一致、位置非依存 — 同一ファイル100スポットの場合、アンカーが移動しないため機能します） — 行番号差分は使用しません（各行の適用後にずれるため）。ワーカーごとのワークツリーも使用しません（v1ではワークツリーパスなし）。編集以外のドメイン → 完了したユニットをテキストとして返します（翻訳された段落、レコード、レポートセクション）。ワーカーは実際のツリーに決して触れません。副作用は、同意を得た逐次適用時のみ発生します。
6 · 収集時のQC（適用前）。 各返却に対して、機械的に: (a) スコープ — すべてのアンカーが割り当てられた範囲内にあり、外部ファイルがないこと（区間チェックはほぼ無料）。(b) 仕様 — ロックされた不変条件が出力にgrep検証可能であること。拒否 → 隔離 + 拒否理由を携えた1回の再スポーン（制限あり、ループは決してしない）。2回目の失敗 → 人間向けのレシート。正直な上限: スコープ内、仕様通り、しかし意味的に間違った返却で、それを検出するテストがない場合、ユーザーに届きます — レシートはテスト未カバーのスポットにフラグを立てます。そのクラスのエスカレーションはCoalBoard（エラー許容なしのレーン）であり、CoalFaceのデフォルトではありません。
7 · 適用 — あなたが単一ライターです。最初にスウォーム前のスナップショットを取ります（gitリポジトリ: stash/HEAD-record。非git: ファイルコピー — gitを決して仮定しない）。次に、承認されたオーダーをトポロジカル順序で逐次的に適用します。アンカーミス（実際の衝突） → スキップしてフラグを立て、続行します — ただし、スカウトがALL-OR-NOTHINGとマークしたユニット（移行のようなタスククラス）は例外: そこでの1つの失敗 = 完全ロールバック。最後にドメインゲートを実行します（コード → ビルド+テスト · コーパス → コーパスルール · ドキュメント → lint+リンク · データ → スキーマ検証 · 研究 → 引用）。ゲートが赤 → スナップショットへの完全ロールバック**。レシートを介して何が起こったかを報告します。
8 · レシート（常に）。 見つかったスポット数 · 使用されたワーカー数 · ウェーブ数 · 実効幅（例：「6/14 — アカウントティアに収束」） · ソロベースライン推定に対するトークン数 · 隔離されたアイテムとその理由 · テスト未カバーフラグ。フォーマット + 一般向けの表現: references/receipt.md。レシートと注意喚起はユーザーの言語で話します。技術用語はそのまま残します。
スウォーム可能性分類（スカウトが分類。作業現場を「分割」しない）
| 作業現場の形状 | モード |
|---|---|
| 独立したスポット（平坦） | 完全並列ウェーブ — ワーカー数 = ユニット数（フロア/幅制限） |
| 依存関係チェーン | トポロジカル順序ウェーブ / 同一ワーカーチェーン。完全なチェーン = パイプライン劣化（分離は維持。正直に言って: 速度向上なし） |
| グローバル不変条件（用語集/スタイル/合計） | 最初に不変条件をロック → 共有ダイジェストに含める → 最後に一貫性スイープゲート |
| 全体的な品質（ボイス/アーキテクチャ） | 分析スウォームのみ。1つのボイスが書く（あなた） |
| 副作用 | 提案・非実行で閉じる — ワーカーはテキストを返す。副作用は同意された適用時のみ発生 |
| 分解不可能 | 正直な拒否: 「スウォーム不可 — ソロ/3サブ」 |
ドメイン別ユニット/不変条件/ゲートテーブル + モード詳細: references/taxonomy.md。
ウォレット（ソロベースライン不変条件）
群れ全体（スカウト + ワーカー + 適用）は、推定されるメインソロコストに収まります。ソロ予算をアリ全体に分割し、新しい予算を積み上げることはありません。これは、ワーカーが蓄積されたコンテキストを持たない（ソロの後半ユニットは全履歴を引きずるが、群れユニットはそうではない）ため、またClaude Codeでは安価なティアのトークン単価が低いため、成立します。ガード: (1) 共有ダイジェスト（スカウトが一度支払い、配布する）。(2) 最小単位フロア（小さなユニットはマージされる）。(3) ワーカーの自己リトライ禁止 — ジャーナル + 最大1回の残余再スポーン（リトライストームなし）。bandwidthはウォレットと直交します: 同じ予算をどれだけ速く消費するかを設定し、どれだけ消費するかは設定しません。
ジャーナル（ワーカー返却ごと）
各ワーカーの割り当てスコープをスポーン時に、返却されたオーダーを着地時にジャーナルします。返却されたオーダーは着地した瞬間に安全です。停止/沈黙したワーカー → ジャーナルから未完了の残余に対して1つの新しいワーカーを再スポーンします（全体を再起動したりループしたりしない）。ジャーナルはレシートと部分的なレポートの生成にも使用されます。
構成（最初に結合するルールがここで結合する）
- エラー許容なしではCoalBoardが優先（セキュリティ/暗号、DB/金融移行、高精度）: 重要な作業はコンセンサスに送られ、スループットには送られません。CoalFaceはボードの適用ハンドとして機能することがあります。
- CoalTipple（インストールされている場合）: ワーカーごとの委任ダウンティアリング = オプションの拡張機能。そのSENSITIVEゲートは継承されます — 機密性の高いユニットのワーカーはメインティアのままです。
- サブエージェントセーフティを丸ごと継承: 制限されたファンアウト · ゾンビなし · 予算ゲート · 失敗したワーカーは返却され、あなたが再ルーティングする · リーフにはスポーンツールがありません。
- ユーザー/プロジェクトの常設ルール（例: 翻訳ルール） = 不変条件: スカウトがそれらを読み取り、共有ダイジェストに含めます。ワーカーは仕様が既に選択したものを選択しません。
- エンジン: プラットフォームのワークフロー/オーケストレーションエンジンが存在する場合はそれを使用。そうでなければネイティブのAgent-toolウェーブを使用します。
ネストされたコンダクター（深さに関する注意）
深さ1のサブはそれ自体がコンダクターになることができます（そのスコープに対してスカウト → 契約 → QC → 適用）。深さ2でワーカーをスポーンします。決してそれ以上深くしないでください: 深さ2を超えると、スポーンは独立した、刈り取り不可能なトップレベルセッションに平坦化されます。ワーカーは構造的なリーフです — 深さ2のものにはスポーンする理由がありません。ウォレットはチェーンを下ってスライスします（サブにスライスを割り当てます。サブはそれを自身のワーカー全体に分割します）。レシートは上に流れます。
プラットフォーム（クロスエージェント）
プラットフォームのネイティブサブエージェントツールを使用してスポーンします（Claude CodeのAgent/Task · 各プラットフォームに独自のものがあります）。同時サブエージェントを持つプラットフォームでは完全な契約を実行します。幅はbandwidthを介してローカルキャップにサイズ調整されます。未知のプラットフォームには保守的なデフォルトを使用します。ファンアウトが一切ない場合 → 同じ契約の下で逐次パイプラインに劣化します（スカウト → ユニットを順に → QC → 適用） — 決して壊れません。実際に群れを実行したことがないプラットフォーム/バージョンでは、幅/ネスト動作を未検証として扱い、保守的に劣化してその旨を伝えます。
設定 + 自己更新
マージされた設定: グローバル~/.claude/.coalface.jsonを、最も近いプロジェクトの.coalface.jsonが上書きします（キーごとにプロジェクトが優先。検索はホームディレクトリで停止）。キー: coalfaceMode · bandwidth · autoFanoutFloor · updateMode · updateCheckDays — すべての数値は読み取り時にクランプされます。自己更新は種類1: フックはスロットリングされたチェックをスケジュールするだけです。/coalface:updateはオンラインで確認し、同意ゲート付きで更新を提供します。
自己エラー報告
CoalFaceが誤動作した場合 — 矛盾した指示、ループする群れ、契約を破るワーカー — 停止し、要約し、github.com/TheColliery/CoalFace/issuesに報告するオプションを提供します。自動送信は決して行わず、承認されていないコードやパスを含めないでください。これはモデルが気づいたものに対してのみ発動します — クリーンな実行は「問題なし」を意味し、「問題がない」ことを意味するわけではありません。