Verification & Quality Assurance

検証と品質保証のスキル

このスキルでできること

このスキルは、以下を通じてコードの品質と正確性を確保する、包括的な検証および品質保証システムを提供します。

• 真実性スコアリング：コード、エージェント、タスクの信頼性をリアルタイムで測定（0.0〜1.0 のスケール）
• 検証チェック：コードの正確性、セキュリティ、ベストプラクティスを自動検証
• 自動ロールバック：検証に失敗した変更を即座に元に戻します（デフォルトのしきい値：0.95）
• 品質メトリクス：傾向、信頼区間、改善状況の追跡を含む統計分析
• CI/CD との統合：継続的インテグレーションパイプラインへのエクスポート機能
• リアルタイム監視：継続的な検証に対応したライブダッシュボードと監視モード

提供済み機能と今後の構想。 実際に提供され、CI で実行される検証スタック（6 つのリグレッションガードジョブ、witness manifest、ツールの検出可能性監査）は実装済みで、プッシュごとに実行されます。このドキュメントの後半で説明する真実性スコアリング、自動ロールバック、WebSocket ダッシュボードは、一部が提供済み（ruflo verify が witness チェックを実行）で、一部が設計段階です。現在の確定情報として、以下の「CI ガード」セクションを参照してください。

CI ガード — 実際に提供されている機能（現状）

Ruflo のリグレッション保護は 3 層構成で、すべて公開前にチェックされます。確定情報は verification/README.md を参照してください。

層	内容	.github/workflows/v3-ci.yml の CI ジョブ	ADR
1 — インストール／動作スモークテスト	実際のビルドに対して、ユーザーから見える障害モードを検証	smoke-install-no-bsqlite（プリビルドがないプラットフォームでの npm install）、plugin-hooks-smoke（#1859/#1862 — フックフラグの解析）、mcp-protocol-smoke（#1874 — HTTP MCP のワイヤーフォーマット）、memory-import-smoke（#1883/#1884 — WSL パスとキーのサニタイズ）、mcp-roundtrip-smoke（#1889 のペアツールのラウンドトリップ + #1863 の cli-no-crash + ADR-095 G2 のコンセンサストランスポート）	ADR-102
1 — 検出可能性ゲート	すべての MCP ツールの説明で「ネイティブ機能ではなく、こちらを使うべきなのはどんなときか」に回答する必要があります	tool-descriptions-audit — scripts/audit-tool-descriptions.mjs、ベースラインは verification/mcp-tool-baseline.json（単調減少：noGuidance / tooShort / duplicates）	ADR-112
2 — 暗号学的 witness	ドキュメント化された各修正の重要なマーカーが dist に残っていることを検証。Ed25519 で署名し、OS ごとにバンドル	witness-verify（ubuntu/macos/windows）— plugins/ruflo-core/scripts/witness/verify.mjs で verification/<os>/manifest.md.json を検証	ADR-103
3 — 時系列履歴	リグレッションがいつ導入されたかを記録	verification/<os>/history.jsonl + history.mjs（summary / regressions / timeline）	ADR-103

ガードをローカルで実行する

# Tool-description discoverability audit (ADR-112)
node scripts/audit-tool-descriptions.mjs                       # fails if any baseline count rises
node scripts/audit-tool-descriptions.mjs --update-baseline     # lock the new floor after a fix lands

# Behavioral smokes (each builds what it needs; safe to run individually)
node plugins/ruflo-core/scripts/test-hooks.mjs "node $PWD/v3/@claude-flow/cli/bin/cli.js"
node plugins/ruflo-core/scripts/test-mcp-protocol.mjs
node plugins/ruflo-core/scripts/test-memory-import.mjs
node plugins/ruflo-core/scripts/test-mcp-roundtrips.mjs        # #1889 paired-tool round-trip
node plugins/ruflo-core/scripts/test-cli-no-crash.mjs          # #1863 unhandled-exception class
node plugins/ruflo-core/scripts/test-consensus-transport.mjs   # ADR-095 G2 consensus transport

# Witness manifest — regenerate + verify
node scripts/regen-witness.mjs
node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification/macos/manifest.md.json

