phasegate 0.183.0 → 0.212.0

package/skills/doc-health-checker/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: doc-health-checker
+kind: advisory
+description: 設計文書の健全性（鮮度 + ポインタ有効性）を L4 バリデータ CLI で診断・対処するスキル。`npx phasegate p2:check-freshness`（鮮度・code-design drift, L4-004）と `npx phasegate p2:validate-pointers`（壊れたファイルパスポインタ, L4-005）をラップし、結果を解釈して修正アクションを提案する。使用タイミング:「設計文書が古くなっていないか確認して」「ドキュメントの鮮度チェック」「設計とコードの乖離を調べて」「ドキュメントのリンク切れを確認して」「broken pointer を探して」「設計文書の参照が正しいか確認して」「L4 doc health チェック」など。
+model: sonnet
+review: opus
+languages: [typescript]
+---
+
+# Doc Health Checker
+
+## 目的
+
+設計文書の健全性を 2 つの観点で機械的に検証し、結果を解釈して修正アクションを提案する advisory スキル。旧 `doc-freshness-checker`（鮮度）と旧 `pointer-validator`（ポインタ有効性）を統合したもの。
+
+1. **鮮度（freshness）— L4-004**: 設計文書の最終更新が古すぎないか、コード変更と設計文書の乖離（code-design drift）がないかを検出する。`npx phasegate p2:check-freshness` をラップする。
+2. **ポインタ有効性（pointer validity）— L4-005**: 設計文書内で参照されているファイルパスポインタが実在するか（broken pointer）を検出する。`npx phasegate p2:validate-pointers` をラップする。
+
+いずれも L4 バリデータの CLI 拡張であり、本スキルは CLI を実行して結果を解釈し、ユーザーに対処案を提示する。
+
+> **重要（CLI 名の正）**: コマンドは必ず `p2:` 接頭辞付きで呼ぶ。無接頭辞の `phasegate check-freshness` / `phasegate validate-pointers` は **存在しない誤った表記**（旧スキルの記載は誤りだった）。正しくは `npx phasegate p2:check-freshness` / `npx phasegate p2:validate-pointers`。
+
+## 対象読者・使いどころ
+
+- 設計文書（`docs/product/construction/` や `docs/inception/` 配下の `.md`）が実装から取り残されていないか、参照リンクが壊れていないかを点検したいとき。
+- リリース前・大規模リファクタ後・Unit 完了時のドキュメント健全性確認。
+- 軽量チェックのため、鮮度とポインタの両方をまとめて走らせるのが基本運用。
+
+## CLI リファレンス
+
+### 1. 鮮度チェック — `p2:check-freshness`（L4-004）
+
+```bash
+npx phasegate p2:check-freshness [--pattern <glob>] [--format text|json] [--dry-run]
+```
+
+| オプション | 意味 |
+|-----------|------|
+| `--pattern <glob>` | 対象ファイルの glob（未指定時は config の設計文書パスが対象） |
+| `--format text\|json` | 出力形式（デフォルト `text`） |
+| `--dry-run` | 副作用なしで診断のみ |
+
+`CheckDocFreshnessOutput` の主なフィールド:
+
+| フィールド | 意味 |
+|-----------|------|
+| `results[].status` | `ok` / `warn` / `error` |
+| `results[].documentPath` | チェック対象ファイル |
+| `results[].daysSinceUpdate` | 最終更新からの日数 |
+| `results[].threshold` | 設定閾値 |
+| `summary.error` | error 件数（exit code 1 になる） |
+| `summary.warn` | warn 件数 |
+
+**exit code**: `summary.error > 0` なら 1、それ以外 0。
+
+### 2. ポインタ検証 — `p2:validate-pointers`（L4-005）
+
+```bash
+npx phasegate p2:validate-pointers [--pattern <glob>] [--include-urls] [--format text|json]
+```
+
+| オプション | 意味 |
+|-----------|------|
+| `--pattern <glob>` | 対象ファイルの glob（未指定時は config の設計文書パスが対象） |
+| `--include-urls` | URL ポインタ（`http(s)://`）も検証対象に含める（デフォルトは file-path のみ） |
+| `--format text\|json` | 出力形式（デフォルト `text`） |
+
+検出対象ポインタ: Markdown `[text](path)` リンク / `@file:` `@ref:` / `filePath:` フィールドのパス参照。`http(s)://` URL は `--include-urls` 指定時のみ検証。
+
+`ValidateDocPointersOutput` の主なフィールド:
+
+| フィールド | 意味 |
+|-----------|------|
+| `results[].documentPath` | ポインタを含む文書 |
+| `results[].pointerTarget` | 参照先パス |
+| `results[].pointerType` | `file-path` / `url` |
+| `results[].isResolvable` | 解決可能かどうか |
+| `results[].errorMessage` | エラー内容（null なら正常） |
+| `summary.brokenPointers` | broken 件数 |
+| `summary.skippedUrlPointers` | スキップした URL 件数 |
+| `passed` | 全ポインタ有効なら true |
+
+**exit code**: `passed` なら 0、broken があれば 1。
+
+> **注意**: このスキルの CLI には自動修正フラグ（`--fix`）は存在しない。ポインタ修正は結果を解釈したうえで手動（`Edit`）で行う。
+
+## ワークフロー
+
+軽量チェックのため単一フェーズで実行する。鮮度とポインタは独立なので、必要に応じて片方だけ／両方を走らせる。
+
+### Step 1: 実行
+
+```bash
+# 両方まとめて（推奨）
+npx phasegate p2:check-freshness --format json
+npx phasegate p2:validate-pointers --format json
+```
+
+大量に broken が出そうな大規模リポジトリでは `--pattern` でスコープを絞って段階実行する。
+
+### Step 2: 結果の解釈とアクション
+
+**鮮度（freshness）**:
+
+| 状態 | 推奨アクション |
+|------|--------------|
+| `error`（閾値超過 / drift 疑い） | `cascade-updater` で上位設計文書を更新、コードと設計の乖離を解消 |
+| `warn`（閾値近接） | 設計文書の内容を確認し、必要に応じて更新 |
+| `ok` | 対応不要 |
+
+**ポインタ（pointer）**: broken の原因別に対処する。
+
+| broken 原因 | 推奨アクション |
+|-----------|--------------|
+| ファイルが移動された | ポインタのパスを新パスに更新（`Edit`） |
+| ファイルが削除された | ポインタを削除 or 代替ファイルに変更 |
+| タイポ | パス修正 |
+| 未作成ファイルへの前方参照 | 意図的なら `[TODO]` マーカーを付ける |
+
+修正後は同じコマンドを再実行して 0 件（`passed: true` / `summary.error: 0`）を確認する。
+
+### 出力フォーマット（ユーザー報告例）
+
+```markdown
+# Doc Health チェック結果
+
+## 鮮度（p2:check-freshness / L4-004）
+- 総ドキュメント数: N ／ ok: N / warn: N / error: N
+### 要対応（error）
+| ファイル | 最終更新 | 閾値超過日数 | 推奨アクション |
+|---------|---------|------------|--------------|
+
+## ポインタ（p2:validate-pointers / L4-005）
+- チェック文書数: N ／ broken: N / URL(スキップ): N
+### Broken Pointers（要修正）
+| 文書ファイル | 参照先 | エラー | 推奨修正 |
+|------------|--------|--------|---------|
+
+## 次のアクション
+（error があれば cascade-updater、broken があれば該当ポインタの Edit を提案）
+```
+
+## 関連スキル
+
+| スキル | 用途 |
+|-------|------|
+| `cascade-updater` | 鮮度 error が出た設計文書の連鎖更新 |
+| `consistency-checker` | 文書間の内容整合性チェック（健全性修正後の確認） |

