phasegate 0.123.0 → 0.125.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.125.0] - 2026-05-08
+
+### Changed
+
+- **WI-089 — WI-088 guidance skills の dogfood feedback 反映 (P1, P2, P4, P5 + cohesion audit)** — v0.124.0 で追加した `phasegate-toolkit-guide` / `phasegate-config-doctor` を別 PJ で dogfood 検証した結果を反映し、UX 改善 + skill 内部の冗長 / 凝集度 / 矛盾を解消。
+  - **P1 (discoverability)**: `phasegate init` 完了メッセージの末尾に `Need help?` ブロックを追加。`skillSet !== "core"` 時に `/phasegate-toolkit-guide` (Q&A) と `/phasegate-config-doctor` (config tuning) の起動方法を案内。
+  - **P2 (fresh init shortcut)**: `phasegate-config-doctor` に **Step 1.5: Fresh init 判定** を新設。default config + 設計文書空 + Unit 構造未着手の 3 条件を全て満たすプロジェクトには「先に `/product-architect` で AIDLC を開始するのが効率的」とショートカット応答し、9 観点の機械的診断ノイズを抑制。
+  - **P4 (UX 標準化)**: `phasegate-config-doctor` Step 4 (適用フロー) を `AskUserQuestion` ベースに書き換え。提案件数に応じて 1 回確認 / WARN→SUGGEST 分割を使い分ける指針を明記。
+  - **P5 (consumer noise 削除)**: 両 skill 本文から `WI-086` / `WI-087` 等の実装履歴 WI 番号を削除し、機能ベースの記述 (例: `(v0.122 以降)` / `monorepo 自動検出`) に置き換え。consumer プロジェクトの AI に意味のない historical noise を排除。
+  - **Cohesion audit** (`phasegate-toolkit-guide`): 「重要な設計原則」と「アンチパターン」「回答プロセス」と「回答時のスタイル」「マッピングが曖昧な場合 / 設定変更を伴う質問 / アンチパターン」の 3 重複を統合。設計原則を肯定形 4 項目に正規化、回答プロセスを 4 step に統合、境界条件を 1 セクションにまとめ、アンチパターン section を削除。
+  - **Cohesion audit** (`phasegate-config-doctor`): 設計原則を 6 項目の肯定形に正規化しアンチパターン section を削除、観点 1 (schema バージョン) と観点 3 (architecture.preset) を「観点 1: architecture セクション (preset / 整合性)」に統合 (architecture key 不在判定 + 推奨 preset 推測 + custom 値検証を一体化)、Step 3 末尾の重複した「適用しますか？」列挙を Step 4 に統合、Step 4 末尾と重複していた「出力例 (簡易)」section を削除。
+  - **矛盾解消** (`phasegate-config-doctor` 観点 3 paths): default path が「実プロジェクトのパスに合っていれば OK」という曖昧条件を「Read tool でリストして存在 + 中身ありなら OK / 存在しないか空なら scaffold 期 (Step 1.5) または別配置の可能性」と判定基準を明示化。
+  - **検証**: 両 SKILL.md を `skill-creator/scripts/quick_validate.py` で再 validation pass。全 3499 テストグリーン (前回と同数、新規テストは追加せず — UX 改善 + 文章整理のため挙動変更なし)。L1 lint 違反なし。
+  - **スコープ外**: P3 (canonical doc 日本語化 / 各 doc に日本語サマリ追加) は分量大のため別 WI (WI-090 候補) で扱う。
+
+## [0.124.0] - 2026-05-08
+
+### Added
+
+- **WI-088 Phase B — bundled guidance skill `phasegate-config-doctor`** — `phasegate.config.json` の現状を schema + プロジェクト検出結果と突き合わせて改善案を **diff 形式で提案する診断スキル** を追加。Phase A の `phasegate-toolkit-guide` (read-only Q&A) と対をなす設定変更系 skill。AI による silent な書き換えを禁止し、必ずユーザー承認 → Edit → `phasegate validate --layer L2` 検証の手順を踏む。
+  - **新規ファイル**: `skills/phasegate-config-doctor/SKILL.md` を `skill-creator` skill (`init_skill.py`) 経由で作成 (validation pass)。9 診断観点 (schema バージョン / project.preset / architecture.preset / paths / quickMode / harnesses / baseline / agentIntegration.stopHook.enforce / hook-config.json) ごとに OK / WARN / SUGGEST 判定の基準と提案 diff フォーマットを定義。
+  - **設計原則**: silent 書き換え禁止 / schema を読んでから提案 / 機械検出を優先 / AI 推論は判断要素のみ・根拠提示必須 / read-only Q&A は phasegate-toolkit-guide に委譲。
+  - **skill-deployer 拡張**: `SKILL_CATEGORIES.guidance` に `phasegate-config-doctor` を追加。`getSkillsForSet("all")` に含まれるが `getSkillsForSet("core")` には含まれない (Phase A と同じ責務分離)。
+  - **テスト追加**: 4 ケース (guidance カテゴリ登録 / `getCategoryForSkill('phasegate-config-doctor') === 'guidance'` / `getSkillsForSet('all')` に含まれる / `getSkillsForSet('core')` に含まれない)。全 3499 テスト (前回 3495 + 新規 4) グリーン。
+  - **互換性**: 既存 deploy ロジックに変更なし。consumer プロジェクトで `phasegate init` 実行時、`.claude/skills/` 配下に `phasegate-toolkit-guide` (Phase A) と `phasegate-config-doctor` (Phase B) の 2 つが追加 deploy される。
+
 ## [0.123.0] - 2026-05-08
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.123.0",
+  "version": "0.125.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/main.ts

