musubix 3.4.3 → 3.4.7

package/steering/structure.ja.md

@@ -0,0 +1,503 @@
+# Project Structure
+
+**Project**: MUSUBIX
+**Last Updated**: 2026-01-04
+**Version**: 1.1.15
+
+---
+
+## Architecture Pattern
+
+**Primary Pattern**: {{ARCHITECTURE_PATTERN}}
+
+> [Description of the architecture pattern used in this project]
+> Examples: Monorepo with Library-First, Microservices, Modular Monolith, Serverless
+
+---
+
+## Architecture Layers (Language-Agnostic)
+
+The following layer definitions apply regardless of programming language:
+
+### Layer 1: Domain / Core
+
+**Purpose**: Business logic and domain models
+**Rules**:
+
+- MUST NOT depend on any other layer
+- Contains: Entities, Value Objects, Domain Services, Domain Events
+- No framework dependencies, no I/O
+
+**Language Examples**:
+| Language | Location | Pattern |
+|----------|----------|---------|
+| TypeScript | `lib/{feature}/domain/` | Classes/Types |
+| Rust | `{crate}/src/domain/` | Structs + Traits |
+| Python | `src/{pkg}/domain/` | Dataclasses |
+| Go | `internal/domain/` | Structs + Interfaces |
+| Java | `src/main/.../domain/` | Classes + Records |
+
+### Layer 2: Application / Use Cases
+
+**Purpose**: Orchestrate domain logic, implement use cases
+**Rules**:
+
+- Depends only on Domain layer
+- Contains: Application Services, Commands, Queries, DTOs
+- No direct I/O (uses ports/interfaces)
+
+**Language Examples**:
+| Language | Location | Pattern |
+|----------|----------|---------|
+| TypeScript | `lib/{feature}/application/` | Service classes |
+| Rust | `{crate}/src/application/` | Impl blocks |
+| Python | `src/{pkg}/application/` | Service functions |
+| Go | `internal/app/` | Service structs |
+| Java | `src/main/.../application/` | @Service classes |
+
+### Layer 3: Infrastructure / Adapters
+
+**Purpose**: External integrations (DB, APIs, messaging)
+**Rules**:
+
+- Depends on Application layer (implements ports)
+- Contains: Repositories, API Clients, Message Publishers
+- All I/O operations here
+
+**Language Examples**:
+| Language | Location | Pattern |
+|----------|----------|---------|
+| TypeScript | `lib/{feature}/infrastructure/` | Repository impls |
+| Rust | `{crate}/src/infrastructure/` | Trait impls |
+| Python | `src/{pkg}/infrastructure/` | Repository classes |
+| Go | `internal/infra/` | Interface impls |
+| Java | `src/main/.../infrastructure/` | @Repository classes |
+
+### Layer 4: Interface / Presentation
+
+**Purpose**: Entry points (CLI, API, Web UI)
+**Rules**:
+
+- Depends on Application layer
+- Contains: Controllers, CLI handlers, API routes
+- Input validation and response formatting
+
+**Language Examples**:
+| Language | Location | Pattern |
+|----------|----------|---------|
+| TypeScript | `app/api/` or `cli/` | Route handlers |
+| Rust | `{crate}/src/api/` or `cli/` | Axum handlers |
+| Python | `src/{pkg}/api/` or `cli/` | FastAPI routes |
+| Go | `cmd/` or `internal/api/` | HTTP handlers |
+| Java | `src/main/.../api/` | @RestController |
+
+### Layer Dependency Rules
+
+```
+┌─────────────────────────────────────────┐
+│        Interface / Presentation         │ ← Entry points
+├─────────────────────────────────────────┤
+│        Application / Use Cases          │ ← Orchestration
+├─────────────────────────────────────────┤
+│        Infrastructure / Adapters        │ ← I/O & External
+├─────────────────────────────────────────┤
+│            Domain / Core                │ ← Pure business logic
+└─────────────────────────────────────────┘
+
+Dependency Direction: ↓ (outer → inner)
+Domain layer has NO dependencies
+```
+
+---
+
+## Directory Organization
+
+### Root Structure
+
+```
+MUSUBIX/
+├── lib/                  # Reusable libraries (Article I: Library-First)
+├── app/                  # Application code (Next.js, etc.)
+├── api/                  # API routes/controllers
+├── components/           # UI components
+├── services/             # Business logic services
+├── tests/                # Test suites
+├── docs/                 # Documentation
+├── storage/              # SDD artifacts
+│   ├── specs/            # Requirements, design, tasks
+│   ├── changes/          # Delta specifications (brownfield)
+│   └── validation/       # Validation reports
+├── steering/             # Project memory (this directory)
+│   ├── structure.md      # This file
+│   ├── tech.md           # Technology stack
+│   ├── product.md        # Product context
+│   └── rules/            # Constitutional governance
+├── templates/            # Document templates
+└── [Other directories]
+```
+
+---
+
+## Library-First Pattern (Article I)
+
+All features begin as independent libraries in `lib/`.
+
+### Library Structure
+
+Each library follows this structure:
+
+```
+lib/{{feature}}/
+├── src/
+│   ├── index.ts          # Public API exports
+│   ├── service.ts        # Business logic
+│   ├── repository.ts     # Data access
+│   ├── types.ts          # TypeScript types
+│   ├── errors.ts         # Custom errors
+│   └── validators.ts     # Input validation
+├── tests/
+│   ├── service.test.ts   # Unit tests
+│   ├── repository.test.ts # Integration tests (real DB)
+│   └── integration.test.ts # E2E tests
+├── cli.ts                # CLI interface (Article II)
+├── package.json          # Library metadata
+├── tsconfig.json         # TypeScript config
+└── README.md             # Library documentation
+```
+
+### Library Guidelines
+
+- **Independence**: Libraries MUST NOT depend on application code
+- **Public API**: All exports via `src/index.ts`
+- **Testing**: Independent test suite
+- **CLI**: All libraries expose CLI interface (Article II)
+
+---
+
+## Application Structure
+
+### Application Organization
+
+```
+app/
+├── (auth)/               # Route groups (Next.js App Router)
+│   ├── login/
+│   │   └── page.tsx
+│   └── register/
+│       └── page.tsx
+├── dashboard/
+│   └── page.tsx
+├── api/                  # API routes
+│   ├── auth/
+│   │   └── route.ts
+│   └── users/
+│       └── route.ts
+├── layout.tsx            # Root layout
+└── page.tsx              # Home page
+```
+
+### Application Guidelines
+
+- **Library Usage**: Applications import from `lib/` modules
+- **Thin Controllers**: API routes delegate to library services
+- **No Business Logic**: Business logic belongs in libraries
+
+---
+
+## Component Organization
+
+### UI Components
+
+```
+components/
+├── ui/                   # Base UI components (shadcn/ui)
+│   ├── button.tsx
+│   ├── input.tsx
+│   └── card.tsx
+├── auth/                 # Feature-specific components
+│   ├── LoginForm.tsx
+│   └── RegisterForm.tsx
+├── dashboard/
+│   └── StatsCard.tsx
+└── shared/               # Shared components
+    ├── Header.tsx
+    └── Footer.tsx
+```
+
+### Component Guidelines
+
+- **Composition**: Prefer composition over props drilling
+- **Types**: All props typed with TypeScript
+- **Tests**: Component tests with React Testing Library
+
+---
+
+## Database Organization
+
+### Schema Organization
+
+```
+prisma/
+├── schema.prisma         # Prisma schema
+├── migrations/           # Database migrations
+│   ├── 001_create_users_table/
+│   │   └── migration.sql
+│   └── 002_create_sessions_table/
+│       └── migration.sql
+└── seed.ts               # Database seed data
+```
+
+### Database Guidelines
+
+- **Migrations**: All schema changes via migrations
+- **Naming**: snake_case for tables and columns
+- **Indexes**: Index foreign keys and frequently queried columns
+
+---
+
+## Test Organization
+
+### Test Structure
+
+```
+tests/
+├── unit/                 # Unit tests (per library)
+│   └── auth/
+│       └── service.test.ts
+├── integration/          # Integration tests (real services)
+│   └── auth/
+│       └── login.test.ts
+├── e2e/                  # End-to-end tests
+│   └── auth/
+│       └── user-flow.test.ts
+└── fixtures/             # Test data and fixtures
+    └── users.ts
+```
+
+### Test Guidelines
+
+- **Test-First**: Tests written BEFORE implementation (Article III)
+- **Real Services**: Integration tests use real DB/cache (Article IX)
+- **Coverage**: Minimum 80% coverage
+- **Naming**: `*.test.ts` for unit, `*.integration.test.ts` for integration
+
+---
+
+## Documentation Organization
+
+### Documentation Structure
+
+```
+docs/
+├── architecture/         # Architecture documentation
+│   ├── c4-diagrams/
+│   └── adr/              # Architecture Decision Records
+├── api/                  # API documentation
+│   ├── openapi.yaml
+│   └── graphql.schema
+├── guides/               # Developer guides
+│   ├── getting-started.md
+│   └── contributing.md
+└── runbooks/             # Operational runbooks
+    ├── deployment.md
+    └── troubleshooting.md
+```
+
+---
+
+## SDD Artifacts Organization
+
+### Storage Directory
+
+```
+storage/
+├── specs/                # Specifications
+│   ├── auth-requirements.md
+│   ├── auth-design.md
+│   ├── auth-tasks.md
+│   └── payment-requirements.md
+├── changes/              # Delta specifications (brownfield)
+│   ├── add-2fa.md
+│   └── upgrade-jwt.md
+├── features/             # Feature tracking
+│   ├── auth.json
+│   └── payment.json
+└── validation/           # Validation reports
+    ├── auth-validation-report.md
+    └── payment-validation-report.md
+```
+
+---
+
+## Naming Conventions
+
+### File Naming
+
+- **TypeScript**: `PascalCase.tsx` for components, `camelCase.ts` for utilities
+- **React Components**: `PascalCase.tsx` (e.g., `LoginForm.tsx`)
+- **Utilities**: `camelCase.ts` (e.g., `formatDate.ts`)
+- **Tests**: `*.test.ts` or `*.spec.ts`
+- **Constants**: `SCREAMING_SNAKE_CASE.ts` (e.g., `API_ENDPOINTS.ts`)
+
+### Directory Naming
+
+- **Features**: `kebab-case` (e.g., `user-management/`)
+- **Components**: `kebab-case` or `PascalCase` (consistent within project)
+
+### Variable Naming
+
+- **Variables**: `camelCase`
+- **Constants**: `SCREAMING_SNAKE_CASE`
+- **Types/Interfaces**: `PascalCase`
+- **Enums**: `PascalCase`
+
+---
+
+## Integration Patterns
+
+### Library → Application Integration
+
+```typescript
+// ✅ CORRECT: Application imports from library
+import { AuthService } from '@/lib/auth';
+
+const authService = new AuthService(repository);
+const result = await authService.login(credentials);
+```
+
+```typescript
+// ❌ WRONG: Library imports from application
+// Libraries must NOT depend on application code
+import { AuthContext } from '@/app/contexts/auth'; // Violation!
+```
+
+### Service → Repository Pattern
+
+```typescript
+// Service layer (business logic)
+export class AuthService {
+  constructor(private repository: UserRepository) {}
+
+  async login(credentials: LoginRequest): Promise<LoginResponse> {
+    // Business logic here
+    const user = await this.repository.findByEmail(credentials.email);
+    // ...
+  }
+}
+
+// Repository layer (data access)
+export class UserRepository {
+  constructor(private prisma: PrismaClient) {}
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.prisma.user.findUnique({ where: { email } });
+  }
+}
+```
+
+---
+
+## Deployment Structure
+
+### Deployment Units
+
+**Projects** (independently deployable):
+
+1. MUSUBIX - Main application
+
+> ⚠️ **Simplicity Gate (Article VII)**: Maximum 3 projects initially.
+> If adding more projects, document justification in Phase -1 Gate approval.
+
+### Environment Structure
+
+```
+environments/
+├── development/
+│   └── .env.development
+├── staging/
+│   └── .env.staging
+└── production/
+    └── .env.production
+```
+
+---
+
+## Multi-Language Support
+
+### Language Policy
+
+- **Primary Language**: English
+- **Documentation**: English first (`.md`), then Japanese (`.ja.md`)
+- **Code Comments**: English
+- **UI Strings**: i18n framework
+
+### i18n Organization
+
+```
+locales/
+├── en/
+│   ├── common.json
+│   └── auth.json
+└── ja/
+    ├── common.json
+    └── auth.json
+```
+
+---
+
+## Version Control
+
+### Branch Organization
+
+- `main` - Production branch
+- `develop` - Development branch
+- `feature/*` - Feature branches
+- `hotfix/*` - Hotfix branches
+- `release/*` - Release branches
+
+### Commit Message Convention
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+**Example**:
+
+```
+feat(auth): implement user login (REQ-AUTH-001)
+
+Add login functionality with email and password authentication.
+Session created with 24-hour expiry.
+
+Closes REQ-AUTH-001
+```
+
+---
+
+## Constitutional Compliance
+
+This structure enforces:
+
+- **Article I**: Library-first pattern in `lib/`
+- **Article II**: CLI interfaces per library
+- **Article III**: Test structure supports Test-First
+- **Article VI**: Steering files maintain project memory
+
+---
+
+## Changelog
+
+### Version 1.1 (Planned)
+
+- [Future changes]
+
+---
+
+**Last Updated**: 2026-01-01
+**Maintained By**: {{MAINTAINER}}