package/skills/domain-designer/SKILL.md

@@ -24,7 +24,7 @@ DDD戦術パターンを用いてドメインモデルを設計するスキル
 
 ## ⚠️ 上位レイヤー存在チェック
 
-**このスキルは AIDLC Step 4「Domainの設計」に対応します。実行前に上位設計の存在を確認してください。**
+**このスキルは AIDLC Step 2.1「Domainの設計」に対応します。実行前に上位設計の存在を確認してください。**
 
 ### 依存する上位設計文書
 
@@ -77,6 +77,8 @@ DDD戦術パターンを用いてドメインモデルを設計するスキル
 ### 出力ファイル
 `docs/inception/{unit}/domain_model_plan.md`
 
+> **パス注記**: 本スキルが扱う設計文書パス（`docs/inception/...` / `docs/product/construction/...`）は既定値であり、consumer が `phasegate.config.json` の `paths` 設定で上書きしている場合はそちらが優先される。
+
 ### 計画ファイルの構成
 
 ```markdown
@@ -145,7 +147,7 @@ DDD戦術パターンを用いてドメインモデルを設計するスキル
 
 ## 🔗 成果物のトレーサビリティメタデータ（必須）
 
-Phase 2 で生成する設計文書には、以下 2 種類のメタデータを emit する。`MetadataValidator.validateDesignDocument` が検証対象とし、ISSUE-008 Phase B-2/B-3 完了後は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
+Phase 2 で生成する設計文書には、以下 2 種類のメタデータを emit する。これらのメタデータは `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
 
 ### 1. YAML frontmatter（新規作成時）
 

