phasegate 0.15.0 → 0.31.0

package/README.ja.md

@@ -48,6 +48,9 @@ AIエージェント（Claude Code, Codex, Cursor, その他）が生成する
 | **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`, リダイレクト等）を検出してブロック |
 
 ---
 
@@ -60,7 +63,7 @@ AIエージェント（Claude Code, Codex, Cursor, その他）が生成する
 ║  hook-config        .harness-hooks.yml設定検証              ║
 ║  gate-check         完了ゲートチェック                      ║
 ║                                                             ║
-║  実行: npx harness validate --layer L0                      ║
+║  実行: npx phasegate validate --layer L0                      ║
 ╠══════════════════════════════════════════════════════════════╣
 ║  L1  EDITOR TIME: Biome AST Rules                           ║
 ║  ─────────────────────────────────────────────────────────  ║
@@ -70,7 +73,7 @@ AIエージェント（Claude Code, Codex, Cursor, その他）が生成する
 ║  no-comment-flood       no-code-duplication                 ║
 ║  + it-test-mock-detection  + stub-comment-detection         ║
 ║                                                             ║
-║  実行: npx harness lint                                     ║
+║  実行: npx phasegate lint                                     ║
 ╠══════════════════════════════════════════════════════════════╣
 ║  L2  PRE-COMMIT: Validators                                 ║
 ║  ─────────────────────────────────────────────────────────  ║
@@ -78,7 +81,7 @@ AIエージェント（Claude Code, Codex, Cursor, その他）が生成する
 ║  metadata      @unit/@layer/@US-XXX/@story の完全性検証     ║
 ║  test-quality  AAA / actual / single-act / no-domain-mock   ║
 ║                                                             ║
-║  実行: npx harness validate --layer L2                      ║
+║  実行: npx phasegate validate --layer L2                      ║
 ╠══════════════════════════════════════════════════════════════╣
 ║  L3  CI/CD: Validators                                      ║
 ║  ─────────────────────────────────────────────────────────  ║
@@ -87,7 +90,7 @@ AIエージェント（Claude Code, Codex, Cursor, その他）が生成する
 ║  coverage      カバレッジ閾値 (standard: 90% / strict: 95%) ║
 ║  nyquist       要件→テスト双方向トレーサビリティ検証        ║
 ║                                                             ║
-║  実行: npx harness validate --layer L3                      ║
+║  実行: npx phasegate validate --layer L3                      ║
 ╠══════════════════════════════════════════════════════════════╣
 ║  L4  SCHEDULED: Validators                                  ║
 ║  ─────────────────────────────────────────────────────────  ║
@@ -95,7 +98,7 @@ AIエージェント（Claude Code, Codex, Cursor, その他）が生成する
 ║  consistency-check 文書間レイヤー整合性チェック             ║
 ║  dead-code         未使用エクスポート・到達不能コード検出   ║
 ║                                                             ║
-║  実行: npx harness validate --layer L4                      ║
+║  実行: npx phasegate validate --layer L4                      ║
 ╚══════════════════════════════════════════════════════════════╝
 ```
 
@@ -135,7 +138,7 @@ npm install --save-dev phasegate
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.14.0"
+    "phasegate": "^0.31.0"
   }
 }
 ```
@@ -147,7 +150,7 @@ npm install --save-dev phasegate
 ### 1. プロジェクト初期化
 
 ```bash
-npx harness init --name <プロジェクト名>
+npx phasegate init --name <プロジェクト名>
 ```
 
 実行されること:
@@ -183,7 +186,7 @@ claude  # プロジェクトルートで起動
 ```bash
 # ハーネスを更新後、スキルを最新版に同期
 npm update phasegate
