add-coder 0.2.2 → 0.2.4

package/templates/core/hooks/doc-format-guard.sh

@@ -4,20 +4,31 @@ set -euo pipefail
 
 input=$(cat)
 
+# 动态探测 MAGIC_DIR（兼容多 adapter）
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+PARENT_DIR="$(dirname "$HOOK_DIR")"
+MAGIC_DIR="$(basename "$PARENT_DIR")"
+
 # DEBUG: dump stdin for investigation
-mkdir -p .qoder/debug-dump
-echo "=== $(date) ===" >> .qoder/debug-dump/stdin.log
-echo "file_path: $(echo "$input" | jq -r '.tool_input.file_path // "EMPTY"')" >> .qoder/debug-dump/stdin.log
-echo "has_file_content: $(echo "$input" | jq 'has("tool_input") and (.tool_input | has("file_content"))')" >> .qoder/debug-dump/stdin.log
-echo "has_replacements: $(echo "$input" | jq 'has("tool_input") and (.tool_input | has("replacements"))')" >> .qoder/debug-dump/stdin.log
-echo "top_keys: $(echo "$input" | jq -r 'keys | join(", ")')" >> .qoder/debug-dump/stdin.log
-echo "tool_input_keys: $(echo "$input" | jq -r '.tool_input | keys | join(", ") // "NO_TOOL_INPUT"')" >> .qoder/debug-dump/stdin.log
-echo "=== DONE ===" >> .qoder/debug-dump/stdin.log
+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 '\.qoder/(plans|specs)/'; then
+if ! echo "$file_path" | grep -qE '$MAGIC_DIR/(plans|specs)/'; then
   exit 0
 fi
 
@@ -34,8 +45,8 @@ if [ -z "$CONTENT" ]; then
   exit 2
 fi
 
-PROJECT_DIR="${QODER_PROJECT_DIR:-${QODERCN_PROJECT_DIR:-$PWD}}"
-TEMPLATES_DIR="$PROJECT_DIR/.qoder/templates"
+PROJECT_DIR="$PWD"
+TEMPLATES_DIR="$PROJECT_DIR/$MAGIC_DIR/templates"
 
 # 通过 filename 匹配模板名
 TEMPLATE_NAME=""
@@ -49,10 +60,12 @@ done
 
 # 退一步：根据文件内容特征猜测模板类型
 if [ -z "$TEMPLATE_NAME" ]; then
-  if echo "$CONTENT" | grep -q "## 四、Handoff"; then
-    TEMPLATE_NAME="simple-standard-plan-template.md"
-  elif echo "$CONTENT" | grep -q "## PLAN 元信息"; 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"
@@ -119,7 +132,7 @@ ISSUES=""
 
 # ── 章节校验 ──
 # 使用项目目录下的临时文件，避免 /tmp 在沙箱中不可写导致静默跳过
-TMPFILE="$PROJECT_DIR/.qoder/.doc-guard-issues.tmp"
+TMPFILE="$PROJECT_DIR/$MAGIC_DIR/.doc-guard-issues.tmp"
 : > "$TMPFILE"
 trap "rm -f $TMPFILE" EXIT
 # SearchReplace 只传 patch → 跳过章节/子章节校验（无法从 patch 推断完整文档结构）
@@ -154,6 +167,62 @@ 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 校验不通过:
@@ -163,7 +232,7 @@ $ISSUES" >&2
 fi
 
 # ── 自动更新 index.md ──
-if echo "$file_path" | grep -q '\.qoder/plans/'; then
+if echo "$file_path" | grep -q '$MAGIC_DIR/plans/'; then
   if [ -x "$PROJECT_DIR/scripts/gen-plan-index.sh" ]; then
     "$PROJECT_DIR/scripts/gen-plan-index.sh" 2>/dev/null || true
   fi

package/templates/core/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="$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/core/hooks/lib/vocabulary.sh

@@ -2,7 +2,14 @@
 # vocabulary.sh — 从 vocabulary markdown 表格加载触发词
 # 单一数据源: .qoder/vocabulary/add-governance-vocabulary.md §类别 A-F 表格
 
