@dogfood-lab/study-swarm 0.6.0 → 1.1.0

package/README.zh.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` 可以取代这两种做法：它会同时启动多个研究代理，要求提供具体的引文结果，并且在将任何引文用于指导设计之前，都会通过**来自不同模型系列的外部验证器**进行验证。
 
-它也适用于自身。该协议规定，对于它所帮助设计的系统，应使用经过验证器保护的机制——因此，它也将其应用于自身。**没有模型会自己批改作业，包括运行该协议的模型。**
+它采取了自我调节的方式。该协议规定，对于其参与设计的系统，应使用经过验证者保护的信封——因此，它也将其应用于自身。**没有任何模型会自己批改作业，包括运行该协议的模型。**
 
-## 该协议包含五个步骤
+## 五步流程
 
-1. **确定** 3-5 个关键的设计问题，如果存在经验证据，这些证据可能会改变答案。
-2. **同时启动**每个问题的研究代理。每个代理必须返回论文标题 + 作者 + 年份 + URL + 一句话的结论——强调具体性而非广泛性（“6-8 个来源可靠的结论胜过 20 个模糊的描述”）。
-3. **将结论综合**到“研究依据”部分：`N. **<结论>.** <作者> <年份> (<arXiv/DOI>). <设计意义>.`
-4. **进行外部验证**——一个*不同的模型系列*，不带推理能力，以两个阶段检查每个引用：一个**检索预言机**确认论文是否存在（永远不是模型的记忆），然后一个**可靠性**过滤器确认结论与来源是否匹配。如果发现捏造或错误引用，则**停止**；如果验证器或检索预言机不可用，则**停止并升级**（永远不要将无法找到的情况视为“引用没问题”）。
-5. **将每个架构选择与一个结论联系起来**，通过编号进行关联。没有设计意义的引用是噪音。
+1. **确定** 3 到 5 个关键的结构设计问题，这些问题的答案可以通过实证证据来改变。
+2. **指派** 一名研究人员负责每个问题，并让他们并行工作。每位研究人员必须提供论文标题、作者、发表年份、网址以及一个简短的结论（强调具体性而非广泛性，“6 到 8 个有充分依据的结论胜过 20 个含糊不清的描述”）。
+3. **综合** 这些结论，形成一个“*研究基础*”部分：`N. **<结论>.** <作者> <年份> (<arXiv/DOI>)。 <设计启示>。`
+4. **进行外部验证**——使用一种*不同的模型系列*，去除推理能力后，分两个阶段检查所有引用文献：首先，一个**检索预言机**确认论文是否存在（绝不能依赖模型的记忆），然后，一个**真实性评估工具**确认结论是否与来源一致。如果发现捏造或错误归因的引用，则立即**停止**；如果验证者或检索预言机不可用，则**停止并升级处理**（切勿将无法找到的情况解读为“引用没有问题”）。
+5. **将**每个结构设计选择与相应的结论联系起来，通过编号进行关联。如果没有明确的设计启示，那么这些引用就是噪音。
 
-完整的可执行细节——停止表、来源标准、集成规则——位于 **[PROTOCOL.md](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))——大型语言模型的错误是*相关的*，因此关键变量是视角多样性，而不是原始数量。
+- **大型语言模型无法可靠地验证自身输出。** 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))——GPT-3.5 中 55% 的引用，GPT-4 中 18% 的引用是捏造的。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`)——检查了一组引用，并且不带推理能力，并设置了两个盲目陷阱：
+为了进行测试，我们将该协议应用于其自身的引用文献。我们选择了两个与 Claude 模型无关的模型系列——**Mistral**（`mistral-small:24b`）和 **IBM Granite**（`granite4.1:30b`），并对它们进行了测试。测试内容包括：检查一组引用文献，去除推理过程中的干扰因素，并在其中设置了两个隐藏的陷阱。
 
