role-os 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 2.1.0
+
+### Added
+
+#### Brainstorm Mission (v0.4) — Structured Inquiry with Traceable Disagreement
+
+- **Brainstorm mission** — 7th mission in the library, 9-role chain with two-layer architecture
+- **Layer 1 (truth):** 4 analyst roles emit role-native schemas (ContextMap, UserValueMap, MechanicsMap, PositioningMap), not shared prose. Blindspot enforcement: forbidden phrases, forbidden claim kinds, filtered input partitions per role. Provenance-preserving atoms carry source_role, claim_kind, allowed_challengers. Cross-examination permission matrix (directed graph). Rebut phase: original analysts defend, narrow, or retract under pressure.
+- **Layer 2 (render):** 5 distinct voices — Boundary Memo (taxonomist), Field Notes (ethnographer), System Sketch (whiteboard), Claim Brief (strategist), Cross-Exam Transcript (litigator). Lexical bans prevent voice convergence. Debate transcript generator. Both layers always available.
+- **Trace links:** Every rendered sentence maps to a truth-layer atom. Synthesis cites atoms, never prose.
+- **Golden run proof:** Full artifact chain for MCP server marketplace topic — truth artifacts, dispute graph (4 challenges, 3 narrowed, 1 unresolved), rendered artifacts, trace map (16+ links). Published as `examples/golden-run.md`.
+- **Result formatter:** `formatBrainstormResult()` produces saveable markdown with verdict, directions, dispute, tensions, rendered artifacts (opt-in), and evidence trail. Layer parameter controls truth-only vs both.
+- **Artifact contracts:** 9 brainstorm role contracts (replacing 3 v0.1 scout contracts) with completion rules, required evidence, and consumer mapping.
+- **Pack update:** Brainstorm pack updated from v0.1 scouts to v0.3/v0.4 analysts with correct chain order and required artifacts.
+
+### Changed
+
+- Mission count: 6 → 7
+- Role count: 31 → 50 (brainstorm analysts, contrarian, plus existing)
+- Artifact contract count: 20 → 30
+- Test count: 617 → 905
+
+## 2.0.1
+
+### Added
+
+- 4 version consistency tests (semver, >= 1.0.0, CHANGELOG, help output)
+
 ## 2.0.0
 
 ### Added

package/README.es.md

@@ -2,10 +2,8 @@
   <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
 </p>
 
-# Role OS
-
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/role-os/readme.png" alt="Role OS" width="400">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/role-os/readme.png" alt="Role OS" width="600">
 </p>
 
 <p align="center">
@@ -15,7 +13,7 @@
   <a href="https://mcp-tool-shop-org.github.io/role-os/"><img src="https://img.shields.io/badge/Landing_Page-live-brightgreen" alt="Landing Page"></a>
 </p>
 
-Un sistema operativo multi-Claude que asigna personal, dirige, valida y ejecuta tareas a través de 31 contratos de roles especializados. Crea paquetes de tareas, ensambla el equipo adecuado a partir de la coincidencia de roles, detecta problemas antes de la ejecución, redirige automáticamente la recuperación cuando una tarea se bloquea o se rechaza, y requiere evidencia estructurada en cada decisión.
+Un sistema operativo multi-Claude que asigna personal, dirige, valida y ejecuta tareas a través de 50 contratos de roles especializados. Crea paquetes de tareas, ensambla el equipo adecuado mediante la coincidencia de roles, detecta problemas antes de la ejecución, redirige automáticamente la recuperación cuando una tarea se bloquea o se rechaza, y requiere evidencia estructurada en cada decisión.
 
 ## ¿Qué hace?
 
@@ -47,20 +45,49 @@ roleos start "something completely novel"
 **La jerarquía de respaldo:**
 
 1. **Misión:** cuando la tarea coincide con un flujo de trabajo recurrente probado (corrección de errores, tratamiento, lanzamiento de funciones, documentación, seguridad, investigación). Cadena de roles conocida, flujo de artefactos, ramas de escalamiento y definiciones parciales.
-2. **Paquete:** cuando la tarea pertenece a una familia conocida pero no tiene una estructura de misión completa. 7 paquetes de equipo calibrados con selección automática y mecanismos de protección contra errores.
+2. **Paquete:** cuando la tarea es una familia conocida pero no una misión completa. 7 paquetes de equipo calibrados con selección automática y protecciones contra errores.
 3. **Enrutamiento libre:** cuando la tarea es novedosa, mixta o incierta. Asigna una puntuación a los 31 roles en función del contenido del paquete y ensambla una cadena dinámica.
 
 El sistema nunca fuerza una tarea a través de una abstracción incorrecta. Explica por qué eligió cada nivel y ofrece alternativas.
 
+**Un comando para iniciar la ejecución:**
+
+```bash
+roleos run "fix the crash in save handler"
+# → Created run: run-1234
+# → Entry: MISSION (bugfix)
+# → Started step 0: Repo Researcher → diagnosis-report
+# → Guidance: Required sections: entrypoints, module-map, build-test-commands
+
+roleos next                    # Start the next step
+roleos complete diagnosis.md   # Complete the active step with artifact
+roleos explain                 # Show full run state and guidance
+roleos resume                  # Continue an interrupted run
+roleos report                  # Generate completion report
+roleos friction                # Measure operator touches
+```
+
+**Intervenciones cuando algo sale mal:**
+
+```bash
+roleos retry 0                 # Retry a failed step
+roleos reroute 1 "Frontend Developer" "UI bug"  # Swap a role
+roleos escalate "Test Engineer" "Repo Researcher" "missed edge case" "re-diagnose"
+roleos block 2 "waiting for API spec"
+roleos reopen 0 "found issue in review"
+```
+
+Las ejecuciones se guardan en disco (`.claude/runs/`), por lo que las sesiones interrumpidas se reanudan correctamente. Cada paso incluye orientación para el operador: qué producir, secciones requeridas y condiciones de parada.
+
 **Una vez enrutada:**
 
 1. **Cada rol produce una transferencia:** salida estructurada con elementos de evidencia que reducen la ambigüedad para el siguiente rol.
 2. **El revisor evalúa según el contrato:** acepta, rechaza o bloquea en función de la evidencia estructurada, no de la impresión.