# Temporal history
node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl summary
node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl regressions

新しいガードの追加

1. 動作スモークテスト → plugins/ruflo-core/scripts/test-<name>.mjs を作成します。パターン：まず静的な dist スキャンを行い（高速で必ず完了）、次に内部タイムアウトとプロセスレベルのウォッチドッグを備えた動作プローブを実行して、CI がハングしないようにします。v3-ci.yml の該当ジョブにステップを追加してください。
2. ベースラインを使用する静的ゲート → スキャンして違反をカウントし、カウントが verification/<name>-baseline.json の単調減少するベースラインを超えた場合に失敗する scripts/audit-<name>.mjs を作成します。--update-baseline に対応させてください。CI ジョブを追加し、publish のゲートにする場合は witness-verify の needs[] に組み込んでください。
3. ドキュメント化された修正のマーカー → verification/witness-fixes.json に { id, desc, file, marker } を追加し、node scripts/regen-witness.mjs を実行します。マーカーは修正によって特に作成される部分文字列でなければなりません（'function' のような一般的なパターンは使用しないでください）。

前提条件

• Ruflo がインストールされていること（npx ruflo@alpha）
• Git リポジトリ（ロールバック機能用）
• Node.js 18+（ダッシュボード機能用）
• @noble/ed25519（witness verifier 用のランタイム依存関係 1 つ。npm i @noble/ed25519）

クイックスタート

# View current truth scores
npx ruflo@alpha truth

# Run verification check
npx ruflo@alpha verify check

# Verify specific file with custom threshold
npx ruflo@alpha verify check --file src$app.js --threshold 0.98

# Rollback last failed verification
npx ruflo@alpha verify rollback --last-good

---

完全ガイド

真実性スコアリングシステム

Truth メトリクスの表示

コードベースとエージェントタスクに関する包括的な品質および信頼性メトリクスを表示します。

基本的な使用方法:

# View current truth scores (default: table format)
npx ruflo@alpha truth

# View scores for specific time period
npx ruflo@alpha truth --period 7d

# View scores for specific agent
npx ruflo@alpha truth --agent coder --period 24h

# Find files$tasks below threshold
npx ruflo@alpha truth --threshold 0.8

出力フォーマット:

# Table format (default)
npx ruflo@alpha truth --format table

# JSON for programmatic access
npx ruflo@alpha truth --format json

# CSV for spreadsheet analysis
npx ruflo@alpha truth --format csv

# HTML report with visualizations
npx ruflo@alpha truth --format html --export report.html

リアルタイム監視:

# Watch mode with live updates
npx ruflo@alpha truth --watch

# Export metrics automatically
npx ruflo@alpha truth --export .claude-flow$metrics$truth-$(date +%Y%m%d).json

Truth スコアダッシュボード

ダッシュボード出力の例:

📊 Truth Metrics Dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Truth Score: 0.947 ✅
Trend: ↗️ +2.3% (7d)

Top Performers:
  verification-agent   0.982 ⭐
  code-analyzer       0.971 ⭐
  test-generator      0.958 ✅

Needs Attention:
  refactor-agent      0.821 ⚠️
  docs-generator      0.794 ⚠️

Recent Tasks:
  task-456  0.991 ✅  "Implement auth"
  task-455  0.967 ✅  "Add tests"
  task-454  0.743 ❌  "Refactor API"

メトリクスの説明

Truth スコア (0.0〜1.0):

• 1.0-0.95: 優秀 ⭐ (本番環境対応)
• 0.94-0.85: 良好 ✅ (許容可能な品質)
• 0.84-0.75: 警告 ⚠️ (要注意)
• <0.75: 重大 ❌ (即時の対応が必要)

トレンドインジケーター:

• ↗️ 改善中 (ポジティブなトレンド)
• → 安定 (一貫したパフォーマンス)
• ↘️ 低下中 (品質の後退を検出)

統計:

• 平均スコア: すべての測定値の Truth スコアの平均
• 中央値スコア: 中央の値 (外れ値の影響を受けにくい)
• 標準偏差: スコアの一貫性 (低いほど一貫性が高い)
• 信頼区間: 測定値の統計的信頼性

