@sk8metal/michi-cli 0.8.1 → 0.8.3

package/docs/michi-development/testing/manual-verification-troubleshooting.md

@@ -0,0 +1,122 @@
+# Michi 手動検証フロー - トラブルシューティング
+
+**親ドキュメント**: [manual-verification-flow.md](./manual-verification-flow.md)
+
+---
+
+## トラブルシューティング
+
+### 問題1: cc-sddのインストールが失敗する
+
+**症状:**
+
+```
+Error: Unknown option: --cline
+```
+
+**原因:**
+指定したAI開発ツール用のフラグがcc-sddに存在しない
+
+**解決方法:**
+
+1. cc-sddの最新版を確認: `npm info cc-sdd`
+2. サポートされているフラグを確認: `npx cc-sdd@latest --help`
+3. 対応していない場合は、他のツール（Cursor または Claude Code）を使用
+
+### 問題2: Michiセットアップが既存ファイルと競合する
+
+**症状:**
+
+```
+Warning: File already exists: .cursor/commands/michi-confluence-sync.md
+```
+
+**原因:**
+既にMichiがセットアップされている、または手動で同名ファイルが作成されている
+
+**解決方法:**
+
+```bash
+# 既存のMichiファイルを削除してから再セットアップ
+rm -rf .cursor/commands/michi-*.md
+michi setup-existing --cursor --lang ja
+```
+
+### 問題3: phase:run コマンドが feature を見つけられない
+
+**症状:**
+
+```
+Error: Feature 'java-calculator-webapp' not found
+```
+
+**原因:**
+`.kiro/specs/java-calculator-webapp/` ディレクトリまたは `spec.json` が存在しない
+
+**解決方法:**
+
+1. AIコマンドで初期化されているか確認
+   ```bash
+   ls -la .kiro/specs/java-calculator-webapp/spec.json
+   ```
+2. 存在しない場合は、AIコマンド `/kiro:spec-init` を再実行
+
+### 問題4: validate:phase が失敗する
+
+**症状:**
+
+```
+Error: Validation failed for phase test-type-selection
+```
+
+**原因:**
+必要なファイルが生成されていない、またはフォーマットが不正
+
+**解決方法:**
+
+1. 該当フェーズの出力ファイルを確認
+   ```bash
+   cat .kiro/specs/java-calculator-webapp/test-types.md
+   ```
+2. ファイルが空または不正な場合は、フェーズを再実行
+   ```bash
+   michi phase:run java-calculator-webapp test-type-selection
+   ```
+
+### 問題5: 絶対パスコマンドが動作しない（Pattern B）
+
+**症状:**
+
+```
+Error: Cannot find module '~/Work/git/michi/src/cli.ts'
+```
+
+**原因:**
+シェルがチルダ `~` を展開していない
+
+**解決方法:**
+
+```bash
+# チルダの代わりに $HOME を使用
+npx tsx $HOME/Work/git/michi/src/cli.ts phase:run java-calculator-webapp test-type-selection
+
+# または完全な絶対パスを使用
+npx tsx /Users/yourusername/Work/git/michi/src/cli.ts phase:run java-calculator-webapp test-type-selection
+```
+
+### 問題6: 自動テストスクリプトが途中で失敗する
+
+**症状:**
+自動テストスクリプト（pre-publish または test:package）が途中でエラーで終了する
+
+**原因:**
+スクリプトは `set -e` を使用しており、最初のエラーで即座に終了する
+
+**解決方法:**
+
+1. エラーメッセージを確認
+2. 該当するコマンドを手動で実行して詳細を確認
+3. 問題を修正してから再実行
+
+---
+

package/docs/user-guide/getting-started/setup.md

@@ -28,48 +28,30 @@ michi --help
 
 > **開発者向け**: Michiの開発に貢献したい場合や、最新の開発版を使用したい場合は [開発環境セットアップガイド](../contributing/development.md) を参照してください。
 
-## Step 2: cc-sddのインストール
 
-**重要**: 作業するプロジェクトのルートディレクトリで実行してください。
-
-cc-sddは、Michiの仕様駆動開発ワークフローのコアフレームワークです。
+## Step 2: cc-sddとMichiのセットアップ
 
