PlanGate

Hook Enforcement — runtime で強制すべき不変条件

Status: v5（Implementation: 10/10 hooks Done — #169 完走 — #157 で 3 hook、#169 セッション A で 2 / B で 3 / C で 2 = 計 10 hook、3 mode 設計） Hook 数の現状（v8.7.0 以降）: 本書は v8.5.0 時点の 10/10 hooks スナップショット。 v8.6.0 で EH-8（check-metrics-privacy.sh、metrics privacy 強制）、 v8.7.0 で EH-9（check-delegation-commit-boundary.sh、TASK-0073 F2）を追加し、 現状は EH-1〜EH-9 + EHS-1〜EHS-3 = 12/12。本書本文の表は v8.5.0 構成のまま 維持し、追加分の詳細はそれぞれの実装 PR / CHANGELOG / bin/plangate doctor 出力を参照。

実装と物理配線の区別（2026-06-10 棚卸し）: 12/12 は「スクリプト実装 + 単体テスト済み」を指す。発火経路（settings.json / .codex/hooks.json / CI / bin/plangate）への物理配線は 6/12。配線の完全化は #500 Wiring Integrity Enforcement （仕様策定済み）の実装範囲。

配線状態	Hook	発火経路
✅ 配線済み（6）	EH-1 / EH-2 / EH-3 / EH-6 / EH-9	Claude PreToolUse + Codex hooks.json
	EH-8	CI（metrics-privacy.yml）+ doctor + codex-guarded
⏳ 実装済み・未配線（6）	EH-4 / EH-5 / EH-7	発火経路なし（#500 で配線予定）
	EHS-1 / EHS-2 / EHS-3	発火条件の validation_bias: strict 自体が未配線（model-profiles.yaml は参照層）

関連: responsibility-boundary.md / tool-policy.md / model-profiles.md 実装: scripts/hooks/check-plan-exists.sh / check-c3-approval.sh / check-plan-hash.sh / check-test-cases.sh / check-verification-evidence.sh / check-forbidden-files.sh / check-merge-approvals.sh / check-v3-review.sh / check-handoff-elements.sh / check-fix-loop.sh 設定例: .claude/settings.example.json / 単体テスト: tests/hooks/run-tests.sh

1. 目的

PlanGate の Iron Law のうち runtime 強制可能な不変条件（現状 #1〜#7 相当）を、プロンプトに頼らず runtime で決定論的にブロック する。プロンプト薄型化（PBI-116-01 で達成）と両立して、強制力を維持する。なお Iron Law #8（出典照合）は決定論的 hook 化が困難なため、プロンプト + self-review（ソフト面）で担保し runtime hook の対象外とする。

2. 強制すべき不変条件（一覧）

responsibility-boundary.md § 5 と整合。最低 6 件:

EH-1: plan.md なし production code 編集ブロック

• トリガー: docs/working/TASK-XXXX/plan.md が存在しない状態で、production code（CLAUDE.md / AGENTS.md / docs/ai/ / .claude/ / bin/ / schemas/ / plugin/ 等）を編集しようとした
• 対応: Hook が即 block。「plan.md を作成してください」とユーザーに通知
• 基盤: Iron Law #1（C-3 承認前 production 編集禁止）+ #5（承認済 plan との整合性）

EH-2: C-3 承認なし exec ブロック

• トリガー: approvals/c3.json の c3_status: APPROVED がない、または存在しない状態で exec フェーズに進もうとした
• 対応: Hook が即 block。Child C-3 ゲートを促す
• 基盤: Iron Law #1（C-3 承認前 production 編集禁止）

EH-3: plan_hash 改竄検知

• トリガー: approvals/c3.json 発行後、plan.md が変更されたが c3.json の plan_hash が更新されていない

  #282 / TASK-0105 ハードニング: c3.json の plan_hash 抽出を寛容 sed から strict JSON 解析（scripts/plan_hash_util.recorded_plan_hash と意味一致）へ変更。不正 JSON / 非 object / prefix 不一致の c3.json は 承認記録として信用せず空＝SKIP（旧 sed は不正でも plan_hash を抽出し 比較続行＝不正記録を承認境界の根拠にしていた）。承認境界はより厳格化 ＝安全側。正常系（PASS）・改竄検知（BLOCK）の挙動は不変（回帰なし）。