-VOCABULARY_FILE="$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/core/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:-.add}"
+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/core/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="$PWD"
 
 # ── ① 获取 ADD 状态并保存到标记文件 ──
 if type detect_active_add >/dev/null 2>&1; then

package/templates/core/hooks/pre-tool-use.sh

@@ -11,7 +11,7 @@ input=$(cat)
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 PARENT="$(dirname "$HOOK_DIR")"
 MAGIC_DIR="$(basename "$PARENT")"
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${QODER_PROJECT_DIR:-${QODERCN_PROJECT_DIR:-$(dirname "$PARENT")}}}"
+PROJECT_DIR="$PWD"
 
 # ── §A 辅助函数: 阻断日志 ──
 _log_block() {

package/templates/core/rules/project_rules.md

@@ -26,6 +26,7 @@
 | P2 | ADD-13 DPS 上游文档质量闸门 | Plan 概括度 → Review 注意力稀释 → Specs 遗漏 → 实现偏差。`check_dps`（DPS ≥ 85）在 Step 0 末尾量化阻断 | ✅ 已实现 | 2026-06-11 引入 |
 | P2 | ADD-14 RAHS 下游执行健康度闸门 | 范围保真度 + 类型安全 + 审计完整度 + Spec 合规 + 阶段对称性。`check_rahs`（RAHS ≥ 90）在 Step 4/8 量化阻断 | ✅ 已实现 | 2026-06-11 引入 |
 | P2 | ADD-15 add-route 闭环自检 | Step 3 代码完成后必须调用 `check_add_route_completeness` 扫描 add-route Step 完成度，防止执行遗漏。返回 complete 方可进入 Step 3.5 | ✅ 已实现 | 2026-06-11 引入 |
+| P2 | ADD-17 HITL 磋商临时文件机制 | doc-format-guard 要求 Plan/Review 文件包含完整章节才放行，HITL 第一步只写总览表会被 guard 阻断。用 `{name}.temporary.md` 做磋商（不受 guard 检查），人类拍板后再写正式文件并删除 temporary.md | ✅ 已实现 | 2026-07-23 引入 |
 
 
 ### P0 规则：不可跳过
@@ -66,6 +67,7 @@ AI 助手必须先恢复到基线、找到对应的 SKILL 文件并按步骤执
 | ADD-14 | `add-paradigm` Step 4 末端 + Step 8 收敛 + MCP `check_rahs` | Step 4 合规检查 / Step 8 收敛判定 |
 | ADD-15 | `add-paradigm` Step 3.6 + MCP `check_add_route_completeness` | Step 3 代码完成后自检 |
 | ADD-16 | `add-paradigm` Step 9 | runtime-fix plan 收敛后，关闭 gateway.md 运行时发现 |
+| ADD-17 | `add-paradigm` 独立能力：生成 Plan / Step 0 | Plan/Review HITL 磋商时（写入 temporary.md 绕过 guard，拍板后写正式文件） |
 
 ---
 
@@ -148,22 +150,28 @@ ADD 是**开发阶段**的编程范式，不是运行时范式。
 | 架构文档 | `docs/*/knowledge/01-架构/` 或 `02-架构/` | 架构说明书、系统设计、模块定义 |
 | 规范文档 | `docs/*/knowledge/02-规范/` 或 `03-规范/` | 开发规范、AI 核心规范、状态机规范 |
 
-**此外，ADD 工作流的核心产物由 `{{magicDir}}/templates/` 下的 11 个模板定义**，这些模板不是参考资料，而是每次变更必须产出的文档骨架。分析变更影响范围时，必须同步确认需要创建/更新哪些模板产物：
+**此外，ADD 工作流的核心产物由 `{{magicDir}}/templates/` 下的 13 个模板定义**，这些模板不是参考资料，而是每次变更必须产出的文档骨架。分析变更影响范围时，必须同步确认需要创建/更新哪些模板产物：
 
 | 模板 | 用途 | 对应阶段 |
-|------|------|---------|
-| `plan-template.md` | 需求方案：元信息 + 背景目标 + 方案选型 + 架构设计 + 实施步骤 + 验收标准 + ADD-7审计策略 | 需求理解 |
+|------|------|------|
+| `simple-plan-template.md` | 精简版 Plan：≤3 文件单一改动，Tasks+Handoff 融合在 Plan 体内，无需独立 spec/handoff | 简单任务 |
+| `standard-plan-template.md` | 标准版 Plan：多模块/跨系统/含架构设计，需独立 spec/tasks/checklist/handoff | 复杂任务 |
 | `spec-template.md` | 功能规格：Why / What Changes / Impact / WHEN-THEN Requirements | Step 0~1 |
 | `tasks-template.md` | 任务拆分：Phase → Task → SubTask 层级 | Step 1 |
 | `checklist-template.md` | 验收清单：业务检查项 + ADD 规则合规检查 + 跨项目联调检查 [T]/[R] | Step 3.5 / Step 8 |
-| `review-template.md` | 方案审查（ADD-9）：元信息 + 问题复现 + 方案对比 + 决策结论 + 影响评估 | Plan 后 |
-| `review-implementation-template.md` | 实现审查（ADD-10）：格式契约 + 框架版本 + 数据模型 + 环境变量 + API 选择 + E2E curl | Code 后 |
+| `review-template.md` | 方案审查（ADD-9）：元信息 + **HITL 发现总览** + 问题复现 + 方案对比 + 决策结论 + 影响评估 | Plan 后 |
+| `review-implementation-template.md` | 实现审查（ADD-10）：元信息 + **HITL 发现总览** + 格式契约 + 框架版本 + 数据模型 + 环境变量 + API 选择 + E2E curl | Code 后 |
 | `review-runtime-template.md` | 运行时纠偏（ADD-11）：发现列表 + 根因分析 + 流程改进项 + 回流确认 | Deploy 后 |
 | `handoff-template.md` | 交接总览索引（指向单轮/多轮） | Step 8 后 |
 | `handoff-single-round-template.md` | 单轮交接：9 章节（含恢复上下文审计查询） | 单轮变更完成后 |
 | `handoff-multi-round-template.md` | 多轮交接：全局拓扑 + 每轮 13 子章节 + 收敛规则 + 启动模板 | 多轮原子事务完成后 |
 
-> **AI 首次学习 ADD 范式时，必须读取上述全部 11 个模板文件。遗漏模板 = 遗漏范式全貌。**
+> **AI 首次学习 ADD 范式时，必须读取上述全部 13 个模板文件。遗漏模板 = 遗漏范式全貌。**
+>
+> **精简版 Plan 特殊规则**：
+> - **Handoff 融合**：使用 `simple-plan-template.md` 时，Handoff 信息直接嵌入 Plan 的 §四，**不产生**独立的 `-handoff-v1.md` 文件
+> - **反作弊**：以下三条不满足任一条，必须改用 `standard-plan-template.md`：① 涉及文件 ≤ 3 个且全部在本模块内；② 无新增模块/子系统/外部依赖；③ 无需独立 spec 文档
+> - **HITL 强制**：精简版 Plan 的 HITL 表必须列出实际完整文件路径（禁止"等 N 个文件"）和所有设计决策（禁止"等若干决策"）
 ### 审计要求
 
 每次文档变更必须记录到 AuditLog（通过 `record_dev_operation` 工具），`targetType` 为 `"DOC"`，`action` 为 `"DOC_UPDATED"` 或 `"DOC_CREATED"`，`targetId` 为文档文件路径。
@@ -753,6 +761,34 @@ ADD-0.1 要求"文档先行"（先改文档再改代码）。ADD-16 是对 ADD-0
 
 ---
 
+## ADD-17：HITL 磋商临时文件机制
+
+**Plan 和 Review 的 HITL 磋商必须在写入正式文件之前完成，但 doc-format-guard 要求 `.qoder/plans/` 和 `.qoder/reviews/` 下的文件包含完整章节才放行。HITL 第一步只写总览表、不写正文——会被 guard 阻断。**
+
+### 流程
+
+```
+① AI 写 {name}.temporary.md（只含 HITL 总览表，放项目根目录，不受 guard 检查）
+② 人类审阅 HITL 表 → 逐行拍板（同意/调整）
+③ AI 根据确认后的 HITL 表生成完整 Plan/Review → 写入正式路径（guard 放行）
+④ 删除 temporary.md
+```
+
+### 适用范围
+
+| 文档类型 | temporary 磋商 | 正式写入路径 |
+|---------|:---:|------|
+| Plan（标准版/精简版） | ✅ 需要 | `.qoder/plans/{YYYY-MM}/{DD}/` |
+| Review（方案/实现） | ✅ 需要 | `.qoder/reviews/` |
+| Spec / Tasks / Checklist | ❌ 不需要 | 直接写入 `.qoder/specs/` |
+| Handoff | ❌ 不需要 | 直接写入 `.qoder/plans/` |
+
+### 与 ADD-0.1 的关系
+
+ADD-0.1 要求"文档先行"——HITL 磋商本身就是文档先行的一种形式（先对齐方向再产出文档）。temporary.md 机制确保 HITL 的"先拍板再展开"哲学不因 guard 的"完整章节校验"而被破坏。
+
+---
+
 ---
 
 ## 项目技术约束

package/templates/core/skills/add-paradigm/SKILL.md

@@ -46,18 +46,32 @@ description: "Audit-Driven Development paradigm workflow. Invoke when starting a
 >
 > **Plan 是后续 ADD 工作流的输入。** 生成 plan 后如需执行，才启动下方 Step 0。
 
-1. **读取模板**：读 `plan-template.md`，禁止凭记忆
-2. **命名规范**：`{项目名}-{功能名}-plan-v1.md` → `{{magicDir}}/plans/{YYYY-MM}/{DD}/`（按当天日期创建子目录）
-3. **必含章节**：
-   - 元信息（名称/时间/关联文档/ADD-7审计策略表）
+1. **模板选择**：根据任务复杂度选模板
+   - **精简版** `simple-plan-template.md`：≤3 文件、无新模块/架构、无外部 API 契约变更。Tasks 合并在 Plan 体内，无需独立 spec 文件。
+   - **标准版** `standard-plan-template.md`：多模块、跨系统集成、含架构选型或数据模型设计。
+2. **读取模板**：读选定的模板文件，禁止凭记忆
+3. **命名规范**：`{项目名}-{功能名}-plan-v1.md` → `{{magicDir}}/plans/{YYYY-MM}/{DD}/`（按当天日期创建子目录）
+4. **HITL 总览（先写 temporary.md）**：doc-format-guard 要求写入 `.qoder/plans/` 的文件必须包含完整章节，但 HITL 第一步只写总览表不写正文。因此先在项目根目录写 `{plan-name}.temporary.md`（只含 HITL 表，不受 guard 检查），人类拍板后再写正式 Plan 文件并删除 temporary.md。
+5. **HITL 确认后展开**：人类拍板后，再填写以下正文章节。
+6. **必含章节（标准版）**：
+   - PLAN 元信息（名称/时间/关联文档/ADD-7审计策略表）
+   - HITL 计划总览（人类拍板入口）
    - 一、背景与目标
    - 二、方案选型
    - 三、架构设计
-   - 四、实施步骤 + 依赖图
+   - 四、实施 Task + 依赖图
    - 五、验收标准
-   - 六、关联文档（指向 review/handoff/spec 的占位链接）
-4. **文档链路**：plan 作为枢纽节点，必须包含与后续 review/handoff 的双向链接占位
-5. **记录审计**：plan 生成后调用 `record_dev_operation`（targetType: "PLAN"）
+   - 六、关联文档
+6. **必含章节（精简版）**：
+   - HITL 计划总览（人类拍板入口）
+   - 一、Plan 概述
+   - 二、变更范围
+   - 三、Tasks（合并在 Plan 中）
+   - 四、Handoff
+   - 五、验收标准
+   - 六、关联
+7. **文档链路**：plan 作为枢纽节点，必须包含与后续 review/handoff 的双向链接占位
+8. **记录审计**：plan 生成后调用 `record_dev_operation`（targetType: "PLAN"）
 
 ---
 
@@ -90,15 +104,16 @@ description: "Audit-Driven Development paradigm workflow. Invoke when starting a
 |------|------|---------|
 | `prd-standard-template.md` | 产品/系统需求文档（新建）：背景目标 + 用户场景 + 功能需求 + 非功能需求 + 验收标准 | 需求定义 |
 | `prd-incremental-template.md` | 产品/系统需求文档（增量）：在已有 PRD 基础上追加/修改/删除 | 需求变更 |
-| `plan-template.md` | 需求方案：元信息 + 背景目标 + 方案选型 + 架构设计 + 实施步骤 + 验收标准 + ADD-7审计策略 | 需求理解 |
+| `simple-plan-template.md` | 精简版 Plan：≤3 文件单一改动，Tasks+Handoff 融合在 Plan 体内，无需独立 spec/handoff 文件 | 简单任务 |
+| `standard-plan-template.md` | 标准版 Plan：多模块/跨系统/含架构设计，需独立 spec/tasks/checklist | 复杂任务 |
 | `add-route-template.md` | Plan→ADD 十阶段执行映射：Step 0-9 具体动作 + Task 映射表 + 审计阶段清单 + 依赖拓扑 | Step 0 |
 | `spec-template.md` | 功能规格：Why / What Changes / Impact / WHEN-THEN Requirements | Step 0~1 |
 | `tasks-template.md` | 任务拆分：Phase → Task → SubTask 层级 | Step 1 |
 | `checklist-template.md` | 验收清单：业务检查项 + ADD 规则合规检查 | Step 5 / Step 8 |
-| `review-template.md` | ADD-9 方向验证：元信息 + 问题复现 + 方案对比 + 决策结论 + 影响评估 | Review 关卡 |
-| `review-implementation-template.md` | ADD-10 语义对齐：格式契约 + 框架版本 + 数据模型 + 环境变量 + API 选择 + E2E curl | Code 后 |
+| `review-template.md` | ADD-9 方向验证：元信息 + **HITL 发现总览**（一次性人类审核表） + 问题复现 + 方案对比 + 决策结论 + 影响评估 | Review 关卡 |
+| `review-implementation-template.md` | ADD-10 语义对齐：元信息 + **HITL 发现总览** + 格式契约 + 框架版本 + 数据模型 + 环境变量 + API 选择 + E2E curl | Code 后 |
 | `review-runtime-template.md` | ADD-11 证据持久化：发现列表 + 根因分析 + 流程改进项 + 回流确认 | Deploy 后 |
-| `handoff-template.md` | 交接总览索引（指向单轮/多轮） | Step 8 后 |
+| `handoff-template.md` | 交接总览索引（指向单轮/多轮）。**注意**：精简版 Plan 不需要生成此文件——Handoff 已融合在 Plan §四 | Step 8 后 |
 | `handoff-single-round-template.md` | 单轮交接：9 章节（含恢复上下文审计查询） | 单轮变更完成后 |
 | `handoff-multi-round-template.md` | 多轮交接：全局拓扑 + 每轮 13 子章节 + 收敛规则 + 启动模板 | 多轮原子事务完成后 |
 
@@ -106,6 +121,8 @@ description: "Audit-Driven Development paradigm workflow. Invoke when starting a
 >
 > **每次根据模板生成文档时（plan/spec/review/handoff），MUST 先重新读取对应的模板文件，再填充内容。禁止凭记忆生成——模板可能已在迭代中更新，记忆中的版本可能不完整。**
 
+> **Review 的 HITL 磋商（temporary.md 机制）**：生成方案 Review（`review-template.md`）或实现 Review（`review-implementation-template.md`）时，和 Plan 一样——doc-format-guard 要求完整章节才放行，HITL 第一步只写总览表会被阻断。因此 Review 也走 temporary.md 流程：先写 `{review-name}.temporary.md`（只含 HITL 发现总览表）→ 人类拍板 → 生成完整 Review 写入 `.qoder/reviews/` → 删除 temporary。具体步骤见下方 Step 3.5.3（实现 Review）和 Step 0 方案 Review 产出。
+
 #### 0.2 搜索相关项目文档
 
 调用 MCP 工具 `find_related_docs` 查找与当前变更相关的项目文档：
@@ -793,7 +810,7 @@ check_add_route_completeness({ planKeyword: "<Plan 核心关键词>" })
 
 ### 3.5.3 生成实现审查文档
 
-读取 `review-implementation-template.md`，逐项填写审查结果。
+按 HITL temporary.md 流程执行：读取 `review-implementation-template.md` → 先写 `{name}-review-implementation.temporary.md`（只含 HITL 发现总览表）→ 人类一次性拍板 → 逐条展开详细分析 → 写入 `.qoder/reviews/`（guard 放行）→ 删除 temporary。详见上方模板生成规则处的 Review HITL 磋商说明。
 
 ### 3.5.4 生成运行时审查文档（所有 [T] 项通过后）
 
@@ -1038,8 +1055,11 @@ LIMIT 10;
 ### 收敛后：生成交接手册（handoff）
 
 > **MUST NOT 跳过此步骤。** 收敛条件全部满足后，必须按模板生成交接手册，使后续 AI Session 能恢复上下文。
+>
+> **例外**：如果本 Plan 使用的是 `simple-plan-template.md`，**跳过本步骤**——Handoff 已融合在 Plan §四，无需独立文件。
 
-1. **读取对应模板**：单轮变更读 `handoff-single-round-template.md`（9 章节），多轮变更读 `handoff-multi-round-template.md`（13 子章节/轮）
+1. **判断是否精简版**：检查 Plan 文件是否基于 `simple-plan-template.md` → 是则跳过，Handoff 信息已在 Plan §四 中
+2. **读取对应模板**：单轮变更读 `handoff-single-round-template.md`（9 章节），多轮变更读 `handoff-multi-round-template.md`（13 子章节/轮）
 2. **填满所有章节**：模板中每个 `{占位符}` 都必须替换为实际内容，不得留空。特别注意：
    - **§8 恢复上下文审计查询**：MUST 包含基于真实 `query_audit_logs` 结果的逐文件审计查询语句，不得编造
    - **§9 后置确认**：逐项确认 tsc/ADD 合规/审计落库

package/templates/core/templates/prd-incremental-template.md

@@ -75,13 +75,18 @@
 ## 四、Plan 拆分影响
 
 > 本次变更是否影响了原 PRD 的 Plan 拆分建议？必填——增量改动可能改变 Plan 链路。
+>
+> **模板选择**：| 任务特征 | 推荐模板 | 特征判断 |
+> |---------|---------|------|
+> | 单一聚焦改动（≤3 文件、无子模块、无新架构） | `simple-plan-template.md` | 配置收敛、重构、修复、单文件新增 |
+> | 多模块/跨系统/含架构设计或外部 API | `standard-plan-template.md` | 新功能模块、数据模型变更、跨仓库集成 |
 
 **影响判定**：无影响 / 新增 Plan / 调整 Plan 依赖 / 废弃 Plan
 
 **变更后的 Plan 链路**：
 
 ```text
-{更新后的 Plan 链路，格式与标准 PRD §10.1 一致}
+{更新后的 Plan 链路，每个 Plan 标注 模板: {simple/standard}，格式与标准 PRD §10.1 一致}
 ```
 
 ---

package/templates/core/templates/prd-standard-template.md

@@ -170,17 +170,22 @@
 ## 十、Plan 拆分建议
 
 > 本章节指导下游 AI 如何将本 PRD 拆分为 Plan。必填——没有这条，AI 拿到 PRD 不知道从哪下手。
+>
+> **模板选择**：| 任务特征 | 推荐模板 | 特征判断 |
+> |---------|---------|------|
+> | 单一聚焦改动（≤3 文件、无子模块、无新架构） | `simple-plan-template.md` | 配置收敛、重构、修复、单文件新增 |
+> | 多模块/跨系统/含架构设计或外部 API | `standard-plan-template.md` | 新功能模块、数据模型变更、跨仓库集成 |
 
 ### 10.1 推荐 Plan 链路
 
 ```text
-Plan 1: {plan名称} ── 聚焦: {子功能描述}
+Plan 1: {plan名称} ── 模板: {simple/standard} ── 聚焦: {子功能描述}
             │  依赖: 无
             ▼
-Plan 2: {plan名称} ── 聚焦: {子功能描述}
+Plan 2: {plan名称} ── 模板: {simple/standard} ── 聚焦: {子功能描述}
             │  依赖: Plan 1 完成的 {产出物}
             ▼
-Plan 3: {plan名称} ── 聚焦: {子功能描述}
+Plan 3: {plan名称} ── 模板: {simple/standard} ── 聚焦: {子功能描述}
             依赖: Plan 2 完成的 {产出物}
 ```
 

package/templates/core/templates/review-implementation-template.md

@@ -10,6 +10,20 @@
 
 ---
 
+## HITL 发现总览（一次性提交人类审核）
+
+> **规则**：AI 必须先在此表中列出 **所有检查维度的发现**，等待人类一次性审核通过后再逐项展开。
+> 禁止逐条边查边改——这是批量审批入口。
+
+| # | 严重度 | 检查维度 | 发现摘要 | 建议措施 | 人类决策 |
+|---|:---:|------|---------|---------|:---:|
+| 1 | 🔴 高 | {契约/数据模型/安全} | {一句话} | {建议} | 接受/拒绝/修改 |
+| 2 | 🟡 中 | {兼容性/环境} | {一句话} | {建议} | 接受/拒绝/修改 |
+
+> **人类确认后**：AI 在下方逐章节展开详细检查。
+
+---
+
 ## 1. 跨仓库格式契约
 
 列出所有跨系统 API，逐对验证请求/响应格式：

package/templates/core/templates/review-implementation-template.schema.json

@@ -6,6 +6,12 @@
             "heading": "## Review 元信息",
             "required": true
         },
