role-os 2.0.0 → 2.1.0

package/README.ja.md

@@ -2,10 +2,8 @@
   <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</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">
@@ -52,6 +50,35 @@ roleos start "something completely novel"
 
 このシステムは、常に適切な抽象レベルでタスクを実行させます。各レベルを選択した理由を説明し、代替案も提示します。
 
+**実行を開始するコマンド:**
+
+```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
+```
+
+**問題発生時の対応:**
+
+```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"
+```
+
+実行結果はディスクに保存されます（`.claude/runs/`）。そのため、中断されたセッションも正常に再開できます。各ステップには、オペレーター向けのガイダンスが含まれており、生成すべき内容、必要なセクション、および停止条件が示されています。
+
 **ルーティング後:**
 
 1. **各役割は成果物を生成:** 構造化された出力で、次の役割が理解しやすいように、証拠となる情報が含まれています。
@@ -97,19 +124,24 @@ Role OSは、Claudeプロジェクトのメモリと連携します。置き換
 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
 ```
 
 ## Role OSを使用しない場合
@@ -148,6 +180,12 @@ Role OSは、構造が異なる2つのリポジトリで、3つの異なるテ
 - 同じトリートメントパッケージを使用。構造は異なり、リポジトリの内容も異なる（クリエイティブワークスペース vs ゲーム）。
 - トリートメントパッケージは移植可能。契約の変更は不要。
 
+**理想的な実行例（MCPサーバーマーケットプレイスのトピック）**
+- 9つの役割を持つ連携、並行して4人の分析者。相互に質問し、反論するグラフ。
+- 4つの課題が提示され、3つの主張が絞り込まれ、1つが未解決。健全なプレッシャーがかかっていますが、行き詰まりはありません。
+- 生成された成果物から、真実の要素への16以上の追跡リンク。
+- 完全なトレーサビリティが証明されています：真実 → 要素 → 反論 → 統合 → 拡張 → 評価 → 生成 → 追跡
+
 ## 主要な特性
 
 これらは変更できません。変更によってこれらのいずれかが弱体化する場合は、却下してください。
@@ -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 @@ Role OSは、**ローカルでのみ**動作します。Markdownテンプレー
 | **Mission library** | 6つの名前付きミッション（新機能追加、バグ修正、改善、ドキュメントのリリース、セキュリティ強化、研究開発）。それぞれが、パッケージ、ロールチェーン、成果物の流れ、エスカレーションのブランチ、正直で部分的な定義を宣言します。6つすべてが試行錯誤され、強化されています。 | ✓ 完了 |
 | **Mission runner** | 実行を開始し、追跡された状態とともにステップを進め、正直なレポートで完了または失敗。ブロックされたステップの伝播、チェーンからの逸脱に関する警告、最後のステップの再開。 | ✓ 完了 |
 | **Unified entry** | `roleos start`は、ミッション、パッケージ、または自由ルーティングを自動的に決定します。信頼度スコア、代替案、および複合検出を備えたフォールバックシステム。 | ✓ 完了 |
+| **Persistent runs** | `roleos run` コマンドは、ディスクに保存された実行結果を作成します。`resume`（再開）、`next`（次へ）、`explain`（説明）、`complete`（完了）、`fail`（失敗）。対応：`reroute`（リダイレクト）、`escalate`（エスカレーション）、`retry`（再試行）、`block`（ブロック）、`reopen`（再開）。各ステップにローカルなガイダンスがあります。摩擦の測定。 | ✓ 完了 |
+| **Brainstorm** | 2層のアーキテクチャ：真実層（役割固有のスキーマ、トレーサビリティを持つ要素、相互質問と反論のグラフ）+ 生成層（5つの異なる声、禁止語、議論の記録）。追跡リンクは、生成されたすべての主張が、真実の要素に対応していることを証明します。理想的な実行例：894件のテスト。 | ✓ 完了 |
 
 ## 6つのミッション
 
@@ -223,23 +268,47 @@ Role OSは、**ローカルでのみ**動作します。Markdownテンプレー
 | `docs-release` | ドキュメント | 2 | ドキュメントの作成/更新、リリースノート |
 | `security-hardening` | セキュリティ | 4 | 脅威モデルの作成、監査、脆弱性の修正、再監査、検証 |
 | `research-launch` | 研究 | 4 | 問題の定義、調査、結果の文書化、決定 |
+| `brainstorm` | ブレインストーミング | 9 | 追跡可能な意見の相違と結論を持つ、構造化された多角的な調査 |
 
 各ミッションには、正直で部分的な定義が含まれています。作業が停滞した場合、システムは完了した内容と残りの内容を記録し、進捗を偽装することはありません。
 
+### ブレインストーミングミッション
+
+これは「AIによるブレインストーミング」ではありません。ブレインストーミングミッションは、**法に基づいて定義された役割であり、追跡可能な意見の相違と、結論を導き出すための出力を持つ**ものです。
+
+```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
+```
+
+**何が違うのか:**
+
+- **層1（真実）：** 4人の分析者が、役割固有のスキーマ（コンテキストマップ、ユーザーバリューマップ、メカニズムマップ、ポジショニングマップ）を生成します。これは、共有された文章ではありません。各役割には、盲点防止機能が組み込まれており、禁止語、禁止される主張の種類、およびフィルタリングされた入力セクションがあります。要素には、トレーサビリティ情報が含まれています。方向性のある相互質問グラフにより、ターゲットを絞った課題が生成されます。元の分析者は、プレッシャーの下で、主張を擁護したり、絞り込んだり、撤回したりします。
+
+- **層2（生成）：** 5つの異なる人間の声（境界メモ、フィールドノート、システムスケッチ、主張概要、相互質問記録）があり、禁止語により、声の統一を防ぎます。統合は、真実の要素を使用しますが、生成された文章は使用しません。両方の層は常に利用可能です。
+
+- **トレーサビリティ：** 生成されたすべての文は、真実の要素にトレースバックできます。統合の指示には、要素が引用されています。相互質問は、実際の主張IDを対象としています。意見の相違グラフは、文章ではなく、その結果です。
+
+**検証済み：** v0.4の理想的な実行例：894件のテスト、完全なトレーサビリティが検証済み。完全な成果物のチェーンについては、[`examples/golden-run.md`](examples/golden-run.md) を参照してください。
+
 ## ステータス
 
-- v0.1–v0.4: 基礎 - 試行、導入、改善パッケージ、スターターパッケージ
-- v1.0.0: 32のロール、完全なCLI、実績のある改善、マルチリポジトリの移植性
-- v1.0.2: ロールOSのロックダウン（ブートストラップの真実性の修正、init --force）
-- v1.1.0: 31のロール、完全なルーティング機能、競合検出、エスカレーション、証拠、ディスパッチ、7つの実績のあるチームパッケージ。35回の実行テスト。212件のテスト。
-- v1.2.0: デフォルトとして推奨されるパッケージ。自動選択、不整合の検出、代替案の提案、自由ルーティングのフォールバック。246件のテスト。
-- v1.3.0: 結果の調整、タスクの細分化、複合実行、適応的な再計画。317件のテスト。
-- v1.4.0: セッションの基盤 - `roleos init claude`、`roleos doctor`、ルートカード、/roleos-route + /roleos-review + /roleos-status コマンド。335件のテスト。
-- v1.5.0: フックの基盤 - 実行時の強制のための5つのライフサイクルフック。358件のテスト。
-- v1.6.0: 成果物の基盤 - ロールごとの20件の成果物契約、7件のパッケージ引き継ぎ契約、構造検証。385件のテスト。
-- v1.7.0: 完了の証明 - 実際のタスクをフルスタックで実行。`roleos artifacts` CLI。構造的な修正に関する正直なエスカレーション。398件のテスト。
-- v1.8.0: ミッションライブラリ（Phase S）- 6つの名前付きミッション、ランナーエンジン、完了レポート。6回の実際の試行錯誤で強化されています。481件のテスト。
-- **v1.9.0**: 統合されたエントリパス（Phase T）- `roleos start`は、ミッション、パッケージ、または自由ルーティングを自動的に決定します。フォールバックシステム、複合検出、エントリパスの比較テスト。527件のテスト。
+- v0.1–v0.4: 基礎機能 — テスト、導入、トリートメントパック、スターターパック
+- v1.0.0: 32種類のロール、フルCLI、実績のあるトリートメント、マルチリポジトリ対応
+- v1.0.2: ロールOSのロックダウン（初期設定の修正、`init --force`コマンド）
+- v1.1.0: 31種類のロール、フルルーティング機能、競合検出、エスカレーション、証拠収集、ディスパッチ、7種類の実績のあるチームパック。35回の実行テスト。212件のテスト。
+- v1.2.0: キャリブレーションされたパックがデフォルト設定に。自動選択、不整合検出、代替案の提案、フリールーティングへのフォールバック。246件のテスト。
+- v1.3.0: 結果のキャリブレーション、タスクの細分化、複合実行、適応的な再計画。317件のテスト。
+- v1.4.0: セッション機能 — `roleos init claude`、`roleos doctor`、ルートカード、`/roleos-route`、`/roleos-review`、`/roleos-status`コマンド。335件のテスト。
+- v1.5.0: フック機能 — 実行時強制のための5つのライフサイクルフック。358件のテスト。
+- v1.6.0: アーティファクト機能 — 各ロールごとの20種類のアーティファクト契約、7種類のパックハンドオフ契約、構造検証。385件のテスト。
+- v1.7.0: 完了の検証 — 実際のタスクをフルスタックで実行。`roleos artifacts` CLI。構造的な修正に対する正直なエスカレーション。398件のテスト。
+- v1.8.0: ミッションライブラリ（フェーズS） — 6種類の名前付きミッション、実行エンジン、完了レポート。6回の実際のテストで強化。481件のテスト。
+- v1.9.0: 統合されたエントリーパス（フェーズT） — `roleos start`コマンドが、ミッション、パック、フリールーティングを自動的に選択。フォールバック機能、複合検出、エントリーパスの比較テスト。527件のテスト。
+- **v2.0.0**: ユーザーエクスペリエンス改善（フェーズU） — `roleos run`コマンドが、永続的なディスクベースの実行を作成。再開、次へ、説明、完了、失敗。介入：リルーティング、エスカレーション、再試行、ブロック、再開。各ステップでの詳細なガイダンス。摩擦の測定。6件の摩擦テスト。613件のテスト。
+- **v2.0.1**: マニュアルの監査、初心者向けドキュメント、テスト件数の修正。617件のテスト。
+- **v2.1.0**: ブレインストーミングミッション（v0.4） — 法分野に特化したロール、追跡可能な意見の相違、判決を含む出力。2層アーキテクチャ（真実性 + レンダリング）、クロスエグザム権限マトリックス、紛争グラフ、黄金の実行の検証。7種類のミッション、50種類のロール、8種類のパック。894件のテスト。
 
 ## ライセンス
 

package/README.md

@@ -2,7 +2,6 @@
   <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</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>
 
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/role-os/readme.png" alt="Role OS" width="600">
 </p>
@@ -14,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>
 
-A multi-Claude operating system that staffs, routes, validates, and runs work through 31 specialized role contracts. Creates task packets, assembles the right team from scored role matching, detects broken chains before execution, auto-routes recovery when work is blocked or rejected, and requires structured evidence in every verdict.
+A multi-Claude operating system that staffs, routes, validates, and runs work through 50 specialized role contracts. Creates task packets, assembles the right team from scored role matching, detects broken chains before execution, auto-routes recovery when work is blocked or rejected, and requires structured evidence in every verdict.
 
 ## What it does
 
@@ -104,7 +103,7 @@ Full treatment is a canonical 7-phase protocol defined in Claude project memory
 
 Order: Shipcheck first, then full treatment. No v1.0.0 without passing hard gates.
 
-## 31 roles across 8 packs
+## 50 roles across 8 packs
 
 | Pack | Roles |
 |------|-------|
@@ -181,6 +180,12 @@ Role OS was proven across three trial shapes in two structurally different repos
 - Same treatment pack, structurally different repo (creative workspace vs game)
 - Treatment Pack portable — no contract modifications needed
 
+**Brainstorm golden run** (MCP server marketplace topic)
+- 9-role chain, 4 analysts in parallel, cross-examine + rebut dispute graph
+- 4 challenges issued, 3 claims narrowed, 1 unresolved — healthy pressure, not deadlock
+- 16+ trace links from rendered artifacts back to truth-layer atoms
+- Full chain of custody proven: truth → atoms → dispute → synthesis → expand → judge → render → trace
+
 ## Core properties
 
 These are non-negotiable. If a change weakens any of them, reject it.
@@ -201,7 +206,7 @@ role-os/
     entry-cmd.mjs              ← `roleos start` CLI command
     run.mjs                    ← Persistent run engine: create → step → pause → resume → report
     run-cmd.mjs                ← `roleos run/resume/next/explain/complete/fail` + interventions
-    mission.mjs                ← 6 named mission types (feature, bugfix, treatment, docs, security, research)
+    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
@@ -210,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/                        ← 613 tests across 25 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
 ```
 
