@dogfood-lab/study-swarm 0.6.0 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.0.0] — 2026-06-13
+
+First stable release. A dogfood-swarm health + feature pass hardened the CLI and verified the methodology against its own gate — all 16 cited papers checked by a retrieval oracle plus a different model family (0 fabricated, 0 misattributed).
+
+### Security
+
+- `new` now sanitizes the slug to a single filename — path separators are replaced with `-` and pure-dots slugs are rejected — so it can only ever write `<slug>.dispatch.md` in the current working directory (a slug like `../../x` previously wrote outside it).
+- Pinned the GitHub Pages workflow's actions to commit SHAs, matching the release workflow.
+
+### Added
+
+- `lint` now also checks that each finding names an **author** before the year (Unicode-aware, so names like "Buçinca" count), completing the author + year + identifier sourcing standard the docs describe.
+- `lint --json` emits a machine-readable report (stable `rule` ids + line numbers) for CI annotations and downstream tools.
+- `lint` accepts **multiple paths, a directory** (linted recursively for `*.dispatch.md`), or **`-` for stdin** — so `study-swarm lint dispatches/` gates a whole corpus and a pre-commit hook can pipe a staged file.
+- On a clean lint, the CLI now names the deferred Step-4 next step (`roleos verify-citations`), so a clean form-check isn't mistaken for verified.
+- `new` stamps methodology provenance into each scaffolded dispatch (`study-swarm vX.Y.Z · protocol-sha256:… · created:…`), fulfilling the "pin the methodology version" promise.
+- Shipped a worked, lint-clean reference dispatch (`examples/study-swarm-self.dispatch.md`) and a copy-paste CI sample (`examples/study-swarm-ci.yml`); both are in the npm tarball.
+
+### Fixed
+
+- `lint`: an arXiv id's `YYMM` prefix is no longer mistaken for a publication year, so a finding with no spelled-out year is correctly flagged.
+- `lint`: the "studies show…" gesture check is now scoped to the *Research grounding* section and fires even when a citation sits on the same line.
+- `lint`: the *Research grounding* section is found by a heading whose text *ends* with that phrase, so a document title that merely mentions "research grounding" no longer shadows the real section.
+- `lint`: numbered lines inside fenced code blocks are no longer mistaken for findings.
+- `lint` on a directory, and `protocol` when `PROTOCOL.md` is unreadable, now report an actionable message instead of a raw `EISDIR`.
+- Light-mode handbook link colour darkened to meet WCAG AA contrast, and added a site favicon (previously a 404 on every page).
+
+### Changed
+
+- `SECURITY.md` and the README Security section now describe the real shipped artifact — a thin, zero-dependency CLI — replacing stale "documentation repository / reserved placeholder / no executable code" language, and the Supported-versions table now lists the version line that actually ships.
+- `new` now notes when it had to sanitize a slug, so the created filename is never a silent surprise.
+
+### Docs
+
+- Added arXiv identifiers to the Bansal 2021 and Wei 2022 citations so they meet the project's own sourcing standard.
+- README CLI section now shows the typical `new → lint → verify` loop, a "Gate it in CI" recipe, and the Step-3→Step-4 handoff contract.
+- Corrected the PROTOCOL.md sourcing standard so it matches what `lint` enforces (a resolvable identifier **or** a direct URL, not "title AND a separate URL" — the repo's own examples cite a bare arXiv id).
+- New handbook page **Common failure modes** (symptom → catching step → fix); Step-1 "is this question load-bearing?" heuristics in PROTOCOL.md and the handbook; the `new` template now embeds a worked example finding + selection hint.
+
 ## [0.6.0] — 2026-06-02
 
 ### Added
@@ -22,5 +61,6 @@ All notable changes to this project are documented here. The format is based on
 - `SECURITY.md`, MIT `LICENSE`, project logo.
 - Landing page + Starlight handbook at <https://dogfood-lab.github.io/study-swarm/>.
 
+[1.0.0]: https://github.com/dogfood-lab/study-swarm/releases/tag/v1.0.0
 [0.6.0]: https://github.com/dogfood-lab/study-swarm/releases/tag/v0.6.0
 [0.5.0]: https://github.com/dogfood-lab/study-swarm/releases/tag/v0.5.0

package/PROTOCOL.md

@@ -21,6 +21,15 @@ The cost of running it is one parallel dispatch and a few minutes of synthesis.
 
 List the specific questions where empirical evidence would change the answer. Aim for 3–5. **Fewer is fine** when the decision is genuinely substantial — run with 1–2 agents; the decision-to-investigate governs invocation, the number of evidence-changing questions governs breadth. Do not manufacture questions to hit a count, and do not abort for being under three. More than ~6 → split into multiple passes.
 
+**A question is load-bearing if:**
+
+- you can picture **two different designs** that hinge on the answer;
+- the honest current answer is *"I think…"*, not *"evidence says…"*;
+- an **adjacent field** (HCI, SRE, compilers, databases) has probably already measured it;
+- getting it wrong ships a **known-broken default** (e.g. "explanations always help" — they can increase over-reliance on *wrong* AI).
+
+Worked decomposition: *"Should a retry reuse the previous output?"* splits into *"does context carryover cause sycophancy drift?"* and *"do explanations increase over-reliance on wrong answers?"* — two evidence-changing questions, not one opinion.
+
 ## Step 2 — Dispatch parallel research agents
 
 One agent per question, dispatched **in parallel** (a single batch). Each agent's prompt MUST include:
@@ -85,9 +94,28 @@ Example: *"Retry uses a fresh prompt without the previous output. (sycophancy mi
 
 ## Sourcing standard
 
-**A citation includes ALL of:** (1) author(s) — first author + "et al." inline is fine; (2) year; (3) paper title OR canonical identifier (arXiv:NNNN.NNNNN, DOI, RFC); (4) a direct URL to the source (not a summary or a social-media thread); (5) a one-sentence key finding in your own words.
+**A citation includes ALL of:** (1) author(s) — first author + "et al." inline is fine; (2) year; (3) a **resolvable identifier or direct URL** — an arXiv id (arXiv:NNNN.NNNNN), a DOI, an RFC number, or a direct link to the source (not a summary or a social-media thread); a paper title is welcome but optional; (4) a one-sentence key finding in your own words.
+
+> `study-swarm lint` enforces exactly this FORM locally — author + year + a resolvable arXiv/DOI/URL, and no "studies show…" gestures. arXiv ids and DOIs are preferred over a bare URL because Step 4's retrieval oracle resolves them deterministically.
+
+**Not allowed:** "studies show…" / "research suggests…" / "it's well-established…" without naming the source; an identifier-less citation; citations the research step did not actually surface.
+
+## Common failure modes
+
+The patterns this protocol exists to catch — each with the step that catches it:
+
+| Failure | Symptom | Caught by |
+|---|---|---|
+| **Fabricated citation** | the id resolves to nothing | Step 4 retrieval oracle → dropped |
+| **Misattribution** | real paper, wrong author/year | Step 4 oracle → corrected once, else dropped |
+| **Groundedness gap** | the link resolves but the source doesn't say it | Step 4 groundedness lens (distinct from existence) |
+| **Self-grading** | the synthesizing model also "verifies" | Step 4 different-family rule |
+| **Postdated-paper false-flag** | an LLM calls a real 2026 paper fabricated | why existence MUST be retrieval, not recall |
+| **Question padding** | five thin questions, two actually evidence-changing | Step 1 ("don't manufacture to hit a count") |
+| **Orphan citation** | a finding never referenced by a Step-5 choice | Step 5 (citations without a connection are noise) |
+| **"Studies show…"** | a gesture with no source named | the sourcing standard / `lint` |
 
-**Not allowed:** "studies show…" / "research suggests…" / "it's well-established…" without naming the source; titles without authors or years; citations the research step did not actually surface.
+A fuller version with corrective actions is in the [handbook](https://dogfood-lab.github.io/study-swarm/handbook/failure-modes/).
 
 ## The architecture this protocol enables
 

package/README.es.md

@@ -13,51 +13,53 @@
   <img src="https://img.shields.io/badge/cited%20research-verified-1f6feb" alt="Cited research, verified">
 </p>
 
-**Fundamentar las decisiones de diseño en investigaciones citadas, y luego verificar las citas con un *modelo diferente* antes de que se convierta en algo definitivo.**
+**Fundamenta las decisiones de diseño en investigaciones citadas, y luego verifica las citas con una familia de modelos *diferente* antes de que todo ello se convierta en algo definitivo.**
 
-`study-swarm` es un protocolo, no una herramienta. Cuando se toma una decisión de diseño importante con un LLM (un nuevo nivel de producto, una elección de arquitectura, una decisión sobre si se debe confiar en el modelo), improvisar a partir de principios básicos da como resultado diseños obsoletos, y citar artículos de memoria da como resultado diseños que se basan en fuentes que no existen o que no dicen lo que se cree. `study-swarm` reemplaza ambas opciones: se envían agentes de investigación en paralelo, se exige la presentación de hallazgos específicos y se verifica cada cita a través de un **verificador externo de una familia de modelos diferente** antes de que se utilice para informar el diseño.
+`study-swarm` es un protocolo, no una herramienta. Cuando tomas una decisión de diseño importante con un LLM (una nueva capa de producto, una elección arquitectónica, una decisión sobre si "debemos confiar en el modelo aquí"), improvisar a partir de principios básicos genera diseños obsoletos y citar artículos de memoria genera diseños que se basan en fuentes que no existen o que no dicen lo que crees. `study-swarm` reemplaza ambas cosas: envía agentes de investigación en paralelo, exige hallazgos específicos citados y valida cada cita a través de un **verificador externo de una familia de modelos diferente** antes de que esto influya en el diseño.
 
-Aplica su propia medicina. El protocolo prescribe el uso de verificadores para proteger los resultados de los sistemas que ayuda a diseñar, por lo que lo aplica también a sí mismo. **Ningún modelo califica su propio trabajo, incluido el que ejecuta el protocolo.**
+Aplica su propia medicina. El protocolo prescribe envolventes protegidas por verificadores para los sistemas que ayuda a diseñar, por lo que ejecuta uno sobre sí mismo. **Ningún modelo califica su propio trabajo, incluido el que ejecuta el protocolo.**
 
 ## El protocolo en cinco pasos
 
-1. **Identificar** de 3 a 5 preguntas de diseño clave en las que la evidencia empírica cambiaría la respuesta.
-2. **Enviar** un agente de investigación por cada pregunta, en paralelo. Cada uno debe devolver títulos de artículos + autores + años + URL + un hallazgo de una sola frase; se prioriza la especificidad sobre la amplitud ("6-8 hallazgos bien documentados superan a 20 observaciones vagas").
-3. **Sintetizar** los hallazgos en una sección de *fundamentación de la investigación*: `N. **<hallazgo>.** <Autores> <año> (<arXiv/DOI>). <implicación para el diseño>.`
-4. **Verificar externamente** — una *familia de modelos diferente*, sin razonamiento, verifica cada cita en dos etapas: un **oráculo de recuperación** confirma que el artículo existe (nunca la memoria del modelo), y luego una lente de **fundamentación** confirma que el hallazgo coincide con la fuente. **Detener** si se detecta una falsificación o atribución incorrecta; **detener y escalar** si el verificador o el oráculo de recuperación no están disponibles (nunca interpretar la ausencia como "las citas son correctas").
-5. **Conectar** cada elección de arquitectura con un hallazgo mediante un número. Las citas sin una implicación para el diseño son ruido.
+1. **Identifica** de 3 a 5 preguntas clave de diseño donde la evidencia empírica cambiaría la respuesta.
+2. **Envía** un agente de investigación por cada pregunta, en paralelo. Cada uno debe devolver títulos de artículos + autores + años + URL + un hallazgo de una sola oración; prioriza la especificidad sobre la amplitud ("6 a 8 hallazgos bien documentados superan a 20 gestos vagos").
+3. **Sintetiza** los hallazgos en una sección de *Fundamentación de la investigación*: `N. <hallazgo>. <Autores> <año> (<arXiv/DOI>). <implicación para el diseño>.`
+4. **Verifica externamente**: una *familia de modelos diferente*, sin razonamiento, verifica cada cita en dos etapas: un **oráculo de recuperación** confirma que el artículo existe (nunca la memoria del modelo), y luego una lente de **fundamentación** confirma que el hallazgo coincide con la fuente. **Detén el proceso** si se detecta una falsificación o atribución incorrecta; **detén el proceso y escala** si el verificador o el oráculo de recuperación no están disponibles (nunca interpretes la ausencia como "las citas son correctas").
+5. **Conecta** cada elección arquitectónica con un hallazgo por número. Las citas sin una implicación para el diseño son ruido.
 
-Los detalles completos y ejecutables (la tabla de detención, el estándar de fuentes, la regla de conjunto) se encuentran en **[PROTOCOL.md](PROTOCOL.md)**.
+Los detalles completos y ejecutables: la tabla de detención, el estándar de fuentes y la regla del conjunto se encuentran en **[PROTOCOL.md](PROTOCOL.md)**.
 
-## ¿Por qué una *familia diferente* y sin razonamiento?
+## ¿Por qué una familia *diferente*, sin razonamiento?
 
-Porque los modos de fallo están documentados, no son hipotéticos:
+Porque los modos de falla están documentados, no son hipotéticos:
 
 - **Los LLM no pueden verificar de manera confiable su propia salida.** 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)) — el verificador externo proporciona las ventajas; el contenido de autocrítica es inerte.