-```bash
-# 作業プロジェクトのルートディレクトリに移動
-cd /path/to/your-project
+Michiは、cc-sddをコアフレームワークとして使用します。セットアップは2段階で行います:
 
-# Cursor IDE を使用する場合
-npx cc-sdd@latest --lang ja --cursor
+1. **cc-sdd**: AI駆動開発ワークフローの基盤
+2. **Michi**: Confluence/JIRA連携などの拡張機能
 
-# Claude Code を使用する場合
-npx cc-sdd@latest --lang ja --claude
+詳細な手順については、以下のセクションを参照してください:
 
-# Gemini CLI を使用する場合
-npx cc-sdd@latest --lang ja --gemini
+### クイックスタート（3ステップ）
 
-# Codex CLI を使用する場合
-npx cc-sdd@next --lang ja --codex
+```bash
+# Step 1: cc-sddで標準ファイル生成
+npx cc-sdd@latest --cursor --lang ja
 
-# GitHub Copilot を使用する場合
-npx cc-sdd@next --lang ja --copilot
+# Step 2: Michi固有ファイルを追加
+npx @sk8metal/michi-cli setup-existing --cursor --lang ja
 
-# Windsurf IDE を使用する場合
-npx cc-sdd@next --lang ja --windsurf
+# Step 3: 環境設定
+npm run setup:interactive
 ```
 
-**実行内容:**
-- `.kiro/settings/` にテンプレート作成
-- `.cursor/commands/kiro/` または `.claude/commands/kiro/` にコマンド作成
-- `CLAUDE.md` にプロジェクト設定追加
-
-**cc-sdd準拠アーキテクチャ（Issue #35）:**
-- Michiは**単一の英語テンプレート + プレースホルダー**でcc-sdd準拠を実現
-- `templates/` ディレクトリからCursor/Claude両環境に対応
-- プレースホルダー（`{{LANG_CODE}}`, `{{DEV_GUIDELINES}}` 等）をAIが実行時に解釈
-
-
-詳細: [cc-sdd公式ドキュメント](https://github.com/gotalab/cc-sdd/blob/main/tools/cc-sdd/README_ja.md)
-
+👉 **詳細な手順**: [推奨ワークフロー（cc-ssd + Michi）](#step-25-推奨ワークフローcc-ssd--michi) を参照してください。
 
 ## Step 2.5: 推奨ワークフロー（cc-sdd + Michi）
 

package/docs/user-guide/guides/multi-repo-guide.md

@@ -432,11 +432,282 @@ michi multi-repo:list
 michi multi-repo:list
 ```
 
