@dogfood-lab/study-swarm 2.0.0 → 2.1.0

package/README.md

@@ -24,7 +24,7 @@ It applies its own medicine. The protocol prescribes verifier-protected envelope
 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").
+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. **Drop** a fabricated finding; **correct a misattribution once** and re-verify (a second non-clean verdict drops it). **Halt-and-escalate** only when the verifier or the 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)**.
@@ -76,8 +76,9 @@ 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 [--json] [--strict] <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 / RFC); "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. `--strict` additionally flags **orphan citations** — a finding no Step-5 choice references — since "citations without a connection are noise" (opt-in, so the default CI gate is unchanged). |
+| `study-swarm return <dispatch> [--check]` | Write the results of a dispatch: `<stem>.results.md` is the sheet you hand someone, and `<stem>.results.json` is the same facts kept beside it for the next run to open. `--check` fails if either copy has drifted from the dispatch. |
 | `study-swarm lock --init <dispatch>` | Scaffold `<dispatch>.orchestration.json` — a fill-in-the-blanks harness record (one step per Step-2 agent) to feed to `lock … --from`. |
-| `study-swarm lock <dispatch> --from <orchestration.json>` | Pin a dispatch for replay — write `<dispatch>.lock.json` content-addressing, per Step-2 agent, the **resolved model id** + the **SHA-256 of the byte-exact prompt** + the **SHA-256 of the tool schema**, plus the Step-4 **verifier receipt**, rolled into one `lock_sha256`. |
+| `study-swarm lock <dispatch> --from <orchestration.json>` | Pin a dispatch for replay — write `<dispatch>.lock.json` content-addressing, per Step-2 agent, the **resolved model id** + the **SHA-256 of the text-normalized prompt** (BOM stripped, newlines folded to LF, NFC) + the **SHA-256 of the tool schema**, plus the Step-4 **verifier receipt**, rolled into one `lock_sha256`. |
 | `study-swarm lock --verify <dispatch> [--from …]` | Re-derive those hashes and assert they match the lock; any drift exits `1`, so it gates CI like a package lockfile. Without `--from`, checks the lock's own integrity. |
 | `study-swarm withdraw <id> --reason <reason> [--from <dir>] [--receipt <path>]` | **Canon-rollback compensator.** Flag every dispatch in the corpus whose *Research grounding* cites `<id>` as `evidence-withdrawn` (a tombstone sidecar `<slug>.withdrawn.json` — flag, never delete) and emit a content-addressed withdrawal receipt. `--reason` ∈ `fabricated · misattributed · retracted · verifier-flipped · other`. |
 | `study-swarm requalify --check <corpus-dir>` | Fail closed (exit `1`) for any dispatch carrying an unresolved `evidence-withdrawn` flag — the andon that **halts** a withdrawn finding's dependents until it is removed or re-grounded. Gates CI. |