-- **Los evaluadores de la misma familia se auto-favorecen.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — el auto-reconocimiento se correlaciona *linealmente* con la auto-preferencia, por lo que el cegamiento parcial no ayuda. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — un panel de diferentes familias es menos sesgado a un costo aproximadamente 7 veces menor.
-- **Las citas son donde los LLM mienten.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — el 55% de las citas de GPT-3.5 / 18% de las citas de GPT-4 son falsas. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — los enlaces resuelven más del 94% de las veces, pero solo el 39-77% del contenido citado realmente respalda la afirmación. Por lo tanto, la existencia debe verificarse mediante la **recuperación, no la memoria**.
-- **Ocultar el razonamiento del generador.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — la manipulación del razonamiento en cadena infla los falsos positivos de un evaluador hasta en un 90% con acciones fijas. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — el razonamiento en cadena es una racionalización *a posteriori*. El verificador ve la afirmación de la cita sin adornos, nunca el "por qué la incluí".
-- **La diversidad supera a la cantidad.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — cuatro verificadores con una correlación por pares de ρ ∈ [0.05, 0.25] superan a cualquiera de ellos mediante una cobertura submodular. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — los errores de los LLM están *correlacionados*, por lo que la variable clave es la diversidad de las lentes, no la cantidad.
+- **Los jueces de la misma familia se auto-favorecen.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — el autorreconocimiento se correlaciona *linealmente* con la autopreferencia, por lo que el cegamiento parcial no ayuda. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — un panel de familias disjuntas es menos sesgado a un costo ~7 veces menor.
+- **Las citas son donde los LLM mienten.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — el 55% de las citas de GPT-3.5 / 18% de GPT-4 son falsas. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — los enlaces resuelven >94% de las veces, pero solo el 39-77% del contenido citado realmente respalda la afirmación. Por lo tanto, la existencia debe verificarse mediante **la recuperación, no el recuerdo**.
+- **Oculta el razonamiento del generador.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — la manipulación del encadenamiento de pensamientos infla los falsos positivos de un juez hasta en un 90% con las acciones fijas. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — el encadenamiento de pensamientos es una racionalización *a posteriori*. El verificador ve la afirmación de cita desnuda, nunca el "por qué lo incluí".
+- **La diversidad supera a la cantidad.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — cuatro verificadores con una correlación por pares ρ ∈ [0.05, 0.25] superan a cualquiera solo mediante la cobertura submodular. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — los errores de los LLM están *correlacionados*, por lo que la variable clave es la diversidad de las lentes, no la cantidad bruta.
 