-| 设置的陷阱 | Mistral | IBM Granite | 真实情况 |
+| 设下陷阱。 | 米斯特拉尔 | IBM 花岗岩（IBM Granite） | 真实数据；基准数据。 |
 |---|---|---|---|
-| 思维链提示归因于“Nakamura & Olsen” | 未发现 | **发现**（错误归因 → 实际上是 Wei 等人，2022 年） | 错误归因 |
-| 一个捏造的“98% 的错误已消除，不需要预言机”论文 | **caught** (fabricated) | **caught** (fabricated) | 捏造 |
+| “中村和奥尔森”提出的基于思维链的提示方法。 | 错过；想念。 | **已更正**（原错误归因，现改为：魏等人，2022年，arXiv:2201.11903） | 错误归因；错误地认为……是……所为。 |
+| 一篇捏造的论文，声称“已消除 98% 的错误，无需使用 Oracle”。 | **caught** (fabricated) | **caught** (fabricated) | 捏造的；伪造的。 |
 
-两个模型单独都没有发现这两个陷阱——但它们的**组合发现了 2/2 个**。如果只有一个评估者，它会忽略错误归因。此外，检索预言机发现了我们自己设计文档中的两个*真实*的错误归因（引用了错误的作者），而任何参数化的大型语言模型都无法标记——并且它正确地确认了 2026 年的真实论文，而这两个大型语言模型都错误地将其标记为捏造，仅仅是因为这些论文的发布时间晚于它们的训练时间。最后一点是，步骤 4 的存在性检查**必须**是一个检索预言机，而不是大型语言模型。
+两个家庭都未能单独成功设置这两个陷阱——但他们合作后，两个陷阱都成功触发了。如果由一位法官来判断，可能会出现误判。此外，检索系统在我们的设计文档中发现了两个真实的错误归因（即引用时将论文归于错误的作者），而任何参数化的大型语言模型都无法识别这些错误——并且它正确地确认了真正的 2026 年发表的论文，这两篇论文之前被两个大型语言模型错误地标记为虚构，仅仅是因为这些论文的发表时间晚于它们接受训练的时间。最后这一点是第四步存在检查必须采用检索系统而非大型语言模型的根本原因。
 
-这一个测试就是缩影：**不相关的视角 + 用于验证存在性的检索预言机，胜过任何一个智能评估者。**
+那一次实验结果，可以被视为一个微缩版的论点：**通过使用不相关的镜头，并结合一种用于验证存在的检索机制，其效果将优于任何单一的智能判断系统。**
 
-## 它的工作方式
+### ……而且，我们还要重新设计 1.1 版本
 