+        {
+            "id": "hitl",
+            "heading": "## HITL 发现总览",
+            "required": true,
+            "note": "AI 必须在此表中列出所有检查维度的发现，提交人类一次性审核。禁止逐条边查边改。"
+        },
         {
             "id": "contract",
             "heading": "## 1. 跨仓库格式契约",

package/templates/core/templates/review-template.md

@@ -10,6 +10,21 @@
 
 ---
 
+## HITL 发现总览（一次性提交人类审核）
+
+> **规则**：AI 必须先在此表中列出 **所有发现**，等待人类一次性审核通过后再逐项推进。
+> 禁止边发现边修改——这是批量审批入口，不是逐条对话。
+
+| # | 严重度 | 类别 | 发现摘要 | 建议措施 | 人类决策 |
+|---|:---:|------|---------|---------|:---:|
+| 1 | 🔴 高 | {架构/安全/性能} | {一句话} | {建议} | 接受/拒绝/修改 |
+| 2 | 🟡 中 | {规范/兼容性} | {一句话} | {建议} | 接受/拒绝/修改 |
+| 3 | 🟢 低 | {风格/优化} | {一句话} | {建议} | 接受/拒绝/修改 |
+
+> **人类确认后**：AI 在下方逐条展开详细分析。每一条展开时必须引用上方编号。
+
+---
+
 ## 1. 问题复现
 
 为什么需要这次评审？

package/templates/core/templates/review-template.schema.json

@@ -6,6 +6,12 @@
             "heading": "## Review 元信息",
             "required": true
         },