@@ -106,7 +107,7 @@ Four complete, lint-clean worked dispatches ship as references: [`examples/study
 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 }}
@@ -119,15 +120,15 @@ jobs:
       - 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 @dogfood-lab/study-swarm@latest requalify --check dispatches/
+      - run: npx --yes @dogfood-lab/study-swarm@2.1.0 requalify --check dispatches/
 ```
 
 ### Pin a dispatch for replay (`dispatch.lock.json`)
 
-A grounded, verified dispatch is only auditable if you can say *what produced it*. `study-swarm lock` writes a companion lockfile that content-addresses, per research agent, the **resolved model id** (never a floating alias), the **SHA-256 of the byte-exact prompt**, and the **SHA-256 of the tool schema** it was given, plus the external **verifier receipt** — rolled into one `lock_sha256`. `study-swarm lock --verify` re-derives those hashes and fails closed on any drift, so a changed prompt, a swapped model, or a shifted tool surface is caught — the [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm) reproducibility standard, made executable. The harness emits the record; the CLI stays zero-dependency and network-free, only canonicalizing (RFC 8785), hashing, and validating it.
+A grounded, verified dispatch is only auditable if you can say *what produced it*. `study-swarm lock` writes a companion lockfile that content-addresses, per research agent, the **resolved model id** (never a floating alias), the **SHA-256 of the text-normalized prompt** (BOM stripped, newlines folded to LF, NFC), and the **SHA-256 of the tool schema** it was given, plus the external **verifier receipt** — rolled into one `lock_sha256`. `study-swarm lock --verify` re-derives those hashes and fails closed on any drift, so a changed prompt, a swapped model, or a shifted tool surface is caught — the [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm) reproducibility standard, made executable. The harness emits the record; the CLI stays zero-dependency and network-free, only canonicalizing (RFC 8785), hashing, and validating it.
 
 **It pins inputs, not outputs.** Pinning model + prompt + temperature does *not* make an LLM's output bit-identical — batch-invariance, floating-point non-associativity, mixture-of-experts routing, and silent provider drift are all outside an offline tool's control. So the lock gives you **replayable inputs and drift-detectable outputs**, never "deterministic replay." The design is grounded, citation by citation, in [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) — the first dispatch to ship its own lock ([`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json)).
 
@@ -151,7 +152,7 @@ study-swarm requalify --resolve d.dispatch.md arXiv:2402.15089 --mode removed
 
 ## Security
 
-`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).
+`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 reads the files you name. `new` writes a single `<slug>.dispatch.md` in the current directory (refusing to overwrite, and never outside that directory). `lock`, `withdraw`, and `requalify` also write a lock file, a tombstone sidecar, and — when you pass `--receipt` — a receipt at the path you give. 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
 

package/README.pt-BR.md

@@ -23,8 +23,8 @@ Ele aplica sua própria abordagem. O protocolo prescreve "envelopes" protegidos
 
 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 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").
+3. **Sintetize** as descobertas em uma seção de *Research grounding* (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. **Descarte** um achado fabricado; **corrija uma atribuição incorreta uma vez** e verifique de novo (um segundo veredito não limpo descarta). **Interrompa e alerte** somente quando 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 do conjunto — estão em **[PROTOCOL.md](PROTOCOL.md)**.
@@ -75,14 +75,15 @@ npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-sw
 |---|---|
 | `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] [--strict] <path…>` | Verifique a *base de pesquisa* de um relatório em relação ao padrão de fontes – cada conclusão deve ter um autor, um ano e um identificador que possa ser localizado (arXiv / DOI / URL / RFC); argumentos vagos do tipo "estudos mostram…" são rejeitados. Retorne `1` em caso de violações, para que isso impeça a execução do CI. Um `<caminho>` pode ser um arquivo, um diretório (verificado recursivamente para `*.dispatch.md`) ou `-` para entrada padrão; `--json` gera um relatório legível por máquina. `--strict` também sinaliza **citações órfãs** – uma conclusão que nenhuma escolha da Etapa 5 referencia –, já que "citações sem conexão são ruído" (opcional, portanto, a configuração padrão do CI permanece inalterada). |
+| `study-swarm lint [--json] [--strict] <path…>` | Verifique a *Research grounding* (base de pesquisa) de um relatório em relação ao padrão de fontes – cada conclusão deve ter um autor, um ano e um identificador que possa ser localizado (arXiv / DOI / URL / RFC); argumentos vagos do tipo "estudos mostram…" são rejeitados. Retorne `1` em caso de violações, para que isso impeça a execução do CI. Um `<caminho>` pode ser um arquivo, um diretório (verificado recursivamente para `*.dispatch.md`) ou `-` para entrada padrão; `--json` gera um relatório legível por máquina. `--strict` também sinaliza **citações órfãs** – uma conclusão que nenhuma escolha da Etapa 5 referencia –, já que "citações sem conexão são ruído" (opcional, portanto, a configuração padrão do CI permanece inalterada). |
+| `study-swarm return <dispatch> [--check]` | Escreve os resultados: `<stem>.results.md` é a folha que se entrega, e `<stem>.results.json` guarda os mesmos fatos ao lado do dispatch para a próxima execução. `--check` falha se alguma das cópias tiver desviado do dispatch. |
 | `study-swarm lock --init <dispatch>` | Crie o arquivo `<dispatch>.orchestration.json` – um modelo de registro para preencher os campos (uma etapa por agente da Etapa 2) para fornecer ao comando `lock … --from`. |
-| `study-swarm lock <dispatch> --from <orchestration.json>` | Fixe um envio para reprodução – crie o arquivo `<dispatch>.lock.json` com informações de conteúdo, conforme o agente da Etapa 2, incluindo o **ID do modelo resolvido** + o **SHA-256 do prompt exato em bytes** + o **SHA-256 do esquema da ferramenta**, mais o **comprovante do verificador** da Etapa 4, tudo reunido em um único arquivo `lock_sha256`. |
+| `study-swarm lock <dispatch> --from <orchestration.json>` | Fixe um envio para reprodução – crie o arquivo `<dispatch>.lock.json` com informações de conteúdo, conforme o agente da Etapa 2, incluindo o **ID do modelo resolvido** + o **SHA-256 do prompt normalizado (BOM removido, quebras de linha em LF, NFC)** + o **SHA-256 do esquema da ferramenta**, mais o **comprovante do verificador** da Etapa 4, tudo reunido em um único arquivo `lock_sha256`. |
 | `study-swarm lock --verify <dispatch> [--from …]` | Recalcule esses hashes e verifique se correspondem ao bloqueio; qualquer desvio resulta em saída `1`, portanto, controla o CI como um arquivo de bloqueio de pacote. Sem `--from`, verifica a própria integridade do bloqueio. |
-| `study-swarm withdraw <id> --reason <reason> [--from <dir>] [--receipt <path>]` | **Mecanismo de compensação para reversão do canon.** Marcar cada registro no corpus cujo *fundamento da pesquisa* cite `<id>` como `evidência-retirada` (um arquivo auxiliar `<slug>.withdrawn.json` — marcar, nunca excluir) e emitir um comprovante de retirada com base no conteúdo. `--reason` ∈ `fabricado · atribuído incorretamente · revogado · verificador alterado · outro`. |
+| `study-swarm withdraw <id> --reason <reason> [--from <dir>] [--receipt <path>]` | **Mecanismo de compensação para reversão do canon.** Marcar cada registro no corpus cuja seção *Research grounding* (fundamento da pesquisa) cite `<id>` como `evidência-retirada` (um arquivo auxiliar `<slug>.withdrawn.json` — marcar, nunca excluir) e emitir um comprovante de retirada com base no conteúdo. `--reason` ∈ `fabricated · misattributed · retracted · verifier-flipped · other` (fabricado, atribuído incorretamente, revogado, verificador alterado, outro). |
 | `study-swarm requalify --check <corpus-dir>` | Falhar em modo fechado (sair com código `1`) para qualquer registro que contenha uma marcação `evidência-retirada` não resolvida — o sinalizador que **interrompe** os elementos dependentes de um resultado retirado até que seja removido ou reavaliado. Gates CI. |
 | `study-swarm requalify --status <corpus-dir> [--json]` | Visualização somente leitura do estado de validade das evidências de um corpus – contagem de conclusões retiradas versus resolvidas, uma divisão por motivo e modo de resolução, linhas por relatório. Informativo (retorna `0`), diferente da verificação `--check`. |
-| `study-swarm requalify --resolve <registro> <id> --mode removed\ | regrounded [--note …]` | Remover uma marcação assim que o resultado for removido (a citação desaparecer) ou reavaliado (reverificado e validado pelo executor irmão; `--note` registra a confirmação). Idempotente; adiciona ao histórico de auditoria do arquivo auxiliar. |
+| `study-swarm requalify --resolve <registro> <id> --mode removed\|regrounded [--note …]` | Remover uma marcação assim que o resultado for removido (a citação desaparecer) ou reavaliado (reverificado e validado pelo executor irmão; `--note` registra a confirmação). Idempotente; adiciona ao histórico de auditoria do arquivo auxiliar. |
 
 `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.
 
@@ -106,7 +107,7 @@ Quatro registros completos, limpos e funcionais são enviados como referência:
 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 }}