-npx harness update-skills
+npx phasegate update-skills
 ```
 
 ---
@@ -194,25 +197,13 @@ npx harness update-skills
 
 ```jsonc
 {
-  "version": "1.0",
-  "preset": "standard",          // "minimal" | "standard" | "strict"
-  "project": {
-    "name": "my-project",
-    "architecture": "clean-architecture",
-    "paths": {
-      "source": ["src"],
-      "docs": {
-        "units": "docs/product/units",
-        "inception": "docs/inception",
-        "construction": "docs/product/construction"
-      }
-    }
-  },
+  "project": { "name": "my-project", "preset": "standard" },
   "layers": {
-    "L1_editor":    { "enabled": true },
-    "L2_precommit": { "enabled": true },
-    "L3_ci":        { "enabled": true },
-    "L4_scheduled": { "enabled": false }  // strict preset では true
+    "L0": { "enabled": false },
+    "L1": { "enabled": true },
+    "L2": { "enabled": true },
+    "L3": { "enabled": true },
+    "L4": { "enabled": false }
   },
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
@@ -220,27 +211,16 @@ npx harness update-skills
     "relaxedGates": ["phase-gate", "2-phase-execution"]
   },
   "phaseDependencies": {
-    "preset": "default",          // "default" | "custom"
-    "override": false,            // true でフェーズ依存の緩和を許可
-    "customRules": []
+    "preset": "standard",
+    "override": false,
+    "storyReflection": { "enabled": true }
   },
-  "planningMode": {
-    "default": "interactive",     // "interactive" | "embedded-qa"
-    "perPhase": {}
-  },
-  "harnesses": {
-    "agentLessonCollection": false,
-    "cascadeUpdate": false,
-    "bundleSizeLimit": 0,
-    "deadCodeGC": false
+  "protectedFiles": {
+    "exclude": ["tsconfig.json", "package.json"]
   },
   "paths": {
     "designDocs": "docs/product/construction",
     "inceptionDocs": "docs/inception"
-  },
-  "reporting": {
-    "format": "json",
-    "outputDir": "reports"
   }
 }
 ```
@@ -250,7 +230,7 @@ npx harness update-skills
 ## CLIコマンドリファレンス
 
 ```bash
-npx harness <command> [options]
+npx phasegate <command> [options]
 ```
 
 ### セットアップ
@@ -277,14 +257,14 @@ npx harness <command> [options]
 
 | コマンド | 説明 | オプション |
 |---|---|---|
-| `harness:status` | ハーネス全体の健全性サマリ | `--json` |
-| `harness:check-ready` | 全storyのPhase Gate通過状態 | `--json` |
-| `harness:check-phase` | 指定Unitの現在フェーズ | `--unit <unitId>` `--json` |
-| `harness:ci-check` | 全L3バリデータ実行結果 | `--json` |
-| `harness:detect-drift` | 設計-コード乖離レポート | `--json` |
-| `harness:lint` | harness-api経由のlint | `--target <path>` `--json` |
-| `harness:complete-check` | L2-L4全チェック | `--json` |
-| `harness:impact-analysis` | ストーリー影響範囲分析 | `<storyId>` `--json` |
+| `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管理
 