+## 既存ユーザーのためのマイグレーションガイド
+
+このセクションは、既存のMichiユーザーがMulti-Repo機能を導入する際の手順を説明します。
+
+### 概要
+
+Multi-Repo機能はMichiに新しく追加された機能です。既存のMichi機能に影響を与えず、追加のコマンド群として提供されます。
+
+**主な特徴**:
+- **後方互換性**: 既存のMichiコマンドとワークフローに影響なし
+- **オプトイン**: Multi-Repo機能を使用する場合のみ、設定を追加
+- **自動マイグレーション**: 初回使用時に自動的に設定ファイルが拡張される
+
+### 変更点（v0.5.0 → v1.0.0）
+
+#### 1. config.jsonスキーマの拡張
+
+`.michi/config.json` に新しいフィールド `multiRepoProjects` が追加されます。
+
+**変更前（v0.5.0）**:
+```json
+{
+  "confluence": { ... },
+  "jira": { ... },
+  "workflow": { ... },
+  "validation": { ... },
+  "atlassian": { ... },
+  "project": { ... }
+}
+```
+
+**変更後（v1.0.0）**:
+```json
+{
+  "confluence": { ... },
+  "jira": { ... },
+  "workflow": { ... },
+  "validation": { ... },
+  "atlassian": { ... },
+  "project": { ... },
+  "multiRepoProjects": []
+}
+```
+
+重要: `multiRepoProjects` フィールドが存在しない場合、Michiは自動的に空配列 `[]` として扱います。手動で追加する必要はありません。
+
+#### 2. 新規コマンドの追加
+
+以下の6つのコマンドが追加されます：
+
+| コマンド | Phase | 説明 |
+|---------|-------|------|
+| `michi multi-repo:init` | 1 (MVP) | プロジェクト初期化 |
+| `michi multi-repo:add-repo` | 1 (MVP) | リポジトリ登録 |
+| `michi multi-repo:list` | 1 (MVP) | プロジェクト一覧表示 |
+| `michi multi-repo:ci-status` | 2 | CI結果集約 |
+| `michi multi-repo:test` | 2 | テスト実行 |
+| `michi multi-repo:confluence-sync` | 3 | Confluence同期 |
+
+#### 3. 環境変数の追加（オプション）
+
+**Phase 2機能を使用する場合**:
+```bash
+export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+**Phase 3機能を使用する場合**:
+```bash
+export ATLASSIAN_URL="https://your-company.atlassian.net"
+export ATLASSIAN_EMAIL="your-email@example.com"
+export ATLASSIAN_API_TOKEN="your-api-token"
+```
+
+注意: 既存のMichiでConfluence機能を使用している場合、これらの環境変数は既に設定されているため、追加の設定は不要です。
+
+### マイグレーション手順
+
+#### ステップ1: Michiをv1.0.0にアップグレード
+
+```bash
+npm install -g @sk8metal/michi-cli@latest
+```
+
+アップグレード後、バージョンを確認します。
+
+```bash
+michi --version
+# @sk8metal/michi-cli v1.0.0
+```
+
+#### ステップ2: 環境変数の設定（オプション）
+
+**Phase 2機能を使用する場合**:
+
+GitHub Personal Access Tokenを取得し、環境変数に設定します。
+
+GitHub Personal Access Tokenの取得方法:
+1. GitHubにログイン
+2. Settings → Developer settings → Personal access tokens → Tokens (classic)
+3. "Generate new token (classic)" をクリック
+4. 必要なスコープを選択:
+   - `repo`: プライベートリポジトリへのアクセス（推奨）
+   - `public_repo`: パブリックリポジトリのみへのアクセス
+   - `workflow`: GitHub Actionsへのアクセス（必須）
+5. トークンを生成してコピー
+
+**環境変数の設定**:
+```bash
+# ~/.bashrc または ~/.zshrc に追加
+export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+# 変更を反映
+source ~/.bashrc  # または source ~/.zshrc
+```
+
+**Phase 3機能を使用する場合**:
+
+既存のMichiでConfluence機能を使用している場合は、既に設定済みのため、この手順はスキップしてください。
+
+新規にConfluence機能を使用する場合は、[Confluenceセットアップガイド](../getting-started/setup-guide.md#confluence設定)を参照してください。
+
+#### ステップ3: Multi-Repoプロジェクトの初期化
+
+初めてMulti-Repo機能を使用する際に、自動的に `.michi/config.json` が拡張されます。
+
+```bash
+# プロジェクト初期化
+michi multi-repo:init my-multi-repo-project \
+  --jira MYPROJ \
+  --confluence-space MYSPACE
+```
+
+**実行結果**:
+```
+✅ Multi-Repoプロジェクトの初期化が完了しました
+
+プロジェクト情報:
+  名前: my-multi-repo-project
+  JIRAキー: MYPROJ
+  Confluenceスペース: MYSPACE
+
+作成されたディレクトリ:
+  docs/michi/my-multi-repo-project/
+  ├── overview/
+  │   ├── requirements.md
+  │   ├── architecture.md
+  │   └── multi-repo.md
+  ├── steering/
+  ├── tests/
+  └── docs/
+
+設定ファイルを更新しました: .michi/config.json
+```
+
+#### ステップ4: リポジトリの登録
+
+Multi-Repoプロジェクトにリポジトリを登録します。
+
+```bash
+# リポジトリ登録
+michi multi-repo:add-repo my-multi-repo-project \
+  --name backend \
+  --url https://github.com/your-org/backend \
+  --branch main
+
+michi multi-repo:add-repo my-multi-repo-project \
+  --name frontend \
+  --url https://github.com/your-org/frontend \
+  --branch main
+```
+
+#### ステップ5: 動作確認
+
+プロジェクト一覧を表示して、正常に登録されたことを確認します。
+
+```bash
+michi multi-repo:list
+```
+
+**実行結果**:
+```
+========================================
+Multi-Repo プロジェクト一覧
+========================================
+
+プロジェクト: my-multi-repo-project
+  JIRAキー: MYPROJ
+  Confluenceスペース: MYSPACE
+  作成日時: 2025-12-17T10:00:00+09:00
+  リポジトリ数: 2
+
+  リポジトリ:
+    1. backend
+       URL: https://github.com/your-org/backend
+       ブランチ: main
+
+    2. frontend
+       URL: https://github.com/your-org/frontend
+       ブランチ: main
+
+========================================
+合計プロジェクト数: 1
+========================================
+```
+
+### 既存機能への影響
+
+#### 影響なし
+
+以下の既存Michi機能は、Multi-Repo機能の追加によって**影響を受けません**。
+
+**Spec-Driven Developmentワークフロー**:
+```bash
+# 既存のワークフローは変更なし
+/kiro:spec-init "feature-name"
+/kiro:spec-requirements feature-name
+/kiro:spec-design feature-name
+/kiro:spec-tasks feature-name
+/kiro:spec-impl feature-name
+```
+
+**Confluence/JIRA統合**:
+```bash
+# 既存のConfluence/JIRAコマンドは変更なし
+michi confluence:sync
+michi jira:sync
+```
+
+**設定管理**:
+```bash
+# 既存の設定コマンドは変更なし
+michi config:validate
+michi migrate
+```
+
+既存の設定フィールド（`confluence`, `jira`, `workflow`, `validation`, `atlassian`, `project`）は変更されません。`multiRepoProjects` フィールドが追加されるのみです。
+
+#### 注意事項
+
+**ディレクトリ構造**:
+
+Multi-Repo機能は `docs/michi/{project-name}/` ディレクトリを使用します。既存のMichi機能と同じディレクトリ構造ですが、プロジェクト名が異なる場合は別のディレクトリが作成されます。
+
+```
+docs/
+├── michi/
+│   ├── my-feature/              # 既存のSpec-Driven Development用
+│   │   ├── overview/
+│   │   ├── steering/
+│   │   └── ...
+│   └── my-multi-repo-project/   # Multi-Repo用（新規）
+│       ├── overview/
+│       ├── steering/
+│       └── ...
+```
+
+**Confluence階層構造**:
+
+Multi-Repo機能でConfluence同期を使用する場合、以下の階層構造が作成されます。
+
+```
+Confluenceスペース (例: MYSPACE)
+└── my-multi-repo-project (親ページ)
+    ├── my-multi-repo-project - Requirements
+    ├── my-multi-repo-project - Architecture
+    ├── my-multi-repo-project - Sequence Diagrams
+    └── my-multi-repo-project - Test Strategy
+```
+
+既存のConfluenceページとは別の階層構造となるため、影響はありません。
+
 ## トラブルシューティング
 
-### GitHub Token未設定
+### 問題1: GITHUB_TOKEN が設定されていないエラー
 
-**症状**:
+**エラーメッセージ**:
 ```
 Error: GITHUB_TOKEN environment variable is not set
 ```
@@ -452,11 +723,11 @@ Error: GITHUB_TOKEN environment variable is not set
    ```
 3. コマンドを再実行
 