@@ -119,15 +120,15 @@ jobs:
       - 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 @dogfood-lab/study-swarm@latest requalify --check dispatches/
+      - run: npx --yes @dogfood-lab/study-swarm@2.1.0 requalify --check dispatches/
 ```
 
 ### Fixe um envio para reprodução (`dispatch.lock.json`)
 
-Um envio validado e comprovado só pode ser auditado se você puder dizer *o que o gerou*. `study-swarm lock` cria um arquivo de bloqueio complementar que, por meio do agente de pesquisa, contém informações sobre o **ID do modelo resolvido** (nunca um alias flutuante), o **SHA-256 do prompt exato em bytes** e o **SHA-256 do esquema da ferramenta** fornecido, mais o **comprovante externo do verificador** – tudo reunido em um único arquivo `lock_sha256`. `study-swarm lock --verify` recalcula esses hashes e falha se houver qualquer desvio, portanto, um prompt alterado, um modelo substituído ou uma ferramenta modificada são detectados – o padrão de reprodutibilidade [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm), que pode ser executado. O sistema emite o registro; a CLI permanece sem dependências e independente da rede, apenas normalizando (RFC 8785), calculando hashes e validando.
+Um envio validado e comprovado só pode ser auditado se você puder dizer *o que o gerou*. `study-swarm lock` cria um arquivo de bloqueio complementar que, por meio do agente de pesquisa, contém informações sobre o **ID do modelo resolvido** (nunca um alias flutuante), o **SHA-256 do prompt normalizado (BOM removido, quebras de linha em LF, NFC)** e o **SHA-256 do esquema da ferramenta** fornecido, mais o **comprovante externo do verificador** – tudo reunido em um único arquivo `lock_sha256`. `study-swarm lock --verify` recalcula esses hashes e falha se houver qualquer desvio, portanto, um prompt alterado, um modelo substituído ou uma ferramenta modificada são detectados – o padrão de reprodutibilidade [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm), que pode ser executado. O sistema emite o registro; a CLI permanece sem dependências e independente da rede, apenas normalizando (RFC 8785), calculando hashes e validando.
 
 **Ele fixa as entradas, não as saídas.** Fixar modelo + prompt + temperatura *não* torna a saída de um LLM bit a bit idêntica – invariância em lote, não associatividade de ponto flutuante, roteamento de mistura de especialistas e desvio silencioso do provedor estão todos fora do controle de uma ferramenta offline. Portanto, o bloqueio fornece **entradas reproduzíveis e saídas com detecção de desvio**, nunca "reprodução determinística". O design é fundamentado, citação por citação, em [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) – o primeiro envio a incluir seu próprio bloqueio ([`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json)).
 