-## ¿Funciona realmente? (prueba)
+## ¿Realmente funciona? (prueba)
 
-Como prueba, el protocolo se ejecutó con sus propias citas. Dos familias no correlacionadas y diferentes a Claude — **Mistral** (`mistral-small:24b`) y **IBM Granite** (`granite4.1:30b`) — verificaron un conjunto de citas, sin razonamiento, con dos trampas ocultas:
+Como prueba, el protocolo se ejecutó contra sus propias citas. Dos familias decorrelacionadas y distintas a Claude: **Mistral** (`mistral-small:24b`) e **IBM Granite** (`granite4.1:30b`), verificaron un conjunto de citas, sin razonamiento, con dos trampas ciegas:
 
 | Trampa plantada | Mistral | IBM Granite | Verdad fundamental |
 |---|---|---|---|
-| El razonamiento en cadena atribuido a "Nakamura & Olsen" | no se detectó | **se detectó** (atribución incorrecta → en realidad Wei et al. 2022) | atribución incorrecta |
+| Encadenamiento de pensamientos atribuido a "Nakamura & Olsen" | no detectada | **detectada** (atribución incorrecta → en realidad Wei et al. 2022, arXiv:2201.11903) | atribución incorrecta |
 | un artículo fabricado con la afirmación de que "el 98% de los errores se eliminan, no se necesita un oráculo" | **caught** (fabricated) | **caught** (fabricated) | fabricado |
 