• 対応: Hook が次の operation を block。再承認を要求
• 基盤: Iron Law #5（承認済 plan と実装差分の整合性）

EH-4: test-cases.md なし V-1 ブロック

• トリガー: V-1（受入検査）を試みたが test-cases.md が存在しない
• 対応: Hook が即 block
• 基盤: Iron Law #3（検証証拠なし完了禁止）

EH-5: 検証ログなし PR 作成ブロック

• トリガー: evidence/verification.md または同等のログがないまま子 PR を作成しようとした
• 対応: Hook が PR 作成を block
• 基盤: Iron Law #3（検証証拠なし完了禁止）

EH-6: scope 外ファイル編集検知

• トリガー: 子 PBI YAML の forbidden_files に該当するファイルを編集
• 対応: Hook が即停止
• 基盤: Iron Law #2（PBI 外 scope 追加禁止）

EH-7: 2 段階レビューなしマージブロック（推奨）

• トリガー: C-3 + C-4 のいずれかが APPROVED でない状態で main へマージ試行
• 対応: GitHub branch protection / Hook で block
• 基盤: Iron Law #7（2 段階レビューなしマージ禁止）

EH-9: 委譲 commit/push 境界検知（F2 / TASK-0073）

• トリガー: 委譲タスクが delegation_commit_boundary: no-commit を宣言 （env PLANGATE_DELEGATION_NOCOMMIT=1）した文脈で git commit / git push 試行
• 対応: default=block（bypass・未宣言のみ従来動作=誤検出ゼロ。warn 廃止）。git -c/-C/env 前置/command git/gh pr merge/sh -c 等の回避形を網羅。信頼境界=stdin JSON 正本
• 基盤: #239 問題2（委譲先 Behavior Rule 不遵守）の決定論ガード化

3. validation_bias: strict 時の追加条件

Model Profile の validation_bias: strict プロファイル（gpt-5_5_pro）では、上記 EH-1〜EH-7 に加えて以下 3 件以上を追加で強制:

EHS-1: V-3 外部レビュー必須化

• トリガー: standard 以上の mode で V-3 外部 AI レビューなしに PR 作成
• 対応: Hook が PR 作成 block

EHS-2: handoff.md 必須 6 要素チェック

• トリガー: handoff.md が必須 6 要素（要件適合 / 既知課題 / V2 候補 / 妥協点 / 引き継ぎ文書 / テスト結果）を欠く
• 対応: Hook が WF-05 完了を block

EHS-3: V-1 fix loop 上限超過 escalation

• トリガー: V-1 FAIL → fix → V-1 のループが 5 回を超過
• 対応: Hook が ABORT、ユーザー判断にエスカレーション

4. 実装（#157 で 3 hook + #169 で 7 hook = 計 10 hook、すべて完了）