検証チェック

検証の実行

コード、タスク、またはエージェントの出力に対して包括的な検証チェックを実行します。

ファイル検証:

# Verify single file
npx ruflo@alpha verify check --file src$app.js

# Verify directory recursively
npx ruflo@alpha verify check --directory src/

# Verify with auto-fix enabled
npx ruflo@alpha verify check --file src$utils.js --auto-fix

# Verify current working directory
npx ruflo@alpha verify check

タスク検証:

# Verify specific task output
npx ruflo@alpha verify check --task task-123

# Verify with custom threshold
npx ruflo@alpha verify check --task task-456 --threshold 0.99

# Verbose output for debugging
npx ruflo@alpha verify check --task task-789 --verbose

バッチ検証:

# Verify multiple files in parallel
npx ruflo@alpha verify batch --files "*.js" --parallel

# Verify with pattern matching
npx ruflo@alpha verify batch --pattern "src/**/*.ts"

# Integration test suite
npx ruflo@alpha verify integration --test-suite full

検証基準

検証システムは以下を評価します:

1. コードの正確性

   • 構文検証
   • 型チェック (TypeScript)
   • ロジックフロー分析
   • エラーハンドリングの完全性

2. ベストプラクティス

   • コードスタイルの遵守
   • SOLID 原則
   • デザインパターンの使用
   • モジュール性と再利用性

3. セキュリティ

   • 脆弱性スキャン
   • シークレットの検出
   • 入力検証
   • 認証$認可チェック

4. パフォーマンス

   • アルゴリズムの計算量
   • メモリ使用パターン
   • データベースクエリの最適化
   • バンドルサイズへの影響

5. ドキュメント

   • JSDoc/TypeDoc の完全性
   • README の正確性
   • API ドキュメント
   • コードコメントの品質

CI/CD 向け JSON 出力

# Get structured JSON output
npx ruflo@alpha verify check --json > verification.json

# Example JSON structure:
{
  "overallScore": 0.947,
  "passed": true,
  "threshold": 0.95,
  "checks": [
    {
      "name": "code-correctness",
      "score": 0.98,
      "passed": true
    },
    {
      "name": "security",
      "score": 0.91,
      "passed": false,
      "issues": [...]
    }
  ]
}

自動ロールバック

失敗した変更のロールバック

検証チェックに失敗した変更を自動的に元に戻します。

基本的なロールバック:

# Rollback to last known good state
npx ruflo@alpha verify rollback --last-good

# Rollback to specific commit
npx ruflo@alpha verify rollback --to-commit abc123

# Interactive rollback with preview
npx ruflo@alpha verify rollback --interactive

スマートロールバック:

# Rollback only failed files (preserve good changes)
npx ruflo@alpha verify rollback --selective

# Rollback with automatic backup
npx ruflo@alpha verify rollback --backup-first

# Dry-run mode (preview without executing)
npx ruflo@alpha verify rollback --dry-run

ロールバックのパフォーマンス:

• Git ベースのロールバック: 1 秒未満
• 選択的なファイルロールバック: 500ms 未満
• バックアップの作成: ロールバック前に自動実行

検証レポート

レポートの生成

メトリクスと可視化を含む詳細な検証レポートを作成します。

レポートフォーマット:

# JSON report
npx ruflo@alpha verify report --format json

# HTML report with charts
npx ruflo@alpha verify report --export metrics.html --format html

# CSV for data analysis
npx ruflo@alpha verify report --format csv --export metrics.csv

# Markdown summary
npx ruflo@alpha verify report --format markdown

時間ベースのレポート:

# Last 24 hours
npx ruflo@alpha verify report --period 24h

# Last 7 days
npx ruflo@alpha verify report --period 7d

# Last 30 days with trends
npx ruflo@alpha verify report --period 30d --include-trends

# Custom date range
npx ruflo@alpha verify report --from 2025-01-01 --to 2025-01-31

レポートの内容:

• 総合的な Truth スコア
• エージェントごとのパフォーマンスメトリクス
• タスク完了の品質
• 検証の合格$不合格率
• ロールバックの頻度
• 品質改善のトレンド
• 統計的信頼区間