@@ -564,6 +564,12 @@ async function main(): Promise<void> {
           );
           console.log(`     See docs/guide/codex-integration.md for the native apply_patch limitation.`);
         }
+        if (skillSet !== "core") {
+          console.log("");
+          console.log("Need help?");
+          console.log("  • Q&A about phasegate concepts: invoke /phasegate-toolkit-guide");
+          console.log("  • Diagnose & tune phasegate.config.json: invoke /phasegate-config-doctor");
+        }
         process.exit(0);
         break;
       }

package/scripts/harness/setup/skill-deployer.ts

@@ -52,7 +52,7 @@ export const SKILL_CATEGORIES: Record<SkillCategory, readonly string[]> = {
     "unit-test-logic-designer",
   ],
   utility: ["codex-delegator", "skill-creator"],
-  guidance: ["phasegate-toolkit-guide"],
+  guidance: ["phasegate-toolkit-guide", "phasegate-config-doctor"],
 } as const;
 
 export function getSkillsForSet(skillSet: SkillSet): string[] {

package/skills/phasegate-config-doctor/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: phasegate-config-doctor
+description: 現在の phasegate.config.json を schema + プロジェクト検出結果と突き合わせて改善提案する診断スキル。read-only Q&A の phasegate-toolkit-guide とは異なり、設定変更を伴う相談に応える。使用タイミング:「phasegate のセットアップを最適化して」「architecture preset 入ってないけど何が適切？」「Quick Mode の relaxedGates に推奨設定教えて」「baseline 有効化しても大丈夫？」「monorepo に対して targetDirs / formatter が正しく検出されてる？」「v2 schema warning が出る、何を直せばいい？」など、現状 config の診断と改善 diff 提案を求める質問。
+---
+
+# Phasegate Config Doctor
+
+現在の `phasegate.config.json` を診断し、改善案を **diff 形式** でユーザーに提示する skill。
+
+## このスキルが解決する問題
+
+phasegate を導入した直後の config は単純な default で、実プロジェクトの構造 (monorepo / formatter 選定 / architecture style / Quick Mode の運用方針) に最適化されていない。AI が schema を知らずに勘で書き換えると壊れるため、**schema + 検出結果に基づいた決定的提案** が必要。
+
+## 設計原則
+
+1. **silent 書き換え禁止** — 提案は diff として提示し、`AskUserQuestion` で承認を取ってから Edit
+2. **検出結果を優先** — 機械的に決定可能な部分 (workspace 構造、formatter、bash 互換性) は AI 推論ではなく検出結果を採用
+3. **AI 推論は判断要素のみ** — architecture preset 選定、relaxedGates 推奨値などは AI が判断するが根拠を必ず示す
+4. **schema は enum 違反確認時のみ Read** — 日常診断は本 SKILL 内の判定基準で十分。schema 全文 Read は値域不明時に限定する
+5. **read-only な Q&A は phasegate-toolkit-guide に委譲** — 「L2 って何？」など概念質問は本 skill スコープ外
+6. **変更後は L2 検証必須** — `npx phasegate validate --layer L2` を走らせてからユーザーに完了報告
+
+## 診断プロセス
+
+### Step 1: 現状把握 (read-only)
+
+以下のファイルを Read してから診断する:
+
+| 情報源 | パス | 用途 |
+|---|---|---|
+| 現 config | `phasegate.config.json` | 診断対象 |
+| package.json | `package.json` | devDependencies (formatter 検出) / workspaces 検出 |
+| pnpm workspace | `pnpm-workspace.yaml` (存在すれば) | workspace 検出 |
+| lerna config | `lerna.json` (存在すれば) | workspace 検出 |
+| hook config | `.claude/scripts/hook-config.json` | 既存 hook 設定確認 |
+
+**schema は必要なときだけ Read** (enum 違反疑い時など): `node_modules/phasegate/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` (or `harness-config-v2.schema.json` if v2)。
+
+phasegate リポジトリ自体 (dogfood) の場合は `node_modules/phasegate/` を `scripts/harness/config-foundation/...` に置換。
+
+### Step 1.5: Fresh init 判定 (重要)
+
+以下の **全条件** を満たす場合、フル診断は早期。Step 2 に進まず AIDLC 開始を案内する:
+
+- `phasegate.config.json` が `phasegate init` 直後の default 状態 (`project.preset = "standard"` / `architecture.preset` 設定済 / `layers` / `quickMode` / `harnesses` が空 dict)
+- `docs/product/construction/` が空または存在しない
+- `scripts/`, `src/` 配下に Unit 構造 (`domain/application/infrastructure/presentation` 等) が無い
+
+**該当時の応答**:
+
+```
+このプロジェクトは phasegate init 直後の状態のため、config を最適化するより先に
+AIDLC を開始することを推奨します:
+
+  /product-architect
+
+product-architect で Unit を作り、いくつかの logical_design を書いた後で本 skill を再実行すると、
+実態に基づいた具体的な改善提案ができます。
+```
+
+該当しない場合のみ Step 2 に進む。
+
+### Step 2: 診断観点
+
+各観点で **OK / WARN / SUGGEST** のいずれかを出す。
+
+#### 観点 1: architecture セクション (preset / 整合性)
+
+- `architecture` キーが無い → v2 として扱われる → SUGGEST: `architecture: { preset: "..." }` 追加
+- `architecture.preset` 未指定 + `scripts/`, `src/` 配下のディレクトリ構造から推測 → SUGGEST:
+  - `domain/` `application/` `infrastructure/` `presentation/` の 4 層あり → `clean` 推奨
+  - DDD タクティカル (`entities/aggregates/repositories`) あり → `strict-ddd` 推奨
+  - `core/`, `adapters/`, `ports/` パターン → `hexagonal` 推奨
+  - 上記いずれも無し → ユーザーに確認 + `custom` 提案
+- 検出根拠を必ず提示 (例:「`scripts/harness/{domain,application,infrastructure,presentation}` を検出 → `clean` 推奨」)
+- `architecture.preset = "custom"` だが `architecture.layers` 未定義 → WARN: schema validator で reject される
+
+#### 観点 2: project.preset (防御プリセット)
+
+- `project.preset` 未指定 → SUGGEST: プロジェクト規模に応じて `minimal` / `standard` / `strict`
+- 値が enum 外 → WARN
+
+#### 観点 3: paths
+
+- `paths.designDocs` / `paths.inceptionDocs` が default のまま (`docs/product/construction` / `docs/inception`):
+  - 実 path を Read tool でリスト確認し、存在 + 中身あり → OK
+  - 存在しない or 空 → fresh init scaffold 期 (Step 1.5 で早期 return しているはず) または別 path に置いている可能性 → ユーザーに確認
+- default 以外で実 path に存在する → OK
+
+#### 観点 4: quickMode
+
+- `quickMode.allowedCategories` が default `['bugfix', 'docs', 'test', 'config']` のまま → プロジェクトの慣習に応じて拡張提案
+- `quickMode.relaxedGates` が空 → small team なら `['phase-gate']` 追加を SUGGEST、enterprise なら現状維持を OK
+
+#### 観点 5: harnesses (cascade / bundle / dead-code)
+
+- `cascadeUpdate: false` → AI 主導開発なら `true` 推奨 (SUGGEST)
+- `agentLessonCollection: false` → AI セッションの教訓を蓄積したいなら `true` 推奨 (SUGGEST)
+- `bundleSizeLimit: 0` → frontend プロジェクトなら値設定推奨
+
+#### 観点 6: baseline
+
+- `baseline` セクション不在 → default `enabled: true, path: .phasegate/baseline.json` (v0.117 以降)
+- 既存大規模プロジェクトに後追い導入なら baseline 有効化推奨 (新規違反のみ厳しく検査)
+
+#### 観点 7: agentIntegration.stopHook.enforce (v0.122 以降)
+
+- 未指定 (`false` 相当) → AI セッションの Stop hook 失敗を **warning のみ** で許容
+- `true` セット → Complete Check 失敗時に Claude Code の turn を hard block (exit 2)
+- 推奨: AI 主導開発で本格運用するなら `true` を SUGGEST
+
+#### 観点 8: hook-config.json (`.claude/scripts/`)
+
+- `targetDirs: ["src"]` のままで monorepo の場合 → WARN: `phasegate init` を再実行すれば monorepo 自動検出が効く (v0.120 以降)
+- `formatter: "biome"` だが `@biomejs/biome` が devDependencies に無い → WARN: prettier に切り替え推奨
+- v0.119 未満で deploy された hook script (bash 4 `mapfile` 使用) → WARN: macOS の bash 3.2 で silent fail。`phasegate init` 再実行で更新
+
+### Step 3: 診断レポート
+
+診断結果を以下の形式で提示する:
+
+````markdown
+## phasegate.config.json 診断結果
+
+### サマリ
+- ✅ OK: N 件
+- ⚠️ WARN: N 件
+- 💡 SUGGEST: N 件
+
+### ⚠️ 修正推奨 (WARN)
+
+#### W1: `architecture.preset = "custom"` だが `architecture.layers` が未定義
+- 影響: schema validator で reject される
+- 修正案:
+  ```json-diff
+  - "architecture": { "preset": "custom" }
+  + "architecture": {
+  +   "preset": "custom",
+  +   "layers": [ /* layer 定義 */ ]
+  + }
+  ```
+- 補足: layer 構造が clean / strict-ddd / hexagonal / onion / layered / flat のいずれかに該当するなら `preset: "<その値>"` のほうが簡潔
+
+### 💡 改善提案 (SUGGEST)
+
+#### S1: `architecture.preset` 未指定 → "clean" を推奨
+- 検出根拠: `scripts/harness/{domain,application,infrastructure,presentation}` の 4 ディレクトリが存在
+- 修正案:
+  ```json-diff
+   {
+     "project": { ... },
+  +  "architecture": { "preset": "clean" },
+     "layers": { ... }
+   }
+  ```
+
+### ✅ 問題なし (OK)
+- project.preset = "standard"
+- paths.designDocs / paths.inceptionDocs はデフォルト値で実プロジェクトと一致
+- baseline セクション不在 → default 有効 (v0.117+)
+````
+
+### Step 4: 適用 (AskUserQuestion 経由)
+
+提案件数に応じて使い分ける:
+
+- **提案 1-3 件**: `AskUserQuestion` 1 回で「全て適用 / 個別選択 / 適用しない」を提示
+- **提案 4 件以上**: WARN を先に `AskUserQuestion` で確認し、SUGGEST はバッチで別途確認
+
+option 設計の例 (提案 2 件、WARN 1 + SUGGEST 1 のとき):
+
+```
+question: "phasegate.config.json に提案 2 件あります。どう適用しますか？"
+options:
+  - label: "全て適用 (推奨) — W1 + S1"
+  - label: "WARN のみ適用 — W1 のみ"
+  - label: "適用しない (情報のみ受け取る)"
+```
+
+ユーザーが適用対象を確定したら `Edit` で `phasegate.config.json` を変更。
+
+**変更後の必須検証**:
+
+```bash
+npx phasegate validate --layer L2
+```
+
+L2 でエラーが出た場合は変更を **rollback** し、ユーザーに報告 (silent に進めない)。
+
+## phasegate-toolkit-guide との使い分け
+
+| 質問種別 | 使う skill |
+|---|---|
+| 「L2 って何？」「Quick Mode の仕組み教えて」(read-only Q&A) | phasegate-toolkit-guide |
+| 「config の relaxedGates 何にすべき？」(設定診断 + 提案) | phasegate-config-doctor |
+| 「monorepo 対応されてる？」(現状確認) | phasegate-toolkit-guide |
+| 「monorepo 用に config 直して」(設定変更) | phasegate-config-doctor |
+
+ユーザー質問が両方にまたがる場合は、まず phasegate-toolkit-guide で概念を説明 → ユーザーが「じゃあ修正して」と言ったら本 skill に切り替える。

package/skills/phasegate-toolkit-guide/SKILL.md

@@ -9,22 +9,23 @@ phasegate ツールキット自体の概念・仕様・設定について、ユ
 
 ## このスキルが解決する問題
 
-ユーザーが phasegate を導入したプロジェクトで、AI に phasegate 関連の質問や設定変更を依頼したとき、AI が `node_modules/phasegate/` を grep で調査して仕様を推測する非効率を防ぐ。
+ユーザーが phasegate を導入したプロジェクトで AI に phasegate 関連の質問をしたとき、AI が `node_modules/phasegate/` を grep で調査して仕様を推測する非効率を防ぐ。
 
-phasegate の概念と仕様は **canonical doc が `node_modules/phasegate/docs/guide/` 配下に同梱されている**。本 skill はそれらへの正確なポインタを提供する。
+phasegate の概念・仕様は **canonical doc が `node_modules/phasegate/docs/guide/` 配下に同梱されている**。本 skill はそれらへの正確なポインタを提供する。
 
-## 重要な設計原則
+## 設計原則
 
-**knowledge を skill 本体に固定しない**。本 SKILL.md は「どの doc を読めば答えられるか」のポインタだけを持つ。実際の概念知識は phasegate 同梱 canonical doc から動的に読み込む。
-
-これにより `npm update phasegate` で knowledge が自動追従する (skill markdown に概念本文を書いてしまうとバージョン乖離が起きる)。
+1. **canonical doc を必ず Read してから答える** — training data 依存で答えない (バージョン乖離リスク)
+2. **knowledge を skill 本体に固定しない** — skill markdown には「どの doc を読めば答えられるか」のポインタだけを書く。`npm update phasegate` で knowledge が自動追従する構造を保つ
+3. **read-only に徹する** — 「config の X を変更したい」など設定変更を伴う質問は範囲外。`phasegate-config-doctor` に委譲する
+4. **doc 全文をユーザーに貼り付けない** — 要約 + 該当セクション名引用で返す
 
 ## 回答プロセス
 
 1. ユーザー質問を以下の **概念カテゴリ** にマッピング
-2. 対応する canonical doc を **Read tool で読む**
-3. Read した内容に基づいて回答
-4. 回答内に **doc 内の該当セクションへのポインタ** を含める (ユーザーが詳細確認できるように)
+2. 対応する canonical doc を **Read tool で読む** — 長い doc は当該セクションを `offset` / `limit` で限定して読む
+3. Read した内容に基づいて簡潔に回答 (2-3 段落 + コード例 1 つ程度)
+4. 回答内に **doc 内の該当セクション名** を引用 (ユーザーが doc を直接開いたとき navigation できるように)
 
 ### canonical doc の場所
 
@@ -32,7 +33,7 @@ phasegate がインストールされたプロジェクトでは、以下のい
 
 ```
 node_modules/phasegate/docs/guide/   # npm 経由でインストールされた consumer プロジェクト
-docs/guide/                           # phasegate リポジトリ自体 (dogfood)
+docs/guide/                          # phasegate リポジトリ自体 (dogfood)
 ```
 
 **先に `node_modules/phasegate/docs/guide/` を試し**、見つからなければ `docs/guide/` を試す。
@@ -48,7 +49,7 @@ docs/guide/                           # phasegate リポジトリ自体 (dogfood
 
 **参照先**: `docs/guide/layer-model.md`
 
-**読み方**: ファイル全体を読む (各層のセクションが明確に分かれている)。
+各層 (L0 / L1 / L2 / L3 / L4) のセクションが見出しで区切られているので、質問された層のセクションのみ `offset` 指定で部分読みすると効率的。
 
 ### 2. 防御プリセット / アーキプリセット (重要: 2 系統あり)
 
@@ -75,9 +76,9 @@ docs/guide/                           # phasegate リポジトリ自体 (dogfood
 - 「relaxedGates って何のため？」
 - 「allowedCategories はどこで設定する？」
 
-**参照先**: `docs/guide/quick-vs-full-mode.md`
+**参照先**: `docs/guide/quick-vs-full-mode.md` (Mode の概念と切り替え条件)
 
-設定キーは `phasegate.config.json` の `quickMode` セクション (`allowedCategories` / `relaxedGates` / `fullModeRequiredWhen`)。詳細は `docs/guide/configuration.md` の `quickMode` セクションも併読。
+設定キー (`quickMode.allowedCategories` / `quickMode.relaxedGates` / `quickMode.fullModeRequiredWhen`) の詳細は `docs/guide/configuration.md` の `quickMode` セクション。
 
 ### 4. Hook 仕様 (PreToolUse / PostToolUse / Stop / SessionStart / UserPromptSubmit)
 
@@ -89,7 +90,7 @@ docs/guide/                           # phasegate リポジトリ自体 (dogfood
 
 **参照先**: `docs/guide/hooks-integration.md`
 
-`Responsibility Separation` セクションに pre / post / Stop の責務分担表がある (WI-086 で追加)。Stop hook の `agentIntegration.stopHook.enforce` オプションは WI-087 Phase C-2 で追加された。
+`Responsibility Separation` セクションに pre / post / Stop の責務分担表があり、Stop hook を strict mode (turn を hard block) にする `agentIntegration.stopHook.enforce` オプションもそこに記載されている。
 
 ### 5. config 全般 (`phasegate.config.json`)
 
@@ -101,7 +102,7 @@ docs/guide/                           # phasegate リポジトリ自体 (dogfood
 
 **参照先**: `docs/guide/configuration.md`
 
-各 top-level セクションごとに説明あり: `project` / `layers` / `quickMode` / `phaseDependencies` / `harnesses` / `paths` / `reporting` / `architecture` / `agentIntegration` / `protectedFiles` / `baseline`。
+各 top-level セクション (`project` / `layers` / `quickMode` / `phaseDependencies` / `harnesses` / `paths` / `reporting` / `architecture` / `agentIntegration` / `protectedFiles` / `baseline`) ごとに説明あり。
 
 ### 6. CLI コマンド一覧
 
@@ -120,7 +121,7 @@ docs/guide/                           # phasegate リポジトリ自体 (dogfood
 - 「既存プロジェクトに後から導入したい」
 
 **参照先**:
-- 新規導入: `docs/guide/installation.md`, `docs/guide/quickstart.md` (存在する場合)
+- 新規導入: `docs/guide/installation.md`
 - 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
 
 ### 8. skill 一覧と使い分け
@@ -139,28 +140,18 @@ docs/guide/                           # phasegate リポジトリ自体 (dogfood
 
 **参照先**: `docs/guide/codex-integration.md`
 
-## 回答時のスタイル
+## 境界条件
 
-- 簡潔に答える (2-3 段落 + コード例 1 つ程度)
-- canonical doc の **該当セクション名** を必ず引用 (ユーザーが doc を直接開いたときの navigation 補助)
-- 質問が複数カテゴリにまたがる場合は、最も関連性の高い doc を先に読む
-- doc を読まずに回答しない (本 skill の存在意義は「正確な情報源を引く」こと)
+### 質問が複数カテゴリにまたがる場合
 
-## マッピングが曖昧な場合
+最も関連性の高い doc を先に読み、必要なら追加で別 doc を読んで補う。
 
-ユーザー質問が上記カテゴリのいずれにも明確に当てはまらない場合:
+### マッピングが曖昧な場合
 
 1. `docs/guide/` 配下の doc 一覧 (`ls node_modules/phasegate/docs/guide/`) を取得
 2. ファイル名から推測して最も近い doc を読む
 3. それでも見つからなければ、ユーザーに **どの観点を知りたいか** を質問で絞り込む
 
-## 設定変更を伴う質問
-
-「config の X を変更したい」など **設定変更を伴う質問** は、本 skill の範囲外。phasegate-config-doctor skill (存在すれば) に委譲するか、ユーザーに「設定変更には phasegate-config-doctor を起動するのが推奨」と案内する。本 skill は **read-only な Q&A に徹する**。
-
-## アンチパターン
+### 設定変更を伴う質問
 
-- ❌ canonical doc を読まずに training data 依存で答える (バージョン乖離リスク)
-- ❌ doc 全文をユーザーに貼り付ける (要約して該当セクションへのポインタを返す)
-- ❌ `phasegate.config.json` を直接編集する (本 skill は read-only)
-- ❌ skill 本文に概念解説を書き加える (doc に書くべき。skill はポインタ役)
+「config の X を変更したい」など **設定変更を伴う質問** は本 skill のスコープ外。`phasegate-config-doctor` に委譲する (deploy 済の guidance skill。ユーザーに「設定変更には phasegate-config-doctor が推奨」と案内)。