phasegate 0.16.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`, リダイレクト等）を検出してブロック |
 
 ---
 
@@ -135,7 +138,7 @@ npm install --save-dev phasegate
 ```json
 {
   "devDependencies": {
-    "phasegate": "^0.14.0"
+    "phasegate": "^0.31.0"
   }
 }
 ```
@@ -194,25 +197,13 @@ npx phasegate 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 phasegate 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"
   }
 }
 ```
@@ -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,7 +518,7 @@ describe('ConfigSchema', () => {
 
 | Hook | タイミング | 動作 |
 |---|---|---|
-| **PreToolUse** | ファイル書き込み前 | Phase Gate強制・保護ファイルへの変更をブロック。ブロック時はアクショナブルなエラーメッセージ（違反理由・不足成果物・次に使うべきスキル）を返却 |
+| **PreToolUse** | ファイル書き込み前 | Phase Gate強制・保護ファイルへの変更をブロック・**Bash経由の書き込み検出（`sed -i`, `tee`, `cp`, `mv`, リダイレクト）**。ブロック時はアクショナブルなエラーメッセージ（違反理由・不足成果物・次に使うべきスキル）を返却 |
 | **PostToolUse** | ファイル書き込み後 | Biome ASTルールを自動実行、違反があれば即時フィードバック |
 | **Stop** | セッション終了前 | `phasegate:complete-check` (L2-L4全チェック) を実行、全グリーンでないとセッション終了を保留 |
 
@@ -674,7 +654,9 @@ npx phasegate ci-check --quick
 
 ## プリセット
 
-`phasegate.config.json` の `preset` フィールドで段階的に品質レベルを選択できます。
+`phasegate.config.json` のプリセットは **2 系統** あります。
+
+### `project.preset` — レイヤー厳密度（L1-L4 有効化とカバレッジ閾値）
 
 | プリセット | 用途 | 有効レイヤー | カバレッジ閾値 |
 |---|---|---|---|
@@ -688,6 +670,56 @@ npx phasegate 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 テンプレート
@@ -885,4 +917,4 @@ npx phasegate 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 |
 
 ---
@@ -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 |
 

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/configuration.md

@@ -27,9 +27,14 @@ This file is the **Single Source of Truth** for all quality configuration in a P
     "relaxedGates": ["phase-gate", "2-phase-execution"]
   },
   "phaseDependencies": {
-    "preset": "default",       // "default" | "custom"
+    "preset": "standard",      // "full" | "standard" | "minimal" | "custom" ("default" -> "full")
     "override": false,
-    "customRules": []
+    "customRules": [],
+    "gates": [],               // Optional. Custom phase gates (preset: "custom"). See gates[] reference below.
+    "storyReflection": {       // Optional. Defaults per preset when omitted.
+      "enabled": true,
+      "mappings": []           // Omit to use the preset's built-in mappings.
+    }
   },
   "planningMode": {
     "default": "interactive",  // "interactive" | "embedded-qa"
@@ -108,11 +113,243 @@ The five layers are:
 
 #### `phaseDependencies`
 
-| Sub-field     | Type       | Default     | Description                                                        |
-|---------------|------------|-------------|--------------------------------------------------------------------|
-| `preset`      | `string`   | `"default"` | `"default"` uses the built-in AIDLC phase dependency graph. `"custom"` enables `customRules`. |
-| `override`    | `boolean`  | `false`     | When `true`, custom rules fully replace the default graph instead of extending it. |
-| `customRules` | `array`    | `[]`        | Array of custom phase dependency rules. Only used when `preset` is `"custom"`. |
+| Sub-field          | Type       | Default      | Description                                                        |
+|--------------------|------------|--------------|--------------------------------------------------------------------|
+| `preset`           | `string`   | `"standard"` | One of `"full"`, `"standard"`, `"minimal"`, `"custom"`. `"default"` is accepted for backward compatibility and falls back to `"full"`. |
+| `override`         | `boolean`  | `false`      | When `true`, custom rules fully replace the default graph instead of extending it. Required when `preset` is `"custom"`. |
+| `customRules`      | `array`    | `[]`         | Array of custom phase dependency rules. Only used when `preset` is `"custom"`. |
+| `gates`            | `array`    | `[]`         | Array of custom phase gate definitions. See [gates\[\]](#gates-custom-phase-gates) below. Optional; defaults to empty. |
+| `storyReflection`  | `object`   | preset-based | See [storyReflection](#storyreflection-inception--product-gate) below. Omit entirely for zero-config defaults per preset. |
+
+##### Phase Dependency Presets
+
+| Preset     | Phase 3 Gates | storyReflection default                                                 | Use Case                                           |
+|------------|---------------|-------------------------------------------------------------------------|----------------------------------------------------|
+| `full`     | All gates     | **Enabled** -- `logical_design.md` + `domain_model.md` required, `uiux_design.md` optional | AIDLC full ceremony; mission-critical systems      |
+| `standard` | Core gates    | **Enabled** -- `logical_design.md` required, `domain_model.md` optional | Production development with moderate rigor        |
+| `minimal`  | None          | **Disabled**                                                            | Prototyping / exploration (trade-off: no reflection enforcement) |
+| `custom`   | User-defined  | User-defined (zero or explicit `mappings`)                              | Full control via `customRules` and `storyReflection.mappings` |
+
+> `"default"` is accepted as an alias for `"full"` so existing `phasegate.config.json` files keep working after the upgrade.
+
+#### `gates[]` (custom phase gates)
+
+`gates[]` lets a project declare **additional phase gates** that fire when a write targets specific file globs. Each gate is checked at the pre-tool-use hook (and via `check-phase-gate` CLI) and blocks the write if its preconditions are not met.
+
+`gates[]` is typically combined with `preset: "custom"` and `override: true` when the project wants full control over the phase dependency graph. It is also valid to layer a small number of gates on top of `preset: "custom"` without replacing the full graph.
+
+**Validation is fail-fast**: a malformed `gates[]` entry (e.g. `level: 99`, unknown dependency) causes `loadResolvedConfig()` to exit with code `2` and prints `Invalid phasegate.config.json: ...` to stderr. The same error surfaces as a `blocker` in the hook path.
+
+##### Gate definition schema
+
+Each entry in `gates[]` is an object with:
+
+| Field             | Type       | Required | Description                                                                                                       |
+|-------------------|------------|----------|-------------------------------------------------------------------------------------------------------------------|
+| `name`            | `string`   | yes      | Unique gate identifier. Must match `^[a-z][a-z0-9-]*$`.                                                           |
+| `level`           | `integer`  | yes      | Phase level this gate belongs to. One of `1`, `2`, `3`.                                                           |
+| `requires`        | `object[]` | yes      | Required artifacts. Each entry is `{ "path": "<glob or path>", "required": <boolean> }`.                          |
+| `blocks`          | `string[]` | yes      | Glob patterns of files the gate guards. A write targeting any matching file triggers this gate.                  |
+| `dependsOn`       | `string[]` | yes      | Names of other gates that must pass first. Forms a DAG; cycles are rejected at load time.                         |
+| `storyAnnotation` | `object`   | no       | `{ "required": <boolean>, "tag": "<tag-name>" }`. When `required: true`, matched files must contain the tag (e.g. `@story-id H01-01`). Only valid when `level: 3`. |
+
+**Rules:**
+
+- `name` must be unique across the whole `gates[]` array.
+- `level` is restricted to `1`, `2`, or `3`. `level: 99` or similar is a schema violation.
+- `dependsOn` must reference existing gate names and must not form a cycle.
+- `storyAnnotation` may only appear on `level: 3` gates (schema-enforced).
+- `blocks` uses picomatch glob syntax (e.g. `"src/**/*.ts"`, `"scripts/harness/order/**"`).
+
+##### Example 1 — single level-3 story gate
+
+Enforce that any write under `scripts/harness/order/**` carries an `@story-id` annotation:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "customRules": [],
+    "gates": [
+      {
+        "name": "order-story-impl",
+        "level": 3,
+        "requires": [
+          { "path": "docs/product/user_stories.md", "required": true }
+        ],
+        "blocks": ["scripts/harness/order/**/*.ts"],
+        "dependsOn": [],
+        "storyAnnotation": { "required": true, "tag": "@story-id" }
+      }
+    ]
+  }
+}
+```
+
+##### Example 2 — diamond DAG with multiple chains
+
+Two level-1 gates feed into a level-2 aggregate, which gates a level-3 implementation:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "customRules": [],
+    "gates": [
+      {
+        "name": "logical-design",
+        "level": 1,
+        "requires": [
+          { "path": "docs/product/construction/{unit}/logical_design.md", "required": true }
+        ],
+        "blocks": [],
+        "dependsOn": []
+      },
+      {
+        "name": "domain-model",
+        "level": 1,
+        "requires": [
+          { "path": "docs/product/construction/{unit}/domain_model.md", "required": true }
+        ],
+        "blocks": [],
+        "dependsOn": []
+      },
+      {
+        "name": "tdd-plan",
+        "level": 2,
+        "requires": [
+          { "path": "docs/inception/{unit}/{storyId}/tdd_implementation_plan.md", "required": true }
+        ],
+        "blocks": [],
+        "dependsOn": ["logical-design", "domain-model"]
+      },
+      {
+        "name": "story-impl",
+        "level": 3,
+        "requires": [],
+        "blocks": ["scripts/harness/**/*.ts"],
+        "dependsOn": ["tdd-plan"],
+        "storyAnnotation": { "required": true, "tag": "@story-id" }
+      }
+    ]
+  }
+}
+```
+
+##### Example 3 — minimal level-1 gate (no storyAnnotation)
+
+Block commits that touch a protected path unless a design artifact exists — no story-id enforcement:
+
+```jsonc
+{
+  "phaseDependencies": {
+    "preset": "custom",
+    "override": true,
+    "customRules": [],
+    "gates": [
+      {
+        "name": "schema-guard",
+        "level": 1,
+        "requires": [
+          { "path": "docs/schema/migration-notes.md", "required": true }
+        ],
+        "blocks": ["db/migrations/**/*.sql"],
+        "dependsOn": []
+      }
+    ]
+  }
+}
+```
+
+#### `storyReflection` (inception -> product gate)
+
+`storyReflection` enforces that every US / issue under `docs/inception/{unit}/{storyId}/` has been **cascaded into the accumulating product design documents** (`docs/product/construction/{unit}/`) before source code under `src/{unit}/` or `scripts/harness/{unit}/` can be written or edited.
+
+The check fires at the pre-tool-use hook and blocks `Write`/`Edit` (and their Bash equivalents such as `cat > file`, `tee`, heredoc, `sed -i`, `cp`, `mv`, `touch`) whenever an inception design exists but its `@story-id` is not reflected in the corresponding product file.
+
+**Zero-config**: omitting the `storyReflection` block, or specifying it without `mappings`, applies the preset's built-in mappings automatically.
+
+| Sub-field   | Type       | Default                 | Description                                                                  |
+|-------------|------------|-------------------------|------------------------------------------------------------------------------|
+| `enabled`   | `boolean`  | preset-dependent        | Master switch. `full` / `standard` default to `true`; `minimal` defaults to `false`. |
+| `mappings`  | `array`    | preset-dependent        | Array of inception -> product file mappings. Omit to use the preset default. |
+
+Each mapping entry:
+
+| Field       | Type      | Description                                                                 |
+|-------------|-----------|-----------------------------------------------------------------------------|
+| `inception` | `string`  | Template path, e.g. `"docs/inception/{unit}/{storyId}/logical_design.md"`. |
+| `product`   | `string`  | Template path, e.g. `"docs/product/construction/{unit}/logical_design.md"`.|
+| `required`  | `boolean` | When `true`, missing reflection blocks the write. When `false`, it is tolerated (optional mapping). |
+
+##### Preset defaults (hard-coded)
+
+**`full`** -- AIDLC recommended (product-accumulated design documents only; test designs are out of scope because they live per-US inside `inception/`):
+
+```jsonc
+[
+  { "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 },
+  { "inception": "docs/inception/{unit}/{storyId}/uiux_design.md",
+    "product":   "docs/product/construction/{unit}/uiux_design.md",
+    "required": false }
+]
+```
+
+**`standard`**:
+
+```jsonc
+[
+  { "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": false }
+]
+```
+
+**`minimal`**: `enabled: false`. No storyReflection checking.
+
+##### Custom mappings example
+
+Override the preset defaults only when your project needs a different policy:
+
+```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 }
+      ]
+    }
+  }
+}
+```
+
+##### How the check fires
+
+1. `Write` / `Edit` (or a Bash write such as `cat > src/order/foo.ts`) targets a source file under a Unit.
+2. `WriteTargetScope` resolves the `@unit` annotation (comma-separated and multi-line `@unit` are both supported; **all** listed units are checked).
+3. For each unit, every `storyId` directory under `docs/inception/{unit}/` is enumerated.
+4. For each required mapping, the pre-tool-use hook checks that the target product document contains `@story-id {storyId}`.
+5. Any missing reflection produces a `STORY_REFLECTION` block reason with a fix hint that points to the `cascade-updater` skill and [ADR-013](../ADR/ADR-013-story-reflection-gate.md).
+
+##### Passing the gate
+
+`cascade-updater` is the **standard means of passing the storyReflection gate**: run it to propagate the new US / issue design into the accumulating product documents. Manual editing of the product file with an appended `@story-id` tag is also accepted.
+
+Quick Mode with `relaxedGates: ["phase-gate"]` relaxes `storyReflection` as well (see [Quick Mode](#quick-mode)). L1 and L2 `metadata` / `test-quality` checks remain fully enforced.
 
 #### `planningMode`