add-coder 0.3.25 → 0.3.27

package/templates/core/hooks/lib/vocabulary.sh

@@ -1,15 +1,21 @@
 #!/bin/bash
 # vocabulary.sh — 从 vocabulary markdown 表格加载触发词
-# 单一数据源: .qoder/vocabulary/add-governance-vocabulary.md §类别 A-F 表格
+# 单一数据源: {MAGIC_DIR}/vocabulary/add-governance-vocabulary.md §类别 A-F 表格
+# 协议层契约（Review P1 #5）: 仅当前 magicDir scope；入口注入 MAGIC_DIR 或物理位置推导；
+# 禁止跨端扫描与 .add fallback，禁止 adapter 名称默认值。
 
-# 动态探测 MAGIC_DIR
+# MAGIC_DIR 解析: 入口注入优先；未注入时从脚本物理位置（<magicDir>/hooks/lib/）反推
 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}"
+  if [ -n "${HOOK_DIR:-}" ]; then
+    MAGIC_DIR="$(basename "$(dirname "$HOOK_DIR")")"
+  else
+    # 无注入且无物理位置 → 无法判定 → 返回空（调用方 fail-closed，禁止猜测 adapter）
+    VOCABULARY_FILE=""
+  fi
+fi
+if [ -n "${MAGIC_DIR:-}" ]; then
+  VOCABULARY_FILE="${PROJECT_DIR:-$PWD}/$MAGIC_DIR/vocabulary/add-governance-vocabulary.md"
 fi
