phasegate 0.120.0 → 0.122.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ 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
+
+- **WI-087 finding #3 + WI-086 docs: PreToolUse の Quick Mode 通過時の visibility 改善 + hook 責務分離をドキュメント化** — 外部レポーター nakataj-mti / junpei-9898 が GitHub Issue [#3](https://github.com/junpei-9898/phasegate/issues/3) finding #3 / [#2](https://github.com/junpei-9898/phasegate/issues/2) で報告した「Quick Mode で write が allow されるとき hook が完全 silent で、初見ユーザーが "hook が走っていない" と誤認する」問題と「pre-tool-use が L1 lint をしないことが暗黙仕様化していてレポーター期待と齟齬している」問題を解消。
+  - **Quick Mode visibility notice** (`scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts`): `HandlePreToolUseOutput.quickModeAllowed` がセットされた場合、stderr に `phasegate: write allowed (Quick Mode, category=<dominantCategory>)` を出力。exit code は 0 維持で **semantics は不変**、可視性のみ向上。
+  - **DTO 拡張** (`scripts/harness/agent-integration/application/dto/handle-pre-tool-use-dto.ts`): `quickModeAllowed?: { dominantCategory?: string }` を追加。`HandlePreToolUseUseCase.execute` 内で `WRITE_TOOLS + fullModeRequirementQueryPort + requiresFullMode=false` の経路で populate。block 経路や WRITE_TOOLS 外 (`Bash` 等) では出力されず、後方互換維持。
+  - **テスト追加** (`scripts/harness/__tests__/integration/agent-integration/handle-pre-tool-use-usecase.test.ts`): 4 ケース — `quickModeAllowed` が `dominantCategory` 付きで返る / `dominantCategory` 未設定で返る / `fullModeRequirementQueryPort` 未指定時は出力なし / WRITE_TOOLS 外 (`Bash`) では出力なし。全 49 ケース (前回 45 + 新規 4) グリーン。
+  - **責務分離のドキュメント明文化** (`docs/guide/hooks-integration.md`): "Responsibility Separation" セクションを冒頭に追加し、pre = フェーズゲート / post = lint / Stop = complete-check の役割分担表と「pre-tool-use は意図的に lint を実行しない (lint は書き込み後の content が必要)」旨を明記。WI-086 で指摘された「`pre-tool-use` で違反 Write を exit 2 でブロックしてほしい」期待が現行設計と乖離する理由を ユーザー視点で説明。
+  - **互換性**: 既存テスト全てグリーン（`expect(actual).toEqual({ shouldBlock: false })` 形式の既存 assert は `quickModeAllowed: undefined` を含む結果でも一致）。`HandlePreToolUseOutput` への field 追加は外部 API ではなく application/presentation 内部 DTO のみで、外部消費者なし。
+  - **スコープ外** (Phase C-2 で対応予定): WI-087 finding #4 — Stop hook `--enforce` flag (`agentIntegration.stopHook.enforce` config 追加で Complete Check 失敗時に exit 2 + decision JSON `"deny"` を返す strict mode)。config schema 拡張のため story-implementor で別リリース予定。
+
 ## [0.120.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

@@ -42,9 +42,27 @@ Add the following to `.claude/settings.json`:
 
 ## Hook Behaviors
 