package/skills/engineering-perspective/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: engineering-perspective
+kind: advisory
 description: |
   ケント・ベック + マーティン・ファウラー + アンクル・ボブ + エリック・エヴァンスの視点を統合したエンジニアリング思考フレームワーク。
   以下の場面で使用:

package/skills/environment-designer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: environment-designer
-description: ローカル開発環境のプラットフォーム構成設計。コードと環境のブリッジ（AIDLC Step 2.2並行）
+description: ローカル開発環境のプラットフォーム構成設計。コードと環境のブリッジ（AIDLC Step 2.3、logical-designer の後）
 model: sonnet
 review: opus
 languages: [typescript]
@@ -26,7 +26,7 @@ languages: [typescript]
 
 ## ⚠️ 上位レイヤー存在チェック
 
-**このスキルは AIDLC Step 2.2並行「環境設計」に対応します。実行前に上位設計の存在を確認してください。**
+**このスキルは AIDLC Step 2.3「環境設計」（logical-designer の後）に対応します。実行前に上位設計の存在を確認してください。**
 
 ### 依存する上位設計文書
 
@@ -69,10 +69,10 @@ languages: [typescript]
 
 **このスキルは3フェーズで実行する。**
 - **Phase 1（計画）**: Opus がスコープ・方針・不明点を整理し、人間の承認を得る
-- **Phase 2（実行）**: Sonnet 4.6 に委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
+- **Phase 2（実行）**: 委任先モデルに委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
 - **Phase 3（レビュー）**: Opus が成果物を検証し、問題があれば直接修正する
 
-**Phase 1/2/3を同時に実行してはならない。モデルルーティングの詳細は `docs/principles/model-routing.md` を参照。**
+**Phase 1/2/3を同時に実行してはならない。モデルルーティングの詳細は `docs/principles/model-routing.md` を参照（consumer プロジェクトでは `node_modules/phasegate/docs/principles/model-routing.md`、phasegate 自リポジトリでは `docs/principles/model-routing.md` を参照する）。**
 
 ---
 
@@ -84,6 +84,8 @@ languages: [typescript]
 ### 出力ファイル
 `docs/inception/_shared/environment_design_plan.md`
 
