@dogfood-lab/study-swarm 0.5.0 → 1.0.0

package/README.md

@@ -45,7 +45,7 @@ As a test, the protocol was run against its own citations. Two decorrelated non-
 
 | Planted trap | Mistral | IBM Granite | Ground truth |
 |---|---|---|---|
-| Chain-of-thought prompting attributed to "Nakamura & Olsen" | missed | **caught** (misattributed → really Wei et al. 2022) | misattributed |
+| Chain-of-thought prompting attributed to "Nakamura & Olsen" | missed | **caught** (misattributed → really Wei et al. 2022, arXiv:2201.11903) | misattributed |
 | a fabricated "98% of errors removed, no oracle needed" paper | **caught** (fabricated) | **caught** (fabricated) | fabricated |
 
 Neither family caught both traps alone — but their **union caught 2/2**. A single judge would have shipped the misattribution. Separately, the retrieval oracle caught two *real* misattributions in our own design docs (papers cited under the wrong first author) that no parametric LLM could have flagged — and it correctly confirmed genuine 2026 papers that both LLMs false-flagged as fabricated simply because the papers postdate their training. That last point is the whole reason Step 4's existence check **must** be a retrieval oracle, never an LLM.
@@ -59,13 +59,64 @@ You can run the protocol by hand — any different-family model plus resolving t
 - **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — the runtime verifier: family-different routing, reasoning-stripped, multi-lens adjudication, a deterministic retrieval existence floor (arXiv → Crossref), and signed receipts.
 - **[role-os](https://github.com/mcp-tool-shop-org/role-os)** — provides `roleos verify-citations <dispatch>`, the runner that extracts a dispatch's citations and gates them through prism.
 
+The handoff is the dispatch format itself: a finding written as `N. **finding.** Authors year (arXiv|DOI). implication.` — with **one resolvable identifier per finding** — is exactly what `roleos verify-citations` lifts and gates. A `lint`-clean dispatch hands off cleanly; a malformed citation is what the runner flags as unparsed. That contract is what `study-swarm lint` checks locally, so Step 3 and Step 4 agree on what a citation is.
+
+## CLI
+
+```bash
+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 [--json] <path…>` | Check a dispatch's *Research grounding* against the sourcing standard — every finding needs an author, a year, and a resolvable identifier (arXiv / DOI / URL); "studies show…" hand-waving is rejected. Exit `1` on violations, so it gates CI. A `<path>` may be a file, a directory (linted recursively for `*.dispatch.md`), or `-` for stdin; `--json` emits a machine-readable report. |
+
+`lint` is deterministic — zero model calls — so it's safe in CI. It enforces **Step 3's sourcing standard** locally; the model-based **Step 4** verification still defers to [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
+
+A typical loop:
+
+```bash
+study-swarm new my-decision                      # creates my-decision.dispatch.md
+# …fill in the questions, run the research dispatch, write the findings…
+study-swarm lint my-decision.dispatch.md         # enforce the sourcing standard (Step 3)
+roleos verify-citations my-decision.dispatch.md  # model-based Step 4 (different family, via prism)
+```
+
+A complete, lint-clean dispatch — study-swarm applied to its own design — ships in [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) as a worked reference.
+
+### Gate it in CI
+
+`lint` takes a file, a directory (linted recursively for `*.dispatch.md`), or `-` for stdin, and `--json` emits a machine-readable report. Drop this into your repo to gate every dispatch's sourcing on each PR (a copy-paste sample also lives in [`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml)):
+
+```yaml
+# .github/workflows/dispatches.yml
+name: study-swarm lint
+on:
+  pull_request:
+    paths: ['**/*.dispatch.md', '.github/workflows/dispatches.yml']
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
+```
+
 ## Why it works, in one breath
 
-**Current** — the field moves fast; demanding specific studies-with-years keeps designs from shipping 18 months behind. **Functional** — evidence shows what *fails*, not just what works (explanations can increase over-reliance on *wrong* AI — Bansal et al. 2021). **Safe** — the verifier-protected envelope is the architecture the evidence supports, and the protocol enforces it on its own output. Sourcing isn't academic theater; it's the evidence trail.
+**Current** — the field moves fast; demanding specific studies-with-years keeps designs from shipping 18 months behind. **Functional** — evidence shows what *fails*, not just what works (explanations can increase over-reliance on *wrong* AI — Bansal et al. 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Safe** — the verifier-protected envelope is the architecture the evidence supports, and the protocol enforces it on its own output. Sourcing isn't academic theater; it's the evidence trail.
 
 ## Security
 
-`study-swarm` is a documentation repository — Markdown and a logo. It ships no executable code and installs nothing from this repo. It touches no data, requires no permissions, and collects no telemetry; there are no secrets or credentials in the source. The methodology *describes* a workflow that uses web retrieval and model-based verification, but this repo does not implement or run it. See [SECURITY.md](SECURITY.md).
+`study-swarm` ships a **thin, zero-dependency CLI** (`study-swarm`) alongside the methodology. It makes **no network or model calls** and collects **no telemetry**; there are no secrets or credentials in the source. At runtime it only reads the file you pass to `lint` and writes a single `<slug>.dispatch.md` in the current directory for `new` (refusing to overwrite, and never outside the working directory). The model-based verification the methodology describes (Step 4) is run by the sibling tools, not by this package. See [SECURITY.md](SECURITY.md).
 
 ## Status
 

package/README.pt-BR.md

@@ -7,70 +7,122 @@
 </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.**
+**Baseie as decisões de design em pesquisa citada — e depois verifique as citações com uma família de modelos *diferente* antes que qualquer parte disso se torne canônica.**
 
-`study-swarm` é um protocolo, não uma ferramenta. Ao tomar uma decisão de design importante com um LLM — uma nova camada de produto, uma escolha de arquitetura, uma decisão sobre "se devemos confiar no modelo aqui" — improvisar a partir de princípios básicos resulta em designs desatualizados, e citar artigos de memória resulta em designs que se baseiam em fontes que não existem ou que não dizem o que você pensa. O `study-swarm` substitui ambos: envie agentes de pesquisa em paralelo, exija descobertas específicas citadas e valide cada citação por meio de um **verificador externo de uma família de modelos diferente** antes que ela influencie o design.
+`study-swarm` é um protocolo, não uma ferramenta. Quando você está tomando uma decisão de design substancial com um LLM — uma nova camada de produto, uma escolha de arquitetura, uma decisão de "devemos confiar no modelo aqui" — improvisar a partir de primeiros princípios entrega designs que estão desatualizados, e citar artigos de memória entrega designs que se baseiam em fontes que não existem ou não dizem o que você pensa. study-swarm substitui ambos: despache agentes de pesquisa paralelos, exija descobertas citadas específicas e submeta cada citação a um **verificador externo de uma família de modelos diferente** antes que ela informe 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.**
+Ele aplica seu próprio remédio. O protocolo prescreve envelopes protegidos por verificador para os sistemas que ajuda a projetar — então ele executa um em si mesmo. **Nenhum modelo corrige sua própria tarefa, incluindo aquele que executa o protocolo.**
 
-## O protocolo em cinco etapas
+## O protocolo em cinco passos
 
-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.
+1. **Identifique** 3–5 questões de design cruciais onde evidências empíricas mudariam a resposta.
+2. **Despache** 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–8 descobertas bem fundamentadas valem mais que 20 gestos vagos").
+3. **Sintetize** as descobertas em uma seção de *Base de pesquisa*: `N. **<descoberta>.** <Autores> <ano> (<arXiv/DOI>). <implicação de 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 então uma **lente de fundamentação** confirma que a descoberta corresponde à fonte. **Pare** em caso de fabricação/má atribuição; **pare e escale** se o verificador ou o oráculo de recuperação estiver indisponível (nunca interprete a ausência como "citações estão ok").
+5. **Conecte** cada escolha arquitetônica a uma descoberta pelo número. Citações sem uma implicação de 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)**.
+O detalhe executável completo — a tabela de paradas, o padrão de fontes, a regra de conjunto — está em **[PROTOCOL.md](PROTOCOL.md)**.
 
-## Por que uma *família diferente*, sem raciocínio?
+## 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.
+- **Os LLMs não conseguem verificar de forma confiável suas próprias saídas.** 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 é responsável pelos ganhos; o conteúdo de autocrítica é inerte.
+- **Juízes da mesma família preferem a si mesmos.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — o autorreconhecimento correlaciona-se *linearmente* com a autopreferência, portanto, o cegamento parcial não ajuda. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — um painel entre famílias distintas é menos tendencioso a um custo ~7× menor.
+- **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% das citações 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 apoia 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") — o raciocínio em cadeia (chain-of-thought) manipulado por si só infla 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)) — CoT é uma racionalização a posteriori. O verificador vê a afirmação da citação em si, nunca o 'por que incluí isto'.
+- **Diversidade supera quantidade.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — quatro verificadores com correlação par a par ρ ∈ [0.05, 0.25] superam qualquer um individualmente através de cobertura submodular. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — os erros dos LLMs são *correlacionados*, portanto, a variável crucial é a diversidade das lentes, não a quantidade bruta.
 
-## Ele realmente funciona? (prova)
+## Funciona de verdade? (prova)
 
-Como teste, o protocolo foi executado em suas próprias citações. Duas famílias não correlacionadas, diferentes do Claude — **Mistral** (`mistral-small:24b`) e **IBM Granite** (`granite4.1:30b`) — verificaram um conjunto de citações, sem raciocínio, com duas armadilhas ocultas:
+Como teste, o protocolo foi executado contra suas próprias citações. Duas famílias não Claude e decorrelacionadas — **Mistral** (`mistral-small:24b`) e **IBM Granite** (`granite4.1:30b`) — verificaram um conjunto de citações, sem o raciocínio, plantadas com duas armadilhas cegas:
 
-| Armadilha plantada | Mistral | IBM Granite | Verdade |
+| Armadilha plantada | Mistral | IBM Granite | Verdade fundamental |
 |---|---|---|---|
-| 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 |
+| Prompt de raciocínio em cadeia atribuído a "Nakamura & Olsen" | perdida | **apanhada** (atribuída incorretamente → na verdade Wei et al. 2022, arXiv:2201.11903) | atribuída incorretamente |
+| um artigo fabricado "98% dos erros removidos, sem necessidade de oráculo" | **caught** (fabricated) | **caught** (fabricated) | fabricado |
 
-Nenhuma das famílias detectou as duas armadilhas sozinha — mas a **união detectou 2/2**. Um único juiz teria validado a atribuição incorreta. Separadamente, o oráculo de recuperação detectou duas *atribuições incorretas reais* em nossos próprios documentos de design (artigos citados sob o autor principal errado) que nenhum LLM paramétrico poderia ter sinalizado — e ele confirmou corretamente artigos genuínos de 2026 que ambos os LLMs sinalizaram falsamente como fabricados, simplesmente porque os artigos são posteriores ao seu treinamento. Esse último ponto é a razão pela qual a verificação de existência na etapa 4 **deve** ser um oráculo de recuperação, nunca um LLM.
+Nenhuma das famílias apanhou ambas as armadilhas sozinha — mas a sua **união apanhou 2/2**. Um único juiz teria deixado passar a atribuição incorreta. Separadamente, o oráculo de recuperação apanhou duas atribuições incorretas *reais* nos nossos próprios documentos de projeto (artigos citados com o primeiro autor incorreto) que nenhum LLM paramétrico poderia ter sinalizado — e 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 da Etapa 4 **deve** ser um oráculo de recuperação, nunca um LLM.
 
-Essa única execução é a tese em miniatura: **lentes descoordenadas + um oráculo de recuperação para existência superam qualquer juiz inteligente.**
+Essa única execução é a tese em miniatura: **lentes decorrelacionadas + um oráculo de recuperação para existência superam qualquer juiz inteligente.**
 
-## Como está conectado
+## Como funciona
 
-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:
+Pode executar o protocolo manualmente — qualquer modelo de família diferente, além de resolver o arXiv/DOI você mesmo, satisfaz a Etapa 4. Duas ferramentas irmãs 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.
+- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — o verificador em tempo de execução: roteamento diferenciado por família, sem raciocínio, adjudicação multilente, um piso 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 despacho e as encaminha através do prism.
 
-## Por que funciona, em poucas palavras
+A transferência é o próprio formato do despacho: uma descoberta escrita como `N. **descoberta.** Autores ano (arXiv|DOI). implicação.` — com **um identificador resolvível por descoberta** — é exatamente o que `roleos verify-citations` extrai e encaminha. Um despacho limpo pelo `lint` é transferido sem problemas; uma citação malformada é o que o executor sinaliza como não analisada. Esse contrato é o que `study-swarm lint` verifica localmente, para que o Passo 3 e o Passo 4 concordem sobre o que é uma citação.
 
-**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.
+## 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 — os cinco passos, a tabela de parada, o padrão de fontes. |
+| `study-swarm new <slug>` | Gera o esqueleto de um `<slug>.dispatch.md` com a estrutura de cinco passos para preencher. |
+| `study-swarm lint [--json] <path…>` | Verifica a *Base de pesquisa* de um despacho em relação ao padrão de fontes — cada descoberta precisa de um autor, um ano e um identificador resolvível (arXiv / DOI / URL); o discurso vago de "estudos mostram..." é rejeitado. Sai com `1` em caso de violações, para que bloqueie a CI. Um `<path>` pode ser um arquivo, um diretório (verificado recursivamente para `*.dispatch.md`), ou `-` para stdin; `--json` emite um relatório legível por máquina. |
+
+`lint` é determinístico — zero chamadas ao modelo — portanto, é seguro na CI. Ele impõe o **padrão de fontes do Passo 3** localmente; a verificação baseada em modelo do **Passo 4** ainda depende de [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
+
+Um ciclo típico:
+
+```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)
+```
+
+Um despacho completo e limpo pelo `lint` — study-swarm aplicado ao seu próprio design — está disponível em [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) como uma referência prática.
+
+### Bloqueie na CI
+
+`lint` aceita um arquivo, um diretório (verificado recursivamente para `*.dispatch.md`), ou `-` para stdin, e `--json` emite um relatório legível por máquina. Adicione isto ao seu repositório para bloquear as fontes de cada despacho em cada PR (um exemplo para copiar e colar também está em [`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml)):
+
+```yaml
+# .github/workflows/dispatches.yml
+name: study-swarm lint
+on:
+  pull_request:
+    paths: ['**/*.dispatch.md', '.github/workflows/dispatches.yml']
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
+```
+
+## Por que funciona, em uma só frase
+
+**Atual** — o campo avança rapidamente; exigir estudos específicos com anos impede que os designs fiquem 18 meses atrasados. **Funcional** — as evidências mostram o que *falha*, não apenas o que funciona (explicações podem aumentar a confiança excessiva em IA *errada* — Bansal et al. 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Seguro** — o envelope protegido pelo verificador é a arquitetura que as evidências suportam, e o protocolo a impõe em sua própria saída. A citação de fontes não é teatro acadêmico; é o rastro de evidências.
 
 ## Segurança
 
-`study-swarm` é um repositório de documentação — Markdown e um logotipo. Não contém código executável e não instala nada deste repositório. Não acessa dados, não requer permissões e não coleta dados de telemetria; não há segredos ou credenciais no código-fonte. A metodologia *descreve* um fluxo de trabalho que usa recuperação da web e verificação baseada em modelo, mas este repositório não o implementa nem o executa. Consulte [SECURITY.md](SECURITY.md).
+`study-swarm` é fornecido com uma **CLI leve e sem dependências** (`study-swarm`) juntamente com a metodologia. Ele não faz **nenhuma chamada de rede ou de modelo** e não coleta **telemetria**; não há segredos ou credenciais no código-fonte. Em tempo de execução, ele apenas lê o arquivo que você passa para `lint` e escreve um único `<slug>.dispatch.md` no diretório atual para `new` (recusando sobrescrever e nunca fora do diretório de trabalho). A verificação baseada em modelo que a metodologia descreve (Passo 4) é executada pelas ferramentas irmãs, não por este pacote. Consulte [SECURITY.md](SECURITY.md).
 
 ## Status
 
-Um protocolo funcional, verificado externamente por sua própria ferramenta — uma família de modelos diferente verifica suas citações (veja a prova acima). Este repositório é a referência pública; [PROTOCOL.md](PROTOCOL.md) é a forma executável. Parte da família [dogfood-lab](https://github.com/dogfood-lab) — métodos e demonstrações para construir na era da IA.
+Um protocolo funcional, verificado externamente por sua própria maquinaria — 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 vitrines para construir na era da IA.
 
-Licenciado sob a licença MIT.
+Licenciado pelo MIT.
 
 ---
 

package/README.zh.md

@@ -7,68 +7,120 @@
 </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` 替代了这两种方法：它会派遣并行研究代理，要求提供具体的引用结果，并且在任何引用结果影响设计之前，都会通过一个**来自不同模型系列的外部验证器**进行验证。
+`study-swarm`是一种协议，而不是一种工具。当您使用LLM做出重大的设计决策时（例如，新的产品层、架构选择或“我们是否应该信任该模型”），从第一性原理出发进行即兴创作会导致过时的设计，而凭记忆引用论文会导致设计依赖于不存在的来源或与您认为的内容不符。`study-swarm`取代了这两种方法：派遣并行研究代理，要求提供具体的引用结果，并在每个引用通过**不同模型系列的外部验证器**后才将其用于指导设计。
 
-它会自我应用。该协议规定，对于它所帮助设计的系统，必须使用经过验证器保护的机制——因此，它也会对自己进行验证。**没有模型会自己批改作业，包括运行该协议的模型。**
+它也适用于自身。该协议规定，对于其帮助设计的系统，应使用经过验证器的保护机制——因此，它也在自身上运行这种机制。**没有模型会自己批改作业，包括运行该协议的模型。**
 
-## 该协议包含五个步骤
+## 该协议包含五个步骤：
 
-1. **确定** 3-5 个关键的设计问题，如果存在经验证据，这些证据可能会改变答案。
-2. **派遣**一个研究代理来处理每个问题，并并行进行。每个代理都必须返回论文标题 + 作者 + 年份 + URL + 一句话的结论——强调具体性而非广泛性（“6-8 个来源可靠的结论胜过 20 个模糊的描述”）。
-3. **将结论综合**到“研究依据”部分：`N. **<结论>.** <作者> <年份> (<arXiv/DOI>). <设计意义>.`
-4. **进行外部验证**——一个*不同的模型系列*，去除推理能力，以两个阶段检查每个引用：一个**检索预言机**确认论文是否存在（永远不是模型的记忆），然后一个**相关性**过滤器确认结论与来源是否匹配。如果发现捏造或错误引用，则**停止**；如果验证器或检索预言机不可用，则**停止并升级**（永远不要将无法找到的情况视为“引用没问题”）。
-5. **将每个架构选择与一个结论联系起来**，并按编号进行。没有设计意义的引用就是噪音。
+1. **确定** 3-5个关键设计问题，如果存在经验证据，答案可能会发生变化。
+2. **派遣**每个问题的研究代理，并行进行。每个代理必须返回论文标题+作者+年份+URL+一个句子摘要——强调具体性而非广泛性（“6-8条有充分依据的发现胜过20个模糊的要点”）。
+3. **综合**这些发现，形成一份*研究基础*部分：`N. **<发现>.** <作者> <年份> (<arXiv/DOI>)。 <设计意义>.`
+4. **进行外部验证**——一个*不同的模型系列*（不带推理能力），以两个阶段检查每个引用：一个**检索预言机**确认论文是否存在（永远不是模型的记忆），然后一个**真实性**过滤器确认该发现与来源是否匹配。如果出现捏造/错误归因，则**停止**；如果验证器或检索预言机不可用，则**停止并升级**（切勿将无法访问视为“引用没问题”）。
+5. **将**每个架构选择与编号的发现联系起来。没有设计意义的引用就是噪音。
 
-完整的可执行细节——停止表、来源标准、集成规则——都包含在 **[PROTOCOL.md](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))——大型语言模型的错误是*相关的*，因此关键变量是验证器的多样性，而不是原始数量。
+- **LLM无法可靠地验证自身的输出。** 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。
+- **引用是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等人，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)）——LLM的错误是*相关的*，因此关键变量是视角多样性，而不是原始数量。
 
 ## 它真的有效吗？（证明）
 
-作为一项测试，该协议被应用于它自己的引用。两个不相关的非 Claude 系列——**Mistral** (`mistral-small:24b`) 和 **IBM Granite** (`granite4.1:30b`)——检查了一组引用，并去除了推理能力，并设置了两个盲目陷阱：
+作为测试，该协议针对其自身的引用进行了运行。两个不相关的非Claude系列——**Mistral** (`mistral-small:24b`)和**IBM Granite** (`granite4.1:30b`)——以无推理的方式检查了一组引用，并设置了两个盲目陷阱：
 
-| 设置的陷阱 | Mistral | IBM Granite | 真实情况 |
+| 设定的陷阱 | Mistral | IBM Granite | 真实情况 |
 |---|---|---|---|
-| 思维链提示归因于“Nakamura & Olsen” | 未发现 | **发现**（错误归因 → 实际上是 Wei 等人，2022 年） | 错误归因 |
-| 一个捏造的“98% 的错误已消除，不需要预言机”论文 | **caught** (fabricated) | **caught** (fabricated) | 捏造 |
+| 思维链提示归因于“Nakamura & Olsen” | 未发现 | **发现**（错误归因→实际上是Wei等人，2022年，arXiv:2201.11903） | 错误归因 |
+| 一篇捏造的“98%的错误已消除，无需预言机”论文 | **caught** (fabricated) | **caught** (fabricated) | 捏造 |
 
-两个模型单独都没有发现这两个陷阱——但它们的**组合发现了 2/2 个陷阱**。如果只有一个评估者，它会忽略错误归因。此外，检索预言机发现了我们自己设计文档中两个*真实的*错误归因（引用了错误的作者），而任何参数化的大型语言模型都无法识别——并且它正确地确认了 2026 年的真实论文，而这两个大型语言模型都错误地将其标记为捏造，仅仅是因为这些论文的发表时间晚于它们的训练时间。最后一点是，步骤 4 的存在性检查**必须**使用检索预言机，而不是大型语言模型。
+两个系列都没有单独发现这两个陷阱——但它们的**组合发现了2/2个。** 单个评判者会忽略错误归因。此外，检索预言机还发现了我们自己设计文档中的两个*真实*的错误归因（引用了错误的作者），而任何参数LLM都无法标记出来——并且它正确地确认了真正的2026年的论文，这两个LLM因为该论文发布时间晚于它们的训练数据而将其错误地标记为捏造。后一点是第4步存在性检查**必须**使用检索预言机的原因，而不是LLM。
 
-这个简单的测试就是缩影：**不相关的验证器 + 用于验证存在性的检索预言机，胜过任何一个智能评估者。**
+这次运行就是缩影：**不相关的视角+用于验证存在的检索预言机胜过任何一个聪明的评判者。**
 
 ## 它的工作原理
 
-您可以手动运行该协议——任何不同的模型系列，再加上您自己解析 arXiv/DOI，就可以满足步骤 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 进行验证。
+- **[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>`，该工具提取一个“dispatch”中的引用并将其传递给 prism 进行验证。
 
-## 它为何有效，一言以蔽之
+数据传输是“dispatch”格式本身：以 `N. **finding.** Authors year (arXiv|DOI). implication.` 形式编写的发现——每个发现都**包含一个可解析的标识符**——这正是 `roleos verify-citations` 工具所处理和验证的内容。如果“dispatch”符合 `lint` 的要求，则可以顺利进行；如果引用格式不正确，该工具会将其标记为未解析。`study-swarm lint` 会在本地检查此约定，因此步骤 3 和步骤 4 对引用的定义保持一致。
 
-**实用性** — 该领域发展迅速；要求进行特定且耗时的研究，会导致设计落后 18 个月。**功能性** — 证据表明哪些*失败*，而不仅仅是哪些有效（解释可能会增加对*错误*人工智能的过度依赖——Bansal 等人，2021 年）。**安全性** — 验证器保护的范围是证据支持的架构，协议对其自身的输出进行强制执行。来源不是学术表演；它是证据链。
+## 命令行界面 (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 [--json] <path…>` | 检查“dispatch”的*研究依据*是否符合来源标准——每个发现都需要作者、年份和一个可解析的标识符（arXiv / DOI / URL）；“研究表明……”这种泛泛而谈的方式将被拒绝。如果存在违规行为，则返回 `1`，从而阻止 CI 流程。`<path>` 可以是文件、目录（递归地对所有 `*.dispatch.md` 文件进行 lint 检查），或者 `-` 表示标准输入；`--json` 会输出机器可读的报告。 |
+
+`lint` 是确定性的——不调用任何模型——因此可以在 CI 中安全使用。它在本地强制执行**步骤 3 的来源标准**；基于模型的**步骤 4** 验证仍然依赖于 [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism。
+
+典型的流程：
+
+```bash
+study-swarm new my-decision                      # creates my-decision.dispatch.md
+# …fill in the questions, run the research dispatch, write the findings…
+study-swarm lint my-decision.dispatch.md         # enforce the sourcing standard (Step 3)
+roleos verify-citations my-decision.dispatch.md  # model-based Step 4 (different family, via prism)
+```
+
+一个完整的、符合 `lint` 要求的“dispatch”——将 study-swarm 应用于其自身的设计——包含在 [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) 中，作为参考示例。
+
+### 在 CI 中进行验证
+
+`lint` 接受文件、目录（递归地对所有 `*.dispatch.md` 文件进行 lint 检查），或者 `-` 表示标准输入，并且 `--json` 会输出机器可读的报告。将其添加到你的仓库中，以便在每次 PR 中验证每个“dispatch”的来源（一个复制粘贴示例也包含在 [`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml) 中）：
+
+```yaml
+# .github/workflows/dispatches.yml
+name: study-swarm lint
+on:
+  pull_request:
+    paths: ['**/*.dispatch.md', '.github/workflows/dispatches.yml']
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
+```
+
+## 为什么它有效，一句话概括：
+
+**当前**——该领域发展迅速；要求提供具体的、带有年份的研究，可以防止设计落后 18 个月。**功能性**——证据表明哪些*失败*了，而不仅仅是哪些有效（解释可能会增加对*错误* AI 的过度依赖——Bansal 等人，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) 家族的一部分——用于在人工智能时代构建方法和展示案例。
+一个可工作的协议，通过其自身的机制进行了外部验证——不同的模型会检查其引用（参见上面的证明）。该仓库是公共参考；[PROTOCOL.md](PROTOCOL.md) 是可执行的形式。它是 [dogfood-lab](https://github.com/dogfood-lab) 系列的一部分——用于构建 AI 时代的方法和示例。
 
 采用 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