+### Responsibility Separation (important)
+
+Phasegate's hooks are **strictly partitioned by phase**:
+
+| Hook | What it checks | What it does NOT check |
+|------|----------------|------------------------|
+| **PreToolUse** | Phase Gate, protected files, Quick Mode category gating, story-reflection | L1 lint (`@unit` / `@layer` / `any` abuse) — these are post-write concerns |
+| **PostToolUse** | L1 Biome AST rules, formatter, type-check (via `analyze-errors-hook.sh`) | Phase Gate (already checked before write) |
+| **Stop** | Complete-check (L2-L4 full validation suite) | Per-edit lint (already done by PostToolUse) |
+
+This separation is intentional:
+- **Pre = "should this write happen at all?"** — concerns the caller's intent and design state.
+- **Post = "is what was written valid?"** — concerns the resulting code's quality.
+- **Stop = "is the session ready to end?"** — concerns the cumulative state across the session.
+
+If you expect L1 lint (e.g., missing `@unit` annotation) to **block** a Write before it happens, that is by design **not** the case. The PreToolUse hook intentionally does not run lint, because lint requires the resulting file content (which only exists after the write). Lint violations surface as **PostToolUse** decision JSON (`decision: "block"`) and trigger Claude Code to retry.
+
 ### PreToolUse (before file write)
 - Enforces Phase Gate: blocks writing to source files if required design documents don't exist
 - Blocks writes to protected files (package.json, biome.json, tsconfig.json)
+- Quick Mode: when a write is allowed because the change is classified within `quickMode.allowedCategories`, an informational notice is emitted to stderr (`phasegate: write allowed (Quick Mode, category=<...>)`) — exit code remains 0
 - Returns actionable error messages with:
   - Violation reason
   - Missing artifacts
@@ -73,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.120.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-pre-tool-use-dto.ts

@@ -19,4 +19,9 @@ export interface HandlePreToolUseOutput {
   fullModeRejectionRule?: 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
   fullModeDominantCategory?: string;
   nextAction?: string;
+  // Quick Mode が write を許可した際に dominant カテゴリを presentation 層に伝える。
+  // shouldBlock=false のときのみセットされる。WI-087 finding #3。
+  quickModeAllowed?: {
+    dominantCategory?: string;
+  };
 }

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-pre-tool-use-usecase.ts

@@ -134,6 +134,7 @@ export class HandlePreToolUseUseCase {
       }
     }
 
+    let quickModeAllowed: HandlePreToolUseOutput["quickModeAllowed"];
     if (
       HandlePreToolUseUseCase.WRITE_TOOLS.has(input.toolName) &&
       this.fullModeRequirementQueryPort !== undefined &&
@@ -157,29 +158,31 @@ export class HandlePreToolUseUseCase {
               unitIdForGuidance,
             );
           }
+        } else {
+          quickModeAllowed = { dominantCategory: fullModeResult.dominantCategory };
         }
       }
     }
 
     const scope = this.resolveStoryReflectionScope(input);
     if (scope === null || this.storyReflectionQueryPort === undefined) {
-      return { shouldBlock: false };
+      return { shouldBlock: false, quickModeAllowed };
     }
 
     if (grandfather.allGrandfathered) {
       this.grandfatherLogger("story-reflection", input.targetFilePaths);
-      return { shouldBlock: false };
+      return { shouldBlock: false, quickModeAllowed };
     }
 
     const unitId = scope.unitId;
     if (unitId === undefined) {
-      return { shouldBlock: false };
+      return { shouldBlock: false, quickModeAllowed };
     }
 
     const reflectionResult = await this.storyReflectionQueryPort.checkReflection(unitId);
 
     if (reflectionResult.skipped || reflectionResult.passed) {
-      return { shouldBlock: false };
+      return { shouldBlock: false, quickModeAllowed };
     }
 
     return HandlePreToolUseUseCase.buildStoryReflectionBlockOutput(

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/pre-tool-use-hook.ts

@@ -150,6 +150,14 @@ async function main(): Promise<void> {
       process.exit(2);
     }
 
+    // Quick Mode が write を許可した場合に visibility を上げる informational notice。
+    // exit 0 は維持し semantics は変えない。WI-087 finding #3。
+    if (output.quickModeAllowed !== undefined) {
+      const cat = output.quickModeAllowed.dominantCategory;
+      const suffix = cat !== undefined && cat !== '' ? `, category=${cat}` : '';
+      process.stderr.write(`phasegate: write allowed (Quick Mode${suffix})\n`);
+    }
+
     process.exit(0);
   } catch (error) {
     process.stderr.write(`実行エラー: ${String(error)}\n`);

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,