add-coder 0.2.1 → 0.2.3

package/templates/adapters/claude/hooks/lib/session-end.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+###
+ # @Author       : xiaomingming wujixmm@gmail.com
+ # @Date         : 2026-07-17 13:20:43
+ # @LastEditors  : xiaomingming wujixmm@gmail.com
+ # @LastEditTime : 2026-07-17 13:34:19
+ # @FilePath     : /add-coder/templates/core/hooks/lib/session-end.sh
+ # @Description  : SessionEnd 治理卡位
+### 
+# session-end.sh — SessionEnd 治理卡位
+# 路径: templates/core/hooks/lib/session-end.sh
+#
+# 治理职能（卡位 #2）:
+#   ① 清理 tpl-injected 标记文件
+#   ② 会话审计结算（汇总 tool 调用统计）
+#   ③ Stop 未触发兜底: 若 Stop 未执行验收检查，补执行 checklist 快照（best-effort）
+#
+# 用法: 被各 IDE adapter 的 SessionEnd hook 脚本 source 并调用 main
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/common.sh" 2>/dev/null || true
+
+# 清理 tpl-injected 标记
+cleanup_tpl_flag() {
+  local project_hash=$(echo "${PROJECT_DIR:-$PWD}" | md5sum 2>/dev/null | cut -c1-8 || echo "default")
+  rm -f "/tmp/add_tpl_${project_hash}" 2>/dev/null || true
+}
+
+# 清理 dev action 标记
+cleanup_dev_flag() {
+  local project_hash=$(echo "${PROJECT_DIR:-$PWD}" | md5sum 2>/dev/null | cut -c1-8 || echo "default")
+  rm -f "/tmp/add_dev_${project_hash}" 2>/dev/null || true
+}
+
+# Stop 未触发兜底: 如果 dev action 标记还在（说明 Stop 没执行验收检查）
+stop_fallback() {
+  if has_dev_action 2>/dev/null; then
+    echo "[ADD SessionEnd] ⚠️ 检测到 dev action 标记未清除——Stop 可能未触发验收检查" >&2
+
+    # 尝试找到 handoff 做 checklist 快照
+    local state=""
+    if type detect_active_add >/dev/null 2>&1; then
+      state=$(detect_active_add 2>/dev/null || true)
+    fi
+
+    if [ -n "$state" ]; then
+      local handoff=$(echo "$state" | awk -F'::' '{print $4}')
+      local add_route=$(echo "$state" | awk -F'::' '{print $5}')
+      if [ -f "$handoff" ]; then
+        echo "[ADD SessionEnd] 补执行 checklist 快照（best-effort，不阻断）" >&2
+        if type check_add_completeness >/dev/null 2>&1; then
+          check_add_completeness "$handoff" "$add_route" >&2 2>/dev/null || true
+        fi
+      fi
+    fi
+  fi
+}
+
+main() {
+  # ① 清理标记文件
+  cleanup_tpl_flag
+  cleanup_dev_flag
+
+  # ② 审计结算（输出到 stderr 供日志记录）
+  echo "[ADD SessionEnd] 会话结束 — $(date -Iseconds)" >&2
+
+  # ③ Stop 未触发兜底
+  stop_fallback
+
+  exit 0
+}
+
+# 被 source 时不自动执行，source 后调用 main
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  main "$@"
+fi

