phasegate 0.32.0 → 0.44.0

package/README.ja.md

@@ -1,206 +1,192 @@
 # Phasegate
 
-**Phasegate — AI-Agnostic Quality Defense Toolkit**
+**Phasegate -- AI-Agnostic Quality Defense Toolkit**
 
-AIエージェント（Claude Code, Codex, Cursor, その他）が生成するコードと設計の構造的整合性を、エージェント非依存で機械的に保証し続けるポータブルな品質防御ツールキットです。
-
-> **Core Value**: 「設計意図とコードの構造的整合性を、機械的に保証し続けること」
->
-> どのAIエージェントで開発しても、このハーネスをプロジェクトに導入すれば、設計意図とコードの構造的整合性が壊れない。
+AIエージェント（Claude Code, Codex, Cursor, Copilot 等）が生成するコードと設計の構造的整合性を機械的に保証する品質防御ツールキットです。
 
 ---
 
 ## 目次
 
 - [何ができるのか](#何ができるのか)
-- [アーキテクチャ — 5層防御モデル](#アーキテクチャ--5層防御モデル)
-- [前提条件](#前提条件)
-- [インストール](#インストール)
-- [セットアップ](#セットアップ)
-- [phasegate.config.json](#harnessconfigjson)
-- [CLIコマンドリファレンス](#cliコマンドリファレンス)
-- [AIDLCプロセス — スキル実行順序](#aidlcプロセス--スキル実行順序)
-- [スキル一覧 (28スキル)](#スキル一覧-28スキル)
-- [メタデータ規約 (@unit / @layer / @story)](#メタデータ規約-unit--layer--story)
-- [Claude Code Hooks 統合](#claude-code-hooks-統合)
-- [Quick Mode](#quick-mode)
-- [プリセット](#プリセット)
+- [クイックスタート](#クイックスタート)
+- [5層防御モデル](#5層防御モデル)
+- [設定 (phasegate.config.json)](#設定-phasegateconfigjson)
+- [CLIコマンド](#cliコマンド)
+- [AIDLC スキル](#aidlc-スキル)
+- [メタデータ規約](#メタデータ規約)
+- [Claude Code Hooks](#claude-code-hooks)
+- [カスタムフェーズゲート](#カスタムフェーズゲート)
 - [CI/CD テンプレート](#cicd-テンプレート)
-- [回帰テスト (K1-K15)](#回帰テスト-k1-k15)
-- [ディレクトリ構造](#ディレクトリ構造)
-- [バージョン管理](#バージョン管理)
+- [導入後のプロジェクト構造](#導入後のプロジェクト構造)
 
 ---
 
 ## 何ができるのか
 
-| 機能 | 説明 |
+Phasegate は **「設計なしの実装を物理的に拒否する」** ツールです。
+
+| カテゴリ | 内容 |
 |---|---|
-| **L1 Biome AST 検証** | エディタ保存時・CI実行時にimportグラフ解析・レイヤー違反・AIアンチパターンを検出 |
-| **L2 Pre-commit バリデータ** | コミット前にPhase Gate・メタデータ完全性・テスト品質ルールを強制 |
-| **L3 CI バリデータ** | PRマージ前にセキュリティ・パフォーマンス・カバレッジ・Nyquist要件トレーサビリティを検証 |
-| **L4 スケジュール検証** | 週次で設計-実装乖離・文書間整合性・デッドコードを検出 |
-| **28スキル** | product-architectからstory-implementorまで、設計→実装の全フェーズをカバー |
-| **Phase Dependency Model** | 設計フェーズ間の前提条件を機械的に強制（設計なしの実装を物理的に拒否） |
-| **Quick Mode** | バグ修正・テスト追加などの軽微な変更では最小限のゲートで高速実行 |
-| **Claude Code Hooks** | ファイル書き込み時の自動Biome lint、セッション終了時の全テストグリーン強制 |
-| **HarnessError** | 全バリデータのエラーにADR参照と修正コード例を付与。AIエージェントが自己修正可能 |
-| **Nyquist Validation** | 要件→テストの双方向トレーサビリティを`requirement-test-matrix.json`で保証 |
-| **Cascade Updater** | 下位フェーズの発見を上位設計文書に自動フィードバック |
-| **Regression Suite** | K1-K15非交渉要件・GnGゲート・エージェント非依存性を回帰テストで継続検証 |
-| **カスタムフェーズゲート** | `phasegate.config.json` の `gates[]` で独自のフェーズゲートを定義可能。デフォルトはAIDLCフェーズ依存 |
-| **保護ファイル制御** | `protectedFiles.exclude` でAI書き込みから保護するファイルを設定 |
-| **Bash書き込み検出** | シェル経由のファイル書き込み（`sed -i`, `tee`, `cp`, `mv`, リダイレクト等）を検出してブロック |
+| **フェーズゲート** | 設計文書が存在しないとソースコードの書き込みをブロック。カスタムゲートも定義可能 |
+| **5層バリデーション** | L1(AST) → L2(Pre-commit) → L3(CI) → L4(週次) の段階的品質チェック |
+| **28 AIDLC スキル** | 要求定義 → 設計 → テスト設計 → TDD実装の全フェーズをスキルとして提供 |
+| **Claude Code Hooks** | Write/Edit 時に自動でゲートチェック・Biome lint を実行 |
+| **Quick Mode** | バグ修正・ドキュメント修正など軽微な変更ではゲートを緩和して高速実行 |
 
 ---
 
-## アーキテクチャ — 5層防御モデル
+## クイックスタート
 
-```
-╔══════════════════════════════════════════════════════════════╗
-║  L0  HOOKS ENGINE: Agent Hook Configuration                  ║
-║  ─────────────────────────────────────────────────────────  ║
-║  hook-config        .harness-hooks.yml設定検証              ║
-║  gate-check         完了ゲートチェック                      ║
-║                                                             ║
-║  実行: npx phasegate validate --layer L0                      ║
-╠══════════════════════════════════════════════════════════════╣
-║  L1  EDITOR TIME: Biome AST Rules                           ║
-║  ─────────────────────────────────────────────────────────  ║
-║  require-unit-comment   require-layer-comment               ║
-║  no-layer-violation     enforce-folder-structure            ║
-║  no-any-abuse           no-ghost-file                       ║
-║  no-comment-flood       no-code-duplication                 ║
-║  + it-test-mock-detection  + stub-comment-detection         ║
-║                                                             ║
-║  実行: npx phasegate lint                                     ║
-╠══════════════════════════════════════════════════════════════╣
-║  L2  PRE-COMMIT: Validators                                 ║
-║  ─────────────────────────────────────────────────────────  ║
-║  phase-gate    設計→実装の順序強制                          ║
-║  metadata      @unit/@layer/@US-XXX/@story の完全性検証     ║
-║  test-quality  AAA / actual / single-act / no-domain-mock   ║
-║                                                             ║
-║  実行: npx phasegate validate --layer L2                      ║
-╠══════════════════════════════════════════════════════════════╣
-║  L3  CI/CD: Validators                                      ║
-║  ─────────────────────────────────────────────────────────  ║
-║  security      ハードコード秘密・SQLインジェクション検出    ║
-║  performance   ループ内await・N+1クエリ・バンドルサイズ     ║
-║  coverage      カバレッジ閾値 (standard: 90% / strict: 95%) ║
-║  nyquist       要件→テスト双方向トレーサビリティ検証        ║
-║                                                             ║
-║  実行: npx phasegate validate --layer L3                      ║
-╠══════════════════════════════════════════════════════════════╣
-║  L4  SCHEDULED: Validators                                  ║
-║  ─────────────────────────────────────────────────────────  ║
-║  drift-detect      設計↔コード双方向乖離検出               ║
-║  consistency-check 文書間レイヤー整合性チェック             ║
-║  dead-code         未使用エクスポート・到達不能コード検出   ║
-║                                                             ║
-║  実行: npx phasegate validate --layer L4                      ║
-╚══════════════════════════════════════════════════════════════╝
-```
+### 前提条件
 
-各バリデータは統一された`HarnessError`フォーマットでエラーを報告します。
+Node.js >= 18, npm >= 9, TypeScript 5.x
 
-```typescript
-interface HarnessError {
-  code: string;         // "L1-003", "L2-001" など
-  severity: "error" | "warning";
-  message: string;      // 人間可読な説明
-  suggestion: string;   // 修正方法の提案
-  adr_ref?: string;     // 関連ADR参照 ("ADR-003" など)
-  fix_example?: string; // 修正コード例（AIエージェントの自己修正用）
-}
+### 1. インストール
+
+```bash
+npm install --save-dev phasegate
 ```
 
----
+### 2. プロジェクト初期化
 
-## 前提条件
+```bash
+npx phasegate init --name <プロジェクト名> --preset standard
+```
 
-| 要件 | バージョン |
-|---|---|
-| Node.js | 18以上 |
-| npm | 9以上 |
-| TypeScript | 5.x |
+`.claude/skills/` に28スキルを展開し、設計原則ドキュメント（`docs/principles/*.md`・`docs/folder_management_rules.md`）を配置し、`phasegate.config.json` を生成します。
 
----
+`--preset` で初期構成を選択できます: `minimal`（プロトタイプ）/ `standard`（推奨）/ `strict`（本番）
 
-## インストール
+オプションで `--with-husky` を付けると L2 バリデータを実行する `.husky/pre-commit` フックも同時にインストールされます。
+
+### 3. AIDLC を開始
 
 ```bash
-npm install --save-dev phasegate
+claude  # プロジェクトルートで起動
 ```
 
-`package.json` に直接記載する場合:
+セッション内で `/product-architect` を実行して設計を開始します。
 
-```json
-{
-  "devDependencies": {
-    "phasegate": "^0.31.0"
-  }
-}
+### アップデート
+
+```bash
+npm update phasegate          # パッケージ更新
+npx phasegate update-skills   # スキルを最新版に同期
 ```
 
 ---
 
-## セットアップ
+## 5層防御モデル
 
-### 1. プロジェクト初期化
+| レイヤー | タイミング | チェック内容 | 実行コマンド |
+|---|---|---|---|
+| **L0** | Agent Hook | hook 設定検証・完了ゲートチェック | `npx phasegate validate --layer L0` |
+| **L1** | エディタ保存時 | import グラフ・レイヤー違反・`@unit`/`@layer` メタデータ・AI アンチパターン | `npx phasegate lint` |
+| **L2** | コミット前 | フェーズゲート・メタデータ完全性・テスト品質 | `npx phasegate validate --layer L2` |
+| **L3** | CI/CD | セキュリティ・パフォーマンス・カバレッジ・要件トレーサビリティ (※) | `npx phasegate validate --layer L3` |
+| **L4** | 週次（CI cron） | 設計-コード乖離検出・文書間整合性・デッドコード検出 | `npx phasegate validate --layer L4` |
 
-```bash
-npx phasegate init --name <プロジェクト名>
-```
+エラーは統一された `HarnessError` フォーマットで報告され、ADR 参照と修正コード例が含まれるため AI エージェントが自己修正できます。
+
+`--format` オプションで出力形式を切り替えられます:
 
-実行されること:
-- `.claude/skills/` に28スキルを展開
-- プロジェクトルートに `phasegate.config.json` を生成
+| フォーマット | 用途 | 出力形式 |
+|---|---|---|
+| `human` | ローカル開発 | コンソール向け（絵文字・色付き） |
+| `agent` | AI エージェント連携 | キー値テキスト（`OVERALL: PASS`, `VALIDATOR: L2-001`） |
+| `ci` | CI/CD パイプライン | 構造化 JSON（GitHub Actions 等で解析可能） |
 
-### 2. 設計原則ドキュメントをコピー
+### L2 テスト品質ルール
 
-```bash
-# プロジェクトの docs/ 配下にコピー
-cp node_modules/phasegate/docs/folder_management_rules.md docs/
-mkdir -p docs/principles
-cp node_modules/phasegate/docs/principles/*.md docs/principles/
-```
+L2 のテスト品質バリデータ（L2-003）は以下をチェックします:
 
-### 3. プロダクト概要を作成
+| ルール | コード | 内容 |
+|---|---|---|
+| **日本語テスト名** | L2-003 | `it()` / `test()` のテスト名が日本語であること |
+| **`actual` 変数** | L2-003 | `expect()` の対象を `const actual` に代入していること |
+| **CLI E2E テスト存在** | L2-013 | CLI コマンドに対応する E2E テストが存在すること |
 
-```
-docs/product/
-└── <your_product>_overview.md   # プロダクト定義（AIDLCの起点）
+```typescript
+// PASS
+it('ユーザーが存在する場合、結果を返すこと', async () => {
+  // Arrange
+  const userId = "test_user";
+
+  // Act
+  const actual = await sut.findByUserId(userId);
+
+  // Assert
+  expect(actual).toEqual(expectedResult);
+});
+
+// FAIL — 英語テスト名 + actual 変数なし
+it('should return user', async () => {
+  const result = await sut.findByUserId(userId);
+  expect(result).toEqual(expectedResult);
+});
 ```
 
-### 4. Claude Codeを起動してAIDLCを開始
+### L3 Nyquist Validation（要件カバレッジ）※ 未完成
 
-```bash
-claude  # プロジェクトルートで起動
+> **注意**: バリデーションロジックは実装済みですが、マトリクスファイルの自動生成パイプラインが未完成のため、現時点では手動セットアップが必要です。
+
+通常のコードカバレッジ（L3 coverage）は「コードの何%が実行されたか」を測りますが、Nyquist は**「要件（受け入れ基準）の何%がテストされているか」**を測ります。
+
+**利用するには**: `.harness/requirement-test-matrix.json` を手動で作成し、受け入れ基準とテストの対応を定義します:
+
+```json
+{
+  "version": "1.0.0",
+  "stories": [
+    {
+      "storyId": "H07-01",
+      "storyMappings": [
+        {
+          "acId": "AC-1",
+          "testReferences": [
+            {
+              "filePath": "src/__tests__/unit/feature.test.ts",
+              "testType": "unit",
+              "testName": "特定のシナリオをテストする"
+            }
+          ]
+        },
+        {
+          "acId": "AC-2",
+          "testReferences": []
+        }
+      ]
+    }
+  ]
+}
 ```
 
-セッション内で `/product-architect` を実行してAIDLCを開始します。
+上記の例では AC-2 に `testReferences` がないため、L3 バリデータが「AC-2 はテストされていない」とエラーを報告します。`testType` は `unit` / `it` / `scenario` のいずれかです。マトリクスファイルが存在しない場合、Nyquist チェックはスキップされます。
+
+### L4 週次実行
 
-### スキルのアップデート
+L4 は CI の cron スケジュールで週次実行します。`consistency-check` テンプレートを使います:
 
 ```bash
-# ハーネスを更新後、スキルを最新版に同期
-npm update phasegate
-npx phasegate update-skills
+# テンプレートを生成して配置
+npx phasegate ci:generate-template --type consistency-check --render > .github/workflows/consistency-check.yml
 ```
 
+デフォルトは毎週月曜 09:00 UTC に実行。乖離やデッドコードが検出されると GitHub Issue が自動作成されます。手動で実行する場合は `npx phasegate validate --layer L4` を使います。
+
 ---
 
-## phasegate.config.json
+## 設定 (phasegate.config.json)
 
-プロジェクトルートに配置する品質設定のSingle Source of Truth。
+プロジェクトルートに配置する品質設定の Single Source of Truth です。
 
 ```jsonc
 {
   "project": { "name": "my-project", "preset": "standard" },
   "layers": {
     "L0": { "enabled": false },
-    "L1": { "enabled": true },
+    "L1": { "enabled": true, "rules": {} },
     "L2": { "enabled": true },
     "L3": { "enabled": true },
     "L4": { "enabled": false }
@@ -212,22 +198,170 @@ npx phasegate update-skills
   },
   "phaseDependencies": {
     "preset": "standard",
-    "override": false,
     "storyReflection": { "enabled": true }
   },
   "protectedFiles": {
-    "exclude": ["tsconfig.json", "package.json"]
-  },
-  "paths": {
-    "designDocs": "docs/product/construction",
-    "inceptionDocs": "docs/inception"
+    "exclude": ["package.json"]
+  }
+}
+```
+
+### project.preset -- レイヤー厳密度
+
+| プリセット | 有効レイヤー | カバレッジ | 用途 |
+|---|---|---|---|
+| **minimal** | L1, L2 | -- | プロトタイプ・学習 |
+| **standard** | L1-L3 | 90% | 通常開発（デフォルト） |
+| **strict** | L1-L4 | 95% | 本番・エンタープライズ |
+
+### layers.L1.rules -- AST ルール設定
+
+L1 の各ルールを `"error"` / `"warning"` / `"off"` で個別に制御できます。省略したルールはデフォルト `"error"` で適用されます。
+
+```jsonc
+{
+  "layers": {
+    "L1": {
+      "enabled": true,
+      "rules": {
+        "no-any-abuse": "warning",
+        "no-comment-flood": "off"
+      }
+    }
   }
 }
 ```
 
+| ルール | コード | チェック内容 |
+|---|---|---|
+| `require-unit-comment` | L1-001 | `@unit` アノテーションの存在 |
+| `require-layer-comment` | L1-002 | `@layer` アノテーションの存在 |
+| `no-layer-violation` | L1-003 | import グラフ解析・レイヤー依存方向違反の検出 |
+| `enforce-folder-structure` | L1-004 | フォルダ構造と宣言レイヤーの一致 |
+| `no-any-abuse` | L1-005 | `any` 型の濫用検出 |
+| `no-code-duplication` | L1-006 | コード重複の検出 |
+| `no-ghost-file` | L1-007 | 未参照ファイルの検出 |
+| `no-comment-flood` | L1-008 | 過剰コメントの検出 |
+| `it-test-mock-detection` | L1-017 | テストでの不適切なモック使用を検出 |
+| `stub-comment-detection` | L1-018 | スタブコメント（TODO/FIXME/HACK 等）の検出 |
+
+### phaseDependencies.preset -- フェーズゲート構成
+
+`project.preset` とは独立して設定します。
+
+| プリセット | ゲート | storyReflection | 用途 |
+|---|---|---|---|
+| **full** | 全 AIDLC ゲート | `logical_design` + `domain_model` required | AIDLC フルセレモニー |
+| **standard** | コアゲート | `logical_design` required | 通常開発 |
+| **minimal** | なし | 無効 | プロトタイプ |
+| **custom** | `gates[]` で定義 | `storyReflection.mappings` で定義 | 完全カスタマイズ（`override: true` 必須） |
+
+### storyReflection -- US 単位の設計反映ゲート
+
+`storyReflection` は **「inception の設計成果が product docs に反映されるまで実装をブロックする」** 仕組みです。
+
+#### 動作の仕組み
+
+`src/{unit}/` への書き込み時に、以下の検査が自動で走ります:
+
+1. `docs/inception/{unit}/` 配下のディレクトリを走査し、US-XXX / ISSUE-XXX を自動検出
+2. 検出した各 US について、inception 側のファイルが存在するかチェック
+3. 存在する場合、対応する product 側のファイルに `@story-id` アノテーションが含まれるかチェック
+4. **含まれていなければ書き込みをブロック**
+
+```
+docs/inception/my-unit/US-001/logical_design.md  ← 存在する
+docs/product/construction/my-unit/logical_design.md  ← @story-id US-001 がない
+→ src/my-unit/ への書き込みがブロックされる
+```
+
+#### `@story-id` アノテーションの書き方
+
+product docs に設計成果を反映する際、反映元の US/ISSUE を `@story-id` で記録します:
+
+```markdown
+<!-- docs/product/construction/my-unit/logical_design.md -->
+
+## ポート定義
+
+<!-- @story-id US-001 -->
+### UserRepository Port
+- findById(id: UserId): Promise<User>
+
+<!-- @story-id US-001, US-002 -->
+### OrderRepository Port
+- findByUserId(id: UserId): Promise<Order[]>
+```
+
+カンマ区切りで複数の US を1つのアノテーションに記載できます。
+
+#### standard プリセットのデフォルトマッピング
+
+| inception 側（検出対象） | product 側（反映先） | 必須 |
+|---|---|---|
+| `docs/inception/{unit}/{storyId}/logical_design.md` | `docs/product/construction/{unit}/logical_design.md` | **Yes**（ブロック） |
+| `docs/inception/{unit}/{storyId}/domain_model.md` | `docs/product/construction/{unit}/domain_model.md` | No（警告のみ） |
+
+カスタムマッピングも定義できます:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "standard",
+    "storyReflection": {
+      "enabled": true,
+      "mappings": [
+        {
+          "inception": "docs/inception/{unit}/{storyId}/logical_design.md",
+          "product": "docs/product/construction/{unit}/logical_design.md",
+          "required": true
+        },
+        {
+          "inception": "docs/inception/{unit}/{storyId}/domain_model.md",
+          "product": "docs/product/construction/{unit}/domain_model.md",
+          "required": true
+        }
+      ]
+    }
+  }
+}
+```
+
+#### 制限事項
+
+- **特定の US だけゲートを通すことはできません** — inception に存在する全 US の反映が必要です
+- `/story-implementor --story US-001` の `--story` 引数はゲートに接続されていません。検出はファイルシステムの走査のみで行われます
+
+### quickMode -- 軽微な変更の緩和
+
+Quick Mode は以下の方法で発動します:
+
+- **CLI**: `npx phasegate ci-check --quick`
+- **スキル**: `/quick-implementor` を使用すると自動で Quick Mode が適用されます
+
+`bugfix`, `docs`, `test`, `config` カテゴリの変更では、Phase Gate と 2-Phase Execution を緩和し L1/L2 のみ維持します。
+
+**Quick Mode が拒否される条件**（フルチェックが強制されます）:
+- `domain/` 配下に新規ファイルを追加した場合
+- `*port.ts` や `*adapter.ts`（API 契約）を変更した場合
+- 新機能追加・新ドメインモデル追加に該当する変更
+
+### protectedFiles -- AI 書き込み保護
+
+以下のファイルはデフォルトで AI による直接編集から保護されます:
+
+| 保護ファイル | 理由 |
+|---|---|
+| `package.json` | 依存関係・バージョン管理 |
+| `package-lock.json` | ロックファイル |
+| `tsconfig.json` | TypeScript 設定 |
+| `biome.json` / `.biome.json` | リンター設定 |
+
+`protectedFiles.exclude` に指定すると、そのファイルの保護が解除され AI が直接編集できるようになります。保護されたファイルを編集しようとすると、PreToolUse Hook が適切なスキル（`/quick-implementor` 等）の使用をガイドします。
+
 ---
 
-## CLIコマンドリファレンス
+## CLIコマンド
 
 ```bash
 npx phasegate <command> [options]
@@ -239,248 +373,162 @@ npx phasegate <command> [options]
 |---|---|
 | `init --name <name>` | スキル展開 + phasegate.config.json 生成 |
 | `update-skills` | スキルを最新版に再デプロイ |
-| `list-features` | 利用可能な機能一覧 |
-| `enable-feature <name>` | 機能を有効化 |
-| `disable-feature <name>` | 機能を無効化 |
+| `list-features` | 利用可能な機能一覧（下表参照） |
+| `enable-feature <name>` / `disable-feature <name>` | 機能の有効化/無効化 |
 
-### 品質チェック
+利用可能な Feature flags:
 
-| コマンド | 説明 | オプション |
+| Feature | 説明 | デフォルト |
 |---|---|---|
-| `lint` | L1 Biome AST チェック | `--target <path>` `--json` |
-| `validate` | L2〜L4バリデータ実行 | `--layer L1\|L2\|L3\|L4\|all` `--unit <name>` `--format human\|agent\|ci` |
-| `ci-check` | CIフルチェック (L2-L4) | `--quick` `--fail-on-reject` `--dry-run` `--files` |
-| `validate-metadata <files>` | 実装メタデータ検証 | |
-| `check-phase-gate` | フェーズゲートチェック | `--level 1\|2\|3` |
+| `agentLessonCollection` | AI エージェントの学習ログを収集 | off (`strict` で on) |
+| `cascadeUpdate` | 下位フェーズの変更を上位設計に自動反映 | off |
+| `bundleSizeLimit` | バンドルサイズ制限チェック (KB) | off (`strict` で 500KB) |
+| `deadCodeGC` | デッドコード検出・削除 | off (`strict` で on) |
 
-### harness-api コマンド
+> **注意**: Feature flags は config への保存・読み出しは動作しますが、フラグに応じたランタイム動作は未実装です（将来バージョンで対応予定）。
 
-| コマンド | 説明 | オプション |
-|---|---|---|
-| `phasegate:status` | ハーネス全体の健全性サマリ | `--json` |
-| `phasegate:check-ready` | 全storyのPhase Gate通過状態 | `--json` |
-| `phasegate:check-phase` | 指定Unitの現在フェーズ | `--unit <unitId>` `--json` |
-| `phasegate:ci-check` | 全L3バリデータ実行結果 | `--json` |
-| `phasegate:detect-drift` | 設計-コード乖離レポート | `--json` |
-| `phasegate:lint` | harness-api経由のlint | `--target <path>` `--json` |
-| `phasegate:complete-check` | L2-L4全チェック | `--json` |
-| `phasegate:impact-analysis` | ストーリー影響範囲分析 | `<storyId>` `--json` |
-
-### ADR管理
-
-| コマンド | 説明 | オプション |
-|---|---|---|
-| `list-adrs` | ADR一覧 | `--status Proposed\|Accepted\|Deprecated\|Superseded` |
-| `validate-adr` | ADR検証 | `--all` または `<adrRef>` |
-
-### HarnessError
+### 品質チェック
 
-| コマンド | 説明 | オプション |
+| コマンド | 説明 | 主なオプション |
 |---|---|---|
-| `list-errors` | エラー定義一覧 | `--format human\|json` `--layer L0-L4` |
-| `render-errors` | エラーを人間/AI/CI向けに出力 | `--format human\|agent\|ci` |
-| `validate-fix` | 修正コード例の検証 | `--code <code>` |
-
-### スキル品質
+| `lint` | L1 Biome AST チェック | `--target <path>` `--json` |
+| `validate` | 指定レイヤーのバリデータ実行 | `--layer L1\|L2\|L3\|L4\|all` `--unit <name>` `--format human\|agent\|ci` |
+| `ci-check` | CI フルチェック (L2-L4) | `--quick` `--dry-run` `--fail-on-reject` |
+| `check-phase-gate` | フェーズゲートチェック | `--level 1\|2\|3` |
+| `validate-metadata <files>` | メタデータ検証 | |
 
-| コマンド | 説明 | オプション |
-|---|---|---|
-| `skill:execute-tdd-cycle` | TDDサイクル実行 | `--unit` `--story` `--desc` `--phase RED\|GREEN\|REFACTOR` `--passed` |
-| `skill:check-coverage` | テストカバレッジ検証 | `--story <storyId>` `--json` |
-| `skill:collect-lessons` | エージェントLesson収集 | `--story <storyId>` `--sources <paths>` `--write-artifact` |
-| `skill:apply-cascade-update` | 上位設計への影響反映 | `--story <storyId>` `--dry-run` |
-| `skill:validate-structure` | スキル構造検証 | `--file <path>` `--json` |
+### phasegate コマンド
 
-### CI/CD
+`phasegate:` プレフィックス付きのコマンドは JSON 出力に対応し、スクリプトからの利用に適しています。
 
-| コマンド | 説明 | オプション |
-|---|---|---|
-| `ci:generate-template` | CI/CDテンプレート生成 | `--preset <id>` `--type <type>` `--render` `--json` |
-| `ci:migrate-agents-md` | AGENTS.mdポインタ型移行 | `--dry-run` `--validate-only` `--json` |
-| `ci:check-repetition` | 反復エラー検出 | `--code <errorCode>` `--reset` `--json` |
+| コマンド | 説明 |
+|---|---|
+| `phasegate:status` | 全体の健全性サマリ |
+| `phasegate:check-ready` | 全 story の Phase Gate 通過状態 |
+| `phasegate:check-phase --unit <id>` | 指定 Unit の現在フェーズ |
+| `phasegate:ci-check` | 全 L3 バリデータ実行 |
+| `phasegate:detect-drift` | 設計-コード乖離レポート |
+| `phasegate:lint --target <path>` | lint 実行 |
+| `phasegate:complete-check` | L2-L4 全チェック |
+| `phasegate:impact-analysis <storyId>` | ストーリー影響範囲分析 |
 
-### 回帰テスト
+### その他
 
 | コマンド | 説明 |
 |---|---|
-| `regression:run-k-requirements` | K1-K15非交渉要件の回帰テスト |
-| `regression:run-gng-gate` | Go/No-Go Gate 3条件の回帰テスト |
-| `regression:run-agent-guard` | エージェント非依存性ガード |
-| `regression:run-k14-k15` | K14/K15 (Phase Dependency / Plan文書) 回帰テスト |
-| `regression:configure-ci-gate` | CIゲート設定 |
-| `regression:analyze-migration` | v0テスト移行分析 |
-| `regression:migrate-v0-tests` | v0テスト移行実行 |
+| `list-adrs` | ADR 一覧（`--status` でフィルタ可能） |
+| `validate-adr` | ADR 検証（`--all` または `<adrRef>`） |
+| `list-errors` | エラー定義一覧（`--layer L0-L4`） |
+| `ci:generate-template` | CI/CD テンプレート生成（`--type <type>`） |
 
-### Hooks Engine
+### Hook / 委任ラッパー
 
 | コマンド | 説明 |
 |---|---|
-| `hooks:config validate` | .harness-hooks.yml の検証 |
-| `hooks:gate-check --story <id>` | 完了ゲートチェック |
+| `hook <pre-tool-use\|post-tool-use\|stop>` | Claude Code hook を起動（stdin から JSON を読む） |
+| `pre-commit` | L2 pre-commit バリデータをステージファイルに対して実行 |
+| `delegate-sonnet [...args]` | Sonnet 4.6 委任スクリプトの透過ラッパー（`scripts/delegate-sonnet.sh` に引数を forward） |
 
-### Phase 2 拡張
-
-| コマンド | 説明 | オプション |
-|---|---|---|
-| `p2:check-freshness` | 設計文書の鮮度チェック | `--pattern <glob>` `--dry-run` `--format text\|json` |
-| `p2:validate-pointers` | ドキュメント内ファイルポインタ検証 | `--include-urls` `--format text\|json` |
-| `p2:generate-e2e-template` | E2Eテストテンプレート生成 | `--phase <phase>` `--output <path>` |
+> 開発者向けコマンド（回帰テスト、Hooks Engine、Phase 2 拡張、スキル品質）は [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) を参照してください。
 
 ---
 
-## AIDLCプロセス — スキル実行順序
+## AIDLC スキル
 
-AIDLC (AI-Driven Development Life Cycle) は設計文書が存在しない状態での実装を物理的に禁止するプロセスです。Phase Dependency Modelにより上位フェーズの成果物なしに下位フェーズへの移行は不可能です。
+AIDLC (AI-Driven Development Life Cycle) は設計 → テスト設計 → TDD 実装の順序を強制するプロセスです。各レベルの成果物が次のレベルの前提条件になります。
 
-```
-Level 1: 要求定義 — inception/_shared/ に配置
-─────────────────────────────────────────────
-/product-architect   プロダクト全体像の定義
-/story-writer        Who/What/Why形式のユーザーストーリー作成
-/story-mapper        MVPスコープ整理・優先順位定義
-/unit-designer       ストーリーを独立構築可能なUnitにグルーピング
-
-Level 2: Unit横断設計 — inception/{unit}/ に配置
-─────────────────────────────────────────────
-/domain-designer     DDDドメインモデル設計（集約・Entity・VO・Event）
-/logical-designer    Hexagonal Architecture設計（Port & Adapter）
-/mock-designer       UIモックアップ設計
-/environment-designer ローカル開発環境・インフラ設計
-/it-test-designer    統合テストケース設計
-/unit-test-designer  ユニットテストケース設計
-/it-test-logic-designer    IT Vitest実装ロジック設計
-/unit-test-logic-designer  UT Vitest実装ロジック設計
-
-Level 3: ストーリー実装 — inception/{unit}/{US-XXX}/ に配置
-─────────────────────────────────────────────
-/logical-designer    US固有の論理設計
-/scenario-test-designer    E2Eシナリオテストケース設計
-/scenario-test-logic-designer  PlaywrightE2Eテスト実装ロジック設計
-/uiux-designer       最終UI/UX定義
-/implementation-readiness-checker  実装開始前の準備状況検証
-/story-implementor   TDD実装 (Red→Green→Refactor)
-```
+### 使い方
 
-**フェーズ間の依存ルール:**
-- Level 2はLevel 1の`unit-designer`完了が必須
-- Level 3はLevel 2の`domain_model.md`・`logical_design.md`の存在が必須
-- `story-implementor`の前に少なくとも1つのテスト設計フェーズが必須（緩和不可）
+Claude Code セッション内でスラッシュコマンドとして実行します:
 
----
+```
+/product-architect          ← Level 1 の最初のスキル
+/story-implementor          ← Level 3 の実装スキル
+/quick-implementor          ← バグ修正など軽微な変更
+```
 
-## スキル一覧 (28スキル)
+各スキルは前のレベルの成果物を入力として参照します。前提条件が未完了の場合、フェーズゲートがブロックします。
 
-### Foundation (4スキル)
+### Level 1: 要求定義（成果物: `docs/inception/_shared/`）
 
-| スキル | 説明 |
+| スキル | 目的 |
 |---|---|
-| `/product-architect` | ビジネス要求からプロダクト全体像を定義 |
-| `/story-writer` | Who/What/Why形式のユーザーストーリーと受け入れ基準を作成 |
-| `/story-mapper` | ストーリーのMVPスコープ整理・優先順位定義 |
-| `/unit-designer` | ストーリーを独立構築可能なUnitにグルーピングし統合契約を定義 |
-
-### Design (5スキル)
+| `/product-architect` | プロダクト全体像（ドメイン・アーキテクチャ・制約）を定義 |
+| `/story-writer` | Who/What/Why 形式のユーザーストーリーと受け入れ基準を作成 |
+| `/story-mapper` | MVP スコープ整理・優先順位定義 |
+| `/unit-designer` | ストーリーを独立構築可能な Unit にグルーピング |
 
-| スキル | 説明 |
-|---|---|
-| `/domain-designer` | DDDドメインモデル設計（集約・Entity・VO・イベント） |
-| `/logical-designer` | Hexagonal Architecture設計（Port & Adapter）。横断設計とUS固有設計の2モード |
-| `/mock-designer` | UIモックアップ設計。UI/UXの検証とフィードバック |
-| `/uiux-designer` | テストケース・論理設計・既存UIを加味して最終UI/UX定義を策定 |
-| `/environment-designer` | ローカル開発環境・インフラ構成設計 |
+### Level 2: Unit 設計（成果物: `docs/inception/{unit}/`）
 
-### Test Engineering (7スキル)
+Level 1 の `/unit-designer` 完了が前提条件。
 
-| スキル | 説明 |
+| スキル | 目的 |
 |---|---|
-| `/unit-test-designer` | ドメインモデルからユニットテストケースを設計 |
-| `/it-test-designer` | 論理設計から統合テストケースを設計 |
-| `/scenario-test-designer` | E2Eシナリオテストケースを設計 |
-| `/unit-test-logic-designer` | Vitest実装ロジックを設計（疑似コード付き詳細設計） |
-| `/it-test-logic-designer` | IT Vitest実装ロジックを設計 |
-| `/scenario-test-logic-designer` | Playwright実装ロジックを設計 |
-| `/test-coverage-checker` | テストカバレッジ検証・Nyquist Validation |
+| `/domain-designer` | DDD ドメインモデル設計（集約・Entity・VO・イベント） |
+| `/logical-designer` | Hexagonal Architecture 設計（Port & Adapter） |
+| `/mock-designer` | UI モックアップ設計 |
+| `/environment-designer` | ローカル開発環境・インフラ設計 |
+| `/unit-test-designer` | ユニットテストケース設計 |
+| `/it-test-designer` | 統合テストケース設計 |
+| `/unit-test-logic-designer` | UT Vitest 実装ロジック設計 |
+| `/it-test-logic-designer` | IT Vitest 実装ロジック設計 |
 
-### Implementation (4スキル)
+### Level 3: ストーリー実装（成果物: `docs/inception/{unit}/{US-XXX}/`）
 
-| スキル | 説明 |
+Level 2 の `domain_model.md` + `logical_design.md` の存在が前提条件。
+
+| スキル | 目的 |
 |---|---|
-| `/story-implementor` | 論理設計+環境設計に基づくTDD実装。Atomic commit付き |
-| `/quick-implementor` | Quick Mode下でのad-hoc実装（バグ修正・ドキュメント修正等） |
-| `/implementation-planner` | Unit仕様とドメインモデル設計を元に実装計画を立案 |
-| `/implementation-readiness-checker` | 実装開始前の準備状況を自動検証 |
+| `/logical-designer` | US 固有の論理設計 |
+| `/uiux-designer` | 最終 UI/UX 定義 |
+| `/scenario-test-designer` | E2E シナリオテストケース設計 |
+| `/scenario-test-logic-designer` | Playwright E2E 実装ロジック設計 |
+| `/implementation-readiness-checker` | 実装開始前の準備状況検証 |
+| `/story-implementor` | TDD 実装 (Red -> Green -> Refactor) |
+| `/quick-implementor` | 軽微変更の高速実装（バグ修正・ドキュメント等） |
 
-### Verification (8スキル)
+### Verification スキル（任意のタイミングで使用）
 
-| スキル | 説明 |
+| スキル | 目的 |
 |---|---|
-| `/consistency-checker` | AIDLC設計文書群のレイヤー間整合性チェック・矛盾/漏れ検出 |
-| `/cascade-updater` | 下位フェーズの発見・変更を上位設計文書にフィードバック |
-| `/codex-delegator` | Codex CLIにタスクを委任し、Claude Codeがマネージャーとして品質管理 |
-| `/codebase-mapper` | 全ソースファイルの @unit/@layer アノテーションを解析し構造マップを生成 |
-| `/doc-freshness-checker` | 設計文書の鮮度チェック（L4バリデータ拡張） |
-| `/pointer-validator` | 設計文書内のファイルポインタ有効性を検証 |
-| `/engineering-perspective` | ケントベック+マーティンファウラー+アンクルボブ+エリックエヴァンスの視点で設計レビュー |
-| `/skill-creator` | AgentSkillsを作成・更新 |
+| `/consistency-checker` | 設計文書間の整合性チェック |
+| `/cascade-updater` | 下位フェーズの発見を上位設計にフィードバック ※未完成 |
+| `/codex-delegator` | Codex CLI にタスクを委任し品質管理 |
+| `/codebase-mapper` | `@unit`/`@layer` アノテーションから構造マップ生成 |
+| `/doc-freshness-checker` | 設計文書の鮮度チェック |
+| `/pointer-validator` | 設計文書内のファイルパス参照を検証 |
+| `/engineering-perspective` | Beck/Fowler/Martin/Evans の視点で設計レビュー |
+| `/test-coverage-checker` | カバレッジ検証・Nyquist Validation |
+| `/implementation-planner` | 実装計画の立案 |
+| `/skill-creator` | スキルの作成・更新 |
 
 ---
 
-## メタデータ規約 (@unit / @layer / @story)
-
-全ソースファイルの先頭にメタデータコメントを記載します。これによりL1検証・トレーサビリティ・drift-detectionが機能します。
+## メタデータ規約
 
-### 実装ファイル
+全ソースファイルの先頭に `@unit` / `@layer` コメントを記載します。テストファイルには `@story` も追加します。
 
 ```typescript
 // @unit config-foundation
 // @layer domain
+// @story US-001          ← テストファイルのみ
 
 export class ConfigSchema { ... }
 ```
 
-`@layer` の有効値: `domain` / `application` / `infrastructure` / `presentation`
-
-### テストファイル
-
-```typescript
-// @unit config-foundation
-// @layer domain
-// @story US-001
-
-describe('ConfigSchema', () => {
-  it('バリデーションルールが正しく適用される', () => {
-    // Arrange
-    const actual = ...;
-
-    // Act
-    ...
-
-    // Assert
-    expect(actual).toBe(...);
-  });
-});
-```
-
-### 設計文書 (累積更新時)
-
-`product/construction/{unit}/` 配下の設計文書を更新する際は、更新箇所に起源USを記録します。
-
-```markdown
-## エンティティ: ConfigSchema
-
-@US-001
-- name: string（必須）
-- version: SemVer
+| タグ | 値の決め方 | 例 |
+|---|---|---|
+| `@unit` | `/unit-designer` スキルが定義した Unit 名を使用。手動の場合はドメインの論理グループ名 | `config-foundation`, `validator-system` |
+| `@layer` | ファイルの役割に応じて4値から選択 | `domain` / `application` / `infrastructure` / `presentation` |
+| `@story` | テストが検証するユーザーストーリーの ID | `US-001`, `US-003` |
 
-@US-003
-- validationRules: ValidationRule[]（バリデーション拡張）
-```
+これにより L1 検証（`require-unit-comment`, `require-layer-comment`）・トレーサビリティ・drift-detection が機能します。タグが欠けているファイルは L1 でエラーになります（`layers.L1.rules` で緩和可能）。
 
 ---
 
-## Claude Code Hooks 統合
+## Claude Code Hooks
 
-`.claude/settings.json` に以下を設定するとClaude Codeとのネイティブ統合が有効になります。
+`.claude/settings.json` に以下を設定すると、ファイル書き込み時に自動でゲートチェックと lint が実行されます。
 
 ```jsonc
 {
@@ -518,178 +566,36 @@ describe('ConfigSchema', () => {
 
 | Hook | タイミング | 動作 |
 |---|---|---|
-| **PreToolUse** | ファイル書き込み前 | Phase Gate強制・保護ファイルへの変更をブロック・**Bash経由の書き込み検出（`sed -i`, `tee`, `cp`, `mv`, リダイレクト）**。ブロック時はアクショナブルなエラーメッセージ（違反理由・不足成果物・次に使うべきスキル）を返却 |
-| **PostToolUse** | ファイル書き込み後 | Biome ASTルールを自動実行、違反があれば即時フィードバック |
-| **Stop** | セッション終了前 | `phasegate:complete-check` (L2-L4全チェック) を実行、全グリーンでないとセッション終了を保留 |
-
-### PreToolUse エラーメッセージ (v0.9.0)
-
-PreToolUse Hook がブロックした際、AIエージェントが自律的に正しい行動を取れるよう、具体的なエラーメッセージを返します。
-
-**フェーズゲート違反:**
-
-```
-フェーズゲート違反: scripts/harness/config-foundation/domain/test.ts
-対象スコープ: Level 3 (実装), Unit: config-foundation
-ブロック理由:
-  - 成果物が不足しています: docs/product/construction/config-foundation/domain_model.md
-  - plan文書が不足しています: 2:logical-designer
-次のアクション: /story-implementor スキルを使用して設計フェーズから開始してください。
-  実行例: /story-implementor --unit config-foundation
-```
-
-**保護ファイル:**
-
-```
-保護ファイルへの書き込みがブロックされました: package.json
-バージョン変更を含む package.json の更新は /quick-implementor スキルを使用してください。
-```
-
-対象の保護ファイルに応じて、`/quick-implementor`、`/update-config`、CLI経由の変更など適切なガイダンスが表示されます。
-
-### オプション: シェルスクリプトフック
-
-`.claude/scripts/` 配下に以下のオプションフックを配置できます。
-
-```jsonc
-// .claude/settings.json に追記
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [{
-          "type": "command",
-          "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/deny-check.sh"
-        }]
-      }
-      // ... 既存の Write|Edit フック
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/format-settings-hook.sh"
-          },
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/format-typescript-hook.sh"
-          },
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/scripts/analyze-errors-hook.sh"
-          }
-          // ... 既存の post-tool-use-hook.ts
-        ]
-      }
-    ]
-  }
-}
-```
-
-| スクリプト | 動作 |
-|---|---|
-| `deny-check.sh` | 危険な git/bash コマンド（`git reset --hard`, `rm -rf` 等）をブロック |
-| `format-settings-hook.sh` | `settings.json` 編集時に JSON を自動整形 |
-| `format-typescript-hook.sh` | TypeScript ファイル編集時に自動フォーマット（Biome / ESLint+Prettier 切替可能） |
-| `analyze-errors-hook.sh` | TypeScript ファイル編集時に tsc / lint エラーを検出しフィードバック |
-
-### hook-config.json
-
-`format-typescript-hook.sh` と `analyze-errors-hook.sh` は `.claude/scripts/hook-config.json` で対象ディレクトリとフォーマッタを設定します。
+| **PreToolUse** | Write/Edit/Bash 実行前 | フェーズゲート違反・保護ファイルへの書き込み・Bash 経由の書き込み(`sed -i`, `tee` 等)をブロック |
+| **PostToolUse** | Write/Edit 実行後 | Biome AST ルールを自動実行、違反を即時フィードバック |
+| **Stop** | セッション終了前 | L2-L4 全チェックを実行、全グリーンでないと終了を保留 |
 
-```json
-{
-  "targetDirs": ["scripts/harness"],
-  "formatter": "biome",
-  "formatterArgs": ["check", "--write"]
-}
-```
+ブロック時は違反理由・不足している設計文書・次に実行すべきスキルを含むエラーメッセージが返されます。
 
-| フィールド | 説明 | デフォルト |
-|---|---|---|
-| `targetDirs` | フックが適用されるディレクトリのリスト（プロジェクトルートからの相対パス） | `[]`（空の場合スキップ） |
-| `formatter` | `"biome"` または `"eslint-prettier"` | `"biome"` |
-| `formatterArgs` | フォーマッタに渡す引数 | `["check", "--write"]` |
+> **オプション**: `.claude/scripts/` 配下にシェルスクリプトフック（deny-check, format, analyze-errors 等）を追加配置できます。詳細は [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md#オプション-シェルスクリプトフック) を参照してください。
 
 ---
 
-## Quick Mode
+## カスタムフェーズゲート
 
-軽微な変更（バグ修正、ドキュメント修正、テスト追加、設定変更）に対してハーネスの一部を緩和するモード。
+デフォルトでは AIDLC フェーズ依存モデルが適用されますが、`gates[]` 配列で独自のゲートを定義できます。
 
-```bash
-npx phasegate ci-check --quick
-```
+### ゲート定義
 
-| レイヤー | 通常モード | Quick Mode |
+| フィールド | 型 | 説明 |
 |---|---|---|
-| L1 Biome | 有効 | **有効**（維持） |
-| L2 Pre-commit | 有効 | **有効**（維持） |
-| L3 CI | 有効 | **securityのみ** |
-| L4 Scheduled | 有効 | **スキップ** |
-| Phase Gate | 必須 | **緩和** |
-| 2-Phase Execution | 必須 | **緩和** |
-
-`phasegate.config.json` でQuick Modeの適用条件を定義します。
-
-```jsonc
-{
-  "quickMode": {
-    "allowedCategories": ["bugfix", "docs", "test", "config"],
-    "maintainedLayers": ["L1", "L2"],
-    "relaxedGates": ["phase-gate", "2-phase-execution"]
-  }
-}
-```
-
-**Quick Mode適用の除外** (フルハーネス必須):
-- 新機能追加
-- API契約変更
-- 新ドメインモデル追加
-
----
-
-## プリセット
-
-`phasegate.config.json` のプリセットは **2 系統** あります。
-
-### `project.preset` — レイヤー厳密度（L1-L4 有効化とカバレッジ閾値）
-
-| プリセット | 用途 | 有効レイヤー | カバレッジ閾値 |
-|---|---|---|---|
-| **minimal** | 学習・プロトタイプ | L1, L2 | — |
-| **standard** | 通常開発 | L1, L2, L3 | 90% |
-| **strict** | 本番・エンタープライズ | L1-L4 | 95% |
-
-`strict` プリセット追加機能:
-- L4 スケジュール検証（週次drift-detect・dead-code検出）
-- `agentLessonCollection: true`
-- `bundleSizeLimit: 500 KB`
-- `deadCodeGC: true`
-
-### `phaseDependencies.preset` — フェーズゲート構成と storyReflection デフォルト
-
-`project.preset` とは独立。`"default"` は後方互換のため `"full"` にフォールバックされます。
-
-| プリセット | Phase 3 ゲート | storyReflection デフォルト | 用途 |
-|---|---|---|---|
-| **full** | 全 AIDLC ゲート | 有効 — `logical_design` + `domain_model` required、`uiux` optional | AIDLC フルセレモニー（旧 `default`） |
-| **standard** | コアゲート | 有効 — `logical_design` required、`domain_model` optional | 通常開発・中庸な厳密度 |
-| **minimal** | なし | 無効 — inception → product 反映強制なし | プロトタイプ・試行錯誤段階 |
-| **custom** | ユーザー定義 | `storyReflection.mappings` で定義 | 完全カスタマイズ（`override: true` 必須） |
-
-`storyReflection` は inception の US/issue 設計が `docs/product/construction/{unit}/` に反映されていない場合に `src/{unit}/*` への Write/Edit をブロックします。config で省略した場合はプリセットのデフォルト mappings がゼロコンフィグで自動適用されます。`cascade-updater` スキルがこのゲートを通過する標準手段です。詳細は [ADR-013](docs/ADR/ADR-013-story-reflection-gate.md) と [Configuration guide](docs/guide/configuration.md#storyreflection-inception--product-gate) を参照してください。
-
----
+| `name` | string | ゲートの一意識別子 |
+| `level` | 1 \| 2 \| 3 | フェーズレベル（上位は下位の通過が前提） |
+| `blocks` | string[] | 保護するファイルの glob パターン |
+| `requires` | string[] | 書き込み前に存在が必要なファイル |
+| `dependsOn` | string[] | 事前に通過が必要な他のゲート名 |
+| `description` | string | ゲートの説明 |
 
-## カスタムフェーズゲート
+ゲートは DAG（有向非巡回グラフ）を形成します。循環依存は設定読み込み時に拒否されます。
 
-デフォルトでは **AIDLCフェーズ依存モデル** が適用され、設計文書なしでの実装ファイル書き込みがブロックされます。`standard` または `full` プリセットでゼロコンフィグで動作します。
+### 例 1: API スキーマファーストゲート
 
-AIDLCを使わないプロジェクトでは、`phasegate.config.json` の `gates[]` 配列で **独自のゲート** を定義できます:
+AIDLC を使わないプロジェクトで「OpenAPI スキーマなしに API 実装を書けない」を強制する例:
 
 ```jsonc
 {
@@ -709,212 +615,144 @@ AIDLCを使わないプロジェクトでは、`phasegate.config.json` の `gate
 }
 ```
 
-| フィールド | 型 | 説明 |
-|---|---|---|
-| `name` | string | ゲートの一意識別子 |
-| `level` | 1 \| 2 \| 3 | フェーズレベル（上位レベルは下位レベルのゲート通過が前提） |
-| `blocks` | string[] | このゲートが保護するファイルのglobパターン |
-| `requires` | string[] | ブロック対象パスへの書き込み前に存在が必要なファイル |
-| `dependsOn` | string[] | 事前に通過が必要な他のゲート名 |
-| `description` | string | ゲートの説明 |
+### 例 2: AIDLC フローを明示的に定義
 
-ゲートは **DAG**（有向非巡回グラフ）を形成します。循環依存は設定読み込み時に拒否されます。
-
----
-
-## CI/CD テンプレート
+[docs/folder_management_rules.md](docs/folder_management_rules.md) の **inception → product → source** フローを段階的にゲートする例:
 
-```bash
-# 3種のテンプレートを生成
-npx phasegate ci:generate-template --type aidlc-gate
-npx phasegate ci:generate-template --type pre-commit
-npx phasegate ci:generate-template --type consistency-check
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "gates": [
+      // Phase 1: プロダクト概要がないとストーリー定義に進めない
+      {
+        "name": "product-overview",
+        "level": 1,
+        "blocks": [
+          "docs/product/user_stories.md",
+          "docs/product/user_story_mapping.md"
+        ],
+        "requires": ["docs/product/product_overview.md"],
+        "description": "プロダクト概要がないとストーリー定義に進めない"
+      },
+      // Phase 1→2: Unit定義がないとUnit設計に進めない
+      {
+        "name": "unit-definition",
+        "level": 1,
+        "blocks": ["docs/product/construction/*/domain_model.md"],
+        "requires": ["docs/product/units/integration_contract.md"],
+        "dependsOn": ["product-overview"],
+        "description": "Unit定義・統合契約がないとUnit設計に進めない"
+      },
+      // Phase 2: ドメインモデルがないと論理設計に進めない
+      {
+        "name": "domain-model",
+        "level": 2,
+        "blocks": ["docs/product/construction/*/logical_design.md"],
+        "requires": ["docs/product/construction/{unit}/domain_model.md"],
+        "dependsOn": ["unit-definition"],
+        "description": "ドメインモデルがないと論理設計に進めない"
+      },
+      // Phase 2→3: 論理設計がないと実装コードに進めない
+      {
+        "name": "implementation-gate",
+        "level": 3,
+        "blocks": ["src/**/*.ts"],
+        "requires": [
+          "docs/product/construction/{unit}/domain_model.md",
+          "docs/product/construction/{unit}/logical_design.md"
+        ],
+        "dependsOn": ["domain-model"],
+        "description": "確定版の設計文書がないと実装に進めない"
+      }
+    ],
+    "storyReflection": {
+      "enabled": true,
+      "mappings": [
+        {
+          "inception": "docs/inception/{unit}/{storyId}/logical_design.md",
+          "product": "docs/product/construction/{unit}/logical_design.md",
+          "required": true
+        }
+      ]
+    }
+  }
+}
 ```
 
-| テンプレート | 用途 | 配置先 |
-|---|---|---|
-| `aidlc-gate.yml` | PR検証ワークフロー | `.github/workflows/aidlc-gate.yml` |
-| `consistency-check.yml` | 週次整合性チェック（乖離検出時Issue自動作成） | `.github/workflows/consistency-check.yml` |
-| `.husky/pre-commit` | Pre-commitフック | `.husky/pre-commit` |
-
-手動配置する場合:
+この設定では以下の順序が強制されます:
 
-```bash
-# aidlc-gate.yml を .github/workflows/ にコピー
-npx phasegate ci:generate-template --type aidlc-gate --render > .github/workflows/aidlc-gate.yml
-
-# pre-commit フックを設定
-npx phasegate ci:generate-template --type pre-commit --render > .husky/pre-commit
-chmod +x .husky/pre-commit
+```
+product_overview.md
+  → user_stories.md / user_story_mapping.md
+    → integration_contract.md
+      → domain_model.md
+        → logical_design.md
+          → src/**/*.ts（+ storyReflection で US 単位の反映も必須）
 ```
 
----
+> **ヒント**: `standard` や `full` プリセットはこのフローの大部分をゼロコンフィグで適用します。カスタムゲートは、段階をより細かく制御したい場合や AIDLC 以外のワークフローに使います。
 
-## 回帰テスト (K1-K15)
+---
 
-非交渉要件が継続的に満たされているかを回帰テストで検証します。
+## CI/CD テンプレート
 
 ```bash
-# K1-K13 非交渉要件の回帰テスト（16件）
-npx phasegate regression:run-k-requirements
-
-# Go/No-Go Gate 品質側3条件（3件）
-npx phasegate regression:run-gng-gate
-
-# K14（Phase Dependency Model）/ K15（Plan文書必須）（2件）
-npx phasegate regression:run-k14-k15
-
-# エージェント非依存性ガード（3件）
-npx phasegate regression:run-agent-guard
+npx phasegate ci:generate-template --type aidlc-gate          # PR検証ワークフロー
+npx phasegate ci:generate-template --type pre-commit           # Pre-commitフック
+npx phasegate ci:generate-template --type consistency-check    # 週次整合性チェック
 ```
 
-JSON出力:
+`--render` オプションでファイルに直接出力できます:
 
 ```bash
-npx phasegate regression:run-k-requirements --format json
+npx phasegate ci:generate-template --type aidlc-gate --render > .github/workflows/aidlc-gate.yml
 ```
 
-**非交渉要件 (K1-K15) 概要:**
-
-| # | 要件 |
-|---|---|
-| K1 | 5層防御モデル（L0-L4） |
-| K2 | Phase Gate（設計→実装の順序強制） |
-| K3 | Biome AST解析（importグラフ+循環依存検出） |
-| K3.5 | @unit/@layer/@US-XXXメタデータ |
-| K4 | テスト品質ルール（AAA / actual / no-domain-mock等） |
-| K5 | DDD設計スキル群 |
-| K6 | 2-Phase Execution（AI安全メカニズム） |
-| K7 | Document Split（inception/product分離） |
-| K8 | Cascade Updater |
-| K9 | Agent-Lesson System |
-| K10 | Security/Performance検出 |
-| K11 | Drift Detection（双方向） |
-| K12 | Consistency Checker |
-| K13 | phasegate.config.json（品質設定SSOT） |
-| K14 | Phase Dependency Model（3層フェーズ構造） |
-| K15 | Plan文書の必須生成 |
+> **既知の問題**: `--preset` オプションでデフォルトプリセットが見つからないエラーが発生する場合があります。`--preset` を省略して実行してください。
 
 ---
 
-## ディレクトリ構造
-
-### ハーネスの内部構造
-
-```
-phasegate/
-├── scripts/harness/
-│   ├── main.ts                      # CLIエントリポイント
-│   ├── harness-error/               # HarnessError定義・ADR参照
-│   ├── config-foundation/           # phasegate.config.json 解析・スキーマ
-│   ├── traceability-model/          # @unit/@layer/@story メタデータ管理
-│   ├── phase-dependency-model/      # フェーズ依存関係・Phase Gate
-│   ├── adr-foundation/              # ADR管理
-│   ├── biome-ast-engine/            # Biome AST解析エンジン
-│   ├── validator-system/            # L0-L4バリデータシステム
-│   ├── nyquist-validation/          # 要件-テストトレーサビリティ
-│   ├── harness-api/                 # harness:* コマンドCLI層
-│   ├── quick-mode/                  # Quick Mode判定・緩和実行
-│   ├── agent-integration/           # Claude Code Hooks アダプタ
-│   ├── skill-quality/               # TDDサイクル・カバレッジ・Cascade Update
-│   ├── ci-governance/               # CI/CDテンプレート・反復エラー監視
-│   ├── regression-suite/            # K1-K15回帰テストスイート
-│   ├── fuse-hooks-engine/           # Hooks Engine (.harness-hooks.yml・完了ゲート)
-│   └── phase2-extensions/           # freshness/pointer/e2e-template (v2)
-├── skills/                          # 28スキル (npx phasegate init で .claude/skills/ に展開)
-├── templates/
-│   └── phasegate.config.json          # 設定テンプレート
-└── docs/
-    ├── principles/                  # アーキテクチャ哲学・テスト規約
-    └── product/                     # ハーネス自身の設計文書
-```
-
-### 導入後のプロジェクト構造
+## 導入後のプロジェクト構造
 
 ```
 your-project/
-├── phasegate.config.json              # 品質設定（ハーネスのSSoT）
+├── phasegate.config.json         # 品質設定（Single Source of Truth）
 ├── docs/
-│   ├── folder_management_rules.md   # ドキュメント配置ルール
-│   ├── principles/
-│   │   ├── architecture-philosophy.md
-│   │   └── testing-rules.md
-│   ├── product/                     # 確定版設計文書
+│   ├── folder_management_rules.md
+│   ├── principles/               # アーキテクチャ哲学・テスト規約
+│   ├── product/                  # 確定版設計文書
 │   │   ├── <product>_overview.md
-│   │   ├── units/                   # Unit仕様書
-│   │   │   └── {unit_name}.md
-│   │   └── construction/            # レイヤー設計文書
-│   │       └── {unit_name}/
-│   │           ├── domain_model.md
-│   │           ├── logical_design.md
-│   │           └── ...
-│   ├── inception/                   # AIDLCが生成する設計計画文書
-│   │   ├── _shared/                 # Level 1 (Product全体設計)
-│   │   │   ├── product_overview_plan.md
-│   │   │   └── unit_design_plan.md
-│   │   └── {unit_name}/             # Level 2/3 (Unit/US単位)
-│   │       ├── domain_model_plan.md
-│   │       └── {US-XXX}/
-│   │           └── tdd_implementation_plan.md
-│   └── ADR/                         # Architecture Decision Records
-│       └── ADR-001-*.md
-├── src/                             # 実装コード（@unit/@layer 必須）
+│   │   ├── units/{unit}.md
+│   │   └── construction/{unit}/
+│   │       ├── domain_model.md
+│   │       └── logical_design.md
+│   ├── inception/                # AIDLC が生成する設計計画文書
+│   │   ├── _shared/             # Level 1（プロダクト全体）
+│   │   └── {unit}/{US-XXX}/     # Level 2/3（Unit・ストーリー単位）
+│   └── ADR/
+├── src/                          # 実装コード（@unit/@layer 必須）
 └── .claude/
-    ├── CLAUDE.md
-    ├── settings.json                # Hooks設定
-    └── skills/                      # npx phasegate init で展開（gitignore推奨）
+    ├── settings.json             # Hooks 設定
+    └── skills/                   # npx phasegate init で展開
 ```
 
-### .gitignore 推奨設定
+### 推奨 .gitignore
 
 ```
 node_modules/
-.claude/skills/          # npx phasegate init で再生成可能
+.claude/skills/    # npx phasegate init で再生成可能
 dist/
 reports/
-.harness/
 ```
 
 ---
 
-## バージョン管理
+## 開発者向けドキュメント
 
-Semantic Versioning (MAJOR.MINOR.PATCH) を採用しています。
-
-| 変更種別 | バージョン |
-|---|---|
-| バグ修正・小改善 | PATCH (例: v1.1.0 → v1.1.1) |
-| スキル追加・新コマンド追加 | MINOR (例: v1.1.0 → v1.2.0) |
-| 設定スキーマ変更など破壊的変更 | MAJOR (例: v1.x.x → v2.0.0) |
-
-### リリース手順 (ハーネス側)
-
-```bash
-npm version patch   # または minor / major
-git push origin main --tags
-```
-
-### アップデート手順 (利用側プロジェクト)
-
-```bash
-# semver範囲内で最新版に更新
-npm update phasegate
-
-# スキルを最新版に同期
-npx phasegate update-skills
-```
-
-> メジャーバージョンアップ時のみ `package.json` の `semver:^X.Y.Z` を手動で更新してください。
-
----
-
-## ロードマップ
-
-| バージョン | 内容 |
-|---|---|
-| **v1.6.0 (v1 MVH)** | L1-L4・28スキル・Claude Code Hooks・Nyquist Validation・K1-K15回帰テスト完備 |
-| **v2.0.0** | Hooks Engine（.harness-hooks.yml設定・完了ゲート）・Phase 2拡張（doc-freshness・pointer-validator・Playwright E2Eテンプレート） |
+phasegate 自体の開発（内部アーキテクチャ、回帰テスト、リリース手順等）については [DEVELOPMENT.ja.md](DEVELOPMENT.ja.md) を参照してください。
 
 ---
 
-*Last updated: 2026-04-06 — v0.31.0*
+*Last updated: 2026-04-07 -- v0.33.0*