+> **パス注記**: 本スキルが扱う設計文書パス（`docs/inception/...` / `docs/product/environment_contract.md`）は既定値であり、consumer が `phasegate.config.json` の `paths` 設定で上書きしている場合はそちらが優先される。
+
 ### 計画ファイルの構成
 
 ```markdown
@@ -161,11 +163,11 @@ languages: [typescript]
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体
-メインセッション（Opus 4.6）が実行する。Sonnetへの再委任は行わない。
+メインセッション（model-routing.md の Architect ロール）が実行する。Sonnetへの再委任は行わない。
 
 ### レビュー手順
 1. Sonnetが出力したファイルを読み込む
-2. `docs/principles/model-routing.md` のレビュー観点 R1〜R7 に沿って検証する
+2. `docs/principles/model-routing.md` の「レビュー観点」節に沿って検証する
 3. **スキル固有レビュー観点**を検証する
 4. 判定結果を出力する
 

package/skills/implementation-readiness-checker/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: implementation-readiness-checker
+kind: advisory
 description: 実装開始前の準備状況を自動検証 - テスト設計・カバレッジ・ロジック設計の存在チェックとギャップ分析
 model: sonnet
 review: opus
@@ -169,7 +170,7 @@ languages: [typescript]
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体
-メインセッション（Opus 4.6）が実行する。Sonnetへの再委任は行わない。
+メインセッション（model-routing.md の Architect ロール）が実行する。Sonnetへの再委任は行わない。
 
 ### レビュー手順
 1. Sonnetが出力したファイルを読み込む

package/skills/it-test-designer/SKILL.md

@@ -19,9 +19,11 @@ languages: [typescript]
 ### 任意インプット（あれば参照）
 - **ドメインモデル** — `docs/product/construction/{unit}/domain_model.md`
 - **環境設計** — `docs/product/environment_contract.md`
-- **テスト規約** — `docs/principles/testing-rules.md`
+- **テスト規約** — `docs/principles/testing-rules.md`（consumer プロジェクトでは `node_modules/phasegate/docs/principles/testing-rules.md`、phasegate リポジトリ自体では `docs/principles/testing-rules.md` を参照）
 - **既存ITテスト** — 既存パターンの参考
 
+> **設計文書パスの注記:** 上記および本スキルが扱う `docs/product/construction/{unit}/...` / `docs/inception/...` パスは既定値。consumer が `phasegate.config.json` の paths 設定を上書きしている場合はそちらに従う。
+
 ---
 
 ## ⛔ スキップ禁止
@@ -34,7 +36,7 @@ languages: [typescript]
 - `implementation-readiness-checker` でブロックされる
 
 ### フロー上の位置
-`scenario-test-designer` → **it-test-designer（本スキル）** → `unit-test-designer` → `test-coverage-checker` → テストロジック設計 → `story-implementor`
+`scenario-test-designer` → `uiux-designer` → `unit-test-designer` → **it-test-designer（本スキル）** → `test-coverage-checker` → テストロジック設計 → `implementation-readiness-checker` → `story-implementor`
 
 **必ず完了してから次のステップに進んでください。**
 
@@ -69,7 +71,7 @@ languages: [typescript]
 
 **このスキルは3フェーズで実行する。**
 - **Phase 1（計画）**: Opus がスコープ・方針・不明点を整理し、人間の承認を得る
-- **Phase 2（実行）**: Sonnet 4.6 に委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
+- **Phase 2（実行）**: 委任先モデルに委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
 - **Phase 3（レビュー）**: Opus が成果物を検証し、問題があれば直接修正する
 
 **Phase 1/2/3を同時に実行してはならない。モデルルーティングの詳細は `docs/principles/model-routing.md` を参照。**
@@ -151,11 +153,11 @@ ITテスト設計のスコープ・テスト対象・不明点を整理し、人
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体
-メインセッション（Opus 4.6）が実行する。Sonnetへの再委任は行わない。
+メインセッション（model-routing.md の Architect ロール）が実行する。Sonnetへの再委任は行わない。
 
 ### レビュー手順
 1. Sonnetが出力したファイルを読み込む
-2. `docs/principles/model-routing.md` のレビュー観点 R1〜R7 に沿って検証する
+2. `docs/principles/model-routing.md` の「レビュー観点」節に沿って検証する
 3. **スキル固有レビュー観点**を検証する
 4. 判定結果を出力する
 
@@ -193,7 +195,7 @@ ITテスト設計のスコープ・テスト対象・不明点を整理し、人
 
 ITテストケース設計完了後、以下の順序で進める（フロー図は「スキップ禁止」セクション参照）:
 
-1. `unit-test-designer` — ユニットテストケース設計
-2. `test-coverage-checker` — カバレッジ検証（90%以上）
-3. `*-test-logic-designer` — 各レベルのテストロジック設計
+1. `test-coverage-checker` — カバレッジ検証（90%以上）
+2. `*-test-logic-designer` — 各レベルのテストロジック設計
+3. `implementation-readiness-checker` — 実装準備の自動検証
 4. `story-implementor` — TDD実装（Unit → IT → E2E）

package/skills/it-test-logic-designer/SKILL.md

@@ -14,7 +14,7 @@ ITテストケース設計（`it_test_design.md`）を元に、Vitest実装ロ
 
 ```
 テストケース設計フェーズ