-Ninguna de las dos familias detectó ambas trampas por sí sola, pero su **unión detectó 2/2**. Un solo evaluador habría aceptado la atribución incorrecta. Por separado, el oráculo de recuperación detectó dos *atribuciones incorrectas reales* en nuestros propios documentos de diseño (artículos citados con el primer autor incorrecto) que ningún LLM paramétrico podría haber detectado, y confirmó correctamente los artículos genuinos de 2026 que ambos LLM marcaron erróneamente como fabricados simplemente porque los artículos son posteriores a su entrenamiento. Ese último punto es la razón por la que la verificación de la existencia en el paso 4 **debe** ser un oráculo de recuperación, nunca un LLM.
+Ninguna de las dos familias detectó ambas trampas por sí sola, pero su **unión detectó 2/2**. Un solo juez habría aceptado la atribución incorrecta. Por separado, el oráculo de recuperación detectó dos *atribuciones incorrectas reales* en nuestros propios documentos de diseño (artículos citados bajo el primer autor incorrecto) que ningún LLM paramétrico podría haber señalado, y confirmó correctamente los artículos genuinos de 2026 que ambos LLM marcaron erróneamente como fabricados simplemente porque los artículos son posteriores a su entrenamiento. Ese último punto es la razón por la que la verificación de existencia en el paso 4 **debe** ser un oráculo de recuperación, nunca un LLM.
 
-Esa única ejecución es la tesis en miniatura: **lentes no correlacionadas + un oráculo de recuperación para la existencia superan a cualquier evaluador inteligente**.
+Esa única ejecución es la tesis en miniatura: **lentes decorrelacionadas + un oráculo de recuperación para la existencia superan a cualquier juez inteligente.**
 
 ## Cómo está conectado
 
-Puede ejecutar el protocolo manualmente: cualquier modelo de una familia diferente más la resolución de arXiv/DOI por sí mismo satisface el paso 4. Dos herramientas complementarias lo convierten en un solo comando:
+Puedes ejecutar el protocolo manualmente; cualquier modelo de familia diferente, junto con la resolución del arXiv/DOI por tu cuenta, satisface el paso 4. Dos herramientas complementarias lo convierten en un solo comando:
 
-- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — el verificador en tiempo de ejecución: enrutamiento diferenciado por familia, sin razonamiento superfluo, adjudicación con múltiples lentes, un umbral determinista para la existencia de referencias (arXiv → Crossref) y comprobantes firmados.
-- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** — proporciona `roleos verify-citations <dispatch>`, el programa que extrae las citas de un documento y las valida a través de prism.
+- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)**: el verificador de tiempo de ejecución: enrutamiento entre familias, razonamiento simplificado, adjudicación con múltiples lentes y un límite determinista para la existencia de recuperaciones (arXiv → Crossref) y recibos firmados.
+- **[role-os](https://github.com/mcp-tool-shop-org/role-os)**: proporciona `roleos verify-citations <dispatch>`, el ejecutor que extrae las citas de un "dispatch" y las pasa a través de prism.
+
+La transición es el formato del "dispatch" en sí: una conclusión escrita como `N. **conclusión.** Autores año (arXiv|DOI). implicación.` — con **un identificador resoluble por cada conclusión** — es exactamente lo que `roleos verify-citations` extrae y procesa. Un "dispatch" limpio, según las reglas de formato (`lint`), se transfiere sin problemas; una cita malformada es lo que el ejecutor marca como no analizada. Ese contrato es lo que `study-swarm lint` verifica localmente, por lo que los pasos 3 y 4 coinciden en la definición de una cita.
 
 ## CLI
 
@@ -65,25 +67,60 @@ Puede ejecutar el protocolo manualmente: cualquier modelo de una familia diferen
 npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
 ```
 
-| Comando | Función |
+| Comando | Qué hace |
 |---|---|
-| `study-swarm protocol` | Imprime el protocolo completo: los cinco pasos, la tabla de control y el estándar de búsqueda de fuentes. |
-| `study-swarm new <slug>` | Crea un archivo `<slug>.dispatch.md` con la estructura de los cinco pasos para que se complete. |
-| `study-swarm lint <file>` | Comprueba la *base de investigación* de un documento en relación con el estándar de búsqueda de fuentes; cada hallazgo debe tener un autor, un año y un identificador que se pueda resolver (arXiv / DOI / URL); se rechazan las afirmaciones vagas como "los estudios demuestran...". Si se detectan infracciones, el programa finaliza con el código `1`, lo que impide que se ejecute en el entorno de integración continua (CI). |
+| `study-swarm protocol` | Imprime el protocolo completo: los cinco pasos, la tabla de interrupción y el estándar de fuentes. |
+| `study-swarm new <slug>` | Crea un archivo `<slug>.dispatch.md` con el esqueleto de los cinco pasos para completar. |
+| `study-swarm lint [--json] <path…>` | Verifica la *fundamentación de la investigación* de un "dispatch" según el estándar de fuentes: cada conclusión necesita un autor, un año y un identificador resoluble (arXiv / DOI / URL); se rechaza cualquier afirmación vaga del tipo "los estudios demuestran...". Sale con código `1` en caso de violaciones, por lo que bloquea la integración continua. Una `<ruta>` puede ser un archivo, un directorio (analizado recursivamente para archivos `*.dispatch.md`) o `-` para la entrada estándar; `--json` emite un informe legible por máquina. |
+
+`lint` es determinista: no realiza llamadas al modelo, por lo que es seguro en la integración continua. Aplica el **estándar de fuentes del paso 3** localmente; la verificación basada en modelos del **paso 4** aún depende de [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
 
-`lint` es determinista (no realiza llamadas al modelo), por lo que es seguro para usar en el entorno de integración continua (CI). Aplica el **estándar de búsqueda de fuentes del paso 3** a nivel local; la verificación basada en el modelo del **paso 4** sigue dependiendo de [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
+Un 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)
+```
+
+Un "dispatch" completo y limpio, según las reglas de formato (`lint`), con `study-swarm` aplicado a su propio diseño, se incluye en [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) como una referencia práctica.
+
+### Bloquéalo en la integración continua
+
+`lint` toma un archivo, un directorio (analizado recursivamente para archivos `*.dispatch.md`) o `-` para la entrada estándar, y `--json` emite un informe legible por máquina. Incluye esto en tu repositorio para bloquear la verificación de las fuentes de cada "dispatch" en cada solicitud de extracción (también hay una muestra que se puede copiar y pegar en [`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 qué funciona, en pocas palabras
 
-**Eficiencia:** el campo avanza rápidamente; exigir estudios específicos y exhaustivos retrasa el lanzamiento de los diseños en 18 meses. **Funcionalidad:** la evidencia muestra lo que *falla*, no solo lo que funciona (las explicaciones pueden aumentar la dependencia excesiva de una IA *incorrecta* — Bansal et al. 2021). **Seguridad:** el entorno protegido por el verificador es la arquitectura que respalda la evidencia, y el protocolo la aplica a su propia salida. La verificación no es un ejercicio académico; es el rastro de la evidencia.
+**Actualizado**: el campo avanza rápidamente; exigir estudios específicos con años evita que los diseños se retrasen 18 meses. **Funcional**: la evidencia muestra lo que *falla*, no solo lo que funciona (las explicaciones pueden aumentar la dependencia excesiva de la IA *incorrecta* — Bansal et al. 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Seguro**: el entorno protegido por el verificador es la arquitectura que respalda la evidencia, y el protocolo lo aplica a su propia salida. La verificación de fuentes no es un ejercicio académico; es el rastro de la evidencia.
 
 ## Seguridad
 
-`study-swarm` es un repositorio de documentación: Markdown y un logotipo. No incluye código ejecutable ni instala nada de este repositorio. No accede a datos, no requiere permisos y no recopila datos de telemetría; no hay secretos ni credenciales en el código fuente. La metodología *describe* un flujo de trabajo que utiliza la recuperación web y la verificación basada en modelos, pero este repositorio no lo implementa ni lo ejecuta. Consulte [SECURITY.md](SECURITY.md).
+`study-swarm` incluye una **CLI delgada, con cero dependencias** (`study-swarm`) junto con la metodología. No realiza **ninguna llamada a la red ni al modelo** y no recopila **ningún dato de telemetría**: no hay secretos ni credenciales en el código fuente. En tiempo de ejecución, solo lee el archivo que se pasa a `lint` y escribe un único archivo `<slug>.dispatch.md` en el directorio actual para `new` (rechazando sobrescribirlo y nunca saliendo del directorio de trabajo). La verificación basada en modelos que describe la metodología (paso 4) es realizada por las herramientas complementarias, no por este paquete. Consulta [SECURITY.md](SECURITY.md).
 
 ## Estado
 
-Un protocolo funcional, verificado externamente por su propio mecanismo: una familia de modelos diferente verifica sus citas (vea la prueba anterior). Este repositorio es la referencia pública; [PROTOCOL.md](PROTOCOL.md) es la implementación ejecutable. Forma parte de la familia [dogfood-lab](https://github.com/dogfood-lab): métodos y ejemplos para construir en la era de la IA.
+Un protocolo funcional, verificado externamente por su propia maquinaria: una familia de modelos diferente verifica sus citas (consulta la prueba anterior). Este repositorio es la referencia pública; [PROTOCOL.md](PROTOCOL.md) es la forma ejecutable. Forma parte de la familia [dogfood-lab](https://github.com/dogfood-lab): métodos y ejemplos para construir en la era de la IA.
 
 Con licencia MIT.
 

package/README.fr.md

@@ -13,53 +13,55 @@
   <img src="https://img.shields.io/badge/cited%20research-verified-1f6feb" alt="Cited research, verified">
 </p>
 
-**Ancrez les décisions de conception dans les recherches citées, puis vérifiez les citations à l’aide d’un *modèle* différent avant que quoi que ce soit ne devienne un élément canonique.**
+**Ancrez les décisions de conception dans des recherches citées, puis vérifiez ces citations à l’aide d’une *autre* famille de modèles avant que quoi que ce soit ne devienne un élément canonique.**
 
-`study-swarm` est un protocole, pas un outil. Lorsque vous prenez une décision de conception importante avec un LLM (un nouveau niveau de produit, un choix d’architecture, une question du type « devons-nous faire confiance au modèle ici »), improviser à partir de principes de base conduit à des conceptions obsolètes, et citer des articles de mémoire conduit à des conceptions qui reposent sur des sources qui n’existent pas ou qui ne disent pas ce que vous pensez. `study-swarm` remplace les deux : il lance des agents de recherche parallèles, exige des résultats spécifiques cités et soumet chaque citation à un **vérificateur externe d’une famille de modèles différente** avant qu’elle n’influence la conception.
+`study-swarm` est un protocole, pas un outil. Lorsque vous prenez une décision de conception importante avec un LLM (un nouveau niveau de produit, un choix d’architecture, une question du type « devons-nous faire confiance au modèle ici »), improviser à partir de principes fondamentaux conduit à des conceptions obsolètes, et citer des articles de mémoire conduit à des conceptions qui reposent sur des sources inexistantes ou qui ne disent pas ce que vous pensez. `study-swarm` remplace les deux : il lance en parallèle des agents de recherche, exige des résultats spécifiques cités et soumet chaque citation à un **vérificateur externe d’une famille de modèles différente** avant qu’elle n’influence la conception.
 
-Il applique sa propre méthode. Le protocole prescrit des enveloppes protégées par un vérificateur pour les systèmes qu’il aide à concevoir, il l’applique donc à lui-même. **Aucun modèle n’évalue son propre travail, y compris celui qui exécute le protocole.**
+Il applique sa propre méthode. Le protocole prescrit l’utilisation d’enveloppes protégées par un vérificateur pour les systèmes auxquels il contribue à concevoir, il l’applique donc également sur lui-même. **Aucun modèle n’évalue son propre travail, y compris celui qui exécute le protocole.**
 
 ## Le protocole en cinq étapes
 
-1. **Identifiez** 3 à 5 questions de conception essentielles auxquelles des preuves empiriques permettraient de modifier la réponse.
-2. **Lancez** un agent de recherche par question, en parallèle. Chacun doit renvoyer les titres des articles + les auteurs + les années + les URL + un résultat en une phrase (la spécificité prime sur l’étendue : « 6 à 8 résultats bien documentés sont plus efficaces que 20 observations vagues »).
-3. **Synthétisez** les résultats dans une section « Justification par la recherche » : `N. **<résultat>.** <Auteurs> <année> (<arXiv/DOI>). <implication pour la conception>.`
-4. **Vérifiez de manière externe** — une *famille de modèles différente*, sans raisonnement, vérifie chaque citation en deux étapes : un **oracle de récupération** confirme que l’article existe (jamais la mémoire du modèle), puis une **lentille de pertinence** confirme que le résultat correspond à la source. **Arrêtez** en cas de fabrication/d’attribution incorrecte ; **arrêtez et escaladez** si le vérificateur ou l’oracle de récupération n’est pas disponible (ne considérez jamais l’absence comme « les citations sont correctes »).
-5. **Reliez** chaque choix architectural à un résultat par numéro. Les citations sans implication pour la conception sont du bruit.
+1. **Identifiez** 3 à 5 questions de conception essentielles dont la réponse serait modifiée par des preuves empiriques.
+2. **Lancez** un agent de recherche par question, en parallèle. Chacun doit renvoyer le titre de l’article + les auteurs + les années + les URL + une conclusion d’une phrase (privilégiez la spécificité à l’étendue : « 6 à 8 conclusions bien étayées sont plus efficaces que 20 observations vagues »).
+3. **Synthétisez** les résultats dans une section intitulée *Justification par la recherche* : `N. <conclusion>. <Auteurs> <année> (<arXiv/DOI>). <implication pour la conception>.`
+4. **Vérifiez de manière externe** — une *famille de modèles différente*, sans raisonnement, vérifie chaque citation en deux étapes : un **oracle de récupération** confirme que l’article existe (jamais à partir de la mémoire du modèle), puis une **lentille d’ancrage** confirme que la conclusion correspond à la source. **Arrêtez le processus** si la citation est fabriquée ou mal attribuée ; **arrêtez et escaladez** si le vérificateur ou l’oracle de récupération n’est pas disponible (ne considérez jamais l’absence comme une indication que les citations sont correctes).
+5. **Reliez** chaque choix architectural à une conclusion en utilisant un numéro. Les citations sans implication pour la conception sont du bruit.
 
-Les détails exécutables complets (le tableau d’arrêt, la norme de référencement, la règle d’ensemble) se trouvent dans **[PROTOCOL.md](PROTOCOL.md)**.
+Les détails complets et exécutables — le tableau d’arrêt, la norme de référencement, la règle d’ensemble — se trouvent dans **[PROTOCOL.md](PROTOCOL.md)**.
 
 ## Pourquoi une *famille différente*, sans raisonnement ?
 
 Parce que les modes d’échec sont documentés, et non hypothétiques :
 
-- **Les LLM ne peuvent pas vérifier de manière fiable leurs propres résultats.** 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)) — le vérificateur externe apporte les avantages ; le contenu d’auto-critique est inerte.
-- **Les juges de la même famille ont une préférence pour eux-mêmes.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — l’auto-reconnaissance est corrélée *linéairement* avec l’auto-préférence, de sorte qu’un aveuglement partiel n’aide pas. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — un groupe de juges issus de familles distinctes est moins biaisé, pour un coût environ 7 fois inférieur.
-- **Les citations sont les endroits où les LLM mentent.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — 55 % des citations de GPT-3.5 / 18 % des citations de GPT-4 sont fabriquées. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — les liens résolvent > 94 % du temps, mais seulement 39 à 77 % du contenu cité soutiennent réellement l’affirmation. Par conséquent, l’existence doit être vérifiée par **la récupération, et non par la mémorisation**.
-- **Masquez le raisonnement du générateur.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), « Gaming the Judge ») — la manipulation du raisonnement en chaîne seule augmente les faux positifs d’un juge jusqu’à 90 %, les actions étant maintenues fixes. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — le raisonnement en chaîne est une rationalisation a posteriori. Le vérificateur voit la revendication de citation brute, jamais le « pourquoi je l’ai incluse ».
-- **La diversité est plus importante que le nombre.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — quatre vérificateurs avec une corrélation par paires ρ ∈ [0,05, 0,25] sont plus efficaces qu’un seul, grâce à une couverture sous-modulaire. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — les erreurs des LLM sont *corrélées*, de sorte que la variable essentielle est la diversité des lentilles, et non le nombre brut.
+- **Les LLM ne peuvent pas vérifier de manière fiable leurs propres résultats.** 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)) — le vérificateur externe apporte les améliorations ; le contenu d’auto-évaluation est inerte.
+- **Les juges de la même famille ont une préférence pour eux-mêmes.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — l’auto-reconnaissance est corrélée *linéairement* avec la préférence pour soi-même, de sorte qu’un aveuglement partiel n’est pas utile. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — un groupe de juges issus de familles différentes est moins biaisé, pour un coût environ 7 fois inférieur.
+- **Les citations sont les points où les LLM mentent.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — 55 % des citations de GPT-3.5 et 18 % des citations de GPT-4 sont fabriquées. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — les liens résolvent plus de 94 % du temps, mais seulement 39 à 77 % du contenu cité soutiennent réellement l’affirmation. Par conséquent, l’existence doit être vérifiée par **récupération, et non par rappel**.
+- **Masquez le raisonnement du générateur.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), « Gaming the Judge ») — la simple manipulation de la chaîne de pensée augmente les faux positifs d’un juge jusqu’à 90 %, les actions étant maintenues constantes. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — la chaîne de pensée est une rationalisation a posteriori. Le vérificateur voit uniquement l’affirmation de citation, jamais le « pourquoi j’ai inclus ceci ».
+- **La diversité surpasse la quantité.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — quatre vérificateurs avec une corrélation par paires ρ ∈ [0,05, 0,25] sont plus efficaces qu’un seul grâce à la couverture sous-modulaire. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — les erreurs des LLM sont *corrélées*, de sorte que la variable essentielle est la diversité des lentilles, et non la quantité brute.
 
 ## Est-ce que cela fonctionne réellement ? (preuve)
 
-À titre de test, le protocole a été appliqué à ses propres citations. Deux familles non-Claude non corrélées — **Mistral** (`mistral-small:24b`) et **IBM Granite** (`granite4.1:30b`) — ont vérifié un ensemble de citations, sans raisonnement, en utilisant deux pièges aveugles :
+À titre de test, le protocole a été appliqué à ses propres citations. Deux familles non-Claude décorrélées — **Mistral** (`mistral-small:24b`) et **IBM Granite** (`granite4.1:30b`) — ont vérifié un ensemble de citations, sans raisonnement, en utilisant deux pièges aveugles :
 
 | Piège planté | Mistral | IBM Granite | Vérité terrain |
 |---|---|---|---|
-| Le raisonnement en chaîne attribué à « Nakamura & Olsen » | manqué | **détecté** (attribution incorrecte → en réalité Wei et al. 2022) | attribution incorrecte |
-| un article fabriqué « 98 % des erreurs éliminées, aucun oracle n’est nécessaire » | **caught** (fabricated) | **caught** (fabricated) | fabriqué |
+| Une chaîne de pensée attribuée à « Nakamura & Olsen » | non détecté | **détecté** (mal attribué → en réalité Wei et al. 2022, arXiv:2201.11903) | mal attribué |
+| un article fabriqué affirmant que « 98 % des erreurs sont éliminées, aucun oracle n’est nécessaire » | **caught** (fabricated) | **caught** (fabricated) | fabriqué |
 
-Aucune des deux familles n’a détecté les deux pièges seule, mais leur **union a détecté 2/2**. Un seul juge aurait validé l’attribution incorrecte. Par ailleurs, l’oracle de récupération a détecté deux *véritables* attributions incorrectes dans nos propres documents de conception (articles cités sous le mauvais premier auteur) que aucun LLM paramétrique n’aurait pu signaler, et il a correctement confirmé les articles authentiques de 2026 que les deux LLM ont faussement signalés comme étant fabriqués simplement parce que les articles sont postérieurs à leur date d’entraînement. Ce dernier point est la raison pour laquelle la vérification de l’existence à l’étape 4 **doit** être effectuée par un oracle de récupération, et non par un LLM.
+Aucune des deux familles n’a détecté les deux pièges individuellement, mais leur **union a permis de détecter 2/2**. Un seul juge aurait validé la mauvaise attribution. Par ailleurs, l’oracle de récupération a détecté deux *vrais* mauvaises attributions dans nos propres documents de conception (articles cités avec le mauvais premier auteur) que aucun LLM paramétrique n’aurait pu signaler — et il a correctement confirmé des articles authentiques de 2026 que les deux LLM ont faussement signalés comme étant fabriqués simplement parce que les articles sont postérieurs à leur date d’entraînement. Ce dernier point est la raison pour laquelle la vérification de l’existence dans l’étape 4 **doit** être effectuée par un oracle de récupération, et non par un LLM.
 
-Cette seule exécution est la thèse en miniature : **des lentilles non corrélées + un oracle de récupération pour l’existence sont plus efficaces qu’un seul juge intelligent.**
+Cette seule exécution est la thèse en miniature : **des lentilles décorrélées + un oracle de récupération pour vérifier l’existence sont plus efficaces qu’un seul juge intelligent.**
 
-## Comment cela fonctionne
+## Comment cela fonctionne-t-il ?
 
-Vous pouvez exécuter le protocole manuellement — tout modèle d’une famille différente, ainsi que la résolution de l’arXiv/DOI vous-même, satisfont aux exigences de l’étape 4. Deux outils frères permettent de le faire en une seule commande :
+Vous pouvez exécuter le protocole manuellement : tout modèle d’une famille différente, associé à la résolution de l’identifiant arXiv/DOI, satisfait l’étape 4. Deux outils complémentaires permettent de réaliser cette opération en une seule commande :
 
-- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** — le vérificateur d’exécution : routage différencié par famille, suppression du raisonnement, adjudication multi-lentilles, seuil d’existence de récupération déterministe (arXiv → Crossref) et reçus signés.
-- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** — fournit `roleos verify-citations <dispatch>`, l’exécutant qui extrait les citations d’un document et les soumet à prism pour vérification.
+- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** : le vérificateur d’exécution ; il effectue un routage différent selon la famille, supprime les raisonnements inutiles, réalise une évaluation à plusieurs niveaux et établit un seuil minimal de récupération déterministe (arXiv → Crossref), en plus de générer des reçus signés.
+- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** : il fournit la commande `roleos verify-citations <dispatch>`, qui extrait les citations d’un document et les transmet à prism pour vérification.
 
-## Interface en ligne de commande
+Le transfert se fait via le format du document lui-même : une conclusion rédigée sous la forme `N. **conclusion.** Auteurs année (arXiv|DOI). implication.` — avec **un seul identifiant résolvable par conclusion** — est exactement ce que la commande `roleos verify-citations` extrait et transmet pour vérification. Un document propre, validé par `lint`, est transféré sans problème ; une citation mal formée est signalée comme non analysée par l’outil. Ce contrat est ce que la commande `study-swarm lint` vérifie localement, de sorte que les étapes 3 et 4 s’accordent sur la définition d’une citation.
+
+## CLI
 
 ```bash
 npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
@@ -67,23 +69,58 @@ npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-sw
 
 | Commande | Fonctionnement |
 |---|---|
-| `study-swarm protocol` | Affiche le protocole complet : les cinq étapes, la table d’arrêt, la norme de référencement. |
+| `study-swarm protocol` | Affiche le protocole complet : les cinq étapes, la table de terminaison et la norme de référencement. |
 | `study-swarm new <slug>` | Crée un fichier `<slug>.dispatch.md` avec le squelette des cinq étapes à compléter. |
-| `study-swarm lint <file>` | Vérifie le *fondement de la recherche* d’un document par rapport à la norme de référencement : chaque élément doit avoir un auteur, une année et un identifiant résolvable (arXiv / DOI / URL) ; les affirmations vagues du type « des études montrent… » sont rejetées. En cas de violation, le programme se termine avec le code `1`, ce qui empêche l’exécution dans l’environnement CI. |
+| `study-swarm lint [--json] <path…>` | Vérifie le *fondement de la recherche* d’un document par rapport à la norme de référencement : chaque conclusion doit comporter un auteur, une année et un identifiant résolvable (arXiv / DOI / URL) ; les affirmations vagues du type « des études montrent que… » sont rejetées. En cas de violation, le programme se termine avec le code `1`, ce qui permet de contrôler l’intégration continue. Un `<chemin>` peut être un fichier, un répertoire (vérifié récursivement pour les fichiers `*.dispatch.md`) ou `-` pour l’entrée standard ; l’option `--json` génère un rapport lisible par machine. |
+
+La commande `lint` est déterministe — elle n’effectue aucun appel de modèle —, ce qui la rend sûre pour l’intégration continue. Elle applique localement la **norme de référencement de l’étape 3** ; la vérification basée sur un modèle, à l’**étape 4**, est toujours effectuée par les outils complémentaires, et non par ce paquet.
 
-`lint` est déterministe — il n’effectue aucun appel de modèle — il est donc sûr à utiliser dans l’environnement CI. Il applique localement la **norme de référencement de l’étape 3** ; la vérification basée sur un modèle de l’**étape 4** est toujours déléguée à [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
+Une boucle typique :
+
+```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)
+```
+
+Un document complet, propre et validé par `lint` — study-swarm appliqué à sa propre conception — est fourni dans le fichier [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) en tant que référence.
+
+### Activez-le dans l’intégration continue
+
+La commande `lint` prend un fichier, un répertoire (vérifié récursivement pour les fichiers `*.dispatch.md`) ou `-` pour l’entrée standard, et l’option `--json` génère un rapport lisible par machine. Intégrez ceci dans votre dépôt pour contrôler le référencement de chaque document lors de chaque demande d’extraction (un exemple à copier-coller est également disponible dans le fichier [`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/
+```
 
-## Pourquoi cela fonctionne, en quelques mots
+## Pourquoi cela fonctionne, en résumé
 
-**Actuel** — le domaine évolue rapidement ; exiger des études spécifiques avec des dates permet d’éviter que les conceptions ne soient mises en œuvre avec 18 mois de retard. **Fonctionnel** — les données montrent ce qui *ne fonctionne pas*, et pas seulement ce qui fonctionne (les explications peuvent entraîner une dépendance excessive à l’égard d’une IA *incorrecte* — Bansal et al. 2021). **Sûr** — l’enveloppe protégée par le vérificateur est l’architecture que les données étayent, et le protocole l’applique à ses propres résultats. Le référencement n’est pas un exercice académique ; c’est la chaîne de preuves.
+**Actuel** — le domaine évolue rapidement ; exiger des études spécifiques avec les années correspondantes évite que les conceptions ne soient mises en œuvre avec 18 mois de retard. **Fonctionnel** — les données montrent ce qui *échoue*, et pas seulement ce qui fonctionne (les explications peuvent entraîner une dépendance excessive à l’égard d’une IA *incorrecte* — Bansal et al., 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Sûr** — l’enveloppe protégée par le vérificateur est l’architecture que les données étayent, et le protocole l’applique à sa propre sortie. Le référencement n’est pas un exercice académique ; il s’agit de la chaîne de preuves.
 
 ## Sécurité
 
-`study-swarm` est un dépôt de documentation : Markdown et un logo. Il ne contient aucun code exécutable et n’installe rien à partir de ce dépôt. Il n’accède à aucune donnée, ne nécessite aucune autorisation et ne collecte aucune télémétrie ; il n’y a pas de secrets ou d’identifiants dans le code source. La méthodologie *décrit* un flux de travail qui utilise la récupération sur le web et la vérification basée sur un modèle, mais ce dépôt ne l’implémente ni ne l’exécute. Voir [SECURITY.md](SECURITY.md).
+`study-swarm` fournit une **CLI légère, sans dépendances**, (`study-swarm`) ainsi que la méthodologie. Il n’effectue **aucun appel réseau ou de modèle** et ne collecte **aucune télémétrie** ; il n’y a pas de secrets ni d’identifiants dans le code source. Lors de l’exécution, il lit uniquement le fichier que vous transmettez à la commande `lint` et écrit un seul fichier `<slug>.dispatch.md` dans le répertoire courant pour une nouvelle version (il refuse d’écraser les fichiers existants et ne sort jamais du répertoire de travail). La vérification basée sur un modèle décrite par la méthodologie (étape 4) est effectuée par les outils complémentaires, et non par ce paquet. Voir [SECURITY.md](SECURITY.md).
 
-## État
+## État actuel
 
-Un protocole fonctionnel, vérifié de manière externe par ses propres mécanismes : une famille de modèles différente vérifie ses citations (voir la preuve ci-dessus). Ce dépôt est la référence publique ; [PROTOCOL.md](PROTOCOL.md) est la forme exécutable. Fait partie de la famille [dogfood-lab](https://github.com/dogfood-lab) : méthodes et exemples pour construire dans l’ère de l’IA.
+Un protocole fonctionnel, vérifié en externe par ses propres mécanismes — une famille de modèles différente vérifie ses citations (voir la preuve ci-dessus). Ce dépôt est la référence publique ; le fichier [PROTOCOL.md](PROTOCOL.md) représente la forme exécutable. Il fait partie de la famille [dogfood-lab](https://github.com/dogfood-lab) — méthodes et exemples pour construire dans l’ère de l’IA.
 
 Licence MIT.