@@ -243,13 +251,14 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | **Adaptive replanning** | Mid-run scope changes, findings, or new requirements update the plan without restarting. | ✓ Shipped |
 | **Session spine** | `roleos init claude` scaffolds CLAUDE.md, /roleos-route, /roleos-review, /roleos-status. `roleos doctor` verifies wiring. Route cards prove engagement. | ✓ Shipped |
 | **Hook spine** | 5 lifecycle hooks (SessionStart, PromptSubmit, PreToolUse, SubagentStart, Stop). Advisory enforcement: route card reminders, write-tool gating, subagent role injection, completion audit. | ✓ Shipped |
-| **Artifact spine** | 20 per-role artifact contracts. 7 pack handoff contracts. Structural validation. Chain completeness checks. Downstream roles never guess what they received. | ✓ Shipped |
-| **Mission library** | 6 named missions (feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch). Each declares pack, role chain, artifact flow, escalation branches, honest-partial definition. All 6 trial-run and hardened. | ✓ Shipped |
+| **Artifact spine** | 30 per-role artifact contracts. 7 pack handoff contracts. Structural validation. Chain completeness checks. Downstream roles never guess what they received. | ✓ Shipped |
+| **Mission library** | 7 named missions (feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch, brainstorm). Each declares pack, role chain, artifact flow, escalation branches, honest-partial definition. All 7 trial-proven. | ✓ Shipped |
 | **Mission runner** | Create runs, step through with tracked state, complete/fail with honest reporting. Blocked-step propagation, out-of-chain escalation warnings, last-step re-opening. | ✓ Shipped |
 | **Unified entry** | `roleos start` decides mission vs pack vs free routing automatically. Fallback ladder with confidence scores, alternatives, and composite detection. | ✓ Shipped |
 | **Persistent runs** | `roleos run` creates disk-backed runs. `resume`, `next`, `explain`, `complete`, `fail`. Interventions: reroute, escalate, retry, block, reopen. Step-local guidance. Friction measurement. | ✓ Shipped |
