musubix 3.3.9 → 3.4.0

package/docs/adr/0001-real-time-pattern-learning-architecture-for-v1-5-0.md

@@ -0,0 +1,75 @@
+# ADR-0001: Real-time Pattern Learning Architecture for v1.5.0
+
+- **Date**: 2026-01-05
+- **Status**: accepted
+- **Deciders**: Architecture Team
+- **Categories**: Learning, Performance
+
+## Context
+
+MUSUBIX v1.4.xではバッチ学習方式を採用しているが、ユーザーのコード変更をリアルタイムで学習する要求がある。
+
+### 要件
+- REQ-LEARN-011: ファイル変更時500ms以内に分析
+- REQ-LEARN-013: フィードバック収集レイテンシ100ms以内
+- REQ-LEARN-014: ストリーム処理1000 events/sec以上
+
+### 検討した選択肢
+1. **Polling方式**: 定期的にファイル変更をチェック
+2. **fs.watch + EventEmitter**: Node.js標準のファイル監視
+3. **chokidar + RxJS**: サードパーティライブラリによるリアクティブストリーム
+
+## Decision
+
+**選択肢 2: fs.watch + EventEmitter** を採用する。
+
+### 理由
+- 外部依存なしで実現可能
+- Node.js標準APIで十分な性能
+- メモリフットプリントが小さい
+
+### アーキテクチャ
+
+```
+FileWatcher (fs.watch)
+    │
+    ▼
+StreamProcessor (EventEmitter)
+    │
+    ├─▼ FeedbackQueue (Non-blocking)
+    │
+    └─▼ PatternExtractor (AST)
+           │
+           ▼
+    IncrementalUpdater (Delta)
+```
+
+### パフォーマンス目標
+| メトリクス | 目標 | 測定方法 |
+|------------|------|----------|
+| 分析レイテンシ | < 500ms | StreamProcessor.getLatency() |
+| フィードバック収集 | < 100ms | FeedbackQueue timing |
+| スループット | ≥ 1000/sec | EventStream.getThroughput() |
+
+## Consequences
+
+### Positive
+- リアルタイム学習によるユーザー体験向上
+- 外部依存なしで軽量
+- 段階的な実装が可能
+
+### Negative
+- fs.watchのクロスプラットフォーム差異への対応が必要
+- 大規模プロジェクトでのスケーラビリティ検証が必要
+
+### Risks
+- macOS/Linux/Windowsでのfs.watchの挙動差異
+- 軽減策: chokidarへのフォールバック機構を用意
+
+## Related Requirements
+
+- REQ-LEARN-010: Real-time pattern learning
+- REQ-LEARN-011: 500ms analysis latency
+- REQ-LEARN-012: Incremental update
+- REQ-LEARN-013: Non-blocking feedback
+- REQ-LEARN-014: Stream processing

package/docs/adr/0002-pattern-sharing-protocol-for-cross-team-collaborat.md

@@ -0,0 +1,79 @@
+# ADR-0002: Pattern Sharing Protocol for cross-team collaboration
+
+- **Date**: 2026-01-05
+- **Status**: accepted
+- **Deciders**: Architecture Team
+- **Categories**: Sharing, Security
+
+## Context
+
+チーム間で学習済みパターンを共有する要求がある。プライバシーとセキュリティを考慮したプロトコルが必要。
+
+### 要件
+- REQ-SHARE-001: JSON形式でエクスポート
+- REQ-SHARE-003: インポート時のオントロジー検証
+- REQ-SHARE-004: 機密データの除去
+- REQ-SHARE-005: 競合解決戦略
+
+### 検討した選択肢
+1. **Git-based sharing**: Gitリポジトリでパターンを共有
+2. **REST API**: 中央サーバー経由の共有
+3. **File-based export/import**: JSONファイルの直接交換
+
+## Decision
+
+**選択肢 3: File-based export/import** を採用する。
+
+### 理由
+- インフラ不要で即座に利用可能
+- オフライン環境でも利用可能
+- 将来的にGit連携への拡張が容易
+
+### ファイルフォーマット
+
+```json
+{
+  "version": "1.0",
+  "exportedAt": "2026-01-05T12:00:00Z",
+  "patterns": [
+    {
+      "id": "PAT-001",
+      "name": "Repository Pattern",
+      "category": "design",
+      "confidence": 0.95,
+      "template": "...",
+      "metadata": {
+        "author": "[REDACTED]",
+        "domain": "data-access"
+      }
+    }
+  ],
+  "checksum": "sha256:..."
+}
+```
+
+### セキュリティ対策
+| 対策 | 実装 |
+|------|------|
+| 機密データ除去 | DataSanitizerによる自動マスキング |
+| 改ざん検出 | SHA-256チェックサム |
+| スキーマ検証 | JSON Schemaによるバリデーション |
+
+## Consequences
+
+### Positive
+- シンプルで即座に利用可能
+- プライバシー保護が容易
+- バージョン管理が明確
+
+### Negative
+- 自動同期機能なし（将来拡張）
+- 大規模チームでの管理が煩雑になる可能性
+
+## Related Requirements
+
+- REQ-SHARE-001: JSON export format
+- REQ-SHARE-002: External import
+- REQ-SHARE-003: Ontology validation
+- REQ-SHARE-004: Privacy protection
+- REQ-SHARE-005: Conflict resolution

