musubix 1.1.15 → 1.3.1

package/docs/USER-GUIDE.ja.md

@@ -15,10 +15,11 @@
 9. [検証フェーズ](#検証フェーズ)
 10. [自己学習システム](#自己学習システム)
 11. [C4コード生成](#c4コード生成)
-12. [MCPサーバー連携](#mcpサーバー連携)
-13. [YATA知識グラフ](#yata知識グラフ)
-14. [ベストプラクティス](#ベストプラクティス)
-15. [トラブルシューティング](#トラブルシューティング)
+12. [シンボリック推論](#シンボリック推論) *(v1.2.0)*
+13. [MCPサーバー連携](#mcpサーバー連携)
+14. [YATA知識グラフ](#yata知識グラフ)
+15. [ベストプラクティス](#ベストプラクティス)
+16. [トラブルシューティング](#トラブルシューティング)
 
 ---
 
@@ -633,6 +634,114 @@ export function createAuthService(): IAuthService {
 
 ---
 
+## シンボリック推論
+
+*(v1.2.0 新機能)*
+
+### 概要
+
+シンボリック推論は、形式検証と知識グラフベースの推論を適用して、LLM出力を強化します。このハイブリッドアプローチ（ニューロシンボリック）は、ニューラルネットワークの創造性とシンボリックロジックの精度を組み合わせます。
+
+### 主要コンポーネント
+
+| コンポーネント | 説明 |
+|--------------|------|
+| `SemanticCodeFilterPipeline` | コード品質のためのLLM出力フィルタリング |
+| `HallucinationDetector` | ハルシネーション（幻覚）出力の検出と防止 |
+| `EarsToFormalSpecConverter` | EARS要件からZ3形式仕様への変換 |
+| `Z3Adapter` | 形式検証のためのZ3ソルバーインターフェース |
+| `QualityGateValidator` | 17品質ゲートチェックに対する検証 |
+
+### 使用方法
+
+#### セマンティックコードフィルタリング
+
+```typescript
+import { SemanticCodeFilterPipeline } from '@nahisaho/musubix-core';
+
+const pipeline = new SemanticCodeFilterPipeline({
+  enableHallucinationDetection: true,
+  maxRetries: 3
+});
+
+const result = await pipeline.filter({
+  code: generatedCode,
+  context: { language: 'typescript', domain: 'authentication' }
+});
+
+if (result.isValid) {
+  console.log('コードが検証に合格:', result.filteredCode);
+} else {
+  console.log('問題が検出されました:', result.issues);
+}
+```
+
+#### ハルシネーション検出
+
+```typescript
+import { HallucinationDetector } from '@nahisaho/musubix-core';
+
+const detector = new HallucinationDetector();
+
+const analysis = await detector.analyze({
+  response: llmResponse,
+  groundTruth: knownFacts,
+  context: projectContext
+});
+
+console.log('信頼度スコア:', analysis.confidence);
+console.log('ハルシネーションリスク:', analysis.risks);
+```
+
+#### EARSから形式仕様への変換
+
+```typescript
+import { EarsToFormalSpecConverter } from '@nahisaho/musubix-core';
+
+const converter = new EarsToFormalSpecConverter();
+
+const formalSpec = await converter.convert({
+  earsRequirement: 'WHEN user clicks login, THE system SHALL authenticate within 2 seconds',
+  requirementId: 'REQ-AUTH-001'
+});
+
+// Z3互換の仕様を返す
+console.log(formalSpec.z3Expression);
+```
+
+#### 品質ゲート検証
+
+```typescript
+import { QualityGateValidator } from '@nahisaho/musubix-core';
+
+const validator = new QualityGateValidator();
+
+const gateResult = await validator.validate({
+  requirements: requirementsList,
+  designs: designDocuments,
+  tasks: taskList
+});
+
+console.log('全ゲート合格:', gateResult.allPassed);
+console.log('ゲート詳細:', gateResult.gates);
+// EARS準拠、トレーサビリティなど17の品質チェック
+```
+
+### 品質ゲートチェック
+
+| ゲート | 説明 |
+|--------|------|
+| EARS準拠 | 要件がEARSパターンに従っているか |
+| 一意のID | すべての成果物に一意の識別子があるか |
+| トレーサビリティ | 完全なトレーサビリティチェーンが存在するか |
+| 設計カバレッジ | すべての要件に設計があるか |
+| タスクカバレッジ | すべての設計にタスクがあるか |
+| 孤立なし | 孤立した要件やタスクがないか |
+| 完全性 | すべての必須フィールドが存在するか |
+| ... | その他10の品質チェック |
+
+---
+
 ## MCPサーバー連携
 
 ### MCPサーバーの起動
@@ -945,6 +1054,6 @@ const client = createYATAClient({
 
 ---
 
-**バージョン**: 1.0.12  
-**最終更新**: 2026-01-03  
+**バージョン**: 1.3.0  
+**最終更新**: 2026-01-05  
 **MUSUBIX Project**

package/docs/USER-GUIDE.md

@@ -13,10 +13,11 @@
 5. [SDD Workflow](#sdd-workflow)
 6. [Self-Learning System](#self-learning-system)
 7. [C4 Code Generation](#c4-code-generation)
-8. [MCP Server Integration](#mcp-server-integration)
-9. [YATA Integration](#yata-integration)
-10. [Best Practices](#best-practices)
-11. [Troubleshooting](#troubleshooting)
+8. [Symbolic Reasoning](#symbolic-reasoning) *(v1.2.0)*
+9. [MCP Server Integration](#mcp-server-integration)
+10. [YATA Integration](#yata-integration)
+11. [Best Practices](#best-practices)
+12. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -593,6 +594,114 @@ Add to `.cursor/mcp.json`:
 
 ---
 
+## Symbolic Reasoning
+
+*(v1.2.0 New Feature)*
+
+### Overview
+
+Symbolic reasoning enhances LLM outputs by applying formal verification and knowledge-graph backed reasoning. This hybrid approach (Neuro-Symbolic) combines the creativity of neural networks with the precision of symbolic logic.
+
+### Key Components
+
+| Component | Description |
+|-----------|-------------|
+| `SemanticCodeFilterPipeline` | Filter LLM outputs for code quality |
+| `HallucinationDetector` | Detect and prevent hallucinated outputs |
+| `EarsToFormalSpecConverter` | Convert EARS requirements to formal Z3 specifications |
+| `Z3Adapter` | Interface with Z3 solver for formal verification |
+| `QualityGateValidator` | Validate against 17 quality gate checks |
+
+### Usage
+
+#### Semantic Code Filtering
+
+```typescript
+import { SemanticCodeFilterPipeline } from '@nahisaho/musubix-core';
+
+const pipeline = new SemanticCodeFilterPipeline({
+  enableHallucinationDetection: true,
+  maxRetries: 3
+});
+
+const result = await pipeline.filter({
+  code: generatedCode,
+  context: { language: 'typescript', domain: 'authentication' }
+});
+
+if (result.isValid) {
+  console.log('Code passed validation:', result.filteredCode);
+} else {
+  console.log('Issues found:', result.issues);
+}
+```
+
+#### Hallucination Detection
+
+```typescript
+import { HallucinationDetector } from '@nahisaho/musubix-core';
+
+const detector = new HallucinationDetector();
+
+const analysis = await detector.analyze({
+  response: llmResponse,
+  groundTruth: knownFacts,
+  context: projectContext
+});
+
+console.log('Confidence score:', analysis.confidence);
+console.log('Hallucination risks:', analysis.risks);
+```
+
+#### EARS to Formal Specification
+
+```typescript
+import { EarsToFormalSpecConverter } from '@nahisaho/musubix-core';
+
+const converter = new EarsToFormalSpecConverter();
+
+const formalSpec = await converter.convert({
+  earsRequirement: 'WHEN user clicks login, THE system SHALL authenticate within 2 seconds',
+  requirementId: 'REQ-AUTH-001'
+});
+
+// Returns Z3-compatible specification
+console.log(formalSpec.z3Expression);
+```
+
+#### Quality Gate Validation
+
+```typescript
+import { QualityGateValidator } from '@nahisaho/musubix-core';
+
+const validator = new QualityGateValidator();
+
+const gateResult = await validator.validate({
+  requirements: requirementsList,
+  designs: designDocuments,
+  tasks: taskList
+});
+
+console.log('All gates passed:', gateResult.allPassed);
+console.log('Gate details:', gateResult.gates);
+// 17 quality checks including EARS compliance, traceability, etc.
+```
+
+### Quality Gate Checks
+
+| Gate | Description |
+|------|-------------|
+| EARS Compliance | Requirements follow EARS patterns |
+| Unique IDs | All artifacts have unique identifiers |
+| Traceability | Full traceability chain exists |
+| Design Coverage | All requirements have designs |
+| Task Coverage | All designs have tasks |
+| No Orphans | No orphaned requirements or tasks |
+| Completeness | All required fields are present |
+| ... | And 10 more quality checks |
+
+---
+
 ## YATA Integration
 
 ### What is YATA?
@@ -785,6 +894,6 @@ const client = createYATAClient({
 
 ---
 
-**Version**: 1.0.12  
-**Last Updated**: 2026-01-03  
+**Version**: 1.3.0  
+**Last Updated**: 2026-01-05  
 **MUSUBIX Project**