@dogfood-lab/study-swarm 0.6.0 → 1.1.0

package/README.ja.md

@@ -13,79 +13,120 @@
   <img src="https://img.shields.io/badge/cited%20research-verified-1f6feb" alt="Cited research, verified">
 </p>
 
-**調査で引用された研究に基づいて設計上の決定を行い、その後、その決定が公式なものになる前に、*別の*モデルファミリーを使用して引用を検証します。**
+**引用された研究に基づいて設計上の決定を行い、その後、そのすべての内容が公式なものになる前に、*別の*モデルファミリーを使用して引用を検証する。**
 
-`study-swarm`はツールではなく、プロトコルです。大規模言語モデル（LLM）を使用して重要な設計上の決定を行う場合（新しい製品レイヤー、アーキテクチャの選択、「ここでモデルを信頼すべきか」という判断など）に、即興で進めるのではなく、既存の知識に基づいて設計を進めると、時代遅れの設計になったり、存在しない情報源や、あなたが考えていることとは異なる内容の情報源に基づいて設計が進んでしまう可能性があります。`study-swarm`は、これらの問題を解決します。複数の研究エージェントを並行して実行し、特定の引用された情報を要求し、設計に影響を与える前に、すべての引用を**異なるモデルファミリーの外部検証者**を通じて検証します。
+`study-swarm`はツールではなくプロトコルである。大規模言語モデル（LLM）を用いて重要な設計上の決定を行う場合（新しい製品レイヤー、アーキテクチャの選択、「ここでモデルを信頼すべきか」という判断など）、最初の原則から即興で進めることは、時代遅れの設計につながり、記憶に基づいて論文を引用することは、存在しない情報源や、あなたが考えていることとは異なる内容の情報源に依存する設計につながる。`study-swarm`はこれら両方を置き換える：並行して研究エージェントを派遣し、特定の引用された調査結果を要求し、すべての引用を**別のモデルファミリーの外部検証者**を通じてゲートすることで、その情報が設計に影響を与えるようにする。
 
-これは、自らその方法を実践しています。このプロトコルでは、設計を支援するシステムに対して、検証者によって保護された情報を提供するように規定されており、そのため、このプロトコル自体にもそれを適用します。**プロトコルを実行しているモデルであっても、自分の宿題を評価することはできません。**
+それは独自の治療法を適用する。このプロトコルは、支援するシステムの設計において、検証者によって保護されたエンベロープを規定するため、それ自体にもそれを適用する。**プロトコルを実行しているモデルを含め、どのモデルも自分の宿題を評価しない。**
 
-## プロトコルの5つのステップ
+## 5つのステップで構成されるプロトコル
 
-1. **特定する**：経験的な証拠によって回答が変わる可能性のある、3〜5個の重要な設計上の質問を特定します。
-2. **実行する**：各質問に対して、1つの研究エージェントを並行して実行します。各エージェントは、論文のタイトル、著者、発表年、URL、および1文の結論を返します。広範囲にわたる情報よりも、具体的な情報を提供します（「6〜8件の信頼できる情報源が、20件の曖昧な情報よりも優れている」）。
-3. **統合する**：得られた情報を「研究による裏付け」セクションに統合します。`N. **<結論>.** <著者> <年> (<arXiv/DOI>). <設計への影響>.`
-4. **外部で検証する**：*別のモデルファミリー*（推論機能を削除したもの）を使用して、すべての引用を2つの段階で検証します。まず、**検索エンジン**が論文が存在することを確認します（モデルの記憶ではなく）。次に、**妥当性検証**ツールが、結論が情報源と一致することを確認します。**捏造または誤った引用が見つかった場合は、処理を停止します。検証者または検索エンジンが利用できない場合は、処理を停止し、エスカレーションします（情報がないことを「引用は問題ない」と解釈しないでください）。**
-5. **関連付ける**：各アーキテクチャの選択を、番号を使用して結論と関連付けます。設計への影響がない引用はノイズです。
+1. **特定する**：経験的証拠によって回答が変わる可能性のある3〜5個の重要な設計上の質問を特定する。
+2. **派遣する**：各質問に対して、並行して1つの研究エージェントを派遣する。それぞれが論文タイトル＋著者＋年＋URL＋1文の調査結果を返す必要がある（網羅性よりも具体性を重視：「6〜8件の信頼できる調査結果は、20件の曖昧な記述よりも優れている」）。
+3. **統合する**：調査結果を「研究による根拠」セクションに統合する：`N. **<調査結果>.** <著者> <年> (<arXiv/DOI>). <設計への影響>.`
+4. **外部で検証する**：*別のモデルファミリー（推論機能を削除したもの）が、2つの段階ですべての引用をチェックする。まず、**検索オラクル**が論文が存在することを確認する（モデルの記憶ではなく）。次に、「根拠」レンズが、調査結果が情報源と一致することを確認する。**捏造または誤った帰属の場合、処理を停止する。検証者または検索オラクルが利用できない場合は、処理を停止してエスカレーションする（不在を「引用は問題ない」と解釈しないこと）。
+5. **関連付ける**：各アーキテクチャの選択を、番号を使って調査結果に関連付ける。設計への影響がない引用はノイズである。
 
-完全な実行可能な詳細（停止テーブル、情報源の標準、アンサンブルルール）は、**[PROTOCOL.md](PROTOCOL.md)**にあります。
+完全な実行可能な詳細（停止テーブル、情報源に関する標準、アンサンブルルール）は、**[PROTOCOL.md](PROTOCOL.md)**に記載されている。
 
-## なぜ*別の*モデルファミリーで、推論機能を削除する必要があるのでしょうか？
+## なぜ*別の*ファミリーで、推論機能を削除する必要があるのか？
 
-なぜなら、失敗のパターンは、仮説ではなく、実際に確認されているからです。
+それは、失敗モードが仮説ではなく、文書化されているためである：
 
