@dogfood-lab/study-swarm 0.0.0 → 0.6.0

package/README.ja.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dogfood-lab/study-swarm/main/assets/study-swarm.png" alt="study-swarm" width="360">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@dogfood-lab/study-swarm"><img src="https://img.shields.io/npm/v/@dogfood-lab/study-swarm" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
+  <a href="https://dogfood-lab.github.io/study-swarm/"><img src="https://img.shields.io/badge/handbook-live-purple" alt="Handbook"></a>
+  <img src="https://img.shields.io/badge/cited%20research-verified-1f6feb" alt="Cited research, verified">
+</p>
+
+**調査で引用された研究に基づいて設計上の決定を行い、その後、その決定が公式なものになる前に、*別の*モデルファミリーを使用して引用を検証します。**
+
+`study-swarm`はツールではなく、プロトコルです。大規模言語モデル（LLM）を使用して重要な設計上の決定を行う場合（新しい製品レイヤー、アーキテクチャの選択、「ここでモデルを信頼すべきか」という判断など）に、即興で進めるのではなく、既存の知識に基づいて設計を進めると、時代遅れの設計になったり、存在しない情報源や、あなたが考えていることとは異なる内容の情報源に基づいて設計が進んでしまう可能性があります。`study-swarm`は、これらの問題を解決します。複数の研究エージェントを並行して実行し、特定の引用された情報を要求し、設計に影響を与える前に、すべての引用を**異なるモデルファミリーの外部検証者**を通じて検証します。
+
+これは、自らその方法を実践しています。このプロトコルでは、設計を支援するシステムに対して、検証者によって保護された情報を提供するように規定されており、そのため、このプロトコル自体にもそれを適用します。**プロトコルを実行しているモデルであっても、自分の宿題を評価することはできません。**
+
+## プロトコルの5つのステップ
+
+1. **特定する**：経験的な証拠によって回答が変わる可能性のある、3〜5個の重要な設計上の質問を特定します。
+2. **実行する**：各質問に対して、1つの研究エージェントを並行して実行します。各エージェントは、論文のタイトル、著者、発表年、URL、および1文の結論を返します。広範囲にわたる情報よりも、具体的な情報を提供します（「6〜8件の信頼できる情報源が、20件の曖昧な情報よりも優れている」）。
+3. **統合する**：得られた情報を「研究による裏付け」セクションに統合します。`N. **<結論>.** <著者> <年> (<arXiv/DOI>). <設計への影響>.`
+4. **外部で検証する**：*別のモデルファミリー*（推論機能を削除したもの）を使用して、すべての引用を2つの段階で検証します。まず、**検索エンジン**が論文が存在することを確認します（モデルの記憶ではなく）。次に、**妥当性検証**ツールが、結論が情報源と一致することを確認します。**捏造または誤った引用が見つかった場合は、処理を停止します。検証者または検索エンジンが利用できない場合は、処理を停止し、エスカレーションします（情報がないことを「引用は問題ない」と解釈しないでください）。**
+5. **関連付ける**：各アーキテクチャの選択を、番号を使用して結論と関連付けます。設計への影響がない引用はノイズです。
+
+完全な実行可能な詳細（停止テーブル、情報源の標準、アンサンブルルール）は、**[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のエラーは*相関しているため、重要な変数は、生の数ではなく、レンズの多様性です。
+
+## 実際に機能するのでしょうか？（証拠）
+
+テストとして、このプロトコルを自分の引用に対して実行しました。2つの相関性の低い、Claude以外のモデル（**Mistral** (`mistral-small:24b`)と**IBM Granite** (`granite4.1:30b`)）を使用して、推論機能を削除した状態で、2つのブラインドトラップを仕込んだ引用セットを検証しました。
+
+| 仕掛けられたトラップ | Mistral | IBM Granite | 真実 |
+|---|---|---|---|
+| 「Nakamura & Olsen」に帰属された推論 | 見逃された | **検出された**（誤って帰属された → 実際にはWei et al. 2022） | 誤って帰属された |
+| 「98％のエラーが解消され、オラクルは不要」という捏造された論文 | **caught** (fabricated) | **caught** (fabricated) | 捏造された |
+
+どちらのモデルも、単独では両方のトラップを検出できませんでしたが、**両方のモデルを組み合わせることで、2/2を検出しました。** 単一の判断者では、誤った帰属を検出できなかったでしょう。別途、検索エンジンは、当社の設計ドキュメントにある2つの*実際の*誤った帰属（間違った最初の著者に帰属された論文）を検出しました。これらの誤りは、パラメトリックLLMでは検出できなかったでしょう。また、両方のLLMが、トレーニングデータ以降に発表された論文を捏造されたものとして誤ってフラグを立てたのに対し、検索エンジンは、これらの論文が実際に存在することを正しく確認しました。この最後の点が、ステップ4の存在チェックが**検索エンジンである必要があり、LLMであってはならない**理由です。
+
+この単一の実行は、ミニチュア版の論文です。**相関性の低いレンズと、存在を確認するための検索エンジンを組み合わせることで、単一の優れた判断者よりも優れた結果が得られます。**
+
+## その仕組み
+
+このプロトコルを手動で実行することもできます。異なるモデルファミリーのモデルと、自分で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 を介して検証する。
+
+## 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の実行を停止します。 |
+
+`lint`は決定的な処理であり、モデルへの呼び出しは行われないため、CI環境で安全に使用できます。ローカルで**ステップ3の情報源の基準**を適用します。モデルベースの**ステップ4**の検証は、引き続き[`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prismに委ねられます。
+
+## なぜ機能するのか（簡潔に）
+
+**現状** — この分野は急速に進展しており、特定の研究を数年かけて行うと、設計が18か月遅れてリリースされることになる。**機能性** — 証拠は、何が「機能する」かだけでなく、何が「機能しない」かを示す（説明が、誤ったAIへの過度な依存を招く可能性がある — Bansal et al. 2021）。**安全性** — 検証ツールによって保護された範囲は、証拠によって裏付けられるアーキテクチャであり、プロトコルはそれを自身の出力に適用する。情報源の提示は、学術的なパフォーマンスではなく、証拠の追跡である。
+
+## セキュリティ
+
+`study-swarm` は、ドキュメントのリポジトリであり、Markdown とロゴが含まれている。実行可能なコードは含まれておらず、このリポジトリから何もインストールされない。データにアクセスせず、権限を必要とせず、テレメトリも収集しない。ソースコードには、秘密情報や認証情報は含まれていない。この手法は、Web検索とモデルベースの検証を使用するワークフローを「記述」しているが、このリポジトリはそれを実装または実行するものではない。詳細は [SECURITY.md](SECURITY.md) を参照。
+
+## ステータス
+
+動作するプロトコルであり、その独自の仕組みによって外部から検証されている。異なるモデルファミリーがその引用をチェックする（上記の証明を参照）。このリポジトリは、公開リファレンスであり、[PROTOCOL.md](PROTOCOL.md) が実行可能な形式である。これは、[dogfood-lab](https://github.com/dogfood-lab) ファミリーの一部であり、AI時代におけるビルドのための手法と事例を紹介する。
+
+MITライセンス。
+
+---
+
+<p align="center"><sub>Part of the <a href="https://github.com/dogfood-lab">dogfood-lab</a> family — methods &amp; showcases for building in the AI era. Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>.</sub></p>

package/README.md

@@ -1,10 +1,92 @@
-# @dogfood-lab/study-swarm
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
 
-> **Reserved placeholder (`0.0.0`).** This reserves the package name on Trusted-Publishing rails; a real package will follow.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dogfood-lab/study-swarm/main/assets/study-swarm.png" alt="study-swarm" width="360">
+</p>
 
-**study-swarm** is a methodology for grounding substantial design decisions in cited research — then verifying every citation with a *different* model family, reasoning-stripped, before any of it becomes canon.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@dogfood-lab/study-swarm"><img src="https://img.shields.io/npm/v/@dogfood-lab/study-swarm" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
+  <a href="https://dogfood-lab.github.io/study-swarm/"><img src="https://img.shields.io/badge/handbook-live-purple" alt="Handbook"></a>
+  <img src="https://img.shields.io/badge/cited%20research-verified-1f6feb" alt="Cited research, verified">
+</p>
 
-- **Repository:** https://github.com/dogfood-lab/study-swarm
-- **Handbook:** https://dogfood-lab.github.io/study-swarm/
+**Ground design decisions in cited research — then verify the citations with a *different* model family before any of it becomes canon.**
 
-Part of the [dogfood-lab](https://github.com/dogfood-lab) family.
+`study-swarm` is a protocol, not a tool. When you're making a substantial design decision with an LLM — a new product layer, an architecture choice, a "should we trust the model here" call — improvising from first principles ships designs that are stale, and citing papers from memory ships designs that rest on sources that don't exist or don't say what you think. study-swarm replaces both: dispatch parallel research agents, demand specific cited findings, and gate every citation through an **external verifier of a different model family** before it informs the design.
+
+It applies its own medicine. The protocol prescribes verifier-protected envelopes for the systems it helps design — so it runs one on itself. **No model grades its own homework, including the one running the protocol.**
+
+## The protocol in five steps
+
+1. **Identify** 3–5 load-bearing design questions where empirical evidence would change the answer.
+2. **Dispatch** one research agent per question, in parallel. Each must return paper titles + authors + years + URLs + a one-sentence finding — specificity over breadth ("6–8 well-sourced findings beat 20 vague gestures").
+3. **Synthesize** the findings into a *Research grounding* section: `N. **<finding>.** <Authors> <year> (<arXiv/DOI>). <design implication>.`
+4. **Verify externally** — a *different model family*, reasoning-stripped, checks every citation in two stages: a **retrieval oracle** confirms the paper exists (never the model's memory), then a **groundedness** lens confirms the finding matches the source. **Halt** on fabricated/misattributed; **halt-and-escalate** if the verifier or retrieval oracle is unavailable (never read absence as "citations fine").
+5. **Connect** each architectural choice back to a finding by number. Citations without a design implication are noise.
+
+The full executable detail — the halt table, the sourcing standard, the ensemble rule — is in **[PROTOCOL.md](PROTOCOL.md)**.
+
+## Why a *different* family, reasoning-stripped?
+
+Because the failure modes are documented, not hypothetical:
+
+- **LLMs can't reliably verify their own output.** 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)) — the external verifier carries the gains; the self-critique content is inert.
+- **Same-family judges self-prefer.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — self-recognition correlates *linearly* with self-preference, so partial blinding doesn't help. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — a panel across disjoint families is less biased at ~7× lower cost.
+- **Citations are where LLMs lie.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — 55% of GPT-3.5 / 18% of GPT-4 citations are fabricated. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — links resolve >94% of the time yet only 39–77% of cited content actually supports the claim. So existence must be checked by **retrieval, not recall**.
+- **Hide the generator's reasoning.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — manipulated chain-of-thought alone inflates a judge's false-positives by up to 90% with actions held fixed. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — CoT is post-hoc rationalization. The verifier sees the bare citation claim, never the "why I included this."
+- **Diversity beats count.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — four verifiers at pairwise correlation ρ ∈ [0.05, 0.25] beat any single one via submodular coverage. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — LLM errors are *correlated*, so the load-bearing variable is lens diversity, not raw count.
+
+## Does it actually work? (proof)
+
+As a test, the protocol was run against its own citations. Two decorrelated non-Claude families — **Mistral** (`mistral-small:24b`) and **IBM Granite** (`granite4.1:30b`) — checked a citation set, reasoning-stripped, seeded with two blind traps:
+
+| Planted trap | Mistral | IBM Granite | Ground truth |
+|---|---|---|---|
+| Chain-of-thought prompting attributed to "Nakamura & Olsen" | missed | **caught** (misattributed → really Wei et al. 2022) | 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.**
+
+## 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:
+
+- **[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.
+
+## CLI
+
+```bash
+npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
+```
+
+| Command | What it does |
+|---|---|
+| `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. |
+
+`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.
+
+## 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.
+
+## 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).
+
+## 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.
+
+MIT licensed.
+
+---
+
+<p align="center"><sub>Part of the <a href="https://github.com/dogfood-lab">dogfood-lab</a> family — methods &amp; showcases for building in the AI era. Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>.</sub></p>

package/README.pt-BR.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.md">English</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dogfood-lab/study-swarm/main/assets/study-swarm.png" alt="study-swarm" width="360">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@dogfood-lab/study-swarm"><img src="https://img.shields.io/npm/v/@dogfood-lab/study-swarm" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
+  <a href="https://dogfood-lab.github.io/study-swarm/"><img src="https://img.shields.io/badge/handbook-live-purple" alt="Handbook"></a>
+  <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.**
+
+`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.
+
+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.**
+
+## O protocolo em cinco etapas
+
+1. **Identifique** 3 a 5 questões de design 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.
+
+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)**.
+
+## 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.
+
+## 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:
+
+| Armadilha plantada | Mistral | IBM Granite | Verdade |
+|---|---|---|---|
+| 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 |
+
+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.
+
+Essa única execução é a tese em miniatura: **lentes descoordenadas + um oráculo de recuperação para existência superam qualquer juiz inteligente.**
+
+## Como está conectado
+
+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:
+
+- **[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.
+
+## CLI
+
+```bash
+npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
+```
+
+| Comando | O que 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. |
+
+`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.
+
+## 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.
+
+## 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).
+
+## 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.
+
+Licenciado sob a licença MIT.
+
+---
+
+<p align="center"><sub>Part of the <a href="https://github.com/dogfood-lab">dogfood-lab</a> family — methods &amp; showcases for building in the AI era. Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>.</sub></p>

package/README.zh.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.md">English</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dogfood-lab/study-swarm/main/assets/study-swarm.png" alt="study-swarm" width="360">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@dogfood-lab/study-swarm"><img src="https://img.shields.io/npm/v/@dogfood-lab/study-swarm" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
+  <a href="https://dogfood-lab.github.io/study-swarm/"><img src="https://img.shields.io/badge/handbook-live-purple" alt="Handbook"></a>
+  <img src="https://img.shields.io/badge/cited%20research-verified-1f6feb" alt="Cited research, verified">
+</p>
+
+**将设计决策建立在引用的研究基础上——然后在将任何内容确立为标准之前，使用*不同的*模型系列来验证这些引用。**
+
+`study-swarm` 是一种协议，而不是一种工具。当您使用大型语言模型 (LLM) 做出重大的设计决策时——例如，创建一个新的产品层、选择一种架构，或者决定“我们是否应该在这里信任该模型”——如果仅凭经验进行设计，会导致设计陈旧；如果仅凭记忆引用论文，会导致设计依赖于不存在或与您认为的内容不符的来源。`study-swarm` 替代了这两种方法：同时启动多个研究代理，要求提供具体的引用结果，并在每个引用被用于指导设计之前，通过一个**来自不同模型系列的外部验证器**进行验证。
+
+它也适用于自身。该协议规定，对于它所帮助设计的系统，应使用经过验证器保护的机制——因此，它也将其应用于自身。**没有模型会自己批改作业，包括运行该协议的模型。**
+
+## 该协议包含五个步骤
+
+1. **确定** 3-5 个关键的设计问题，如果存在经验证据，这些证据可能会改变答案。
+2. **同时启动**每个问题的研究代理。每个代理必须返回论文标题 + 作者 + 年份 + URL + 一句话的结论——强调具体性而非广泛性（“6-8 个来源可靠的结论胜过 20 个模糊的描述”）。
+3. **将结论综合**到“研究依据”部分：`N. **<结论>.** <作者> <年份> (<arXiv/DOI>). <设计意义>.`
+4. **进行外部验证**——一个*不同的模型系列*，不带推理能力，以两个阶段检查每个引用：一个**检索预言机**确认论文是否存在（永远不是模型的记忆），然后一个**可靠性**过滤器确认结论与来源是否匹配。如果发现捏造或错误引用，则**停止**；如果验证器或检索预言机不可用，则**停止并升级**（永远不要将无法找到的情况视为“引用没问题”）。
+5. **将每个架构选择与一个结论联系起来**，通过编号进行关联。没有设计意义的引用是噪音。
+
+完整的可执行细节——停止表、来源标准、集成规则——位于 **[PROTOCOL.md](PROTOCOL.md)** 中。
+
+## 为什么使用*不同的*模型系列，并且不带推理能力？
+
+因为失败模式是已知的，而不是假设的：
+
+- **大型语言模型无法可靠地验证其自身的输出。** Huang 等人，2023 年 ([arXiv:2310.01798](https://arxiv.org/abs/2310.01798))；Kambhampati 等人，2024 年 ([arXiv:2402.01817](https://arxiv.org/abs/2402.01817)，LLM-Modulo)；Stechly 等人，2024 年 ([arXiv:2402.08115](https://arxiv.org/abs/2402.08115))——外部验证器可以带来收益；自我批评的内容是无效的。
+- **同一系列的评估者会偏向于自我。** Panickssery、Bowman 和 Feng，2024 年 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076))——自我识别与自我偏好呈*线性*相关，因此部分隐藏并不能提供帮助。Verga 等人，2024 年 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796)，PoLL))——来自不同系列的评估小组的偏见更小，成本约为原来的 1/7。
+- **大型语言模型最容易在引用方面撒谎。** Walters 和 Wilder，2023 年 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5))——55% 的 GPT-3.5 / 18% 的 GPT-4 引用是捏造的。Onweller 等人，2026 年 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635))——链接可以解决超过 94% 的问题，但只有 39-77% 的引用内容实际上支持该主张。因此，必须通过**检索**来检查是否存在，而不是通过**回忆**。
+- **隐藏生成器的推理过程。** Khalifa 等人，2026 年 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691)，“欺骗评估者”)——仅通过操纵思维链，就可以使评估者的假阳性率提高高达 90%，而操作保持不变。Turpin 等人，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]，通过亚模覆盖胜过任何一个智能评估者。Kim 等人，2025 年 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962))——大型语言模型的错误是*相关的*，因此关键变量是视角多样性，而不是原始数量。
+
+## 它真的有效吗？（证明）
+
+作为一项测试，该协议被应用于其自身的引用。两个不相关的非 Claude 系列——**Mistral** (`mistral-small:24b`) 和 **IBM Granite** (`granite4.1:30b`)——检查了一组引用，并且不带推理能力，并设置了两个盲目陷阱：
+
+| 设置的陷阱 | Mistral | IBM Granite | 真实情况 |
+|---|---|---|---|
+| 思维链提示归因于“Nakamura & Olsen” | 未发现 | **发现**（错误归因 → 实际上是 Wei 等人，2022 年） | 错误归因 |
+| 一个捏造的“98% 的错误已消除，不需要预言机”论文 | **caught** (fabricated) | **caught** (fabricated) | 捏造 |
+
+两个模型单独都没有发现这两个陷阱——但它们的**组合发现了 2/2 个**。如果只有一个评估者，它会忽略错误归因。此外，检索预言机发现了我们自己设计文档中的两个*真实*的错误归因（引用了错误的作者），而任何参数化的大型语言模型都无法标记——并且它正确地确认了 2026 年的真实论文，而这两个大型语言模型都错误地将其标记为捏造，仅仅是因为这些论文的发布时间晚于它们的训练时间。最后一点是，步骤 4 的存在性检查**必须**是一个检索预言机，而不是大型语言模型。
+
+这一个测试就是缩影：**不相关的视角 + 用于验证存在性的检索预言机，胜过任何一个智能评估者。**
+
+## 它的工作方式
+
+您可以手动运行该协议——任何不同的模型系列，加上您自己解析 arXiv/DOI，就可以满足步骤 4 的要求。两个辅助工具可以将其简化为一个命令：
+
+- **[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 进行验证。
+
+## 命令行界面
+
+```bash
+npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
+```
+
+| 命令 | 功能 |
+|---|---|
+| `study-swarm protocol` | 打印完整的协议——五个步骤、终止表、来源标准。 |
+| `study-swarm new <slug>` | 生成一个 `<slug>.dispatch.md` 文件，其中包含五个步骤的框架，以便进行填充。 |
+| `study-swarm lint <file>` | 检查某个任务的*研究依据*是否符合来源标准——每个发现都需要有作者、年份和可解析的标识符（arXiv / DOI / URL）；“研究表明……”这种含糊的说法将被拒绝。如果存在违规，则返回 `1`，从而阻止 CI。 |
+
+`lint` 命令是确定性的——不调用任何模型——因此可以在 CI 中安全地使用。它在本地强制执行**第三步的来源标准**；基于模型的**第四步**验证仍然依赖于 [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism。
+
+## 为什么它有效，一句话概括
+
+**及时性**——该领域发展迅速；要求提供具体的、带有年份的研究，可以防止设计落后 18 个月。**实用性**——证据表明哪些*失败*，而不仅仅是哪些有效（解释可能会增加对*错误*人工智能的过度依赖——Bansal 等人，2021 年）。**安全性**——由验证器保护的范围是证据支持的架构，并且协议对其自身的输出进行强制执行。来源不是学术表演；它是证据链。
+
+## 安全性
+
+`study-swarm` 是一个文档仓库——包含 Markdown 文件和徽标。它不包含任何可执行代码，也不从该仓库安装任何内容。它不涉及任何数据，不需要任何权限，也不收集任何遥测数据；源代码中没有秘密或凭据。该方法*描述*了一种使用网络检索和基于模型的验证的工作流程，但此仓库不实现或运行该工作流程。请参阅 [SECURITY.md](SECURITY.md)。
+
+## 状态
+
+一个可行的协议，由其自身的机制进行外部验证——不同的模型家族检查其引用（参见上面的证明）。此仓库是公共参考；[PROTOCOL.md](PROTOCOL.md) 是可执行的形式。它是 [dogfood-lab](https://github.com/dogfood-lab) 系列的一部分——用于在人工智能时代构建的方法和示例。
+
+采用 MIT 许可。
+
+---
+
+<p align="center"><sub>Part of the <a href="https://github.com/dogfood-lab">dogfood-lab</a> family — methods &amp; showcases for building in the AI era. Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>.</sub></p>

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+`study-swarm` is a **documentation repository** — it contains the study-swarm methodology (Markdown) and a logo asset. It ships no executable code, no compiled artifacts, and installs nothing from this repository. (The npm name `@dogfood-lab/study-swarm` is a reserved placeholder; this repo is the methodology source, not the package.)
+
+## Threat model
+
+- **What it touches:** nothing at runtime. There is no program to run; reading the docs executes no code.
+- **What it does NOT touch:** your filesystem, network, credentials, or environment.
+- **Telemetry:** none. **Secrets/credentials:** none in source.
+- **Permissions required:** none.
+
+The methodology *describes* a workflow that uses web retrieval and model-based verification, but this repository does not implement or execute that workflow.
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x     | ✅        |
+| < 1.0   | —         |
+
+## Reporting
+
+Found an error in the methodology, a broken or misattributed citation, or a security concern in related tooling? Open an issue at <https://github.com/dogfood-lab/study-swarm/issues>, or email **64996768+mcp-tool-shop@users.noreply.github.com**. We aim to acknowledge within 7 days.

package/bin/study-swarm.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// study-swarm — thin CLI for the research-grounded design protocol.
+// Zero runtime dependencies. Commands: protocol | new | lint | help | version.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf8'));
+const VERSION = PKG.version;
+
+const HELP = `study-swarm v${VERSION} — ground design decisions in cited research, then verify.
+
+USAGE
+  study-swarm <command> [args]
+
+COMMANDS
+  protocol            Print the locked protocol (the five steps + halt rules).
+  new <slug>          Scaffold a dispatch file <slug>.dispatch.md to fill in.
+  lint <file>         Check a dispatch's citations against the sourcing standard.
+  help                Show this help.
+  version             Print the version.
+
+EXIT CODES
+  0  ok / lint clean
+  1  lint found sourcing violations
+  2  usage or runtime error
+
+Run a dispatch's model-based verification with: roleos verify-citations <file>
+Docs: https://dogfood-lab.github.io/study-swarm/
+`;
+
+function fail(code, msg) {
+  process.stderr.write(`study-swarm: ${msg}\n`);
+  process.exit(code);
+}
+
+function cmdProtocol() {
+  const p = resolve(__dirname, '../PROTOCOL.md');
+  if (!existsSync(p)) fail(2, 'PROTOCOL.md not found in package');
+  process.stdout.write(readFileSync(p, 'utf8'));
+}
+
+const template = (slug) => `# Study-swarm dispatch: ${slug}
+
+> Fill in each section. Verify citations (Step 4) BEFORE connecting findings to the design (Step 5).
+> Lint the sourcing with:  study-swarm lint ${slug}.dispatch.md
+
+## Step 1 — Load-bearing questions
+<!-- 3-5 questions where empirical evidence would change the answer. Fewer is fine if the decision is substantial. -->
+1.
+2.
+3.
+
+## Step 2 — Research dispatch
+<!-- One research agent per question, in parallel. Each returns: title, authors, year, URL, one-sentence finding. -->
+
+## Step 3 — Research grounding
+<!-- One entry per finding (this is what 'lint' checks):
+     N. **<finding>.** <Authors> <year> (<arXiv:NNNN.NNNNN | DOI>). <design implication>. -->
+1. **<finding>.** <Authors> <year> (arXiv:____.____). <implication>.
+
+## Step 4 — External verification
+<!-- Different model family, reasoning-stripped. Run:  roleos verify-citations ${slug}.dispatch.md
+     HALT on fabricated/misattributed; halt-and-escalate if the verifier or oracle is unavailable. -->
+- [ ] every citation resolved by retrieval (arXiv/DOI), not model memory
+- [ ] every finding matches what its source actually claims (groundedness)
+- [ ] >= 3 decorrelated lenses (retrieval oracle + >= 2 different model families)
+
+## Step 5 — Architecture
+<!-- Each load-bearing choice references a finding by number. Citations without a connection are noise. -->
+`;
+
+function cmdNew(slug) {
+  if (!slug) fail(2, 'usage: study-swarm new <slug>');
+  const safe = String(slug).replace(/\.dispatch\.md$/i, '').replace(/[^\w.\-/]/g, '-');
+  const out = `${safe}.dispatch.md`;
+  if (existsSync(out)) fail(2, `refusing to overwrite existing ${out}`);
+  writeFileSync(out, template(safe), 'utf8');
+  process.stdout.write(`Created ${out}\nFill it in, then:  study-swarm lint ${out}\n`);
+}
+
+function cmdLint(file) {
+  if (!file) fail(2, 'usage: study-swarm lint <file>');
+  if (!existsSync(file)) fail(2, `file not found: ${file}`);
+  const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+
+  const start = lines.findIndex((l) => /^#{1,6}\s.*research grounding/i.test(l));
+  if (start === -1) fail(1, 'no "Research grounding" section found — every dispatch needs one (Step 3).');
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,6}\s/.test(lines[i])) { end = i; break; }
+  }
+  const section = lines.slice(start + 1, end);
+
+  const YEAR = /\b(19|20)\d{2}\b/;
+  const ID = /(arxiv:\s*\d{4}\.\d{4,5}|10\.\d{4,9}\/\S+|https?:\/\/\S+)/i;
+  const PLACEHOLDER = /arXiv:_{2,}|<finding>|<authors>|<year>|<implication>/i;
+  const BANNED = /\b(studies show|research suggests|it'?s well[- ]established|well[- ]established that)\b/i;
+
+  // Each numbered list item (with its continuation lines) is one finding.
+  const findings = [];
+  let cur = null;
+  for (const l of section) {
+    if (/^\s*\d+\.\s/.test(l)) { if (cur !== null) findings.push(cur); cur = l; }
+    else if (cur !== null && l.trim()) cur += ' ' + l.trim();
+  }
+  if (cur !== null) findings.push(cur);
+
+  const problems = [];
+  if (findings.length === 0) problems.push('Research grounding has no numbered findings.');
+  findings.forEach((f, i) => {
+    const n = i + 1;
+    if (PLACEHOLDER.test(f)) problems.push(`finding ${n}: still has template placeholders — fill it in.`);
+    if (!YEAR.test(f)) problems.push(`finding ${n}: missing a year.`);
+    if (!ID.test(f)) problems.push(`finding ${n}: missing an identifier (arXiv:NNNN.NNNNN, DOI, or URL).`);
+  });
+  lines.forEach((l, i) => {
+    if (BANNED.test(l) && !ID.test(l)) {
+      problems.push(`line ${i + 1}: name the study (author + year + identifier), don't gesture: "${l.trim().slice(0, 56)}"`);
+    }
+  });
+
+  if (problems.length) {
+    process.stderr.write(`x ${file}: ${problems.length} sourcing issue(s)\n`);
+    for (const p of problems) process.stderr.write(`  - ${p}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`ok ${file}: ${findings.length} finding(s), all sourced.\n`);
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case 'protocol': return cmdProtocol();
+    case 'new': return cmdNew(rest[0]);
+    case 'lint': return cmdLint(rest[0]);
+    case 'version': case '--version': case '-v':
+      return void process.stdout.write(VERSION + '\n');
+    case 'help': case '--help': case '-h': case undefined:
+      return void process.stdout.write(HELP);
+    default:
+      fail(2, `unknown command "${cmd}". Run "study-swarm help".`);
+  }
+}
+
+try {
+  main(process.argv.slice(2).filter((a) => a !== '--debug'));
+} catch (err) {
+  if (process.argv.includes('--debug')) throw err;
+  fail(2, err && err.message ? err.message : String(err));
+}