-  unit-test-designer → it-test-designer → scenario-test-designer
+  scenario-test-designer → uiux-designer → unit-test-designer → it-test-designer
                           ↓
               test-coverage-checker
                           ↓
@@ -27,7 +27,7 @@ ITテストケース設計（`it_test_design.md`）を元に、Vitest実装ロ
   scenario-test-logic-designer
                           ↓
 TDD実装フェーズ
-  story-implementor
+  implementation-readiness-checker → story-implementor
 ```
 
 ## 前提条件チェック
@@ -38,10 +38,12 @@ TDD実装フェーズ
 
 ### 推奨インプット（あれば参照）
 - **カバレッジレポート** — `docs/product/construction/{unit}/coverage_report.md`
-- **既存ITテスト** — `backend/test/integration/**/*.test.ts`（パターン参考）
-- **テスト規約** — `docs/principles/testing-rules.md`
+- **既存ITテスト** — 対象プロジェクトの構成（package.json scripts, vitest 設定, `phasegate.config.json` の paths）からテスト配置を特定してパターン参考にする。例（モノレポ構成の場合）: `backend/test/integration/**/*.test.ts`
+- **テスト規約** — `docs/principles/testing-rules.md`（consumer プロジェクトでは `node_modules/phasegate/docs/principles/testing-rules.md`、phasegate リポジトリ自体では `docs/principles/testing-rules.md` を参照）
 - **ストーリー固有論理設計** — `docs/inception/{unit}/{story_id}/logical_design.md`
 
+> **設計文書パスの注記:** 本スキルが扱う `docs/product/construction/{unit}/...` / `docs/inception/...` パスは既定値。consumer が `phasegate.config.json` の paths 設定を上書きしている場合はそちらに従う。
+
 ---
 
 ## ⚠️ 上位レイヤー存在チェック
@@ -72,7 +74,7 @@ TDD実装フェーズ
 
 **このスキルは3フェーズで実行する。**
 - **Phase 1（計画）**: Opus がスコープ・方針・不明点を整理し、人間の承認を得る
-- **Phase 2（実行）**: Sonnet 4.6 に委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
+- **Phase 2（実行）**: 委任先モデルに委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
 - **Phase 3（レビュー）**: Opus が成果物を検証し、問題があれば直接修正する
 
 **Phase 1/2/3を同時に実行してはならない。モデルルーティングの詳細は `docs/principles/model-routing.md` を参照。**
@@ -105,7 +107,7 @@ TDD実装フェーズ
 | `{controller}.test.ts` | {Controller名} | X |
 
 ## 3. DB/モック戦略
-- テストDB: ローカルSupabase使用
+- テストDB: プロジェクトが採用する DB/BaaS のテスト用インスタンス（例: ローカル Supabase）
 - トランザクション制御: テスト毎にクリーンアップ
 - モック対象: 外部API（例: ○○）
 
@@ -212,11 +214,11 @@ Repositoryテストでは、`getTestClient()` でDBに直接クエリし永続
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体
-メインセッション（Opus 4.6）が実行する。Sonnetへの再委任は行わない。
+メインセッション（model-routing.md の Architect ロール）が実行する。Sonnetへの再委任は行わない。
 
 ### レビュー手順
 1. Sonnetが出力したファイルを読み込む
-2. `docs/principles/model-routing.md` のレビュー観点 R1〜R7 に沿って検証する
+2. `docs/principles/model-routing.md` の「レビュー観点」節に沿って検証する
 3. **スキル固有レビュー観点**を検証する
 4. 判定結果を出力する
 
@@ -253,7 +255,7 @@ Phase 2 で設計する IT テストファイル（`*.test.ts` / `*.it.test.ts`
 - **テストコードは生成しない**（設計文書のみ）— 実装は `story-implementor` スキル（codex-delegator経由、またはメインセッションで直接実行）が行う
 - 疑似コードは実装の指針となる詳細レベルで記載する
 - TDDの「RED」フェーズで正しく失敗するテストを設計する
-- 既存のテストパターン（`backend/test/integration/**/*.test.ts`）を参照してスタイルを統一する
+- 既存のテストパターンを参照してスタイルを統一する（テスト配置は対象プロジェクトの構成から特定する。例（モノレポ構成の場合）: `backend/test/integration/**/*.test.ts`）
 - シードデータはテスト間で独立させ、相互干渉を防ぐ
 
 ---

package/skills/it-test-logic-designer/references/repository-test-patterns.md

@@ -3,10 +3,14 @@
 本ファイルは `it-test-logic-designer` スキルで使用するRepositoryレイヤーのテストテンプレート集。
 シードデータ設計・トランザクション・クリーンアップ戦略を含む。
 
+> **配置パス・DB クライアント・実行コマンドについて:** 以下のテスト配置ディレクトリ（`backend/test/seeds/` 等）・テスト実行コマンドは対象プロジェクトの構成（`package.json` scripts, vitest 設定, `phasegate.config.json` の paths）から特定すること。`getTestClient` / `SupabaseClient` / `supabase-test-helper.js` はプロジェクトが採用する DB/BaaS のテスト用ヘルパーに読み替える（以下は Supabase プロジェクト向けの実装例）。テンプレート構造自体はそのまま流用してよい。
+
 ---
 
 ## テストヘルパーのインポート
 
+以下は例（Supabase プロジェクトの場合）。DB/BaaS ヘルパーはプロジェクトの採用技術に読み替える。
+
 ```typescript
 import { target, context } from '../../helpers/common-helper.js';
 import { getTestClient, cleanupTestData } from '../../helpers/supabase-test-helper.js';
