add-coder 0.2.1 → 0.2.3

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

@@ -2,12 +2,25 @@
 # state-detect.sh — ADD 活跃流程检测 + dev action 追踪
 # 共享库
 
-PROJECT_DIR="${QODER_PROJECT_DIR:-${QODERCN_PROJECT_DIR:-$PWD}}"
-QODER_DIR="$PROJECT_DIR/.qoder"
-PLANS_DIR="$QODER_DIR/plans"
+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/qoder_dev_$(echo "$PROJECT_DIR" | md5sum 2>/dev/null | cut -c1-8 || echo "default")"
+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" 或 ""

package/templates/adapters/qoder/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/qoder/hooks/lib/vocabulary.sh

@@ -2,7 +2,14 @@
 # vocabulary.sh — 从 vocabulary markdown 表格加载触发词
 # 单一数据源: .qoder/vocabulary/add-governance-vocabulary.md §类别 A-F 表格
 
-VOCABULARY_FILE="${PROJECT_DIR:-$PWD}/.qoder/vocabulary/add-governance-vocabulary.md"
+# 动态探测 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() {

package/templates/adapters/qoder/hooks/pre-compact.sh

@@ -8,7 +8,7 @@ export CURRENT_MAGIC=$(basename "$(dirname "$HOOK_DIR")")
 COMMON_LIB="$HOOK_DIR/lib/common.sh"
 [ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
 
-export PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+export PROJECT_DIR="${QODER_PROJECT_DIR:-${QODERCN_PROJECT_DIR:-$PWD}}"
 
 # ── ① 获取 ADD 状态并保存到标记文件 ──
 if type detect_active_add >/dev/null 2>&1; then

package/templates/adapters/trae/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=".trae"
+
+# 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 '\.trae/(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 '\.trae/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

package/templates/adapters/trae/hooks/lib/common.sh

@@ -0,0 +1,261 @@
+#!/bin/bash
+###
+ # @Author       : xiaomingming wujixmm@gmail.com
+ # @Date         : 2026-07-17 13:14:46
+ # @LastEditors  : xiaomingming wujixmm@gmail.com
+ # @LastEditTime : 2026-07-17 13:21:36
+ # @FilePath     : /add-coder/templates/core/hooks/lib/common.sh
+ # @Description  : ADD Hook 共享库 — 四端通用函数
+### 
+# ADD Hook 共享库 — 四端通用函数
+# 被 Claude/Qoder/VS Code/Trae adapter 的 hook 脚本 source 引用
+# 路径: templates/core/hooks/lib/common.sh
+
+# 退出码常量,目前适配的ide都一样
+export EXIT_PASS=0   # 放行
+export EXIT_BLOCK=2  # 阻断
+
+# ── 输入解析 ──
+
+# 从 stdin 解析 JSON 输入（hook 事件通过 stdin 传入 JSON）
+parse_input() {
+  if [ -t 0 ]; then
+    echo "{}"
+  else
+    cat
+  fi
+}
+
+# 从 JSON 中提取字段值（简单实现，不依赖 jq）
+# 用法: json_get "$json" "field_name"
+json_get() {
+  echo "$1" | grep -o "\"$2\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/'
+}
+
+# ── ADD 活跃 Plan 检测（裁决定逻辑，SKILL §0.7.1） ──
+#
+# 活跃判定标准：
+#   1. magicDir 优先级: 由 Hook 脚本自身的路径推断（.claude/hooks/xxx.sh → .claude）→ .add → stderr 提示全局搜索
+#   2. 索引优先: 先读 plans/index.md 匹配 → 无匹配才 glob *-handoff*.md
+#   3. 活跃定义: add-route 中存在 [ ] 未勾选项 = 活跃；全部 [x] = 已收敛
+#   4. 多 Plan 冲突: 取 add-route 最近 mtime
+#   5. 无 add-route: Plan 初始态，视为活跃
+#
+# 前置条件: 调用方需设置 PROJECT_DIR 环境变量（项目根目录）
+# 返回: "plan_keyword::step_n/total::round_n/total::handoff_path::add_route_path" 或 ""
+
+detect_active_add() {
+  local plans_dir=""
+
+  # 1. magicDir 回退: 当前 IDE（CURRENT_MAGIC）→ 目录检测 → .add → 提示全局搜索
+  local magic_dirs=()
+  if [ -n "${CURRENT_MAGIC:-}" ]; then
+    magic_dirs+=("$CURRENT_MAGIC")
+  else
+    # 兜底: 检测 PROJECT_DIR 下哪个 magicDir 存在
+    for m in ".claude" ".qoder" ".vscode" ".trae"; do
+      [ -d "${PROJECT_DIR:-$PWD}/$m" ] && { magic_dirs+=("$m"); break; }
+    done
+  fi
+  magic_dirs+=(".add")
+
+  for magic in "${magic_dirs[@]}"; do
+    if [ -d "${PROJECT_DIR:-$PWD}/$magic/plans" ]; then
+      plans_dir="${PROJECT_DIR:-$PWD}/$magic/plans"
+      break
+    fi
+  done
+
+  if [ -z "$plans_dir" ]; then
+    echo "[ADD detect] 未在当前 IDE magicDir 和 .add 中找到 plans 目录。是否需要全局搜索所有 magicDir？" >&2
+    return 1
+  fi
+
+  local handoff=""
+  local add_route=""
+
+  # 2. 索引优先: 先读 index.md
+  if [ -f "$plans_dir/index.md" ]; then
+    # 从 index.md 表格提取最近一个 handoff 相对路径
+    # 表格格式: | YYYY-MM/DD/path-to-handoff.md | ...
+    handoff=$(grep -oE '[0-9]{4}-[0-9]{2}/[0-9]{2}/[^|]*handoff[^|]*\.md' "$plans_dir/index.md" 2>/dev/null | head -1 | xargs)
+    if [ -n "$handoff" ] && [ -f "$plans_dir/$handoff" ]; then
+      handoff="$plans_dir/$handoff"
+    else
+      handoff=""
+    fi
+  fi
+
+  # 3. 退路: glob handoff 文件（mtime 7 天内）
+  if [ -z "$handoff" ]; then
+    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)
+  fi
+  [ -z "$handoff" ] && return 1
+
+  # 提取 plan keyword
+  local plan_kw=$(basename "$handoff" | sed 's/-handoff.*//')
+
+  # 查找 add-route
+  local handoff_dir=$(dirname "$handoff")
+  add_route=$(find "$handoff_dir" -name "*add-route*.md" -type f 2>/dev/null | head -1)
+  [ -z "$add_route" ] && add_route=$(find "$plans_dir" -name "*add-route*.md" -type f 2>/dev/null | head -1)
+
+  # 4. 活跃判定: 读 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}"
+    # 全部 [x] → 已收敛（但 handoff 还存在 → 可能是遗留，仍返回但标记）
+  else
+    # 无 add-route → Plan 初始态，视为活跃
+    step_info="init"
+  fi
+
+  # 5. 轮次统计（从 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 追踪 ──
+
+# dev action 标记文件（项目级，PreToolUse 写入，Stop 读取）
+DEV_FLAG="/tmp/add_dev_$(echo "${PROJECT_DIR:-$PWD}" | md5sum 2>/dev/null | cut -c1-8 || echo "default")"
+
+mark_dev_action() {
+  touch "$DEV_FLAG" 2>/dev/null || true
+}
+
+has_dev_action() {
+  [ -f "$DEV_FLAG" ]
+}
+
+clear_dev_action() {
+  rm -f "$DEV_FLAG" 2>/dev/null || true
+}
+
+# ── 验收完整度检查 ──
+
+# 检查 handoff + add-route 的验收完整度
+# 用法: check_add_completeness "$handoff_path" "$add_route_path"
+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"
+}
+
+# ── 验收幂等保护 ──
+
+# 检查是否已验收（幂等保护）
+# 用法: is_already_accepted "$add_route_path" "$handoff_path"
+# 返回 0 = 已验收，1 = 未验收
+is_already_accepted() {
+  local add_route="$1" handoff="$2"
+  # add-route Step 8 是否已 [x]
+  if [ -f "$add_route" ]; then
+    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
+}
+
+# ── Stop 四象限分流 few-shot 上下文（卡位 #7） ──
+# 用法: build_stop_context "$quadrant" "$info"
+build_stop_context() {
+  local quadrant="$1" info="$2"
+  case "$quadrant" in
+    "no_add_no_dev")
+      echo "[ADD Stop] 无活跃 Plan，无代码改动。正常结束。"
+      ;;
+    "no_add_has_dev")
+      cat <<'EOF'
+[ADD Stop] ⚠️ 检测到代码修改但无活跃 ADD Plan。
+
+Plan 不是"文档开销"——它是代码治理的基础设施。跳过 Plan 的后果:
+  · 没有 add-route → 每次改动无法追溯到具体 Task
+  · 没有 tasks.md → 后续 AI Session 不知道改了哪些文件
+  · 没有 handoff → 交接时上下文全丢，只能靠 git log 猜
+
+你必须立即补救，二选一:
+
+方案 A — 补 ADD 流程（招安）:
+  Step 0: 读 .qoder/templates/plan-template.md → 生成 Plan
+          生成 add-route → check_dps ≥ 85
+  Step 1: 扩展 AgentAuditPhase（如需要）
+  Step 2: 确认 agentAudit() 通道
+  Step 3: 将已写代码关联到 tasks.md
+  完成后可正常停止。
+
+方案 B — 补不上则回滚:
+  如果改动太复杂无法追溯生成 Plan，则:
+  ① git diff 确认改动范围
+  ② git checkout -- <改动的文件> 撤回
+  ③ 告知用户 "以下改动已回滚，请先走 ADD 流程再重新实施: <文件列表>"
+
+无论选 A 还是 B，完成后告诉用户下次执行 session-init 恢复上下文。
+EOF
+      ;;
+    "has_add_no_dev")
+      echo "[ADD Stop] ADD 流程进行中 (${info})，本次无代码改动。下次继续时执行 session-init 恢复上下文。"
+      ;;
+    "has_add_dev_unclosed")
+      cat <<EOF
+[ADD Stop] ⚠️ 代码已完成但验收未闭环:
+${info}
+
+请依次执行（不要等下次会话）:
+  ① Write devlog → handoff 同目录 devlog-{plan}-v{n}.md
+     格式: # Devlog: {plan}\n 日期 / Plan / 轮次 / 本轮改了什么 / 验收结果 / 遗留项 / 架构回看
+  ② Edit handoff → 更新 §验证标准 全部 [x] + 补充审计 ID
+  ③ Read docs/ → 回看架构文档确认一致性
+  ④ Edit add-route → 勾选对应 Step [x]
+
+以上全部完成后 Agent 才能停止。
+EOF
+      ;;
+  esac
+}
+
+# ── PreToolUse 写入前置守卫上下文（卡位 #4） ──
+build_pretool_context() {
+  local plan="$1" round="$2"
+  cat <<EOF
+[ADD PreToolUse] 当前 Plan: ${plan}，轮次: ${round}。
+本次写入应属于 ADD Step 3 代码实现阶段。
+完成后执行 record_dev_operation 记录审计。
+EOF
+}