+| **Brainstorm** | Two-layer architecture: truth (role-native schemas, provenance atoms, cross-exam dispute graph) + render (5 distinct voices, lexical bans, debate transcript). Trace links prove every rendered claim maps to a truth atom. Golden run: 894 tests. | ✓ Shipped |
 
-## 6 missions
+## 7 missions
 
 | Mission | Pack | Roles | When to use |
 |---------|------|-------|-------------|
@@ -259,9 +268,30 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | `docs-release` | docs | 2 | Write/update documentation, release notes |
 | `security-hardening` | security | 4 | Threat model, audit, fix vulnerabilities, re-audit, verify |
 | `research-launch` | research | 4 | Frame question, research, document findings, decide |
+| `brainstorm` | brainstorm | 9 | Structured multi-perspective inquiry with traceable disagreement and verdict |
 
 Each mission includes honest-partial definitions — when work stalls, the system documents what was completed and what remains instead of bluffing completion.
 
+### Brainstorm mission
+
+Not "AI brainstorming." The brainstorm mission is **specialized roles under law, with traceable disagreement and verdict-bearing output.**
+
+```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
+```
+
+**What makes it different:**
+
+- **Layer 1 (truth):** Four analysts emit role-native schemas (ContextMap, UserValueMap, MechanicsMap, PositioningMap) — not shared prose. Each role is blindspot-enforced: forbidden phrases, forbidden claim kinds, filtered input partitions. Atoms carry provenance. A directed cross-examination graph produces targeted challenges. Original analysts defend, narrow, or retract under pressure.
+
+- **Layer 2 (render):** Five distinct human voices (Boundary Memo, Field Notes, System Sketch, Claim Brief, Cross-Exam Transcript) with lexical bans preventing voice convergence. Synthesis consumes truth, never rendered prose. Both layers always available.
+
+- **Chain of custody:** Every rendered sentence traces back to a truth-layer atom. Synthesis directions cite atoms. Cross-exam targets real claim IDs. The dispute graph is the product, not the prose.
+
+**Proven:** v0.4 golden run — 894 tests, full chain of custody verified. See [`examples/golden-run.md`](examples/golden-run.md) for the complete artifact chain.
+
 ## Status
 
 - v0.1–v0.4: Foundation — trials, adoption, treatment pack, starter pack
