phasegate 0.121.0 → 0.123.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.123.0] - 2026-05-08
+
+### Added
+
+- **WI-088 Phase A — bundled guidance skill `phasegate-toolkit-guide`** — phasegate を導入したプロジェクトで AI エージェントが phasegate ツールキット自体の概念 (L0-L4 / 防御プリセット / アーキプリセット / Quick Mode / Hook 仕様 / config 全般) について質問されたとき、`node_modules/phasegate/docs/guide/` 配下の canonical doc を読み込んで正確に回答するための skill を追加。
+  - **設計原則 (stale 回避)**: SKILL 本体に概念知識を固定せず、概念カテゴリごとに canonical doc へのポインタのみを記述。`npm update phasegate` で knowledge が自動追従する構造。
+  - **新規ファイル**: `skills/phasegate-toolkit-guide/SKILL.md` を `skill-creator` スキル (`init_skill.py`) 経由で作成 (validation pass)。9 概念カテゴリ (L0-L4 layer model / preset 2 系統 / Quick vs Full Mode / hook 仕様 / config 全般 / CLI / installation / skills overview / codex integration) ごとに `docs/guide/*.md` への参照を整理。
+  - **skill-deployer 拡張**: `scripts/harness/setup/skill-deployer.ts` の `SkillCategory` type union に `"guidance"` を追加、`SKILL_CATEGORIES.guidance = ["phasegate-toolkit-guide"]` を登録、`getSkillsForSet("all")` の返り値に guidance カテゴリを含めた。`getSkillsForSet("core")` には含めない (core は continuous governance 用、guidance は ad-hoc Q&A 用なので責務分離)。
+  - **テスト追加**: 4 ケース (`scripts/harness/__tests__/unit/setup/skill-deployer.test.ts` に `SKILL_CATEGORIES.guidance` 登録 / `getCategoryForSkill('phasegate-toolkit-guide') === 'guidance'` / `getSkillsForSet('all')` に含まれる / `getSkillsForSet('core')` に含まれない)。全 3495 テスト (前回 3491 + 新規 4) グリーン。
+  - **互換性**: 既存 deploy ロジックに変更なし、`getSkillsForSet("core")` の返り値も変更なし。consumer プロジェクトで `phasegate init` 実行時、`.claude/skills/` 配下に `phasegate-toolkit-guide` が追加 deploy されるのみ。
+
+## [0.122.0] - 2026-05-08
+
+### Added
+
+- **WI-087 Phase C-2 — Stop hook strict mode (`agentIntegration.stopHook.enforce`)** — 外部レポーター nakataj-mti が GitHub Issue [#3](https://github.com/junpei-9898/phasegate/issues/3) finding #4 で報告した「`phasegate hook stop` が Complete Check 失敗時に exit 1 を返すが、Claude Code の Stop hook block には exit 2 が必要」問題を解消。新 config flag `agentIntegration.stopHook.enforce: boolean` (default `false`) を v3 schema に追加し、true セット時のみ Complete Check 失敗で **exit 2 + `{"decision":"block","reason":"Complete Check failed (exitCode=N)"}`** を出力する strict mode に切り替わる。default は従来挙動 (exit cliResult.exitCode、stderr メッセージのみ) を完全維持。
+  - **schema 拡張**: `scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json` に top-level `agentIntegration.stopHook.enforce: boolean` を追加 (`additionalProperties: false`)。boolean 以外 / 未定義 key は AJV validator が reject。
+  - **新ポートメソッド**: `ConfigQueryPort.getStopHookEnforce(): Promise<boolean>` を追加 (`scripts/harness/agent-integration/domain/ports/config-query-port.ts`)。
+  - **infrastructure 実装**: `HarnessConfigConfigQueryAdapter.getStopHookEnforce()` が `agentIntegration.stopHook.enforce === true` のときのみ true を返す strict 一致判定。
+  - **application 拡張**: `HandleStopOutput` DTO に `shouldEnforceFailure?: boolean` を追加。`HandleStopUseCase.execute` 内で `enforce && cliResult.exitCode !== 0` の合成条件を populate。reentry 検出時は populate されない (現行挙動保持)。
+  - **presentation 分岐拡張**: `stop-hook.ts` で `output.shouldEnforceFailure === true` のとき stdout に decision JSON 出力 + stderr に reason 付きメッセージ + exit 2。それ以外は現行通り cliResult.exitCode で抜ける。
+  - **テスト追加**: 11 ケース (`ajv-config-schema-validator-v3.test.ts` +5、`harness-config-config-query-adapter.test.ts` +2、`handle-stop-usecase.test.ts` +4)。全 3491 テスト (前回 3480 + 新規 11) グリーン。
+  - **dogfood 検証**: phasegate 自身の `phasegate.config.json` に `enforce: true` を一時注入し `stop-hook.ts` を手動実行 → exit 2 + decision JSON 出力を確認。enforce 削除後は exit 1 + decision JSON なしの後方互換挙動を確認。
+  - **既存テストへの影響**: `ConfigQueryPort` インターフェース拡張に伴い、`handle-pre-tool-use-usecase.test.ts` / `handle-post-tool-use-usecase.test.ts` / `handle-stop-usecase.test.ts` / `ci-governance-baseline-grandfather-adapter.test.ts` の mock literal に `getStopHookEnforce: vi.fn().mockResolvedValue(false)` を追加 (default 後方互換を維持しつつ TypeScript 型契約を満たす)。
+  - **ドキュメント整合**: `docs/guide/configuration.md` に `agentIntegration` セクションを追加 (sub-field 表 + 用途説明)、`docs/guide/hooks-integration.md` の Stop hook 説明に enforce オプションを追記。
+  - **互換性**: 既存 v2/v3 config (agentIntegration セクション不在) は default false で v0.121.0 以前と完全同一挙動。schema validator 経路 / ConfigQueryPort 既存メソッド経路への影響なし。
+
 ## [0.121.0] - 2026-05-07
 
 ### Fixed

package/docs/guide/configuration.md

@@ -416,6 +416,28 @@ Introduced in ISSUE-007 Wave 1 (v0.65.0) and wired into the pre-tool-use hook by
 
 Generate or refresh the snapshot with `npx phasegate baseline` (`--dry-run` to inspect, `--force` to overwrite, `--paths <glob,glob,...>` to scope, `--json` for CI-friendly output). See the [Baseline section in CLI Reference](cli-reference.md#baseline-retrofit-grandfather) for details.
 
+#### `agentIntegration` (Stop hook strict mode)
+
+Controls how phasegate's agent-side hooks integrate with Claude Code. Currently only `stopHook.enforce` is exposed.
+
+```jsonc
+{
+  "agentIntegration": {
+    "stopHook": {
+      "enforce": true
+    }
+  }
+}
+```
+
+| Sub-field          | Type      | Default | Description                                                                                                          |
+|--------------------|-----------|---------|----------------------------------------------------------------------------------------------------------------------|
+| `stopHook.enforce` | `boolean` | `false` | When `true`, a non-zero exit from `phasegate:complete-check` causes the Stop hook to emit `{"decision":"block","reason":"Complete Check failed (exitCode=N)"}` on stdout and exit with code 2, blocking Claude Code's turn. When `false` (default), the hook exits with the inner CLI's exit code, which Claude Code surfaces only as a transcript warning. |
+
+Use `enforce: true` when your team treats Complete Check failures as hard gates (e.g., disallow ending a session with failing tests or lint). Leave it as default `false` for an opt-in / advisory experience.
+
+Reentry-detection cases (`REENTRY_DETECTED`) always exit with code 0 regardless of this setting; strict mode applies only to actual Complete Check failures.
+
 ---
 
 ### Quick Mode

package/docs/guide/hooks-integration.md

@@ -91,7 +91,8 @@ Use /quick-implementor skill for version changes in package.json.
 
 ### Stop (before session end)
 - Runs `phasegate:complete-check` (L2-L4 full validation)
-- Session end is held if checks are not all green
+- By default, the hook exits with the inner CLI's exit code, which Claude Code shows as a transcript warning but does not turn-block on.
+- Set `agentIntegration.stopHook.enforce: true` in `phasegate.config.json` to enable **strict mode**: on Complete Check failure, the hook emits `{"decision":"block","reason":"Complete Check failed (exitCode=N)"}` on stdout and exits with code 2, hard-blocking Claude Code's turn end. Reentry-detection still exits 0 regardless of this setting. See `docs/guide/configuration.md` `agentIntegration` section for details.
 
 ## Optional Shell Script Hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.121.0",
+  "version": "0.123.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/agent-integration/application/dto/handle-stop-dto.ts

@@ -14,4 +14,5 @@ export interface HandleStopOutput {
   executed: boolean;
   skipReason?: SkipReason;
   cliResult?: CliExecutionResult;
+  shouldEnforceFailure?: boolean;
 }

package/scripts/harness/agent-integration/application/usecases/handle-stop-usecase.ts

@@ -69,9 +69,13 @@ export class HandleStopUseCase {
 
     try {
       const cliResult = await this.cliExecutorPort.execute('phasegate:complete-check', []);
+      // WI-087 finding #4: enforce=true かつ Complete Check 失敗時のみ shouldEnforceFailure=true
+      const enforce = await this.configQueryPort.getStopHookEnforce();
+      const shouldEnforceFailure = enforce && cliResult.exitCode !== 0;
       return {
         executed: true,
         cliResult,
+        shouldEnforceFailure,
       };
     } finally {
       // deactivate は成否問わず必ず実行（finally保証）

package/scripts/harness/agent-integration/domain/ports/config-query-port.ts

@@ -17,4 +17,7 @@ export interface ConfigQueryPort {
   getRelaxedGates(): Promise<readonly string[]>;
   getProjectPaths(): ProjectPaths;
   getBaselineConfig(): Promise<BaselineConfig>;
+  // WI-087 finding #4: Stop hook strict mode 設定。true なら Complete Check 失敗時に
+  // exit 2 + decision JSON を出して Claude Code セッションを block する。
+  getStopHookEnforce(): Promise<boolean>;
 }

package/scripts/harness/agent-integration/infrastructure/adapters/harness-config-config-query-adapter.ts

@@ -48,12 +48,21 @@ interface BaselineSection {
   path?: string;
 }
 
+interface AgentIntegrationStopHookSection {
+  enforce?: boolean;
+}
+
+interface AgentIntegrationSection {
+  stopHook?: AgentIntegrationStopHookSection;
+}
+
 interface HarnessConfigDocument {
   harnesses?: HarnessesSection;
   project?: ProjectSection;
   protectedFiles?: ProtectedFilesSection;
   quickMode?: QuickModeSection;
   baseline?: BaselineSection;
+  agentIntegration?: AgentIntegrationSection;
 }
 
 export class HarnessConfigConfigQueryAdapter implements ConfigQueryPort {
@@ -128,4 +137,11 @@ export class HarnessConfigConfigQueryAdapter implements ConfigQueryPort {
       path: baseline.path ?? '.phasegate/baseline.json',
     };
   }
+
+  async getStopHookEnforce(): Promise<boolean> {
+    const config = this.loadConfig();
+    const enforce = config.agentIntegration?.stopHook?.enforce;
+    // type guard: boolean 以外（schema validator ですり抜ける null/undefined を含む）は false にフォールバック
+    return enforce === true;
+  }
 }

package/scripts/harness/agent-integration/presentation/stop-hook.ts

@@ -88,6 +88,15 @@ async function main(): Promise<void> {
 
     if (output.executed && output.cliResult) {
       if (output.cliResult.exitCode !== 0) {
+        // WI-087 finding #4: enforce=true なら exit 2 + decision JSON で turn block
+        if (output.shouldEnforceFailure === true) {
+          const reason = `Complete Check failed (exitCode=${output.cliResult.exitCode})`;
+          process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\n`);
+          process.stderr.write(
+            `Complete Check失敗 (exitCode=${output.cliResult.exitCode}) — strict mode により turn を block します\n`,
+          );
+          process.exit(2);
+        }
         process.stderr.write(`Complete Check失敗 (exitCode=${output.cliResult.exitCode})\n`);
       }
       process.exit(output.cliResult.exitCode);

package/scripts/harness/config-foundation/infrastructure/schemas/harness-config-v3.schema.json

@@ -482,6 +482,21 @@
         }
       }
     },
+    "agentIntegration": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "stopHook": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enforce": {
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    },
     "architecture": {
       "type": "object",
       "additionalProperties": false,

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

@@ -17,7 +17,7 @@ const HOOKS_TARGET_DIR = ".claude";
 
 // ── Skill Category Map ──
 
-export type SkillCategory = "core" | "aidlc" | "utility";
+export type SkillCategory = "core" | "aidlc" | "utility" | "guidance";
 export type SkillSet = "core" | "all";
 
 export const SKILL_CATEGORIES: Record<SkillCategory, readonly string[]> = {
@@ -52,13 +52,19 @@ export const SKILL_CATEGORIES: Record<SkillCategory, readonly string[]> = {
     "unit-test-logic-designer",
   ],
   utility: ["codex-delegator", "skill-creator"],
+  guidance: ["phasegate-toolkit-guide"],
 } as const;
 
 export function getSkillsForSet(skillSet: SkillSet): string[] {
   if (skillSet === "core") {
     return [...SKILL_CATEGORIES.core];
   }
-  return [...SKILL_CATEGORIES.core, ...SKILL_CATEGORIES.aidlc, ...SKILL_CATEGORIES.utility];
+  return [
+    ...SKILL_CATEGORIES.core,
+    ...SKILL_CATEGORIES.aidlc,
+    ...SKILL_CATEGORIES.utility,
+    ...SKILL_CATEGORIES.guidance,
+  ];
 }
 
 export function getCategoryForSkill(skillName: string): SkillCategory | null {

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

@@ -0,0 +1,166 @@
+---
+name: phasegate-toolkit-guide
+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 ツールキット内部の仕様・設定を尋ねる質問。
+---
+
+# Phasegate Toolkit Guide
+
+phasegate ツールキット自体の概念・仕様・設定について、ユーザーの質問に正確に答えるための skill。
+
+## このスキルが解決する問題
+
+ユーザーが phasegate を導入したプロジェクトで、AI に phasegate 関連の質問や設定変更を依頼したとき、AI が `node_modules/phasegate/` を grep で調査して仕様を推測する非効率を防ぐ。
+
+phasegate の概念と仕様は **canonical doc が `node_modules/phasegate/docs/guide/` 配下に同梱されている**。本 skill はそれらへの正確なポインタを提供する。
+
+## 重要な設計原則
+
+**knowledge を skill 本体に固定しない**。本 SKILL.md は「どの doc を読めば答えられるか」のポインタだけを持つ。実際の概念知識は phasegate 同梱 canonical doc から動的に読み込む。
+
+これにより `npm update phasegate` で knowledge が自動追従する (skill markdown に概念本文を書いてしまうとバージョン乖離が起きる)。
+
+## 回答プロセス
+
+1. ユーザー質問を以下の **概念カテゴリ** にマッピング
+2. 対応する canonical doc を **Read tool で読む**
+3. Read した内容に基づいて回答
+4. 回答内に **doc 内の該当セクションへのポインタ** を含める (ユーザーが詳細確認できるように)
+
+### canonical doc の場所
+
+phasegate がインストールされたプロジェクトでは、以下のいずれかにある:
+
+```
+node_modules/phasegate/docs/guide/   # npm 経由でインストールされた consumer プロジェクト
+docs/guide/                           # phasegate リポジトリ自体 (dogfood)
+```
+
+**先に `node_modules/phasegate/docs/guide/` を試し**、見つからなければ `docs/guide/` を試す。
+
+## 概念カテゴリと参照先 doc
+
+### 1. L0-L4 レイヤーモデル
+
+ユーザー質問例:
+- 「phasegate の L1 と L2 の違いって何？」
+- 「L0 ってどこで動いてる？」
+- 「L3 と L4 の検査内容を教えて」
+
+**参照先**: `docs/guide/layer-model.md`
+
+**読み方**: ファイル全体を読む (各層のセクションが明確に分かれている)。
+
+### 2. 防御プリセット / アーキプリセット (重要: 2 系統あり)
+
+ユーザー質問例:
+- 「preset って何？」
+- 「standard と strict の違いは？」
+- 「architecture.preset で onion と clean どっち選ぶべき？」
+- 「アーキプリセットを custom にしたいんだけど」
+
+**重要**: phasegate には **「防御プリセット」(`project.preset`) と「アーキプリセット」(`architecture.preset`) の 2 系統** がある。質問が曖昧な場合は **どちらを聞いているか確認** すること:
+
+| 呼称 | 概念 | 設定キー | 値の例 |
+|---|---|---|---|
+| **防御プリセット** | L3 CI で検査強度を選ぶ | `project.preset` | `minimal` / `standard` / `strict` |
+| **アーキプリセット** | L1 の層構造と依存方向を定義 | `architecture.preset` | `clean` / `strict-ddd` / `onion` / `hexagonal` / `layered` / `flat` / `custom` |
+
+**参照先**: `docs/guide/preset-selection.md` (両系統の詳細解説)
+
+### 3. Quick Mode と Full Mode
+
+ユーザー質問例:
+- 「Quick Mode と Full Mode の違いは？」
+- 「Quick Mode で書き込みが許可されるカテゴリを増やしたい」
+- 「relaxedGates って何のため？」
+- 「allowedCategories はどこで設定する？」
+
+**参照先**: `docs/guide/quick-vs-full-mode.md`
+
+設定キーは `phasegate.config.json` の `quickMode` セクション (`allowedCategories` / `relaxedGates` / `fullModeRequiredWhen`)。詳細は `docs/guide/configuration.md` の `quickMode` セクションも併読。
+
+### 4. Hook 仕様 (PreToolUse / PostToolUse / Stop / SessionStart / UserPromptSubmit)
+
+ユーザー質問例:
+- 「phasegate の hook って何が動いてる？」
+- 「PreToolUse で何が走る？」
+- 「Stop hook の enforce オプションって何？」
+- 「post-tool-use で format / lint が走らない、なぜ？」
+
+**参照先**: `docs/guide/hooks-integration.md`
+
+`Responsibility Separation` セクションに pre / post / Stop の責務分担表がある (WI-086 で追加)。Stop hook の `agentIntegration.stopHook.enforce` オプションは WI-087 Phase C-2 で追加された。
+
+### 5. config 全般 (`phasegate.config.json`)
+
+ユーザー質問例:
+- 「phasegate.config.json の各セクションの意味は？」
+- 「baseline.enabled って何？」
+- 「protectedFiles って何？」
+- 「project.paths にはどうやって書く？」
+
+**参照先**: `docs/guide/configuration.md`
+
+各 top-level セクションごとに説明あり: `project` / `layers` / `quickMode` / `phaseDependencies` / `harnesses` / `paths` / `reporting` / `architecture` / `agentIntegration` / `protectedFiles` / `baseline`。
+
+### 6. CLI コマンド一覧
+
+ユーザー質問例:
+- 「phasegate のコマンド一覧を教えて」
+- 「validate と lint と check-phase の違いは？」
+- 「init コマンドは何をする？」
+
+**参照先**: `docs/guide/cli-reference.md`
+
+### 7. インストールと初期設定
+
+ユーザー質問例:
+- 「phasegate のインストール方法は？」
+- 「monorepo で使うときは？」
+- 「既存プロジェクトに後から導入したい」
+
+**参照先**:
+- 新規導入: `docs/guide/installation.md`, `docs/guide/quickstart.md` (存在する場合)
+- 既存プロジェクト導入: `docs/guide/retrofit-adoption.md`
+
+### 8. skill 一覧と使い分け
+
+ユーザー質問例:
+- 「phasegate にはどんな skill がある？」
+- 「story-implementor と quick-implementor の違いは？」
+
+**参照先**: `docs/guide/skills-overview.md`
+
+### 9. Codex 統合
+
+ユーザー質問例:
+- 「codex CLI と組み合わせて使うには？」
+- 「codex-delegator って何？」
+
+**参照先**: `docs/guide/codex-integration.md`
+
+## 回答時のスタイル
+
+- 簡潔に答える (2-3 段落 + コード例 1 つ程度)
+- canonical doc の **該当セクション名** を必ず引用 (ユーザーが doc を直接開いたときの navigation 補助)
+- 質問が複数カテゴリにまたがる場合は、最も関連性の高い doc を先に読む
+- doc を読まずに回答しない (本 skill の存在意義は「正確な情報源を引く」こと)
+
+## マッピングが曖昧な場合
+
+ユーザー質問が上記カテゴリのいずれにも明確に当てはまらない場合:
+
+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 はポインタ役)