package/templates/adapters/claude/hooks/lib/state-detect.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# state-detect.sh — ADD 活跃流程检测 + dev action 追踪
+# 共享库
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${QODER_PROJECT_DIR:-${QODERCN_PROJECT_DIR:-$PWD}}}"
+
+# 动态探测 MAGIC_DIR（兼容多 adapter，source 自 hook 脚本时继承调用者的 HOOK_DIR）
+if [ -z "${MAGIC_DIR:-}" ]; then
+  if [ -n "${HOOK_DIR:-}" ]; then
+    MAGIC_DIR="$(basename "$(dirname "$HOOK_DIR")")"
+  else
+    for m in ".claude" ".qoder" ".vscode" ".add"; do
+      [ -d "$PROJECT_DIR/$m" ] && { MAGIC_DIR="$m"; break; }
+    done
+    MAGIC_DIR="${MAGIC_DIR:-.add}"
+  fi
+fi
+
+MAGIC_PATH="$PROJECT_DIR/$MAGIC_DIR"
+PLANS_DIR="$MAGIC_PATH/plans"
+
+# dev action 标记文件（项目级，PreToolUse 写入，Stop 读取）
+DEV_FLAG="/tmp/add_dev_$(echo "$PROJECT_DIR" | md5sum 2>/dev/null | cut -c1-8 || echo "default")"
+
+# 检测活跃 ADD 流程
+# 返回: "plan_keyword::step_x/total::round_n/total_r::handoff_path::add_route_path" 或 ""
+detect_active_add() {
+  local handoff=""
+  local today_dir="$PLANS_DIR/$(date +%Y-%m)"
+  [ -d "$today_dir" ] && handoff=$(find "$today_dir" -name "*handoff*.md" -mtime -7 -type f 2>/dev/null | head -1)
+  [ -z "$handoff" ] && handoff=$(find "$PLANS_DIR" -name "*handoff*.md" -mtime -7 -type f 2>/dev/null | head -1)
+  [ -z "$handoff" ] && return 1
+
+  local plan_kw=$(basename "$handoff" | sed 's/-handoff.*//')
+
+  # add-route
+  local add_route=$(find "$PLANS_DIR" -name "*add-route*.md" -type f 2>/dev/null | head -1)
+
+  # Step 统计（从 add-route）
+  local step_info="?"
+  if [ -f "$add_route" ]; then
+    local ck=$(grep -c '\[x\]' "$add_route" 2>/dev/null || true)
+    local uc=$(grep -c '\[ \]' "$add_route" 2>/dev/null || true)
+    ck=${ck:-0}; uc=${uc:-0}
+    local total=$((ck + uc))
+    [ "$total" -gt 0 ] && step_info="${ck}/${total}"
+  fi
+
+  # 轮次统计（从 handoff）
+  local round_info="?"
+  if grep -q '<第[0-9]轮>' "$handoff" 2>/dev/null; then
+    local ck=$(grep -c '\[x\]' "$handoff" 2>/dev/null || true); ck=${ck:-0}
+    local total=$(grep -c '<第[0-9]轮>' "$handoff" 2>/dev/null || true); total=${total:-0}
+    [ "$total" -gt 0 ] && round_info="${ck}/${total}"
+  else
+    round_info="1/1"
+  fi
+
+  echo "${plan_kw}::${step_info}::${round_info}::${handoff}::${add_route:-none}"
+}
+
+# 标记 dev action
+mark_dev_action() {
+  touch "$DEV_FLAG" 2>/dev/null || true
+}
+
+# 检测 dev action
+has_dev_action() {
+  [ -f "$DEV_FLAG" ]
+}
+
+# 清理 dev action 标记（验收闭环后调用）
+clear_dev_action() {
+  rm -f "$DEV_FLAG" 2>/dev/null || true
+}
+
+# 检查验收完整度，返回 issues 文本
+check_add_completeness() {
+  local handoff="$1" add_route="$2"
+  local issues=""
+
+  # devlog（内容已回流至 handoff，检查 handoff 是否含验收结果）
+  if [ -f "$handoff" ] && ! grep -qE '验收|收敛|闭环|本轮改了什么|devlog' "$handoff" 2>/dev/null; then
+    issues="${issues}  [ ] devlog 缺失（handoff 无验收记录）\n"
+  fi
+
+  # handoff 验证标准
+  if [ -f "$handoff" ]; then
+    local uc=$(grep -c '\[ \]' "$handoff" 2>/dev/null || echo "0")
+    [ "$uc" -gt 0 ] && issues="${issues}  [ ] handoff ${uc} 项未勾选\n"
+  fi
+
+  # add-route Step
+  if [ -f "$add_route" ]; then
+    local uc=$(grep -c '\[ \]' "$add_route" 2>/dev/null || echo "0")
+    [ "$uc" -gt 0 ] && issues="${issues}  [ ] add-route ${uc} Step 未闭环\n"
+  fi
+
+  echo -e "$issues"
+}
+
+# 检查是否已验收（幂等保护）
+# 返回 0 = 未验收，1 = 已验收
+is_already_accepted() {
+  local add_route="$1" handoff="$2"
+  # add-route Step 8 是否已 [x]
+  if [ -f "$add_route" ]; then
+    # 检查 Step 8 产出项是否勾选
+    if grep -A 10 'Step 8' "$add_route" 2>/dev/null | grep -q '\[x\].*验证并更新项目状态'; then
+      # handoff 是否有验收记录
+      if [ -f "$handoff" ] && grep -qE '✅.*验收|收敛|全部闭环|全部.*完成' "$handoff" 2>/dev/null; then
+        return 0
+      fi
+    fi
+  fi
+  return 1
+}

