phasegate 0.119.0 → 0.121.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ 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
+
+- **WI-087 Phase B + WI-086 finding #1 統合対応: `phasegate init` のデフォルト値を実プロジェクト構成に追従させる** — 外部レポーター nakataj-mti / junpei-9898 が GitHub Issue [#3](https://github.com/junpei-9898/phasegate/issues/3) / [#2](https://github.com/junpei-9898/phasegate/issues/2) で報告した「デプロイされる `hook-config.json` のデフォルト値が単一パッケージ構成（`targetDirs:["src"]` / `formatter:"biome"`）固定で、モノレポ構成や biome 不在環境ではユーザーが明示的に書き換えない限り hook が silent no-op になる」問題を修正。
+  - **モノレポ workspace 自動検出** (`scripts/harness/setup/skill-deployer.ts:detectWorkspaceTargetDirs`): `pnpm-workspace.yaml` の `packages:` 配列 → `package.json.workspaces` (配列形式 / `{packages:[...]}` オブジェクト形式の両対応) → `lerna.json.packages` の優先順位で検出。検出した workspace glob (`pkg/*` 等) を実 FS 上で展開し、`<workspace>/src` ディレクトリが存在するもののみを `targetDirs` に採用。pnpm-workspace.yaml は依存追加を避けるため line-based の最小 parser で対応 (`packages:` ブロック検出 + `- 'pattern'` 行抽出のみ)。
+  - **formatter 自動検出** (`detectFormatter`): `package.json.devDependencies` (および `dependencies`) を読み、`@biomejs/biome` 存在 → `biome` + `["check","--write"]`、不在 + `prettier` 存在 → `eslint-prettier`、どちらも不在 → `null` (formatter フィールド省略で `format-typescript-hook.sh` の case 文 default フォールスルー、registry pull を回避)。
+  - **`deployHookScripts` 拡張**: `copyDirectory` 直前に既存 `.claude/scripts/hook-config.json` を捕捉し、(a) 既存あり → 元の内容を書き戻して **ユーザーカスタマイズ尊重**、(b) 既存なし → 検出結果を反映した新規 hook-config.json を生成。`DeployHooksResult` に `hookConfigGenerated` / `detectedTargetDirs` / `detectedFormatter` を追加し、`scripts/harness/main.ts` の init 出力に `✓ hook-config.json generated (targetDirs: ...; formatter: ...)` 行を追加。
+  - **`initHarnessConfig` テンプレートに `architecture: { preset: "clean" }` を追加**: 新規プロジェクトで生成される `phasegate.config.json` が schemaVersion = 'v3' と判定されるようにし、`init` 直後の v2 schema warning を解消（GitHub Issue #2 の "v2 schema warning が phasegate init 直後でも出る" を解消）。既存 v2 config を持つプロジェクトは `migrate-schema` CLI / 手動編集ルートを継続。
+  - **テスト追加**: `scripts/harness/__tests__/integration/setup/init-hook-config-detection.integration.test.ts` (14 ケース) — workspace 検出 (pnpm/npm/yarn 配列/yarn オブジェクト/lerna/未定義/src 不在/全 src 不在)、formatter 検出 (biome/prettier/null)、hook-config.json 生成 (既存尊重 / 新規生成)、schema v3 化 (architecture フィールド存在 / `phasegate:status` の stderr に v2 warning が出ないこと)。
+  - **互換性**: 既存 v2 config を読む load-resolved-config-use-case 側は変更なし。既存 `.claude/scripts/hook-config.json` をカスタマイズ済みのプロジェクトで `phasegate init` を再実行しても上書きされない (write-back ガード)。
+  - **スコープ外** (Phase C で対応予定): Quick Mode 通過時の stderr notice (finding #3) / Stop hook `--enforce` flag (finding #4) / `pre-tool-use` の責務範囲ドキュメント明文化 (WI-086)。
+
 ## [0.119.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.119.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`);

package/scripts/harness/main.ts

@@ -469,7 +469,13 @@ async function main(): Promise<void> {
         const configResult = await initHarnessConfig(rootDir, projectName, phasePreset);
         const hooksResult = deployClaude
           ? await deployHookScripts(harnessRoot, rootDir)
-          : { scriptsDeployed: 0, settingsCreated: false };
+          : {
+              scriptsDeployed: 0,
+              settingsCreated: false,
+              hookConfigGenerated: false,
+              detectedTargetDirs: [] as string[],
+              detectedFormatter: null,
+            };
         const codexResult = deployCodex ? await deployCodexHooks(harnessRoot, rootDir) : null;
         const designDocsResult = await deployDesignDocs(harnessRoot, rootDir);
         const withHusky = hasFlag(args, "--with-husky");
@@ -486,6 +492,13 @@ async function main(): Promise<void> {
         if (hooksResult.scriptsDeployed > 0) {
           console.log(`✓ Hook scripts deployed to .claude/scripts/ (${hooksResult.scriptsDeployed} files)`);
         }
+        if (hooksResult.hookConfigGenerated) {
+          const dirsLabel = hooksResult.detectedTargetDirs.join(", ");
+          const formatterLabel = hooksResult.detectedFormatter ?? "none";
+          console.log(
+            `✓ hook-config.json generated (targetDirs: ${dirsLabel}; formatter: ${formatterLabel})`,
+          );
+        }
         if (hooksResult.settingsCreated) {
           console.log(`✓ .claude/settings.json created`);
         } else if (hooksResult.scriptsDeployed > 0) {

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

@@ -197,15 +197,159 @@ export async function deployAgentSkillLinks(
 export interface DeployHooksResult {
   scriptsDeployed: number;
   settingsCreated: boolean;
+  hookConfigGenerated: boolean;
+  detectedTargetDirs: string[];
+  detectedFormatter: string | null;
+}
+
+// pnpm-workspace.yaml の packages: 配列を line-based でパースする最小実装。
+// 依存追加を避けつつ pnpm の workspace 定義を扱う。
+function parsePnpmWorkspacePackages(yaml: string): string[] {
+  const lines = yaml.split(/\r?\n/);
+  const packages: string[] = [];
+  let inPackages = false;
+  let packagesIndent = -1;
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/#.*$/, "").replace(/\s+$/, "");
+    if (line.length === 0) continue;
+    const indent = line.length - line.trimStart().length;
+    if (!inPackages) {
+      if (/^packages\s*:\s*$/.test(line)) {
+        inPackages = true;
+        packagesIndent = indent;
+      }
+      continue;
+    }
+    if (indent <= packagesIndent) {
+      // packages: ブロックを抜けた
+      inPackages = false;
+      continue;
+    }
+    const itemMatch = line.match(/^\s*-\s*['"]?([^'"#]+?)['"]?\s*$/);
+    if (itemMatch) {
+      packages.push(itemMatch[1].trim());
+    }
+  }
+  return packages;
+}
+
+// 単純な末尾 `*` glob (`pkg/*`) のみを展開する。`**` 等のネストパターンは対象外。
+async function expandWorkspaceGlobs(projectRoot: string, patterns: string[]): Promise<string[]> {
+  const expanded = new Set<string>();
+  for (const pattern of patterns) {
+    if (pattern.includes("**")) {
+      // 安全のため、再帰 glob は無視（無限ループ・性能を避ける）
+      continue;
+    }
+    if (pattern.endsWith("/*")) {
+      const baseDir = pattern.slice(0, -2);
+      try {
+        const entries = await fs.readdir(join(projectRoot, baseDir), { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory() && !entry.name.startsWith(".")) {
+            expanded.add(`${baseDir}/${entry.name}`);
+          }
+        }
+      } catch {}
+    } else {
+      // glob なし: そのまま採用（ディレクトリ存在チェックは後段で実施）
+      expanded.add(pattern);
+    }
+  }
+  return [...expanded];
+}
+
+export async function detectWorkspaceTargetDirs(projectRoot: string): Promise<string[]> {
+  let patterns: string[] = [];
+
+  // 1. pnpm-workspace.yaml
+  try {
+    const yamlContent = await fs.readFile(join(projectRoot, "pnpm-workspace.yaml"), "utf-8");
+    patterns = parsePnpmWorkspacePackages(yamlContent);
+  } catch {}
+
+  // 2. package.json の workspaces (npm/yarn)
+  if (patterns.length === 0) {
+    try {
+      const pkgRaw = await fs.readFile(join(projectRoot, "package.json"), "utf-8");
+      const pkg = JSON.parse(pkgRaw) as { workspaces?: string[] | { packages?: string[] } };
+      const workspaces = pkg.workspaces;
+      if (Array.isArray(workspaces)) {
+        patterns = workspaces;
+      } else if (workspaces && Array.isArray(workspaces.packages)) {
+        patterns = workspaces.packages;
+      }
+    } catch {}
+  }
+
+  // 3. lerna.json
+  if (patterns.length === 0) {
+    try {
+      const lernaRaw = await fs.readFile(join(projectRoot, "lerna.json"), "utf-8");
+      const lerna = JSON.parse(lernaRaw) as { packages?: string[] };
+      if (Array.isArray(lerna.packages)) {
+        patterns = lerna.packages;
+      }
+    } catch {}
+  }
+
+  if (patterns.length === 0) {
+    return ["src"];
+  }
+
+  const workspaceDirs = await expandWorkspaceGlobs(projectRoot, patterns);
+  const targetDirs: string[] = [];
+  for (const ws of workspaceDirs) {
+    try {
+      const stats = await fs.stat(join(projectRoot, ws, "src"));
+      if (stats.isDirectory()) {
+        targetDirs.push(`${ws}/src`);
+      }
+    } catch {}
+  }
+
+  // workspace 定義は見つかったが src/ を持つものが一切ない場合は ["src"] にフォールバック
+  return targetDirs.length > 0 ? targetDirs.sort() : ["src"];
+}
+
+export interface DetectedFormatter {
+  formatter: string | null;
+  formatterArgs: string[];
+}
+
+export async function detectFormatter(projectRoot: string): Promise<DetectedFormatter> {
+  try {
+    const pkgRaw = await fs.readFile(join(projectRoot, "package.json"), "utf-8");
+    const pkg = JSON.parse(pkgRaw) as {
+      devDependencies?: Record<string, string>;
+      dependencies?: Record<string, string>;
+    };
+    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (allDeps["@biomejs/biome"]) {
+      return { formatter: "biome", formatterArgs: ["check", "--write"] };
+    }
+    if (allDeps["prettier"]) {
+      return { formatter: "eslint-prettier", formatterArgs: [] };
+    }
+  } catch {}
+  return { formatter: null, formatterArgs: [] };
 }
 
 export async function deployHookScripts(harnessRoot: string, projectRoot: string): Promise<DeployHooksResult> {
   const templateDir = join(harnessRoot, HOOKS_TEMPLATE_DIR);
   const targetDir = join(projectRoot, HOOKS_TARGET_DIR);
 
-  // scripts/ ディレクトリをコピー
   const scriptsSource = join(templateDir, "scripts");
   const scriptsTarget = join(targetDir, "scripts");
+  const hookConfigPath = join(scriptsTarget, "hook-config.json");
+
+  // copyDirectory で全 scripts/ を上書きするため、ユーザーカスタマイズを尊重するには
+  // 事前に hook-config.json の既存内容を捕捉して後で復元する。
+  let preexistingHookConfig: string | null = null;
+  try {
+    preexistingHookConfig = await fs.readFile(hookConfigPath, "utf-8");
+  } catch {}
+
   let scriptsDeployed = 0;
 
   try {
@@ -221,6 +365,29 @@ export async function deployHookScripts(harnessRoot: string, projectRoot: string
     }
   } catch {}
 
+  // hook-config.json の決定:
+  //   既存あり → ユーザーカスタマイズ尊重で元の内容を書き戻し
+  //   既存なし → 検出結果を反映して新規生成
+  const detectedTargetDirs = await detectWorkspaceTargetDirs(projectRoot);
+  const { formatter, formatterArgs } = await detectFormatter(projectRoot);
+  let hookConfigGenerated = false;
+
+  if (scriptsDeployed > 0) {
+    if (preexistingHookConfig !== null) {
+      await fs.writeFile(hookConfigPath, preexistingHookConfig, "utf-8");
+    } else {
+      const hookConfig: Record<string, unknown> = {
+        targetDirs: detectedTargetDirs,
+      };
+      if (formatter !== null) {
+        hookConfig.formatter = formatter;
+        hookConfig.formatterArgs = formatterArgs;
+      }
+      await fs.writeFile(hookConfigPath, JSON.stringify(hookConfig, null, 2) + "\n", "utf-8");
+      hookConfigGenerated = true;
+    }
+  }
+
   // settings.json を作成（既存があればスキップ）
   const settingsSource = join(templateDir, "settings.json");
   const settingsTarget = join(targetDir, "settings.json");
@@ -238,7 +405,13 @@ export async function deployHookScripts(harnessRoot: string, projectRoot: string
     } catch {}
   }
 
-  return { scriptsDeployed, settingsCreated };
+  return {
+    scriptsDeployed,
+    settingsCreated,
+    hookConfigGenerated,
+    detectedTargetDirs,
+    detectedFormatter: formatter,
+  };
 }
 
 export async function initHarnessConfig(
@@ -259,6 +432,9 @@ export async function initHarnessConfig(
       name: projectName,
       preset: "standard",
     },
+    architecture: {
+      preset: "clean",
+    },
     layers: {},
     quickMode: {},
     phaseDependencies: {