@@ -277,6 +307,8 @@ Each mission includes honest-partial definitions — when work stalls, the syste
 - v1.8.0: Mission library (Phase S) — 6 named missions, runner engine, completion reports. Hardened from 6 real trial runs. 481 tests.
 - v1.9.0: Unified entry path (Phase T) — `roleos start` auto-decides mission vs pack vs free routing. Fallback ladder, composite detection, entry-path comparison trials. 527 tests.
 - **v2.0.0**: Operator friction pass (Phase U) — `roleos run` creates persistent disk-backed runs. Resume, next, explain, complete, fail. Interventions: reroute, escalate, retry, block, reopen. Step-local guidance at every step. Friction measurement. 6 friction trials. 613 tests.
+- **v2.0.1**: Handbook audit, beginner docs, test count corrections. 617 tests.
+- **v2.1.0**: Brainstorm mission (v0.4) — specialized roles under law, traceable disagreement, verdict-bearing output. Two-layer architecture (truth + render), cross-exam permission matrix, dispute graph, golden run proof. 7 missions, 50 roles, 8 packs. 894 tests.
 
 ## License
 

package/README.pt-BR.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.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.md">English</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"
 
 O sistema nunca força o trabalho a passar pela camada de abstração incorreta. Ele explica por que escolheu cada nível e oferece alternativas.
 
