@dogfood-lab/study-swarm 1.3.0 → 2.1.0

package/README.zh.md

@@ -23,13 +23,13 @@
 
 1. **确定** 3 到 5 个关键的结构设计问题，这些问题的答案可以通过实证证据来改变。
 2. **指派** 一名研究人员负责每个问题，并让他们并行工作。每位研究人员必须提供论文标题、作者、发表年份、网址以及一个简短的结论（强调具体性而非广泛性，“6 到 8 个有充分依据的结论胜过 20 个含糊不清的描述”）。
-3. **综合** 这些结论，形成一个“*研究基础*”部分：`N. **<结论>.** <作者> <年份> (<arXiv/DOI>)。 <设计启示>。`
-4. **进行外部验证**——使用一种*不同的模型系列*，去除推理能力后，分两个阶段检查所有引用文献：首先，一个**检索预言机**确认论文是否存在（绝不能依赖模型的记忆），然后，一个**真实性评估工具**确认结论是否与来源一致。如果发现捏造或错误归因的引用，则立即**停止**；如果验证者或检索预言机不可用，则**停止并升级处理**（切勿将无法找到的情况解读为“引用没有问题”）。
+3. **综合** 这些结论，形成一个*Research grounding*（研究基础）部分：`N. **<结论>.** <作者> <年份> (<arXiv/DOI>)。 <设计启示>。`
+4. **进行外部验证**——使用一种*不同的模型系列*，在隐藏生成者推理的前提下，分两个阶段检查所有引用文献：首先，一个**检索预言机**确认论文是否存在（绝不能依赖模型的记忆），然后，一个**真实性评估工具**确认结论是否与来源一致。捏造的结论**丢弃**；错误归属**纠正一次**并重新验证（第二次仍不干净则丢弃）。仅当验证者或检索预言机不可用时才**停止并升级处理**（切勿将无法找到的情况解读为“引用没有问题”）。
 5. **将**每个结构设计选择与相应的结论联系起来，通过编号进行关联。如果没有明确的设计启示，那么这些引用就是噪音。
 
-完整的可执行细节——包括停止表、源标准和集成规则——都可以在**[PROTOCOL.md]**文件中找到。
+完整的可执行细节——包括停止表、源标准和集成规则——都可以在**[PROTOCOL.md](PROTOCOL.md)**文件中找到。
 
-## 为什么会是另外一个家庭？而且，请不要再进行任何推测
+## 为什么要换一个模型系列，并隐藏生成者的推理？
 
 因为这里记录的是实际发生的故障模式，而不是假设的故障模式：
 
@@ -75,12 +75,15 @@ npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-sw
 |---|---|
 | `study-swarm protocol` | 打印完整的协议——五个步骤、停止表以及来源标准。 |
 | `study-swarm new <slug>` | 创建一个`<slug>.dispatch.md`文件，其中包含五步流程的框架，以便进行填充。 |