package/docs/adr/0003-owl-2-rl-implementation-strategy-for-advanced-infe.md

@@ -0,0 +1,90 @@
+# ADR-0003: OWL 2 RL Implementation Strategy for advanced inference
+
+- **Date**: 2026-01-05
+- **Status**: accepted
+- **Deciders**: Architecture Team
+- **Categories**: Ontology, Inference
+
+## Context
+
+MUSUBIX v1.4.xではN3.jsによる基本的なRDF処理を実装済み。OWL 2 RLプロファイルの推論機能を追加する必要がある。
+
+### 要件
+- REQ-ONTO-010: OWL 2 RLプロファイル対応
+- REQ-ONTO-011: 200ms以内の推論（10,000トリプルまで）
+- REQ-ONTO-014: Datalogルール統合（最大100ルール）
+
+### 検討した選択肢
+1. **完全なOWL 2推論器（HermiT等）**: Javaベース、高機能だが重い
+2. **N3.js + カスタムルール**: 既存実装を拡張
+3. **RDFox / Stardog**: 商用推論エンジン
+
+## Decision
+
+**選択肢 2: N3.js + カスタムOWL 2 RLルール** を採用する。
+
+### 理由
+- 既存のN3Store実装を活用可能
+- 軽量でNode.js環境に最適
+- 必要なルールセットのみ実装（段階的拡張）
+
+### 実装するOWL 2 RLルール（Phase 1）
+
+| ルールID | 説明 | 優先度 |
+|----------|------|--------|
+| prp-dom | rdfs:domain推論 | P0 |
+| prp-rng | rdfs:range推論 | P0 |
+| prp-spo1 | rdfs:subPropertyOf推論 | P0 |
+| cax-sco | rdfs:subClassOf推論 | P0 |
+| prp-trp | owl:TransitiveProperty | P1 |
+| prp-symp | owl:SymmetricProperty | P1 |
+| prp-inv1/2 | owl:inverseOf | P1 |
+
+### アーキテクチャ
+
+```
+QueryEngine
+    │
+    ▼
+RuleEngine (OWL 2 RL)
+    │
+    ├── BuiltInRules (prp-*, cax-*)
+    │
+    └── DatalogIntegrator (最大100ルール)
+           │
+           ▼
+    InferenceExecutor (200ms SLA)
+           │
+           ▼
+    ExplanationGenerator
+```
+
+### パフォーマンス目標
+| グラフサイズ | 目標レイテンシ |
+|-------------|---------------|
+| 1,000 triples | < 50ms |
+| 5,000 triples | < 100ms |
+| 10,000 triples | < 200ms |
+
+## Consequences
+
+### Positive
+- 既存実装との統合が容易
+- 軽量で高速
+- 段階的な機能追加が可能
+
+### Negative
+- OWL 2 RL全機能のサポートには時間がかかる
+- 複雑な推論には限界あり
+
+### Risks
+- 10,000トリプル超での性能劣化
+- 軽減策: インデックス最適化、マテリアライズドビュー
+
+## Related Requirements
+
+- REQ-ONTO-010: OWL 2 RL support
+- REQ-ONTO-011: 200ms inference latency
+- REQ-ONTO-012: Progress feedback
+- REQ-ONTO-013: Explanation generation
+- REQ-ONTO-014: Datalog integration