package/steering/tech.ja.md

@@ -0,0 +1,208 @@
+# Technology Stack
+
+**Project**: MUSUBIX
+**Last Updated**: 2026-01-04
+**Version**: 1.1.15
+**Status**: Production Ready
+
+---
+
+## Overview
+
+MUSUBIXはニューロシンボリックAIコーディングシステムであり、LLM（Large Language Model）とシンボリック推論（知識グラフ）を統合しています。
+
+## Core Technologies
+
+| カテゴリ | 技術 | バージョン | 状態 |
+|---------|------|-----------|------|
+| 言語 | TypeScript | 5.3+ | ✅ 採用 |
+| ランタイム | Node.js | 20.0.0+ | ✅ 採用 |
+| パッケージマネージャ | npm | 10.0.0+ | ✅ 採用 |
+| ビルドシステム | tsc | 5.3+ | ✅ 採用 |
+| テストフレームワーク | Vitest | 4.0+ | ✅ 採用 |
+| リンター | ESLint | 9.0+ | ✅ 採用 |
+
+## Architecture
+
+### パッケージ構成（モノレポ）
+
+```
+packages/
+├── core/           # @nahisaho/musubix-core (v1.1.15)
+├── mcp-server/     # @nahisaho/musubix-mcp-server (v1.1.15)
+├── yata-client/    # @nahisaho/musubix-yata-client (v1.1.15)
+└── musubi/         # @nahisaho/musubi (v1.1.15) - Alias wrapper
+```
+
+### Core Package モジュール
+
+| モジュール | 役割 | 主要機能 |
+|-----------|------|---------|
+| `auth/` | 認証・認可 | JWT/OAuth管理 |
+| `cli/` | CLIインターフェース | コマンドライン処理 |
+| `codegen/` | コード生成・解析 | テンプレート生成、静的解析、セキュリティスキャン |
+| `design/` | 設計 | パターン検出、C4モデル、ADR生成 |
+| `error/` | エラーハンドリング | 構造化エラー、リカバリー |
+| `explanation/` | 説明生成 | 推論グラフ、可視化 |
+| `learning/` | 自己学習 | フィードバック収集、パターン抽出 |
+| `requirements/` | 要件分析 | EARS検証、オントロジーマッピング |
+| `traceability/` | トレーサビリティ | アーティファクト追跡、カバレッジ分析 |
+| `validators/` | 検証 | EARS検証器 |
+
+## Domain Support
+
+| カテゴリ | ドメイン数 | コンポーネント数 |
+|---------|-----------|-----------------|
+| 合計 | 62 | ~430 |
+
+### 対応ドメイン一覧
+
+- **汎用**: general
+- **業種特化**: healthcare, banking, insurance, realestate, hotel, restaurant, retail, ecommerce, logistics, manufacturing, construction, agriculture, agritech
+- **専門サービス**: legal, accounting, hr, recruitment, marketing, crm
+- **教育・学習**: education, elearning, library
+- **エンターテイメント**: game, music, media, cinema, museum, streaming, podcast, news
+- **交通・物流**: travel, aviation, railway, shipping, vehicle, parking
+- **通信・IT**: telecom, iot, security
+- **医療・福祉**: pharmacy, veterinary, caregiving, childcare
+- **イベント・冠婚葬祭**: event, ticketing, wedding, funeral
+- **その他**: fitness, sports, beauty, petcare, rental, laundry, subscription, crowdfunding, auction, charity, government, election, survey, energy, environment, archive, social, property, warehouse
+
+## Key Features
+
+### 1. EARS検証器（Symbolic Reasoning）
+
+5つのEARSパターンをサポート（**Markdownブロッククォート形式対応** v1.1.9+）：
+
+| パターン | 構文 | 信頼度ボーナス |
+|---------|------|---------------|
+| Event-driven | `WHEN <trigger>, THE <system> SHALL <action>` | +0.25 |
+| State-driven | `WHILE <state>, THE <system> SHALL <action>` | +0.25 |
+| Unwanted | `THE <system> SHALL NOT <behavior>` | +0.20 |
+| Optional | `WHERE <feature>, THE <system> SHALL <action>` | +0.20 |
+| Ubiquitous | `THE <system> SHALL <action>` | +0.00 |
+
+**最適化機能**:
+- 早期終了（高信頼度≥0.85で即座にマッチ）
+- 事前チェック（"shall"キーワードの存在確認）
+
+### 2. トレーサビリティ管理
+
+**カバレッジ計算（重み付け平均）**:
+- 要件: 30%
+- 設計: 20%
+- コード: 30%
+- テスト: 20%
+
+**最適化機能**:
+- リンクインデックス（O(1)検索）
+- アーティファクト型インデックス
+
+### 3. アーティファクトステータス
+
+```typescript
+type ArtifactStatus =
+  | 'draft'       // 初期作成状態
+  | 'active'      // アクティブ開発中
+  | 'approved'    // レビュー承認済み
+  | 'implemented' // コード実装完了
+  | 'verified'    // テスト・検証完了
+  | 'deprecated'  // 非推奨
+  | 'deleted';    // 削除予定
+```
+
+### 4. ニューロシンボリック統合ルール（REQ-INT-002）
+
+| シンボリック結果 | ニューラル信頼度 | 最終決定 |
+|-----------------|-----------------|---------|
+| invalid | - | ニューラル結果を棄却 |
+| valid | ≥0.8 | ニューラル結果を採用 |
+| valid | <0.8 | シンボリック結果を優先 |
+
+## Development Commands
+
+```bash
+# 依存関係インストール
+npm install
+
+# 全パッケージビルド
+npm run build
+
+# テスト実行
+npm run test
+
+# コード品質
+npm run lint
+npm run typecheck
+
+# クリーンアップ
+npm run clean
+```
+
+## Performance Benchmarks
+
+| 機能 | 処理速度 | 備考 |
+|------|---------|------|
+| EARS検証（単一要件） | <1ms | 早期終了最適化 |
+| パターンマッチング | <5ms | 信頼度計算含む |
+| トレーサビリティリンク検索 | O(1) | インデックス利用 |
+| C4モデル生成 | <10ms | 11要素、6関係 |
+| 全テスト（459件） | ~1.0s | Vitest実行 |
+
+## Self-Learning System (v1.1.10)
+
+### ベストプラクティスCLI
+
+```bash
+# 一覧表示
+npx musubix learn bp-list
+
+# 詳細表示（コード例付き）
+npx musubix learn bp-show BP-CODE-001
+
+# カテゴリ別フィルタ
+npx musubix learn best-practices --category code
+```
+
+### 学習済みパターン（17件）
+
+| ID | 名称 | 信頼度 | ソース |
+|----|------|--------|--------|
+| BP-CODE-001 | Entity Input DTO | 95% | P07-08 |
+| BP-CODE-002 | Date-based ID Format | 90% | P07-08 |
+| BP-CODE-003 | Value Objects | 90% | P08 |
+| BP-CODE-004 | Function-based Value Objects | 95% | P13-14 |
+| BP-CODE-005 | Result Type | 95% | P13-14 |
+| BP-DESIGN-001 | Status Transition Map | 95% | P08, P13-14 |
+| BP-DESIGN-002 | Repository Async Pattern | 85% | P08 |
+| BP-DESIGN-003 | Service Layer with DI | 90% | P07-08 |
+| BP-DESIGN-004 | Optimistic Locking | 90% | P10 |
+| BP-DESIGN-005 | AuditService | 85% | P09-10 |
+| BP-DESIGN-006 | Entity Counter Reset | 95% | P13-14 |
+| BP-DESIGN-007 | Expiry Time Logic | 90% | P14 |
+| BP-TEST-001 | Test Counter Reset | 95% | P07 |
+| BP-TEST-002 | Verify API Before Test | 80% | P08 |
+| BP-TEST-003 | Vitest ESM Configuration | 85% | P07 |
+| BP-TEST-004 | Result Type Test Pattern | 95% | P13-14 |
+| BP-TEST-005 | Status Transition Testing | 90% | P14 |
+
+### コード生成テンプレート（12タイプ）
+
+| タイプ | 説明 | 追加バージョン |
+|--------|------|----------------|
+| class | クラス定義 | v1.0.0 |
+| interface | インターフェース | v1.0.0 |
+| function | 関数 | v1.0.0 |
+| module | モジュール | v1.0.0 |
+| test | テストファイル | v1.0.0 |
+| api-endpoint | APIエンドポイント | v1.0.0 |
+| model | データモデル | v1.0.0 |
+| repository | リポジトリ | v1.0.0 |
+| service | サービス層 | v1.0.0 |
+| controller | コントローラ | v1.0.0 |
+| value-object | Value Object (function-based) | v1.1.10 |
+| entity | エンティティ (status transition, counter reset) | v1.1.10 |
+
+---
+
+*Last Updated: 2026-01-04 by MUSUBIX v1.1.15*