musubix2 0.2.0 → 0.3.1

package/.github/copilot-instructions.md

@@ -0,0 +1,155 @@
+# MUSUBIX2 — Specification Driven Development System
+
+## プロジェクト概要
+
+MUSUBIX2 はニューロシンボリック AI コーディングシステムの SDD（Specification Driven Development）基盤である。
+TypeScript / Node.js 20+ / ESM のモノレポ構成で、25 パッケージを npm workspaces で管理する。
+
+## アーキテクチャ原則
+
+| 原則 | 説明 |
+|------|------|
+| **ライブラリファースト** | 各機能を独立パッケージとして設計。アプリ依存を排除 |
+| **CLIファースト** | 全機能に Commander.js ベースの CLI インターフェースを提供 |
+| **テストファースト** | Red→Green→Blue サイクル。Vitest カバレッジ 80% 以上 |
+| **関心の分離** | 4層: Domain / Application / Infrastructure / Interface |
+| **依存性逆転** | インターフェースによる抽象化。具象への直接依存を禁止 |
+| **Git Native** | 全永続化データを JSON / YAML / Markdown 形式で保存 |
+
+## 9条憲法（不可侵）
+
+| 条項 | 原則 | 検証手段 |
+|------|------|----------|
+| Article I | ライブラリファースト | constitution-enforcer |
+| Article II | CLI インターフェース | constitution-enforcer |
+| Article III | テストファースト | test-engineer |
+| Article IV | EARS 形式 | requirements-analyst |
+| Article V | トレーサビリティ | traceability-auditor |
+| Article VI | プロジェクトメモリ | steering/ 参照 |
+| Article VII | デザインパターン文書化 | design-generator |
+| Article VIII | ADR 記録 | design-generator |
+| Article IX | 品質ゲート | test-engineer |
+
+## SDD ワークフロー（5フェーズ）
+
+```
+Phase 1: Requirements → Phase 2: Design → Phase 3: Tasks → Phase 4: Implementation → Phase 5: Complete
+```
+
+- **Phase 遷移には前フェーズの承認が必須**（REQ-SDD-002a/b/c）
+- 各 Phase で品質ゲートを通過すること（REQ-SDD-003）
+
+## ディレクトリ構成
+
+```
+src/
+├── packages/
+│   ├── core/                  # @nahisaho/musubix-core
+│   ├── knowledge/             # @musubix/knowledge
+│   ├── decisions/             # @musubix/decisions
+│   ├── policy/                # @musubix/policy
+│   ├── codegraph/             # @nahisaho/musubix-codegraph
+│   ├── dfg/                   # @nahisaho/musubix-dfg
+│   ├── formal-verify/         # @nahisaho/musubix-formal-verify
+│   ├── lean/                  # @nahisaho/musubix-lean
+│   ├── security/              # @nahisaho/musubix-security
+│   ├── workflow-engine/       # @nahisaho/musubix-workflow-engine
+│   ├── skill-manager/         # @nahisaho/musubix-skill-manager
+│   ├── agent-orchestrator/    # @nahisaho/musubix-agent-orchestrator
+│   ├── expert-delegation/     # @nahisaho/musubix-expert-delegation
+│   ├── assistant-axis/        # @nahisaho/musubix-assistant-axis
+│   ├── mcp-server/            # @nahisaho/musubix-mcp-server
+│   ├── sdd-ontology/          # @nahisaho/musubix-sdd-ontology
+│   ├── ontology-mcp/          # @nahisaho/musubix-ontology-mcp
+│   ├── neural-search/         # @nahisaho/musubix-neural-search
+│   ├── wake-sleep/            # @nahisaho/musubix-wake-sleep
+│   ├── library-learner/       # @nahisaho/musubix-library-learner
+│   ├── synthesis/             # @nahisaho/musubix-synthesis
+│   ├── pattern-mcp/           # @nahisaho/musubix-pattern-mcp
+│   ├── deep-research/         # @nahisaho/musubix-deep-research
+│   ├── musubi/                # @nahisaho/musubi
+│   └── musubix/               # musubix (umbrella)
+├── steering/
+│   ├── product.ja.md
+│   ├── structure.ja.md
+│   ├── tech.ja.md
+│   ├── rules/constitution.md
+│   └── project.yml
+├── .github/
+│   ├── copilot-instructions.md
+│   └── skills/
+├── docker/
+├── virtual-projects/
+└── testing/
+```
+
+## パッケージ内部構成（4層）
+
+```
+packages/<name>/
+├── src/
+│   ├── domain/           # ドメインモデル、インターフェース
+│   ├── application/      # ユースケース、サービス
+│   ├── infrastructure/   # 外部アダプター、ファイルI/O
+│   └── interface/
+│       └── cli/          # Commander.js コマンド
+├── tests/
+├── package.json
+└── tsconfig.json
+```
+
+## コーディング規約
+
+- **言語**: TypeScript 5.3+ / ESM (`type: "module"`)
+- **ビルド**: `tsc -b` インクリメンタルビルド
+- **テスト**: Vitest
+- **リンター**: ESLint
+- **CLI**: Commander.js, `registerXCommand(program)` パターン
+- **エラー**: `ActionableError` + `GracefulDegradation`（CircuitBreaker, retryWithBackoff）
+- **リポジトリ**: `IRepository` / `ISearchableRepository` / `IPaginatedRepository`
+- **ファクトリ**: `createInMemoryRepository` 等
+
+## EARS 要件構文
+
+全要件は EARS（Easy Approach to Requirements Syntax）形式で記述する:
+
+| パターン | 構文 |
+|----------|------|
+| UBIQUITOUS | THE システム SHALL... |
+| EVENT-DRIVEN | WHEN \<event\>, THE システム SHALL... |
+| STATE-DRIVEN | WHILE \<state\>, THE システム SHALL... |
+| UNWANTED | THE システム SHALL NOT... |
+| OPTIONAL | WHERE \<feature\>, THE システム SHALL... |
+| COMPLEX | IF \<condition\>, THEN THE システム SHALL... |
+
+## 仕様文書
+
+- **要件定義書**: `references/musubix2/REQ-MUSUBIX2-001.md` (v1.5, 69 要件)
+- **設計書**: `references/musubix2/DES-MUSUBIX2-001.md` (v1.5, 69 DES 仕様)
+- **実装計画**: `references/musubix2/PLAN-MUSUBIX2-001.md` (77 タスク, 8 フェーズ)
+
+## オーケストレーション
+
+SDD ワークフローのルーティングとフェーズ管理は `skills/orchestrator/SKILL.md` を参照。
+全スキル一覧と起動条件はそこに定義されている。
+
+## Review Orchestration (Cross-Model Review)
+
+SDD アーティファクトの品質保証には `review-orchestrator` スキルを使用する。
+詳細は `skills/review-orchestrator/SKILL.md` を参照。
+
+1. **交互レビュー**: opus-4.6 → gpt-5.4 → opus-4.6 → ... (エラー0まで)
+2. **最終合意**: 両モデルが同時にPASSすること
+3. **実装許可**: requirements, design, plan 全てが承認済みであること
+
+`ReviewOrchestrator` クラス（`@musubix2/agent-orchestrator` パッケージ）が
+レビュープロセスのオーケストレーションを担当する。
+
+## Steering 参照ルール
+
+全スキル実行前に `steering/` を参照すること:
+- `product.ja.md` — プロダクトコンテキスト
+- `structure.ja.md` — アーキテクチャパターン
+- `tech.ja.md` — 技術スタック
+- `rules/constitution.md` — 9条憲法
+- `project.yml` — プロジェクト設定