@@ -15,7 +19,8 @@ import { getTestClient, cleanupTestData } from '../../helpers/supabase-test-help
 ## シードデータ設計テンプレート
 
 ```typescript
-// backend/test/seeds/{context}/{seed-name}.ts
+// 例（モノレポ構成の場合）: backend/test/seeds/{context}/{seed-name}.ts
+// SupabaseClient 型はプロジェクトが採用する DB/BaaS のクライアント型に読み替える
 
 export const {SEED_NAME}_SEED = {
   // テストデータ定義
@@ -194,6 +199,8 @@ expect(row).not.toBeNull();
 
 ## テスト実行コマンド
 
+実行コマンドは対象プロジェクトの構成（`package.json` scripts, vitest 設定, `phasegate.config.json` の paths）から特定する。以下は例（pnpm モノレポ構成の場合）。
+
 ```bash
 # 全ITテスト実行
 pnpm --filter backend test:integration

package/skills/logical-designer/SKILL.md

@@ -22,7 +22,7 @@ Unit単位でアーキテクチャの各層（DB → ドメイン → ユース
 ## Pre-flight check (BLOCKING)
 
 Before generating any plan, verify `docs/inception/{unit}/WI-XXX/description.md` exists.
-If not, halt and ask the user to create the WI first, or offer to run `phasegate scaffold-wi <unit> <story|issue|chore>`.
+If not, halt and ask the user to create the WI first, or offer to run `phasegate scaffold-wi <unit|_cross> <story|issue|fix|refactor|chore>`.
 
 ### 必須インプット（存在しなければ`[Question]`で提供を要求）
 
