@takuma-hirai/hirai-method 0.1.0

package/.claude/hooks/task-rule-guard.sh

@@ -0,0 +1,317 @@
+#!/usr/bin/env bash
+# task-rule-guard.sh — Task Management 強制 hook
+#
+# 役割:
+#   delegation-guard.sh の弱い「draft が 1 つでもあれば通す」判定を補強し、
+#   下記 4 ルールを Hook block で強制する:
+#
+#   1. ID 重複検知:
+#      task-<id>-*.md / phase-<id>-*.md と同じ <id> が既存なら block
+#   2. 対応 draft 名一致:
+#      task-<id>-<slug>.md の Write は docs/draft/{<slug>.md, task-<slug>.md, <basename>} の
+#      いずれかが存在することを要求
+#   3. parking-lot.md 必須 7 項目（追加時のみ警告レベル）
+#   4. テンプレ章立て（_TASK_TEMPLATE.md 準拠）— additionalContext 注入のみ
+#
+# Args: $1 = tool name (Edit|Write) — JSON tool_name 優先
+# Stdin: PreToolUse JSON
+#
+# Bypass:
+#   ECC_TASKGUARD=off                       # 全 OFF
+#   /task-bypass <slug>                     # 1 ファイル分 pre-clear
+#   ${taskguard_state_dir}/<slug>.cleared   # 上記の実体
+#
+# Subagent passthrough: delegation-guard と同じ多段検出。
+#
+# Config keys consumed (.claude/harness-config.yml):
+#   task_dir / draft_dir       # 判定対象ディレクトリ
+#   taskguard_state_dir        # bypass marker 保存場所
+#   agent_marker_dir           # subagent passthrough 検出
+
+set -u
+
+# config 読み込み (HC_* 変数 export)
+# shellcheck source=lib/config-loader.sh
+source "$(dirname "$0")/lib/config-loader.sh"
+
+# Feature toggle 参照 (task-45 Phase 2)
+if command -v is_feature_enabled >/dev/null 2>&1 && ! is_feature_enabled task_rule_guard; then
+  echo '{}'
+  exit 0
+fi
+
+# Phase β: F2 disable for SWE-bench grid evaluation (fail-open)
+# ECC_F{1,2,3}_OFF env vars allow runner.py to bypass gates per-task
+# while measuring gate effectiveness. Production usage MUST NOT set these.
+if [ "${ECC_F2_OFF:-0}" = "1" ] || [ "${ECC_F2_OFF:-}" = "true" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    jq -n '{decision:"approve", reason:"F2 (task-rule-guard) disabled via ECC_F2_OFF"}'
+  else
+    printf '{"decision":"approve","reason":"F2 (task-rule-guard) disabled via ECC_F2_OFF"}\n'
+  fi
+  exit 0
+fi
+
+# === 全 bypass ===
+if [ "${ECC_TASKGUARD:-}" = "off" ]; then
+  echo '{}'
+  exit 0
+fi
+
+input=$(cat)
+
+# === jq 必須 ===
+if ! command -v jq >/dev/null 2>&1; then
+  echo '{}'
+  exit 0
+fi
+
+# === session id (task-68 §3.2: Edit status-sync note を session 1 回に抑制する marker key) ===
+session_id=$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null)
+if [ -z "$session_id" ] || [ "$session_id" = "null" ]; then
+  session_id="nosess"
+fi
+
+# === tool 取得 ===
+tool=$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)
+if [ -z "$tool" ] || [ "$tool" = "null" ]; then
+  tool="${1:-}"
+fi
+
+# === Edit / Write 以外は素通し ===
+if [ "$tool" != "Edit" ] && [ "$tool" != "Write" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# === subagent passthrough ===
+is_subagent="false"
+if [ "${CLAUDE_HARNESS_ROLE:-}" = "subagent" ]; then
+  is_subagent="true"
+fi
+if [ "$is_subagent" = "false" ]; then
+  for field in agent_type subagent_type parent_tool_use_id agent_id; do
+    v=$(printf '%s' "$input" | jq -r ".${field} // empty" 2>/dev/null)
+    if [ -n "$v" ] && [ "$v" != "null" ]; then
+      is_subagent="true"
+      break
+    fi
+  done
+fi
+if [ "$is_subagent" = "false" ] && [ -d "$HC_AGENT_MARKER_DIR" ]; then
+  if ls "$HC_AGENT_MARKER_DIR"/*.lock >/dev/null 2>&1; then
+    is_subagent="true"
+  fi
+fi
+if [ "$is_subagent" = "true" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# === target file 取得 ===
+file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
+if [ -z "$file" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# === ${draft_dir}/ 配下の Write は plan-first warn 判定 (block しない、honor system) ===
+# task-33 Phase 3 規範化 (list-md-plan-first-normative.md §3 P5、task-36 Step 1 / Step 2):
+#   新規 draft Write が発生した時点で list.md に対応 slug の 📝 行が不在なら warn 注入。
+#   既存 task_glob filter (L下) より前に挿入する必要あり (filter で early-exit するため)。
+#
+# task-36 Step 2 iter2 fix:
+#   F1: Write 限定 (Edit は素通り) — draft の既存 update 時に warn を出さない
+#   F2: slug grep を col 限定 (awk) に変更 — 別 task の description/detail に slug が含まれる
+#       false negative (warn 抑制) を防ぐ。false positive は許容。
+#
+# task-36 Step 2 iter3 fix:
+#   F7: awk col 拡張 (MED-2、reviewer C) — 実 list.md 6 列 format
+#       `| # | Status | Task | 概要 | 依存 | 詳細 |` (awk NF=8、$4=Task / $5=概要 / $6=依存 / $7=詳細)
+#       で slug link が col 7 にある false negative を解消。概要列 ($5) のみ除外して
+#       行全体で slug index 検索 (false positive 回避 + 5 列/6 列 両 format サポート)。
+draft_glob_a="*/${HC_DRAFT_DIR}/*.md"
+draft_glob_b="*/${HC_DRAFT_DIR}/*.mdx"
+# shellcheck disable=SC2254  # 意図的な glob 展開 (case pattern として draft path 判定)
+case "$file" in
+  $draft_glob_a|$draft_glob_b)
+    # F1: Write のみ判定 (Edit は素通り、既存 draft update に warn 不要)
+    if [ "$tool" != "Write" ]; then
+      echo '{}'
+      exit 0
+    fi
+    # template (_DRAFT_TEMPLATE.md 等の underscore prefix) は exempt
+    draft_basename=$(basename "$file")
+    case "$draft_basename" in
+      _*) echo '{}'; exit 0 ;;
+    esac
+    # slug 抽出 (basename から .md / .mdx を除去)
+    draft_slug="${draft_basename%.md}"
+    draft_slug="${draft_slug%.mdx}"
+    # list.md path 算出 (draft path から root 推定)
+    # shellcheck disable=SC2295  # 意図的: HC_DRAFT_DIR は literal path、glob 文字含まない前提
+    draft_root="${file%/${HC_DRAFT_DIR}/*}"
+    list_md_path="${draft_root}/${HC_TASK_DIR}/list.md"
+    # list.md 不在なら silent pass (init 未完了)
+    if [ ! -f "$list_md_path" ]; then
+      echo '{}'
+      exit 0
+    fi
+    # F7 (iter3): 📝 行検出を「概要列 ($5) のみ除外 + 行全体 index 検索」に変更
+    # 対応する list.md 列構成:
+    #   5 列 format (規範): | # | Status | Task | 概要 | 詳細 |              awk NF=7、$5=概要、slug link は $6
+    #   6 列 format (実 list.md): | # | Status | Task | 概要 | 依存 | 詳細 | awk NF=8、$5=概要、slug link は $7
+    #   将来 7 列拡張時も $5 概要列のみ除外 + 残列で検索 で対応可
+    # false positive 回避: 概要列に偶然 slug substring が含まれるケースは $5 を空文字に置換して除外
+    # awk 変数 injection 防止: draft_slug は basename 由来で英数字 + `.` + `-` のみ (kebab-case)、index() は literal 比較で安全
+    # [OFS rewrite 副作用の設計メモ]
+    # `$5 = ""` を実行すると awk は $0 を OFS (default: 空白) で再構築するため、
+    # `|` 区切りが空白に置換される。ただし index($0, slug) は literal 文字列比較であり、
+    # slug は kebab-case (英数字+ハイフンのみ) で空白を含まないため、誤検知ゼロで安全。
+    # 5列 / 6列 / 7列 format 進化耐性のため列番号非依存設計。
+    if awk -F'|' -v slug="$draft_slug" '
+      $3 !~ /📝/ { next }
+      {
+        $5 = ""  # 概要列除外 ($0 が OFS=空白で再構築されるが index() slug 検出には影響なし)
+        if (index($0, slug) > 0) { found = 1; exit }
+      }
+      END { exit (found ? 0 : 1) }
+    ' "$list_md_path" 2>/dev/null; then
+      # 既存 📝 行あり → pass (warn なし)
+      echo '{}'
+      exit 0
+    fi
+    # 📝 行不在 → warn 注入 (block しない)
+    warn_msg="[task-rule-guard] 新規 draft '${draft_basename}' を Write 中ですが、list.md に対応 slug '${draft_slug}' の 📝 行が見当たりません。
+
+batch planning (経路 B、N ≥ 3 task の一括計画) の場合は、先に list.md に 📝 行を先置きしてください。
+単発 task (経路 A) なら本 warn は無視可。
+
+詳細: .claude/rules/task-management.md §plan-first 行先置きフロー (batch planning)"
+    jq -n --arg m "$warn_msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$m}}'
+    exit 0
+    ;;
+esac
+
+# === ${task_dir}/ 配下のみ判定対象（${draft_dir}/ は通過） ===
+task_glob="*/${HC_TASK_DIR}/*"
+case "$file" in
+  $task_glob) ;;
+  *) echo '{}'; exit 0;;
+esac
+
+basename=$(basename "$file")
+root="${file%/${HC_TASK_DIR}/*}"
+
+# === index / template ファイルは exempt ===
+case "$basename" in
+  list.md|parking-lot.md|_TASK_TEMPLATE.md)
+    # parking-lot.md の追加時に必須項目 hint を注入
+    if [ "$basename" = "parking-lot.md" ] && [ "$tool" = "Edit" ]; then
+      jq -n '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:"[task-rule-guard] parking-lot.md 編集中。新規エントリは必須 7 項目（起案日 / 保留日 / 保留理由 / 設計書 / 実装状態 / 再検討トリガー / 代替現状）と ステータス（🧊 / 🔍 / ❌）を含めること。"}}'
+      exit 0
+    fi
+    echo '{}'
+    exit 0
+    ;;
+esac
+
+# === slug 単位 bypass marker ===
+mkdir -p "$HC_TASKGUARD_STATE_DIR" 2>/dev/null
+slug_guess=$(printf '%s' "$basename" | sed -E 's/^(task|phase)-[A-Za-z0-9.]+-(.+)\.md$/\2/' )
+if [ -f "${HC_TASKGUARD_STATE_DIR}/${slug_guess}.cleared" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# === 命名規約判定 ===
+# task-<id>-<slug>.md  または  phase-<id>-<slug>.md  のみ厳格 check
+if ! printf '%s' "$basename" | grep -qE '^(task|phase)-[A-Za-z0-9.]+-.+\.md$'; then
+  # 命名規約外 — 警告のみ
+  jq -n --arg f "$basename" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:("[task-rule-guard] " + $f + " は task-<id>-<slug>.md / phase-<id>-<slug>.md 規約から外れています。意図的なら続行可、ただし list.md との対応を確認すること。")}}'
+  exit 0
+fi
+
+prefix=$(printf '%s' "$basename" | sed -E 's/^(task|phase)-.*$/\1/')
+id=$(printf '%s' "$basename" | sed -E 's/^(task|phase)-([A-Za-z0-9.]+)-.+\.md$/\2/')
+slug=$(printf '%s' "$basename" | sed -E 's/^(task|phase)-[A-Za-z0-9.]+-(.+)\.md$/\2/')
+
+# === Edit（既存編集）は status 同期注意のみ ===
+# task-68 §3.2: status-sync note は advisory のため session 1 回に抑制 (2 回目以降 silent)。
+# enforcement (BLOCK) は一切変更しない。marker は taskguard_state_dir 配下に session_id 付きで作成。
+if [ "$tool" = "Edit" ]; then
+  mkdir -p "$HC_TASKGUARD_STATE_DIR" 2>/dev/null
+  editnote_marker="${HC_TASKGUARD_STATE_DIR}/.editnote-shown-${session_id}"
+  if [ -f "$editnote_marker" ]; then
+    # 既に本 session で 1 回注入済 → silent pass
+    echo '{}'
+    exit 0
+  fi
+  # [code MED-1] marker 書込失敗時の stderr leak guard (task-68 §C):
+  # `: > file 2>/dev/null || true` は一部 shell で redirect 失敗メッセージを stderr に leak する。
+  # `if ! ...; then :; fi` 形式で同等の fail-open を実現しつつ leak を抑止。
+  # BLOCK 判定ロジック (line 256 以降) には一切影響しない。
+  if ! : > "$editnote_marker" 2>/dev/null; then :; fi
+  jq -n --arg id "$id" --arg t "$HC_TASK_DIR" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:("[task-rule-guard] 既存タスク #" + $id + " を編集中。" + $t + "/list.md の同 ID 行と必ず同期更新すること。(本 note は session 1 回のみ)")}}'
+  exit 0
+fi
+
+# === Write 時の厳格 check ===
+
+# (1) ID 重複検知
+shopt -s nullglob 2>/dev/null
+existing=()
+for f in "${root}/${HC_TASK_DIR}/${prefix}-${id}-"*.md; do
+  [ -f "$f" ] || continue
+  if [ "$f" != "$file" ]; then
+    existing+=("$f")
+  fi
+done
+
+if [ ${#existing[@]} -gt 0 ]; then
+  list=$(printf '  - %s\n' "${existing[@]}")
+  reason="[task-rule-guard] BLOCK: ID '${id}' の ${prefix}-* ファイルが既に存在します:
+${list}
+別 ID を割り当てるか、既存ファイルを Edit してください。
+重複作成すると list.md との対応が壊れます。
+
+Bypass: ECC_TASKGUARD=off / ${HC_TASKGUARD_STATE_DIR}/${slug}.cleared を touch"
+  jq -n --arg r "$reason" '{decision:"block", reason:$r}'
+  exit 0
+fi
+
+# (2) 対応 draft 名一致 check
+draft_dir="${root}/${HC_DRAFT_DIR}"
+matched_draft=""
+for candidate in "${slug}.md" "task-${slug}.md" "${basename}"; do
+  if [ -f "${draft_dir}/${candidate}" ]; then
+    matched_draft="${draft_dir}/${candidate}"
+    break
+  fi
+done
+
+if [ -z "$matched_draft" ]; then
+  reason="[task-rule-guard] BLOCK: 対応する設計 draft が見つかりません。
+
+期待される draft path（いずれか）:
+  - ${draft_dir}/${slug}.md
+  - ${draft_dir}/task-${slug}.md
+  - ${draft_dir}/${basename}
+
+設計→承認→タスク化フローを守ってください:
+  1. /new-draft ${slug}             # 設計 draft 起こし
+  2. <内容を埋めて user に承認依頼>
+  3. /new-task ${id} ${slug}        # 承認後にタスク化
+
+例外（hot fix 等）:
+  - ECC_TASKGUARD=off               # 全 OFF
+  - touch ${HC_TASKGUARD_STATE_DIR}/${slug}.cleared    # 1 ファイル分 bypass"
+  jq -n --arg r "$reason" '{decision:"block", reason:$r}'
+  exit 0
+fi
+
+# (3) Pass — list.md 同時更新の念押し
+jq -n --arg d "$(basename "$matched_draft")" --arg id "$id" --arg t "$HC_TASK_DIR" \
+  '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:("[task-rule-guard] OK: draft 一致 (" + $d + ")。次は " + $t + "/list.md に #" + $id + " 行を追加すること。片方のみ更新は禁止。")}}'
+exit 0

package/.claude/hooks/tests/run-tests.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# run-tests.sh — wrapper that runs every test-*.sh in this directory.
+set -u
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+TOTAL_FAIL=0
+TOTAL_RUN=0
+
+for t in "$DIR"/test-*.sh; do
+  [ -f "$t" ] || continue
+  printf "\n=== %s ===\n" "$(basename "$t")"
+  if bash "$t"; then
+    :
+  else
+    TOTAL_FAIL=$((TOTAL_FAIL + 1))
+  fi
+  TOTAL_RUN=$((TOTAL_RUN + 1))
+done
+
+printf "\n=== run-tests.sh summary: %d files run, %d failed ===\n" \
+  "$TOTAL_RUN" "$TOTAL_FAIL"
+
+[ "$TOTAL_FAIL" -eq 0 ]

package/.claude/hooks/tests/test-agent-marker-warn.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# test-agent-marker-warn.sh — smoke tests for agent-marker-set.sh foreground warning
+#
+# Verifies development-process.md "サブエージェント委譲の必須要件" §1:
+#   1. run_in_background=false → stderr に WARNING を出す
+#   2. run_in_background=true  → WARNING を出さない
+#   3. run_in_background 未指定  → WARNING を出す (default false 扱い)
+#   4. どのケースでも stdout は "{}" を返し marker file は作成される
+
+set -u
+
+HOOKS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+HOOK="$HOOKS_DIR/agent-marker-set.sh"
+PASS=0
+FAIL=0
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export HC_AGENT_MARKER_DIR="$TMP/markers"
+
+assert_warn() {
+  local name="$1"
+  local stderr="$2"
+  if printf '%s' "$stderr" | grep -q 'WARNING: subagent launched without run_in_background'; then
+    printf "PASS: %s\n" "$name"
+    PASS=$((PASS + 1))
+  else
+    printf "FAIL: %s\n  expected WARNING in stderr, got: %s\n" "$name" "$stderr"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_no_warn() {
+  local name="$1"
+  local stderr="$2"
+  if printf '%s' "$stderr" | grep -q 'WARNING: subagent launched without run_in_background'; then
+    printf "FAIL: %s\n  expected no warning, got: %s\n" "$name" "$stderr"
+    FAIL=$((FAIL + 1))
+  else
+    printf "PASS: %s\n" "$name"
+    PASS=$((PASS + 1))
+  fi
+}
+
+assert_marker_created() {
+  local name="$1"
+  if ls "$HC_AGENT_MARKER_DIR"/*.lock >/dev/null 2>&1; then
+    printf "PASS: %s (marker created)\n" "$name"
+    PASS=$((PASS + 1))
+  else
+    printf "FAIL: %s (no marker)\n" "$name"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# --- case 1: run_in_background=false ---
+rm -rf "$HC_AGENT_MARKER_DIR"
+out=$(echo '{"session_id":"s1","tool_input":{"run_in_background":false}}' \
+      | bash "$HOOK" 2>/tmp/_amw_err.log)
+err=$(cat /tmp/_amw_err.log)
+assert_warn "foreground (run_in_background=false) emits WARNING" "$err"
+assert_marker_created "foreground still creates marker"
+[ "$(printf '%s' "$out" | tr -d '[:space:]')" = "{}" ] \
+  && { echo "PASS: stdout is {}"; PASS=$((PASS+1)); } \
+  || { echo "FAIL: stdout != {} got=$out"; FAIL=$((FAIL+1)); }
+
+# --- case 2: run_in_background=true ---
+rm -rf "$HC_AGENT_MARKER_DIR"
+out=$(echo '{"session_id":"s2","tool_input":{"run_in_background":true}}' \
+      | bash "$HOOK" 2>/tmp/_amw_err.log)
+err=$(cat /tmp/_amw_err.log)
+assert_no_warn "background (run_in_background=true) no WARNING" "$err"
+assert_marker_created "background creates marker"
+
+# --- case 3: run_in_background absent ---
+rm -rf "$HC_AGENT_MARKER_DIR"
+out=$(echo '{"session_id":"s3","tool_input":{}}' \
+      | bash "$HOOK" 2>/tmp/_amw_err.log)
+err=$(cat /tmp/_amw_err.log)
+assert_warn "absent run_in_background emits WARNING" "$err"
+assert_marker_created "absent still creates marker"
+
+rm -f /tmp/_amw_err.log
+
+printf "\n=== test-agent-marker-warn.sh: %d PASS / %d FAIL ===\n" "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

package/.claude/hooks/tests/test-check-required-env.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# test-check-required-env.sh — smoke tests for check-required-env.sh
+#
+# 検証する仕様:
+#   1. required_env: [] → 出力なし、exit 0
+#   2. error severity の env が未設定 → stderr に MISSING 出力
+#   3. error severity の env が設定済 → 出力なし
+#   4. severity 混在 (error/warn/info) → 各々分類して出力
+#   5. 不正フォーマット (`|` 不足) → skip して exit 0
+#   6. fail-open: 必ず exit 0
+#
+# bash 3.2 互換 (macOS 標準) で動作する。
+
+set -u
+
+HOOKS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+HOOK="$HOOKS_DIR/check-required-env.sh"
+PASS=0
+FAIL=0
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+# Empty config so config-loader doesn't emit a "not found" WARN line that
+# would interfere with stderr-based assertions.
+: > "$TMP/empty.yml"
+
+assert_contains() {
+  local name="$1"
+  local needle="$2"
+  local haystack="$3"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    printf "PASS: %s\n" "$name"
+    PASS=$((PASS + 1))
+  else
+    printf "FAIL: %s\n  expected substring: %s\n  got: %s\n" "$name" "$needle" "$haystack"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_not_contains() {
+  local name="$1"
+  local needle="$2"
+  local haystack="$3"
+  if [[ "$haystack" != *"$needle"* ]]; then
+    printf "PASS: %s\n" "$name"
+    PASS=$((PASS + 1))
+  else
+    printf "FAIL: %s\n  unexpected substring: %s\n  got: %s\n" "$name" "$needle" "$haystack"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+assert_eq() {
+  local name="$1"
+  local expected="$2"
+  local actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    printf "PASS: %s\n" "$name"
+    PASS=$((PASS + 1))
+  else
+    printf "FAIL: %s\n  expected: [%s]\n  actual:   [%s]\n" "$name" "$expected" "$actual"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Helper: run hook with controlled HC_REQUIRED_ENV / additional env vars.
+# Args: <required_env_value> [env-spec...]
+# Captures stderr and exit code.
+run_hook() {
+  local required_env="$1"
+  shift
+  local env_setup=""
+  for spec in "$@"; do
+    env_setup="$env_setup export $spec;"
+  done
+  bash -c "
+    set +u
+    for v in \$(env | grep -oE '^HC_[A-Z_]+' || true); do unset \"\$v\"; done
+    export HC_CONFIG_PATH='$TMP/empty.yml'
+    export HC_REQUIRED_ENV=\$'$required_env'
+    $env_setup
+    bash '$HOOK' </dev/null 2>&1
+    echo \"EXIT_CODE=\$?\"
+  "
+}
+
+# === Case 1: required_env: [] (empty) → no output, exit 0 ===
+out=$(run_hook "")
+exit_line=$(printf '%s\n' "$out" | grep '^EXIT_CODE=' | tail -1)
+non_exit_lines=$(printf '%s\n' "$out" | grep -v '^EXIT_CODE=')
+assert_eq "Case1a: empty required_env -> exit 0" "EXIT_CODE=0" "$exit_line"
+assert_eq "Case1b: empty required_env -> no output" "" "$non_exit_lines"
+
+# === Case 2: error severity unset → MISSING output ===
+out=$(run_hook 'FOO_UNSET|error|critical resource')
+exit_line=$(printf '%s\n' "$out" | grep '^EXIT_CODE=' | tail -1)
+assert_contains "Case2a: error severity unset -> MISSING" \
+  "MISSING required env: FOO_UNSET" "$out"
+assert_contains "Case2b: error message has purpose" "critical resource" "$out"
+assert_eq "Case2c: error severity still exits 0 (fail-open)" "EXIT_CODE=0" "$exit_line"
+
+# === Case 3: error severity set → no warning ===
+out=$(run_hook 'BAR|error|important' "BAR=somevalue")
+exit_line=$(printf '%s\n' "$out" | grep '^EXIT_CODE=' | tail -1)
+non_exit_lines=$(printf '%s\n' "$out" | grep -v '^EXIT_CODE=')
+assert_eq "Case3a: env set -> no output" "" "$non_exit_lines"
+assert_eq "Case3b: env set -> exit 0" "EXIT_CODE=0" "$exit_line"
+
+# === Case 4: severity mixed → each classified ===
+# Use different names to avoid case-3 contamination
+out=$(run_hook 'A_ERR|error|need-A\nB_WARN|warn|need-B\nC_INFO|info|need-C')
+assert_contains "Case4a: error has MISSING marker" "MISSING required env: A_ERR" "$out"
+assert_contains "Case4b: warn has Recommended marker" "Recommended env not set: B_WARN" "$out"
+assert_contains "Case4c: info has Optional marker" "Optional env not set: C_INFO" "$out"
+exit_line=$(printf '%s\n' "$out" | grep '^EXIT_CODE=' | tail -1)
+assert_eq "Case4d: mixed severity -> exit 0" "EXIT_CODE=0" "$exit_line"
+
+# === Case 5: malformed entry (no `|`) → skip + exit 0 ===
+out=$(run_hook 'NOT_A_PIPE_FORMAT')
+exit_line=$(printf '%s\n' "$out" | grep '^EXIT_CODE=' | tail -1)
+non_exit_lines=$(printf '%s\n' "$out" | grep -v '^EXIT_CODE=')
+assert_eq "Case5a: malformed entry skipped (no output)" "" "$non_exit_lines"
+assert_eq "Case5b: malformed entry exit 0" "EXIT_CODE=0" "$exit_line"
+
+# Combined malformed + valid (the malformed should be skipped, valid should fire)
+out=$(run_hook 'NOT_PIPE\nVALID|error|valid one')
+assert_contains "Case5c: valid entry still detected with malformed neighbor" \
+  "MISSING required env: VALID" "$out"
+assert_not_contains "Case5d: malformed entry not in output" "NOT_PIPE" "$out"
+
+# === Case 6: fail-open guarantee ===
+# Even with HC_REQUIRED_ENV containing many error severity entries, exit must be 0.
+out=$(run_hook 'X|error|x\nY|error|y\nZ|error|z')
+exit_line=$(printf '%s\n' "$out" | grep '^EXIT_CODE=' | tail -1)
+assert_eq "Case6: many missing error envs -> still exit 0 (fail-open)" "EXIT_CODE=0" "$exit_line"
+
+printf "\n--- test-check-required-env.sh: %d pass / %d fail ---\n" "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]