+        {
+            "id": "hitl",
+            "heading": "## HITL 发现总览",
+            "required": true,
+            "note": "AI 必须在此表中列出所有发现，提交人类一次性审核。禁止边发现边修改。"
+        },
         {
             "id": "problem",
             "heading": "## 1. 问题复现",

package/templates/core/templates/simple-plan-template.md

@@ -1,12 +1,39 @@
 # {需求名}-plan-v{版本号}
 
-> 精简版 Plan 模板：适用于单一聚焦改动（配置收敛、重构、修复等）。Tasks 合并于 Plan 体，无需独立 spec 文件。
+> 精简版 Plan 模板：适用于单一聚焦改动（配置收敛、重构、修复、单文件新增等）。Tasks 合并于 Plan 体，无需独立 spec 文件。**Handoff 融合于 §四，无需独立 handoff 文件。**
+>
+> **何时选用精简版 vs 标准版**：
+> - ✅ 精简版：≤3 个文件变更、无新模块/架构设计、无外部 API 契约变更
+> - 📋 标准版 (`standard-plan-template.md`)：多模块、跨系统集成、含架构选型或数据模型设计
+>
+> ⚠️ **反作弊规则**：选择精简版不是因为"想省事"——是因为任务确实简单。以下三条不满足任一条，必须改用标准版：
+> - 涉及文件 ≤ 3 个且全部在本模块内
+> - 无新增模块/子系统/外部依赖
+> - 无需独立 spec 文档（改动逻辑一句话能说清）
+> **如果 AI 为复杂任务偷选精简版，HITL 表中必然暴露——文件数对不上、架构变更为空、人类会拒绝。**
 
 **创建时间**: {ISO 时间戳}
 **主导 AI**: {AI 助手标识}
 
 ---
 
+## HITL 计划总览（一次性提交人类审核）
+
+> **规则**：AI 先在此表中列出本次改动要点，等待人类一次性拍板后再执行。
+>
+> ⚠️ **禁止偷懒**：文件清单必须是**实际完整列表**（不是"等 3 个文件"），方案/设计决策必须逐条列出（不是"等若干决策"）。HITL 表是人类的最后防线——这里糊弄，后面全白做。
+
+| 维度 | 内容 | 人类决策 |
+|------|------|:---:|
+| 涉及文件（完整路径） | {逐行列出的实际文件路径} | 同意/调整 |
+| 改动类型 | {重构 / 修复 / 配置 / 新增} | 同意/调整 |
+| 方案/设计决策 | {逐条列出关键设计选择} | 同意/调整 |
+| 风险等级 | {🔴高 / 🟡中 / 🟢低} | 同意/调整 |
+
+> **人类确认后**：AI 在下方展开并执行。
+
+---
+
 ## 一、Plan 概述
 
 - **现状**: 一句话描述当前问题
@@ -40,9 +67,9 @@
 
 ---
 
-## 四、Handoff
+## 四、Handoff（融合于 Plan 中，无需独立 handoff 文件）
 
-> 与独立 `handoff-single-round-template.md` 结构一致。
+> **本 §四 即是 Handoff。** 精简版 Plan 不产生独立的 `-handoff-v1.md` 文件——交接信息直接嵌入此处。后续 AI Session 恢复上下文时，读取本 Plan 文件即可获取全部交接信息。
 
 ### 4.1 交接前状态
 

package/templates/core/templates/simple-plan-template.schema.json

@@ -6,6 +6,12 @@
             "heading": "## 一、Plan 概述",
             "required": true
         },