@@ -44,7 +44,7 @@ If not, halt and ask the user to create the WI first, or offer to run `phasegate
 
 ## ⚠️ 上位レイヤー存在チェック
 
-**このスキルは AIDLC Step 5「論理設計」に対応します。実行前に上位設計の存在を確認してください。**
+**このスキルは AIDLC Step 2.2「論理設計」に対応します。実行前に上位設計の存在を確認してください。**
 
 ### 依存する上位設計文書
 
@@ -103,6 +103,8 @@ If not, halt and ask the user to create the WI first, or offer to run `phasegate
 ### 出力ファイル
 `docs/inception/{unit}/WI-XXX/logical_design_plan.md`
 
+> **パス注記**: 本スキルが扱う設計文書パス（`docs/inception/...` / `docs/product/construction/...`）は既定値であり、consumer が `phasegate.config.json` の `paths` 設定で上書きしている場合はそちらが優先される。
+
 ### 計画ファイルの構成
 
 ```markdown
@@ -187,7 +189,7 @@ If not, halt and ask the user to create the WI first, or offer to run `phasegate
 
 ## 🔗 成果物のトレーサビリティメタデータ（必須）
 
-Phase 2 で生成する設計文書には、以下 2 種類のメタデータを emit する。`MetadataValidator.validateDesignDocument` が検証対象とし、ISSUE-008 Phase B-2/B-3 完了後は `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
+Phase 2 で生成する設計文書には、以下 2 種類のメタデータを emit する。これらのメタデータは `npx phasegate validate-metadata` / pre-commit で自動チェックされる。
 
 ### 1. YAML frontmatter（新規作成時）
 

package/skills/mock-designer/SKILL.md

@@ -10,6 +10,8 @@ languages: [typescript]
 
 ユーザーストーリーからUIモックアップを作成するスキル。AIDLCプロセスのStep 2「mock（モック）を作る」に対応。
 
+このスキルは UI モックアップ（HTML）作成であり、テストコードのモック/スタブ設計ではない（それらは各 test-logic-designer のモック戦略節を参照）。
+
 ## 前提条件チェック
 
 ### 必須インプット（存在しなければ`[Question]`で提供を要求）
@@ -17,9 +19,11 @@ languages: [typescript]
 
 ### 任意インプット（あれば参照）
 - **プロダクト概要** — `docs/product/product_overview.md`（全体像・ユビキタス言語）
-- **既存モック** — `/mock` フォルダ内の既存HTMLファイル
+- **既存モック** — `mock/` フォルダ内の既存HTMLファイル
 - **デザインシステム** — 色・フォント・コンポーネントの規約
 
+> **設計文書パスの注記:** 上記および本スキルが扱う `docs/product/...` / `docs/inception/...` パスは既定値。consumer が `phasegate.config.json` の paths 設定を上書きしている場合はそちらに従う。
+
 ---
 
 ## ⚠️ 上位レイヤー存在チェック
@@ -65,10 +69,10 @@ languages: [typescript]
 
 **このスキルは3フェーズで実行する。**
 - **Phase 1（計画）**: Opus がスコープ・方針・不明点を整理し、人間の承認を得る
-- **Phase 2（実行）**: Sonnet 4.6 に委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
+- **Phase 2（実行）**: 委任先モデルに委任して成果物を生成する（`npx phasegate delegate-sonnet` 経由）
 - **Phase 3（レビュー）**: Opus が成果物を検証し、問題があれば直接修正する
 
-**Phase 1/2/3を同時に実行してはならない。モデルルーティングの詳細は `docs/principles/model-routing.md` を参照。**
+**Phase 1/2/3を同時に実行してはならない。モデルルーティングの詳細は `docs/principles/model-routing.md`（consumer プロジェクトでは `node_modules/phasegate/docs/principles/model-routing.md`、phasegate リポジトリ自体では `docs/principles/model-routing.md`）を参照。**
 
 ---
 
@@ -153,7 +157,7 @@ graph LR
 
 | 種別 | 配置先 |
 |------|--------|
-| 成果物 | `/mock/{画面名}.html` |
+| 成果物 | `mock/{画面名}.html`（プロジェクトルート相対） |
 
 ---
 
@@ -162,11 +166,11 @@ graph LR
 ## Phase 3: レビュー（Opus review）
 
 ### 実行主体
-メインセッション（Opus 4.6）が実行する。Sonnetへの再委任は行わない。
+メインセッション（model-routing.md の Architect ロール）が実行する。Sonnetへの再委任は行わない。
 
 ### レビュー手順
 1. Sonnetが出力したファイルを読み込む
-2. `docs/principles/model-routing.md` のレビュー観点 R1〜R7 に沿って検証する
+2. `docs/principles/model-routing.md` の「レビュー観点」節に沿って検証する
 3. **スキル固有レビュー観点**を検証する
 4. 判定結果を出力する
 

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

@@ -1,5 +1,6 @@
 ---
 name: phasegate-config-doctor
+kind: advisory
 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 提案を求める質問。
 languages: [typescript]
 ---
@@ -93,7 +94,7 @@ product-architect で Unit を作り、いくつかの logical_design を書い
   - DDD タクティカル (`entities/aggregates/repositories`) あり → `strict-ddd` 推奨
   - `core/`, `adapters/`, `ports/` パターン → `hexagonal` 推奨
   - 上記いずれも無し → ユーザーに確認 + `custom` 提案
-- 検出根拠を必ず提示 (例:「`scripts/harness/{domain,application,infrastructure,presentation}` を検出 → `clean` 推奨」)
+- 検出根拠を必ず提示 (例:「`src/{domain,application,infrastructure,presentation}` を検出 → `clean` 推奨」。phasegate 自リポジトリ（dogfood）では `scripts/harness/{domain,application,infrastructure,presentation}`)
 - `architecture.preset = "custom"` だが `architecture.layers` 未定義 → WARN: schema validator で reject される
 
 #### 観点 2: project.preset (防御プリセット)
@@ -180,7 +181,7 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 ### 💡 改善提案 (SUGGEST)
 
 #### S1: `architecture.preset` 未指定 → "clean" を推奨
-- 検出根拠: `scripts/harness/{domain,application,infrastructure,presentation}` の 4 ディレクトリが存在
+- 検出根拠: `src/{domain,application,infrastructure,presentation}` の 4 ディレクトリが存在（phasegate 自リポジトリ（dogfood）では `scripts/harness/{domain,application,infrastructure,presentation}`）
 - 修正案:
   ```json-diff
    {

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

@@ -1,5 +1,6 @@
 ---
 name: phasegate-toolkit-guide
+kind: advisory
 description: phasegate ツールキット自体に関する Q&A スキル。ユーザーが phasegate の概念 (L0-L4 レイヤーモデル / 防御プリセット / アーキプリセット / Quick Mode と Full Mode / Hook 仕様 / config 全般) について質問したとき、対応する canonical doc を読み込んでから回答する。使用タイミング:「phasegate の L1 と L2 の違いは？」「Quick Mode で許可されるカテゴリを増やしたい」「architecture.preset の使い分けは？」「phasegate の hook って何が動いている？」「phasegate.config.json の relaxedGates は何のため？」など phasegate ツールキット内部の仕様・設定を尋ねる質問。
 languages: [typescript]
 ---

package/skills/quick-implementor/SKILL.md

@@ -94,7 +94,7 @@ Quick Mode下での軽微変更実装スキル。story-implementorの緩和版
 ### Step 4: 検証
 
 ```bash
-pnpm test  # 全テスト グリーンを確認
+npm test  # 全テスト グリーンを確認（プロジェクトのテストコマンド。pnpm/yarn 等は適宜読み替える）
 ```
 
 ### 出力（Step 5: コミット）