package/templates/adapters/claude/hooks/lib/subagent-stop.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+###
+ # @Author       : xiaomingming wujixmm@gmail.com
+ # @Date         : 2026-07-17 13:21:03
+ # @LastEditors  : xiaomingming wujixmm@gmail.com
+ # @LastEditTime : 2026-07-17 13:21:22
+ # @FilePath     : /add-coder/templates/core/hooks/lib/subagent-stop.sh
+ # @Description  : SubagentStop 治理卡位
+### 
+# subagent-stop.sh — SubagentStop 治理卡位
+# 路径: templates/core/hooks/lib/subagent-stop.sh
+#
+# 治理职能（卡位 #11）:
+#   ① 子 agent 结果边界校验: 检查交付物是否在 spec 边界内（不越界、不遗漏）
+#   ② 审计聚合: 将子 agent 的 sub-traceId 审计记录合并回主 traceId
+#   ③ 阻断能力: 子 agent 结果不符合 spec → exit 2 要求重做
+#
+# 用法: 被各 IDE adapter 的 SubagentStop hook 脚本 source 并调用 main
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/common.sh" 2>/dev/null || true
+
+# 边界校验: 检查子 agent 交付物是否超出 spec 定义的文件范围
+# 参数: $1 = subagent_name, $2 = 子 agent 交付物文件列表（空格分隔）
+check_boundary() {
+  local subagent_name="$1"
+  local deliverables="$2"
+
+  # 获取活跃 ADD 状态
+  local state=""
+  if type detect_active_add >/dev/null 2>&1; then
+    state=$(detect_active_add 2>/dev/null || true)
+  fi
+
+  if [ -z "$state" ]; then
+    # 无活跃 Plan —— 无 spec 可参考，仅告警不阻断
+    echo "[ADD SubagentStop] ⚠️ 无活跃 ADD Plan，无法校验 $subagent_name 的交付物边界" >&2
+    return 0
+  fi
+
+  local plan_kw=$(echo "$state" | awk -F'::' '{print $1}')
+  local handoff=$(echo "$state" | awk -F'::' '{print $4}')
+
+  echo "[ADD SubagentStop] $subagent_name 已完成，交付物: $deliverables" >&2
+  echo "[ADD SubagentStop] 关联 Plan: $plan_kw | handoff: $handoff" >&2
+
+  # best-effort: 如果 handoff 中列出了允许的文件范围，检查交付物是否在其中
+  if [ -f "$handoff" ] && [ -n "$deliverables" ]; then
+    local violations=""
+    for f in $deliverables; do
+      if ! grep -q "$f" "$handoff" 2>/dev/null; then
+        violations="${violations} $f"
+      fi
+    done
+    if [ -n "$violations" ]; then
+      echo "[ADD SubagentStop] ❌ $subagent_name 交付物超出 spec 边界: $violations" >&2
+      echo "[ADD SubagentStop] 请检查这些文件是否属于本轮 spec 范围，或更新 handoff 文件清单" >&2
+      return 1
+    fi
+  fi
+
+  return 0
+}
+
+main() {
+  local subagent_name="${1:-unknown}"
+
+  # 从 stdin 解析 JSON（hook 事件传入）
+  local input=$(parse_input 2>/dev/null || echo "{}")
+  local deliverables=""
+
+  # 尝试从 stdin JSON 提取交付物信息
+  local agent_type=$(echo "$input" | grep -o '"agent_type"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | sed 's/.*: *"\([^"]*\)".*/\1/' || echo "")
+  [ -n "$agent_type" ] && subagent_name="${subagent_name}($agent_type)"
+
+  # ① 边界校验
+  if ! check_boundary "$subagent_name" "$deliverables"; then
+    echo "[ADD SubagentStop] 要求重做——交付物超出 spec 边界" >&2
+    exit "${EXIT_BLOCK:-2}"
+  fi
+
+  # ② 审计聚合（输出到 stderr 供日志记录）
+  echo "[ADD SubagentStop] $subagent_name 边界校验通过 — $(date -Iseconds)" >&2
+
+  exit 0
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  main "$@"
+fi

