phasegate 0.120.0 → 0.121.0

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.120.0",
+  "version": "0.121.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/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/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`);