musubix 3.4.0 → 3.4.2

package/docs/overview/MUSUBIX-Learning.md

@@ -1,837 +0,0 @@
-# MUSUBIX 学習システム パッケージ群
-
-**関連パッケージ**:
-- `@nahisaho/musubix-pattern-mcp`
-- `@nahisaho/musubix-ontology-mcp`
-- `@nahisaho/musubix-wake-sleep`
-- `@nahisaho/musubix-sdd-ontology`
-
-**バージョン**: 1.7.5  
-**最終更新**: 2026-01-06
-
----
-
-## 1. 学習システム概要
-
-MUSUBIXの学習システムは、AIエージェントの継続的な改善を実現します。Wake-Sleepサイクル、パターン学習、オントロジー管理を統合した自律学習機能を提供します。
-
-### 1.1 学習アーキテクチャ
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   Wake-Sleep Cycle                           │
-│  ┌──────────────────────┐    ┌──────────────────────┐       │
-│  │      Wake Phase      │    │     Sleep Phase      │       │
-│  │  ・コード観察        │    │  ・パターン統合      │       │
-│  │  ・パターン抽出      │    │  ・類似パターン圧縮  │       │
-│  │  ・知識グラフ更新    │    │  ・メモリ最適化      │       │
-│  └──────────┬───────────┘    └───────────┬──────────┘       │
-│             │                            │                   │
-│             └────────────┬───────────────┘                   │
-│                          ▼                                   │
-│  ┌───────────────────────────────────────────────────────┐  │
-│  │               Pattern Library                          │  │
-│  │  ・抽出パターン  ・圧縮パターン  ・信頼度スコア       │  │
-│  └───────────────────────────────────────────────────────┘  │
-│                          │                                   │
-│                          ▼                                   │
-│  ┌───────────────────────────────────────────────────────┐  │
-│  │              Ontology Store (N3)                       │  │
-│  │  ・RDF/OWL知識  ・推論ルール  ・ドメインオントロジー  │  │
-│  └───────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 1.2 パッケージ構成
-
-| パッケージ | 役割 |
-|-----------|------|
-| **pattern-mcp** | パターン抽出・圧縮・ライブラリ管理 |
-| **ontology-mcp** | N3Store・推論エンジン・オントロジー管理 |
-| **wake-sleep** | Wake-Sleep学習サイクル制御 |
-| **sdd-ontology** | SDD方法論のオントロジー定義 |
-
----
-
-## 2. Pattern MCP
-
-### 2.1 概要
-
-`@nahisaho/musubix-pattern-mcp` は、コードからパターンを抽出・圧縮し、再利用可能な形式で管理します。
-
-### 2.2 アーキテクチャ
-
-```
-packages/pattern-mcp/src/
-├── extractor/
-│   ├── ast-analyzer.ts      # AST解析
-│   ├── pattern-detector.ts  # パターン検出
-│   └── feature-extractor.ts # 特徴抽出
-├── compressor/
-│   ├── similarity.ts        # 類似度計算
-│   ├── merger.ts            # パターン統合
-│   └── abstractor.ts        # 抽象化
-├── library/
-│   ├── pattern-store.ts     # パターンストア
-│   ├── indexer.ts           # インデックス
-│   └── search.ts            # 検索
-├── tools/
-│   └── pattern-tools.ts     # MCPツール
-└── index.ts
-```
-
-### 2.3 主要機能
-
-#### 2.3.1 パターン抽出
-
-コードからパターンを自動抽出します。
-
-```typescript
-import { PatternExtractor } from '@nahisaho/musubix-pattern-mcp';
-
-const extractor = new PatternExtractor();
-
-const patterns = await extractor.extract(`
-  class UserService {
-    constructor(private readonly userRepo: UserRepository) {}
-    
-    async findUser(id: string): Promise<User | null> {
-      return this.userRepo.findById(id);
-    }
-  }
-`);
-
-// 抽出結果
-// {
-//   patterns: [
-//     {
-//       name: 'repository-pattern',
-//       type: 'design-pattern',
-//       confidence: 0.95,
-//       features: ['dependency-injection', 'async-method', 'repository-access']
-//     }
-//   ]
-// }
-```
-
-#### 2.3.2 パターン圧縮
-
-類似パターンを統合・抽象化します。
-
-```typescript
-import { PatternCompressor } from '@nahisaho/musubix-pattern-mcp';
-
-const compressor = new PatternCompressor();
-
-// 類似パターンの統合
-const compressed = await compressor.compress(patterns, {
-  similarityThreshold: 0.8,
-  minOccurrences: 3,
-});
-
-// 抽象化
-const abstracted = await compressor.abstract(pattern, {
-  level: 'high',  // 'low' | 'medium' | 'high'
-});
-```
-
-#### 2.3.3 パターンライブラリ
-
-学習したパターンを永続化・検索します。
-
-```typescript
-import { PatternLibrary } from '@nahisaho/musubix-pattern-mcp';
-
-const library = new PatternLibrary({
-  storagePath: './patterns.db',
-});
-
-// パターン保存
-await library.store(pattern);
-
-// パターン検索
-const matches = await library.search({
-  type: 'design-pattern',
-  domain: 'authentication',
-  minConfidence: 0.9,
-});
-
-// パターン推奨
-const recommendations = await library.recommend({
-  context: 'user-service-implementation',
-  maxResults: 5,
-});
-```
-
-### 2.4 パターンスキーマ
-
-```typescript
-interface Pattern {
-  id: string;
-  name: string;
-  type: PatternType;
-  description: string;
-  
-  // 構造情報
-  structure: {
-    ast: ASTNode;
-    features: string[];
-    relationships: Relationship[];
-  };
-  
-  // メタデータ
-  metadata: {
-    domain: string;
-    language: string;
-    framework?: string;
-  };
-  
-  // 品質情報
-  quality: {
-    confidence: number;      // 0-1
-    occurrences: number;
-    successRate: number;     // 適用成功率
-    lastUsed: Date;
-  };
-  
-  // 抽象化レベル
-  abstraction: {
-    level: 'concrete' | 'semi-abstract' | 'abstract';
-    generalizedFrom: string[];  // 元パターンID
-  };
-}
-
-type PatternType = 
-  | 'design-pattern'
-  | 'code-idiom'
-  | 'architecture-pattern'
-  | 'test-pattern'
-  | 'error-handling';
-```
-
----
-
-## 3. Ontology MCP
-
-### 3.1 概要
-
-`@nahisaho/musubix-ontology-mcp` は、N3Store基盤のオントロジー管理と推論エンジンを提供します。
-
-### 3.2 アーキテクチャ
-
-```
-packages/ontology-mcp/src/
-├── store/
-│   ├── n3-store.ts          # N3Store実装
-│   ├── graph-manager.ts     # グラフ管理
-│   └── namespace.ts         # 名前空間管理
-├── inference/
-│   ├── reasoner.ts          # 推論エンジン
-│   ├── rules.ts             # 推論ルール
-│   └── forward-chain.ts     # 前向き連鎖
-├── validation/
-│   ├── consistency.ts       # 整合性検証
-│   ├── circular.ts          # 循環検出
-│   └── schema-validator.ts  # スキーマ検証
-├── tools/
-│   └── ontology-tools.ts    # MCPツール
-└── index.ts
-```
-
-### 3.3 主要機能
-
-#### 3.3.1 N3Store
-
-RDF/OWLデータを格納・操作します。
-
-```typescript
-import { N3Store } from '@nahisaho/musubix-ontology-mcp';
-
-const store = new N3Store();
-
-// トリプル追加
-store.addQuad(
-  namedNode('http://example.org/User'),
-  namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
-  namedNode('http://www.w3.org/2002/07/owl#Class')
-);
-
-// クエリ
-const results = store.getQuads(
-  null,  // 任意のsubject
-  namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
-  null   // 任意のobject
-);
-```
-
-#### 3.3.2 推論エンジン
-
-オントロジーに基づく推論を実行します。
-
-```typescript
-import { Reasoner } from '@nahisaho/musubix-ontology-mcp';
-
-const reasoner = new Reasoner(store);
-
-// 組み込みルールで推論
-await reasoner.infer({
-  rules: ['rdfs', 'owl-lite'],
-});
-
-// カスタムルール追加
-reasoner.addRule({
-  name: 'transitivity-rule',
-  condition: '?a sdd:dependsOn ?b . ?b sdd:dependsOn ?c',
-  conclusion: '?a sdd:transitivelyDependsOn ?c',
-});
-
-// 推論実行
-const inferred = await reasoner.query({
-  subject: 'comp:UserService',
-  predicate: 'sdd:transitivelyDependsOn',
-});
-```
-
-#### 3.3.3 整合性検証
-
-オントロジーの整合性をチェックします。
-
-```typescript
-import { ConsistencyValidator } from '@nahisaho/musubix-ontology-mcp';
-
-const validator = new ConsistencyValidator(store);
-
-// 整合性検証
-const result = await validator.validate();
-
-// 結果
-// {
-//   valid: false,
-//   violations: [
-//     {
-//       type: 'domain-violation',
-//       subject: 'req:REQ-001',
-//       predicate: 'sdd:implements',
-//       message: 'sdd:implements requires subject of type sdd:Design'
-//     }
-//   ]
-// }
-
-// 循環依存検出
-const circular = await validator.checkCircular({
-  predicate: 'sdd:dependsOn',
-});
-```
-
-### 3.4 MCPツール
-
-| ツール名 | 説明 |
-|---------|------|
-| `ontology_query` | オントロジーグラフへのクエリ |
-| `ontology_infer` | 推論実行 |
-| `consistency_validate` | 整合性検証 |
-| `validate_triple` | トリプル事前検証 |
-| `check_circular` | 循環依存検出 |
-
----
-
-## 4. Wake-Sleep
-
-### 4.1 概要
-
-`@nahisaho/musubix-wake-sleep` は、Wake-Sleepアルゴリズムに基づく継続的学習サイクルを実装します。
-
-### 4.2 アーキテクチャ
-
-```
-packages/wake-sleep/src/
-├── cycle/
-│   ├── wake-sleep-cycle.ts  # メインサイクル
-│   ├── scheduler.ts         # スケジューラー
-│   └── state-machine.ts     # 状態管理
-├── wake/
-│   ├── observer.ts          # コード観察
-│   ├── extractor.ts         # パターン抽出
-│   └── updater.ts           # 知識更新
-├── sleep/
-│   ├── consolidator.ts      # パターン統合
-│   ├── compressor.ts        # 圧縮処理
-│   └── optimizer.ts         # メモリ最適化
-├── bridge/
-│   └── pattern-ontology-bridge.ts  # パターン↔オントロジー変換
-└── index.ts
-```
-
-### 4.3 Wake-Sleepサイクル
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Wake-Sleep Cycle                          │
-└─────────────────────────────────────────────────────────────┘
-
-                    ┌─────────────┐
-                    │    Idle     │
-                    └──────┬──────┘
-                           │ trigger
-                           ▼
-            ┌──────────────────────────┐
-            │       Wake Phase         │
-            │  ┌────────────────────┐  │
-            │  │     Observe        │  │
-            │  └─────────┬──────────┘  │
-            │            ▼             │
-            │  ┌────────────────────┐  │
-            │  │     Extract        │  │
-            │  └─────────┬──────────┘  │
-            │            ▼             │
-            │  ┌────────────────────┐  │
-            │  │     Update KG      │  │
-            │  └────────────────────┘  │
-            └────────────┬─────────────┘
-                         │
-                         ▼
-            ┌──────────────────────────┐
-            │      Sleep Phase         │
-            │  ┌────────────────────┐  │
-            │  │   Consolidate      │  │
-            │  └─────────┬──────────┘  │
-            │            ▼             │
-            │  ┌────────────────────┐  │
-            │  │     Compress       │  │
-            │  └─────────┬──────────┘  │
-            │            ▼             │
-            │  ┌────────────────────┐  │
-            │  │     Optimize       │  │
-            │  └────────────────────┘  │
-            └────────────┬─────────────┘
-                         │
-                         ▼
-                    ┌─────────────┐
-                    │    Idle     │
-                    └─────────────┘
-```
-
-### 4.4 主要機能
-
-#### 4.4.1 サイクル制御
-
-```typescript
-import { WakeSleepCycle } from '@nahisaho/musubix-wake-sleep';
-
-const cycle = new WakeSleepCycle({
-  patternLibrary: patternLib,
-  ontologyStore: ontologyStore,
-  schedule: {
-    wakeInterval: 3600,    // 1時間ごとにWake
-    sleepAfterWake: true,  // Wake後に自動Sleep
-  },
-});
-
-// サイクル開始
-await cycle.start();
-
-// 手動トリガー
-await cycle.triggerWake();
-await cycle.triggerSleep();
-
-// 状態確認
-const status = cycle.getStatus();
-// { phase: 'idle', lastWake: '...', lastSleep: '...' }
-```
-
-#### 4.4.2 Wakeフェーズ
-
-```typescript
-import { WakePhase } from '@nahisaho/musubix-wake-sleep';
-
-const wake = new WakePhase({
-  observers: ['file-system', 'git-changes', 'test-results'],
-});
-
-// コード観察
-const observations = await wake.observe({
-  paths: ['./src'],
-  since: lastWakeTime,
-});
-
-// パターン抽出
-const patterns = await wake.extractPatterns(observations);
-
-// 知識グラフ更新
-await wake.updateKnowledge(patterns);
-```
-
-#### 4.4.3 Sleepフェーズ
-
-```typescript
-import { SleepPhase } from '@nahisaho/musubix-wake-sleep';
-
-const sleep = new SleepPhase({
-  compressionThreshold: 0.8,
-  retentionPolicy: {
-    minConfidence: 0.5,
-    minOccurrences: 2,
-  },
-});
-
-// パターン統合
-const consolidated = await sleep.consolidate();
-
-// 圧縮
-const compressed = await sleep.compress(consolidated);
-
-// メモリ最適化
-await sleep.optimize({
-  pruneUnused: true,
-  defragment: true,
-});
-```
-
-### 4.5 パターン-オントロジーブリッジ
-
-パターンとオントロジー間の相互変換を行います。
-
-```typescript
-import { PatternOntologyBridge } from '@nahisaho/musubix-wake-sleep';
-
-const bridge = new PatternOntologyBridge({
-  patternLibrary,
-  ontologyStore,
-});
-
-// パターン → オントロジー
-const triples = bridge.patternToTriples(pattern);
-await ontologyStore.addQuads(triples);
-
-// オントロジー → パターン
-const pattern = bridge.triplesToPattern(triples);
-await patternLibrary.store(pattern);
-```
-
----
-
-## 5. SDD Ontology
-
-### 5.1 概要
-
-`@nahisaho/musubix-sdd-ontology` は、SDD（Symbolic-Driven Development）方法論のオントロジー定義を提供します。
-
-### 5.2 オントロジー構造
-
-```
-packages/sdd-ontology/src/
-├── schema/
-│   ├── sdd.ttl              # SDDコアオントロジー
-│   ├── requirements.ttl     # 要件オントロジー
-│   ├── design.ttl           # 設計オントロジー
-│   ├── code.ttl             # コードオントロジー
-│   └── traceability.ttl     # トレーサビリティオントロジー
-├── rules/
-│   ├── ears-rules.ttl       # EARS推論ルール
-│   ├── c4-rules.ttl         # C4推論ルール
-│   └── quality-rules.ttl    # 品質推論ルール
-├── loader.ts                # オントロジーローダー
-└── index.ts
-```
-
-### 5.3 SDDコアオントロジー
-
-```turtle
-@prefix sdd: <http://musubix.dev/sdd#> .
-@prefix owl: <http://www.w3.org/2002/07/owl#> .
-@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
-
-# === クラス定義 ===
-
-sdd:Artifact a owl:Class ;
-    rdfs:label "Software Artifact" ;
-    rdfs:comment "Base class for all SDD artifacts" .
-
-sdd:Requirement a owl:Class ;
-    rdfs:subClassOf sdd:Artifact ;
-    rdfs:label "Requirement" .
-
-sdd:Design a owl:Class ;
-    rdfs:subClassOf sdd:Artifact ;
-    rdfs:label "Design" .
-
-sdd:Code a owl:Class ;
-    rdfs:subClassOf sdd:Artifact ;
-    rdfs:label "Code" .
-
-sdd:Test a owl:Class ;
-    rdfs:subClassOf sdd:Artifact ;
-    rdfs:label "Test" .
-
-# === EARSパターン ===
-
-sdd:EARSPattern a owl:Class ;
-    rdfs:label "EARS Pattern" .
-
-sdd:UbiquitousPattern a owl:Class ;
-    rdfs:subClassOf sdd:EARSPattern ;
-    rdfs:label "Ubiquitous Pattern" .
-
-sdd:EventDrivenPattern a owl:Class ;
-    rdfs:subClassOf sdd:EARSPattern ;
-    rdfs:label "Event-Driven Pattern" .
-
-sdd:StateDrivenPattern a owl:Class ;
-    rdfs:subClassOf sdd:EARSPattern ;
-    rdfs:label "State-Driven Pattern" .
-
-sdd:UnwantedPattern a owl:Class ;
-    rdfs:subClassOf sdd:EARSPattern ;
-    rdfs:label "Unwanted Pattern" .
-
-sdd:OptionalPattern a owl:Class ;
-    rdfs:subClassOf sdd:EARSPattern ;
-    rdfs:label "Optional Pattern" .
-
-# === プロパティ定義 ===
-
-sdd:implements a owl:ObjectProperty ;
-    rdfs:domain sdd:Design ;
-    rdfs:range sdd:Requirement ;
-    rdfs:label "implements" .
-
-sdd:realizedBy a owl:ObjectProperty ;
-    rdfs:domain sdd:Requirement ;
-    rdfs:range sdd:Code ;
-    rdfs:label "realizedBy" .
-
-sdd:testedBy a owl:ObjectProperty ;
-    rdfs:domain sdd:Code ;
-    rdfs:range sdd:Test ;
-    rdfs:label "testedBy" .
-
-sdd:hasPattern a owl:ObjectProperty ;
-    rdfs:domain sdd:Requirement ;
-    rdfs:range sdd:EARSPattern ;
-    rdfs:label "hasPattern" .
-
-sdd:priority a owl:DatatypeProperty ;
-    rdfs:domain sdd:Requirement ;
-    rdfs:range xsd:string ;
-    rdfs:label "priority" .
-```
-
-### 5.4 推論ルール
-
-```turtle
-@prefix sdd: <http://musubix.dev/sdd#> .
-@prefix rule: <http://musubix.dev/rules#> .
-
-# トレーサビリティ推論
-rule:TraceabilityInference a rule:Rule ;
-    rule:condition """
-        ?req a sdd:Requirement .
-        ?des sdd:implements ?req .
-        ?code sdd:realizes ?des .
-    """ ;
-    rule:conclusion """
-        ?req sdd:realizedBy ?code .
-    """ .
-
-# テストカバレッジ推論
-rule:TestCoverageInference a rule:Rule ;
-    rule:condition """
-        ?code a sdd:Code .
-        ?test sdd:tests ?code .
-        ?code sdd:realizes ?des .
-        ?des sdd:implements ?req .
-    """ ;
-    rule:conclusion """
-        ?req sdd:hasCoverage true .
-    """ .
-
-# 依存関係推移閉包
-rule:TransitiveDependency a rule:Rule ;
-    rule:condition """
-        ?a sdd:dependsOn ?b .
-        ?b sdd:dependsOn ?c .
-    """ ;
-    rule:conclusion """
-        ?a sdd:transitivelyDependsOn ?c .
-    """ .
-```
-
-### 5.5 使用例
-
-```typescript
-import { SDDOntology } from '@nahisaho/musubix-sdd-ontology';
-
-const ontology = new SDDOntology();
-
-// オントロジーをN3Storeにロード
-const store = await ontology.load();
-
-// 推論ルールを適用
-await ontology.applyRules(store);
-
-// 要件に対するトレーサビリティ検証
-const coverage = await ontology.checkTraceability(store, 'REQ-001');
-```
-
----
-
-## 6. 学習フロー統合
-
-### 6.1 全体フロー
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   Complete Learning Flow                     │
-└─────────────────────────────────────────────────────────────┘
-
-1. [Input] Code Changes
-       │
-       ▼
-2. [Pattern MCP] Extract patterns from code
-       │
-       ├─── AST Analysis
-       ├─── Feature Extraction  
-       └─── Pattern Detection
-       │
-       ▼
-3. [Ontology MCP] Map patterns to ontology
-       │
-       ├─── Triple Generation
-       ├─── Schema Validation
-       └─── Consistency Check
-       │
-       ▼
-4. [Wake-Sleep] Consolidate and optimize
-       │
-       ├─── Wake: Update Knowledge
-       └─── Sleep: Compress & Prune
-       │
-       ▼
-5. [SDD Ontology] Apply inference rules
-       │
-       ├─── Traceability Inference
-       ├─── Coverage Analysis
-       └─── Quality Metrics
-       │
-       ▼
-6. [Output] Updated Knowledge Graph
-```
-
-### 6.2 統合API
-
-```typescript
-import { LearningSystem } from '@nahisaho/musubix-core';
-
-const learningSystem = new LearningSystem({
-  patternMCP: patternMCP,
-  ontologyMCP: ontologyMCP,
-  wakeSleep: wakeSleepCycle,
-  sddOntology: sddOntology,
-});
-
-// コード変更から学習
-await learningSystem.learnFromCode({
-  files: ['src/user-service.ts'],
-  context: 'user-authentication',
-});
-
-// フィードバックから学習
-await learningSystem.learnFromFeedback({
-  patternId: 'pattern-123',
-  feedback: 'accept',  // 'accept' | 'reject' | 'modify'
-  comment: 'Good pattern for DI',
-});
-
-// 推奨パターン取得
-const recommendations = await learningSystem.getRecommendations({
-  context: 'implementing-user-service',
-  maxResults: 5,
-});
-```
-
----
-
-## 7. CLI コマンド
-
-```bash
-# 学習ダッシュボード
-npx musubix learn status
-
-# パターン操作
-npx musubix learn patterns
-npx musubix learn add-pattern <name>
-npx musubix learn remove-pattern <id>
-
-# フィードバック
-npx musubix learn feedback <id>
-
-# 推奨
-npx musubix learn recommend
-
-# Wake-Sleepサイクル
-npx musubix learn wake
-npx musubix learn sleep
-npx musubix learn decay
-
-# データ管理
-npx musubix learn export --output patterns.json
-npx musubix learn import patterns.json
-
-# オントロジー
-npx musubix ontology validate -f knowledge.ttl
-npx musubix ontology check-circular -f knowledge.ttl
-npx musubix ontology stats -f knowledge.ttl
-```
-
----
-
-## 8. 設定
-
-### 8.1 環境変数
-
-| 変数名 | 説明 | デフォルト |
-|--------|------|-----------|
-| `MUSUBIX_LEARNING_PATH` | 学習データパス | `~/.musubix/learning` |
-| `MUSUBIX_PATTERN_THRESHOLD` | パターン登録閾値 | `0.8` |
-| `MUSUBIX_WAKE_INTERVAL` | Wake間隔（秒） | `3600` |
-| `MUSUBIX_SLEEP_AFTER_WAKE` | Wake後自動Sleep | `true` |
-
-### 8.2 設定ファイル
-
-`learning.config.json`:
-
-```json
-{
-  "patterns": {
-    "extractionThreshold": 0.7,
-    "compressionThreshold": 0.8,
-    "minOccurrences": 3,
-    "retentionDays": 90
-  },
-  "wakeSleep": {
-    "wakeInterval": 3600,
-    "sleepAfterWake": true,
-    "observers": ["file-system", "git-changes"]
-  },
-  "ontology": {
-    "schemaPath": "./schema",
-    "rulesPath": "./rules",
-    "inferenceEnabled": true
-  }
-}
-```
-
----
-
-## 9. 関連ドキュメント
-
-| ドキュメント | 説明 |
-|-------------|------|
-| [MUSUBIX-Overview.md](MUSUBIX-Overview.md) | 全体概要 |
-| [MUSUBIX-Core.md](MUSUBIX-Core.md) | Coreパッケージ |
-| [MUSUBIX-YATA.md](MUSUBIX-YATA.md) | YATAシステム |
-| [API-REFERENCE.md](API-REFERENCE.md) | APIリファレンス |
-
----
-
-**© 2026 MUSUBIX Project**