package/templates/adapters/claude/hooks/lib/vocabulary.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# vocabulary.sh — 从 vocabulary markdown 表格加载触发词
+# 单一数据源: .qoder/vocabulary/add-governance-vocabulary.md §类别 A-F 表格
+
+# 动态探测 MAGIC_DIR
+if [ -z "${MAGIC_DIR:-}" ]; then
+  for m in ".claude" ".qoder" ".vscode" ".add"; do
+    [ -d "${PROJECT_DIR:-$PWD}/$m" ] && { MAGIC_DIR="$m"; break; }
+  done
+  MAGIC_DIR="${MAGIC_DIR:-.add}"
+fi
+VOCABULARY_FILE="${PROJECT_DIR:-$PWD}/$MAGIC_DIR/vocabulary/add-governance-vocabulary.md"
+
+# 输出格式: 优先级::触发词正则::响应文本（:: 避免与触发词内的 | 冲突）
+load_triggers() {
+  [ ! -f "$VOCABULARY_FILE" ] && return 1
+  sed -n '/^## 类别 A: 文档类型/,/^## 类别 [G-Z]/p' "$VOCABULARY_FILE" \
+    | grep -E '^\| (P0|P1|P2) ' \
+    | while IFS='|' read -r _ prio raw_trigger action; do
+        prio=$(echo "$prio" | xargs)
+        trigger=$(echo "$raw_trigger" | sed 's/`//g;s/ *\/ */|/g;s/^ *//;s/ *$//')
+        action=$(echo "$action" | xargs)
+        [ -z "$trigger" ] && continue
+        echo "${prio}::${trigger}::${action}"
+      done || true
+}
+
+match_trigger() {
+  local prompt="$1"
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    local prio="${line%%::*}"
+    local rest="${line#*::}"
+    local regex="${rest%%::*}"
+    local action="${rest#*::}"
+    # 跳过开发关键词检测行（由 Layer 2/3 分流处理，特征：超长regex含"修bug"）
+    if echo "$regex" | grep -qE '修\.\?bug|fix\.\?bug' 2>/dev/null; then
+      continue
+    fi
+    if echo "$prompt" | grep -qiE "$regex" 2>/dev/null; then
+      echo "[ADD 触发] ${regex} → ${action}"
+    fi
+  done < <(load_triggers 2>/dev/null)
+}
+
+load_dev_keywords() {
+  load_triggers 2>/dev/null | while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    # 只取包含"开发|改功能"的开发关键词检测行
+    if echo "$line" | grep -q '开发|改功能' 2>/dev/null; then
+      local rest="${line#*::}"
+      local regex="${rest%%::*}"
+      echo "$regex"
+    fi
+  done || true
+}