-VOCABULARY_FILE="${PROJECT_DIR:-$PWD}/$MAGIC_DIR/vocabulary/add-governance-vocabulary.md"
 
 # 输出格式: 优先级::触发词正则::响应文本（:: 避免与触发词内的 | 冲突）
 load_triggers() {

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

@@ -62,8 +62,9 @@ EOF
     exit 2
   fi
 
-  # 检测 2: sed -i 原地编辑
-  if echo "$command" | grep -qE '\bsed\b.*-i'; then
+  # 检测 2: sed -i 原地编辑（精确判定：`-i` 必须是 sed 独立 option；不把路径子串如 session-init 误判）
+  # 协议层契约（Review P0 #3/命令分类）: 与 codex 已实现版本同契约语义
+  if echo "$command" | grep -qE '(^|[;&|][[:space:]]*)sed[[:space:]]+([^;&|]*[[:space:]])?(-[[:alpha:]]*i[^[:space:];&|]*|--in-place(=[^[:space:];&|]*)?)([[:space:];&|]|$)'; then
     _reason="禁止通过 sed -i 直接编辑文件。请使用 SearchReplace 工具。"
     cat >&2 <<'EOF'
 ⛔ [ADD PreToolUse §A] 阻断: 禁止通过 sed -i 原地编辑文件。
@@ -136,7 +137,8 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
   file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
   [ -z "$file_path" ] && exit 0
 
-  if echo "$file_path" | grep -qE '\.(qoder|claude|add)/(plans|specs|reviews)/'; then
+  # §B: 写入守卫按当前 magicDir 限域（Review P1 #5: 禁止多端路径正则）
+  if echo "$file_path" | grep -qE "${MAGIC_DIR}/(plans|specs|reviews)/"; then
     if type detect_active_add >/dev/null 2>&1; then
       state=$(detect_active_add 2>/dev/null || true)
       if [ -z "$state" ]; then
@@ -154,8 +156,8 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
     exit 2
   fi
 
-  # §C: 模板类型前置注入 — plans/ 写入前提示应选模板
-  if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
+  # §C: 模板类型前置注入 — 仅当前 magicDir plans/ 写入前提示应选模板
+  if echo "$file_path" | grep -qE "${MAGIC_DIR}/(plans)/"; then
     fname=$(basename "$file_path")
     if echo "$fname" | grep -qE 'plan-v[0-9]'; then
       echo "💡 [ADD PreToolUse] 写入 Plan → 模板: standard-plan-template.md（标准）或 simple-plan-template.md（≤3文件）" >&2
@@ -177,13 +179,13 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
   # implementation/runtime review 不需要 HITL，走 §B 活跃 Plan 检查
   # handoff 是 Step 8 收敛产物（多轮交接手册），不经 HITL 审批，同样豁免
   # TODO 应该caijuehub管理
-  if echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(plans)/'; then
+  if echo "$file_path" | grep -qE "${MAGIC_DIR}/(plans)/"; then
     if echo "$file_path" | grep -qE '\-handoff'; then
       _do_hitl=false  # handoff 不被 HITL 拦截（Step 8 产物，无独立审批）
     else
       _do_hitl=true
     fi
-  elif echo "$file_path" | grep -qE '\.(qoder|claude|add|vscode|trae)/(reviews)/'; then
+  elif echo "$file_path" | grep -qE "${MAGIC_DIR}/(reviews)/"; then
     if echo "$file_path" | grep -qE '-(implementation|runtime)'; then
       _do_hitl=false  # implementation/runtime review 不被 HITL 拦截
     else
@@ -194,7 +196,11 @@ if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ] || [ "$tool_name" = "
   fi
 
   if [ "$_do_hitl" = true ]; then
-    _relative=$(echo "$file_path" | sed 's|.*/\.\(qoder\|claude\|add\|vscode\|trae\)/\(plans\|reviews\)/||')
+    _relative=$(echo "$file_path" | sed "s|.*/\.\(qoder\|claude\|add\|vscode\|trae\)/\(plans\|reviews\)/||")
+    # 限域: 仅当前 magicDir 下的 plans/reviews 触发 HITL 门禁
+    if ! echo "$file_path" | grep -qE "${MAGIC_DIR}/(plans|reviews)/"; then
+      _do_hitl=false
+    fi
     _planName=$(basename "$_relative" .md | sed 's/\.hitl$//;s/-plan-v[0-9]*$//;s/-add-route-v[0-9]*$//;s/-review-v[0-9]*$//;s/-review-implementation$//;s/-review-runtime$//')
     if [ -n "$_planName" ]; then
       _tongyi_marker="${PROJECT_DIR}/${MAGIC_DIR}/hitl/.tongyi-${_planName}"

package/templates/core/hooks/stop-check.sh

@@ -1,10 +1,12 @@
 #!/bin/bash
 # stop-check.sh — Claude Code Stop：四象限分流 + 验收检查（few-shot 上下文注入）
 # 治理卡位 #7: 验收检查 + devlog + 阻断
+# DB lifecycle 真相源（协议层）：DB 不可用时 fail-closed，禁止回退 Handoff/add-route 猜测
 set -euo pipefail
 
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
 export CURRENT_MAGIC=$(basename "$(dirname "$HOOK_DIR")")
+export MAGIC_DIR=$(basename "$(dirname "$HOOK_DIR")")
 COMMON_LIB="$HOOK_DIR/lib/common.sh"
 [ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
 
@@ -13,6 +15,13 @@ export PROJECT_DIR="$PWD"
 state=$(detect_active_add 2>/dev/null || true)
 has_dev=$(has_dev_action 2>/dev/null && echo "true" || echo "false")
 
+# ═══════ Q0: DB 不可用 → fail closed（禁止当“无 Plan”） ═══════
+if [ "${state%%::*}" = "__STATUS_UNAVAILABLE__" ]; then
+  reason=$(echo "$state" | awk -F'::' '{print $2}')
+  echo "[ADD Stop] ⛔ Plan status 暂不可用（${reason}）。未回退 Handoff/add-route 猜测，请恢复数据库或 MCP resolver 后重试。" >&2
+  exit "${EXIT_BLOCK:-2}"
+fi
+
 # ═══════ Q1: 无 ADD + 无 dev → 正常停 ═══════
 if [ -z "$state" ] && [ "$has_dev" != "true" ]; then
   exit 0

package/templates/core/prisma/add.prisma

@@ -1,43 +1,54 @@
 // add.prisma — ADD 治理模型，独立于用户业务表
 
 model AddUser {
-  id              String          @id @default(cuid())
-  username        String          @unique
-  email           String?
-  devOperations   DevOperation[]
-  auditLogs       AuditLog[]
+  id            String         @id @default(cuid())
+  username      String         @unique
+  email         String?
+  devOperations DevOperation[]
+  auditLogs     AuditLog[]
 }
 
 model DevOperation {
-  id          String   @id @default(cuid())
-  userId      String
-  user        AddUser  @relation(fields: [userId], references: [id], onDelete: Cascade)
-  planKeyword String
-  action      String
-  targetType  String
-  targetId    String
-  beforeState Json?
-  afterState  Json?
-  reason      String?
-  createdAt   DateTime @default(now())
+  id                 String   @id @default(cuid())
+  userId             String
+  user               AddUser  @relation(fields: [userId], references: [id], onDelete: Cascade)
+  projectKey         String   @default("legacy-unknown")
+  producerAdapterKey String   @default("legacy-unknown")
+  contextId          String   @default("legacy-unknown")
+  toolName           String   @default("record_dev_operation")
+  operationKey       String   @default(cuid())
+  planKeyword        String
+  action             String
+  targetType         String
+  targetId           String
+  beforeState        Json?
+  afterState         Json?
+  reason             String?
+  createdAt          DateTime @default(now())
 
+  @@unique([projectKey, producerAdapterKey, toolName, operationKey])
   @@index([planKeyword])
+  @@index([projectKey, producerAdapterKey, planKeyword])
 }
 
 model AuditLog {
-  id          String   @id @default(cuid())
-  userId      String
-  user        AddUser  @relation(fields: [userId], references: [id], onDelete: Cascade)
-  action      String
-  targetType  String
-  targetId    String
-  traceId     String?
-  beforeState Json?
-  afterState  Json?
-  reason      String?
-  createdAt   DateTime @default(now())
+  id                 String   @id @default(cuid())
+  userId             String
+  user               AddUser  @relation(fields: [userId], references: [id], onDelete: Cascade)
+  projectKey         String   @default("legacy-unknown")
+  producerAdapterKey String   @default("legacy-unknown")
+  contextId          String   @default("legacy-unknown")
+  action             String
+  targetType         String
+  targetId           String
+  traceId            String?
+  beforeState        Json?
+  afterState         Json?
+  reason             String?
+  createdAt          DateTime @default(now())
 
   @@index([traceId])
+  @@index([projectKey, producerAdapterKey, contextId])
 }
 
 // ===== HITL 人机审核架构 =====
@@ -61,65 +72,85 @@ enum ReviewType {
   RUNTIME
 }
 
+enum PlanLifecycleStatus {
+  DRAFT
+  ACTIVE
+  BLOCKED
+  REJECTED
+  CLOSED
+  ABANDONED
+}
+
 model HitlRecord {
-  id           String      @id @default(cuid())
+  id           String     @id @default(cuid())
+  projectKey   String     @default("legacy-unknown")
+  adapterKey   String     @default("legacy-unknown")
   planName     String
-  plan         PlanRecord  @relation(fields: [planName], references: [planName])
-  round        Int         @default(1)
-  type         HitlType    @default(PLAN)
-  status       HitlStatus  @default(DRAFT)
+  plan         PlanRecord @relation(fields: [projectKey, adapterKey, planName], references: [projectKey, adapterKey, planName], onDelete: Cascade)
+  round        Int        @default(1)
+  type         HitlType   @default(PLAN)
+  status       HitlStatus @default(DRAFT)
   proposalPath String?
   approvedAt   DateTime?
   rejectedAt   DateTime?
   rejectReason String?
-  createdBy    String      @default("ai-assistant")
-  createdAt    DateTime    @default(now())
-  updatedAt    DateTime    @updatedAt
+  createdBy    String     @default("ai-assistant")
+  createdAt    DateTime   @default(now())
+  updatedAt    DateTime   @updatedAt
 
-  @@unique([planName, round])
-  @@index([planName])
+  @@unique([projectKey, adapterKey, planName, type, round])
+  @@index([projectKey, adapterKey, planName])
   @@index([status])
 }
 
 model PlanRecord {
-  id             String        @id @default(cuid())
-  planName       String        @unique
-  planPath       String
-  specPath       String?
-  tasksPath      String?
-  checklistPath  String?
-  addRoutePath   String?
-  totalTasks     Int           @default(0)
-  doneTasks      Int           @default(0)
-  checklistT     Int           @default(0)
-  checklistTDone Int           @default(0)
-  checklistR     Int           @default(0)
-  planKeyword    String?
+  id               String                     @id @default(cuid())
+  projectKey       String                     @default("legacy-unknown")
+  adapterKey       String                     @default("legacy-unknown")
+  planName         String
+  lifecycle        PlanLifecycleStatus        @default(DRAFT)
+  revision         Int                        @default(0)
+  planPath         String
+  specPath         String?
+  tasksPath        String?
+  checklistPath    String?
+  addRoutePath     String?
+  totalTasks       Int                        @default(0)
+  doneTasks        Int                        @default(0)
+  checklistT       Int                        @default(0)
+  checklistTDone   Int                        @default(0)
+  checklistR       Int                        @default(0)
+  planKeyword      String?
   // 并发协作契约：该 Plan 在契约中的角色（MASTER=总控 / SUB=子 Plan）
-  contractRole   ContractRole?
+  contractRole     ContractRole?
   // 所属契约名（与 CollabContract.contractName 对应，反查用）
-  contractName   String?
+  contractName     String?
   // 作为总控 Plan 持有的契约（masterPlanName 外键方向）
-  masterContract CollabContract?
+  masterContract   CollabContract?            @relation("MasterPlan")
+  contractBindings CollaborationPlanBinding[]
   // DPS 四维评分历史（check_dps 调用后回写，供 FFT 自适应权重消费）
-  dpsSemScore    Int?          // 语义相关性 0-100
-  dpsEntropyScore Int?         // 信息熵匹配 0-100
-  dpsCpmScore    Int?          // CPM 关键路径 0-100
-  dpsStructScore Int?          // 结构完整度 0-100
-  dpsComposite   Int?          // 加权 DPS 总分 0-100
-  hitls          HitlRecord[]
-  reviews        ReviewRecord[]
-  createdAt      DateTime      @default(now())
-  updatedAt      DateTime      @updatedAt
-
+  dpsSemScore      Int? // 语义相关性 0-100
+  dpsEntropyScore  Int? // 信息熵匹配 0-100
+  dpsCpmScore      Int? // CPM 关键路径 0-100
+  dpsStructScore   Int? // 结构完整度 0-100
+  dpsComposite     Int? // 加权 DPS 总分 0-100
+  hitls            HitlRecord[]
+  reviews          ReviewRecord[]
+  createdAt        DateTime                   @default(now())
+  updatedAt        DateTime                   @updatedAt
+
+  @@unique([projectKey, adapterKey, planName])
   @@index([planKeyword])
   @@index([contractName])
+  @@index([projectKey, adapterKey, lifecycle])
 }
 
 model ReviewRecord {
   id           String     @id @default(cuid())
+  projectKey   String     @default("legacy-unknown")
+  adapterKey   String     @default("legacy-unknown")
   planName     String
-  plan         PlanRecord @relation(fields: [planName], references: [planName], onDelete: Cascade)
+  plan         PlanRecord @relation(fields: [projectKey, adapterKey, planName], references: [projectKey, adapterKey, planName], onDelete: Cascade)
   type         ReviewType @default(PLAN_REVIEW)
   reviewPath   String?
   p0Count      Int        @default(0)
@@ -128,33 +159,60 @@ model ReviewRecord {
   createdAt    DateTime   @default(now())
   updatedAt    DateTime   @updatedAt
 
-  @@index([planName])
+  @@index([projectKey, adapterKey, planName])
   @@index([type])
 }
 
 enum ContractRole {
-  MASTER  // 总控 Plan（契约持有者）
-  SUB     // 子 Plan（契约实施单元）
+  MASTER // 总控 Plan（契约持有者）
+  SUB // 子 Plan（契约实施单元）
+}
+
+enum CollaborationBindingRole {
+  MASTER
+  MEMBER
 }
 
 // 并发协作契约（多智能体并行实施规则集，对应 collab-contract 文档）
 model CollabContract {
-  id                 String   @id @default(cuid())
-  contractName       String   @unique
+  id                 String                     @id @default(cuid())
+  projectKey         String                     @default("legacy-unknown")
+  ownerAdapterKey    String                     @default("legacy-unknown")
+  contractName       String
   contractPath       String
   // 外键：总控 Plan（契约持有者，ContractRole=MASTER，一对一）
-  masterPlanName     String   @unique
-  masterPlan         PlanRecord @relation(fields: [masterPlanName], references: [planName], onDelete: Restrict)
-  participants       Json     // [{role, platformEntity, boundPlan, planKeyword, description}]
-  abilityMatrix      Json?    // {能力: {专家: boolean}}
-  stages             Json     // [{stage, expert, trigger, parallelism}]
-  dependencyGraph    String?  // ASCII 图 + 机器可读声明
-  fileBoundaries     Json     // [{expert, exclusiveDomain, forbidden, isolationMode}]  isolationMode: file/worktree
-  completionCriteria Json?    // {专家: 完成标志}
-  status             String   @default("ACTIVE") // ACTIVE / SUPERSEDED
-  version            Int      @default(1)
-  createdAt          DateTime @default(now())
-  updatedAt          DateTime @updatedAt
+  masterProjectKey   String                     @default("legacy-unknown")
+  masterAdapterKey   String                     @default("legacy-unknown")
+  masterPlanName     String
+  masterPlan         PlanRecord                 @relation("MasterPlan", fields: [masterProjectKey, masterAdapterKey, masterPlanName], references: [projectKey, adapterKey, planName], onDelete: Restrict)
+  bindings           CollaborationPlanBinding[]
+  participants       Json // [{role, platformEntity, boundPlan, planKeyword, description}]
+  abilityMatrix      Json? // {能力: {专家: boolean}}
+  stages             Json // [{stage, expert, trigger, parallelism}]
+  dependencyGraph    String? // ASCII 图 + 机器可读声明
+  fileBoundaries     Json // [{expert, exclusiveDomain, forbidden, isolationMode}]  isolationMode: file/worktree
+  completionCriteria Json? // {专家: 完成标志}
+  status             String                     @default("ACTIVE") // ACTIVE / SUPERSEDED
+  version            Int                        @default(1)
+  createdAt          DateTime                   @default(now())
+  updatedAt          DateTime                   @updatedAt
+
+  @@unique([projectKey, contractName])
+  @@unique([masterProjectKey, masterAdapterKey, masterPlanName])
+  @@index([projectKey, ownerAdapterKey])
+}
 
-  @@index([masterPlanName])
+model CollaborationPlanBinding {
+  id         String                   @id @default(cuid())
+  contractId String
+  contract   CollabContract           @relation(fields: [contractId], references: [id], onDelete: Cascade)
+  projectKey String
+  adapterKey String
+  planName   String
+  plan       PlanRecord               @relation(fields: [projectKey, adapterKey, planName], references: [projectKey, adapterKey, planName], onDelete: Cascade)
+  role       CollaborationBindingRole @default(MEMBER)
+  createdAt  DateTime                 @default(now())
+
+  @@unique([contractId, projectKey, adapterKey, planName])
+  @@index([projectKey, adapterKey, planName])
 }

package/templates/core/rules/project_rules.md

@@ -26,8 +26,8 @@
 | P2 | ADD-13 DPS 上游文档质量闸门 | Plan 概括度 → Review 注意力稀释 → Specs 遗漏 → 实现偏差。`check_dps`（DPS ≥ {{dpsPass}}）在 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 引入 |
-| P2 | ADD-18 HITL 人机审核强制规则 | Plan/Review 必须经过 HITL 审批（`create_hitl` → 人工 tongyi/bohui → `update_hitl` 确认）。无 `.hitl-tongyi-{planName}` 哨兵时 pre-tool-use hook 阻断写入正式文件。提案文件按 hitl-template.md 生成 + schema 校验 | ✅ 已实现 | 2026-07-27 引入 |
+| P2 | ADD-17 HITL 提案载体与状态机 | `create_hitl` 接收 `dimensions`，创建 `HitlRecord(DRAFT)` 与 `*.hitl.md` 提案；人工拍板后由 `update_hitl` 写入终态，正式文档仅在 `status_hitl=TONGYI` 后生成 | ✅ 已实现 | 2026-07-23 引入，2026-08-12 对齐 MCP 实现 |
+| P2 | ADD-18 HITL 人机审核强制规则 | Plan、方案 Review、实现 Review 必须经过 `create_hitl` → 人工 tongyi/bohui → `update_hitl`；`TONGYI` 同步写 DB、提案状态和 `.tongyi-{planName}` 哨兵 | ✅ 已实现 | 2026-07-27 引入 |
 
 
 ### P0 规则：不可跳过
@@ -68,7 +68,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，拍板后写正式文件） |
+| ADD-17 | `add-paradigm` 独立能力：生成 Plan / Step 0 / Step 3.5 | Plan/Review HITL：整理 dimensions → create_hitl 生成提案 → update_hitl 拍板 → status_hitl 校验终态 |
 | ADD-18 | `add-paradigm` 独立能力：生成 Plan + Step 0 + pre-tool-use §C | HITL 审批强制：create_hitl → 人工 tongyi/bohui → update_hitl 确认；hook 哨兵检查 |
 
 ---
@@ -783,45 +783,47 @@ ADD-0.1 要求"文档先行"（先改文档再改代码）。ADD-16 是对 ADD-0
 
 ---
 
-## ADD-17：HITL 磋商临时文件机制
+## ADD-17：HITL 提案载体与状态机
 
-**Plan 和 Review 的 HITL 磋商必须在写入正式文件之前完成，但 doc-format-guard 要求 `.qoder/plans/` 和 `.qoder/reviews/` 下的文件包含完整章节才放行。HITL 第一步只写总览表、不写正文——会被 guard 阻断。**
+**Plan、方案 Review 和实现 Review 在写入正式文件前，必须通过 `create_hitl` 建立结构化审批提案。`*.hitl.md` 与 `HitlRecord` 是同一轮审批的文件/数据库双通道载体；正式文档不得替代审批提案。**
 
 ### 流程
 
 ```
-① AI 写 {name}.temporary.md（只含 HITL 总览表，放项目根目录，不受 guard 检查）
-② 人类审阅 HITL 表 → 逐行拍板（同意/调整）
-③ AI 根据确认后的 HITL 表生成完整 Plan/Review → 写入正式路径（guard 放行）
-④ 删除 temporary.md
+① AI 读取对应模板并将待拍板发现整理为 dimensions
+② create_hitl({ planName, type, dimensions }) → HitlRecord(DRAFT) + plans/{YYYY-MM}/{DD}/{planName}.hitl.md
+③ 人类审阅提案并逐项拍板 → update_hitl({ planName, type, status })
+④ status_hitl 确认 TONGYI → 生成完整 Plan/Review 并写入正式路径
+⑤ BOHUI → 修订 dimensions 后调用 create_hitl 创建 round+1
 ```
 
 ### 适用范围
 
-| 文档类型 | temporary 磋商 | 正式写入路径 |
+| 文档类型 | HITL type | 正式写入路径 |
 |---------|:---:|------|
-| Plan（标准版/精简版） | ✅ 需要 | `.qoder/plans/{YYYY-MM}/{DD}/` |
-| Review（方案/实现） | ✅ 需要 | `.qoder/reviews/` |
-| Spec / Tasks / Checklist | ❌ 不需要 | 直接写入 `.qoder/specs/` |
-| Handoff | ❌ 不需要 | 直接写入 `.qoder/plans/` |
+| Plan（标准版/精简版） | `PLAN` | `{{magicDir}}/plans/{YYYY-MM}/{DD}/` |
+| Review（方案/实现） | `PLAN_REVIEW` | `{{magicDir}}/reviews/` |
+| Runtime Review | 不需要 | `[T]` 全部通过后直接写入 `{{magicDir}}/reviews/` |
+| Spec / Tasks / Checklist | 不需要 | 直接写入 `{{magicDir}}/specs/` |
+| Handoff | 不需要 | 直接写入 `{{magicDir}}/plans/` |
 
 ### 与 ADD-0.1 的关系
 
-ADD-0.1 要求"文档先行"——HITL 磋商本身就是文档先行的一种形式（先对齐方向再产出文档）。temporary.md 机制确保 HITL 的"先拍板再展开"哲学不因 guard 的"完整章节校验"而被破坏。
+ADD-0.1 要求“文档先行”。`create_hitl` 先持久化决策维度与审批状态，再展开正式文档，使“先拍板、后展开”具备可查询、可追溯的事实源。
 
 ---
 
 ## ADD-18：HITL 人机审核强制规则
 
-**Plan 和 PLAN_REVIEW 类型 Review 在写入正式文件前，必须经过 HITL 审批。** 审批通过后生成 `.hitl-tongyi-{planName}` 哨兵文件，pre-tool-use hook 以此判断是否允许写入。
+**Plan、方案 Review 和实现 Review 在写入正式文件前，必须经过 HITL 审批。** 审批通过后，`update_hitl` 更新数据库与 `*.hitl.md` 状态，并在 `{{magicDir}}/hitl/` 生成 `.tongyi-{planName}` 哨兵。pre-tool-use hook 对 Plan/方案 Review 执行哨兵门禁；实现 Review 由 `add-paradigm` Step 3.5 与 `status_hitl` 门禁约束。
 
 ### 强制流程
 
 ```
-① create_hitl({ planName, type }) → HitlRecord DRAFT，生成 hitl.md 提案文件
-② 人类审阅 hitl.md → 逐行拍板
-③ update_hitl({ planName, status: "TONGYI" }) → 写 .hitl-tongyi-{planName} 哨兵
-   或 update_hitl({ planName, status: "BOHUI", reason }) → 提案驳回
+① create_hitl({ planName, type, dimensions }) → HitlRecord DRAFT，生成 *.hitl.md 提案文件
+② 人类审阅 *.hitl.md → 逐行拍板
+③ update_hitl({ planName, type, status: "TONGYI" }) → 更新 DB/提案并写 .tongyi-{planName} 哨兵
+   或 update_hitl({ planName, type, status: "BOHUI", reason }) → 更新 DB/提案并写 .bohui-{planName} 哨兵
 ④ TONGYI 后：正式写入 Plan/Review 文件（hook §C 放行）
 ⑤ BOHUI 后：create_hitl 新建 round+1，重新审批
 ```
@@ -830,15 +832,16 @@ ADD-0.1 要求"文档先行"——HITL 磋商本身就是文档先行的一种
 
 | 文档类型 | HITL 审批 | 依据 |
 |---------|:--------:|------|
-| Plan | ✅ 必须 | pre-tool-use §C 拦截 plans/ 目录 |
-| Review（PLAN_REVIEW） | ✅ 必须 | pre-tool-use §C 拦截 reviews/ 目录（不含 implementation/runtime） |
-| Review（implementation/runtime） | ❌ 不需要 | 走 §B 活跃 Plan 检查 |
+| Plan | ✅ 必须 | pre-tool-use §C 哨兵门禁 |
+| 方案 Review | ✅ 必须 | pre-tool-use §C 哨兵门禁 |
+| Implementation Review | ✅ 必须 | `add-paradigm` Step 3.5 + `status_hitl` |
+| Runtime Review | ❌ 不需要 | `[T]` 全部通过后直接生成 |
 | Spec / Tasks / Checklist | ❌ 不需要 | 直接写 |
 | Handoff | ❌ 不需要 | 直接写 |
 
 ### 与 ADD-17 的关系
 
-ADD-17 定义 HITL 如何在 guard 约束下运作（temporary.md 绕过 guard 完成磋商）。ADD-18 定义 HITL 审批本身是强制的——不经过 create_hitl→update_hitl 流程，hook 阻止写入。两者互补：ADD-17 是"怎么做 HITL"，ADD-18 是"必须做 HITL"。
+ADD-17 定义审批提案的载体、维度和状态流转；ADD-18 定义哪些正式文档必须先取得 `TONGYI`。两者共同以 `create_hitl → update_hitl → status_hitl` 为事实链，文件、数据库和哨兵相互校验。
 
 ---
 

package/templates/core/scripts/db-ensure.sh

@@ -156,6 +156,14 @@ apply_atlas_diff() {
 # ⑦ Atlas 同步主流程（探测 → dev-url → 目标 → baseline → diff → apply）
 atlas_sync() {
   [ "$ENGINE" = "sqlite" ] && return 0
+  # 迁移锁（进程层契约 v2 §6）：多 IDE 并发 init 时仅一个进程执行迁移
+  # 非阻塞拿锁（pg_try_advisory_lock），会话级锁——脚本退出连接断开自动释放
+  LOCK_KEY="0xADD001"
+  LOCKED="$(podman exec "${PROJECT_NAME:-add-project}-postgres" psql -U "${DATABASE_USER:-admin}" -d "${PROJECT_NAME:-add-project}" -tAc "SELECT pg_try_advisory_lock(${LOCK_KEY});" 2>/dev/null || true)"
+  if [ "$LOCKED" != "t" ]; then
+    echo "!!! 另一个进程正在迁移，请稍后重试"
+    return 1
+  fi
   if ! atlas_cmd version > /dev/null 2>&1; then
     echo "!!! Atlas 不可用。add-coder sync --patch 可自动安装 @ariga/atlas；或手动: pnpm add -D @ariga/atlas"
     echo "    降级路径: prisma-diff（免 shadow）→ db-push + 强制备份；文档: README「Atlas 数据库同步能力」"

package/templates/core/scripts/gen-plan-index.sh

@@ -1,24 +1,13 @@
 #!/bin/bash
 # 生成 {MAGIC_DIR}/plans/index.md 总览清单 — 按日期分层，每日自动更新
-# 自动探测 MAGIC_DIR（.qoder / .claude / .vscode / .trae / .codex / .add）
+# MAGIC_DIR 由脚本自身的物理目录确定，各 adapter 自治。
 set -e
 
-# 探测 MAGIC_DIR：在当前目录向上查找包含 plans/ 的隐藏目录
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-CURRENT="$SCRIPT_DIR"
-MAGIC_DIR=""
-while [ "$CURRENT" != "/" ]; do
-  for d in "$CURRENT"/.qoder "$CURRENT"/.claude "$CURRENT"/.vscode "$CURRENT"/.trae "$CURRENT"/.codex "$CURRENT"/.add; do
-    if [ -d "$d/plans" ]; then
-      MAGIC_DIR="$d"
-      break 2
-    fi
-  done
-  CURRENT="$(dirname "$CURRENT")"
-done
+MAGIC_DIR="$(dirname "$SCRIPT_DIR")"
 
-if [ -z "$MAGIC_DIR" ]; then
-  echo "❌ 未找到 MAGIC_DIR（.qoder / .claude / .vscode / .trae / .codex / .add 均无 plans/ 子目录）" >&2
+if [ ! -d "$MAGIC_DIR/plans" ]; then
+  echo "❌ 当前 adapter 不存在 plans/: $MAGIC_DIR" >&2
   exit 1
 fi
 

package/templates/core/scripts/mcp-server/notifications/hitl.ts

@@ -3,8 +3,10 @@ import { join } from "path"
 import { existsSync } from "fs"
 import { readFileSafe, readdirRecursive, PROJECT_ROOT, MAGIC_DIR } from "../shared/fs.js"
 import { prisma } from "../shared/prisma.js"
+import { getRuntimeContext } from "../shared/env.js"
 
 export function registerHitlNotifications(server: McpServer) {
+  const runtimeContext = getRuntimeContext()
   // ── HITL 表扫描 ──
   const scanHitl = async () => {
     const plansDir = join(PROJECT_ROOT, MAGIC_DIR, "plans")
@@ -29,7 +31,13 @@ export function registerHitlNotifications(server: McpServer) {
       const ops = prisma.devOperation as Record<string, (...a: unknown[]) => unknown>
       const since = new Date(Date.now() - 24 * 60 * 60 * 1000)
       const count = await ops.count({
-        where: { action: "HOOK_INTERCEPT", planKeyword: "no-active-plan", createdAt: { gte: since } },
+        where: {
+          action: "HOOK_INTERCEPT",
+          planKeyword: "no-active-plan",
+          projectKey: runtimeContext.projectKey,
+          producerAdapterKey: runtimeContext.adapterKey,
+          createdAt: { gte: since },
+        },
       }) as number
       if (count >= 10 && count !== lastWarnedCount) {
         lastWarnedCount = count