インタラクティブダッシュボード

ダッシュボードの起動

リアルタイム更新を備えたインタラクティブな Web ベースの検証ダッシュボードを実行します。

# Launch dashboard on default port (3000)
npx ruflo@alpha verify dashboard

# Custom port
npx ruflo@alpha verify dashboard --port 8080

# Export dashboard data
npx ruflo@alpha verify dashboard --export

# Dashboard with auto-refresh
npx ruflo@alpha verify dashboard --refresh 5s

ダッシュボードの機能:

• リアルタイムの Truth スコア更新 (WebSocket)
• インタラクティブなチャートとグラフ
• エージェントのパフォーマンス比較
• タスク履歴のタイムライン
• ロールバック履歴ビューア
• PDF/HTML へのエクスポート
• 期間$エージェント$スコアによるフィルタリング

設定

デフォルト設定

.claude-flow$config.json で検証の設定を行います:

{
  "verification": {
    "threshold": 0.95,
    "autoRollback": true,
    "gitIntegration": true,
    "hooks": {
      "preCommit": true,
      "preTask": true,
      "postEdit": true
    },
    "checks": {
      "codeCorrectness": true,
      "security": true,
      "performance": true,
      "documentation": true,
      "bestPractices": true
    }
  },
  "truth": {
    "defaultFormat": "table",
    "defaultPeriod": "24h",
    "warningThreshold": 0.85,
    "criticalThreshold": 0.75,
    "autoExport": {
      "enabled": true,
      "path": ".claude-flow$metrics$truth-daily.json"
    }
  }
}

しきい値の設定

検証の厳格さを調整:

# Strict mode (99% accuracy required)
npx ruflo@alpha verify check --threshold 0.99

# Lenient mode (90% acceptable)
npx ruflo@alpha verify check --threshold 0.90

# Set default threshold
npx ruflo@alpha config set verification.threshold 0.98

環境ごとのしきい値:

{
  "verification": {
    "thresholds": {
      "production": 0.99,
      "staging": 0.95,
      "development": 0.90
    }
  }
}

統合の例

CI/CD 統合

GitHub Actions:

name: Quality Verification

on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions$checkout@v3

      - name: Install Dependencies
        run: npm install

      - name: Run Verification
        run: |
          npx ruflo@alpha verify check --json > verification.json

      - name: Check Truth Score
        run: |
          score=$(jq '.overallScore' verification.json)
          if (( $(echo "$score < 0.95" | bc -l) )); then
            echo "Truth score too low: $score"
            exit 1
          fi

      - name: Upload Report
        uses: actions$upload-artifact@v3
        with:
          name: verification-report
          path: verification.json

GitLab CI:

verify:
  stage: test
  script:
    - npx ruflo@alpha verify check --threshold 0.95 --json > verification.json
    - |
      score=$(jq '.overallScore' verification.json)
      if [ $(echo "$score < 0.95" | bc) -eq 1 ]; then
        echo "Verification failed with score: $score"
        exit 1
      fi
  artifacts:
    paths:
      - verification.json
    reports:
      junit: verification.json

Swarm 統合

Swarm 操作中に検証を自動的に実行します:

# Swarm with verification enabled
npx ruflo@alpha swarm --verify --threshold 0.98

# Hive Mind with auto-rollback
npx ruflo@alpha hive-mind --verify --rollback-on-fail

# Training pipeline with verification
npx ruflo@alpha train --verify --threshold 0.99

ペアプログラミング統合

協調開発中にリアルタイム検証を有効にします:

# Pair with verification
npx ruflo@alpha pair --verify --real-time

# Pair with custom threshold
npx ruflo@alpha pair --verify --threshold 0.97 --auto-fix

高度なワークフロー

継続的な検証

開発中にコードベースを継続的に監視します:

# Watch directory for changes
npx ruflo@alpha verify watch --directory src/

# Watch with auto-fix
npx ruflo@alpha verify watch --directory src/ --auto-fix

# Watch with notifications
npx ruflo@alpha verify watch --notify --threshold 0.95