-您可以手动运行该协议——任何不同的模型系列，加上您自己解析 arXiv/DOI，就可以满足步骤 4 的要求。两个辅助工具可以将其简化为一个命令：
+v1.1版本的改进采用相同的方式进行——通过在“study-swarm”上运行“study-swarm”。第一个版本提出的四个问题（如何*实现*扎实性检查的自动化，是否在生成时进行扎实性验证，如何*组合*不同的视角，以及是否对经过校准的不确定性进行弃权）被分配给并行的研究代理，所有**27条结果引用**都通过第4步进行筛选，然后才用于指导设计。检索预言机确认**27/27条引用存在**——包括六篇2025-2026年的论文，如果使用参数模型，这些论文会被错误地标记为捏造的——并且更正了五处归因错误，而这是模型无法做到的，其中一处是研究代理自己发现的一处真实的作者署名错误。在不进行推理的情况下运行，扎实性视角甚至可以重现其自身记录的失败模式：自信地将一篇真实论文错误地标记为虚假论文，并且它们的*分歧*触发了升级——这与级联机制完全一致。经过验证的工作流程以[`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md)的形式提供；它所确定的改进（分解/三元扎实性、生成时扎实性、由预言机控制的级联机制以及经过校准的弃权）都包含在[PROTOCOL.md](PROTOCOL.md)中。
 
-- **[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 进行验证。
+## 其工作原理
 
-## 命令行界面
+您可以手动运行该协议——任何不同类型的模型，再加上您自己解析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进行筛选。
+
+传递过程就是工作流程的格式：将研究结果写成`N. **finding.** Authors year (arXiv|DOI). implication.`的形式——**每条研究结果都包含一个可解析的标识符**——这正是`roleos verify-citations`提取和筛选的内容。如果工作流程符合“lint”规范，则可以顺利传递；如果引用格式不正确，运行器会将其标记为未解析。`study-swarm lint`会在本地检查这一点，因此第3步和第4步对引用的定义是一致的。
+
+## 命令行界面（CLI）
 
 ```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。 |
+| `study-swarm protocol` | 打印完整的协议——五个步骤、停止表以及来源标准。 |
+| `study-swarm new <slug>` | 创建一个`<slug>.dispatch.md`文件，其中包含五步流程的框架，以便进行填充。 |
+| `study-swarm lint [--json] <path…>` | 根据来源标准检查工作流程的*研究扎实性*——每条研究结果都需要作者、年份和一个可解析的标识符（arXiv / DOI / URL）；“研究表明……”这种含糊其辞的方式将被拒绝。如果存在违规行为，则退出代码为`1`，以便在CI中进行筛选。`<path>`可以是文件、目录（递归地检查所有`.dispatch.md`文件），或者`-`表示标准输入；`--json`会输出机器可读的报告。 |
+
+`lint`是确定性的——不调用任何模型——因此可以在CI中安全使用。它在本地强制执行**第3步的来源标准**；基于模型的**第4步**验证仍然依赖于[`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism。
+
+一个典型的循环：
 
-`lint` 命令是确定性的——不调用任何模型——因此可以在 CI 中安全地使用。它在本地强制执行**第三步的来源标准**；基于模型的**第四步**验证仍然依赖于 [`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)
+```
+
+两个完整的、符合“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`文件）或`-`表示标准输入，并且`--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 个月。**实用性**——证据表明哪些*失败*，而不仅仅是哪些有效（解释可能会增加对*错误*人工智能的过度依赖——Bansal 等人，2021 年）。**安全性**——由验证器保护的范围是证据支持的架构，并且协议对其自身的输出进行强制执行。来源不是学术表演；它是证据链。
+**及时性**——该领域发展迅速；要求提供具体的带有年份的研究，可以防止设计落后18个月。**功能性**——证据表明哪些*方法失败*，而不仅仅是哪些有效（解释可能会增加对*错误*人工智能的过度依赖——Bansal等人，2021年，[arXiv:2006.14779](https://arxiv.org/abs/2006.14779)）。**安全性**——受验证器保护的范围是证据支持的架构，并且协议对其自身的输出进行强制执行。来源不是学术上的形式主义；它是证据链。
 
 ## 安全性
 
-`study-swarm` 是一个文档仓库——包含 Markdown 文件和徽标。它不包含任何可执行代码，也不从该仓库安装任何内容。它不涉及任何数据，不需要任何权限，也不收集任何遥测数据；源代码中没有秘密或凭据。该方法*描述*了一种使用网络检索和基于模型的验证的工作流程，但此仓库不实现或运行该工作流程。请参阅 [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) 系列的一部分——用于在人工智能时代构建的方法和示例。
+一个可用的协议，其自身的机制对其进行了外部验证——不同的模型系列检查其引用（参见上面的证明）。**v1.1**改进了验证器，弥补了第一个版本中存在的不足：分解/三元扎实性、生成时扎实性、由预言机控制的级联机制以及经过校准的弃权——每项都基于经过验证的v1.1工作流程。此仓库是公共参考；[PROTOCOL.md](PROTOCOL.md)是可执行的形式。它是[dogfood-lab](https://github.com/dogfood-lab)系列的一部分——用于在人工智能时代构建方法和示例。
 
-采用 MIT 许可。
+采用MIT许可证。
 
 ---
 

package/SECURITY.md

@@ -1,15 +1,15 @@
 # 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.)
+`study-swarm` is the study-swarm methodology (Markdown) plus a **thin, zero-dependency command-line tool**, published as the npm package `@dogfood-lab/study-swarm`. The CLI ships in the package (`bin/study-swarm.mjs`), so installing it exposes a `study-swarm` executable. It has **no runtime dependencies** and makes **no network or model calls** — the model-based verification the methodology describes (Step 4) is run by separate tools, not by this 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.
+- **What it runs:** a small Node CLI (Node >= 18). `protocol`, `version`, and `help` only print text. `lint <file>` **reads** the file you name. `new <slug>` **writes** exactly one file — `<slug>.dispatch.md` — in the current working directory, and refuses to overwrite an existing file. The slug is sanitized to a single filename (path separators are replaced with `-`, pure-dots slugs rejected), so `new` cannot write outside the current directory.
+- **What it does NOT do:** no network access, no model calls, no telemetry, no filesystem access beyond the two cases above, no use of credentials or environment beyond what Node needs to run.
+- **Secrets/credentials:** none in source or output.
+- **Permissions required:** filesystem read for `lint`; one-file write (in the working directory) for `new`. Nothing else.
 
-The methodology *describes* a workflow that uses web retrieval and model-based verification, but this repository does not implement or execute that workflow.
+The methodology *describes* a workflow that uses web retrieval and model-based verification; those are performed by the sibling tools ([prism-verify](https://github.com/mcp-tool-shop-org/prism-verify), [role-os](https://github.com/mcp-tool-shop-org/role-os)), not by this package.
 
 ## Supported versions
 

package/bin/study-swarm.mjs

@@ -1,13 +1,15 @@
 #!/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 { readFileSync, writeFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, join } from 'node:path';
+import { createHash } from 'node:crypto';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf8'));
 const VERSION = PKG.version;
+const PROTOCOL_PATH = resolve(__dirname, '../PROTOCOL.md');
 
 const HELP = `study-swarm v${VERSION} — ground design decisions in cited research, then verify.
 
@@ -15,17 +17,24 @@ 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.
+  protocol                 Print the locked protocol (the five steps + halt rules).
+  new <slug>               Scaffold a dispatch file <slug>.dispatch.md to fill in.
+  lint [--json] <path...>  Check dispatches' citations against the sourcing standard.
+                           A <path> may be a file, a directory (linted recursively for
+                           *.dispatch.md), or "-" to read one dispatch from stdin.
+  help                     Show this help.
+  version                  Print the version.
 
 EXIT CODES
   0  ok / lint clean
   1  lint found sourcing violations
   2  usage or runtime error
 
+NOTE
+  lint checks citation FORM (Step 3: author + year + a resolvable arXiv/DOI/URL,
+  no "studies show…" gestures) — it does not judge whether a source is legitimate
+  or actually supports the claim. That is Step 4, below.
+
 Run a dispatch's model-based verification with: roleos verify-citations <file>
 Docs: https://dogfood-lab.github.io/study-swarm/
 `;
@@ -35,19 +44,29 @@ function fail(code, msg) {
   process.exit(code);
 }
 
+// Short hash of the vendored PROTOCOL.md, so a scaffolded dispatch records the exact
+// methodology version it was authored against (the package vendors PROTOCOL.md for this).
+function protocolHash() {
+  try { return createHash('sha256').update(readFileSync(PROTOCOL_PATH)).digest('hex').slice(0, 16); }
+  catch { return 'unknown'; }
+}
+
 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'));
+  if (!existsSync(PROTOCOL_PATH)) fail(2, 'PROTOCOL.md not found in package');
+  try { process.stdout.write(readFileSync(PROTOCOL_PATH, 'utf8')); }
+  catch (err) { fail(2, `cannot read PROTOCOL.md in package: ${err && err.code ? err.code : err.message}`); }
 }
 
-const template = (slug) => `# Study-swarm dispatch: ${slug}
+const template = (slug, stamp) => `<!-- ${stamp} -->
+# 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. -->
+<!-- 3-5 questions where empirical evidence would change the answer. Fewer is fine if the decision is substantial.
+     A question is load-bearing if you can picture two designs hinging on the answer and the honest current
+     answer is "I think…", not "evidence says…". Don't manufacture questions to hit a count. -->
 1.
 2.
 3.
@@ -57,7 +76,8 @@ const template = (slug) => `# Study-swarm dispatch: ${slug}
 
 ## Step 3 — Research grounding
 <!-- One entry per finding (this is what 'lint' checks):
-     N. **<finding>.** <Authors> <year> (<arXiv:NNNN.NNNNN | DOI>). <design implication>. -->
+     N. **<finding>.** <Authors> <year> (<arXiv:NNNN.NNNNN | DOI>). <design implication>.
+     e.g.: 1. **Contrastive explanations with a predicted human foil improve independent decisions.** Buçinca et al. 2024 (arXiv:2410.04253). Implication: every recommendation carries a "you might think X; I chose Y because…" frame. -->
 1. **<finding>.** <Authors> <year> (arXiv:____.____). <implication>.
 
 ## Step 4 — External verification
@@ -73,60 +93,168 @@ const template = (slug) => `# Study-swarm dispatch: ${slug}
 
 function cmdNew(slug) {
   if (!slug) fail(2, 'usage: study-swarm new <slug>');
-  const safe = String(slug).replace(/\.dispatch\.md$/i, '').replace(/[^\w.\-/]/g, '-');
+  // Reduce the slug to a single safe filename: strip any trailing .dispatch.md (even if
+  // repeated), then collapse anything that isn't a word char, dot, or hyphen to '-'. Path
+  // separators ('/' and '\') are NOT permitted — `new` writes ONE file in the current
+  // directory and must never traverse out of it. A pure-dots slug ('.', '..') is rejected.
+  const stem = String(slug).replace(/(\.dispatch\.md)+$/i, '');
+  const safe = stem.replace(/[^\w.\-]/g, '-');
+  if (!safe || /^\.+$/.test(safe)) {
+    fail(2, `invalid slug "${slug}" — use letters, digits, '.', or '-' (the file stays in the current directory)`);
+  }
   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`);