package/templates/adapters/claude/hooks/notification.sh

@@ -22,7 +22,14 @@ state=$(detect_active_add 2>/dev/null || true)
 
 IFS='::' read -r plan _ _ _ _ <<< "$state"
 
-reviews_dir="${PROJECT_DIR}/.qoder/reviews"
+# 动态探测
+if [ -z "${MAGIC_DIR:-}" ]; then
+  for m in ".claude" ".qoder" ".vscode" ".add"; do
+    [ -d "${PROJECT_DIR:-$PWD}/$m" ] && { MAGIC_DIR="$m"; break; }
+  done
+  MAGIC_DIR="${MAGIC_DIR:-.claude}"
+fi
+reviews_dir="${PROJECT_DIR}/$MAGIC_DIR/reviews"
 if ls "$reviews_dir"/*.md >/dev/null 2>&1; then
   echo "[ADD Notification] Plan: ${plan} — 请检查 Review 文档: ${reviews_dir}"
 fi

package/templates/adapters/codex/hooks/doc-format-guard.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# doc-format-guard.sh — schema.json 驱动的 ADD 文档格式守卫
+set -euo pipefail
+
+input=$(cat)
+
+MAGIC_DIR=".codex"
+
+# DEBUG: dump stdin for investigation
+mkdir -p "$MAGIC_DIR/debug-dump"
+echo "=== $(date) ===" >> "$MAGIC_DIR/debug-dump/stdin.log"
+echo "file_path: $(echo "$input" | jq -r '.tool_input.file_path // "EMPTY"')" >> "$MAGIC_DIR/debug-dump/stdin.log"
+echo "has_file_content: $(echo "$input" | jq 'has("tool_input") and (.tool_input | has("file_content"))')" >> "$MAGIC_DIR/debug-dump/stdin.log"
+echo "has_replacements: $(echo "$input" | jq 'has("tool_input") and (.tool_input | has("replacements"))')" >> "$MAGIC_DIR/debug-dump/stdin.log"
+if echo "$input" | jq -e 'has("tool_input") and (.tool_input | has("file_content"))' > /dev/null 2>&1; then
+  echo "[file_content[500]]: $(echo "$input" | jq -r '.tool_input.file_content' | head -c 500)" >> "$MAGIC_DIR/debug-dump/stdin.log"
+fi
+if echo "$input" | jq -e 'has("tool_input") and (.tool_input | has("replacements"))' > /dev/null 2>&1; then
+  echo "[replacement_new_text[500]]: $(echo "$input" | jq -r '.tool_input.replacements[0].new_text' | head -c 500)" >> "$MAGIC_DIR/debug-dump/stdin.log"
+fi
+echo "top_keys: $(echo "$input" | jq -r 'keys | join(", ")')" >> "$MAGIC_DIR/debug-dump/stdin.log"
+echo "tool_input_keys: $(echo "$input" | jq -r '.tool_input | keys | join(", ") // "NO_TOOL_INPUT"')" >> "$MAGIC_DIR/debug-dump/stdin.log"
+echo "=== DONE ===" >> "$MAGIC_DIR/debug-dump/stdin.log"
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+# L17: 非文件工具事件（空 stdin）→ 不拦截（由 matcher 层过滤）
+[ -z "$file_path" ] && exit 0
+
+if ! echo "$file_path" | grep -qE '\.codex/(plans|specs)/'; then
+  exit 0
+fi
+
+CONTENT=$(echo "$input" | jq -r '
+  if .tool_input.file_content then .tool_input.file_content
+  elif .tool_input.content then .tool_input.content
+  elif .tool_input.replacements then .tool_input.replacements[0].new_text
+  else "" end')
+# L24: PostToolUse 不可阻断（仅反馈），PreToolUse exit 2 + ask 可拦截
+# L24: 文件在 .qoder/(plans|specs)/ 下但 Write 工具未传 content → 无法校验，阻断
+if [ -z "$CONTENT" ]; then
+  echo "⛔ 拒绝：Write 工具未传 file_content，无法校验手写文档格式" >&2
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Write 工具未传 file_content，无法校验手写文档。请用 SearchReplace 改写已有文件，或用 Write 工具重试。"}}'
+  exit 2
+fi
+
+PROJECT_DIR="$PWD"
+TEMPLATES_DIR="$PROJECT_DIR/$MAGIC_DIR/templates"
+
+# 通过 filename 匹配模板名
+TEMPLATE_NAME=""
+for tmpl in "$TEMPLATES_DIR"/*.md; do
+  base=$(basename "$tmpl")
+  if echo "$file_path" | grep -q "$base"; then
+    TEMPLATE_NAME="$base"
+    break
+  fi
+done
+
+# 退一步：根据文件内容特征猜测模板类型
+if [ -z "$TEMPLATE_NAME" ]; then
+  if echo "$CONTENT" | grep -q "## PLAN 元信息"; then
+    TEMPLATE_NAME="standard-plan-template.md"
+  elif echo "$CONTENT" | grep -q "## 一、Plan 概述"; then
+    TEMPLATE_NAME="simple-plan-template.md"
+  elif echo "$CONTENT" | grep -q "## 四、Handoff"; then
+    TEMPLATE_NAME="simple-plan-template.md"
+  elif echo "$CONTENT" | grep -q "## Review 元信息"; then
+    if echo "$CONTENT" | grep -q "运行时验证"; then
+      TEMPLATE_NAME="review-runtime-template.md"
+    elif echo "$CONTENT" | grep -q "跨仓库格式契约"; then
+      TEMPLATE_NAME="review-implementation-template.md"
+    else
+      TEMPLATE_NAME="review-template.md"
+    fi
+  elif echo "$CONTENT" | grep -q "## Why"; then
+    TEMPLATE_NAME="spec-template.md"
+  elif echo "$CONTENT" | grep -q "## Preconditions"; then
+    TEMPLATE_NAME="tasks-template.md"
+  elif echo "$CONTENT" | grep -q "审计链（证据→devlog→checklist）"; then
+    TEMPLATE_NAME="checklist-template.md"
+  else
+    case "$file_path" in
+      *handoff*)
+        # ★ 按内容特征区分单/多轮 handoff，不依赖文件名
+        if echo "$CONTENT" | grep -qF "## 全局元信息"; then
+          TEMPLATE_NAME="handoff-multi-round-template.md"
+        elif echo "$CONTENT" | grep -qF "## 1. 交接前状态"; then
+          TEMPLATE_NAME="handoff-single-round-template.md"
+        else
+          echo "⛔ handoff 文件内容无法识别模板类型（缺 '## 全局元信息' 或 '## 1. 交接前状态'），拒绝写入" >&2
+          echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"handoff 内容不符合 single/multi 模板规范"}}'
+          exit 2
+        fi
+        ;;
+      *plan*)            TEMPLATE_NAME="standard-plan-template.md" ;;
+      *add-route*heavy*) TEMPLATE_NAME="add-route-template-heavyweight.md" ;;
+      *add-route*)       TEMPLATE_NAME="add-route-template.md" ;;
+      *tasks*)           TEMPLATE_NAME="tasks-template.md" ;;
+      *spec*)            TEMPLATE_NAME="spec-template.md" ;;
+      *checklist*)       TEMPLATE_NAME="checklist-template.md" ;;
+      *report*runtime*)  TEMPLATE_NAME="runtime-report-template.md" ;;
+      *report*)          TEMPLATE_NAME="report-template.md" ;;
+      *fix-verif*)       TEMPLATE_NAME="fix-verification-template.md" ;;
+      *) 
+        # 增量修订识别：包含 ~~删除线~~ / → 新增标记 / [修订日期] 任意一个 → 视为增量更新，放行
+        if echo "$CONTENT" | grep -qE '~~.+~~|→|\[[0-9]{4}-[0-9]{2}-[0-9]{2}\s+修订'; then
+          echo "[doc-format-guard] 检测到增量修订格式，跳过完整章节校验" >&2
+          exit 0
+        fi
+        echo "⛔ 拒绝：无法识别文档类型 (file_path: $file_path)，缺少模板匹配规则" >&2
+        echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"无法识别 ADD 文档类型，请联系管理员更新 doc-format-guard.sh"}}'
+        exit 2
+        ;;
+    esac
+  fi
+fi
+
+SCHEMA_FILE="$TEMPLATES_DIR/${TEMPLATE_NAME%.md}.schema.json"
+# L84: schema 文件不存在 → 无校验规则，阻断（不允许无规则放行）
+if [ ! -f "$SCHEMA_FILE" ]; then
+  echo "⛔ 阻断：模板 ${TEMPLATE_NAME} 缺少对应的 .schema.json 校验规则" >&2
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"缺少 .schema.json 校验规则文件，禁止无规则放行"}}'
+  exit 2
+fi
+
+# SearchReplace 只传 patch（replacements[].new_text），不传全文件 → 跳过章节校验
+IS_SEARCH_REPLACE=$(echo "$input" | jq -r '.tool_input.replacements | length > 0 // false')
+
+ISSUES=""
+
+# ── 章节校验 ──
+# 使用项目目录下的临时文件，避免 /tmp 在沙箱中不可写导致静默跳过
+TMPFILE="$PROJECT_DIR/$MAGIC_DIR/.doc-guard-issues.tmp"
+: > "$TMPFILE"
+trap "rm -f $TMPFILE" EXIT
+# SearchReplace 只传 patch → 跳过章节/子章节校验（无法从 patch 推断完整文档结构）
+if [ "$IS_SEARCH_REPLACE" != "true" ]; then
+  jq -r '.sections[] | select(.required == true) | .heading' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r heading; do
+    if ! echo "$CONTENT" | grep -qF "$heading"; then
+      echo "  缺章节: $heading"
+    fi
+  done > "$TMPFILE"
+
+  # 子章节
+  jq -r '.sections[].subsections[]?.heading' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r sub; do
+    if ! echo "$CONTENT" | grep -qF "$sub"; then
+      echo "  缺子章节: $sub"
+    fi
+  done >> "$TMPFILE"
+fi
+
+# ── 占位符校验 ──
+jq -r '.placeholders[]?' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r ph; do
+  if echo "$CONTENT" | grep -qF "$ph"; then
+    echo "  未替换占位符: $ph"
+  fi
+done >> "$TMPFILE"
+
+# ── 禁止词校验 ──
+jq -r '.forbidden_terms[]?' "$SCHEMA_FILE" 2>/dev/null | while IFS= read -r term; do
+  if echo "$CONTENT" | grep -qw "$term"; then
+    echo "  禁止词: $term"
+  fi
+done >> "$TMPFILE"
+
+ISSUES=$(cat "$TMPFILE" 2>/dev/null)
+
+# ── 算法化规则校验（ADD 范式约束下沉为代码）──
+ALGO_ISSUES=""
+
+# 规则1: 精简版 Plan 反作弊
+if echo "$TEMPLATE_NAME" | grep -q 'simple-plan'; then
+  # 1a. 文件数 ≤ 3
+  file_count=$(echo "$CONTENT" | grep -cP '^\|\s*`[^`]+`' 2>/dev/null || echo "0")
+  if [ "$file_count" -gt 3 ] 2>/dev/null; then
+    ALGO_ISSUES="${ALGO_ISSUES}  ❌ 精简版反作弊: 涉及 ${file_count} 个文件（超过 3 个限制），应改用 standard-plan-template.md\n"
+  fi
+  # 1b. HITL 表不能写 "等 N 个文件"
+  if echo "$CONTENT" | grep -qP '等\s*\d*\s*个文件|等\s*若干'; then
+    ALGO_ISSUES="${ALGO_ISSUES}  ❌ 精简版反作弊: HITL 表文件清单使用模糊描述（'等 N 个文件'），必须列出实际完整路径\n"
+  fi
+  # 1c. HITL 方案/设计决策不能写 "等若干决策"
+  if echo "$CONTENT" | grep -qP '等\s*若干\s*(决策|方案|设计)'; then
+    ALGO_ISSUES="${ALGO_ISSUES}  ❌ 精简版反作弊: HITL 表方案/设计决策使用模糊描述（'等若干决策'），必须逐条列出\n"
+  fi
+  # 1d. 不能包含架构设计章节（精简版无架构设计）
+  if echo "$CONTENT" | grep -q '## 三、架构设计'; then
+    ALGO_ISSUES="${ALGO_ISSUES}  ❌ 精简版反作弊: 包含 '## 三、架构设计' 章节，精简版不应有架构设计——应改用 standard-plan-template.md\n"
+  fi
+fi
+
+# 规则2: HITL 表非空校验（所有 Plan + Review 模板）
+if echo "$TEMPLATE_NAME" | grep -qE 'plan|review'; then
+  if echo "$CONTENT" | grep -q '## HITL'; then
+    # HITL 表至少要有 1 行非占位符内容（不包含 { } 占位符）
+    hitl_rows=$(echo "$CONTENT" | sed -n '/## HITL/,/^## /p' | grep -cP '^\|\s*[^|{]*\s*\|' 2>/dev/null || echo "0")
+    # rows 包含表头行和分隔行，实际数据行 = rows - 2
+    hitl_data=$((hitl_rows - 2))
+    if [ "$hitl_data" -lt 1 ] 2>/dev/null; then
+      ALGO_ISSUES="${ALGO_ISSUES}  ⚠️  HITL 表为空——必须填写至少 1 行实际内容后再提交审核\n"
+    fi
+  fi
+fi
+
+# 规则3: 精简版 Plan 禁止同时存在独立 handoff 文件
+if echo "$TEMPLATE_NAME" | grep -q 'simple-plan'; then
+  plan_base=$(basename "$file_path" | sed 's/-plan-v.*//')
+  plan_dir=$(dirname "$file_path")
+  handoff_pattern="${plan_dir}/${plan_base}-handoff"
+  if find "$plan_dir" -name "${plan_base}-handoff*.md" 2>/dev/null | grep -q .; then
+    ALGO_ISSUES="${ALGO_ISSUES}  ❌ 精简版 Handoff 冲突: 检测到独立 handoff 文件（${plan_base}-handoff*.md）。精简版 Plan 的 Handoff 已融合在 §四，不应生成独立文件。请删除独立 handoff 文件或改用 standard-plan-template.md\n"
+  fi
+fi
+
+if [ -n "$ALGO_ISSUES" ]; then
+  echo "⛔ 算法化规则校验不通过:" >&2
+  echo -e "$ALGO_ISSUES" >&2
+  # 合并到 ISSUES 中一起阻断
+  echo -e "$ALGO_ISSUES" >> "$TMPFILE"
+fi
+
+ISSUES=$(cat "$TMPFILE" 2>/dev/null)
+
+# ── 阻断或放行 ──
+if [ -n "$ISSUES" ]; then
+  echo "⛔ $TEMPLATE_NAME 校验不通过:
+$ISSUES" >&2
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"文档格式校验不通过，请对照模板修正\"}}"
+  exit 2
+fi
+
+# ── 自动更新 index.md ──
+if echo "$file_path" | grep -q '\.codex/plans/'; then
+  if [ -x "$PROJECT_DIR/scripts/gen-plan-index.sh" ]; then
+    "$PROJECT_DIR/scripts/gen-plan-index.sh" 2>/dev/null || true
+  fi
+fi
+
+exit 0