-| `study-swarm lint [--json] <path…>` | 根据来源标准检查工作流程的*研究扎实性*——每条研究结果都需要作者、年份和一个可解析的标识符（arXiv / DOI / URL）；“研究表明……”这种含糊其辞的方式将被拒绝。如果存在违规行为，则退出代码为`1`，以便在CI中进行筛选。`<path>`可以是文件、目录（递归地检查所有`.dispatch.md`文件），或者`-`表示标准输入；`--json`会输出机器可读的报告。 |
-| `study-swarm lock <dispatch> --from <orchestration.json>` | 将一个调度固定下来以便重放——编写 `<dispatch>.lock.json`，其中包含基于内容的哈希值，按照步骤 2 中的代理进行操作，包括**已解析的模型 ID** + **字节级精确提示的 SHA-256 值** + **工具模式的 SHA-256 值**，以及步骤 4 中的**验证者凭证**，并将它们组合成一个 `lock_sha256`。 |
+| `study-swarm lint [--json] [--strict] <path…>` | 检查某个报告的*Research grounding*（研究依据），并对照来源标准进行验证——每个发现都需要有作者、年份和可解析的标识符（arXiv / DOI / URL / RFC）；禁止使用含糊不清的表述，例如“研究表明……”。如果存在违规情况，则返回 `1`，从而阻止 CI 流程。`<path>` 可以是文件、目录（递归地检查所有 `*.dispatch.md` 文件），或者 `-` 表示标准输入；`--json` 会输出机器可读的报告。`--strict` 还会标记“孤立引用”——即某个发现没有被任何第五步选项引用，因为“没有关联的引用是无用的”（可选功能，因此默认的 CI 流程不会改变）。 |
+| `study-swarm return <dispatch> [--check]` | 写出结果：`<stem>.results.md` 是交给人的一页，`<stem>.results.json` 把同样的事实留在 dispatch 旁边给下一次运行打开。`--check` 在任一副本与 dispatch 不一致时失败。 |
+| `study-swarm lock --init <dispatch>` | 生成 `<dispatch>.orchestration.json` 文件——这是一个填空式的框架记录（每个步骤对应一个第二步中的代理），用于提供给 `lock … --from` 命令。 |
+| `study-swarm lock <dispatch> --from <orchestration.json>` | 将一个调度固定下来以便重放——编写 `<dispatch>.lock.json`，其中包含基于内容的哈希值，按照步骤 2 中的代理进行操作，包括**已解析的模型 ID** + **文本规范化提示的 SHA-256（去掉 BOM，换行折成 LF，NFC）** + **工具模式的 SHA-256 值**，以及步骤 4 中的**验证者凭证**，并将它们组合成一个 `lock_sha256`。 |
 | `study-swarm lock --verify <dispatch> [--from …]` | 重新计算这些哈希值并确认它们与锁匹配；如果出现任何偏差，则退出并返回 1，因此它就像软件包的 lock 文件一样，可以控制 CI 流程。如果不使用 `--from` 参数，则会检查锁自身的完整性。 |
 | `study-swarm withdraw <id> --reason <reason> [--from <dir>] [--receipt <path>]` | **规范回滚补偿器。** 标记语料库中每个引用 `<id>` 作为“证据已撤回”（一个墓碑侧文件 `<slug>.withdrawn.json`——标记，永不删除）的文档，并生成基于内容的撤回凭证。 `--reason` ∈ `fabricated · misattributed · retracted · verifier-flipped · other`。 |
 | `study-swarm requalify --check <corpus-dir>` | 对于任何带有未解决的“证据已撤回”标志的文档，执行失败安全机制（退出代码为 `1`）——这是一种“andon”（警报），它会**阻止**已撤回结论的依赖项，直到该结论被删除或重新验证。用于门控 CI。 |