-### Confluence認証失敗
+### 問題2: Confluence認証エラー
 
-**症状**:
+**エラーメッセージ**:
 ```
-Error: Confluence authentication failed
+Error: Missing Confluence credentials in .env file
 ```
 
 **原因**:
@@ -474,65 +745,117 @@ Error: Confluence authentication failed
 2. URLが正しい形式か確認（`https://` で始まり、`.atlassian.net` で終わる）
 3. API Tokenを再作成して設定
 
-### レート制限超過
+### 問題3: プロジェクト名にパス区切り文字が含まれているエラー
 
-**症状**:
+**エラーメッセージ**:
 ```
-Error: GitHub API rate limit exceeded
+Error: Project name must not contain path traversal characters (/, \), relative path components (., ..), or control characters
 ```
 
 **原因**:
-GitHub APIのレート制限（5000リクエスト/時）を超えました。
+セキュリティ対策として、プロジェクト名にパス区切り文字（`/`, `\`）、相対パス（`.`, `..`）、制御文字が禁止されています。
 
-**対処法**:
-1. 1時間待機してから再実行
-2. キャッシュを活用（15分以内の再実行はキャッシュから取得）
-3. 複数のGitHub Tokenをローテーションで使用
+**解決方法**:
+
+プロジェクト名を変更して、以下の文字を含まないようにしてください。
+
+- パス区切り文字: `/`, `\`
+- 相対パス: `.`, `..`
+- 制御文字: `\x00`-`\x1F`, `\x7F`
+
+**例**:
+```bash
+# 不正な例
+michi multi-repo:init my/project  # スラッシュを含む
+michi multi-repo:init ../project  # 相対パスを含む
 
-### スクリプト未存在エラー
+# 正しい例
+michi multi-repo:init my-project
+michi multi-repo:init my_project
+michi multi-repo:init myproject
+```
+
+### 問題4: リポジトリURLが無効
 
-**症状**:
+**エラーメッセージ**:
 ```
-Error: Script not found: npm test:unit
+Error: Repository URL must be in GitHub format: https://github.com/{owner}/{repo}
 ```
 
 **原因**:
-`.michi/config.json` に登録されているテストスクリプトが存在しません。
+セキュリティ対策として、GitHub HTTPS URLのみが許可されています。
 
-**対処法**:
-1. `package.json` の `scripts` セクションを確認
-2. スクリプト名を修正:
-   ```json
-   {
-     "scripts": {
-       "test:unit": "vitest run tests/unit",
-       "lint": "eslint .",
-       "type-check": "tsc --noEmit"
-     }
-   }
-   ```
-3. `.michi/config.json` のスクリプト名を修正
+**解決方法**:
 
-### プロジェクトが見つからない
+リポジトリURLを以下の形式に変更してください。
 
-**症状**:
 ```