+        {
+            "id": "hitl",
+            "heading": "## HITL 计划总览",
+            "required": true,
+            "note": "AI 必须先在此表中列出实际完整文件路径和方案决策，等待人类拍板后再执行。禁止偷懒写'等 N 个文件'。"
+        },
         {
             "id": "changes",
             "heading": "## 二、变更范围",

package/templates/core/templates/standard-plan-template.md

@@ -19,6 +19,24 @@
 
 ---
 
+## HITL 计划总览（一次性提交人类审核）
+
+> **规则**：AI 先在此表中列出 Plan 的全部关键决策，等待人类一次性拍板后再展开详细设计。
+> 禁止跳过此表直接写正文——这是方向校准入口。
+
+| 维度 | 内容 | 人类决策 |
+|------|------|:---:|
+| 影响模块 | {列出所有涉及模块/子系统} | 同意/调整 |
+| 预估文件数 | {N} 个文件（{修改/新建/删除}） | 同意/调整 |
+| 架构变更 | {无 / 新增 {模块} / 重构 {层}} | 同意/调整 |
+| 新增依赖 | {无 / {依赖名}} | 同意/调整 |
+| 风险等级 | {🔴高 / 🟡中 / 🟢低} | 同意/调整 |
+| 预计轮次 | {1-2 轮 / 3-5 轮} | 同意/调整 |
+
+> **人类确认后**：AI 在下方展开完整 Plan 设计。
+
+---
+
 ## 一、背景与目标
 
 ### 1.1 问题现状