@@ -151,7 +152,7 @@ study-swarm requalify --resolve d.dispatch.md arXiv:2402.15089 --mode removed
 
 ## Segurança
 
-`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).
+`study-swarm` fornece uma **CLI fina e sem dependências de runtime** (`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ê os arquivos que você nomeia. `new` grava um único `<slug>.dispatch.md` no diretório de trabalho (sem sobrescrever e sem sair dele). `lock`, `withdraw` e `requalify` também gravam um lock, um sidecar de lápide e, com `--receipt`, um recibo no caminho indicado. 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
 

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,14 +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] [--strict] <path…>` | 检查某个报告的“研究依据”，并对照来源标准进行验证——每个发现都需要有作者、年份和可解析的标识符（arXiv / DOI / URL / RFC）；禁止使用含糊不清的表述，例如“研究表明……”。如果存在违规情况，则返回 `1`，从而阻止 CI 流程。`<path>` 可以是文件、目录（递归地检查所有 `*.dispatch.md` 文件），或者 `-` 表示标准输入；`--json` 会输出机器可读的报告。`--strict` 还会标记“孤立引用”——即某个发现没有被任何第五步选项引用，因为“没有关联的引用是无用的”（可选功能，因此默认的 CI 流程不会改变）。 |
+| `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 值** + **工具模式的 SHA-256 值**，以及步骤 4 中的**验证者凭证**，并将它们组合成一个 `lock_sha256`。 |
+| `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 --status <corpus-dir> [--json]` | 以只读方式查看语料库的“证据健康状况”——包括已撤回和已解决的数量、按原因和解决方法分类，以及每个报告的行数。这是一个信息性输出（返回 `0`），与 `--check` 流程不同。 |
-| `study-swarm requalify --resolve <dispatch> <id> --mode removed\ | regrounded [--note …]` | 一旦该结论被删除（引用消失）或重新验证（由辅助运行器重新验证；`--note` 记录证明），则清除标志。幂等性；附加到侧文件的审计跟踪中。 |
+| `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。
 
@@ -106,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 }}
@@ -119,15 +120,15 @@ jobs:
       - 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 @dogfood-lab/study-swarm@latest requalify --check dispatches/
+      - 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)）的调度文件。
 
@@ -151,7 +152,7 @@ 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)。
 
 ## 状态
 

package/SECURITY.md

@@ -7,7 +7,7 @@
 - **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.