+**Um comando para iniciar a execução:**
+
+```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
+```
+
+**Intervenções quando algo dá errado:**
+
+```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"
+```
+
+As execuções são persistidas no disco (em `.claude/runs/`), permitindo que as sessões interrompidas sejam retomadas sem problemas. Cada etapa inclui orientações para o operador: o que produzir, as seções necessárias e as condições de parada.
+
 **Depois de direcionado:**
 
 1. **Cada função produz uma transferência:** saída estruturada com itens de evidência que reduzem a ambiguidade para a próxima função.
@@ -97,19 +124,24 @@ Cada função tem um contrato completo: missão, quando usar, quando não usar,
 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
 ```
 
 ## Quando não usar o Role OS
@@ -148,6 +180,12 @@ O Role OS foi comprovado em três modelos de teste em dois repositórios estrutu
 - Mesmo pacote de tratamento, repositório estruturalmente diferente (ambiente de criação vs. jogo)
 - Pacote de tratamento portátil — nenhuma modificação no contrato é necessária
 
+**Sessão de brainstorming de alta qualidade** (tópico do mercado de servidores MCP)
+- Cadeia de 9 papéis, 4 analistas em paralelo, análise cruzada + gráfico de refutação de disputas.
+- 4 desafios propostos, 3 alegações refinadas, 1 não resolvida — pressão saudável, sem impasse.
+- Mais de 16 links de rastreamento dos artefatos gerados até os átomos da camada de verdade.
+- Cadeia de custódia completa comprovada: verdade → átomos → disputa → síntese → expandir → julgar → renderizar → rastrear.
+
 ## Propriedades essenciais
 
 Estas são inegociáveis. Se uma alteração enfraquecer qualquer uma delas, rejeite-a.
@@ -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 @@ O sistema "Role OS" opera **apenas localmente**. Ele copia modelos em formato Ma
 | **Mission library** | 6 missões nomeadas (feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch). Cada uma define pacote, cadeia de papéis, fluxo de artefatos, ramificações de escalonamento, definição honesta e parcial. Todas as 6 foram testadas e aprimoradas. | ✓ Implementado. |
 | **Mission runner** | Criação de execuções, acompanhamento passo a passo com estado rastreado, conclusão/falha com relatórios precisos. Propagação de etapas bloqueadas, avisos de escalonamento fora da cadeia, reabertura da última etapa. | ✓ Implementado. |
 | **Unified entry** | `roleos start` decide automaticamente entre missão, pacote ou roteamento livre. Sistema de fallback com pontuações de confiança, alternativas e detecção composta. | ✓ Implementado. |
+| **Persistent runs** | `roleos run` cria execuções com backup no disco. Comandos: `resume` (retomar), `next` (próximo), `explain` (explicar), `complete` (concluir), `fail` (falha). Intervenções: redirecionar, escalar, tentar novamente, bloquear, reabrir. Orientações específicas para cada etapa. Medição de atrito. | ✓ Implementado. |
+| **Brainstorm** | Arquitetura de duas camadas: verdade (esquemas nativos do papel, átomos de procedência, gráfico de disputa de análise cruzada) + renderização (5 vozes distintas, restrições lexicais, transcrição do debate). Os links de rastreamento comprovam que cada alegação renderizada corresponde a um átomo de verdade. Sessão de brainstorming de alta qualidade: 894 testes. | ✓ Implementado. |
 
 ## 6 missões
 
@@ -223,23 +268,47 @@ O sistema "Role OS" opera **apenas localmente**. Ele copia modelos em formato Ma
 | `docs-release` | Documentação | 2 | Escrever/atualizar documentação, notas de lançamento |
 | `security-hardening` | Segurança | 4 | Modelo de ameaças, auditoria, correção de vulnerabilidades, re-auditoria, verificação |
 | `research-launch` | Pesquisa | 4 | Formular a pergunta, pesquisar, documentar os resultados, decidir |
+| `brainstorm` | brainstorming | 9 | Investigação estruturada com múltiplas perspectivas, com desacordo rastreável e veredicto. |
 
 Cada missão inclui definições honestas e parciais — quando o trabalho é interrompido, o sistema documenta o que foi concluído e o que resta, em vez de apresentar uma conclusão falsa.
 
+### Missão de brainstorming
+
+Não é "brainstorming de IA". A missão de brainstorming é **papéis especializados sob a lei, com desacordo rastreável e resultados que comprovam o veredicto.**
+
+```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
+```
+
+**O que a diferencia:**
+
+- **Camada 1 (verdade):** Quatro analistas emitem esquemas nativos do papel (ContextMap, UserValueMap, MechanicsMap, PositioningMap) — não é prosa compartilhada. Cada papel tem restrições para evitar pontos cegos: frases proibidas, tipos de alegações proibidas, partições de entrada filtradas. Os átomos carregam informações de procedência. Um gráfico de análise cruzada direcionada gera desafios específicos. Os analistas originais defendem, refinam ou retiram suas alegações sob pressão.
+
+- **Camada 2 (renderização):** Cinco vozes humanas distintas (Boundary Memo, Field Notes, System Sketch, Claim Brief, Cross-Exam Transcript) com restrições lexicais para evitar a convergência das vozes. A síntese consome a verdade, nunca a prosa renderizada. Ambas as camadas estão sempre disponíveis.
+
+- **Cadeia de custódia:** Cada frase renderizada rastreia até um átomo da camada de verdade. As instruções de síntese citam os átomos. Os alvos da análise cruzada são IDs de alegações reais. O gráfico de disputa é o produto, não a prosa.
+
+**Comprovado:** versão 0.4 da sessão de brainstorming de alta qualidade — 894 testes, cadeia de custódia completa verificada. Consulte [`examples/golden-run.md`](examples/golden-run.md) para a cadeia completa de artefatos.
+
 ## Status
 
-- v0.1–v0.4: Fundação — testes, adoção, pacote de tratamento, pacote inicial
-- v1.0.0: 32 papéis, CLI completa, tratamento comprovado, portabilidade multi-repositório
-- v1.0.2: Bloqueio do sistema de papéis (correções de inicialização da verdade, init --force)
-- v1.1.0: 31 papéis, espinha dorsal de roteamento completa, detecção de conflitos, escalonamento, evidências, despacho, 7 pacotes de equipe comprovados. 35 execuções de teste. 212 testes.
-- v1.2.0: Pacotes calibrados promovidos à entrada padrão. Seleção automática, detecção de incompatibilidades, sugestão de alternativas, fallback de roteamento livre. 246 testes.
+- v0.1–v0.4: Fundação — testes, adoção, pacote de tratamento, pacote inicial.
+- v1.0.0: 32 funções, CLI completa, tratamento comprovado, portabilidade multi-repositório.
+- v1.0.2: Bloqueio do sistema operacional para funções (correções de inicialização, `init --force`).
+- v1.1.0: 31 funções, roteamento completo, detecção de conflitos, escalonamento, evidências, despacho, 7 pacotes de equipe comprovados. 35 testes de execução. 212 testes.
+- v1.2.0: Pacotes calibrados promovidos a entrada padrão. Seleção automática, detecção de incompatibilidades, sugestão alternativa, fallback de roteamento livre. 246 testes.
 - v1.3.0: Calibração de resultados, decomposição de tarefas mistas, execução composta, replanejamento adaptativo. 317 testes.
-- v1.4.0: Espinha dorsal da sessão — `roleos init claude`, `roleos doctor`, cartões de roteamento, comandos /roleos-route + /roleos-review + /roleos-status. 335 testes.
-- v1.5.0: Espinha dorsal de ganchos — 5 ganchos de ciclo de vida para aplicação de políticas em tempo de execução. 358 testes.
-- v1.6.0: Espinha dorsal de artefatos — 20 contratos de artefatos por papel, 7 contratos de transferência de pacotes, validação estrutural. 385 testes.
-- v1.7.0: Prova de conclusão — tarefas reais executadas em toda a pilha. CLI `roleos artifacts`. Escalonamento honesto para correções estruturais. 398 testes.
-- v1.8.0: Biblioteca de missões (Fase S) — 6 missões nomeadas, motor de execução, relatórios de conclusão. Aprimorado a partir de 6 execuções de teste reais. 481 testes.
-- **v1.9.0**: Caminho de entrada unificado (Fase T) — `roleos start` decide automaticamente entre missão, pacote ou roteamento livre. Sistema de fallback, detecção composta, testes de comparação de caminho de entrada. 527 testes.
+- v1.4.0: Espinha dorsal da sessão — `roleos init claude`, `roleos doctor`, cartões de rota, comandos `/roleos-route + /roleos-review + /roleos-status`. 335 testes.
+- v1.5.0: Espinha dorsal de hooks — 5 hooks de ciclo de vida para aplicação em tempo de execução. 358 testes.
+- v1.6.0: Espinha dorsal de artefatos — 20 contratos de artefatos por função, 7 contratos de transferência de pacotes, validação estrutural. 385 testes.
+- v1.7.0: Prova de conclusão — tarefas reais executadas em toda a pilha. CLI `roleos artifacts`. Escalabilidade honesta para correções estruturais. 398 testes.
+- v1.8.0: Biblioteca de missões (Fase S) — 6 missões nomeadas, motor de execução, relatórios de conclusão. Reforçado com 6 execuções de teste reais. 481 testes.
+- v1.9.0: Caminho de entrada unificado (Fase T) — `roleos start` decide automaticamente entre missão, pacote ou roteamento livre. Escada de fallback, detecção composta, testes de comparação de caminho de entrada. 527 testes.
+- **v2.0.0**: Otimização da experiência do usuário (Fase U) — `roleos run` cria execuções persistentes com backup em disco. Retomar, próximo, explicar, completar, falhar. Intervenções: redirecionar, escalar, tentar novamente, bloquear, reabrir. Orientação passo a passo em cada etapa. Medição de atrito. 6 testes de atrito. 613 testes.
+- **v2.0.1**: Auditoria do manual, documentação para iniciantes, correções na contagem de testes. 617 testes.
+- **v2.1.0**: Missão de brainstorming (v0.4) — funções especializadas sob a lei, desacordo rastreável, saída com valor de decisão. Arquitetura de duas camadas (verdade + renderização), matriz de permissão de interrogatório, grafo de disputas, prova de execução ideal. 7 missões, 50 funções, 8 pacotes. 894 testes.
 
 ## Licença