add-coder 0.3.26 → 0.3.28

package/templates/core/hooks/notification.ts

@@ -0,0 +1,11 @@
+// notification.ts — Notification 入口薄壳（Task 2.2/3.1 继承体系）
+// 治理逻辑: governance/notification-router.js（NotificationRouter 探测循环 + reviews 提醒）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { readHookInput } from "../governance/common.js"
+import { NotificationRouter } from "../governance/notification-router.js"
+
+const input = readHookInput()
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+process.exit(new NotificationRouter(PROJECT_DIR, ".add").run(input))

package/templates/core/hooks/permission-gate.ts

@@ -0,0 +1,7 @@
+// permission-gate.ts — PermissionRequest 入口薄壳（Task 5.1 继承体系）
+// 治理逻辑: governance/permission-gate-router.js（PermissionGateRouter——jq 语义解析 + emit 输出）
+// 入口职责: 仅进程语义（<50 行），治理 0 复制。
+
+import { runPermissionGate } from "../governance/permission-gate-router.js"
+
+runPermissionGate()

package/templates/core/hooks/post-tool-failure.ts

@@ -0,0 +1,7 @@
+// post-tool-failure.ts — PostToolUseFailure 入口薄壳（Task 5.1 继承体系）
+// 治理逻辑: governance/post-tool-failure-router.js（PostToolFailureRouter——jq 语义解析 + emit 输出）
+// 入口职责: 仅进程语义（<50 行），治理 0 复制。
+
+import { runPostToolFailure } from "../governance/post-tool-failure-router.js"
+
+runPostToolFailure()

package/templates/core/hooks/post-tool-use.ts

@@ -0,0 +1,23 @@
+// post-tool-use.ts — PostToolUse 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/post-tool-router.ts（PostToolRouter §1 DPS 哨兵 / §2 文档守卫 / §3 Bash 增强）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { jsonGet, readHookInput } from "../governance/common.js"
+import { PostToolRouter } from "../governance/post-tool-router.js"
+
+const input = readHookInput()
+let toolName = jsonGet(input, "tool_name")
+if (toolName === "") {
+  // bash 版此处 grep 兜底失败触发 set -e 崩溃（exit 1）——缺陷行为，
+  // TS 版修复：无 tool_name 的 PostToolUse 事件静默放行（冒烟契约 ∈ {0,2}）。
+  const fallback = input.match(/"tool_name"\s*:\s*"([^"]*)"/)?.[1] ?? ""
+  if (fallback === "") {
+    process.exit(0)
+  }
+  toolName = fallback
+}
+
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+const MAGIC_DIR = process.env.MAGIC_DIR || ".qoder"
+
+process.exit(new PostToolRouter(PROJECT_DIR, MAGIC_DIR).run(input, toolName))

package/templates/core/hooks/pre-compact.ts

@@ -0,0 +1,9 @@
+// pre-compact.ts — 上下文压缩前 ADD 状态保存（入口薄壳，Task 2.2/3.1 继承体系）
+// 治理逻辑: governance/pre-compact-guard.js（PreCompactGuard 状态保存 + tpl 标记清理）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { PreCompactGuard } from "../governance/pre-compact-guard.js"
+
+process.env.PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+process.exit(new PreCompactGuard().run())

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

@@ -0,0 +1,30 @@
+// pre-tool-use.ts — PreToolUse 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/pre-tool-guard.ts（PreToolUseGuard 服务类，规则消费 hook-guard-rules.toml）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { jsonGet, readHookInput, tryResolveMagicDir } from "../governance/common.js"
+import { PreToolUseGuard } from "../governance/pre-tool-guard.js"
+
+const input = readHookInput()
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+// 探测 MAGIC_DIR（唯一解析链：注入优先 → 物理位置推导）
+let MAGIC_DIR = process.env.MAGIC_DIR
+if (!MAGIC_DIR) {
+  MAGIC_DIR = tryResolveMagicDir() || ".qoder"
+}
+
+const guard = new PreToolUseGuard(PROJECT_DIR, MAGIC_DIR)
+
+const toolName = jsonGet(input, "tool_name")
+const command = jsonGet(input, "command")
+
+let exitCode = 0
+if (command !== "") {
+  exitCode = guard.runSectionA(input)
+  if (exitCode !== 0) process.exit(exitCode)
+} else {
+  exitCode = guard.runSectionB(input, toolName)
+  if (exitCode !== 0) process.exit(exitCode)
+}
+process.exit(0)

