@dogfood-lab/study-swarm 1.1.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/PROTOCOL.md +6 -0
- package/README.es.md +10 -2
- package/README.fr.md +30 -22
- package/README.hi.md +10 -2
- package/README.it.md +41 -33
- package/README.ja.md +43 -35
- package/README.md +10 -2
- package/README.pt-BR.md +10 -2
- package/README.zh.md +10 -2
- package/bin/study-swarm.mjs +183 -1
- package/examples/study-swarm-lock.dispatch.md +137 -0
- package/examples/study-swarm-lock.lock.json +62 -0
- package/examples/study-swarm-lock.orchestration.json +369 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,25 @@
|
|
|
2
2
|
|
|
3
3
|
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/).
|
|
4
4
|
|
|
5
|
+
## [1.2.0] — 2026-06-30
|
|
6
|
+
|
|
7
|
+
Makes a study-swarm dispatch **byte-replayable**. The design was grounded by running study-swarm on this feature itself — five load-bearing questions (replay-manifest structure, cross-platform canonicalization, step-level provenance, LLM replay-determinism reality, tool-schema drift) dispatched to parallel retrieval-grounded agents; all 39 findings were gated through Step 4 (`roleos verify-citations` → prism, a different model family, reasoning-stripped) with a public-key-verified Ed25519 receipt before any informed the design.
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- **`study-swarm lock <dispatch> --from <orchestration.json>`** — writes a companion `dispatch.lock.json` that content-addresses, per Step-2 research agent, the resolved model id, the SHA-256 of the byte-exact prompt, and the SHA-256 of the tool schema, plus the Step-4 verifier receipt, rolled into one `lock_sha256` (the PIN_PER_STEP standard). The harness emits the record; the CLI stays zero-dependency and network-free, only canonicalizing (RFC 8785 JCS + NFC normalization, no BOM), hashing (SHA-256, self-describing `sha256-…` digests), and validating.
|
|
12
|
+
- **`study-swarm lock --verify <dispatch> [--from …]`** — re-derives every deterministic hash and fails closed (exit `1`) on any drift: a changed prompt, a swapped or aliased model, a shifted tool surface, edited dispatch text, or a tampered lock file. Gates CI like a package lockfile. Without `--from`, it checks the lock's own integrity.
|
|
13
|
+
- A worked, runner-verified reference dispatch — `examples/study-swarm-lock.dispatch.md` (39 cited findings) — with its harness record (`examples/study-swarm-lock.orchestration.json`) and the first shipped lock (`examples/study-swarm-lock.lock.json`). All three ship in the npm tarball.
|
|
14
|
+
- Smoke coverage proving `lock --verify` goes **RED** on every drift class (prompt, output, model, dispatch text, lock-file tamper) and that `lock` builds deterministically — a lock that can't detect drift is theater.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- `PROTOCOL.md` adds a short **Replayability** section stating the PIN_PER_STEP property and its honest ceiling.
|
|
19
|
+
|
|
20
|
+
### Honest ceiling
|
|
21
|
+
|
|
22
|
+
Pinning model + prompt + temperature does **not** make an LLM's *output* bit-identical (batch-invariance, floating-point non-associativity, mixture-of-experts routing, silent provider drift). The lock pins **inputs byte-exact and records output hashes for drift detection** — replayable inputs + drift-detectable outputs, never "deterministic replay." Grounded in He & Thinking Machines Lab 2025, Yuan et al. 2025 (arXiv:2506.09501), Atil et al. 2024 (arXiv:2408.04667), and Chen, Zaharia & Zou 2023 (arXiv:2307.09009).
|
|
23
|
+
|
|
5
24
|
## [1.1.0] — 2026-06-29
|
|
6
25
|
|
|
7
26
|
The protocol run on itself a second time — to design its own next version. Four load-bearing questions the first release left to "I think" were dispatched to parallel research agents; all 27 resulting citations were gated through Step 4 (retrieval oracle for existence + two different model families for groundedness, reasoning-stripped) before any informed the design. The oracle confirmed 27/27 exist — including six 2025–2026 papers a parametric model would have false-flagged — and corrected five attributions, among them a real first-author misattribution the research agent flagged on itself.
|
|
@@ -76,6 +95,7 @@ First stable release. A dogfood-swarm health + feature pass hardened the CLI and
|
|
|
76
95
|
- `SECURITY.md`, MIT `LICENSE`, project logo.
|
|
77
96
|
- Landing page + Starlight handbook at <https://dogfood-lab.github.io/study-swarm/>.
|
|
78
97
|
|
|
98
|
+
[1.2.0]: https://github.com/dogfood-lab/study-swarm/releases/tag/v1.2.0
|
|
79
99
|
[1.1.0]: https://github.com/dogfood-lab/study-swarm/releases/tag/v1.1.0
|
|
80
100
|
[1.0.0]: https://github.com/dogfood-lab/study-swarm/releases/tag/v1.0.0
|
|
81
101
|
[0.6.0]: https://github.com/dogfood-lab/study-swarm/releases/tag/v0.6.0
|
package/PROTOCOL.md
CHANGED
|
@@ -141,3 +141,9 @@ Verifier admits before output
|
|
|
141
141
|
- **Verifier as admission gate** — the verifier checks the output against the structure before admitting it; retries use a fresh context to avoid sycophancy drift.
|
|
142
142
|
|
|
143
143
|
Designs that touch model-facing behavior default to this shape unless evidence justifies a different one.
|
|
144
|
+
|
|
145
|
+
## Replayability — pinning a dispatch (`dispatch.lock.json`)
|
|
146
|
+
|
|
147
|
+
A grounded, verified dispatch is only auditable if you can say *what produced it*. `study-swarm lock <dispatch> --from <orchestration.json>` writes a companion `dispatch.lock.json` that pins, per Step-2 research agent, the **resolved model id** (never an alias), the **SHA-256 of the byte-exact prompt**, and the **SHA-256 of the tool schema** the agent was given, plus the Step-4 **verifier receipt** — rolled into one `lock_sha256` content-address. `study-swarm lock --verify` re-derives those hashes and exits non-zero on any drift, so a changed prompt, model, or tool surface is caught — it gates CI exactly like a package lockfile. This is the PIN_PER_STEP standard made executable: the harness emits the record, and the CLI (zero-dependency, network-free) only canonicalizes, hashes, and validates it.
|
|
148
|
+
|
|
149
|
+
**Honest ceiling:** pinning model + prompt + temperature does **not** make an LLM's *output* bit-identical — batch-invariance, floating-point non-associativity, mixture-of-experts routing, and silent provider drift all sit outside any offline tool's control. So the lock pins **inputs byte-exact and records output hashes for drift detection** — *replayable inputs + drift-detectable outputs*, never "deterministic replay." The design and its evidence are the worked dispatch [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) — itself the first dispatch to ship its own lock.
|
package/README.es.md
CHANGED
|
@@ -76,6 +76,8 @@ npm i -g @dogfood-lab/study-swarm # or run ad-hoc: npx @dogfood-lab/study-sw
|
|
|
76
76
|
| `study-swarm protocol` | Imprime el protocolo completo: los cinco pasos, la tabla de detención y el estándar de fuentes. |
|
|
77
77
|
| `study-swarm new <slug>` | Crea un archivo `<slug>.dispatch.md` con el esqueleto de los cinco pasos para completarlo. |
|
|
78
78
|
| `study-swarm lint [--json] <path…>` | Verifica la *fundamentación de la investigación* de una prueba en comparación con el estándar de fuentes: cada hallazgo 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` si hay infracciones, por lo que valida la integración continua. Un `<path>` puede ser un archivo, un directorio (se analiza recursivamente para archivos `*.dispatch.md`) o `-` para la entrada estándar; `--json` emite un informe legible por máquina. |
|
|
79
|
+
| `study-swarm lock <dispatch> --from <orchestration.json>` | Fija un envío para su reproducción: escribe el contenido con direccionamiento por contenido en `<dispatch>.lock.json`, según el agente del paso 2, que incluye el **ID de modelo resuelto** + el **SHA-256 del mensaje exacto en bytes** + el **SHA-256 del esquema de la herramienta**, más el **comprobante del verificador** del paso 4, todo integrado en un único `lock_sha256`. |
|
|
80
|
+
| `study-swarm lock --verify <dispatch> [--from …]` | Vuelve a generar esos hashes y verifica que coincidan con el bloqueo; cualquier desviación provoca una salida con código `1`, por lo que actúa como un archivo de bloqueo de paquetes para la integración continua. Sin `--from`, comprueba la integridad del propio bloqueo. |
|
|
79
81
|
|
|
80
82
|
`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** sigue utilizando [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
|
|
81
83
|
|
|
@@ -88,7 +90,7 @@ study-swarm lint my-decision.dispatch.md # enforce the sourcing standard
|
|
|
88
90
|
roleos verify-citations my-decision.dispatch.md # model-based Step 4 (different family, via prism)
|
|
89
91
|
```
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
Tres envíos completos y revisados se publican como referencias: [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) (la decisión central del protocolo, concisa), [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md) (el diseño completo de la versión 1.1: 27 citas, todas verificadas externamente) y [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) (el diseño del bloqueo de la versión 1.2: 39 citas, controlado a través del ejecutor, y el primer envío que incluye su propio bloqueo).
|
|
92
94
|
|
|
93
95
|
### Valídalo en la integración continua
|
|
94
96
|
|
|
@@ -114,6 +116,12 @@ jobs:
|
|
|
114
116
|
- run: npx @dogfood-lab/study-swarm@latest lint dispatches/
|
|
115
117
|
```
|
|
116
118
|
|
|
119
|
+
### Fija un envío para su reproducción (`dispatch.lock.json`)
|
|
120
|
+
|
|
121
|
+
Un envío verificado y con base sólida solo es auditable si se puede indicar *qué lo produjo*. `study-swarm lock` escribe un archivo de bloqueo complementario que, según el agente de investigación, utiliza el direccionamiento por contenido para incluir el **ID de modelo resuelto** (nunca un alias dinámico), el **SHA-256 del mensaje exacto en bytes** y el **SHA-256 del esquema de la herramienta** que se le proporcionó, más el **comprobante externo del verificador**, todo integrado en un único `lock_sha256`. `study-swarm lock --verify` vuelve a generar esos hashes y falla si detecta alguna desviación, por lo que cualquier cambio en el mensaje, un modelo diferente o una modificación en la herramienta se detectan. Este es el estándar de reproducibilidad [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm) implementado. El sistema emite el registro; la CLI permanece sin dependencias y sin conexión a la red, solo normaliza (RFC 8785), calcula hashes y lo valida.
|
|
122
|
+
|
|
123
|
+
**Fija las entradas, no las salidas.** Fijar el modelo + el mensaje + la temperatura *no* hace que la salida de un LLM sea idéntica en bits; la invariancia por lotes, la no asociatividad de punto flotante, el enrutamiento de mezcla de expertos y la desviación silenciosa del proveedor están fuera del control de una herramienta offline. Por lo tanto, el bloqueo le proporciona **entradas reproducibles y salidas con detección de desviaciones**, nunca una "reproducción determinista". El diseño se basa, cita por cita, en [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md): el primer envío que incluye su propio bloqueo ([`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json)).
|
|
124
|
+
|
|
117
125
|
## Por qué funciona, en pocas palabras
|
|
118
126
|
|
|
119
127
|
**Actual:** el campo evoluciona 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.
|
|
@@ -124,7 +132,7 @@ jobs:
|
|
|
124
132
|
|
|
125
133
|
## Estado
|
|
126
134
|
|
|
127
|
-
Un protocolo funcional, verificado externamente por su
|
|
135
|
+
Un protocolo funcional, verificado externamente por su propia maquinaria: una familia de modelos diferente verifica sus citas (vea la prueba anterior). **v1.1** mejora el verificador donde la primera versión era silenciosa: solidez descompuesta/ternaria, fundamentación en el momento de la generación, una cascada controlada por un oráculo para combinar lentes y abstención calibrada; todo ello se basa en el envío v1.1 verificado. **v1.2** hace que un envío sea reproducible a nivel de bytes: `study-swarm lock` fija el modelo resuelto, el mensaje y el esquema de la herramienta por paso, además del comprobante del verificador, y `lock --verify` falla si detecta alguna desviación. 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.
|
|
128
136
|
|
|
129
137
|
Con licencia MIT.
|
|
130
138
|
|
package/README.fr.md
CHANGED
|
@@ -15,16 +15,16 @@
|
|
|
15
15
|
|
|
16
16
|
**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.**
|
|
17
17
|
|
|
18
|
-
`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 :
|
|
18
|
+
`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 : déployez des agents de recherche parallèles, exigez des résultats spécifiques cités et soumettez chaque citation à un **vérificateur externe d’une famille de modèles différente** avant qu’elle n’influence la conception.
|
|
19
19
|
|
|
20
20
|
Il applique sa propre méthode. Le protocole prescrit l’utilisation d’enveloppes protégées par un vérificateur pour les systèmes dont il facilite la conception, il l’applique donc à lui-même. **Aucun modèle ne corrige ses propres devoirs, y compris celui qui exécute le protocole.**
|
|
21
21
|
|
|
22
22
|
## Le protocole en cinq étapes
|
|
23
23
|
|
|
24
|
-
1. **Identifiez** 3 à 5 questions de conception essentielles
|
|
25
|
-
2. **
|
|
24
|
+
1. **Identifiez** 3 à 5 questions de conception essentielles auxquelles des preuves empiriques permettraient de modifier la réponse.
|
|
25
|
+
2. **Déployez** un agent de recherche par question, en parallèle. Chacun doit renvoyer les titres d’articles + les auteurs + les années + les URL + une conclusion en une phrase (la spécificité prime sur l’étendue : « 6 à 8 conclusions bien étayées sont plus efficaces que 20 observations vagues »).
|
|
26
26
|
3. **Synthétisez** les conclusions dans une section intitulée *Justification par la recherche* : `N. <conclusion>. <Auteurs> <année> (<arXiv/DOI>). <implication pour la conception>.`
|
|
27
|
-
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
|
|
27
|
+
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 d’exactitude** 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 signifiant que les citations sont correctes).
|
|
28
28
|
5. **Reliez** chaque choix architectural à une conclusion en utilisant un numéro. Les citations qui n’ont pas d’implication pour la conception sont du bruit.
|
|
29
29
|
|
|
30
30
|
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)**.
|
|
@@ -34,8 +34,8 @@ Les détails complets et exécutables (le tableau d’arrêt, la norme de réfé
|
|
|
34
34
|
Parce que les modes d’échec sont documentés, et non hypothétiques :
|
|
35
35
|
|
|
36
36
|
- **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’autocritique est inerte.
|
|
37
|
-
- **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
|
|
38
|
-
- **Les citations sont les
|
|
37
|
+
- **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.
|
|
38
|
+
- **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**.
|
|
39
39
|
- **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 de la chaîne de pensée 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)) — la chaîne de pensée est une rationalisation a posteriori. Le vérificateur voit uniquement l’affirmation de citation, jamais le « pourquoi je l’ai incluse ».
|
|
40
40
|
- **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.
|
|
41
41
|
|
|
@@ -43,27 +43,27 @@ Parce que les modes d’échec sont documentés, et non hypothétiques :
|
|
|
43
43
|
|
|
44
44
|
À 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 y intégrant deux pièges aveugles :
|
|
45
45
|
|
|
46
|
-
| Piège
|
|
46
|
+
| Piège implanté | Mistral | IBM Granite | Vérité terrain |
|
|
47
47
|
|---|---|---|---|
|
|
48
48
|
| 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é |
|
|
49
49
|
| un article fabriqué affirmant que « 98 % des erreurs sont éliminées, aucun oracle n’est nécessaire » | **caught** (fabricated) | **caught** (fabricated) | fabriqué |
|
|
50
50
|
|
|
51
|
-
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.
|
|
51
|
+
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. De plus, l’oracle de récupération a détecté deux *vrais* mauvaises attributions 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é 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.
|
|
52
52
|
|
|
53
53
|
Cette seule expérience résume la thèse : **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.**
|
|
54
54
|
|
|
55
55
|
### …et encore une fois, pour concevoir la version 1.1
|
|
56
56
|
|
|
57
|
-
Les améliorations de la version 1.1 ont été choisies de la même manière : en exécutant « study-swarm » sur « study-swarm ». Quatre questions auxquelles la première version n’avait pas répondu (« Je pense que… ») (comment *
|
|
57
|
+
Les améliorations de la version 1.1 ont été choisies de la même manière : en exécutant « study-swarm » sur « study-swarm ». Quatre questions auxquelles la première version n’avait pas répondu (« Je pense que… ») (comment *automatiser* la vérification de la pertinence, faut-il effectuer cette vérification au moment de la génération, comment *combiner* les différentes sources d’information, faut-il s’abstenir en cas d’incertitude calibrée) ont été soumises à des agents de recherche parallèles, et les **27 références résultantes** ont été validées à l’étape 4 avant d’influencer la conception. L’oracle de récupération a confirmé que **27 sur 27 existent**, y compris six articles datant de 2025-2026 qu’un modèle paramétrique aurait faussement identifiés comme étant fabriqués, et il a corrigé cinq attributions qu’un modèle n’aurait pas pu faire, dont une véritable erreur d’attribution à un premier auteur que l’agent de recherche avait lui-même signalée. En exécutant le processus sans raisonnement préalable, les différentes sources d’information ont même reproduit leurs propres modes d’échec documentés dans notre analyse : l’une a identifié de manière erronée un article réel et leur *divergence* a déclenché une escalade, exactement comme le prévoit la séquence. L’analyse effectuée est fournie sous forme de [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md) ; les améliorations qui ont été validées (pertinence décomposée/ternaire, validation au moment de la génération, séquence validée par l’oracle et abstention calibrée) sont disponibles dans [PROTOCOL.md](PROTOCOL.md).
|
|
58
58
|
|
|
59
59
|
## Comment cela fonctionne
|
|
60
60
|
|
|
61
|
-
Vous pouvez exécuter le protocole manuellement : tout modèle d’une famille différente, associé à la résolution de l’identifiant arXiv/DOI,
|
|
61
|
+
Vous pouvez exécuter le protocole manuellement : tout modèle d’une famille différente, associé à la résolution de l’identifiant arXiv/DOI, suffit pour l’étape 4. Deux outils complémentaires permettent de ne réaliser qu’une seule opération :
|
|
62
62
|
|
|
63
|
-
- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** : le vérificateur d’exécution
|
|
64
|
-
- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** : fournit `roleos verify-citations <dispatch>`,
|
|
63
|
+
- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)** : le vérificateur d’exécution ; il effectue un routage en fonction de la famille, supprime le raisonnement, utilise une adjudication multi-sources et établit un seuil minimal déterministe pour l’existence des références (arXiv → Crossref), et fournit des reçus signés.
|
|
64
|
+
- **[role-os](https://github.com/mcp-tool-shop-org/role-os)** : il fournit la commande `roleos verify-citations <dispatch>`, qui extrait les références d’une analyse et les valide à l’aide de prism.
|
|
65
65
|
|
|
66
|
-
Le transfert se fait par le biais du format de l’analyse : une conclusion rédigée sous la forme
|
|
66
|
+
Le transfert se fait par le biais du format de l’analyse : une conclusion rédigée sous la forme `N. **conclusion.** Auteurs année (arXiv|DOI). implication.` — avec **un identifiant résolvable par conclusion** — est exactement ce que `roleos verify-citations` extrait et valide. Une analyse propre, validée par « lint », se transfère sans problème ; une citation mal formée est ce que l’outil signale comme non analysée. Ce contrat est ce que `study-swarm lint` vérifie localement, de sorte que les étapes 3 et 4 s’accordent sur la définition d’une citation.
|
|
67
67
|
|
|
68
68
|
## Interface en ligne de commande (CLI)
|
|
69
69
|
|
|
@@ -75,11 +75,13 @@ npm i -g @dogfood-lab/study-swarm # or run ad-hoc: npx @dogfood-lab/study-sw
|
|
|
75
75
|
|---|---|
|
|
76
76
|
| `study-swarm protocol` | Affiche le protocole complet : les cinq étapes, la table d’arrêt et la norme de référencement. |
|
|
77
77
|
| `study-swarm new <slug>` | Crée un fichier `<slug>.dispatch.md` avec le squelette des cinq étapes à compléter. |
|
|
78
|
-
| `study-swarm lint [--json] <path…>` | Vérifie
|
|
78
|
+
| `study-swarm lint [--json] <path…>` | Vérifie la *pertinence de la recherche* d’une analyse 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 du type « des études montrent que… » ne sont pas acceptées. En cas de violation, le programme se termine avec le code `1`, ce qui permet de contrôler l’intégration continue (CI). Un `<path>` peut être un fichier, un répertoire (validé récursivement pour les fichiers `*.dispatch.md`) ou `-` pour l’entrée standard ; l’option `--json` génère un rapport lisible par machine. |
|
|
79
|
+
| `study-swarm lock <dispatch> --from <orchestration.json>` | Enregistre une analyse pour la relecture : écrit le contenu de `<dispatch>.lock.json`, qui, par agent, adresse le **modèle résolu** (jamais un alias flottant), le **SHA-256 de l’invite exacte**, et le **SHA-256 du schéma d’outil** qui lui a été fourni, ainsi que le **reçu du vérificateur** de l’étape 4, dans un seul `lock_sha256`. |
|
|
80
|
+
| `study-swarm lock --verify <dispatch> [--from …]` | Recalcule ces hachages et vérifie qu’ils correspondent à ceux enregistrés ; en cas d’écart, le programme se termine avec le code `1`, ce qui permet de contrôler l’intégration continue (CI), comme un fichier de verrouillage des dépendances. Sans l’option `--from`, il vérifie l’intégrité du propre fichier de verrouillage. |
|
|
79
81
|
|
|
80
|
-
`lint` est déterministe
|
|
82
|
+
`lint` est déterministe : il n’effectue aucun appel au modèle, ce qui le rend sûr pour l’intégration continue (CI). Il applique localement la **norme de référencement de l’étape 3** ; la vérification basée sur un modèle à l’**étape 4** s’appuie toujours sur [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
|
|
81
83
|
|
|
82
|
-
Exemple
|
|
84
|
+
Exemple de boucle typique :
|
|
83
85
|
|
|
84
86
|
```bash
|
|
85
87
|
study-swarm new my-decision # creates my-decision.dispatch.md
|
|
@@ -88,11 +90,11 @@ study-swarm lint my-decision.dispatch.md # enforce the sourcing standard
|
|
|
88
90
|
roleos verify-citations my-decision.dispatch.md # model-based Step 4 (different family, via prism)
|
|
89
91
|
```
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
Trois analyses complètes et validées par « lint » sont fournies à titre d’exemple : [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) (la décision centrale du protocole, concise), [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md) (l’analyse complète de la version 1.1 : 27 références, chacune d’entre elles ayant été validée en externe) et [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) (la conception du verrouillage de la version 1.2 : 39 références, validées par l’outil, et la première analyse à inclure son propre fichier de verrouillage).
|
|
92
94
|
|
|
93
95
|
### Intégration dans l’intégration continue (CI)
|
|
94
96
|
|
|
95
|
-
`lint` prend un fichier, un répertoire (
|
|
97
|
+
`lint` prend un fichier, un répertoire (validé récursivement pour les fichiers `*.dispatch.md`) ou `-` pour l’entrée standard, et `--json` génère un rapport lisible par machine. Intégrez ceci dans votre dépôt afin de contrôler le référencement de chaque analyse à chaque demande d’extraction (un exemple que vous pouvez copier-coller est également disponible dans [`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml)) :
|
|
96
98
|
|
|
97
99
|
```yaml
|
|
98
100
|
# .github/workflows/dispatches.yml
|
|
@@ -114,17 +116,23 @@ jobs:
|
|
|
114
116
|
- run: npx @dogfood-lab/study-swarm@latest lint dispatches/
|
|
115
117
|
```
|
|
116
118
|
|
|
117
|
-
|
|
119
|
+
### Enregistre une analyse pour la relecture (`dispatch.lock.json`)
|
|
118
120
|
|
|
119
|
-
|
|
121
|
+
Une analyse validée et vérifiée n’est auditable que si vous pouvez indiquer *ce qui l’a produite*. `study-swarm lock` écrit un fichier de verrouillage associé qui, par agent de recherche, adresse le **modèle résolu** (jamais un alias flottant), le **SHA-256 de l’invite exacte**, et le **SHA-256 du schéma d’outil** qui lui a été fourni, ainsi que le **reçu du vérificateur externe** dans un seul `lock_sha256`. `study-swarm lock --verify` recalcule ces hachages et échoue si l’un d’eux diffère, de sorte qu’une invite modifiée, un modèle remplacé ou une surface d’outil décalée sont détectés : la norme de reproductibilité [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm), rendue exécutable. L’ensemble des outils émet le rapport ; l’interface en ligne de commande reste sans dépendance et sans connexion réseau, se contentant de normaliser (RFC 8785), de hacher et de valider les données.
|
|
122
|
+
|
|
123
|
+
**Il fixe les entrées, pas les sorties.** Le fait de fixer le modèle + l’invite + la température ne permet *pas* d’obtenir une sortie d’un LLM qui soit exactement identique à chaque fois — l’invariance par lots, la non-associativité des nombres à virgule flottante, le routage du mélange d’experts et la dérive silencieuse du fournisseur sont autant de facteurs qui échappent au contrôle d’un outil hors ligne. Ainsi, le verrouillage vous donne des **entrées reproductibles et des sorties dont la dérive peut être détectée**, mais jamais une « reproduction déterministe ». La conception est basée sur des données probantes, citation par citation, dans [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) — le premier outil à intégrer son propre verrouillage ([`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json)).
|
|
124
|
+
|
|
125
|
+
## Pourquoi cela fonctionne, en un clin d’œil
|
|
126
|
+
|
|
127
|
+
**Efficacité** — le domaine évolue rapidement ; exiger des études spécifiques sur plusieurs années empêcherait la publication de nouvelles versions 18 mois plus tard. **Fonctionnalité** — les données probantes 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 *erronée* — Bansal et al., 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Sécurité** — l’enveloppe protégée par le vérificateur est l’architecture que les données probantes soutiennent, et le protocole l’applique à sa propre sortie. La recherche de sources n’est pas un exercice académique ; il s’agit du fil conducteur des données probantes.
|
|
120
128
|
|
|
121
129
|
## Sécurité
|
|
122
130
|
|
|
123
|
-
`study-swarm` fournit une **CLI légère et sans dépendances** (`study-swarm`)
|
|
131
|
+
`study-swarm` fournit une **CLI légère et sans dépendances** (`study-swarm`) en plus de la méthodologie. Il n’effectue **aucune requête réseau ou vers le modèle** et ne collecte **aucune télémétrie** ; il n’y a pas de secrets ni d’identifiants dans le code source. Au moment de l’exécution, il lit uniquement le fichier que vous transmettez à `lint` et écrit un seul fichier `<slug>.dispatch.md` dans le répertoire courant pour `new` (il refuse d’écraser les fichiers et ne fonctionne jamais en dehors du répertoire de travail). La vérification basée sur le modèle décrite par la méthodologie (étape 4) est effectuée par les outils associés, et non par ce paquet. Voir [SECURITY.md](SECURITY.md).
|
|
124
132
|
|
|
125
133
|
## État actuel
|
|
126
134
|
|
|
127
|
-
Un protocole fonctionnel, vérifié
|
|
135
|
+
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). La **version 1.1** affine le vérificateur là où la première version était silencieuse : fondement décomposé/ternaire, ancrage au moment de la génération, cascade contrôlée par un oracle pour combiner les objectifs et abstention calibrée — chacun étant basé sur les données probantes de la version 1.1 vérifiée. La **version 1.2** rend une sortie reproductible : `study-swarm lock` fixe le modèle résolu, l’invite et le schéma d’outil pour chaque étape, ainsi que le reçu du vérificateur, et `lock --verify` échoue en cas de dérive. 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.
|
|
128
136
|
|
|
129
137
|
Licence MIT.
|
|
130
138
|
|
package/README.hi.md
CHANGED
|
@@ -76,6 +76,8 @@ npm i -g @dogfood-lab/study-swarm # or run ad-hoc: npx @dogfood-lab/study-sw
|
|
|
76
76
|
| `study-swarm protocol` | पूरे प्रोटोकॉल को प्रिंट करें - पांच चरण, रोक तालिका, सोर्सिंग मानक। |
|
|
77
77
|
| `study-swarm new <slug>` | पांच-चरणीय ढांचे के साथ `<slug>.dispatch.md` बनाएं ताकि इसे भरा जा सके। |
|
|
78
78
|
| `study-swarm lint [--json] <path…>` | एक प्रेषण की *अनुसंधान आधार* की जांच सोर्सिंग मानक के विरुद्ध करें - प्रत्येक निष्कर्ष में एक लेखक, एक वर्ष और एक हल करने योग्य पहचानकर्ता (arXiv / DOI / URL) होना चाहिए; "अध्ययनों से पता चलता है..." जैसे अस्पष्ट कथन अस्वीकार कर दिए जाते हैं। उल्लंघन होने पर `1` से बाहर निकलें, इसलिए यह CI को संसाधित करता है। `<path>` एक फ़ाइल, एक निर्देशिका (जो `*.dispatch.md` के लिए पुनरावर्ती रूप से जांच की जाती है), या `-` stdin के लिए हो सकता है; `--json` मशीन-पठनीय रिपोर्ट उत्सर्जित करता है। |
|
|
79
|
+
| `study-swarm lock <dispatch> --from <orchestration.json>` | किसी प्रेषण को फिर से चलाने के लिए पिन करें – `<dispatch>.lock.json` सामग्री-आधारित, चरण-2 एजेंट के अनुसार लिखें, **समाधान मॉडल आईडी** + **बाइट-सटीक प्रॉम्प्ट का SHA-256** + **टूल स्कीमा का SHA-256**, साथ ही चरण-4 **सत्यापन रसीद**, एक `lock_sha256` में समेकित करें। |
|
|
80
|
+
| `study-swarm lock --verify <dispatch> [--from …]` | उन हैश को फिर से प्राप्त करें और पुष्टि करें कि वे लॉक से मेल खाते हैं; यदि कोई विचलन होता है, तो यह `1` पर समाप्त हो जाएगा, इसलिए यह पैकेज लॉकफ़ाइल की तरह CI को नियंत्रित करता है। `--from` के बिना, यह लॉक की अपनी अखंडता की जांच करता है। |
|
|
79
81
|
|
|
80
82
|
`lint` नियतात्मक है - शून्य मॉडल कॉल - इसलिए यह CI में सुरक्षित है। यह स्थानीय रूप से **चरण 3 के सोर्सिंग मानक** को लागू करता है; मॉडल-आधारित **चरण 4** सत्यापन अभी भी [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → प्रिज्म पर निर्भर करता है।
|
|
81
83
|
|
|
@@ -88,7 +90,7 @@ study-swarm lint my-decision.dispatch.md # enforce the sourcing standard
|
|
|
88
90
|
roleos verify-citations my-decision.dispatch.md # model-based Step 4 (different family, via prism)
|
|
89
91
|
```
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
तीन पूर्ण, त्रुटि-मुक्त प्रेषण संदर्भों के रूप में भेजे जाते हैं: [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) (प्रोटोकॉल का केंद्रीय निर्णय, संक्षिप्त), [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md) (पूर्ण v1.1 डिज़ाइन पास – 27 उद्धरण, जिनमें से प्रत्येक को बाहरी रूप से सत्यापित किया गया है), और [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) (v1.2 लॉक डिज़ाइन – 39 उद्धरण, रनर के माध्यम से नियंत्रित, और पहला प्रेषण जो अपना स्वयं का लॉक भेजता है)।
|
|
92
94
|
|
|
93
95
|
### इसे CI में संसाधित करें
|
|
94
96
|
|
|
@@ -114,6 +116,12 @@ jobs:
|
|
|
114
116
|
- run: npx @dogfood-lab/study-swarm@latest lint dispatches/
|
|
115
117
|
```
|
|
116
118
|
|
|
119
|
+
### किसी प्रेषण को फिर से चलाने के लिए पिन करें (`dispatch.lock.json`)
|
|
120
|
+
|
|
121
|
+
एक सत्यापित प्रेषण केवल तभी ऑडिट करने योग्य होता है जब आप बता सकें कि *इसे क्या उत्पन्न किया*। `study-swarm lock` एक सहायक लॉकफ़ाइल लिखता है जो सामग्री-आधारित है, अनुसंधान एजेंट के अनुसार, **समाधान मॉडल आईडी** (कभी भी अस्थायी उपनाम नहीं), **बाइट-सटीक प्रॉम्प्ट का SHA-256**, और **टूल स्कीमा का SHA-256** जिसे दिया गया था, साथ ही बाहरी **सत्यापन रसीद** – एक `lock_sha256` में समेकित। `study-swarm lock --verify` उन हैश को फिर से प्राप्त करता है और किसी भी विचलन पर विफल हो जाता है, इसलिए बदले हुए प्रॉम्प्ट, बदले गए मॉडल या परिवर्तित टूल सतह का पता लगाया जा सकता है – [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm) पुनरुत्पादनीयता मानक, जिसे निष्पादन योग्य बनाया गया है। हार्नेस रिकॉर्ड उत्सर्जित करता है; CLI शून्य-निर्भर और नेटवर्क-मुक्त रहता है, केवल मानकीकरण (RFC 8785), हैशिंग और मान्य करता है।
|
|
122
|
+
|
|
123
|
+
**यह इनपुट को पिन करता है, आउटपुट को नहीं।** मॉडल + प्रॉम्प्ट + तापमान को पिन करने से LLM का आउटपुट बिट-समान नहीं होगा – बैच-अपरिवर्तनशीलता, फ़्लोटिंग-पॉइंट गैर-सहयोगिता, विशेषज्ञ मिश्रण रूटिंग और मौन प्रदाता विचलन सभी एक ऑफ़लाइन टूल के नियंत्रण से बाहर हैं। इसलिए लॉक आपको **पुन: चलाने योग्य इनपुट और विचलन-पता लगाने योग्य आउटपुट** देता है, कभी भी "निर्धारित पुन: चलाना" नहीं। डिज़ाइन [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) में उद्धरण द्वारा उद्धरण के आधार पर है – पहला प्रेषण जो अपना स्वयं का लॉक भेजता है ([`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json))।
|
|
124
|
+
|
|
117
125
|
## यह कैसे काम करता है, एक सांस में
|
|
118
126
|
|
|
119
127
|
**वर्तमान** - क्षेत्र तेजी से आगे बढ़ रहा है; विशिष्ट अध्ययनों के साथ वर्षों की मांग करने से डिज़ाइन 18 महीने पीछे नहीं रहते हैं। **कार्यात्मक** - साक्ष्य दिखाते हैं कि क्या *असफल* होता है, न कि केवल यह कि क्या काम करता है (व्याख्याएँ *गलत* AI पर अत्यधिक निर्भरता बढ़ा सकती हैं - बंसल एट अल. 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779))। **सुरक्षित** - सत्यापनकर्ता-संरक्षित आवरण वह आर्किटेक्चर है जिसे साक्ष्य समर्थन देता है, और प्रोटोकॉल इसे अपने स्वयं के आउटपुट पर लागू करता है। सोर्सिंग अकादमिक नाटक नहीं है; यह साक्ष्य श्रृंखला है।
|
|
@@ -124,7 +132,7 @@ jobs:
|
|
|
124
132
|
|
|
125
133
|
## स्थिति
|
|
126
134
|
|
|
127
|
-
एक कार्यशील प्रोटोकॉल,
|
|
135
|
+
एक कार्यशील प्रोटोकॉल, जिसकी अपनी मशीनरी द्वारा बाहरी रूप से पुष्टि की जाती है – एक अलग मॉडल परिवार इसके उद्धरणों की जांच करता है (ऊपर प्रमाण देखें)। **v1.1** सत्यापनकर्ता को तेज करता है जहाँ पहला संस्करण मौन था: विघटित/त्रिक आधार, पीढ़ी-समय आधार, लेंस को संयोजित करने के लिए एक ओरेकल-गेटेड कैस्केड और अंशांकित परित्याग – प्रत्येक सत्यापित v1.1 प्रेषण में आधारित। **v1.2** एक प्रेषण को बाइट-पुन: चलाने योग्य बनाता है: `study-swarm lock` चरण दर चरण समाधान मॉडल, प्रॉम्प्ट और टूल स्कीमा को पिन करता है, साथ ही सत्यापनकर्ता रसीद भी, और `lock --verify` विचलन पर विफल हो जाता है। यह रिपॉजिटरी सार्वजनिक संदर्भ है; [PROTOCOL.md](PROTOCOL.md) निष्पादन योग्य आकार है। [dogfood-lab](https://github.com/dogfood-lab) परिवार का हिस्सा – AI युग में निर्माण के लिए विधियाँ और प्रदर्शन।
|
|
128
136
|
|
|
129
137
|
MIT लाइसेंस प्राप्त।
|
|
130
138
|
|
package/README.it.md
CHANGED
|
@@ -17,55 +17,55 @@
|
|
|
17
17
|
|
|
18
18
|
`study-swarm` è un protocollo, non uno strumento. Quando si prende una decisione progettuale importante con un LLM (un nuovo livello di prodotto, una scelta architettonica, una valutazione sul fatto se fidarsi o meno del modello), improvvisare partendo da principi generali porta a progetti obsoleti e citare articoli a memoria porta a progetti basati su fonti inesistenti o che non dicono ciò che si pensa. `study-swarm` sostituisce entrambi: attiva agenti di ricerca paralleli, richiede risultati specifici dalle ricerche citate e sottopone ogni citazione a un **verificatore esterno appartenente a una famiglia di modelli diversa** prima che influenzi il progetto.
|
|
19
19
|
|
|
20
|
-
Applica la propria
|
|
20
|
+
Applica la propria "medicina". Il protocollo prevede l'utilizzo di verificatori per proteggere le informazioni contenute nei sistemi che aiuta a progettare, quindi lo applica anche a se stesso. **Nessun modello valuta il proprio lavoro, incluso quello che esegue il protocollo.**
|
|
21
21
|
|
|
22
22
|
## Il protocollo in cinque passaggi:
|
|
23
23
|
|
|
24
|
-
1. **Identificare** 3-5 domande progettuali fondamentali
|
|
25
|
-
2. **Attivare** un agente di ricerca per ogni domanda, in parallelo. Ognuno deve restituire titoli degli articoli + autori + anni + URL +
|
|
26
|
-
3. **Sintetizzare** i risultati in una sezione
|
|
27
|
-
4. **Verificare esternamente** — una *famiglia di modelli diversa*, priva di capacità di ragionamento, controlla ogni citazione in due fasi: un **oracolo di recupero** conferma l'
|
|
28
|
-
5. **Collegare** ogni scelta architettonica a un risultato specifico, tramite numero. Le citazioni prive di implicazioni progettuali sono
|
|
24
|
+
1. **Identificare** 3-5 domande progettuali fondamentali su cui le prove empiriche potrebbero cambiare la risposta.
|
|
25
|
+
2. **Attivare** un agente di ricerca per ogni domanda, in parallelo. Ognuno deve restituire titoli degli articoli + autori + anni + URL + una breve sintesi (una frase) — dare priorità alla specificità rispetto all'ampiezza ("6-8 risultati ben documentati sono meglio di 20 affermazioni vaghe").
|
|
26
|
+
3. **Sintetizzare** i risultati in una sezione "Fondamento della ricerca": `N. **<risultato>.** <Autori> <anno> (<arXiv/DOI>). <implicazione progettuale>.`
|
|
27
|
+
4. **Verificare esternamente** — una *famiglia di modelli diversa*, priva di capacità di ragionamento, controlla ogni citazione in due fasi: un **oracolo di recupero** conferma che l'articolo esiste (non si basa mai sulla memoria del modello), quindi una "lente di fondatezza" verifica che il risultato corrisponda alla fonte. **Interrompere** se la citazione è fabbricata o attribuita in modo errato; **interrompere e segnalare** se il verificatore o l'oracolo di recupero non sono disponibili (non interpretare mai l'assenza come "le citazioni sono corrette").
|
|
28
|
+
5. **Collegare** ogni scelta architettonica a un risultato specifico, tramite numero. Le citazioni prive di implicazioni progettuali sono rumore.
|
|
29
29
|
|
|
30
|
-
I dettagli completi e
|
|
30
|
+
I dettagli completi e eseguibili — la tabella di interruzione, lo standard per le fonti, la regola dell'insieme — si trovano in **[PROTOCOL.md](PROTOCOL.md)**.
|
|
31
31
|
|
|
32
|
-
## Perché una *famiglia
|
|
32
|
+
## Perché una *famiglia diversa*, priva di capacità di ragionamento?
|
|
33
33
|
|
|
34
34
|
Perché i modi di errore sono documentati, non ipotetici:
|
|
35
35
|
|
|
36
36
|
- **Gli LLM non possono verificare in modo affidabile i propri risultati.** 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)) — il verificatore esterno offre i vantaggi; l'autovalutazione è inerte.
|
|
37
|
-
- **I giudici della stessa famiglia tendono a favorire se stessi.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — l'autoriconoscimento è correlato *linearmente*
|
|
38
|
-
- **Le citazioni sono dove gli LLM mentono.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — il 55% delle citazioni di GPT-3.5 / il 18%
|
|
37
|
+
- **I giudici della stessa famiglia tendono a favorire se stessi.** Panickssery, Bowman & Feng 2024 ([arXiv:2404.13076](https://arxiv.org/abs/2404.13076)) — l'autoriconoscimento è correlato *linearmente* all'autopreferenza, quindi un'occlusione parziale non aiuta. Verga et al. 2024 ([arXiv:2404.18796](https://arxiv.org/abs/2404.18796), PoLL) — un gruppo di esperti provenienti da famiglie diverse è meno influenzato, con un costo inferiore di circa il 7%.
|
|
38
|
+
- **Le citazioni sono dove gli LLM mentono.** Walters & Wilder 2023 ([doi:10.1038/s41598-023-41032-5](https://doi.org/10.1038/s41598-023-41032-5)) — il 55% delle citazioni di GPT-3.5 / il 18% di GPT-4 sono fabbricate. Onweller et al. 2026 ([arXiv:2605.06635](https://arxiv.org/abs/2605.06635)) — i collegamenti risolvono oltre il 94% delle volte, ma solo il 39-77% del contenuto citato supporta effettivamente l'affermazione. Pertanto, l'esistenza deve essere verificata tramite **recupero, non richiamo**.
|
|
39
39
|
- **Nascondere il ragionamento del generatore.** Khalifa et al. 2026 ([arXiv:2601.14691](https://arxiv.org/abs/2601.14691), "Gaming the Judge") — la sola manipolazione della catena di pensiero aumenta i falsi positivi del giudice fino al 90%, mantenendo le azioni fisse. Turpin et al. 2023 ([arXiv:2305.04388](https://arxiv.org/abs/2305.04388)) — la catena di pensiero è una razionalizzazione post-hoc. Il verificatore vede solo l'affermazione della citazione, mai il "perché ho incluso questo".
|
|
40
|
-
- **La diversità supera la quantità.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — quattro verificatori con una correlazione a coppie ρ ∈ [0,05, 0,25] superano qualsiasi singolo verificatore tramite copertura submodulare. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — gli errori degli LLM sono *correlati*, quindi la variabile più importante è la diversità delle lenti, non la quantità assoluta.
|
|
40
|
+
- **La diversità supera la quantità.** Rajan 2025 ([arXiv:2511.16708](https://arxiv.org/abs/2511.16708)) — quattro verificatori con una correlazione a coppie ρ ∈ [0,05, 0,25] superano qualsiasi singolo verificatore tramite copertura submodulare. Kim et al. 2025 ([arXiv:2506.07962](https://arxiv.org/abs/2506.07962)) — gli errori degli LLM sono *correlati*, quindi la variabile più importante è la diversità delle "lenti", non la quantità assoluta.
|
|
41
41
|
|
|
42
42
|
## Funziona davvero? (prova)
|
|
43
43
|
|
|
44
|
-
Come test, il protocollo è stato applicato alle proprie citazioni. Due famiglie diverse da Claude e non correlate — **Mistral** (`mistral-small:24b`) e **IBM Granite** (`granite4.1:30b`) — hanno controllato un insieme di citazioni, senza capacità di ragionamento, con due trappole nascoste:
|
|
44
|
+
Come test, il protocollo è stato applicato alle proprie citazioni. Due famiglie diverse da Claude e non correlate — **Mistral** (`mistral-small:24b`) e **IBM Granite** (`granite4.1:30b`) — hanno controllato un insieme di citazioni, senza capacità di ragionamento, con due "trappole" nascoste:
|
|
45
45
|
|
|
46
|
-
| Trappola
|
|
46
|
+
| Trappola piazzata | Mistral | IBM Granite | Verità oggettiva |
|
|
47
47
|
|---|---|---|---|
|
|
48
|
-
| Il ragionamento della catena di pensiero è attribuito a "Nakamura & Olsen" |
|
|
48
|
+
| Il ragionamento della catena di pensiero è attribuito a "Nakamura & Olsen" | mancato | **rilevato** (attribuito in modo errato → in realtà Wei et al. 2022, arXiv:2201.11903) | attribuito in modo errato |
|
|
49
49
|
| un articolo fabbricato con la frase "il 98% degli errori è stato eliminato, non è necessario alcun oracolo" | **caught** (fabricated) | **caught** (fabricated) | fabbricato |
|
|
50
50
|
|
|
51
|
-
Nessuna delle due famiglie ha rilevato entrambe le trappole da sola, ma la loro **unione ha rilevato 2/2**. Un singolo giudice avrebbe accettato l'attribuzione errata. Separatamente, l'oracolo di recupero ha individuato due *vere* attribuzioni errate nei nostri documenti progettuali (articoli citati con il
|
|
51
|
+
Nessuna delle due famiglie ha rilevato entrambe le trappole da sola, ma la loro **unione ha rilevato 2/2**. Un singolo giudice avrebbe accettato l'attribuzione errata. Separatamente, l'oracolo di recupero ha individuato due *vere* attribuzioni errate nei nostri documenti progettuali (articoli citati con il primo autore sbagliato) che nessun LLM parametrico avrebbe potuto segnalare — e ha confermato correttamente articoli genuini del 2026 che entrambi gli LLM hanno erroneamente contrassegnato come fabbricati semplicemente perché gli articoli sono successivi alla loro data di addestramento. Quest'ultimo punto è la ragione principale per cui il controllo dell'esistenza nel passaggio 4 **deve** essere effettuato tramite un oracolo di recupero, e non tramite un LLM.
|
|
52
52
|
|
|
53
|
-
Questa singola esecuzione rappresenta la tesi in miniatura: **lenti correlate + un oracolo di recupero per l'esistenza superano qualsiasi singolo giudice esperto.**
|
|
53
|
+
Questa singola esecuzione rappresenta la tesi in miniatura: **"lenti" correlate + un oracolo di recupero per l'esistenza superano qualsiasi singolo giudice esperto.**
|
|
54
54
|
|
|
55
55
|
### ...e ancora, per progettare la versione 1.1
|
|
56
56
|
|
|
57
|
-
Le modifiche della versione 1.1 sono state scelte nello stesso modo: eseguendo `study-swarm` su `study-swarm`. Quattro domande a cui la prima versione lasciava spazio per un "a mio parere" (come *meccanizzare* il controllo di fondatezza, se effettuare la verifica al momento della generazione, come *combinare* le diverse
|
|
57
|
+
Le modifiche della versione 1.1 sono state scelte nello stesso modo: eseguendo `study-swarm` su `study-swarm`. Quattro domande a cui la prima versione lasciava spazio per un "a mio parere" (come *meccanizzare* il controllo di fondatezza, se effettuare la verifica al momento della generazione, come *combinare* le diverse prospettive, se astenersi in caso di incertezza calibrata) sono state indirizzate ad agenti di ricerca paralleli e tutte le **27 citazioni risultanti** sono state verificate tramite il passaggio 4 prima che qualsiasi elemento influenzasse la progettazione. L'oracolo di recupero ha confermato l'esistenza di **tutte le 27 citazioni**, incluse sei pubblicazioni del 2025-2026 che un modello parametrico avrebbe erroneamente classificato come fabbricate, e ha corretto cinque attribuzioni che un modello non sarebbe stato in grado di fare, tra cui una reale errata attribuzione dell'autore principale individuata dall'agente di ricerca. Eseguendo l'analisi senza ragionamento deduttivo, le diverse prospettive hanno persino riprodotto i propri noti punti deboli nel nostro sistema: un elemento ha identificato erroneamente una pubblicazione reale e la loro *discrepanza* ha innescato un'escalation, esattamente come previsto. Il sistema funzionante viene fornito come [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md); le modifiche che sono state apportate (fondatezza scomposta/ternaria, verifica al momento della generazione, cascata controllata dall'oracolo e astensione calibrata) sono disponibili in [PROTOCOL.md](PROTOCOL.md).
|
|
58
58
|
|
|
59
|
-
## Come
|
|
59
|
+
## Come è strutturato
|
|
60
60
|
|
|
61
|
-
È possibile eseguire il protocollo manualmente: qualsiasi modello di famiglia diversa, purché
|
|
61
|
+
È possibile eseguire il protocollo manualmente: qualsiasi modello di famiglia diversa, purché si risolvano autonomamente le informazioni da arXiv/DOI, soddisfa il passaggio 4. Due strumenti complementari lo rendono un unico comando:
|
|
62
62
|
|
|
63
|
-
- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)**: il verificatore in fase di esecuzione: instradamento per famiglie diverse, analisi senza ragionamento, arbitraggio multi-
|
|
64
|
-
- **[role-os](https://github.com/mcp-tool-shop-org/role-os)**: fornisce `roleos verify-citations <dispatch>`, lo strumento che estrae le citazioni da un
|
|
63
|
+
- **[prism-verify](https://github.com/mcp-tool-shop-org/prism-verify)**: il verificatore in fase di esecuzione: instradamento per famiglie diverse, analisi senza ragionamento deduttivo, arbitraggio multi-prospettiva, un limite deterministico per l'esistenza dei risultati (arXiv → Crossref) e ricevute firmate.
|
|
64
|
+
- **[role-os](https://github.com/mcp-tool-shop-org/role-os)**: fornisce `roleos verify-citations <dispatch>`, lo strumento che estrae le citazioni da un sistema e le verifica tramite prism.
|
|
65
65
|
|
|
66
|
-
Il passaggio di consegne è il formato
|
|
66
|
+
Il passaggio di consegne è il formato del sistema stesso: un risultato scritto come `N. **risultato.** Autori anno (arXiv|DOI). implicazione.` — con **un identificatore risolvibile per ogni risultato** — è esattamente ciò che `roleos verify-citations` estrae e verifica. Un sistema "pulito" secondo i criteri di linting passa senza problemi; una citazione malformata è ciò che lo strumento segnala come non analizzata. Questo contratto è ciò che `study-swarm lint` controlla a livello locale, in modo che il passaggio 3 e il passaggio 4 concordino su cosa sia una citazione.
|
|
67
67
|
|
|
68
|
-
##
|
|
68
|
+
## Interfaccia a riga di comando (CLI)
|
|
69
69
|
|
|
70
70
|
```bash
|
|
71
71
|
npm i -g @dogfood-lab/study-swarm # or run ad-hoc: npx @dogfood-lab/study-swarm <command>
|
|
@@ -75,9 +75,11 @@ npm i -g @dogfood-lab/study-swarm # or run ad-hoc: npx @dogfood-lab/study-sw
|
|
|
75
75
|
|---|---|
|
|
76
76
|
| `study-swarm protocol` | Stampa l'intero protocollo: i cinque passaggi, la tabella di arresto e lo standard di riferimento. |
|
|
77
77
|
| `study-swarm new <slug>` | Crea uno scheletro `<slug>.dispatch.md` con i cinque passaggi da completare. |
|
|
78
|
-
| `study-swarm lint [--json] <path…>` | Verifica la *fondatezza della ricerca* di un
|
|
78
|
+
| `study-swarm lint [--json] <path…>` | Verifica la *fondatezza della ricerca* di un sistema rispetto allo standard di riferimento: ogni risultato deve avere un autore, un anno e un identificatore risolvibile (arXiv / DOI / URL); le affermazioni generiche del tipo "gli studi dimostrano..." vengono rifiutate. In caso di violazioni, il programma termina con codice `1`, in modo da bloccare l'integrazione continua (CI). Un `<path>` può essere un file, una directory (analizzata ricorsivamente per i file `*.dispatch.md`) o `-` per l'input standard; `--json` emette un report leggibile dalla macchina. |
|
|
79
|
+
| `study-swarm lock <dispatch> --from <orchestration.json>` | Blocca un sistema per la riproduzione: scrive il contenuto di `<dispatch>.lock.json`, che, per ogni agente del passaggio 2, include l'**ID del modello risolto**, l'**SHA-256 del prompt esatto in byte** e l'**SHA-256 dello schema dello strumento**, oltre alla **ricevuta del verificatore** del passaggio 4, tutto racchiuso in un unico `lock_sha256`. |
|
|
80
|
+
| `study-swarm lock --verify <dispatch> [--from …]` | Ricalcola questi hash e verifica che corrispondano al blocco; qualsiasi discrepanza fa terminare il programma con codice `1`, in modo da bloccare l'integrazione continua (CI) come farebbe un file di blocco dei pacchetti. Senza `--from`, controlla l'integrità del blocco stesso. |
|
|
79
81
|
|
|
80
|
-
`lint` è deterministico: non effettua chiamate al modello, quindi è sicuro nell'integrazione continua. Applica lo
|
|
82
|
+
`lint` è deterministico: non effettua chiamate al modello, quindi è sicuro da utilizzare nell'integrazione continua (CI). Applica **lo standard di riferimento del passaggio 3** a livello locale; la verifica basata sul modello del **passaggio 4** si basa ancora su [`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism.
|
|
81
83
|
|
|
82
84
|
Un ciclo tipico:
|
|
83
85
|
|
|
@@ -88,11 +90,11 @@ study-swarm lint my-decision.dispatch.md # enforce the sourcing standard
|
|
|
88
90
|
roleos verify-citations my-decision.dispatch.md # model-based Step 4 (different family, via prism)
|
|
89
91
|
```
|
|
90
92
|
|
|
91
|
-
|
|
93
|
+
Tre sistemi completi e "puliti" secondo i criteri di linting vengono forniti come riferimento: [`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md) (la decisione centrale del protocollo, in forma compatta), [`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md) (l'intero passaggio di progettazione della versione 1.1: 27 citazioni, tutte verificate esternamente) e [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) (il progetto del blocco della versione 1.2: 39 citazioni, verificate tramite lo strumento, ed è il primo sistema a fornire il proprio file di blocco).
|
|
92
94
|
|
|
93
|
-
###
|
|
95
|
+
### Bloccalo nell'integrazione continua (CI)
|
|
94
96
|
|
|
95
|
-
`lint` accetta un file, una directory (analizzata ricorsivamente per i file `*.dispatch.md`) o `-` per l'input standard e `--json` emette un report leggibile dalla macchina.
|
|
97
|
+
`lint` accetta un file, una directory (analizzata ricorsivamente per i file `*.dispatch.md`) o `-` per l'input standard e `--json` emette un report leggibile dalla macchina. Aggiungi questo al tuo repository per verificare la fondatezza di ogni sistema in ogni richiesta pull (un esempio di copia-incolla è disponibile anche in [`examples/study-swarm-ci.yml`](examples/study-swarm-ci.yml)):
|
|
96
98
|
|
|
97
99
|
```yaml
|
|
98
100
|
# .github/workflows/dispatches.yml
|
|
@@ -114,17 +116,23 @@ jobs:
|
|
|
114
116
|
- run: npx @dogfood-lab/study-swarm@latest lint dispatches/
|
|
115
117
|
```
|
|
116
118
|
|
|
117
|
-
|
|
119
|
+
### Blocca un sistema per la riproduzione (`dispatch.lock.json`)
|
|
118
120
|
|
|
119
|
-
|
|
121
|
+
Un sistema fondato e verificato è auditabile solo se si può dire *cosa lo ha prodotto*. `study-swarm lock` scrive un file di blocco complementare che, per ogni agente di ricerca, include l'**ID del modello risolto** (mai un alias fluttuante), l'**SHA-256 del prompt esatto in byte** e l'**SHA-256 dello schema dello strumento** fornito, oltre alla **ricevuta del verificatore esterno**, tutto racchiuso in un unico `lock_sha256`. `study-swarm lock --verify` ricalcola questi hash e fallisce se rileva discrepanze, quindi una modifica al prompt, uno scambio di modello o una variazione della superficie dello strumento vengono rilevati: lo standard di riproducibilità [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm), reso eseguibile. Il sistema emette il record; l'interfaccia a riga di comando rimane senza dipendenze e indipendente dalla rete, limitandosi alla normalizzazione (RFC 8785), all'hashing e alla convalida.
|
|
122
|
+
|
|
123
|
+
**Blocca gli input, non gli output.** Bloccare il modello + prompt + temperatura *non* rende l'output di un LLM identico bit per bit: l'invarianza del batch, la non associatività dei numeri in virgola mobile, il routing a esperti multipli e la deriva silenziosa del provider sono tutti elementi al di fuori del controllo di uno strumento offline. Pertanto, il blocco fornisce **input riproducibili e output con rilevamento della deriva**, mai una "riproduzione deterministica". Il progetto è basato su evidenze, citazione per citazione, in [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) — la prima implementazione che include il proprio blocco ([`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json)).
|
|
124
|
+
|
|
125
|
+
## Perché funziona, in sintesi:
|
|
126
|
+
|
|
127
|
+
**Attuale:** il settore è in rapida evoluzione; richiedere studi specifici che durino anni impedisce di rilasciare i progetti con 18 mesi di ritardo. **Funzionale:** le evidenze mostrano cosa *fallisce*, non solo cosa funziona (le spiegazioni possono aumentare l'eccessiva dipendenza da un'IA *errata* — Bansal et al. 2021, [arXiv:2006.14779](https://arxiv.org/abs/2006.14779)). **Sicuro:** l'ambito protetto dal verificatore è l'architettura supportata dalle evidenze e il protocollo la applica ai propri output. L'analisi delle fonti non è un esercizio accademico; è la traccia delle evidenze.
|
|
120
128
|
|
|
121
129
|
## Sicurezza
|
|
122
130
|
|
|
123
|
-
`study-swarm`
|
|
131
|
+
`study-swarm` include una **CLI leggera, senza dipendenze** (`study-swarm`) insieme alla metodologia. Non effettua **nessuna chiamata di rete o al modello** e non raccoglie **dati di telemetria**; non ci sono segreti o credenziali nel codice sorgente. In fase di esecuzione legge solo il file che si passa a `lint` e scrive un singolo file `<slug>.dispatch.md` nella directory corrente per `new` (rifiutando di sovrascriverlo e operando sempre all'interno della directory di lavoro). La verifica basata sul modello descritta dalla metodologia (Passaggio 4) viene eseguita dagli strumenti correlati, non da questo pacchetto. Vedere [SECURITY.md](SECURITY.md).
|
|
124
132
|
|
|
125
|
-
## Stato
|
|
133
|
+
## Stato
|
|
126
134
|
|
|
127
|
-
Un protocollo funzionante, verificato esternamente dai propri meccanismi: una famiglia di modelli diversa verifica le sue citazioni (vedere la prova sopra).
|
|
135
|
+
Un protocollo funzionante, verificato esternamente dai propri meccanismi: una famiglia di modelli diversa verifica le sue citazioni (vedere la prova sopra). **v1.1** affina il verificatore rispetto alla prima versione, che era silenziosa: base dati scomposta/ternaria, ancoraggio al momento della generazione, una cascata controllata da un oracolo per combinare le "lenti" e astensione calibrata — ciascuno basato sulle evidenze verificate di v1.1. **v1.2** rende un output riproducibile byte per byte: `study-swarm lock` blocca il modello, il prompt e lo schema dello strumento risolti per ogni passaggio più la ricevuta del verificatore, e `lock --verify` fallisce in caso di deriva. Questo repository è il riferimento pubblico; [PROTOCOL.md](PROTOCOL.md) è la forma eseguibile. Parte della famiglia [dogfood-lab](https://github.com/dogfood-lab): metodi ed esempi per lo sviluppo nell'era dell'IA.
|
|
128
136
|
|
|
129
137
|
Con licenza MIT.
|
|
130
138
|
|