-3. **La recuperación se redirige automáticamente:** las tareas bloqueadas o rechazadas se redirigen al responsable adecuado, junto con la razón, el tipo de recuperación y el artefacto requerido.
+3. **La recuperación se redirige automáticamente:** las tareas bloqueadas o rechazadas se redirigen al solucionador adecuado, junto con la razón, el tipo de recuperación y el artefacto requerido.
 
 ## Estado de implementación en la organización
 
-El estado de implementación en toda la organización (cola, decisiones, registros de auditoría, paquetes de bloqueo por repositorio) se encuentra en un repositorio privado separado: [`role-os-rollout`](https://github.com/mcp-tool-shop-org/role-os-rollout). Este repositorio es el producto; el otro es el estado operativo.
+El estado de implementación en toda la organización (cola, decisiones, registros de auditoría, paquetes de bloqueo por repositorio) se encuentra en un repositorio privado separado: [`role-os-rollout`](https://github.com/mcp-tool-shop-org/role-os-rollout). Este repositorio es el producto; ese repositorio es el estado operativo.
 
 ## Memoria y continuidad
 
@@ -85,11 +112,11 @@ Orden: Verificación de entrega primero, luego tratamiento completo. No hay vers
 | **Design** (2) | Diseñador de Interfaz de Usuario, Guardián de la Marca. |
 | **Marketing** (1) | Redactor para Lanzamiento. |
 | **Treatment** (7) | Investigador de Repositorios, Traductor de Repositorios, Arquitecto de Documentación, Curador de Metadatos, Auditor de Cobertura, Verificador de Despliegue, Ingeniero de Lanzamiento. |
-| **Product** (3) | Sintetizador de comentarios, Priorizador de hoja de ruta, Redactor de especificaciones. |
+| **Product** (3) | Generador de comentarios, Priorizador de hoja de ruta, Redactor de especificaciones. |
 | **Research** (4) | Investigador de Experiencia de Usuario, Analista de la Competencia, Investigador de Tendencias, Sintetizador de Entrevistas con Usuarios. |
 | **Growth** (4) | Estratega de Lanzamiento, Estratega de Contenido, Community Manager, Líder de Soporte. |
 
-Cada rol tiene un contrato completo: misión, cuándo usar, cuándo no usar, entradas esperadas, salidas requeridas, nivel de calidad y desencadenantes de escalamiento. Cada rol es enrutable; `roleos route` puede recomendar cualquiera de ellos en función del contenido del paquete.
+Cada rol tiene un contrato completo: misión, cuándo usar, cuándo no usar, entradas requeridas, salidas requeridas, nivel de calidad y desencadenantes de escalamiento. Cada rol se puede enrutar; `roleos route` puede recomendar cualquiera de ellos en función del contenido del paquete.
 
 ## Cómo empezar
 
@@ -97,19 +124,24 @@ Cada rol tiene un contrato completo: misión, cuándo usar, cuándo no usar, ent
 npx role-os init
 
 # Describe what you need — Role OS picks the right level:
-roleos start "fix the crash in save handler"
+roleos run "fix the crash in save handler"
+# → Creates run, picks bugfix mission, starts first step with guidance
+
+# Step through:
+roleos next                    # Start next step
+roleos complete artifact.md    # Complete with artifact
+roleos explain                 # Show full state
+roleos report                  # Completion report
 
 # Or go manual:
+roleos start "fix the crash"   # Entry decision only (no run)
 roleos packet new feature
 roleos route .claude/packets/my-feature.md
 roleos review .claude/packets/my-feature.md accept
-roleos status
 
 # Explore missions and packs:
 roleos mission list
-roleos mission show bugfix
 roleos packs list
-roleos packs show feature
 ```
 
 ## Cuándo no usar Role OS
@@ -148,6 +180,12 @@ Role OS se ha probado en tres tipos de tareas diferentes en dos repositorios con
 - Mismo paquete de tratamiento, repositorio estructuralmente diferente (espacio de trabajo creativo vs. juego).
 - Paquete de tratamiento portátil: no se requieren modificaciones en el contrato.
 
+**Ejecución de prueba ideal** (tema del mercado de servidores MCP)
+- Cadena de 9 roles, 4 analistas en paralelo, examen cruzado + gráfico de refutación de disputas.
+- Se plantearon 4 desafíos, se redujeron 3 afirmaciones, 1 sin resolver: presión saludable, no un punto muerto.
+- Más de 16 enlaces de trazado desde los artefactos renderizados hasta los átomos de la capa de verdad.
+- Cadena de custodia completa probada: verdad → átomos → disputa → síntesis → expansión → juez → renderizado → trazado.
+
 ## Propiedades fundamentales
 
 Estas son innegociables. Si un cambio debilita alguna de ellas, recházalo.
@@ -166,7 +204,9 @@ role-os/
   src/
     entry.mjs                  ← Unified entry: mission → pack → free routing
     entry-cmd.mjs              ← `roleos start` CLI command
-    mission.mjs                ← 6 named mission types (feature, bugfix, treatment, docs, security, research)
+    run.mjs                    ← Persistent run engine: create → step → pause → resume → report
+    run-cmd.mjs                ← `roleos run/resume/next/explain/complete/fail` + interventions
+    mission.mjs                ← 7 named mission types (feature, bugfix, treatment, docs, security, research, brainstorm)
     mission-run.mjs            ← Mission runner: create → step → complete → report
     mission-cmd.mjs            ← `roleos mission` CLI commands
     route.mjs                  ← 31-role routing + dynamic chain builder
@@ -175,14 +215,17 @@ role-os/
     escalation.mjs             ← Auto-routing for blocked/rejected/split
     evidence.mjs               ← Structured evidence + role-aware requirements
     dispatch.mjs               ← Runtime dispatch manifests for multi-claude
-    artifacts.mjs              ← 20 per-role artifact contracts + 7 pack handoffs
+    artifacts.mjs              ← 30 per-role artifact contracts + 7 pack handoffs
     decompose.mjs              ← Composite task detection + splitting
     composite.mjs              ← Dependency-ordered execution + recovery
     replan.mjs                 ← Mid-run adaptive replanning
     calibration.mjs            ← Outcome recording + weight tuning
     hooks.mjs                  ← 5 lifecycle hooks for runtime enforcement
     session.mjs                ← Session scaffolding + doctor
-  test/                        ← 527 tests across 20 test files
+    brainstorm.mjs             ← Evidence modes, request validation, finding/synthesis/judge schemas
+    brainstorm-roles.mjs       ← Role-native schemas, input partitioning, blindspot enforcement, cross-exam
+    brainstorm-render.mjs      ← Two-layer rendering: lexical bans, render schemas, debate transcript
+  test/                        ← 894 tests across 30 test files
   starter-pack/                ← Drop-in role contracts, policies, schemas, workflows
 ```
 
@@ -192,54 +235,80 @@ El sistema operativo del rol opera **únicamente de forma local**. Copia las pla
 
 ## El sistema operativo
 
-| Capa. | ¿Qué hace? | Estado |
+| Capa | ¿Qué hace? | Estado |
 |-------|-------------|--------|
-| **Routing** | Asigna una puntuación a los 31 roles en función del contenido del paquete, explica las recomendaciones, evalúa la confianza. | ✓ Implementado. |
-| **Chain builder** | Ensambla cadenas ordenadas por fases a partir de roles con puntuación, sesgadas por tipo de paquete, pero no bloqueadas por plantillas. | ✓ Implementado. |
-| **Conflict detection** | Validación de 4 pasos: conflictos graves, secuencia, redundancia, lagunas de cobertura. Sugerencias de corrección. | ✓ Implementado. |
-| **Escalation** | Redirige automáticamente las tareas bloqueadas/rechazadas/divididas al responsable adecuado, junto con la razón y el artefacto requerido. | ✓ Implementado. |
-| **Evidence** | Evidencia estructurada en las decisiones, específica para cada rol. Comprobaciones de suficiencia. 12 tipos de evidencia. | ✓ Implementado. |
-| **Dispatch** | Genera manifiestos de ejecución para multi-claude. Perfiles de herramientas por rol, indicaciones del sistema, presupuestos. | ✓ Implementado. |
-| **Trials** | Lista completa probada: 30/30 tareas de oro + 5/5 pruebas negativas. 7 pruebas de paquete completadas. | ✓ Completo. |
-| **Team Packs** | 7 paquetes calibrados con selección automática, mecanismos de protección contra errores y enrutamiento libre como respaldo. | ✓ Implementado. |
-| **Outcome calibration** | Registra los resultados de la ejecución, ajusta los pesos de los paquetes/roles en función de los resultados y ajusta los umbrales de confianza. | ✓ Implementado. |
-| **Mixed-task decomposition** | Detecta tareas compuestas, las divide en paquetes secundarios, asigna paquetes y conserva las dependencias. | ✓ Implementado. |
-| **Composite execution** | Ejecuta los paquetes secundarios en orden de dependencia, con transferencia de artefactos, recuperación de ramas y síntesis. | ✓ Implementado. |
-| **Adaptive replanning** | Los cambios de alcance, los hallazgos o los nuevos requisitos durante la ejecución actualizan el plan sin necesidad de reiniciar. | ✓ Implementado. |
-| **Session spine** | `roleos init claude` crea CLAUDE.md, /roleos-route, /roleos-review, /roleos-status. `roleos doctor` verifica la configuración. Las tarjetas de enrutamiento demuestran la participación. | ✓ Implementado. |
-| **Hook spine** | 5 ganchos de ciclo de vida (SessionStart, PromptSubmit, PreToolUse, SubagentStart, Stop). Aplicación de políticas: recordatorios en las tarjetas de ruta, control de acceso a herramientas, inyección de roles de subagente, auditoría de finalización. | ✓ Implementado. |
-| **Artifact spine** | 20 contratos de artefactos por rol. 7 contratos de transferencia de paquetes. Validación estructural. Comprobaciones de integridad de la cadena. Los roles posteriores nunca adivinan lo que recibieron. | ✓ Implementado. |
-| **Mission library** | 6 misiones con nombre (desarrollo de características, corrección de errores, implementación, lanzamiento de documentación, endurecimiento de seguridad, lanzamiento de investigación). Cada una define el paquete, la cadena de roles, el flujo de artefactos, las ramas de escalada y una definición honesta y parcial. Las 6 misiones se probaron y se optimizaron. | ✓ Implementado. |
-| **Mission runner** | Crear ejecuciones, avanzar paso a paso con el estado rastreado, completar/fallar con informes precisos. Propagación de pasos bloqueados, advertencias de escalada fuera de la cadena, reapertura del último paso. | ✓ Implementado. |
-| **Unified entry** | `roleos start` decide automáticamente entre una misión, un paquete o una ruta libre. Escalera de respaldo con puntuaciones de confianza, alternativas y detección compuesta. | ✓ Implementado. |
-
-## 6 misiones
+| **Routing** | Asigna una puntuación a los 31 roles en función del contenido del paquete, explica las recomendaciones, evalúa la confianza. | ✓ Implementado |
+| **Chain builder** | Ensambla cadenas ordenadas por fase a partir de roles con puntuación, sesgadas por tipo de paquete, no bloqueadas por plantillas. | ✓ Implementado |
+| **Conflict detection** | Validación de 4 pasos: conflictos duros, secuencia, redundancia, lagunas de cobertura. Sugerencias de reparación. | ✓ Implementado |
+| **Escalation** | Redirige automáticamente las tareas bloqueadas/rechazadas/divididas al solucionador adecuado, junto con la razón y el artefacto requerido. | ✓ Implementado |
+| **Evidence** | Evidencia estructurada en las decisiones, específica para cada rol. Comprobaciones de suficiencia. 12 tipos de evidencia. | ✓ Implementado |
+| **Dispatch** | Genera manifiestos de ejecución para multi-claude. Perfiles de herramientas por rol, indicaciones del sistema, presupuestos. | ✓ Implementado |
+| **Trials** | Lista completa probada: 30/30 tareas de oro + 5/5 pruebas negativas. 7 pruebas de paquete completadas. | ✓ Completo |
+| **Team Packs** | 7 paquetes calibrados con selección automática, protección contra errores y recuperación flexible. | ✓ Implementado |
+| **Outcome calibration** | Registra los resultados de las ejecuciones, ajusta los pesos de los paquetes/roles según los resultados y modifica los umbrales de confianza. | ✓ Implementado |
+| **Mixed-task decomposition** | Detecta tareas compuestas, las divide en paquetes secundarios, asigna paquetes, preserva las dependencias. | ✓ Implementado |
+| **Composite execution** | Ejecuta los paquetes secundarios en orden de dependencia, transfiriendo artefactos, recuperando ramas y sintetizando. | ✓ Implementado |
+| **Adaptive replanning** | Los cambios en el alcance, los hallazgos o los nuevos requisitos durante la ejecución actualizan el plan sin necesidad de reiniciarlo. | ✓ Implementado |
+| **Session spine** | `roleos init claude` crea los archivos CLAUDE.md, /roleos-route, /roleos-review y /roleos-status. `roleos doctor` verifica la configuración. Las tarjetas de ruta demuestran la participación. | ✓ Implementado |
+| **Hook spine** | 5 ganchos de ciclo de vida (SessionStart, PromptSubmit, PreToolUse, SubagentStart, Stop). Aplicación de políticas: recordatorios en las tarjetas de ruta, control de acceso a herramientas, inyección de roles de subagente, auditoría de finalización. | ✓ Implementado |
+| **Artifact spine** | 30 contratos de artefactos por rol. 7 contratos de transferencia de paquetes. Validación estructural. Comprobaciones de integridad de la cadena. Los roles posteriores nunca adivinan lo que recibieron. | ✓ Implementado |
+| **Mission library** | 7 misiones con nombre (feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch, brainstorm). Cada una define el paquete, la cadena de roles, el flujo de artefactos, las ramas de escalada y una definición parcial y honesta. Las 7 están probadas. | ✓ Implementado |
+| **Mission runner** | Crea ejecuciones, avanza paso a paso con seguimiento del estado, completa o falla con informes precisos. Propagación de pasos bloqueados, advertencias de escalada fuera de la cadena, reapertura del último paso. | ✓ Implementado |
+| **Unified entry** | `roleos start` decide automáticamente entre una misión, un paquete o una ruta flexible. Escalera de recuperación con puntuaciones de confianza, alternativas y detección de tareas compuestas. | ✓ Implementado |
+| **Persistent runs** | `roleos run` crea ejecuciones respaldadas en disco. Comandos: `resume` (reanudar), `next` (siguiente), `explain` (explicar), `complete` (completar), `fail` (fallar). Intervenciones: `reroute` (redirigir), `escalate` (escalar), `retry` (reintentar), `block` (bloquear), `reopen` (reabrir). Guía específica para cada paso. Medición de la fricción. | ✓ Implementado |
+| **Brainstorm** | Arquitectura de dos capas: verdad (esquemas nativos del rol, átomos de procedencia, gráfico de disputa cruzada) + renderizado (5 voces distintas, prohibiciones léxicas, transcripción del debate). Los enlaces de trazado demuestran que cada afirmación renderizada se corresponde con un átomo de verdad. Ejecución de referencia: 894 pruebas. | ✓ Implementado |
+
+## 7 misiones
 
 | Misión | Paquete | Roles | Cuándo usar |
 |---------|------|-------|-------------|
-| `feature-ship` | característica | 5 | Entrega completa de una característica: alcance → especificación → implementación → prueba → revisión |
-| `bugfix` | corrección de errores | 4 | Diagnosticar la causa raíz, corregir, probar, verificar |
-| `treatment` | implementación | 4 | Verificación + pulido + documentación + verificación CI + revisión |
-| `docs-release` | documentación | 2 | Escribir/actualizar documentación, notas de la versión |
+| `feature-ship` | Característica | 5 | Entrega completa de la característica: alcance → especificación → implementación → prueba → revisión |
+| `bugfix` | Corrección de errores | 4 | Diagnosticar la causa raíz, corregir, probar, verificar |
+| `treatment` | Tratamiento | 4 | Verificación + pulido + documentación + verificación CI + revisión |
+| `docs-release` | Documentación | 2 | Escribir/actualizar documentación, notas de la versión |
 | `security-hardening` | Seguridad | 4 | Modelo de amenazas, auditoría, corregir vulnerabilidades, volver a auditar, verificar |
-| `research-launch` | investigación | 4 | Formular la pregunta, investigar, documentar los hallazgos, decidir |
+| `research-launch` | Investigación | 4 | Formular la pregunta, investigar, documentar los hallazgos, decidir |
+| `brainstorm` | Lluvia de ideas | 9 | Investigación estructurada con múltiples perspectivas, con desacuerdos trazables y resultados. |
+
+Cada misión incluye definiciones parciales y honestas: cuando el trabajo se detiene, el sistema documenta lo que se completó y lo que queda, en lugar de simular una finalización.
+
+### Misión de lluvia de ideas
+
+No es una "lluvia de ideas de IA". La misión de lluvia de ideas es **un conjunto de roles especializados bajo un marco legal, con desacuerdos trazables y resultados con valor de juicio.**
+
+```bash
+roleos run "explore product directions for a developer tool discovery platform"
+# → MISSION: Brainstorm (Structured Inquiry)
+#   Chain: 4 Analysts (parallel) → Normalize → Cross-Examine → Rebut → Synthesize → Expand → Judge
+```
+
+**¿Qué la diferencia?**
+
+- **Capa 1 (verdad):** Cuatro analistas emiten esquemas nativos del rol (ContextMap, UserValueMap, MechanicsMap, PositioningMap) — no prosa compartida. Cada rol tiene restricciones para evitar puntos ciegos: frases prohibidas, tipos de afirmaciones prohibidas, particiones de entrada filtradas. Los átomos llevan información de procedencia. Un gráfico de interrogatorio dirigido genera desafíos específicos. Los analistas originales defienden, refinan o retiran sus afirmaciones bajo presión.
+
+- **Capa 2 (renderizado):** Cinco voces humanas distintas (Memorándum de Límites, Notas de Campo, Esquema del Sistema, Resumen de Reclamación, Transcripción del Interrogatorio) con restricciones léxicas que evitan la convergencia de las voces. La síntesis consume información verídica, pero nunca produce prosa. Ambas capas están siempre disponibles.
+
+- **Cadena de custodia:** Cada oración generada se remonta a un átomo de la capa de verdad. Las instrucciones de síntesis citan átomos. Los interrogatorios se dirigen a identificadores de reclamaciones reales. El grafo de disputas es el producto, no la prosa.
 
-Cada misión incluye definiciones honestas y parciales: cuando el trabajo se detiene, el sistema documenta lo que se completó y lo que queda, en lugar de simular una finalización.
+**Comprobado:** Versión 0.4, ejecución de referencia — 894 pruebas, cadena de custodia completamente verificada. Consulte [`examples/golden-run.md`](examples/golden-run.md) para ver la cadena de artefactos completa.
 
 ## Estado
 
-- v0.1–v0.4: Fundación: pruebas, adopción, paquete de implementación, paquete de inicio
-- v1.0.0: 32 roles, CLI completa, implementación probada, portabilidad multi-repositorio
-- v1.0.2: Bloqueo del sistema de roles (correcciones de inicialización de la verdad, init --force)
-- v1.1.0: 31 roles, columna vertebral de enrutamiento completa, detección de conflictos, escalada, evidencia, despacho, 7 paquetes de equipo probados. 35 ejecuciones de prueba. 212 pruebas.
-- v1.2.0: Paquetes calibrados promovidos a la entrada predeterminada. Selección automática, detección de incompatibilidades, sugerencia de alternativas, respaldo de enrutamiento libre. 246 pruebas.
+- v0.1–v0.4: Fundación — pruebas, adopción, paquete de tratamiento, paquete de inicio.
+- v1.0.0: 32 roles, interfaz de línea de comandos completa, tratamiento comprobado, portabilidad entre múltiples repositorios.
+- v1.0.2: Bloqueo del sistema de roles (correcciones de inicialización de la verdad, init --force).
+- v1.1.0: 31 roles, columna vertebral de enrutamiento completa, detección de conflictos, escalamiento, evidencia, despacho, 7 paquetes de equipo comprobados. 35 pruebas de ejecución. 212 pruebas.
+- v1.2.0: Paquetes calibrados promovidos a la entrada predeterminada. Selección automática, detección de incompatibilidades, sugerencia alternativa, recuperación de enrutamiento libre. 246 pruebas.
 - v1.3.0: Calibración de resultados, descomposición de tareas mixtas, ejecución compuesta, replanificación adaptativa. 317 pruebas.
-- v1.4.0: Columna vertebral de la sesión: `roleos init claude`, `roleos doctor`, tarjetas de ruta, comandos /roleos-route + /roleos-review + /roleos-status. 335 pruebas.
-- v1.5.0: Columna vertebral de los ganchos: 5 ganchos de ciclo de vida para la aplicación en tiempo de ejecución. 358 pruebas.
-- v1.6.0: Columna vertebral de los artefactos: 20 contratos de artefactos por rol, 7 contratos de transferencia de paquetes, validación estructural. 385 pruebas.
-- v1.7.0: Prueba de finalización: tareas reales que se ejecutan a través de toda la pila. CLI `roleos artifacts`. Escalada honesta para correcciones estructurales. 398 pruebas.
-- v1.8.0: Biblioteca de misiones (Fase S): 6 misiones con nombre, motor de ejecución, informes de finalización. Optimizadas a partir de 6 ejecuciones de prueba reales. 481 pruebas.
-- **v1.9.0**: Ruta de entrada unificada (Fase T): `roleos start` decide automáticamente entre una misión, un paquete o una ruta libre. Escalera de respaldo, detección compuesta, pruebas de comparación de la ruta de entrada. 527 pruebas.
+- v1.4.0: Columna vertebral de la sesión — `roleos init claude`, `roleos doctor`, tarjetas de ruta, comandos /roleos-route + /roleos-review + /roleos-status. 335 pruebas.
+- v1.5.0: Columna vertebral de los ganchos — 5 ganchos de ciclo de vida para la aplicación en tiempo de ejecución. 358 pruebas.
+- v1.6.0: Columna vertebral de los artefactos — 20 contratos de artefactos por rol, 7 contratos de entrega de paquetes, validación estructural. 385 pruebas.
+- v1.7.0: Prueba de finalización — tareas reales ejecutadas a través de toda la pila. Interfaz de línea de comandos `roleos artifacts`. Escalamiento honesto para correcciones estructurales. 398 pruebas.
+- v1.8.0: Biblioteca de misiones (Fase S) — 6 misiones con nombre, motor de ejecución, informes de finalización. Endurecido a partir de 6 ejecuciones de prueba reales. 481 pruebas.
+- v1.9.0: Ruta de entrada unificada (Fase T) — `roleos start` decide automáticamente entre misión, paquete o enrutamiento libre. Escalera de recuperación, detección compuesta, pruebas de comparación de rutas de entrada. 527 pruebas.
+- **v2.0.0**: Optimización de la experiencia del usuario (Fase U) — `roleos run` crea ejecuciones persistentes respaldadas por disco. Reanudar, siguiente, explicar, completar, fallar. Intervenciones: redirigir, escalar, reintentar, bloquear, reabrir. Guía específica para cada paso. Medición de la fricción. 6 pruebas de fricción. 613 pruebas.
+- **v2.0.1**: Auditoría del manual, documentación para principiantes, correcciones del número de pruebas. 617 pruebas.
+- **v2.1.0**: Misión de lluvia de ideas (v0.4) — roles especializados en el ámbito legal, desacuerdo trazable, salida con valor de veredicto. Arquitectura de dos capas (verdad + renderizado), matriz de permisos de interrogatorio, grafo de disputas, prueba de ejecución de referencia. 7 misiones, 50 roles, 8 paquetes. 894 pruebas.
 
 ## Licencia
 

package/README.fr.md

@@ -2,10 +2,8 @@
   <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.md">English</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
 </p>
 
-# Role OS
-
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/role-os/readme.png" alt="Role OS" width="400">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/role-os/readme.png" alt="Role OS" width="600">
 </p>
 
 <p align="center">
@@ -52,6 +50,35 @@ roleos start "something completely novel"
 
 Le système ne force jamais une tâche à travers le mauvais niveau d'abstraction. Il explique pourquoi il a choisi chaque niveau et propose des alternatives.
 
+**Une seule commande pour activer l'exécution :**
+
+```bash
+roleos run "fix the crash in save handler"
+# → Created run: run-1234
+# → Entry: MISSION (bugfix)
+# → Started step 0: Repo Researcher → diagnosis-report
+# → Guidance: Required sections: entrypoints, module-map, build-test-commands
+
+roleos next                    # Start the next step
+roleos complete diagnosis.md   # Complete the active step with artifact
+roleos explain                 # Show full run state and guidance
+roleos resume                  # Continue an interrupted run
+roleos report                  # Generate completion report
+roleos friction                # Measure operator touches
+```
+
+**Interventions en cas de problème :**
+
+```bash
+roleos retry 0                 # Retry a failed step
+roleos reroute 1 "Frontend Developer" "UI bug"  # Swap a role
+roleos escalate "Test Engineer" "Repo Researcher" "missed edge case" "re-diagnose"
+roleos block 2 "waiting for API spec"
+roleos reopen 0 "found issue in review"
+```
+
+Les exécutions sont enregistrées sur le disque (dans le dossier `.claude/runs/`), ce qui permet de reprendre les sessions interrompues sans problème. Chaque étape comprend des instructions pour l'utilisateur : ce qu'il faut produire, les sections requises et les conditions d'arrêt.
+
 **Une fois routée :**
 
 1. **Chaque rôle produit une transmission** — sortie structurée avec des éléments de preuve qui réduisent l'ambiguïté pour le rôle suivant.
@@ -97,19 +124,24 @@ Chaque rôle a un contrat complet : mission, conditions d'utilisation, condition
 npx role-os init
 
 # Describe what you need — Role OS picks the right level:
-roleos start "fix the crash in save handler"
+roleos run "fix the crash in save handler"
+# → Creates run, picks bugfix mission, starts first step with guidance
+
+# Step through:
+roleos next                    # Start next step
+roleos complete artifact.md    # Complete with artifact
+roleos explain                 # Show full state
+roleos report                  # Completion report
 
 # Or go manual:
+roleos start "fix the crash"   # Entry decision only (no run)
 roleos packet new feature
 roleos route .claude/packets/my-feature.md
 roleos review .claude/packets/my-feature.md accept
-roleos status
 
 # Explore missions and packs:
 roleos mission list
-roleos mission show bugfix
 roleos packs list
-roleos packs show feature
 ```
 
 ## Quand ne pas utiliser Role OS
@@ -148,6 +180,12 @@ Role OS a été testé sur trois types de tâches différents dans deux référe
 - Même ensemble de traitement, dépôt structurellement différent (espace de travail créatif vs jeu)
 - Ensemble de traitement portable — aucune modification de contrat n'est nécessaire
 
+**Brainstorming pour une exécution optimale** (sujet du marché de serveurs MCP)
+- Chaîne de 9 rôles, 4 analystes en parallèle, examen croisé + réfutation, graphe de désaccord.
+- 4 défis lancés, 3 affirmations affinées, 1 non résolue – pression saine, pas de blocage.
+- Plus de 16 liens de traçabilité des artefacts générés vers les éléments de base de la couche de vérité.
+- Chaîne de traçabilité complète prouvée : vérité → éléments de base → désaccord → synthèse → expansion → jugement → rendu → traçabilité.
+
 ## Propriétés essentielles
 
 Ce sont des éléments non négociables. Si une modification affaiblit l'un de ces éléments, elle doit être rejetée.
@@ -166,7 +204,9 @@ role-os/
   src/
     entry.mjs                  ← Unified entry: mission → pack → free routing
     entry-cmd.mjs              ← `roleos start` CLI command
-    mission.mjs                ← 6 named mission types (feature, bugfix, treatment, docs, security, research)
+    run.mjs                    ← Persistent run engine: create → step → pause → resume → report
+    run-cmd.mjs                ← `roleos run/resume/next/explain/complete/fail` + interventions
+    mission.mjs                ← 7 named mission types (feature, bugfix, treatment, docs, security, research, brainstorm)
     mission-run.mjs            ← Mission runner: create → step → complete → report
     mission-cmd.mjs            ← `roleos mission` CLI commands
     route.mjs                  ← 31-role routing + dynamic chain builder
@@ -175,14 +215,17 @@ role-os/
     escalation.mjs             ← Auto-routing for blocked/rejected/split
     evidence.mjs               ← Structured evidence + role-aware requirements
     dispatch.mjs               ← Runtime dispatch manifests for multi-claude
-    artifacts.mjs              ← 20 per-role artifact contracts + 7 pack handoffs
+    artifacts.mjs              ← 30 per-role artifact contracts + 7 pack handoffs
     decompose.mjs              ← Composite task detection + splitting
     composite.mjs              ← Dependency-ordered execution + recovery
     replan.mjs                 ← Mid-run adaptive replanning
     calibration.mjs            ← Outcome recording + weight tuning
     hooks.mjs                  ← 5 lifecycle hooks for runtime enforcement
     session.mjs                ← Session scaffolding + doctor
-  test/                        ← 527 tests across 20 test files
+    brainstorm.mjs             ← Evidence modes, request validation, finding/synthesis/judge schemas
+    brainstorm-roles.mjs       ← Role-native schemas, input partitioning, blindspot enforcement, cross-exam
+    brainstorm-render.mjs      ← Two-layer rendering: lexical bans, render schemas, debate transcript
+  test/                        ← 894 tests across 30 test files
   starter-pack/                ← Drop-in role contracts, policies, schemas, workflows
 ```
 
@@ -212,6 +255,8 @@ Le rôle OS fonctionne **uniquement localement**. Il copie les modèles Markdown
 | **Mission library** | 6 missions nommées (développement de fonctionnalité, correction de bug, amélioration, publication de documentation, renforcement de la sécurité, lancement de recherche). Chaque mission définit l'ensemble, la chaîne de rôles, le flux d'artefacts, les branches de relance et une définition partielle et honnête. Les 6 missions ont été testées et optimisées. | ✓ Déployé |
 | **Mission runner** | Création d'exécutions, suivi de l'état, finalisation ou échec avec un rapport précis. Propagation des étapes bloquées, avertissements de relance en dehors de la chaîne, réouverture de la dernière étape. | ✓ Déployé |
 | **Unified entry** | `roleos start` détermine automatiquement si l'exécution est une mission, un ensemble ou un routage libre. Mécanisme de repli avec scores de confiance, alternatives et détection des tâches complexes. | ✓ Déployé |
+| **Persistent runs** | `roleos run` crée des exécutions enregistrées sur le disque. Commandes : `resume` (reprendre), `next` (suivant), `explain` (expliquer), `complete` (terminer), `fail` (échec). Interventions : `reroute` (rediriger), `escalate` (escalader), `retry` (réessayer), `block` (bloquer), `reopen` (réouvrir). Instructions spécifiques à chaque étape. Mesure du niveau de friction. | ✓ Déployé |
+| **Brainstorm** | Architecture à deux niveaux : vérité (schémas natifs des rôles, éléments de base de provenance, graphe de désaccord) + rendu (5 voix distinctes, interdictions lexicales, transcription du débat). Les liens de traçabilité prouvent que chaque affirmation rendue correspond à un élément de base de la couche de vérité. Exécution optimale : 894 tests. | ✓ Déployé |
 
 ## 6 missions
 
@@ -223,23 +268,47 @@ Le rôle OS fonctionne **uniquement localement**. Il copie les modèles Markdown
 | `docs-release` | Documentation | 2 | Rédaction/mise à jour de la documentation, notes de publication |
 | `security-hardening` | Sécurité | 4 | Analyse des menaces, audit, correction des vulnérabilités, nouvel audit, vérification |
 | `research-launch` | Recherche | 4 | Définition de la question, recherche, documentation des résultats, prise de décision |
+| `brainstorm` | brainstorming | 9 | Enquête structurée avec plusieurs perspectives, désaccord traçable et verdict. |
 
 Chaque mission inclut des définitions partielles et honnêtes : lorsque le travail est bloqué, le système documente ce qui a été réalisé et ce qui reste, au lieu de prétendre que le travail est terminé.
 
+### Mission de brainstorming
+
+Ce n'est pas un "brainstorming par IA". La mission de brainstorming est **l'attribution de rôles spécialisés dans le domaine juridique, avec un désaccord traçable et une production de résultats justifiés.**
+
+```bash
+roleos run "explore product directions for a developer tool discovery platform"
+# → MISSION: Brainstorm (Structured Inquiry)
+#   Chain: 4 Analysts (parallel) → Normalize → Cross-Examine → Rebut → Synthesize → Expand → Judge
+```
+
+**Ce qui le différencie :**
+
+- **Couche 1 (vérité) :** Quatre analystes produisent des schémas spécifiques à chaque rôle (ContextMap, UserValueMap, MechanicsMap, PositioningMap) – pas de prose partagée. Chaque rôle est soumis à des contraintes pour éviter les biais : phrases interdites, types d'affirmations interdits, partitions d'entrée filtrées. Les éléments de base contiennent des informations de provenance. Un graphe d'examen croisé dirigé génère des défis ciblés. Les analystes originaux défendent, affinent ou retirent leurs affirmations sous pression.
+
+- **Couche 2 (rendu) :** Cinq voix humaines distinctes (Boundary Memo, Field Notes, System Sketch, Claim Brief, Cross-Exam Transcript) avec des interdictions lexicales pour éviter la convergence des voix. La synthèse utilise la couche de vérité, et non la prose rendue. Les deux couches sont toujours disponibles.
+
+- **Chaîne de traçabilité :** Chaque phrase rendue est traçable jusqu'à un élément de base de la couche de vérité. Les instructions de synthèse citent les éléments de base. Les cibles de l'examen croisé sont des identifiants d'affirmations réels. Le graphe de désaccord est le résultat, et non la prose.
+
+**Prouvé :** Exécution optimale v0.4 – 894 tests, chaîne de traçabilité complète vérifiée. Consultez [`examples/golden-run.md`](examples/golden-run.md) pour la chaîne complète des artefacts.
+
 ## Statut
 
 - v0.1–v0.4 : Bases – essais, adoption (du produit), ensemble de traitement, ensemble de démarrage.
-- v1.0.0 : 32 rôles, interface en ligne de commande complète, traitement éprouvé, portabilité multi-dépôts.
-- v1.0.2 : Blocage des rôles au niveau du système d'exploitation (corrections de la configuration initiale, `init --force`).
-- v1.1.0 : 31 rôles, architecture de routage complète, détection des conflits, escalade, preuves, répartition, 7 ensembles d'outils éprouvés. 35 essais d'exécution. 212 tests.
-- v1.2.0 : Les ensembles calibrés sont promus au mode par défaut. Sélection automatique, détection des incompatibilités, suggestion d'alternatives, basculement vers un routage libre. 246 tests.
-- v1.3.0 : Calibrage des résultats, décomposition des tâches complexes, exécution composite, replanification adaptative. 317 tests.
-- v1.4.0 : Architecture de session – `roleos init claude`, `roleos doctor`, cartes de routage, commandes `/roleos-route`, `/roleos-review` et `/roleos-status`. 335 tests.
-- v1.5.0 : Architecture de connexion – 5 points d'accroche pour l'application des règles au moment de l'exécution. 358 tests.
-- v1.6.0 : Architecture des artefacts – 20 contrats d'artefacts par rôle, 7 contrats de transfert d'ensembles, validation structurelle. 385 tests.
-- v1.7.0 : Preuve de complétion – tâches réelles exécutées sur l'ensemble de la pile. Interface en ligne de commande `roleos artifacts`. Escalade transparente pour les corrections structurelles. 398 tests.
-- v1.8.0 : Bibliothèque de missions (Phase S) – 6 missions nommées, moteur d'exécution, rapports de complétion. Durcissement basé sur 6 essais réels. 481 tests.
-- **v1.9.0** : Chemin d'accès unifié (Phase T) – `roleos start` détermine automatiquement si l'on utilise une mission, un ensemble d'outils ou un routage libre. Système de basculement, détection composite, essais de comparaison des chemins d'accès. 527 tests.
+- v1.0.0 : 32 rôles, CLI complète, traitement éprouvé, portabilité multi-dépôts.
+- v1.0.2 : Blocage du système d'exploitation par rôle (corrections de la "vérité" de l'initialisation, `init --force`).
+- v1.1.0 : 31 rôles, infrastructure de routage complète, détection de conflits, escalade, preuves, répartition, 7 ensembles d'équipe éprouvés. 35 essais d'exécution. 212 tests.
+- v1.2.0 : Ensembles calibrés promus au point d'entrée par défaut. Sélection automatique, détection de discordances, suggestion alternative, repli sur le routage libre. 246 tests.
+- v1.3.0 : Calibrage des résultats, décomposition de tâches complexes, exécution composite, replanification adaptative. 317 tests.
+- v1.4.0 : Infrastructure de session – `roleos init claude`, `roleos doctor`, cartes de routage, commandes `/roleos-route`, `/roleos-review` et `/roleos-status`. 335 tests.
+- v1.5.0 : Infrastructure de "hooks" – 5 "hooks" de cycle de vie pour l'application en temps réel. 358 tests.
+- v1.6.0 : Infrastructure des artefacts – 20 contrats d'artefacts par rôle, 7 contrats de transmission d'ensembles, validation structurelle. 385 tests.
+- v1.7.0 : Preuve de complétion – tâches réelles exécutées sur toute la pile. CLI `roleos artifacts`. Escalade honnête pour les corrections structurelles. 398 tests.
+- v1.8.0 : Bibliothèque de missions (Phase S) – 6 missions nommées, moteur d'exécution, rapports de complétion. Durcissement basé sur 6 exécutions réelles. 481 tests.
+- v1.9.0 : Chemin d'entrée unifié (Phase T) – `roleos start` décide automatiquement entre mission, ensemble et routage libre. Système de repli, détection composite, essais de comparaison du chemin d'entrée. 527 tests.
+- **v2.0.0** : Optimisation de l'expérience utilisateur (Phase U) – `roleos run` crée des exécutions persistantes avec sauvegarde sur disque. Reprise, suivant, explication, complétion, échec. Interventions : réacheminement, escalade, nouvelle tentative, blocage, réouverture. Assistance spécifique à chaque étape. Mesure du niveau de difficulté. 6 essais de difficulté. 613 tests.
+- **v2.0.1** : Audit du manuel, documentation pour débutants, corrections du nombre de tests. 617 tests.
+- **v2.1.0** : Mission de brainstorming (v0.4) – rôles spécialisés dans le domaine juridique, désaccord traçable, résultat avec verdict. Architecture à deux niveaux (vérité + rendu), matrice de permissions de contre-interrogatoire, graphe de litiges, preuve d'exécution optimale. 7 missions, 50 rôles, 8 ensembles. 894 tests.
 
 ## Licence