-Error: Project 'my-project' not found
+https://github.com/{owner}/{repo}
+```
+
+**例**:
+```bash
+# 不正な例
+--url git@github.com:your-org/repo.git  # SSH URL
+--url https://github.com/your-org/repo.git  # .git拡張子を含む
+--url http://github.com/your-org/repo  # HTTP (非セキュア)
+
+# 正しい例
+--url https://github.com/your-org/repo
+```
+
+### 問題5: GitHub API レート制限エラー
+
+**エラーメッセージ**:
+```
+Warning: GitHub API rate limit exceeded. Retrying after X seconds...
 ```
 
 **原因**:
-指定されたプロジェクト名が `.michi/config.json` に存在しません。
+GitHub API呼び出しがレート制限（5,000リクエスト/時間）に達した。
 
-**対処法**:
-1. プロジェクト名を確認:
-   ```bash
-   michi multi-repo:list
-   ```
-2. プロジェクト名のスペル、大文字小文字を確認
-3. 必要に応じてプロジェクトを初期化:
-   ```bash
-   michi multi-repo:init my-project --jira PROJ --confluence-space PROJ
-   ```
+**解決方法**:
+
+Michiは自動的にExponential Backoffで再試行します。以下の対策を検討してください。
+
+1. **待機**: 自動再試行が完了するまで待つ（最大3回再試行）
+2. **キャッシング活用**: CI結果は15分間キャッシュされるため、頻繁な実行を避ける
+3. **GitHub Enterprise**: より高いレート制限が必要な場合は、GitHub Enterpriseの使用を検討
+
+### 問題6: config.jsonが破損している
+
+**エラーメッセージ**:
+```
+Error: Failed to parse config: Unexpected token } in JSON at position X
+```
+
+**原因**:
+`.michi/config.json` が不正なJSON形式になっている。
+
+**解決方法**:
+
+1. バックアップが存在する場合、復元する
+
+```bash
+cp .michi/config.json.backup .michi/config.json
+```
+
+2. バックアップが存在しない場合、config.jsonを手動で修正する
+
+```bash
+# JSONリンターで構文エラーを確認
+cat .michi/config.json | jq .
+```
+
+3. それでも解決しない場合、config.jsonを再生成する
+
+```bash
+# 既存のconfig.jsonをバックアップ
+mv .michi/config.json .michi/config.json.broken
+
+# 新しいconfig.jsonを生成（Multi-Repoプロジェクトは失われる）
+michi config:validate
+```
 
 ## FAQ
 

package/docs/user-guide/reference/config.md

@@ -392,7 +392,7 @@ npx tsx scripts/utils/config-validator.ts
 
 ### 必須設定値エラー
 
-**症状**: 実行時に「設定値が不足しています」というエラーが表示される
+**症状**: 実行時に「設定値が不足しています」エラーが表示される
 
 **よくあるエラーケース**:
 

package/docs/user-guide/reference/security-test-payloads.md

@@ -0,0 +1,50 @@
+# セキュリティテスト - 一般的な攻撃ペイロード
+
+**親ドキュメント**: [../templates/test-specs/security-test-spec-template.md](../templates/test-specs/security-test-spec-template.md)
+
+このドキュメントでは、セキュリティテストで使用される一般的な攻撃ペイロードの例を示します。
+
+---
+
+## Appendix B: Common Attack Payloads
+
+### SQL Injection Payloads
+
+```sql
+' OR '1'='1' --
+' OR '1'='1' /*
+admin' --
+admin' #
+' UNION SELECT NULL, username, password FROM users --
+1'; DROP TABLE users; --
+```
+
+### XSS Payloads
+
+```html
+<script>alert('XSS')</script>
+<img src=x onerror=alert('XSS')>
+<svg onload=alert('XSS')>
+<iframe src="javascript:alert('XSS')">
+<body onload=alert('XSS')>
+```
+
+### Path Traversal Payloads
+
+```text
+../../etc/passwd
+....//....//etc/passwd
+..%2F..%2Fetc%2Fpasswd
+..%252F..%252Fetc%252Fpasswd
+```
+
+### LDAP Injection Payloads
+
+```text
+*)(uid=*))(|(uid=*
+admin)(&(password=*))
+*)(objectClass=*)
+```
+
+---
+