+  // Provenance stamp: pins the methodology version a dispatch was authored against.
+  const stamp = `study-swarm v${VERSION} · protocol-sha256:${protocolHash()} · created:${new Date().toISOString().slice(0, 10)}`;
+  writeFileSync(out, template(safe, stamp), 'utf8');
+  const note = safe === stem ? '' : ` (slug sanitized to "${safe}")`;
+  process.stdout.write(`Created ${out}${note}\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/);
+// --- lint core ------------------------------------------------------------
 
-  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).');
+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;
+// An author cite: a capitalized name (Unicode-aware, so "Buçinca" counts), optionally
+// followed by "et al.", "&", "and", or further surnames, immediately before the year.
+// Accepts "Huang et al. 2023", "Walters & Wilder 2023", "Panickssery, Bowman & Feng 2024";
+// flags an author-less finding like "**Foo.** 2024 (arXiv:…)".
+const AUTHOR = /\p{Lu}[\p{L}.'’-]+(?:\s*,?\s*(?:&|and|et al\.?|\p{Lu}[\p{L}.'’-]+))*\s+\(?(?:19|20)\d{2}/u;
+
+// Check one dispatch's text. Returns a structured result; never exits.
+function lintText(label, raw) {
+  const lines = raw.split(/\r?\n/);
+  const problems = []; // { finding, line, rule, message }
+  const add = (rule, message, line = null, finding = null) => problems.push({ finding, line, rule, message });
+
+  // Find the "Research grounding" heading whose TEXT ends with that phrase (last wins), so a
+  // title that merely mentions "research grounding" above the real section can't shadow it.
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const h = lines[i].match(/^#{1,6}\s+(.*?)\s*$/);
+    if (h && /research grounding$/i.test(h[1])) start = i;
+  }
+  if (start === -1) {
+    add('no-section', 'no "Research grounding" section found — every dispatch needs one (Step 3).');
+    return { file: label, ok: false, findingCount: 0, problems, findings: [] };
+  }
   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 = [];
+  // Split into findings (numbered items + continuation lines), ignoring fenced code blocks
+  // so a "1." inside a ``` example isn't mistaken for a finding. Track each finding's line.
+  const findings = []; // { text, line }
   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);