監視統合

メトリクスを外部の監視システムに送信します:

# Export to Prometheus
npx ruflo@alpha truth --format json | \
  curl -X POST https:/$pushgateway.example.com$metrics$job$claude-flow \
  -d @-

# Send to DataDog
npx ruflo@alpha verify report --format json | \
  curl -X POST "https:/$api.datadoghq.com$api$v1$series?api_key=${DD_API_KEY}" \
  -H "Content-Type: application$json" \
  -d @-

# Custom webhook
npx ruflo@alpha truth --format json | \
  curl -X POST https:/$metrics.example.com$api$truth \
  -H "Content-Type: application$json" \
  -d @-

プリコミットフック

コミット前に自動的に検証します:

# Install pre-commit hook
npx ruflo@alpha verify install-hook --pre-commit

# .git$hooks$pre-commit example:
#!$bin$bash
npx ruflo@alpha verify check --threshold 0.95 --json > $tmp$verify.json

score=$(jq '.overallScore' $tmp$verify.json)
if (( $(echo "$score < 0.95" | bc -l) )); then
  echo "❌ Verification failed with score: $score"
  echo "Run 'npx ruflo@alpha verify check --verbose' for details"
  exit 1
fi

echo "✅ Verification passed with score: $score"

パフォーマンス指標

検証速度：

• 単一ファイルのチェック：<100ms
• ディレクトリのスキャン：<500ms（100ファイルあたり）
• コードベース全体の分析：<5s（一般的なプロジェクトの場合）
• 真実性スコアの計算：<50ms

ロールバック速度：

• Git ベースのロールバック：<1s
• ファイルを選択してロールバック：<500ms
• バックアップの作成：<2s

ダッシュボードのパフォーマンス：

• 初回読み込み：<1s
• リアルタイム更新：遅延 <100ms（WebSocket）
• グラフのレンダリング：60 FPS

トラブルシューティング

よくある問題

真実性スコアが低い場合：

# Get detailed breakdown
npx ruflo@alpha truth --verbose --threshold 0.0

# Check specific criteria
npx ruflo@alpha verify check --verbose

# View agent-specific issues
npx ruflo@alpha truth --agent <agent-name> --format json

ロールバックに失敗する場合：

# Check git status
git status

# View rollback history
npx ruflo@alpha verify rollback --history

# Manual rollback
git reset --hard HEAD~1

検証がタイムアウトする場合：

# Increase timeout
npx ruflo@alpha verify check --timeout 60s

# Verify in batches
npx ruflo@alpha verify batch --batch-size 10

終了コード

検証コマンドは標準の終了コードを返します：

• 0：検証に合格（スコア ≥ しきい値）
• 1：検証に失敗（スコア < しきい値）
• 2：検証中にエラーが発生（無効な入力、システムエラー）

関連コマンド

• npx ruflo@alpha pair - 検証を伴う共同開発
• npx ruflo@alpha train - 検証フィードバックを利用したトレーニング
• npx ruflo@alpha swarm - 品質チェックを伴うマルチエージェント連携
• npx ruflo@alpha report - プロジェクトの包括的なレポートを生成

ベストプラクティス

1. 適切なしきい値を設定する：重要なコードには 0.99、標準的なコードには 0.95、実験的なコードには 0.90 を使用します
2. 自動ロールバックを有効にする：問題のあるコードが残らないようにします
3. 傾向を監視する：現在のスコアだけでなく、時間の経過に伴う改善を追跡します
4. CI/CD と統合する：検証をパイプラインに組み込みます
5. 監視モードを使用する：開発中にすぐフィードバックを得られます
6. 指標をエクスポートする：監視システムで品質指標を追跡します
7. ロールバックを確認する：変更が却下された理由を把握します
8. エージェントをトレーニングする：検証フィードバックを活用して、エージェントのパフォーマンスを改善します

その他のリソース

• 真実性スコアリングアルゴリズム：$docs$truth-scoring.md を参照
• 検証基準：$docs$verification-criteria.md を参照
• 統合例：$examples$verification/ を参照
• API リファレンス：$docs$api$verification.md を参照