phasegate 0.121.0 → 0.122.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.122.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,