+  let inFence = false;
+  section.forEach((l, idx) => {
+    if (/^\s*(```|~~~)/.test(l)) { inFence = !inFence; return; }
+    if (inFence) return;
+    if (/^\s*\d+\.\s/.test(l)) { if (cur) findings.push(cur); cur = { text: l, line: start + 2 + idx }; }
+    else if (cur && l.trim()) cur.text += ' ' + l.trim();
+  });
+  if (cur) findings.push(cur);
+
+  if (findings.length === 0) add('no-findings', 'Research grounding has no numbered findings.');
 
-  const problems = [];
-  if (findings.length === 0) problems.push('Research grounding has no numbered findings.');
+  const parsed = [];
   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).`);
+    if (PLACEHOLDER.test(f.text)) add('placeholder', `finding ${n}: still has template placeholders — fill it in.`, f.line, n);
+    // Strip identifiers before the year check so an arXiv id's YYMM prefix
+    // (e.g. 2402 in arXiv:2402.01817) can't masquerade as a publication year.
+    const fNoIds = f.text.replace(/arxiv:\s*\d{4}\.\d{4,5}/gi, '').replace(/10\.\d{4,9}\/\S+/g, '');
+    if (!YEAR.test(fNoIds)) add('missing-year', `finding ${n}: missing a year (spell it out, e.g. "2024" — an arXiv id alone is not a year).`, f.line, n);
+    if (!AUTHOR.test(f.text)) add('missing-author', `finding ${n}: missing an author before the year (e.g. "Huang et al. 2023").`, f.line, n);
+    const idm = f.text.match(ID);
+    if (!idm) add('missing-id', `finding ${n}: missing an identifier (arXiv:NNNN.NNNNN, DOI, or URL).`, f.line, n);
+    const ym = fNoIds.match(YEAR);
+    const ident = idm ? idm[0].replace(/\s+/g, '').replace(/[).,;]+$/, '') : null;
+    parsed.push({ finding: n, year: ym ? ym[0] : null, identifier: ident });
   });