package/templates/core/hooks/prompt-submit.ts

@@ -0,0 +1,11 @@
+// prompt-submit.ts — UserPromptSubmit 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/prompt-router.ts（PromptRouter L1/L2/L3 分流，日报阈值消费 hook-event-rules.toml）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { readHookInput } from "../governance/common.js"
+import { PromptRouter } from "../governance/prompt-router.js"
+
+const input = readHookInput()
+const MAGIC_DIR = process.env.MAGIC_DIR || ".qoder"
+
+process.exit(new PromptRouter(MAGIC_DIR).run(input))

package/templates/core/hooks/review-checklist.ts

@@ -0,0 +1,4 @@
+// review-checklist.ts — Review 检查清单校验（bash 版 review-checklist.sh 的 TS 同语义实现）
+
+process.stdout.write("[ADD ReviewChecklist] 请在提交前确认 checklist.md 全部项已勾选。\n")
+process.exit(0)

package/templates/core/hooks/session-end.ts

@@ -0,0 +1,10 @@
+// session-end.ts — SessionEnd 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/session-end.ts（SessionEndGuard 清理 + 结算 + 兜底）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { SessionEndGuard } from "../governance/session-end.js"
+
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+process.env.PROJECT_DIR = PROJECT_DIR
+
+process.exit(new SessionEndGuard(PROJECT_DIR).run())

package/templates/core/hooks/session-start.ts

@@ -0,0 +1,9 @@
+// session-start.ts — SessionStart 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/session-start-guard.ts（SessionStartGuard 状态恢复 + 模板索引 + 代办 + HITL）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { SessionStartGuard } from "../governance/session-start-guard.js"
+
+const PROJECT_DIR = process.env.PROJECT_DIR || process.cwd()
+
+process.exit(new SessionStartGuard(PROJECT_DIR).run())

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

@@ -0,0 +1,14 @@
+// stop-check.ts — Stop 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/stop-router.ts（StopRouter 四象限分流，象限文本消费 hook-context-rules.toml）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { tryResolveMagicDir } from "../governance/common.js"
+import { StopRouter } from "../governance/stop-router.js"
+
+// 对齐 bash: MAGIC_DIR 从物理位置推导并 export（入口注入优先）
+const inferredMagicDir = tryResolveMagicDir()
+if (inferredMagicDir && !process.env.MAGIC_DIR) {
+  process.env.MAGIC_DIR = inferredMagicDir
+}
+
+process.exit(new StopRouter().run())

package/templates/core/hooks/subagent-guard.ts

@@ -0,0 +1,8 @@
+// subagent-guard.ts — SubagentStart 入口薄壳（Task 3.1 能力对齐）
+// 治理逻辑: governance/subagent-guard-router.js（SubagentGuardRouter 状态注入——对齐强版语义）
+// 能力对齐注: 原 core 为弱版（事件提示空话），已对齐 claude/vscode/qoder 强版（状态注入）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { SubagentGuardRouter } from "../governance/subagent-guard-router.js"
+
+process.exit(new SubagentGuardRouter().run())

package/templates/core/hooks/subagent-stop.ts

@@ -0,0 +1,9 @@
+// subagent-stop.ts — SubagentStop 入口薄壳（Task 2.2 薄壳化）
+// 治理逻辑: lib/subagent-stop-router.ts（SubagentStopRouter 边界校验 + 审计聚合）
+// 入口职责: 仅解析 + 进程语义（<50 行），治理 0 复制。
+
+import { readHookInput } from "../governance/common.js"
+import { SubagentStopRouter } from "../governance/subagent-stop-router.js"
+
+const input = readHookInput()
+process.exit(new SubagentStopRouter().run(input))

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