package/docs/adr/ADR-v3.4.0-001-deep-research-architecture.md

@@ -0,0 +1,217 @@
+# ADR-v3.4.0-001: Deep Research Architecture Decision
+
+**Status**: Accepted  
+**Date**: 2026-01-16  
+**Authors**: AI Agent  
+**Context**: MUSUBIX v3.4.0 Deep Research Integration  
+**Traces To**: REQ-DR-CORE-001, DES-DR-v3.4.0
+
+---
+
+## Context
+
+MUSUBIX v3.4.0でDeep Research機能を追加するにあたり、以下の技術的決定が必要となった：
+
+1. **アーキテクチャパターン**: どのように反復的調査サイクルを実現するか
+2. **既存システム統合**: 7つの既存パッケージとどのように統合するか
+3. **状態管理**: イテレーション間の知識をどのように蓄積・管理するか
+
+### 要件からの制約
+
+- REQ-DR-CORE-001: 最大10イテレーションの反復サイクル
+- REQ-DR-INT-001〜009: 7パッケージとのシームレス統合必須
+- 憲法Article I: Library-First（独立パッケージとして実装）
+- 憲法Article V: 完全なトレーサビリティ
+
+---
+
+## Decision
+
+**Template Method Pattern**を中心としたアーキテクチャを採用する。
+
+### 採用パターン
+
+```typescript
+// ResearchEngine: Template Method Pattern
+class ResearchEngine {
+  async research(): Promise<ResearchReport> {
+    this.initialize();
+    
+    while (!this.shouldStop()) {
+      // 固定フロー（Template Method）
+      const questions = await this.generateQuestions();
+      const searchResults = await this.search(questions);
+      const contents = await this.read(searchResults);
+      const knowledge = await this.reason(contents);
+      
+      this.knowledge.addAll(knowledge);
+      this.iteration++;
+      
+      if (await this.isAnswerDefinitive()) {
+        break;
+      }
+    }
+    
+    return this.generateReport();
+  }
+  
+  // フックメソッド（拡張可能）
+  protected async generateQuestions(): Promise<ReflectiveQuestion[]> { /* ... */ }
+  protected async search(questions: ReflectiveQuestion[]): Promise<SearchResult[]> { /* ... */ }
+  protected async read(results: SearchResult[]): Promise<WebContent[]> { /* ... */ }
+  protected async reason(contents: WebContent[]): Promise<KnowledgeItem[]> { /* ... */ }
+}
+```
+
+### アーキテクチャレイヤー
+
+```
+┌─────────────────────────────────────────────────────┐
+│ CLI / MCP Tools (Interface Layer)                  │
+│ - deepResearchCommand()                             │
+│ - deep_research_start tool                          │
+├─────────────────────────────────────────────────────┤
+│ ResearchEngine (Application Layer)                  │
+│ - Template Method: research()                       │
+│ - State Management: KnowledgeBase                   │
+├─────────────────────────────────────────────────────┤
+│ Core Services (Domain Layer)                        │
+│ - SearchProviderFactory (Strategy)                  │
+│ - LMReasoning (Adapter)                             │
+│ - ReportGenerator (Builder)                         │
+├─────────────────────────────────────────────────────┤
+│ Integrations (Infrastructure Layer)                 │
+│ - ExpertIntegration                                 │
+│ - KnowledgeStoreIntegration                         │
+│ - WorkflowIntegration                               │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Rationale
+
+### なぜTemplate Method Patternか
+
+**✅ 採用理由**:
+
+1. **固定フローの明確化**: search → read → reason → evaluateの順序が不変
+2. **拡張性**: 各ステップをフックメソッドとして実装し、サブクラスで拡張可能
+3. **トレーサビリティ**: 各ステップが明示的で、ログ・デバッグが容易
+4. **テスト容易性**: 各フックメソッドを独立してテスト可能
+
+**比較した代替案**:
+
+| パターン | メリット | デメリット | 判定 |
+|---------|---------|-----------|------|
+| **Template Method** | フロー固定、拡張可能 | 継承ベース | ✅ 採用 |
+| **Strategy Pattern** | 柔軟な切り替え | フロー全体を切り替える必要 | ❌ 不適 |
+| **Pipeline Pattern** | 関数型、シンプル | エラーハンドリングが複雑 | ❌ 不適 |
+| **State Machine** | 状態遷移明確 | オーバーエンジニアリング | ❌ 不適 |
+
+### 既存システム統合戦略
+
+**Adapter + Bridge Pattern**で統合：
+
+```typescript
+// Adapter Pattern: 外部システムの抽象化
+class ExpertIntegration {
+  constructor(private delegation: DelegationEngine) {}
+  
+  async convertToEARS(finding: string): Promise<string> {
+    return (await this.delegation.delegate({ ... })).content;
+  }
+}
+
+// Bridge Pattern: 実装の切り替え
+interface KnowledgePersistence {
+  save(item: KnowledgeItem): Promise<void>;
+}
+
+class InMemoryPersistence implements KnowledgePersistence { /* ... */ }
+class KnowledgeStorePersistence implements KnowledgePersistence { /* ... */ }
+```
+
+### 状態管理: KnowledgeBase
+
+**Repository Pattern**でデータアクセスを抽象化：
+
+```typescript
+class KnowledgeBase {
+  private items: Map<string, KnowledgeItem> = new Map();
+  private iterationIndex: Map<number, string[]> = new Map();
+  
+  add(item: KnowledgeItem): void { /* ... */ }
+  getFindings(): KnowledgeItem[] { /* ... */ }
+  getByIteration(iteration: number): KnowledgeItem[] { /* ... */ }
+}
+```
+
+**将来の永続化移行が容易**:
+- 現在: In-Memory (Map)
+- 将来: @musubix/knowledge統合 → JSON永続化
+- 将来: Database統合 → PostgreSQL/MongoDB
+
+---
+
+## Consequences
+
+### Positive
+
+✅ **明確なフロー**: research()メソッドでイテレーションロジックが一目瞭然  
+✅ **拡張性**: 各フックメソッドをオーバーライドして特定ドメインに特化可能  
+✅ **テスト容易性**: 各ステップを独立してMock/Stubでテスト  
+✅ **トレーサビリティ**: 各イテレーションでログ出力、デバッグ容易  
+✅ **憲法準拠**: Library-First、Design Patterns適用
+
+### Negative
+
+⚠️ **継承の制約**: Template Methodは継承ベースなので、多重継承不可  
+⚠️ **フック数**: フックメソッドが増えすぎると保守性低下  
+⚠️ **状態管理**: KnowledgeBaseが肥大化する可能性
+
+### Mitigations
+
+- **Composition over Inheritance**: 必要に応じてStrategyパターンと組み合わせ
+- **フック数制限**: 5フックメソッド（generate, search, read, reason, evaluate）に限定
+- **KnowledgeBase分割**: イテレーション数が50を超える場合は永続化層に移行
+
+---
+
+## Compliance
+
+### 憲法準拠
+
+| 条項 | 準拠状況 |
+|-----|---------|
+| I. Library-First | ✅ packages/deep-research/ |
+| V. Traceability | ✅ 各コンポーネントにREQ-ID紐付け |
+| VII. Design Patterns | ✅ Template Method, Strategy, Adapter等適用 |
+
+### SOLID原則
+
+| 原則 | 適用 |
+|------|------|
+| **S**RP | ✅ ResearchEngine（調整）、KnowledgeBase（データ）、ReportGenerator（出力）で分離 |
+| **O**CP | ✅ フックメソッドで拡張、Template Method本体は変更不要 |
+| **L**SP | ✅ サブクラスでフックメソッドをオーバーライド可能 |
+| **I**SP | ✅ 各インターフェースは単一責任（SearchProvider、LMProvider等） |
+| **D**IP | ✅ 抽象（インターフェース）に依存、具象クラスに依存しない |
+
+---
+
+## References
+
+- [Design Patterns: Elements of Reusable Object-Oriented Software](https://en.wikipedia.org/wiki/Design_Patterns) - Template Method Pattern
+- [jina-ai/node-DeepResearch](https://github.com/jina-ai/node-DeepResearch) - 参照実装
+- REQ-MUSUBIX-v3.4.0.md - 要件定義書
+- DES-DR-v3.4.0.md - 設計書
+- steering/structure.ja.md - プロジェクト構造
+
+---
+
+## Approval
+
+- **Author**: AI Agent (2026-01-16)
+- **Reviewer**: -
+- **Status**: Accepted