phasegate 0.15.0

package/scripts/harness/validator-system/presentation/handlers/run-validators-handler.ts

@@ -0,0 +1,137 @@
+/**
+ * @layer presentation
+ * @unit validator-system
+ *
+ * RunValidatorsHandler — バリデータ実行 CLIハンドラー
+ */
+import type { RunFullValidationUseCase } from '../../application/use-cases/run-full-validation-usecase.js';
+import type { RunL0ValidatorsUseCase } from '../../application/use-cases/run-l0-validators-usecase.js';
+import type { RunL1ValidatorsUseCase } from '../../application/use-cases/run-l1-validators-usecase.js';
+import type { AggregatedValidationReport } from '../../application/dto/aggregated-validation-report.js';
+import { HumanValidationResultFormatter } from '../formatters/human-validation-result-formatter.js';
+import { AgentValidationResultFormatter } from '../formatters/agent-validation-result-formatter.js';
+import { CiValidationResultFormatter } from '../formatters/ci-validation-result-formatter.js';
+
+export interface RunValidatorsHandlerArgs {
+  layer?: 'L0' | 'L1' | 'L2' | 'L3' | 'L4' | 'all';
+  validatorIds?: string[];
+  targetPaths?: string[];
+  unit?: string;
+  phase?: string;
+  format?: 'human' | 'agent' | 'ci';
+  failOnWarning?: boolean;
+  noL4?: boolean;
+}
+
+export interface RunValidatorsHandlerDeps {
+  runFullValidationUseCase: RunFullValidationUseCase;
+  runL0ValidatorsUseCase?: RunL0ValidatorsUseCase;
+  runL1ValidatorsUseCase?: RunL1ValidatorsUseCase;
+}
+
+export class RunValidatorsHandler {
+  private readonly useCase: RunFullValidationUseCase;
+  private readonly l0UseCase: RunL0ValidatorsUseCase | undefined;
+  private readonly l1UseCase: RunL1ValidatorsUseCase | undefined;
+
+  constructor(deps: RunValidatorsHandlerDeps) {
+    this.useCase = deps.runFullValidationUseCase;
+    this.l0UseCase = deps.runL0ValidatorsUseCase;
+    this.l1UseCase = deps.runL1ValidatorsUseCase;
+  }
+
+  async execute(args: RunValidatorsHandlerArgs): Promise<{ output: string; exitCode: number }> {
+    try {
+      if (args.layer === 'L0') {
+        const l0UseCase = this.l0UseCase;
+        if (!l0UseCase) {
+          return { output: 'L0 validators not configured', exitCode: 1 };
+        }
+        const l0Results = await l0UseCase.execute({
+          validatorIds: args.validatorIds,
+        });
+        const l0Report: AggregatedValidationReport = {
+          overallPassed: l0Results.every((r) => r.passed || r.skipped),
+          totalValidators: l0Results.length,
+          passedValidators: l0Results.filter((r) => r.passed).length,
+          failedValidators: l0Results.filter((r) => !r.passed && !r.skipped).length,
+          skippedValidators: l0Results.filter((r) => r.skipped).length,
+          allErrors: l0Results.flatMap((r) => r.errors),
+          summary: {
+            totalErrors: l0Results.flatMap((r) => r.errors).filter((e) => e.severity === 'error').length,
+            totalWarnings: l0Results.flatMap((r) => r.errors).filter((e) => e.severity === 'warning').length,
+            errorsByLayer: { L2: 0, L3: 0, L4: 0 },
+          },
+          results: l0Results,
+        };
+        const format = args.format ?? 'human';
+        let output: string;
+        if (format === 'agent') {
+          output = new AgentValidationResultFormatter().format(l0Report);
+        } else if (format === 'ci') {
+          output = new CiValidationResultFormatter().format(l0Report);
+        } else {
+          output = new HumanValidationResultFormatter().format(l0Report);
+        }
+        return { output, exitCode: l0Report.overallPassed ? 0 : 1 };
+      }
+
+      if (args.layer === 'L1') {
+        const l1UseCase = this.l1UseCase;
+        if (!l1UseCase) {
+          return { output: 'L1 validators not configured', exitCode: 1 };
+        }
+        // 空配列はターゲット未指定として扱い、undefinedを渡してアダプター側のデフォルト探索を使う
+        const l1TargetPaths = args.targetPaths && args.targetPaths.length > 0 ? args.targetPaths : undefined;
+        const l1Results = await l1UseCase.execute({ targetPaths: l1TargetPaths });
+        const l1Report: AggregatedValidationReport = {
+          overallPassed: l1Results.every((r) => r.passed || r.skipped),
+          totalValidators: l1Results.length,
+          passedValidators: l1Results.filter((r) => r.passed).length,
+          failedValidators: l1Results.filter((r) => !r.passed && !r.skipped).length,
+          skippedValidators: l1Results.filter((r) => r.skipped).length,
+          allErrors: l1Results.flatMap((r) => r.errors),
+          summary: {
+            totalErrors: l1Results.flatMap((r) => r.errors).filter((e) => e.severity === 'error').length,
+            totalWarnings: l1Results.flatMap((r) => r.errors).filter((e) => e.severity === 'warning').length,
+            errorsByLayer: { L2: 0, L3: 0, L4: 0 },
+          },
+          results: l1Results,
+        };
+        const format = args.format ?? 'human';
+        let output: string;
+        if (format === 'agent') {
+          output = new AgentValidationResultFormatter().format(l1Report);
+        } else if (format === 'ci') {
+          output = new CiValidationResultFormatter().format(l1Report);
+        } else {
+          output = new HumanValidationResultFormatter().format(l1Report);
+        }
+        return { output, exitCode: l1Report.overallPassed ? 0 : 1 };
+      }
+
+      const report = await this.useCase.execute({
+        targetPaths: args.targetPaths ?? [],
+        unitName: args.unit ?? '',
+        currentPhase: args.phase ?? '',
+        includeL4: !args.noL4,
+        failOnWarning: args.failOnWarning,
+      });
+
+      const format = args.format ?? 'human';
+      let output: string;
+      if (format === 'agent') {
+        output = new AgentValidationResultFormatter().format(report);
+      } else if (format === 'ci') {
+        output = new CiValidationResultFormatter().format(report);
+      } else {
+        output = new HumanValidationResultFormatter().format(report);
+      }
+
+      const exitCode = report.overallPassed ? 0 : 1;
+      return { output, exitCode };
+    } catch (err) {
+      return { output: `実行エラー: ${err instanceof Error ? err.message : String(err)}`, exitCode: 2 };
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,21 @@
+# Skills ディレクトリ
+
+このディレクトリには、AIエージェントの共有スキル定義が含まれています。
+
+## ディレクトリ構成と同期
+
+このディレクトリはスキルの**唯一の信頼できる情報源 (Single Source of Truth)** です。
+`.agent` と `.claude` の両方の環境から同じスキルにアクセスできるように、各ディレクトリには以下のようなシンボリックリンクが作成されています：
+
+- `.agent/skills` -> `./skills` (プロジェクトルートからの相対パス)
+- `.claude/skills` -> `./skills` (プロジェクトルートからの相対パス)
+- `.codex/skills` -> `./skills` (プロジェクトルートからの相対パス)
+
+技術的には、リンクは以下のように設定されています：
+- `.agent/skills` -> `../skills`
+- `.claude/skills` -> `../skills`
+- `.codex/skills` -> `../skills`
+
+## 新しいスキルの追加
+
+新しいスキルを追加する場合は、この `skills` ディレクトリに直接追加してください。シンボリックリンクを通じて、両方のエージェントから自動的に利用可能になります。

package/skills/cascade-updater/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: cascade-updater
+description: 下位フェーズの発見・変更を上位設計文書にフィードバックし影響範囲を整合的に更新
+model: sonnet
+review: opus
+---
+
+# Cascade Updater
+
+下位フェーズでの発見・変更・人間からの指示を、正しいレイヤーの設計文書にフィードバックし、影響範囲を整合的に更新するスキル。
+
+## 前提条件チェック
+
+### 必須インプット
+- **変更内容の記述** — 何が発見/変更されたか
+- **変更が発生したレイヤー** — どのフェーズで発見されたか
+
+---
+
+## ⚠️ 3フェーズ実行ルール
+
+**このスキルは3フェーズで実行する。**
+- **Phase 1（計画）**: Opus がスコープ・方針・不明点を整理し、人間の承認を得る
+- **Phase 2（実行）**: Sonnet 4.6 に委任して成果物を生成する（`scripts/delegate-sonnet.sh` 経由）
+- **Phase 3（レビュー）**: Opus が成果物を検証し、問題があれば直接修正する
+
+**Phase 1/2/3を同時に実行してはならない。モデルルーティングの詳細は `docs/principles/model-routing.md` を参照。**
+
+---
+
+## Phase 1: 影響分析（plan）
+
+### 目的
+変更の帰属レイヤーを判定し、影響範囲を特定して人間の承認を得る。
+
+### 出力
+会話内で以下を報告する（ファイルは作成しない）：
+
+```markdown
+# カスケード更新 影響分析
+
+## 1. 変更の起点
+- 発見元: {フェーズ/ストーリー}
+- 内容: {変更内容}
+
+## 2. 帰属レイヤー判定
+- 判定結果: {環境設計 / 論理設計 / Domain / ストーリー}
+- 理由: {判定理由}
+参考: references/層別判定ガイド.md
+
+## 3. 影響を受ける文書一覧
+| # | ファイル | 予定される変更内容 |
+|---|---------|-----------------|
+
+## 4. QA（不明点・確認事項）
+
+### [Question] Q1: {質問タイトル}
+{質問の詳細と背景}
+**推奨案:** {AIの推奨案}
+
+[Answer]
+（人間が回答を記入）
+```
+
+### Phase 1 完了条件
+- 影響分析を報告した
+- 不明点がある場合は`[Question]`セクションに記載した
+- **人間にボールを渡した**
+- **設計文書はまだ更新していない**
+
+---
+
+## Phase 2: 実行（execution）
+
+### 開始条件
+- 人間がPhase 1の影響分析を承認した
+
+### ワークフロー
+
+1. **該当レイヤーの文書を更新** — 変更内容を反映（追記優先、変更理由を記録）
+2. **下位レイヤーの影響確認** — 更新により下位文書に矛盾が生じないか確認・更新
+3. **更新レポート出力** — 変更した全文書の一覧と変更内容を報告
+
+### 更新時の原則
+
+- **更新は該当レイヤー以下のみ** — 上位の抽象設計は汚さない
+- **追記優先** — 既存の記述を削除するのではなく、新しい制約・ルールを追記する
+- **変更理由を記録** — なぜこの変更が必要になったかを文書内に簡潔に記録する
+
+### Phase 2 最低出力基準（Sonnet委任時の品質制約）
+
+以下の基準を満たさない出力は不完全とみなし、Phase 3レビューでBLOCKとする。
+
+| 基準 | 最低要件 |
+|------|---------|
+| 帰属レイヤー明記 | 各変更が帰属するレイヤーが明示されていること |
+| 変更理由記録 | 全変更箇所に変更理由が記録されていること |
+| 追記優先 | 既存記述の削除ではなく追記で対応していること（削除は明示的承認があった場合のみ） |
+| 下位影響確認 | 更新による下位文書への影響が確認・記録されていること |
+| 更新レポート | 変更した全文書の一覧と変更内容が報告されていること |
+
+詳細な判定パターンと具体例は [references/層別判定ガイド.md](references/層別判定ガイド.md) を参照。
+
+---
+
+## Phase 3: レビュー（Opus review）
+
+### 実行主体
+メインセッション（Opus 4.6）が実行する。Sonnetへの再委任は行わない。
+
+### レビュー手順
+1. Sonnetが出力したファイルを読み込む
+2. `docs/principles/model-routing.md` のレビュー観点 R1〜R7 に沿って検証する
+3. **スキル固有レビュー観点**を検証する
+4. 判定結果を出力する
+
+### スキル固有レビュー観点（BLOCK基準）
+- [ ] 変更が正しいレイヤーに帰属しているか（上位の抽象設計を汚していないか）
+- [ ] 変更理由が全箇所に記録されているか
+- [ ] 既存記述の不必要な削除がないか
+- [ ] 下位文書への影響が確認されているか
+- [ ] Phase 1の影響分析と実際の更新範囲が一致しているか
+
+### 判定と修正
+- **BLOCK項目にFAIL** → Opusが直接修正してから完了とする
+- **WARNのみFAIL** → Opusが直接修正してから完了とする
+- **全PASS** → 完了

package/skills/cascade-updater/references//345/261/244/345/210/245/345/210/244/345/256/232/343/202/254/343/202/244/343/203/211.md

@@ -0,0 +1,58 @@
+# 層別判定ガイド
+
+変更・発見の種類ごとに、どのレイヤーの設計文書を更新すべきかの判定基準と具体例。
+
+## 環境設計に帰属するもの（最も頻度が高い）
+
+**判定基準:** コードの正しさではなく、環境の正しさに関する問題
+
+| パターン | 例 |
+|---------|-----|
+| 設定ファイルの漏れ | サービス/関数が設定ファイルに未登録 |
+| ランタイム制約 | 認証トークンのアルゴリズム不一致 |
+| フレームワーク制約 | 特定ファイルからのexportルール、ビルド制約 |
+| シードデータ不足 | テストに必要なデータ層の欠落 |
+| マイグレーション漏れ | DB変更が適用されていない |
+| 依存関係管理 | import map、パッケージ設定の不備 |
+
+## 論理設計に帰属するもの
+
+**判定基準:** コンポーネントの分割・連携・責務に関する問題
+
+| パターン | 例 |
+|---------|-----|
+| API契約の変更 | レスポンス形式では画面要件を満たせない |
+| 層の責務違反 | BFF層にドメインロジックが混入 |
+| コンポーネント不足 | 必要なミドルウェア/ハンドラが未設計 |
+| テーブル設計の変更 | カラム追加/インデックス変更が必要 |
+
+## Domainに帰属するもの
+
+**判定基準:** ビジネスルール・業務概念の理解に関する問題
+
+| パターン | 例 |
+|---------|-----|
+| エンティティの不足 | 必要な業務概念がモデル化されていない |
+| 集約境界の誤り | 本来別の集約であるべきものが混在 |
+| 状態遷移の不足 | 必要なドメインイベントが未定義 |
+| 不変条件の誤り | ビジネスルールの理解が間違っていた |
+
+## ストーリー/Unitに帰属するもの（非常にまれ）
+
+**判定基準:** そもそも何を作るかの理解に関する問題
+
+| パターン | 例 |
+|---------|-----|
+| ストーリーの漏れ | 必要な機能がストーリーとして定義されていない |
+| Unit分割の問題 | 密結合すぎて独立実装できない |
+| 受け入れ基準の不足 | 検証不能な基準しかない |
+
+## 判定フローチャート
+
+```
+発見の内容は？
+├─ 「コードは正しいが動かない」→ 環境設計
+├─ 「コンポーネントの連携が間違っている」→ 論理設計
+├─ 「業務ルールの理解が違った」→ Domain
+└─ 「そもそも作るべきものが違った」→ ストーリー/Unit
+```

package/skills/codebase-mapper/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: codebase-mapper
+description: コードベースの構造マップを生成するスキル。全ソースファイルの `@unit`/`@layer` アノテーションを解析し、Unit・レイヤー分布・Unit間依存関係・循環依存を可視化したマップ文書を出力する。L4バリデータ（drift-detection/dead-code）の入力精度向上にも使用。使用タイミング: 「コードベースの構造を把握したい」「Unitマップを作って」「どのファイルがどのUnitに属するか調べて」「依存関係を可視化して」など。
+model: sonnet
+review: opus
+---
+
+# Codebase Mapper
+
+全ソースファイルの `@unit`/`@layer` アノテーションとimportグラフを解析し、
+コードベースの構造マップを生成するスキル。
+
+## 出力物
+
+`docs/product/construction/codebase-map.md` — Unit・レイヤー分布・依存関係の可視化文書
+
+---
+
+## ⚠️ 2フェーズ実行ルール
+
+- **Phase 1（計画）**: スキャン対象ディレクトリとマップ粒度を確認し、人間の承認を得る
+- **Phase 2（実行）**: 解析を実行しマップ文書を生成する
+
+---
+
+## Phase 1: 計画（plan）
+
+### 出力（会話内のみ）
+
+```markdown
+# Codebase Mapper 計画
+
+## スキャン対象
+- ソースコード: scripts/harness/
+- 除外: __tests__/, node_modules/
+
+## 出力粒度
+- [ ] Unit一覧（@unit アノテーション）
+- [ ] レイヤー分布（@layer アノテーション）
+- [ ] Unit間依存関係（import解析）
+- [ ] 循環依存検出
+
+## 出力先
+docs/product/construction/codebase-map.md
+
+## QA
+[Question] Q1: ...
+[Answer]
+```
+
+### Phase 1 完了条件
+- 計画を報告した
+- **マップはまだ生成していない**
+
+---
+
+## Phase 2: 実行（execution）
+
+### Step 1: @unit/@layer アノテーションの収集
+
+Glob + Read を使い、`scripts/harness/**/*.ts`（テスト・fixture除外）から：
+
+```
+@unit {unit-name}
+@layer {domain|application|infrastructure|presentation}
+```
+
+を抽出する。`__tests__/` と `*.test.ts` は除外する。
+
+### Step 2: Import グラフの構築
+
+各ファイルの `import` 文からUnit間依存を抽出する:
+- 同Unit内のimport → 内部依存（スキップ）
+- 別Unitへのimport → Unit間依存エッジとして記録
+
+### Step 3: 循環依存の検出
+
+Unit間依存グラフを深さ優先探索でサイクル検出する。
+
+### Step 4: マップ文書の生成
+
+`docs/product/construction/codebase-map.md` に出力。
+
+---
+
+## 出力フォーマット
+
+```markdown
+# Codebase Map
+
+生成日時: {date}
+スキャン対象: scripts/harness/
+総ファイル数: N（テスト除く）
+
+---
+
+## Unit 一覧
+
+| Unit | ファイル数 | レイヤー分布 |
+|------|----------|-----------|
+| harness-error | 12 | domain:4, app:4, infra:2, pres:2 |
+| ...
+
+---
+
+## Unit 間依存グラフ
+
+```
+harness-api
+  └── depends on: biome-ast-engine, validator-system, ...
+
+validator-system
+  └── depends on: harness-error, config-foundation
+```
+
+---
+
+## 循環依存
+
+（検出された場合のみ）
+
+| サイクル | 重大度 | 影響ファイル |
+|---------|--------|-----------|
+
+---
+
+## アノテーション欠落ファイル
+
+（@unit または @layer がないファイル）
+
+| ファイル | 欠落アノテーション |
+|---------|-----------------|
+```
+
+---
+
+## アノテーション欠落の対処
+
+マップ生成後、`@unit`/`@layer` が欠落しているファイルが検出された場合:
+1. `L1-001`（require-unit-comment）/ `L1-002`（require-layer-comment）の違反として報告
+2. `quick-implementor` でアノテーションを追加
+
+---
+
+## 関連スキル・コマンド
+
+| スキル/コマンド | 用途 |
+|--------------|------|
+| `pnpm run lint` | L1 archgateルールの全体スキャン |
+| `consistency-checker` | マップ生成後の設計文書整合性確認 |
+| `doc-freshness-checker` | マップと設計文書の鮮度を合わせて確認 |