-| `study-swarm requalify --resolve <dispatch> <id> --mode removed\ | regrounded [--note …]` | 一旦该结论被删除（引用消失）或重新验证（由辅助运行器重新验证；`--note` 记录证明），则清除标志。幂等性；附加到侧文件的审计跟踪中。 |
+| `study-swarm requalify --status <corpus-dir> [--json]` | 以只读方式查看语料库的“证据健康状况”——包括已撤回和已解决的数量、按原因和解决方法分类，以及每个报告的行数。这是一个信息性输出（返回 `0`），与 `--check` 流程不同。 |
+| `study-swarm requalify --resolve <dispatch> <id> --mode removed\|regrounded [--note …]` | 一旦该结论被删除（引用消失）或重新验证（由辅助运行器重新验证；`--note` 记录证明），则清除标志。幂等性；附加到侧文件的审计跟踪中。 |
 
 `lint`是确定性的——不调用任何模型——因此可以在CI中安全使用。它在本地强制执行**第3步的来源标准**；基于模型的**第4步**验证仍然依赖于[`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism。
 
@@ -104,7 +107,7 @@ roleos verify-citations my-decision.dispatch.md  # model-based Step 4 (different
 name: study-swarm lint
 on:
   pull_request:
-    paths: ['**/*.dispatch.md', '.github/workflows/dispatches.yml']
+    paths: ['**/*.dispatch.md', '**/*.withdrawn.json', '.github/workflows/dispatches.yml']
   workflow_dispatch:
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -112,16 +115,20 @@ concurrency:
 jobs:
   lint:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: '20' }
-      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
+      - run: npx --yes @dogfood-lab/study-swarm@2.1.0 lint dispatches/
+      # Halt the build while any finding that became canon is withdrawn and not yet
+      # removed or re-grounded — the canon-rollback andon (exit 1 on any unresolved flag).
+      - run: npx --yes @dogfood-lab/study-swarm@2.1.0 requalify --check dispatches/
 ```
 
 ### 将一个调度固定下来以便重放 (`dispatch.lock.json`)
 
-只有当你能够说明*是什么产生了它*时，才能对经过验证的调度进行审计。`study-swarm lock` 编写一个配套的锁文件，该文件基于内容进行哈希处理，按照研究代理进行操作，包括**已解析的模型 ID（绝不使用浮动别名）**、**字节级精确提示的 SHA-256 值**以及**工具模式的 SHA-256 值**，以及外部**验证者凭证**——所有这些都组合成一个 `lock_sha256`。`study-swarm lock --verify` 重新计算这些哈希值，并且如果出现任何偏差，则会失败并停止，因此，如果提示、模型或工具发生更改，系统都会检测到——这是 [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm) 可重复性标准的可执行版本。该框架会输出记录；CLI 保持零依赖和无网络状态，仅进行规范化（RFC 8785）、哈希处理和验证。
+只有当你能够说明*是什么产生了它*时，才能对经过验证的调度进行审计。`study-swarm lock` 编写一个配套的锁文件，该文件基于内容进行哈希处理，按照研究代理进行操作，包括**已解析的模型 ID（绝不使用浮动别名）**、**文本规范化提示的 SHA-256（去掉 BOM，换行折成 LF，NFC）**以及**工具模式的 SHA-256 值**，以及外部**验证者凭证**——所有这些都组合成一个 `lock_sha256`。`study-swarm lock --verify` 重新计算这些哈希值，并且如果出现任何偏差，则会失败并停止，因此，如果提示、模型或工具发生更改，系统都会检测到——这是 [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm) 可重复性标准的可执行版本。该框架会输出记录；CLI 保持零依赖和无网络状态，仅进行规范化（RFC 8785）、哈希处理和验证。
 
 **它固定输入，而不是输出。** 固定模型 + 提示 + 温度并不能使 LLM 的输出完全相同——批处理不变性、浮点数非结合律、混合专家路由以及无声提供者漂移都超出了离线工具的控制范围。因此，该锁为您提供**可重放的输入和可检测偏差的输出**，而不是“确定性重放”。该设计基于 [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) 中的每一处引用，并且是第一个发布其自身锁（[`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json)）的调度文件。
 
@@ -145,11 +152,11 @@ study-swarm requalify --resolve d.dispatch.md arXiv:2402.15089 --mode removed
 
 ## 安全性
 
-`study-swarm`提供了一个**轻量级、零依赖的CLI**（`study-swarm`），以及该方法论。它**不进行任何网络或模型调用，也不收集任何遥测数据**；源代码中没有秘密或凭据。在运行时，它只会读取您传递给`lint`的文件，并在当前目录中写入一个`<slug>.dispatch.md`文件（拒绝覆盖，并且绝不会超出工作目录）。该方法论描述的基于模型的验证（第4步）由辅助工具执行，而不是由此软件包执行。请参阅[SECURITY.md](SECURITY.md)。
+`study-swarm`提供了一个**轻量级、零依赖的CLI**（`study-swarm`），以及该方法论。它**不进行任何网络或模型调用，也不收集任何遥测数据**；源代码中没有秘密或凭据。在运行时，它读取你指定的文件。`new` 在工作目录中写入一个 `<slug>.dispatch.md`（不覆盖，也不写到目录外）。`lock`、`withdraw` 和 `requalify` 还会写入 lock 文件、墓碑 sidecar，以及在传入 `--receipt` 时按你给出的路径写入回执。该方法论描述的基于模型的验证（第4步）由辅助工具执行，而不是由此软件包执行。请参阅[SECURITY.md](SECURITY.md)。
 
 ## 状态
 
-一个可工作的协议，由其自身的机制进行外部验证——不同的模型系列检查其引用（参见上面的证明）。**v1.1** 改进了验证器，而第一个版本是静默的：分解/三元验证、生成时验证、用于组合透镜的基于 oracle 的级联以及校准后的弃权——每个都基于经过验证的 v1.1 文档。**v1.2** 使文档可重放：`study-swarm lock` 为每个步骤固定已解决的模型、提示和工具模式，以及验证器凭证，并且 `lock --verify` 在检测到漂移时会失败安全。**v1.3** 使回滚操作可执行：当已经成为规范的结论被撤回时，`study-swarm withdraw` 会标记所有依赖项，并且 `requalify --check` 会阻止它们，直到它们被删除或重新验证——这是一种命名的、带有凭证的、幂等的补偿器。此仓库是公共参考；[PROTOCOL.md](PROTOCOL.md) 是可执行的形式。它是 [dogfood-lab](https://github.com/dogfood-lab) 系列的一部分——用于在人工智能时代构建的方法和示例。
+一个可行的协议，通过其自身的机制进行外部验证——不同的模型系列会检查其引用（参见上面的证明）。**v1.1** 版本改进了验证器，解决了首次发布版本中存在的不足：分解/三元依据、生成时间依据、用于组合不同视角的基于预言机的级联方法以及校准的弃权机制——所有这些都以经过验证的 v1.1 报告为基础。**v1.2** 版本使报告能够进行字节级别的重放：`study-swarm lock` 命令会固定每个步骤中已解决的模型、提示和工具模式，以及验证器收据；`lock --verify` 命令会在检测到漂移时停止流程。**v1.3** 版本使回滚操作可执行：当某个已经成为标准的事实被撤回时，`study-swarm withdraw` 命令会标记所有相关的依赖项，并且 `requalify --check` 命令会暂停这些依赖项的运行，直到它们被删除或重新验证——这是一个命名的、带有收据的、幂等的补偿器。**v2.0** 版本使协议中的更多部分可执行，并加强了锁定机制：`lint --strict` 命令会标记孤立引用——这是 CLI 无法捕获的唯一一种失败模式；`lock --init` 命令会生成框架记录；`requalify --status` 命令会读取语料库的证据健康状况；锁定的内容寻址是领域隔离的（工件模式 v2——来自早期版本的锁定会被重新生成，而不是被错误地标记为已篡改；CLI 的命令界面保持向后兼容）。此仓库是公共参考；[PROTOCOL.md](PROTOCOL.md) 是可执行的形式。它是 [dogfood-lab](https://github.com/dogfood-lab) 系列的一部分——用于构建人工智能时代的方法和示例。
 
 采用MIT许可证。
 

package/SECURITY.md

@@ -4,10 +4,10 @@
 
 ## Threat model
 
-- **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.
+- **What it runs:** a small Node CLI (Node >= 18). `protocol`, `version`, and `help` only print text. `lint <path…>` **reads** the files (or stdin) 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 replaced with `-`, pure-dots slugs rejected), so `new` cannot write outside the current directory. `lock`, `withdraw`, and `requalify` **read** the dispatch / orchestration / sidecar files you name and **write** JSON artifacts at paths you supply: a `<dispatch>.lock.json` or `<dispatch>.withdrawn.json` co-located with the dispatch you point at, and (for `withdraw --receipt <path>`) a receipt at the exact path you give. Unlike `new`, these paths are taken as given — no traversal sanitization — because the commands operate on artifacts you name explicitly; they write where you point them (like `cp` or `tee`), never anywhere derived from untrusted input.
+- **What it does NOT do:** no network access, no model calls, no telemetry, no use of credentials or environment beyond what Node needs to run, and no filesystem access beyond reading the inputs you name and writing the artifacts described above.
 - **Secrets/credentials:** none in source or output.
-- **Permissions required:** filesystem read for `lint`; one-file write (in the working directory) for `new`. Nothing else.
+- **Permissions required:** filesystem read for the paths you pass to `lint`, `lock`, `withdraw`, and `requalify`. Writes: one new file in the working directory for `new`; a lock JSON or tombstone sidecar next to the dispatch you name; and, for `withdraw --receipt <path>`, a receipt at that exact path. Those receipt and artifact paths are the paths you supply.
 
 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.
 
@@ -15,9 +15,10 @@ The methodology *describes* a workflow that uses web retrieval and model-based v
 
 | Version | Supported |
 |---------|-----------|
-| 1.x     | ✅        |
+| 2.x     | ✅        |
+| 1.x     | commands still run; regenerate v1 locks |
 | < 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.
+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>. We aim to acknowledge within 7 days.