Hook	種別	実装	由来
EH-1（plan.md なし production code 編集 block）	PreToolUse hook	scripts/hooks/check-plan-exists.sh	#169 セッション A / TASK-0056
EH-2（C-3 未承認 exec block）	PreToolUse hook	scripts/hooks/check-c3-approval.sh	#157 / TASK-0048
EH-3（plan_hash 改竄検知）	PreToolUse hook + CLI	scripts/hooks/check-plan-hash.sh	#169 セッション A / TASK-0056
EH-4（test-cases.md なし V-1 block）	CLI（V-1 前で呼び出し）	scripts/hooks/check-test-cases.sh	#169 セッション B / TASK-0057
EH-5（検証ログなし PR 作成 block）	CLI（PR 作成前で呼び出し）	scripts/hooks/check-verification-evidence.sh	#169 セッション B / TASK-0057
EH-6（scope 外ファイル編集検知）	PreToolUse hook + CLI	scripts/hooks/check-forbidden-files.sh	#169 セッション B / TASK-0057
EH-7（2 段階レビューなしマージ block）	CLI（マージ前で呼び出し）	scripts/hooks/check-merge-approvals.sh	#169 セッション C / TASK-0058
EHS-1（V-3 外部レビュー必須化）	CLI（mode 連携）	scripts/hooks/check-v3-review.sh	#169 セッション C / TASK-0058
EHS-2（handoff 必須 6 要素）	CLI（手動 / WF-05 で呼び出し）	scripts/hooks/check-handoff-elements.sh	#157 / TASK-0048
EHS-3（fix loop 上限超過）	CLI（V-1 fix loop 内で increment / check）	scripts/hooks/check-fix-loop.sh	#157 / TASK-0048
EH-9（委譲 commit/push 境界検知）	PreToolUse hook（Bash 前）	scripts/hooks/check-delegation-commit-boundary.sh	#239 問題2 / TASK-0073
auth-preflight（exec 前 認証三点検証）	CLI（exec 前で呼び出し）	scripts/hooks/check-auth-preflight.sh	#239 問題3 / TASK-0073

残未実装: なし（10/10 完了）。EH-7 の GitHub branch protection 自動連携は別 PBI 候補。

4.1 3 モード設計

モード	環境変数	挙動
default（推奨初期値）	なし	違反検出時は warning のみ、continue:true（block しない）。誤検出時の作業妨害を最小化
strict	PLANGATE_HOOK_STRICT=1	違反検出時に block / exit 1。本番運用 / CI 等で有効化
bypass	PLANGATE_BYPASS_HOOK=1	常時 pass。緊急対応 / 既知の例外時のみ使用、監査 log に必ず記録

4.2 監査ログ

すべての判定は docs/working/_audit/hook-events.log に append-only で記録される（タブ区切り）:

<ISO8601 UTC>\t<level>\t<hook-name>\t<task-id>\t<message>

level: PASS / VIOLATION / BYPASS / SKIP / INCREMENT

4.3 設定方法（opt-in）

.claude/settings.example.json を .claude/settings.json にコピーすると PreToolUse hook（EH-1 + EH-2 + EH-3 + EH-6）+ SessionStart（gh-pin-account）が有効化される。EH-4 / EH-5 / EH-7 / EHS-1 / EHS-2 / EHS-3 は CLI ツールとして workflow 内で呼び出す。

4.4 テスト

• 単体: sh tests/hooks/run-tests.sh → 42 件 PASS（#157 で 12 + #169 セッション A で +9 + B で +12 + C で +9）
• 統合: sh tests/run-tests.sh の TA-06 で hook 子テストを呼び出し

4.5 全 10 hook 完了（#169 完走）

Issue #169 完了。10/10 hooks 実装済（CLI / PreToolUse 構成）。残課題は GitHub branch protection 自動連携（EH-7 の上位拡張、外部 GitHub API 操作を伴うため別 PBI）。

5. 既存 .claude/settings.json hooks との関係

本ファイルが定義する不変条件は、既存 hooks（もしあれば）と:

• 重複なし: 既存 hooks は本ファイルの実装で参照すべき入口
• 追加: EH-1〜EH-7 + EHS-1〜EHS-3 を新規実装
• 既存 v8.1 ガードレール（plugin/plangate/rules/*-gate.md）との関係: Plugin 配布版の追加ガードレールとして共存（responsibility-boundary.md § 6 参照）

6. 「block 通知」の文言ガイド

Hook が block する際の通知文言:

[Hook EH-1] plan.md がないため production code を編集できません。
docs/working/TASK-XXXX/plan.md を作成してください。

形式:

• [Hook EH-N] プレフィックスで該当条件を識別
• 1 行サマリ + 解消手順 1 行
• 詳細は本ファイルへリンク

関連

• 親計画: docs/working/PBI-116/parent-plan.md
• 責務境界: responsibility-boundary.md
• Tool Policy: tool-policy.md
• Model Profile: model-profiles.md
• Iron Law 8 項目: core-contract.md § 4
• Phase 1 成果: core-contract.md

This site is open source. Improve this page.