@@ -507,7 +487,7 @@ describe('ConfigSchema', () => {
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|Bash",
         "hooks": [{
           "type": "command",
           "command": "npx tsx scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts"
@@ -538,9 +518,9 @@ describe('ConfigSchema', () => {
 
 | Hook | タイミング | 動作 |
 |---|---|---|
-| **PreToolUse** | ファイル書き込み前 | Phase Gate強制・保護ファイルへの変更をブロック。ブロック時はアクショナブルなエラーメッセージ（違反理由・不足成果物・次に使うべきスキル）を返却 |
+| **PreToolUse** | ファイル書き込み前 | Phase Gate強制・保護ファイルへの変更をブロック・**Bash経由の書き込み検出（`sed -i`, `tee`, `cp`, `mv`, リダイレクト）**。ブロック時はアクショナブルなエラーメッセージ（違反理由・不足成果物・次に使うべきスキル）を返却 |
 | **PostToolUse** | ファイル書き込み後 | Biome ASTルールを自動実行、違反があれば即時フィードバック |
-| **Stop** | セッション終了前 | `harness:complete-check` (L2-L4全チェック) を実行、全グリーンでないとセッション終了を保留 |
+| **Stop** | セッション終了前 | `phasegate:complete-check` (L2-L4全チェック) を実行、全グリーンでないとセッション終了を保留 |
 
 ### PreToolUse エラーメッセージ (v0.9.0)
 
@@ -641,7 +621,7 @@ PreToolUse Hook がブロックした際、AIエージェントが自律的に
 軽微な変更（バグ修正、ドキュメント修正、テスト追加、設定変更）に対してハーネスの一部を緩和するモード。
 
 ```bash
-npx harness ci-check --quick
+npx phasegate ci-check --quick
 ```
 
 | レイヤー | 通常モード | Quick Mode |
@@ -674,7 +654,9 @@ npx harness ci-check --quick
 
 ## プリセット
 
-`phasegate.config.json` の `preset` フィールドで段階的に品質レベルを選択できます。
+`phasegate.config.json` のプリセットは **2 系統** あります。
+
+### `project.preset` — レイヤー厳密度（L1-L4 有効化とカバレッジ閾値）
 
 | プリセット | 用途 | 有効レイヤー | カバレッジ閾値 |
 |---|---|---|---|
@@ -688,15 +670,65 @@ npx harness ci-check --quick
 - `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) を参照してください。
+
+---
+
+## カスタムフェーズゲート
+
+デフォルトでは **AIDLCフェーズ依存モデル** が適用され、設計文書なしでの実装ファイル書き込みがブロックされます。`standard` または `full` プリセットでゼロコンフィグで動作します。
+
+AIDLCを使わないプロジェクトでは、`phasegate.config.json` の `gates[]` 配列で **独自のゲート** を定義できます:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "gates": [
+      {
+        "name": "schema-first",
+        "level": 3,
+        "blocks": ["src/api/**/*.ts"],
+        "requires": ["docs/api/openapi.yaml"],
+        "description": "API実装にはOpenAPIスキーマが必要"
+      }
+    ]
+  }
+}
+```
+
+| フィールド | 型 | 説明 |
+|---|---|---|
+| `name` | string | ゲートの一意識別子 |
+| `level` | 1 \| 2 \| 3 | フェーズレベル（上位レベルは下位レベルのゲート通過が前提） |
+| `blocks` | string[] | このゲートが保護するファイルのglobパターン |
+| `requires` | string[] | ブロック対象パスへの書き込み前に存在が必要なファイル |
+| `dependsOn` | string[] | 事前に通過が必要な他のゲート名 |
+| `description` | string | ゲートの説明 |
+
+ゲートは **DAG**（有向非巡回グラフ）を形成します。循環依存は設定読み込み時に拒否されます。
+
 ---
 
 ## CI/CD テンプレート
 
 ```bash
 # 3種のテンプレートを生成
-npx harness ci:generate-template --type github-actions
-npx harness ci:generate-template --type pre-commit
-npx harness ci:generate-template --type weekly-check
+npx phasegate ci:generate-template --type github-actions
+npx phasegate ci:generate-template --type pre-commit
+npx phasegate ci:generate-template --type weekly-check
 ```
 
 | テンプレート | 用途 | 配置先 |
@@ -709,10 +741,10 @@ npx harness ci:generate-template --type weekly-check
 
 ```bash
 # aidlc-gate.yml を .github/workflows/ にコピー
-npx harness ci:generate-template --type github-actions --render > .github/workflows/aidlc-gate.yml
+npx phasegate ci:generate-template --type github-actions --render > .github/workflows/aidlc-gate.yml
 
 # pre-commit フックを設定
-npx harness ci:generate-template --type pre-commit --render > .husky/pre-commit
+npx phasegate ci:generate-template --type pre-commit --render > .husky/pre-commit
 chmod +x .husky/pre-commit
 ```
 
@@ -724,22 +756,22 @@ chmod +x .husky/pre-commit
 
 ```bash
 # K1-K13 非交渉要件の回帰テスト（16件）
-npx harness regression:run-k-requirements
+npx phasegate regression:run-k-requirements
 
 # Go/No-Go Gate 品質側3条件（3件）
-npx harness regression:run-gng-gate
+npx phasegate regression:run-gng-gate
 
 # K14（Phase Dependency Model）/ K15（Plan文書必須）（2件）
-npx harness regression:run-k14-k15
+npx phasegate regression:run-k14-k15
 
 # エージェント非依存性ガード（3件）
-npx harness regression:run-agent-guard
+npx phasegate regression:run-agent-guard
 ```
 
 JSON出力:
 
 ```bash
-npx harness regression:run-k-requirements --format json
+npx phasegate regression:run-k-requirements --format json
 ```
 
 **非交渉要件 (K1-K15) 概要:**
@@ -789,7 +821,7 @@ phasegate/
 │   ├── regression-suite/            # K1-K15回帰テストスイート
 │   ├── fuse-hooks-engine/           # Hooks Engine (.harness-hooks.yml・完了ゲート)
 │   └── phase2-extensions/           # freshness/pointer/e2e-template (v2)
-├── skills/                          # 28スキル (npx harness init で .claude/skills/ に展開)
+├── skills/                          # 28スキル (npx phasegate init で .claude/skills/ に展開)
 ├── templates/
 │   └── phasegate.config.json          # 設定テンプレート
 └── docs/
@@ -830,14 +862,14 @@ your-project/
 └── .claude/
     ├── CLAUDE.md
     ├── settings.json                # Hooks設定
-    └── skills/                      # npx harness init で展開（gitignore推奨）
+    └── skills/                      # npx phasegate init で展開（gitignore推奨）
 ```
 
 ### .gitignore 推奨設定
 
 ```
 node_modules/
-.claude/skills/          # npx harness init で再生成可能
+.claude/skills/          # npx phasegate init で再生成可能
 dist/
 reports/
 .harness/
@@ -869,7 +901,7 @@ git push origin main --tags
 npm update phasegate
 
 # スキルを最新版に同期
-npx harness update-skills
+npx phasegate update-skills
 ```
 
 > メジャーバージョンアップ時のみ `package.json` の `semver:^X.Y.Z` を手動で更新してください。
@@ -885,4 +917,4 @@ npx harness update-skills
 
 ---
 
-*Last updated: 2026-04-02 — v0.11.0*
+*Last updated: 2026-04-06 — v0.31.0*

package/README.md

@@ -27,6 +27,9 @@ Works with **Claude Code, Codex, Cursor, Copilot**, or any other AI agent.
 | **Quick Mode** | Lightweight gate for bugfixes, docs, tests, and config changes |
 | **Claude Code Hooks** | Native PreToolUse / PostToolUse / Stop hook integration |
 | **HarnessError Format** | Every error includes ADR references and fix examples for AI self-correction |
+| **Configurable Phase Gates** | Define custom gates with `gates[]` in config. Default uses AIDLC phase dependencies |
+| **Protected File Control** | Configure which files are protected from AI writes via `protectedFiles.exclude` |
+| **Bash Write Detection** | Detects and blocks shell-based file writes (`sed -i`, `tee`, `cp`, `mv`, redirects) |
 | **Presets** | minimal, standard, and strict -- choose your quality level |
 
 ---
@@ -42,7 +45,7 @@ npm install --save-dev phasegate
 ### 2. Initialize
 
 ```bash
-npx harness init --name my-project
+npx phasegate init --name my-project
 ```
 
 This deploys 28 skills to `.claude/skills/` and generates `phasegate.config.json`.
@@ -157,41 +160,98 @@ Skills cover the full **AIDLC (AI-Driven Development Life Cycle)**, enforcing ph
 
 ### Presets
 
+`project.preset` -- overall layer strictness:
+
 | Preset | Layers | Coverage | Use Case |
 |---|---|---|---|
 | `minimal` | L1 + L2 | -- | Prototyping, early exploration |
 | `standard` | L1 - L3 | 90% | Production development (default) |
 | `strict` | L1 - L4 | 95% | Mission-critical systems |
 
+`phaseDependencies.preset` -- phase-gate shape and storyReflection defaults (independent of `project.preset`):
+
+| Preset | Phase 3 gates | storyReflection default | Use Case |
+|---|---|---|---|
+| `full` | All AIDLC gates | Enabled -- `logical_design` + `domain_model` required, `uiux` optional | AIDLC full ceremony (alias for legacy `default`) |
+| `standard` | Core gates | Enabled -- `logical_design` required, `domain_model` optional | Production development with moderate rigor |
+| `minimal` | None | Disabled -- no inception -> product enforcement | Prototyping / exploration |
+| `custom` | User-defined via `gates[]` array | User-defined via `storyReflection.mappings` | Full control (requires `override: true`) |
+
+`storyReflection` blocks writes to `src/{unit}/*` when an inception US/issue design exists but has not been cascaded into `docs/product/construction/{unit}/`. See [ADR-013](docs/ADR/ADR-013-story-reflection-gate.md) and the [Configuration guide](docs/guide/configuration.md#storyreflection-inception--product-gate).
+
 ### Key Configuration Sections
 
 ```jsonc
 {
-  "preset": "standard",
-  "project": { "name": "my-project", "architecture": "clean-architecture" },
+  "project": { "name": "my-project", "preset": "standard" },
   "layers": {
-    "L1_editor":    { "enabled": true },
-    "L2_precommit": { "enabled": true },
-    "L3_ci":        { "enabled": true },
-    "L4_scheduled": { "enabled": false }
+    "L0": { "enabled": false },
+    "L1": { "enabled": true },
+    "L2": { "enabled": true },
+    "L3": { "enabled": true },
+    "L4": { "enabled": false }
   },
   "quickMode": {
     "allowedCategories": ["bugfix", "docs", "test", "config"],
-    "maintainedLayers": ["L1", "L2"]
+    "maintainedLayers": ["L1", "L2"],
+    "relaxedGates": ["phase-gate", "2-phase-execution"]
   },
-  "phaseDependencies": { "preset": "default" }
+  "phaseDependencies": {
+    "preset": "standard",
+    "storyReflection": { "enabled": true }
+  },
+  "protectedFiles": {
+    "exclude": ["tsconfig.json", "package.json"]
+  }
 }
 ```
 
 ---
 
+## Configurable Phase Gates
+
+By default, Phasegate enforces the **AIDLC phase dependency model** -- implementation files cannot be written without prerequisite design documents. This works out of the box with the `standard` or `full` preset.
+
+For projects that don't follow AIDLC, you can define **custom gates** using the `gates[]` array in `phasegate.config.json`:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "gates": [
+      {
+        "name": "schema-first",
+        "level": 3,
+        "blocks": ["src/api/**/*.ts"],
+        "requires": ["docs/api/openapi.yaml"],
+        "description": "API implementation requires OpenAPI schema"
+      }
+    ]
+  }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Unique gate identifier |
+| `level` | 1 \| 2 \| 3 | Phase level (higher levels require lower-level gates to pass first) |
+| `blocks` | string[] | Glob patterns for files this gate protects |
+| `requires` | string[] | Files that must exist before writing to blocked paths |
+| `dependsOn` | string[] | Other gate names that must pass first |
+| `description` | string | Human-readable gate description |
+
+Gates form a **DAG** (Directed Acyclic Graph). Circular dependencies are rejected at config load time.
+
+---
+
 ## Claude Code Hooks Integration
 
 Phasegate integrates natively with Claude Code via hooks in `.claude/settings.json`:
 
 | Hook | Trigger | Behavior |
 |---|---|---|
-| `PreToolUse` | `Write` or `Edit` | Blocks writes to source files without design docs; runs Biome lint |
+| `PreToolUse` | `Write`, `Edit`, or `Bash` (write operations detected) | Blocks writes to source files without design docs; protects configured files; detects Bash write operations (`sed -i`, `tee`, `cp`, etc.) |
 | `PostToolUse` | `Write` or `Edit` | Auto-formats and validates metadata |
 | `Stop` | Session end | Runs full test suite to ensure all tests pass |
 
@@ -202,7 +262,7 @@ All hook errors use the `HarnessError` format with ADR references and fix exampl
 ## CLI Reference
 
 ```bash
-npx harness <command> [options]
+npx phasegate <command> [options]
 ```
 
 | Command | Description |
@@ -212,8 +272,8 @@ npx harness <command> [options]
 | `validate --layer <L1-L4\|all>` | Run validators for specified layer |
 | `ci-check` | Full CI check (L2-L4) |
 | `update-skills` | Update skills to latest version |
-| `harness:status` | Display overall harness health summary |
-| `harness:check-phase --unit <id>` | Check current phase for a Unit |
+| `phasegate:status` | Display overall harness health summary |
+| `phasegate:check-phase --unit <id>` | Check current phase for a Unit |
 | `list-errors --layer <L0-L4>` | List error definitions with fix examples |
 
 See the [Japanese README](README.ja.md) for the complete CLI reference.

package/bin/{harness → phasegate}

@@ -1,5 +1,5 @@
 #!/bin/sh
-# GSDLC Harness CLI entry point
+# Phasegate CLI entry point
 # tsx を使って scripts/harness/main.ts を実行するラッパー
 
 # このスクリプトの実体ファイルの場所を解決する（シンボリックリンク対応）

package/docs/ADR/ADR-013-story-reflection-gate.md

@@ -0,0 +1,100 @@
+# ADR-013: storyReflection ゲート（inception → product 反映の機械強制）
+
+## Status
+
+Accepted
+
+## Context
+
+AIDLC では US/issue ごとの設計文書が `docs/inception/{unit}/{storyId}/` 配下に作成され、Unit ごとに累積される設計文書が `docs/product/construction/{unit}/` に反映される。従来この反映は cascade-updater スキルに委ねられていたが、**手動運用のため抜け落ちが発生**し、以下の問題が顕在化した。
+
+- inception の US-XXX 設計が存在するのに product 文書へ反映されず、Unit 全体の設計整合性が崩れる
+- 実装ファイルの `@unit` → `docs/product/construction/{unit}/` のトレーサビリティが未反映 US に対して欠落する
+- cascade-updater の実行有無をレビュー時に目視確認する必要があり、ヒューマンエラーが避けられない
+
+Phase Gate（L2-001）は設計文書の**存在**を検証するが、inception と product の**整合性**（「inception にあるものが product にも反映されているか」）は検証範囲外だった。実装段階でこの欠落がブロックされなければ、設計の単一源としての product 文書が信頼できなくなる。
+
+## Decision
+
+`phaseDependencies.storyReflection` を導入し、**実装着手時（`src/` / `scripts/harness/` への Write/Edit）に inception → product 反映を機械的に検証**する。
+
+### 設計原則
+
+configurable_phase_gate_plan.md §4 から引用:
+
+- **ハードコードされたデフォルトはプリセットとして残す（後方互換）**
+- **Phase Gate / L2-002 / storyReflection / cascade-updater の 4 系統がプリセット単位で連動**
+- storyReflection の対象は **product に累積更新される設計文書のみ**（テスト設計は US 単位で inception に閉じるため対象外）
+- config 省略時はプリセットのデフォルト mappings が自動適用（**ゼロコンフィグ**）
+- cascade-updater は storyReflection ゲート通過の**唯一の標準手段**
+
+### プリセット別デフォルト
+
+| プリセット | storyReflection | デフォルト mappings |
+|-----------|-----------------|--------------------|
+| `full` | 必須 | `logical_design.md` + `domain_model.md` required、`uiux_design.md` optional |
+| `standard` | 必須 | `logical_design.md` required、`domain_model.md` optional |
+| `minimal` | 無効 | — |
+| `custom` | 任意 | config で明示指定 |
+
+`minimal` で storyReflection を無効にする理由: Phase 3 ゲートなしの状態で story 反映を強制するのは矛盾するため。
+
+### チェックロジック
+
+```
+発火条件: src/{unit}/* または scripts/harness/{unit}/* への Write/Edit
+  1. WriteTargetScope から unitId を解決（@unit 複数ユニット対応）
+  2. docs/inception/{unit}/ 配下の storyId ディレクトリを列挙
+  3. 各 storyId × 各 mapping について:
+     - inception ファイルが存在する AND mapping.required == true
+     - → product ファイル内に @story-id {storyId} が含まれているか検証
+     - 含まれていない → ブロック
+```
+
+### エラーメッセージフォーマット
+
+`HandlePreToolUseUseCase.blockReason: 'STORY_REFLECTION'` で返されるブロックメッセージは以下の形式とする（configurable_phase_gate_plan.md §4.3 より）:
+
+```
+[L2-STORY-REFLECTION] docs/product/construction/order/logical_design.md に
+@story-id US-002 が反映されていません。
+
+inception/order/US-002/logical_design.md は存在しますが、
+対応する product 文書に US-002 の設計が含まれていません。
+
+修正方法:
+  1. cascade-updater を実行して product 文書を更新
+  2. または手動で logical_design.md に @story-id US-002 を追加
+
+参照: ADR-013
+```
+
+### 関連コンポーネント
+
+- `PhaseConfigProviderPort.getStoryReflectionConfig()` — プリセット + config から有効な mappings を解決
+- `FileSystemStoryReflectionAdapter` — inception ディレクトリ列挙と product 文書内 `@story-id` 検索
+- `HandlePreToolUseUseCase` — src/ への Write 発火時に storyReflection チェックを呼び出し、未反映ならブロック
+- Quick Mode (`relaxedGates: ["phase-gate"]`) 時は storyReflection も緩和される（§4.6）
+
+## Consequences
+
+### Positive
+
+- inception → product 反映の欠落が実装着手時点で機械的にブロックされる
+- cascade-updater の実行が事実上必須化され、手動運用の抜け漏れが排除される
+- config 省略時もプリセットデフォルトで動作するため、既存ユーザーはゼロコンフィグで恩恵を受ける
+- `@unit` 複数ユニット対応と組み合わせ、共有インフラファイルでも全 Unit の反映状態が検証される
+
+### Negative / Trade-off
+
+- 実装着手時に反映漏れがあると Write/Edit がブロックされるため、cascade-updater 実行の手間が増える
+- `full` プリセットでは `domain_model.md` も required のため、軽微な変更でも反映が必要になる場合がある → `standard` または `custom` で緩和可能
+- `minimal` ではこの保証が得られない（プロトタイプ段階の試行錯誤を優先するトレードオフ）
+
+## 関連要件・文書
+
+- configurable_phase_gate_plan.md §4（Phase A: プリセット拡充 + storyReflection）
+- ADR-007（phasegate.config.json — Single Source of Truth）
+- ADR-008（Quick Mode）— storyReflection も `relaxedGates` で緩和される
+- ADR-012（2-Phase Execution）— storyReflection は Phase 2 完了の事後条件に相当
+- `docs/folder_management_rules.md` — inception / product の累積更新フロー

package/docs/guide/cli-reference.md

@@ -3,7 +3,7 @@
 Entry point:
 
 ```
-npx harness <command> [options]
+npx phasegate <command> [options]
 ```
 
 ---
@@ -38,14 +38,14 @@ Commands exposed as npm scripts (`npm run <command>`).
 
 | Command | Options | Description |
 |---|---|---|
-| `harness:status` | `--json` | Health summary |
-| `harness:check-ready` | `--json` | Phase Gate pass status for all stories |
-| `harness:check-phase` | `--unit <unitId>` `--json` | Current phase for a unit |
-| `harness:ci-check` | `--json` | All L3 validators |
-| `harness:detect-drift` | `--json` | Design-code drift report |
-| `harness:lint` | `--target <path>` `--json` | Lint via harness-api |
-| `harness:complete-check` | `--json` | L2-L4 full check |
-| `harness:impact-analysis` | `<storyId>` `--json` | Story impact analysis |
+| `phasegate:status` | `--json` | Health summary |
+| `phasegate:check-ready` | `--json` | Phase Gate pass status for all stories |
+| `phasegate:check-phase` | `--unit <unitId>` `--json` | Current phase for a unit |
+| `phasegate:ci-check` | `--json` | All L3 validators |
+| `phasegate:detect-drift` | `--json` | Design-code drift report |
+| `phasegate:lint` | `--target <path>` `--json` | Lint via harness-api |
+| `phasegate:complete-check` | `--json` | L2-L4 full check |
+| `phasegate:impact-analysis` | `<storyId>` `--json` | Story impact analysis |
 
 ---