phasegate 0.160.9 → 0.160.10

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.160.10] - 2026-05-16
+
+### Fixed
+
+- **WI-203 — Stop hook Complete Check execution** — resolves built-in `phasegate:*` hook commands through the packaged CLI entrypoint instead of unmanaged downstream wrapper files, distinguishes Complete Check validation failures from command wiring failures in strict Stop hook output, and documents that `scripts/harness/cli/complete-check.ts` is not required by standard install/reconcile.
+
 ## [0.160.9] - 2026-05-15
 
 ### Fixed

package/docs/guide/configuration.md

@@ -548,12 +548,14 @@ Controls how phasegate's agent-side hooks integrate with Claude Code. Currently
 
 | 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. |
+| `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. If command invocation itself fails, the reason is `Complete Check execution failed (exitCode=N)`. 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.
 
+The built-in Stop hook invokes the packaged PhaseGate CLI command directly; projects initialized or reconciled by PhaseGate do not need a local `scripts/harness/cli/complete-check.ts` wrapper for this setting. <!-- @work-item-id WI-203 -->
+
 ---
 
 ### Quick Mode

package/docs/guide/hooks-integration.md

@@ -93,8 +93,9 @@ Use /quick-implementor skill for version changes in package.json.
 
 ### Stop (before session end)
 - Runs `phasegate:complete-check` (L2-L4 full validation)
+- The built-in Stop hook runs the packaged PhaseGate CLI command; downstream projects do not need to provide `scripts/harness/cli/complete-check.ts`.
 - 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.
+- 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. If the command cannot be invoked at all, strict mode reports `Complete Check execution failed (exitCode=N)` instead. Reentry-detection still exits 0 regardless of this setting. See `docs/guide/configuration.md` `agentIntegration` section for details. <!-- @work-item-id WI-203 -->
 
 ## Git hook metadata validation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.9",
+  "version": "0.160.10",
   "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/infrastructure/adapters/child-process-cli-executor-adapter.ts

@@ -1,22 +1,36 @@
 /**
  * @layer infrastructure
  * @unit agent-integration
+ * @work-item-id WI-203
  *
  * ChildProcessCliExecutorAdapter
  * CliExecutorPort の実装。子プロセスで CLI コマンドを実行する
  */
 
 import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import type { CliExecutorPort, CliExecutionResult } from '../../application/ports/cli-executor-port.js';
 import { TimeoutError } from '../../application/ports/cli-executor-port.js';
 
+function getHarnessMainPath(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), '../../../main.ts');
+}
+
 /**
  * CommandName を実行可能なコマンドに変換する
- * 例: 'phasegate:lint' → ['npx', 'tsx', 'scripts/harness/cli/lint.ts']
+ * 例: 'phasegate:lint' → ['npx', 'tsx', '<package>/scripts/harness/main.ts', 'phasegate:lint']
  * テスト時は直接スクリプトパスで execute を呼ぶことも可能
  */
 function resolveCommand(commandName: string): { cmd: string; args: string[] } {
-  // コマンド名をファイルパスに変換
+  if (commandName.startsWith('phasegate:')) {
+    return {
+      cmd: 'npx',
+      args: ['tsx', getHarnessMainPath(), commandName],
+    };
+  }
+
+  // Legacy extension commands may still be provided as project-local wrappers.
   const slug = commandName.replace('phasegate:', '');
   return {
     cmd: 'npx',

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

@@ -1,6 +1,7 @@
 /**
  * @layer presentation
  * @unit agent-integration
+ * @work-item-id WI-203
  *
  * Stop Hook Adapter
  * Claude Code の Stop Hook エントリポイント
@@ -19,6 +20,20 @@ interface StopHookInput {
   session_id?: string;
 }
 
+function isCompleteCheckExecutionWiringFailure(stderr: string): boolean {
+  return (
+    /scripts\/harness\/cli\/complete-check\.ts/.test(stderr) ||
+    /ERR_MODULE_NOT_FOUND|Cannot find module/i.test(stderr)
+  );
+}
+
+function formatCompleteCheckFailureReason(exitCode: number, stderr: string): string {
+  if (isCompleteCheckExecutionWiringFailure(stderr)) {
+    return `Complete Check execution failed (exitCode=${exitCode})`;
+  }
+  return `Complete Check failed (exitCode=${exitCode})`;
+}
+
 async function readStdin(): Promise<string> {
   const chunks: Buffer[] = [];
   for await (const chunk of process.stdin) {
@@ -97,10 +112,10 @@ async function main(): Promise<void> {
       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})`;
+          const reason = formatCompleteCheckFailureReason(output.cliResult.exitCode, output.cliResult.stderr);
           process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\n`);
           process.stderr.write(
-            `Complete Check失敗 (exitCode=${output.cliResult.exitCode}) — strict mode により turn を block します\n`,
+            `${reason} — strict mode により turn を block します\n`,
           );
           process.exit(2);
         }