-  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)}"`);
+
+  // Banned gesture anywhere in the section (outside fences): a finding STATES its result,
+  // it never "studies show…" — a co-located citation doesn't redeem it.
+  let fence = false;
+  section.forEach((l, idx) => {
+    if (/^\s*(```|~~~)/.test(l)) { fence = !fence; return; }
+    if (!fence && BANNED.test(l)) {
+      add('banned-gesture', `line ${start + 2 + idx}: name the study (author + year + identifier), don't gesture: "${l.trim().slice(0, 56)}"`, start + 2 + idx);
     }
   });
 
-  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);
+  return { file: label, ok: problems.length === 0, findingCount: findings.length, problems, findings: parsed };
+}
+
+// Recursively collect *.dispatch.md files under a directory (skips node_modules/.git).
+function walkDispatches(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkDispatches(full));
+    else if (/\.dispatch\.md$/i.test(entry.name)) out.push(full);
+  }
+  return out.sort();
+}
+
+function readTarget(p) {
+  try { return { label: p, raw: readFileSync(p, 'utf8') }; }
+  catch (err) { fail(2, `cannot read ${p}: ${err && err.code ? err.code : err.message}`); }
+}
+
+function cmdLint(args) {
+  const json = args.includes('--json');
+  const paths = args.filter((a) => a !== '--json');
+  if (paths.length === 0) fail(2, 'usage: study-swarm lint [--json] <file|dir|-> [more...]');
+
+  const targets = [];
+  for (const p of paths) {
+    if (p === '-') {
+      let raw;
+      try { raw = readFileSync(0, 'utf8'); }
+      catch (err) { fail(2, `cannot read stdin: ${err && err.code ? err.code : err.message}`); }
+      targets.push({ label: '<stdin>', raw });
+      continue;
+    }
+    if (!existsSync(p)) fail(2, `path not found: ${p}`);
+    if (statSync(p).isDirectory()) {
+      const files = walkDispatches(p);
+      if (files.length === 0) fail(2, `no .dispatch.md files found under ${p}`);
+      for (const f of files) targets.push(readTarget(f));
+    } else {
+      targets.push(readTarget(p));
+    }
+  }
+
+  const results = targets.map((t) => lintText(t.label, t.raw));
+  const anyFail = results.some((r) => !r.ok);
+
+  if (json) {
+    const payload = results.length === 1 ? results[0] : { ok: !anyFail, files: results };
+    process.stdout.write(JSON.stringify(payload) + '\n');
+    process.exit(anyFail ? 1 : 0);
+  }
+
+  for (const r of results) {
+    if (r.ok) {
+      process.stdout.write(`ok ${r.file}: ${r.findingCount} finding(s), all sourced.\n`);
+    } else {
+      process.stderr.write(`x ${r.file}: ${r.problems.length} sourcing issue(s)\n`);
+      for (const pr of r.problems) process.stderr.write(`  - ${pr.message}\n`);
+    }
+  }
+  if (!anyFail) {
+    process.stdout.write(
+      `\nStep 3 (sourcing FORM) is satisfied — this does NOT confirm the citations exist or support the claim.\n` +
+      `Run Step 4 (existence + groundedness, a different model family):  roleos verify-citations <file>\n`,
+    );
   }
-  process.stdout.write(`ok ${file}: ${findings.length} finding(s), all sourced.\n`);
+  process.exit(anyFail ? 1 : 0);
 }
 
 function main(argv) {
@@ -134,7 +262,7 @@ function main(argv) {
   switch (cmd) {
     case 'protocol': return cmdProtocol();
     case 'new': return cmdNew(rest[0]);
-    case 'lint': return cmdLint(rest[0]);
+    case 'lint': return cmdLint(rest);
     case 'version': case '--version': case '-v':
       return void process.stdout.write(VERSION + '\n');
     case 'help': case '--help': case '-h': case undefined:

package/examples/study-swarm-ci.yml

@@ -0,0 +1,28 @@
+# Copy this into YOUR repo at .github/workflows/dispatches.yml to gate the sourcing
+# of every study-swarm dispatch on each pull request. It is a SAMPLE — it is not an
+# active workflow in the study-swarm repo itself.
+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
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      # Lint every dispatch under dispatches/ (a file, a dir, or '-' for stdin all work).
+      # Exit 1 on any sourcing violation fails the check. Add --json for machine-readable output.
+      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/

package/examples/study-swarm-self.dispatch.md

@@ -0,0 +1,46 @@
+<!-- study-swarm vX.Y.Z · protocol-sha256:<vendored> · a worked, lint-clean reference dispatch -->
+# Study-swarm dispatch: study-swarm-self
+
+> A complete, **lint-clean** example dispatch — study-swarm applied to its own
+> central design decision. Run `study-swarm lint examples/study-swarm-self.dispatch.md`
+> (it passes), then read it as a model for what a filled-in dispatch looks like end to end.
+
+## Step 1 — Load-bearing questions
+
+<!-- Each is load-bearing: two real designs hinge on the answer, and the honest prior is "I think", not "evidence says". -->
+
+1. When an LLM makes a substantial design call, can the *same* model reliably verify its own citations, or does the verifier have to be a separate model?
+2. Is confirming a cited paper *exists* enough, or must "the source supports this claim" be checked as a separate axis?
+3. Does adding *more* verifiers improve coverage, or does the diversity of the verifiers matter more than their count?
+
+## Step 2 — Research dispatch
+
+<!-- One research agent per question, in parallel; each returned paper titles + authors + years + URLs + a one-sentence finding, web-retrieval required (no recall-only citations). -->
+
+Three parallel agents, scoped to empirical evidence (not opinion), word-capped, "specificity over breadth — 6–8 well-sourced findings beat 20 vague gestures." Their citations (below) were then resolved against arXiv/Crossref before any informed the design.
+
+## Step 3 — Research grounding
+
+1. **LLMs struggle to self-correct without external feedback, and can degrade after self-correction.** Huang et al. 2023 (arXiv:2310.01798). Implication: the verifier cannot be the generator itself — an external check is required (answers Q1).
+2. **Autoregressive LLMs cannot self-verify; pair the generator with an external model-based verifier.** Kambhampati et al. 2024 (arXiv:2402.01817). Implication: the architecture is generator + separate verifier, not self-critique (answers Q1).
+3. **An LLM judge's self-recognition correlates *linearly* with its self-preference bias.** Panickssery, Bowman & Feng 2024 (arXiv:2404.13076). Implication: the verifier must be a *different model family*, since partial blinding of a same-family judge does not remove the bias (answers Q1).
+4. **18–55% of LLM-generated citations are fabricated, and many real ones carry bibliographic errors.** Walters & Wilder 2023 (doi:10.1038/s41598-023-41032-5). Implication: existence must be established by *retrieval* (resolve the arXiv/DOI), never by the model's recall (answers Q2).
+5. **Cited links resolve >94% of the time, yet only 39–77% of the content actually supports the claim.** Onweller et al. 2026 (arXiv:2605.06635). Implication: groundedness is a distinct axis from existence — "the link resolves" is not "the paper says this" (answers Q2).
+6. **Decorrelated verifiers (pairwise ρ ∈ [0.05, 0.25]) beat any single one via submodular coverage.** Rajan 2025 (arXiv:2511.16708). Implication: spend the budget on *lens diversity* (a retrieval oracle + ≥2 different families), not on more copies of one judge (answers Q3).
+
+## Step 4 — External verification
+
+<!-- This dispatch's own citations were gated this way before Step 5 was written. -->
+
+- [x] every citation resolved by retrieval (arXiv/DOI), not model memory — arXiv API + OpenAlex + Crossref
+- [x] every finding matches what its source actually claims (groundedness) — checked against each abstract
+- [x] >= 3 decorrelated lenses (retrieval oracle + >= 2 different model families) — oracle + Mistral + IBM Granite, reasoning-stripped
+
+Result: all six citations VERIFIED (existence + attribution + groundedness). Two blind traps seeded into a sibling set — a misattribution and a fabricated paper — were caught by the *union* of the two families, not either alone.
+
+## Step 5 — Architecture
+
+- The verifier is a **different model family** from the synthesizer, run reasoning-stripped. (findings 1, 2, 3)
+- Verification is **two-stage per citation**: a retrieval oracle confirms existence, then a groundedness lens confirms the source supports the claim. (findings 4, 5)
+- The verifier is an **ensemble of decorrelated lenses** (retrieval oracle + ≥2 different families), because diversity — not count — drives coverage. (finding 6)
+- On a non-clean verdict the finding **halts** (fabricated → dropped; misattributed → corrected once; unavailable → escalate), never silently proceeds. (findings 1, 4)