phasegate 0.160.8 → 0.160.10

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
+
+- **WI-201 — config plan apply discoverability** — documents `config:plan --apply` in subcommand help, top-level help, and CLI reference so agents can discover the managed config apply path from `--help`.
+
 ## [0.160.8] - 2026-05-15
 
 ### Fixed

package/docs/guide/cli-reference.md

@@ -28,7 +28,7 @@ Command names in this document are split into three surfaces:
 | `uninstall --dry-run` / `--apply` | Remove PhaseGate-managed files and managed blocks using `.phasegate/manifest.json`; `--force` handles managed conflict cases. |
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes; `--force` allows managed-file replacement with backup. |
 | `setup:agent` | Agent-readable setup planner and optional apply path. Options: `--intent <minimal\|recommended\|strict\|ci-only\|agent-hooks\|retrofit>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-172 --> |
-| `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict>`, `--dry-run`, `--json`. <!-- @work-item-id WI-173 --> |
+| `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict\|retrofit-bootstrap\|planning-mode-relax>`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-173 --> <!-- @work-item-id WI-201 --> |
 | `update-skills` | Compatibility alias for `reconcile`; use `reconcile` for new automation. |
 | `scaffold-wi <unit> <type>` | Create `docs/inception/{unit}/WI-XXX/description.md` using the next free WI number. |
 | `emit-agent-rules` | Print the AGENTS.md / CLAUDE.md WI workflow rules block. |

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.8",
+  "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);
         }

package/scripts/harness/main.ts

@@ -219,7 +219,7 @@ Gate semantics:
   refresh-claude-md            Refresh CLAUDE.md standard sections (--dry-run, --apply, --json)
   p2:check-agent-context       Check AGENTS.md / CLAUDE.md freshness (--threshold-days <n>, --json)
   setup:agent                  Plan agent-driven setup (--intent <minimal|recommended|strict|ci-only|agent-hooks|retrofit>, --agent <claude|codex|both>, --dry-run|--apply, --json)
-  config:plan                  Plan safe config changes (--intent <l4-strict|codex-hooks|ci-fail-on-warning|baseline-reset|quick-mode-strict|retrofit-bootstrap|planning-mode-relax>, --dry-run, --json)
+  config:plan                  Plan safe config changes (--intent <l4-strict|codex-hooks|ci-fail-on-warning|baseline-reset|quick-mode-strict|retrofit-bootstrap|planning-mode-relax>, --dry-run|--apply, --json)
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
   baseline                     Create retrofit baseline snapshot (--dry-run, --force, --paths <glob,glob,...>, --json)
   scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --dry-run|--apply, --force, --json)
@@ -540,6 +540,7 @@ Intents:
 
 Options:
   --dry-run
+  --apply
   --json
   --help, -h                      Show this help`,
   reconcile: `Usage: phasegate reconcile [options]