-- **LLMは、自分の出力を確実に検証できません。** Huang et al. 2023 ([arXiv:2310.01798](https://arxiv.org/abs/2310.01798)); Kambhampati et al. 2024 ([arXiv:2402.01817](https://arxiv.org/abs/2402.01817), LLM-Modulo); Stechly et al. 2024 ([arXiv:2402.08115](https://arxiv.org/abs/2402.08115)) — 外部検証者がメリットをもたらします。自己批判的な内容は、効果がありません。
-- **同じファミリーのモデルは、自分を高く評価します。** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — 自己認識は、自己評価と*線形に*相関するため、部分的なブラインド処理だけでは役に立ちません。Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — 異なるファミリーのモデルで構成されたパネルの方が、偏りが少なく、コストも約7分の1で済みます。
-- **LLMは、引用で嘘をつきます。** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — GPT-3.5の55％、GPT-4の18％の引用が捏造されています。Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — リンクは94％以上の確率で解決されますが、引用されたコンテンツの39〜77％しか、実際に主張を裏付けていません。したがって、存在は**検索によって確認する必要があり、記憶に頼るべきではありません。**
-- **生成者の推論を隠します。** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — 操作された推論のみでは、判断者の誤検出率が最大90％まで増加します（ただし、アクションは固定されています）。Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — 推論は、事後的な合理化です。検証者は、単なる引用の主張のみを確認し、その「なぜこの情報を追加したのか」という理由は確認しません。
-- **多様性は、数よりも重要です。** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — ペアごとの相関関係がρ∈[0.05, 0.25]の4つの検証者が、単一の検証者よりも、サブモジュールカバレッジによって優れています。Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — LLMのエラーは*相関しているため、重要な変数は、生の数ではなく、レンズの多様性です。
+- **LLMは、自分の出力を確実に検証できない。** Huang et al. 2023 ([arXiv:2310.01798](https://arxiv.org/abs/2310.01798)); Kambhampati et al. 2024 ([arXiv:2402.01817](https://arxiv.org/abs/2402.01817), LLM-Modulo); Stechly et al. 2024 ([arXiv:2402.08115](https://arxiv.org/abs/2402.08115)) — 外部検証者がメリットをもたらす。自己批判的な内容は効果がない。
+- **同じファミリーの評価者は、自分を高く評価する傾向がある。** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — 自己認識は、自己選好と*線形に*相関するため、部分的なブラインド処理では効果がない。Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — 異なるファミリーのパネルを使用すると、約7分の1のコストで偏りが少なくなる。
+- **引用は、LLMが嘘をつく場所である。** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — GPT-3.5の55％、GPT-4の18％の引用が捏造されている。Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) —リンクは94％以上の確率で解決するが、引用されたコンテンツのわずか39〜77％しか主張を裏付けていない。したがって、存在は**検索によってチェックする必要があり、想起によってチェックしてはいけない。**
+- **生成者の推論を隠す。** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — 操作された連鎖思考だけでは、評価者の誤検出率が最大90％まで増加する（アクションは固定されている）。Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — CoTは、事後的な合理化である。検証者は、単なる引用の主張のみを確認し、「なぜこれを含めたのか」は確認しない。
+- **多様性は数よりも重要である。** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — ペアワイズ相関ρ∈[0.05, 0.25]の4つの検証者は、サブモジュールカバレッジによって、いずれか1つの優れた評価者よりも優れている。Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — LLMのエラーは*相関しているため、重要な変数はレンズの多様性であり、生の数ではない。
 
-## 実際に機能するのでしょうか？（証拠）
+## 実際に機能するのか？（証拠）
 
-テストとして、このプロトコルを自分の引用に対して実行しました。2つの相関性の低い、Claude以外のモデル（**Mistral** (`mistral-small:24b`)と**IBM Granite** (`granite4.1:30b`)）を使用して、推論機能を削除した状態で、2つのブラインドトラップを仕込んだ引用セットを検証しました。
+テストとして、このプロトコルを自分の引用に対して実行した。2つの非相関性の高いClaude以外のファミリー（**Mistral** (`mistral-small:24b`)と**IBM Granite** (`granite4.1:30b`））を使用して、推論機能を削除し、2つのブラインドトラップで設定された引用セットをチェックした。
 
-| 仕掛けられたトラップ | Mistral | IBM Granite | 真実 |
+| 仕掛けられた罠 | Mistral | IBM Granite | 真実 |
 |---|---|---|---|
-| 「Nakamura & Olsen」に帰属された推論 | 見逃された | **検出された**（誤って帰属された → 実際にはWei et al. 2022） | 誤って帰属された |
-| 「98％のエラーが解消され、オラクルは不要」という捏造された論文 | **caught** (fabricated) | **caught** (fabricated) | 捏造された |
+| 「Nakamura & Olsen」に帰属された連鎖思考プロンプト | 見逃した | **検出（誤った帰属→実際にはWei et al. 2022、arXiv:2201.11903）** | 誤って帰属された |
+| 「98％のエラーが除去され、オラクルは不要」という捏造された論文 | **caught** (fabricated) | **caught** (fabricated) | 捏造された |
 
-どちらのモデルも、単独では両方のトラップを検出できませんでしたが、**両方のモデルを組み合わせることで、2/2を検出しました。** 単一の判断者では、誤った帰属を検出できなかったでしょう。別途、検索エンジンは、当社の設計ドキュメントにある2つの*実際の*誤った帰属（間違った最初の著者に帰属された論文）を検出しました。これらの誤りは、パラメトリックLLMでは検出できなかったでしょう。また、両方のLLMが、トレーニングデータ以降に発表された論文を捏造されたものとして誤ってフラグを立てたのに対し、検索エンジンは、これらの論文が実際に存在することを正しく確認しました。この最後の点が、ステップ4の存在チェックが**検索エンジンである必要があり、LLMであってはならない**理由です。
+どちらのファミリーも単独では両方の罠を検出できなかったが、**それらの組み合わせで2/2を検出した。** 単一の評価者は、誤った帰属を認めてしまうだろう。別途、検索オラクルは、当社の設計ドキュメントにある2つの*実際の*誤った帰属（間違った最初の著者に引用された論文）を検出し、どのパラメトリックLLMも検出できなかった。また、両方のLLMが、トレーニング後の論文であるという理由だけで、捏造されたと誤ってフラグを立てた真の2026年の論文を正しく確認した。最後の点は、ステップ4の存在チェックが**検索オラクルでなければならず、LLMであってはならない**という理由そのものである。
 
-この単一の実行は、ミニチュア版の論文です。**相関性の低いレンズと、存在を確認するための検索エンジンを組み合わせることで、単一の優れた判断者よりも優れた結果が得られます。**
+この単一の実行は、ミニチュア版の論文である：**相関性の低いレンズ＋存在を検証するための検索オラクルは、優れた評価者よりも優れている。**
+
+### …そして再び、v1.1の設計のために
+
+v1.1の改良は、同じ方法で選択された。つまり、「study-swarm」上で「study-swarm」を実行することによってだ。最初のリリースで「おそらく」という回答になった4つの質問（根拠チェックをどのように*機械化*するか、生成時に根拠を示すべきか、レンズをどのように*組み合わせるか、不確実性の評価において保留すべきかどうか）は、並行して研究を行うエージェントに割り当てられ、得られた**27件の参考文献**はすべて、設計に反映される前にステップ4で検証された。検索オラクルは、**27/27件が存在すること**を確認した。これには、パラメトリックモデルが捏造されたものとして誤ってフラグを立てるであろう6つの2025〜2026年の論文も含まれており、また、モデルでは確認できなかった5つの参考文献の帰属についても修正が行われた。その中には、研究エージェント自身が指摘した実際の最初の著者の誤った帰属も含まれている。推論を排除して実行すると、根拠を示すためのレンズは、私たちのシステムで文書化された自身の失敗モードを再現する。つまり、1つの論文を自信を持って誤って分類し、その*不一致*がエスカレーションを引き起こす。これはまさにカスケードで規定されていることだ。実際に動作するシステムは、[`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md)として提供される。このシステムで根拠が示された改良点（分解/三項の根拠、生成時の根拠、オラクルによって制御されるカスケード、および校正された保留）は、[PROTOCOL.md](PROTOCOL.md)に記載されている。
 
 ## その仕組み
 
-このプロトコルを手動で実行することもできます。異なるモデルファミリーのモデルと、自分でarXiv/DOIを解決することで、ステップ4を満たすことができます。2つの関連ツールを使用すると、1つのコマンドで実行できます。
+このプロトコルを手動で実行することもできる。異なるモデルと、arXiv/DOIを自分で解決することでステップ4を満たすことができる。2つの関連ツールを使用すると、これを1つのコマンドにまとめることができる。
+
+- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — 実行時の検証ツール：異なるモデルファミリーへのルーティング、推論を排除した処理、複数のレンズによる判断、決定的な検索の存在確認（arXiv → Crossref）、および署名されたレシート。
+- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** — `roleos verify-citations <dispatch>`コマンドを提供し、このコマンドはディスパッチから参考文献を抽出し、prismを通じて検証する。
 
-- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — 実行時検証ツール：異なるモデルファミリー間でのルーティング、推論の簡略化、多角的な判断、決定的な検索による存在確認（arXiv → Crossref）、および署名されたレシートを提供。
-- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** — `roleos verify-citations <dispatch>` を提供。このツールは、特定のドキュメントの引用を抽出し、それを prism を介して検証する。
+引き継ぎのプロセスは、ディスパッチ形式そのものである。`N. **finding.** Authors year (arXiv|DOI). implication.`という形式で記述された結果（**各結果に対して1つの解決可能な識別子**）が、`roleos verify-citations`によって読み込まれ、検証される。lintチェックに合格したディスパッチは、問題なく引き継がれる。形式が正しくない参考文献は、実行時に解析不能としてフラグが立てられる。この契約内容は、`study-swarm lint`によってローカルでチェックされるため、ステップ3とステップ4では、参考文献の定義について合意が得られる。
 
-## CLI
+## CLI（コマンドラインインターフェース）
 
 ```bash
 npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
 ```
 
-| コマンド | 機能 |
+| コマンド | その機能 |
 |---|---|
-| `study-swarm protocol` | 完全なプロトコル（5つのステップ、停止テーブル、情報源の基準）を出力します。 |
-| `study-swarm new <slug>` | 5つのステップのテンプレートを含む`<slug>.dispatch.md`を作成し、内容を記述できるようにします。 |
-| `study-swarm lint <file>` | ディスパッチの「調査根拠」を情報源の基準と照合し、すべての調査結果について、著者、年、および解決可能な識別子（arXiv / DOI / URL）が必要です。「研究によると…」といった曖昧な表現は認められません。違反があった場合は、エラーコード`1`を返し、CIの実行を停止します。 |
+| `study-swarm protocol` | 完全なプロトコル（5つのステップ、停止テーブル、ソースの標準）を表示する。 |
+| `study-swarm new <slug>` | 5つのステップで構成されたスケルトンを含む`<slug>.dispatch.md`ファイルを生成し、内容を埋めることができるようにする。 |
+| `study-swarm lint [--json] <path…>` | ディスパッチの*研究における根拠*をソース標準と比較してチェックする。すべての結果には、著者、年、および解決可能な識別子（arXiv / DOI / URL）が必要であり、「研究によると…」という曖昧な表現は拒否される。違反があった場合、終了コード1で処理が停止するため、CI（継続的インテグレーション）のゲートとして機能する。<path>はファイル、ディレクトリ（`*.dispatch.md`ファイルを再帰的にlintチェック）、またはstdinを表す`-`とすることができる。`--json`オプションを使用すると、機械可読形式のレポートが出力される。 |
+
+`lint`は決定的な処理であり、モデル呼び出しは行わないため、CI環境で安全に使用できる。ローカルで**ステップ3のソース標準**を適用する。モデルベースの**ステップ4**の検証は、[`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prismに委ねられる。
+
+典型的なループ：
 
-`lint`は決定的な処理であり、モデルへの呼び出しは行われないため、CI環境で安全に使用できます。ローカルで**ステップ3の情報源の基準**を適用します。モデルベースの**ステップ4**の検証は、引き続き[`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prismに委ねられます。
+```bash
+study-swarm new my-decision                      # creates my-decision.dispatch.md
+# …fill in the questions, run the research dispatch, write the findings…
+study-swarm lint my-decision.dispatch.md         # enforce the sourcing standard (Step 3)
+roleos verify-citations my-decision.dispatch.md  # model-based Step 4 (different family, via prism)
+```
+
+2つの完全で、lintチェックに合格した動作するディスパッチが参照として提供される：[`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md)（プロトコルの中心的な決定であり、簡潔）と[`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md)（完全なv1.1の設計パスであり、27件の参考文献があり、そのすべてが外部で検証されている）。
+
+### CI環境でのゲートとして使用する
+
+`lint`は、ファイル、ディレクトリ（`*.dispatch.md`ファイルを再帰的にlintチェック）、またはstdinを表す`-`を受け取り、`--json`オプションを使用すると、機械可読形式のレポートが出力される。これをリポジトリに組み込むことで、各PR（プルリクエスト）でディスパッチのソースを検証することができる（コピー＆ペーストできるサンプルは、[`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml)にも含まれている）。
+
+```yaml
+# .github/workflows/dispatches.yml
+name: study-swarm lint
+on:
+  pull_request:
+    paths: ['**/*.dispatch.md', '.github/workflows/dispatches.yml']
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
+```
 
-## なぜ機能するのか（簡潔に）
+## その仕組みを簡潔に説明する
 
-**現状** — この分野は急速に進展しており、特定の研究を数年かけて行うと、設計が18か月遅れてリリースされることになる。**機能性** — 証拠は、何が「機能する」かだけでなく、何が「機能しない」かを示す（説明が、誤ったAIへの過度な依存を招く可能性がある — Bansal et al. 2021）。**安全性** — 検証ツールによって保護された範囲は、証拠によって裏付けられるアーキテクチャであり、プロトコルはそれを自身の出力に適用する。情報源の提示は、学術的なパフォーマンスではなく、証拠の追跡である。
+**最新性** — この分野は急速に進展しているため、特定の研究と年を指定することで、設計が18か月遅れて公開されるのを防ぐことができる。**機能性** — 証拠は、何が*成功するか*だけでなく、何が*失敗する*かを示す（説明は、*間違った*AIへの過度の依存を高める可能性がある—Bansal et al. 2021、[arXiv:2006.14779](https://arxiv.org/abs/2006.14779)）。**安全性** — 検証ツールによって保護された範囲は、証拠が裏付けるアーキテクチャであり、プロトコルはその出力を強制する。ソースの明示は学術的な儀式ではなく、証拠の追跡である。
 
 ## セキュリティ
 
-`study-swarm` は、ドキュメントのリポジトリであり、Markdown とロゴが含まれている。実行可能なコードは含まれておらず、このリポジトリから何もインストールされない。データにアクセスせず、権限を必要とせず、テレメトリも収集しない。ソースコードには、秘密情報や認証情報は含まれていない。この手法は、Web検索とモデルベースの検証を使用するワークフローを「記述」しているが、このリポジトリはそれを実装または実行するものではない。詳細は [SECURITY.md](SECURITY.md) を参照。
+`study-swarm`は、**軽量で依存関係のないCLI（コマンドラインインターフェース）** (`study-swarm`)と、その方法論を組み合わせて提供する。**ネットワークまたはモデルへの呼び出しは行わず**、**テレメトリも収集しない**。ソースコードには秘密や認証情報は含まれていない。実行時には、`lint`に渡されたファイルのみを読み取り、現在のディレクトリに単一の`<slug>.dispatch.md`ファイルを書き込む（上書きはせず、作業ディレクトリ外には書き込まない）。方法論で説明されているモデルベースの検証（ステップ4）は、このパッケージではなく、関連ツールによって実行される。詳細は[SECURITY.md](SECURITY.md)を参照のこと。
 
 ## ステータス
 
-動作するプロトコルであり、その独自の仕組みによって外部から検証されている。異なるモデルファミリーがその引用をチェックする（上記の証明を参照）。このリポジトリは、公開リファレンスであり、[PROTOCOL.md](PROTOCOL.md) が実行可能な形式である。これは、[dogfood-lab](https://github.com/dogfood-lab) ファミリーの一部であり、AI時代におけるビルドのための手法と事例を紹介する。
+動作するプロトコルであり、その独自のメカニズムによって外部で検証されている。異なるモデルファミリーがその参考文献をチェックしている（上記の証明を参照）。**v1.1**では、最初のリリースでは言及されていなかった点を強化している。具体的には、分解/三項の根拠、生成時の根拠、レンズを組み合わせるためのオラクル制御カスケード、および校正された保留である。これらの要素はすべて、検証済みのv1.1ディスパッチに基づいて根拠が示されている。このリポジトリは公開参照であり、[PROTOCOL.md](PROTOCOL.md)は実行可能な形式である。これは、[dogfood-lab](https://github.com/dogfood-lab)ファミリーの一部であり、AI時代における構築のための方法と事例を紹介するものである。
 
-MITライセンス。
+MITライセンスで提供される。
 
 ---
 

package/README.md

@@ -45,13 +45,17 @@ As a test, the protocol was run against its own citations. Two decorrelated non-
 
 | Planted trap | Mistral | IBM Granite | Ground truth |
 |---|---|---|---|
-| Chain-of-thought prompting attributed to "Nakamura & Olsen" | missed | **caught** (misattributed → really Wei et al. 2022) | misattributed |
+| Chain-of-thought prompting attributed to "Nakamura & Olsen" | missed | **caught** (misattributed → really Wei et al. 2022, arXiv:2201.11903) | misattributed |
 | a fabricated "98% of errors removed, no oracle needed" paper | **caught** (fabricated) | **caught** (fabricated) | fabricated |
 
 Neither family caught both traps alone — but their **union caught 2/2**. A single judge would have shipped the misattribution. Separately, the retrieval oracle caught two *real* misattributions in our own design docs (papers cited under the wrong first author) that no parametric LLM could have flagged — and it correctly confirmed genuine 2026 papers that both LLMs false-flagged as fabricated simply because the papers postdate their training. That last point is the whole reason Step 4's existence check **must** be a retrieval oracle, never an LLM.
 
 That single run is the thesis in miniature: **decorrelated lenses + a retrieval oracle for existence beat any one smart judge.**
 
+### …and again, to design v1.1
+
+The v1.1 refinements were chosen the same way — by running study-swarm **on study-swarm**. Four questions the first release left to "I think" (how to *mechanize* the groundedness check, whether to ground at generation time, how to *combine* the lenses, whether to abstain on calibrated uncertainty) went to parallel research agents, and all **27 resulting citations** were gated through Step 4 before any informed the design. The retrieval oracle confirmed **27/27 exist** — including six 2025–2026 papers a parametric model would have false-flagged as fabricated — and corrected five attributions a model could not, among them a real first-author misattribution the research agent flagged on itself. Run reasoning-stripped, the groundedness lenses even reproduced their own documented failure modes on our dispatch: one confidently mislabelled a real paper, and their *disagreement* triggered escalation — exactly as the cascade prescribes. The worked dispatch ships as [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md); the refinements it grounded — decomposed/ternary groundedness, generation-time grounding, the oracle-gated cascade, and calibrated abstention — are in [PROTOCOL.md](PROTOCOL.md).
+
 ## How it's wired
 
 You can run the protocol by hand — any different-family model plus resolving the arXiv/DOI yourself satisfies Step 4. Two sibling tools make it one command:
@@ -59,6 +63,8 @@ You can run the protocol by hand — any different-family model plus resolving t
 - **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — the runtime verifier: family-different routing, reasoning-stripped, multi-lens adjudication, a deterministic retrieval existence floor (arXiv → Crossref), and signed receipts.
 - **[role-os](https://github.com/mcp-tool-shop-org/role-os)** — provides `roleos verify-citations <dispatch>`, the runner that extracts a dispatch's citations and gates them through prism.
 
+The handoff is the dispatch format itself: a finding written as `N. **finding.** Authors year (arXiv|DOI). implication.` — with **one resolvable identifier per finding** — is exactly what `roleos verify-citations` lifts and gates. A `lint`-clean dispatch hands off cleanly; a malformed citation is what the runner flags as unparsed. That contract is what `study-swarm lint` checks locally, so Step 3 and Step 4 agree on what a citation is.
+
 ## CLI
 
 ```bash
@@ -69,21 +75,56 @@ npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-sw
 |---|---|
 | `study-swarm protocol` | Print the full protocol — the five steps, the halt table, the sourcing standard. |
 | `study-swarm new <slug>` | Scaffold a `<slug>.dispatch.md` with the five-step skeleton to fill in. |
-| `study-swarm lint <file>` | Check a dispatch's *Research grounding* against the sourcing standard — every finding needs an author, a year, and a resolvable identifier (arXiv / DOI / URL); "studies show…" hand-waving is rejected. Exit `1` on violations, so it gates CI. |
+| `study-swarm lint [--json] <path…>` | Check a dispatch's *Research grounding* against the sourcing standard — every finding needs an author, a year, and a resolvable identifier (arXiv / DOI / URL); "studies show…" hand-waving is rejected. Exit `1` on violations, so it gates CI. A `<path>` may be a file, a directory (linted recursively for `*.dispatch.md`), or `-` for stdin; `--json` emits a machine-readable report. |
 
 `lint` is deterministic — zero model calls — so it's safe in CI. It enforces **Step 3's sourcing standard** locally; the model-based **Step 4** verification still defers to [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
 
+A typical loop:
+
+```bash
+study-swarm new my-decision                      # creates my-decision.dispatch.md
+# …fill in the questions, run the research dispatch, write the findings…
+study-swarm lint my-decision.dispatch.md         # enforce the sourcing standard (Step 3)
+roleos verify-citations my-decision.dispatch.md  # model-based Step 4 (different family, via prism)
+```
+
+Two complete, lint-clean worked dispatches ship as references: [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) (the protocol's central decision, compact) and [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md) (the full v1.1 design pass — 27 citations, every one externally verified).
+
+### Gate it in CI
+
+`lint` takes a file, a directory (linted recursively for `*.dispatch.md`), or `-` for stdin, and `--json` emits a machine-readable report. Drop this into your repo to gate every dispatch's sourcing on each PR (a copy-paste sample also lives in [`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml)):
+
+```yaml
+# .github/workflows/dispatches.yml
+name: study-swarm lint
+on:
+  pull_request:
+    paths: ['**/*.dispatch.md', '.github/workflows/dispatches.yml']
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
+```
+
 ## Why it works, in one breath
 
-**Current** — the field moves fast; demanding specific studies-with-years keeps designs from shipping 18 months behind. **Functional** — evidence shows what *fails*, not just what works (explanations can increase over-reliance on *wrong* AI — Bansal et al. 2021). **Safe** — the verifier-protected envelope is the architecture the evidence supports, and the protocol enforces it on its own output. Sourcing isn't academic theater; it's the evidence trail.
+**Current** — the field moves fast; demanding specific studies-with-years keeps designs from shipping 18 months behind. **Functional** — evidence shows what *fails*, not just what works (explanations can increase over-reliance on *wrong* AI — Bansal et al. 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Safe** — the verifier-protected envelope is the architecture the evidence supports, and the protocol enforces it on its own output. Sourcing isn't academic theater; it's the evidence trail.
 
 ## Security
 
-`study-swarm` is a documentation repository — Markdown and a logo. It ships no executable code and installs nothing from this repo. It touches no data, requires no permissions, and collects no telemetry; there are no secrets or credentials in the source. The methodology *describes* a workflow that uses web retrieval and model-based verification, but this repo does not implement or run it. See [SECURITY.md](SECURITY.md).
+`study-swarm` ships a **thin, zero-dependency CLI** (`study-swarm`) alongside the methodology. It makes **no network or model calls** and collects **no telemetry**; there are no secrets or credentials in the source. At runtime it only reads the file you pass to `lint` and writes a single `<slug>.dispatch.md` in the current directory for `new` (refusing to overwrite, and never outside the working directory). The model-based verification the methodology describes (Step 4) is run by the sibling tools, not by this package. See [SECURITY.md](SECURITY.md).
 
 ## Status
 
-A working protocol, externally verified by its own machinery — a different model family checks its citations (see the proof above). This repo is the public reference; [PROTOCOL.md](PROTOCOL.md) is the executable shape. Part of the [dogfood-lab](https://github.com/dogfood-lab) family — methods and showcases for building in the AI era.
+A working protocol, externally verified by its own machinery — a different model family checks its citations (see the proof above). **v1.1** sharpens the verifier where the first release was silent: decomposed/ternary groundedness, generation-time grounding, an oracle-gated cascade for combining lenses, and calibrated abstention — each grounded in the verified v1.1 dispatch. This repo is the public reference; [PROTOCOL.md](PROTOCOL.md) is the executable shape. Part of the [dogfood-lab](https://github.com/dogfood-lab) family — methods and showcases for building in the AI era.
 
 MIT licensed.
 

package/README.pt-BR.md

@@ -13,51 +13,57 @@
   <img src="https://img.shields.io/badge/cited%20research-verified-1f6feb" alt="Cited research, verified">
 </p>
 
-**Baseie as decisões de design em pesquisas citadas — e, em seguida, verifique as citações com um *modelo diferente* antes que qualquer coisa se torne um padrão.**
+**Baseie as decisões de projeto em pesquisas citadas — e, em seguida, verifique as citações com um *modelo diferente* antes que qualquer coisa se torne parte do cânone.**
 
-`study-swarm` é um protocolo, não uma ferramenta. Ao tomar uma decisão de design importante com um LLM — uma nova camada de produto, uma escolha de arquitetura, uma decisão sobre "se devemos confiar no modelo aqui" — improvisar a partir de princípios básicos resulta em designs desatualizados, e citar artigos de memória resulta em designs que se baseiam em fontes que não existem ou que não dizem o que você pensa. O `study-swarm` substitui ambos: envie agentes de pesquisa em paralelo, exija descobertas específicas citadas e valide cada citação por meio de um **verificador externo de uma família de modelos diferente** antes que ela influencie o design.
+`study-swarm` é um protocolo, não uma ferramenta. Ao tomar uma decisão de projeto importante com um LLM — uma nova camada de produto, uma escolha arquitetural, uma decisão sobre "se devemos confiar no modelo aqui" — improvisar a partir de princípios básicos resulta em projetos desatualizados e citar artigos de memória leva a projetos baseados em fontes que não existem ou que não dizem o que você pensa. O `study-swarm` substitui ambos: ele envia agentes de pesquisa paralelos, exige descobertas específicas citadas e valida cada citação por meio de um **verificador externo de uma família de modelos diferente** antes que ela influencie o projeto.
 
-Ele aplica sua própria abordagem. O protocolo prescreve "envelopes" protegidos por verificadores para os sistemas que ele ajuda a projetar — portanto, ele executa um deles em si mesmo. **Nenhum modelo avalia seu próprio trabalho, incluindo o que executa o protocolo.**
+Ele aplica sua própria abordagem. O protocolo prescreve "envelopes" protegidos por verificadores para os sistemas que ele ajuda a projetar — portanto, ele executa um deles em si mesmo. **Nenhum modelo avalia seu próprio trabalho, incluindo o que está executando o protocolo.**
 
-## O protocolo em cinco etapas
+## O protocolo em cinco etapas:
 
-1. **Identifique** 3 a 5 questões de design cruciais, nas quais evidências empíricas mudariam a resposta.
+1. **Identifique** 3 a 5 questões de projeto cruciais, nas quais evidências empíricas mudariam a resposta.
 2. **Envie** um agente de pesquisa por questão, em paralelo. Cada um deve retornar títulos de artigos + autores + anos + URLs + uma descoberta em uma frase — especificidade em vez de amplitude ("6 a 8 descobertas bem fundamentadas superam 20 observações vagas").
-3. **Sintetize** as descobertas em uma seção de *Fundamentação da pesquisa*: `N. **<descoberta>.** <Autores> <ano> (<arXiv/DOI>). <implicação para o design>.`
-4. **Verifique externamente** — uma *família de modelos diferente*, sem raciocínio, verifica cada citação em duas etapas: um **oráculo de recuperação** confirma que o artigo existe (nunca a memória do modelo) e, em seguida, uma lente de **fundamentação** confirma que a descoberta corresponde à fonte. **Interrompa** se for fabricada/atribuída incorretamente; **interrompa e alerte** se o verificador ou o oráculo de recuperação não estiverem disponíveis (nunca interprete a ausência como "citações válidas").
-5. **Conecte** cada escolha arquitetônica a uma descoberta por número. Citações sem uma implicação para o design são ruído.
+3. **Sintetize** as descobertas em uma seção de *fundamentação da pesquisa*: `N. **<descoberta>.** <Autores> <ano> (<arXiv/DOI>). <implicação para o projeto>.`
+4. **Verifique externamente** — uma *família de modelos diferente*, sem raciocínio, verifica cada citação em duas etapas: um **oráculo de recuperação** confirma que o artigo existe (nunca a memória do modelo) e, em seguida, uma lente de **validação** confirma que a descoberta corresponde à fonte. **Interrompa** se for fabricada/atribuída incorretamente; **interrompa e alerte** se o verificador ou o oráculo de recuperação não estiverem disponíveis (nunca interprete a ausência como "citações válidas").
+5. **Conecte** cada escolha arquitetural a uma descoberta por meio de um número. Citações sem implicação para o projeto são ruído.
 
-Os detalhes completos e executáveis — a tabela de interrupção, o padrão de referência e a regra de conjunto — estão em **[PROTOCOL.md](PROTOCOL.md)**.
+Os detalhes completos e executáveis — a tabela de interrupção, o padrão de referência e a regra do conjunto — estão em **[PROTOCOL.md](PROTOCOL.md)**.
 
 ## Por que uma *família diferente*, sem raciocínio?
 
 Porque os modos de falha são documentados, não hipotéticos:
 
 - **Os LLMs não conseguem verificar de forma confiável sua própria saída.** Huang et al. 2023 ([arXiv:2310.01798](https://arxiv.org/abs/2310.01798)); Kambhampati et al. 2024 ([arXiv:2402.01817](https://arxiv.org/abs/2402.01817), LLM-Modulo); Stechly et al. 2024 ([arXiv:2402.08115](https://arxiv.org/abs/2402.08115)) — o verificador externo traz os benefícios; o conteúdo de autocrítica é inerte.
-- **Juízes da mesma família se auto favorecem.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — o auto reconhecimento se correlaciona *linearmente* com a auto preferência, portanto, o obscurecimento parcial não ajuda. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — um painel em famílias distintas é menos tendencioso, com um custo ~7 vezes menor.
-- **As citações são onde os LLMs mentem.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — 55% das citações do GPT-3.5 / 18% do GPT-4 são fabricadas. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — os links resolvem >94% das vezes, mas apenas 39–77% do conteúdo citado realmente sustentam a afirmação. Portanto, a existência deve ser verificada por **recuperação, não por recordação**.
-- **Oculte o raciocínio do gerador.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — a manipulação do raciocínio em cadeia, por si só, inflaciona os falsos positivos de um juiz em até 90%, com as ações mantidas fixas. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — o raciocínio em cadeia é uma racionalização *a posteriori*. O verificador vê apenas a afirmação da citação, nunca o "por que eu incluí isso".
-- **Diversidade supera a quantidade.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — quatro verificadores com correlação pareada ρ ∈ [0.05, 0.25] superam qualquer um deles por meio da cobertura submodular. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — os erros do LLM são *correlacionados*, portanto, a variável crucial é a diversidade das lentes, não a quantidade bruta.
+- **Juízes da mesma família se auto favorecem.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — o autorreconhecimento está correlacionado *linearmente* com a autopreferência, portanto, o bloqueio parcial não ajuda. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — um painel de famílias distintas é menos tendencioso, com um custo cerca de 7 vezes menor.
+- **As citações são onde os LLMs mentem.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — 55% das citações do GPT-3.5 / 18% do GPT-4 são fabricadas. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — os links resolvem >94% das vezes, mas apenas 39–77% do conteúdo citado realmente sustentam a afirmação. Portanto, a existência deve ser verificada por meio de **recuperação, não de recordação**.
+- **Oculte o raciocínio do gerador.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — a manipulação da cadeia de pensamento sozinha aumenta os falsos positivos de um juiz em até 90%, com as ações mantidas fixas. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — a cadeia de pensamento é uma racionalização *a posteriori*. O verificador vê apenas a afirmação da citação, nunca o "por que eu incluí isso".
+- **A diversidade supera a quantidade.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — quatro verificadores com correlação de pares ρ ∈ [0,05, 0,25] superam qualquer um deles por meio da cobertura submodular. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — os erros do LLM são *correlacionados*, portanto, a variável crucial é a diversidade das lentes, não a quantidade bruta.
 
 ## Ele realmente funciona? (prova)
 
-Como teste, o protocolo foi executado em suas próprias citações. Duas famílias não correlacionadas, diferentes do Claude — **Mistral** (`mistral-small:24b`) e **IBM Granite** (`granite4.1:30b`) — verificaram um conjunto de citações, sem raciocínio, com duas armadilhas ocultas:
+Como teste, o protocolo foi executado em suas próprias citações. Duas famílias decorrelacionadas e diferentes do Claude — **Mistral** (`mistral-small:24b`) e **IBM Granite** (`granite4.1:30b`) — verificaram um conjunto de citações, sem raciocínio, com duas armadilhas ocultas:
 
-| Armadilha plantada | Mistral | IBM Granite | Verdade |
+| Armadilha plantada | Mistral | IBM Granite | Verdade factual |
 |---|---|---|---|
-| O raciocínio em cadeia atribuído a "Nakamura & Olsen" | não detectado | **detectado** (atribuído incorretamente → na verdade, Wei et al. 2022) | atribuído incorretamente |
-| um artigo fabricado com "98% dos erros removidos, nenhum oráculo necessário" | **caught** (fabricated) | **caught** (fabricated) | fabricado |
+| O raciocínio da cadeia de pensamento foi atribuído a "Nakamura & Olsen" | não detectada | **detectada** (atribuição incorreta → na verdade, Wei et al. 2022, arXiv:2201.11903) | atribuída incorretamente |
+| um artigo fabricado com a afirmação de que "98% dos erros foram removidos, nenhum oráculo é necessário" | **caught** (fabricated) | **caught** (fabricated) | fabricado |
 
-Nenhuma das famílias detectou as duas armadilhas sozinha — mas a **união detectou 2/2**. Um único juiz teria validado a atribuição incorreta. Separadamente, o oráculo de recuperação detectou duas *atribuições incorretas reais* em nossos próprios documentos de design (artigos citados sob o autor principal errado) que nenhum LLM paramétrico poderia ter sinalizado — e ele confirmou corretamente artigos genuínos de 2026 que ambos os LLMs sinalizaram falsamente como fabricados, simplesmente porque os artigos são posteriores ao seu treinamento. Esse último ponto é a razão pela qual a verificação de existência na etapa 4 **deve** ser um oráculo de recuperação, nunca um LLM.
+Nenhuma das famílias detectou as duas armadilhas sozinha — mas sua **união detectou 2/2**. Um único juiz teria aceitado a atribuição incorreta. Separadamente, o oráculo de recuperação detectou duas *atribuições incorretas reais* em nossos próprios documentos de projeto (artigos citados sob o autor principal errado) que nenhum LLM paramétrico poderia ter sinalizado — e ele confirmou corretamente artigos genuínos de 2026 que ambos os LLMs marcaram falsamente como fabricados, simplesmente porque os artigos são posteriores ao seu treinamento. Esse último ponto é a razão pela qual a verificação da existência na etapa 4 **deve** ser um oráculo de recuperação, nunca um LLM.
 
-Essa única execução é a tese em miniatura: **lentes descoordenadas + um oráculo de recuperação para existência superam qualquer juiz inteligente.**
+Essa única execução é a tese em miniatura: **lentes decorrelacionadas + um oráculo de recuperação para a existência superam qualquer juiz inteligente.**
 
-## Como está conectado
+### …e novamente, para projetar a v1.1
 
-Você pode executar o protocolo manualmente — qualquer modelo de família diferente, juntamente com a resolução do arXiv/DOI, satisfaz a etapa 4. Duas ferramentas auxiliares tornam isso um único comando:
+As melhorias da versão 1.1 foram escolhidas da mesma forma – executando o `study-swarm` no próprio `study-swarm`. Quatro questões que a primeira versão deixou em aberto (“Acho que…” – como *mecanizar* a verificação da fundamentação, se a fundamentação deve ser feita no momento da geração, como *combinar* as lentes, se deve abster-se na incerteza calibrada) foram encaminhadas para agentes de pesquisa paralelos, e todas as **27 citações resultantes** foram validadas na Etapa 4 antes que qualquer uma delas influenciasse o projeto. O oráculo de recuperação confirmou que **27/27 existem** – incluindo seis artigos de 2025–2026 que um modelo paramétrico teria classificado erroneamente como fabricados – e corrigiu cinco atribuições que um modelo não conseguiria, entre elas uma real má atribuição do primeiro autor que o agente de pesquisa identificou em si mesmo. Executando sem raciocínio, as lentes de fundamentação até reproduziram seus próprios modos de falha documentados em nossa análise: uma delas rotulou incorretamente um artigo real com confiança, e sua *discordância* desencadeou a escalada – exatamente como o processo estabelece. A análise completa está disponível em [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md); as melhorias que foram implementadas – fundamentação decomposta/ternária, fundamentação no momento da geração, a cascata validada pelo oráculo e a abstinência calibrada – estão em [PROTOCOL.md](PROTOCOL.md).
 
-- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — o verificador em tempo de execução: roteamento diferenciado por família, sem inferências, adjudicação multi-lente, um limite determinístico de existência de recuperação (arXiv → Crossref) e recibos assinados.
-- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** — fornece `roleos verify-citations <dispatch>`, o executor que extrai as citações de um documento e as valida através do prism.
+## Como funciona
+
+Você pode executar o protocolo manualmente – qualquer modelo de família diferente mais a resolução do arXiv/DOI por conta própria satisfaz a Etapa 4. Duas ferramentas complementares tornam isso um único comando:
+
+- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** – o verificador em tempo de execução: roteamento entre famílias diferentes, sem raciocínio, adjudicação multi-lente, um limite determinístico para a existência da recuperação (arXiv → Crossref) e recibos assinados.
+- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** – fornece `roleos verify-citations <dispatch>`, o executor que extrai as citações de uma análise e as valida por meio do prism.
+
+A transferência é o próprio formato da análise: um achado escrito como `N. **achado.** Autores ano (arXiv|DOI). implicação.` – com **um identificador resolvível por achado** – é exatamente o que `roleos verify-citations` extrai e valida. Uma análise “limpa” passa facilmente; uma citação malformada é o que o executor sinaliza como não analisada. Esse contrato é o que `study-swarm lint` verifica localmente, para que as Etapas 3 e 4 concordem sobre o que é uma citação.
 
 ## CLI
 
@@ -65,27 +71,62 @@ Você pode executar o protocolo manualmente — qualquer modelo de família dife
 npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
 ```
 
-| Comando | O que faz |
+| Comando | O que ele faz |
 |---|---|
-| `study-swarm protocol` | Imprime o protocolo completo — as cinco etapas, a tabela de interrupção, o padrão de pesquisa. |
-| `study-swarm new <slug>` | Cria um arquivo `<slug>.dispatch.md` com a estrutura básica das cinco etapas para ser preenchido. |
-| `study-swarm lint <file>` | Verifica a *base de pesquisa* de um relatório em relação ao padrão de pesquisa — cada descoberta precisa de um autor, um ano e um identificador que possa ser resolvido (arXiv / DOI / URL); afirmações vagas do tipo "estudos mostram…" são rejeitadas. Sai com o código `1` em caso de violações, o que impede a execução no CI. |
+| `study-swarm protocol` | Imprime o protocolo completo – as cinco etapas, a tabela de interrupção e o padrão de referência. |
+| `study-swarm new <slug>` | Cria um arquivo `<slug>.dispatch.md` com o esqueleto das cinco etapas para preencher. |
+| `study-swarm lint [--json] <path…>` | Verifica a *fundamentação da pesquisa* de uma análise em relação ao padrão de referência – cada achado precisa de um autor, um ano e um identificador resolvível (arXiv / DOI / URL); “estudos mostram…” sem embasamento é rejeitado. Sai com `1` em caso de violações, para que valide o CI. Um `<path>` pode ser um arquivo, um diretório (analisado recursivamente para `*.dispatch.md`) ou `-` para stdin; `--json` emite um relatório legível por máquina. |
+
+`lint` é determinístico – sem chamadas de modelo – portanto, é seguro no CI. Ele aplica o **padrão de referência da Etapa 3** localmente; a verificação baseada em modelo da **Etapa 4** ainda depende de [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
+
+Um ciclo típico:
 
-`lint` é determinístico — não faz chamadas ao modelo — portanto, é seguro para uso no CI. Ele aplica o **padrão de pesquisa da Etapa 3** localmente; a verificação baseada em modelo da **Etapa 4** ainda depende de [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
+```bash
+study-swarm new my-decision                      # creates my-decision.dispatch.md
+# …fill in the questions, run the research dispatch, write the findings…
+study-swarm lint my-decision.dispatch.md         # enforce the sourcing standard (Step 3)
+roleos verify-citations my-decision.dispatch.md  # model-based Step 4 (different family, via prism)
+```
+
+Duas análises completas e “limpas” são fornecidas como referência: [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) (a decisão central do protocolo, concisa) e [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md) (o projeto completo da v1.1 – 27 citações, todas validadas externamente).
+
+### Valide no CI
+
+`lint` recebe um arquivo, um diretório (analisado recursivamente para `*.dispatch.md`) ou `-` para stdin, e `--json` emite um relatório legível por máquina. Adicione isso ao seu repositório para validar a referência de cada análise em cada PR (uma amostra de cópia e colagem também está em [`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml)):
+
+```yaml
+# .github/workflows/dispatches.yml
+name: study-swarm lint
+on:
+  pull_request:
+    paths: ['**/*.dispatch.md', '.github/workflows/dispatches.yml']
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
+```
 
 ## Por que funciona, em poucas palavras
 
-**Atual** — o campo evolui rapidamente; exigir estudos específicos com anos de duração impede que os projetos sejam lançados com 18 meses de atraso. **Funcional** — a evidência mostra o que *falha*, não apenas o que funciona (as explicações podem aumentar a dependência excessiva de uma IA *incorreta* — Bansal et al. 2021). **Seguro** — o envelope protegido pelo verificador é a arquitetura que a evidência suporta, e o protocolo a impõe em sua própria saída. A obtenção de fontes não é um exercício acadêmico; é o rastro da evidência.
+**Atual** – o campo evolui rapidamente; exigir estudos específicos com anos evita que os projetos sejam lançados com 18 meses de atraso. **Funcional** – a evidência mostra o que *falha*, não apenas o que funciona (explicações podem aumentar a dependência excessiva em IA *incorreta* – Bansal et al. 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Seguro** – o envelope protegido pelo verificador é a arquitetura que a evidência suporta, e o protocolo a aplica em sua própria saída. A referência não é um exercício acadêmico; é o rastro da evidência.
 
 ## Segurança
 
-`study-swarm` é um repositório de documentação — Markdown e um logotipo. Não contém código executável e não instala nada deste repositório. Não acessa dados, não requer permissões e não coleta dados de telemetria; não há segredos ou credenciais no código-fonte. A metodologia *descreve* um fluxo de trabalho que usa recuperação da web e verificação baseada em modelo, mas este repositório não o implementa nem o executa. Consulte [SECURITY.md](SECURITY.md).
+`study-swarm` fornece uma **CLI fina e com poucas dependências** (`study-swarm`) junto com a metodologia. Ele não faz **chamadas de rede ou modelo** e não coleta **telemetria**; não há segredos ou credenciais no código-fonte. Em tempo de execução, ele lê apenas o arquivo que você passa para `lint` e grava um único arquivo `<slug>.dispatch.md` no diretório atual para `new` (recusando-se a sobrescrever e nunca fora do diretório de trabalho). A verificação baseada em modelo descrita na metodologia (Etapa 4) é executada pelas ferramentas complementares, não por este pacote. Consulte [SECURITY.md](SECURITY.md).
 
 ## Status
 
-Um protocolo funcional, verificado externamente por sua própria ferramenta — uma família de modelos diferente verifica suas citações (veja a prova acima). Este repositório é a referência pública; [PROTOCOL.md](PROTOCOL.md) é a forma executável. Parte da família [dogfood-lab](https://github.com/dogfood-lab) — métodos e demonstrações para construir na era da IA.
+Um protocolo funcional, validado externamente por sua própria ferramenta – uma família de modelos diferente verifica suas citações (veja a prova acima). A **v1.1** aprimora o verificador onde a primeira versão estava em silêncio: fundamentação decomposta/ternária, fundamentação no momento da geração, uma cascata validada pelo oráculo para combinar lentes e abstinência calibrada – cada um com base na análise v1.1 validada. Este repositório é a referência pública; [PROTOCOL.md](PROTOCOL.md) é a forma executável. Faz parte da família [dogfood-lab](https://github.com/dogfood-lab) – métodos e exemplos para construir na era da IA.
 
-Licenciado sob a licença MIT.
+Licenciado sob MIT.
 
 ---