package/.github/skills/code-generator/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: code-generator
+description: >
+  設計仕様からテンプレートベースのコード生成、ドメインスキャフォールド、
+  静的解析、ステータス遷移分析を実行する。4層アーキテクチャ準拠。
+  Use when generating code from design specs, scaffolding domain packages,
+  running static analysis, or starting SDD Phase 4 implementation.
+license: MIT
+version: "1.0.0"
+triggers:
+  - コード生成
+  - スキャフォールド
+  - 静的解析
+  - Phase 4 開始
+  - codegen
+---
+
+# Code Generator
+
+設計仕様から 4層アーキテクチャ準拠のコードを生成するスキル。
+SDD ワークフロー Phase 4（Implementation）の中核。
+
+## 前提条件
+
+- Phase 3（Tasks）が承認済みであること
+- `steering/` を参照済みであること
+- 設計文書（`storage/specs/DES-*.md`）が存在すること
+
+## ワークフロー
+
+### 1. コード生成
+
+```
+WHEN ユーザーがコード生成を要求する:
+1. DES 仕様から TypeScript インターフェースを抽出
+2. CodeGenerator.generate() でテンプレートベース生成
+3. 4層構成で出力:
+   - domain/     → インターフェース、エンティティ、値オブジェクト
+   - application/ → ユースケース、サービス
+   - infrastructure/ → アダプター、ファイル I/O
+   - interface/cli/ → Commander.js コマンド
+4. EARS 要件 ID をコメントとしてリンク
+```
+
+**CLI**: `npx musubix codegen generate <design-file>`
+
+### 2. ドメインスキャフォールド
+
+```
+WHEN ユーザーが新規パッケージのスキャフォールドを要求する:
+1. ScaffoldGenerator で3モードから選択:
+   - minimal: domain/ + tests/ のみ
+   - standard: 4層 + package.json + tsconfig.json
+   - full: standard + CLI + README + CHANGELOG
+2. ディレクトリ構造を生成
+3. package.json に workspace 参照を追加
+```
+
+**CLI**: `npx musubix codegen scaffold <package-name> [--mode minimal|standard|full]`
+
+### 3. 静的解析
+
+```
+WHEN ユーザーが静的解析を要求する:
+1. StaticAnalyzer で複雑度・結合度を計測
+2. QualityMetricsCalculator でメトリクスを算出
+3. codegraph の ASTParser と連携
+```
+
+**CLI**: `npx musubix codegen analyze <path>`
+
+### 4. ステータス遷移分析
+
+```
+WHEN ユーザーがステータス遷移の分析を要求する:
+1. StatusTransitionGenerator でドメインモデルの状態遷移を抽出
+2. 状態遷移図（Mermaid stateDiagram）を生成
+3. 不正遷移の検出
+```
+
+**CLI**: `npx musubix codegen status <entity>`
+
+## パッケージ構成テンプレート
+
+```
+packages/<name>/
+├── src/
+│   ├── domain/
+│   │   ├── entities/
+│   │   ├── value-objects/
+│   │   └── interfaces/
+│   ├── application/
+│   │   └── services/
+│   ├── infrastructure/
+│   │   └── adapters/
+│   └── interface/
+│       └── cli/
+│           └── commands.ts    # registerXCommand(program)
+├── tests/
+│   ├── domain/
+│   ├── application/
+│   └── integration/
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## CLI コマンド登録パターン
+
+```typescript
+import { Command } from 'commander';
+
+export function registerXCommand(program: Command): void {
+  const cmd = program.command('x');
+  cmd.command('subcommand')
+    .description('...')
+    .option('--flag <value>', '...')
+    .action(async (options) => {
+      // implementation
+    });
+}
+```
+
+## 品質ゲート
+
+- [ ] 生成コードが `tsc --noEmit` でエラーなし
+- [ ] 4層アーキテクチャに準拠（domain が infrastructure に依存しない）
+- [ ] CLI コマンドが `registerXCommand` パターンに従う
+- [ ] EARS 要件 ID がコード内コメントにリンク
+- [ ] package.json の依存が workspace プロトコルを使用
+
+## Gotchas
+
+1. **ESM 必須**: `type: "module"` を package.json に設定。`import` 文に `.js` 拡張子を付けること（TypeScript でもビルド後のパスを指定）。
+2. **依存性逆転の徹底**: `domain/` 内で `infrastructure/` の具象クラスを import してはならない。必ずインターフェースを経由。
+3. **ActionableError の使用**: 標準 Error ではなく `ActionableError` を使用し、ユーザーへの修正提案を含める。

package/.github/skills/constitution-enforcer/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: constitution-enforcer
+description: >
+  MUSUBIX2 の9条憲法（CONST-001〜009）への準拠を検証する。
+  PolicyEngine による自動チェック、NonNegotiablesEngine による違反ブロック、
+  BalanceRuleEngine による 90/10 ルール適用を提供。
+  Use when validating constitution compliance, checking policy violations,
+  running governance audits, or blocking non-compliant changes.
+license: MIT
+version: "1.0.0"
+triggers:
+  - 憲法チェック
+  - ポリシー検証
+  - constitution
+  - ガバナンス
+  - 品質ゲート
+  - policy
+---
+
+# Constitution Enforcer
+
+MUSUBIX2 の9条憲法（CONST-001〜009）への準拠を検証するスキル。
+全 Article の不可侵性を保証し、違反を即時ブロックする。
+
+## 前提条件
+
+- `steering/rules/constitution.md` が存在すること
+- `steering/project.yml` が存在すること
+
+## 9条憲法
+
+| 条項 | ポリシーID | 原則 | 検証内容 |
+|------|-----------|------|----------|
+| Article I | CONST-001 | ライブラリファースト | パッケージが独立して利用可能か |
+| Article II | CONST-002 | CLI インターフェース | 全機能に CLI が提供されているか |
+| Article III | CONST-003 | テストファースト | テストが先に書かれているか |
+| Article IV | CONST-004 | EARS 形式 | 全要件が EARS 構文に準拠しているか |
+| Article V | CONST-005 | トレーサビリティ | REQ↔DES↔Code↔Test の 100% 追跡 |
+| Article VI | CONST-006 | プロジェクトメモリ | steering/ が参照されているか |
+| Article VII | CONST-007 | デザインパターン文書化 | パターン使用時に文書化されているか |
+| Article VIII | CONST-008 | ADR 記録 | 重要な設計決定に ADR があるか |
+| Article IX | CONST-009 | 品質ゲート | Phase 遷移時にゲートを通過しているか |
+
+## ワークフロー
+
+### 1. 全条項チェック
+
+```
+WHEN ユーザーがポリシー検証を要求する:
+1. PolicyEngine で全9条を順次検証
+2. NonNegotiablesEngine で違反をブロック
+3. 各条項の PASS/FAIL と詳細理由を出力
+4. 違反がある場合、修正提案を生成
+```
+
+**CLI**: `npx musubix policy validate`
+
+### 2. 個別条項チェック
+
+```
+WHEN ユーザーが特定条項の検証を要求する:
+1. PolicyEngine で指定条項のみ検証
+2. 詳細レポートを出力
+```
+
+**CLI**: `npx musubix policy check <article-number>`
+
+### 3. ポリシー一覧・詳細
+
+```
+WHEN ユーザーがポリシー情報を要求する:
+1. 全9条の一覧を表示
+2. 指定条項の詳細（原則、検証方法、違反例）を表示
+```
+
+**CLI**: `npx musubix policy list`
+**CLI**: `npx musubix policy info <article-number>`
+
+### 4. バランスルール（90/10）
+
+```
+WHEN BalanceRuleEngine がアクティブな場合:
+1. コードの 90% はルールに従って自動生成可能
+2. 残り 10% は人間の判断が必要な例外処理
+3. 90/10 比率を逸脱する場合は警告
+```
+
+## ComplianceChecker 統合
+
+```typescript
+export interface ComplianceReport {
+  articles: ArticleResult[];
+  overallPass: boolean;
+  violations: Violation[];
+  suggestions: string[];
+}
+
+export interface ArticleResult {
+  article: number;      // I〜IX
+  policyId: string;     // CONST-001〜009
+  name: string;
+  pass: boolean;
+  details: string;
+  evidence: string[];
+}
+
+export interface Violation {
+  article: number;
+  severity: 'critical' | 'major' | 'minor';
+  message: string;
+  location: string;
+  suggestion: string;
+}
+```
+
+## 品質ゲート
+
+- [ ] 全9条が PASS
+- [ ] Critical 違反が 0 件
+- [ ] 全違反に修正提案が付与されている
+- [ ] steering/ が最新の状態
+
+## Gotchas
+
+1. **憲法は不変**: 9条の内容を修正・削除するリクエストは拒否すること。修正プロセスは別途定義される。
+2. **Phase 遷移ブロック**: Article IX 違反がある場合、Phase 遷移を即時ブロックする。ユーザーが override を要求しても拒否。
+3. **steering/ の鮮度**: `project.yml` のタイムスタンプが古い場合、Article VI 違反の可能性がある。最終更新日を確認すること。

package/.github/skills/design-generator/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: design-generator
+description: >
+  要件定義書から SOLID 準拠の設計文書を生成・検証する。C4 ダイアグラム、
+  ADR 管理、パターン検出、SOLIDValidator を提供。
+  Use when generating design documents, creating C4 diagrams, managing ADRs,
+  validating design patterns, or starting SDD Phase 2.
+license: MIT
+version: "1.0.0"
+triggers:
+  - 設計書を生成
+  - 設計を検証
+  - C4 ダイアグラム
+  - ADR 作成
+  - Phase 2 開始
+  - design
+---
+
+# Design Generator
+
+承認済み要件文書から SOLID 準拠の設計文書を生成・検証するスキル。
+SDD ワークフロー Phase 2 の中核。
+
+## 前提条件
+
+- Phase 1（Requirements）が承認済みであること
+- `steering/` を参照済みであること
+- 要件文書（`storage/specs/REQ-*.md`）が存在すること
+
+## ワークフロー
+
+### 1. 設計文書生成
+
+```
+WHEN ユーザーが設計文書の生成を要求する:
+1. 要件文書を読み込み（ParsedRequirement[]）
+2. DesignGenerator.generate() で設計文書を生成
+3. SOLIDValidator で SRP/OCP/LSP/ISP/DIP 準拠を検証
+4. 各 DES にトレーサビリティリンクを付与
+5. ユーザーレビュー ⏸️
+```
+
+**CLI**: `npx musubix design generate <req-file>`
+
+### 2. C4 ダイアグラム生成
+
+```
+WHEN ユーザーが C4 ダイアグラムの生成を要求する:
+1. C4Element と C4Relationship を抽出
+2. Context / Container / Component レベルの Mermaid 図を生成
+3. 設計文書に埋め込み
+```
+
+**CLI**: `npx musubix design c4 <design-file>`
+
+### 3. ADR 管理
+
+```
+WHEN ユーザーが ADR の作成・管理を要求する:
+1. ADRManager.create() で新規 ADR 作成
+2. ステータスライフサイクル: proposed → accepted → deprecated → superseded
+3. ADRManager.search() で全文検索
+4. ADRManager.index() でインデクシング
+```
+
+**CLI**: `npx musubix decisions create|list|get|accept|deprecate|search|index`
+
+### 4. 設計検証
+
+```
+WHEN ユーザーが設計文書の検証を要求する:
+1. PatternDetector でデザインパターンを検出
+2. SOLID 原則への準拠を検証
+3. 要件との対応漏れを検出
+```
+
+**CLI**: `npx musubix design validate <design-file>`
+
+## 設計文書フォーマット
+
+各 DES 仕様は以下の構成:
+
+```markdown
+### DES-XXX-NNN: タイトル
+
+**トレーサビリティ**: REQ-XXX-NNN
+**パッケージ**: `package-name`
+
+**設計概要**:
+（自然言語の説明）
+
+（TypeScript インターフェース / Mermaid 図）
+
+**CLI契約**: `npx musubix ...`
+```
+
+## ADR フォーマット
+
+```markdown
+# ADR-NNN: タイトル
+
+**ステータス**: proposed | accepted | deprecated | superseded
+**日付**: YYYY-MM-DD
+
+## Context
+（決定の背景）
+
+## Decision
+（決定内容）
+
+## Consequences
+（影響と結果）
+```
+
+## 品質ゲート
+
+- [ ] 全 DES が少なくとも1つの REQ にトレース可能
+- [ ] TypeScript インターフェースが定義されている
+- [ ] CLI 契約が明記されている
+- [ ] SOLID 原則への違反がない
+- [ ] 重要な設計決定に ADR が作成されている
+
+## Gotchas
+
+1. **DES と REQ の N:M 関係**: 1つの DES が複数の REQ を参照する場合がある。逆も同様。全方向のリンクを維持すること。
+2. **Mermaid 記法の制限**: classDiagram で `?` nullable 表記を使う場合、TypeScript 側の `| undefined` と一致させること。
+3. **ADR のステータス管理**: `accept` と `deprecate` は状態遷移。直接 `superseded` にはできない（必ず `deprecated` を経由）。