add-coder 0.3.33 → 0.3.35

package/templates/core/governance/doc-format-guard.ts

@@ -11,22 +11,8 @@ import { spawnSync } from "node:child_process"
 import { detectActiveAdd, localIsoSeconds } from "./common.js"
 import { writeHookEvent } from "./notify.js"
 import { doc } from "./rules.js"
-
-interface SchemaSection {
-  id?: string
-  heading?: string
-  required?: boolean
-  anchor?: string
-  within?: string
-  subsections?: Array<{ heading?: string }>
-}
-
-interface SchemaFile {
-  sections: SchemaSection[]
-  placeholders?: string[]
-  forbidden_terms?: string[]
-  groupColumn?: number | string
-}
+// 校验逻辑真源：core 校验层（Plan core-validation-lifecycle 轮 3——守卫不再内联实现）
+import { validateAgainstSchema, type SchemaFile } from "../validation/schema-validator.js"
 
 /** token 规则条目（rules.doc.token_rules 结构） */
 interface TokenRule {
@@ -161,104 +147,35 @@ export class DocFormatGuard {
 
   /** 章节/锚定/占位符/禁词校验，返回 struct 统计 */
   private runSchemaChecks(schema: SchemaFile, templateName: string, content: string, isSearchReplace: boolean): { applied: number; missed: number; anchorHit: boolean } {
-    const templatesDir = join(this.projectDir, this.magicDir, "templates")
-    let applied = 0
-    let missed = 0
-    let anchorHit = true
-
-    const headings = schema.sections.filter((s) => s.heading).map((s) => s.heading as string)
-    const requiredHeadings = schema.sections.filter((s) => s.required === true && s.heading).map((s) => s.heading as string)
-    const subs = schema.sections.flatMap((s) => s.subsections ?? []).filter((s) => s.heading).map((s) => s.heading as string)
-    const placeholders = schema.placeholders ?? []
-    const terms = schema.forbidden_terms ?? []
-
-    if (!isSearchReplace) {
-      // 锚定校验
-      for (const section of schema.sections) {
-        if (!section.anchor) continue
-        applied++
-        const templateContent = existsSync(join(templatesDir, templateName))
-          ? readFileSync(join(templatesDir, templateName), "utf-8")
-          : ""
-        const refLine = templateContent.split("\n").find((l) => l.includes(section.anchor as string))
-        if (!refLine) {
-          process.stderr.write(`[doc-format-guard] anchor_miss: schema ${section.id} 声明的 anchor '${section.anchor}' 在 ${templateName} 中未定位，跳过该规则（冒烟巡检兑底）\n`)
-          applied--
-          continue
-        }
-        const tokens = [...new Set(refLine.replace(/[#*`|(){]/g, " ").split(/\s+/).filter((t) => t !== "" && !t.includes("{")))]
-        if (tokens.length === 0) {
-          applied--
-          continue
-        }
-        let scope = content
-        if (section.within) {
-          if (content.includes(section.within)) {
-            const startIdx = content.indexOf(section.within)
-            const endIdx = content.indexOf("\n## ", startIdx + 1)
-            scope = content.slice(startIdx, endIdx === -1 ? undefined : endIdx)
-          } else {
-            process.stderr.write(`[doc-format-guard] within_miss: schema ${section.id} 的 within '${section.within}' 在文档中未定位，跳过该规则\n`)
-            applied--
-            continue
-          }
-        }
-        const missTokens = tokens.filter((tok) => !scope.includes(tok))
-        if (missTokens.length > 0) {
-          this.issues.push(`  缺锚点(${section.id}): ${missTokens.join(" ")}`)
-          missed++
-          anchorHit = false
-        }
-      }
-
-      // 必选章节
-      for (const heading of requiredHeadings) {
-        applied++
-        if (!content.includes(heading)) {
-          this.issues.push(`  缺章节: ${heading}`)
-          missed++
-        }
-      }
-      // 子章节
-      for (const sub of subs) {
-        applied++
-        if (!content.includes(sub)) {
-          this.issues.push(`  缺子章节: ${sub}`)
-          missed++
-        }
-      }
-    }
-
-    // 占位符
-    for (const ph of placeholders) {
-      if (content.includes(ph)) {
-        this.issues.push(`  未替换占位符: ${ph}`)
-        missed++
-      }
-    }
-
-    // 结构位禁词（标题行 + groupColumn）
-    let structText = (content.match(/^#{2,}\s.*$/gm) ?? []).join("\n")
-    const col = typeof schema.groupColumn === "number" ? schema.groupColumn : Number(schema.groupColumn)
-    if (!Number.isNaN(col) && col > 0) {
-      const colLines = content
-        .split("\n")
-        .map((l) => {
-          const cells = l.split("|")
-          return cells.length > col ? (cells[col + 1] ?? "").trim() : ""
-        })
-        .filter(Boolean)
-      structText += "\n" + colLines.join("\n")
-    }
-    for (const term of terms) {
-      applied++
-      if (structText.includes(term)) {
-        this.issues.push(`  结构位禁词: ${term}`)
-        missed++
-      }
+    // ★ 校验真源 = core 校验层（Plan core-validation-lifecycle 轮 3：删除内联实现）
+    //   SearchReplace 只传 patch → 标题/锚定类规则不适用，仅保留占位符与结构位禁词
+    const templatePath = join(this.projectDir, this.magicDir, "templates", templateName)
+    const templateContent = existsSync(templatePath) ? readFileSync(templatePath, "utf-8") : ""
+    const all = validateAgainstSchema(content, schema, { templateContent })
+    const relevant = isSearchReplace
+      ? all.filter((i) => i.code === "PLACEHOLDER_LEFT" || i.code === "FORBIDDEN_TERM")
+      : all
+
+    for (const i of relevant) this.issues.push(`  ${i.detail}`)
+
+    const missed = relevant.length
+    const declared = this.countDeclaredRules(schema, isSearchReplace)
+    return {
+      applied: Math.max(missed, declared),
+      missed,
+      anchorHit: !relevant.some((i) => i.code === "ANCHOR_MISS"),
     }
+  }
 
-    return { applied, missed, anchorHit }
+  /** 已声明规则数（用于 struct_score 分母；口径与原内联实现一致：按规则条数计） */
+  private countDeclaredRules(schema: SchemaFile, isSearchReplace: boolean): number {
+    const placeholders = (schema.placeholders ?? []).length
+    const terms = (schema.forbidden_terms ?? []).length
+    if (isSearchReplace) return placeholders + terms
+    const anchors = schema.sections.filter((s) => s.anchor).length
+    const required = schema.sections.filter((s) => s.required === true && s.heading).length
+    const subs = schema.sections.flatMap((s) => s.subsections ?? []).filter((s) => s.heading).length
+    return anchors + required + subs + placeholders + terms
   }
 
   /** 算法化规则校验（真源: [doc.anti_cheat] + HITL 表非空 + handoff 冲突）

package/templates/core/governance/post-tool-router.ts

@@ -3,10 +3,12 @@
 //
 // 设计范式: OOP 路由类（§1 DPS 哨兵自动化 / §2 Edit·Write 守卫 / §3 Bash 增强）。
 
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, readdirSync, appendFileSync, writeFileSync } from "node:fs"
 import { join, basename, dirname } from "node:path"
 import { jsonGet } from "./common.js"
 import { AuditBridge } from "./audit-bridge.js"
+import { evidenceEnabled, EVIDENCE_QUEUE_FILE, MEMORY_DIR_NAME, recallMode } from "../scripts/mcp-server/shared/memory/switches.js"
+import { buildEvidenceEvent, classifyEvidenceSource } from "../scripts/mcp-server/shared/memory/jobs/evidence-collector.js"
 
 /** 纯函数：从 input 中提取 output/content 拼接文本（对齐 bash grep -o 组合） */
 function extractOutputText(raw: string): string {
@@ -165,6 +167,9 @@ export class PostToolRouter {
 
       // §2f: 审计桥接（Task 8.1，ADD-7 自动化）——文件写入事件 → jsonl → MCP 常驻消费落库
       this.emitWriteEvent(filePath)
+
+      // §2g: Memory 采证入队（白名单 → evidence-queue.jsonl → consolidation 异步落库）
+      this.emitMemoryEvidence(filePath)
     } else if (toolName === "Bash") {
       // ═══════════════ §3: Bash matcher: 结果增强（扩展点: codex 文本）═══════════════
       this.emitLine(this.emitBashDone())
@@ -200,6 +205,33 @@ export class PostToolRouter {
     this.auditBridge.emit(filePath)
   }
 
+  /**
+   * §2g Memory 采证入队（Spec §10 PostToolUse 白名单，扩展点）:
+   *   白名单路径（plans/specs/reviews/handoff）→ 追加 evidence-queue.jsonl（幂等 dedupKey），
+   *   由 consolidation job 异步落库。ADD_MEMORY_EVIDENCE=off 或 RECALL_MODE=off 时关闭。
+   *   fail-open：任何异常不阻断文件写入主路径（Plan §9.3）。
+   */
+  protected emitMemoryEvidence(filePath: string): void {
+    try {
+      if (!evidenceEnabled() || recallMode() === "off") return
+      if (!classifyEvidenceSource(filePath)) return
+      if (!this.magicDir) return
+      let excerpt = ""
+      try {
+        excerpt = readFileSync(filePath, "utf-8").slice(0, 500)
+      } catch {
+        excerpt = basename(filePath)
+      }
+      const ev = buildEvidenceEvent(filePath, excerpt)
+      const dir = join(this.projectDir, this.magicDir, MEMORY_DIR_NAME)
+      mkdirSync(dir, { recursive: true })
+      appendFileSync(join(dir, EVIDENCE_QUEUE_FILE), JSON.stringify(ev) + "\n", "utf-8")
+      this.emitLine(`[ADD PostToolUse] 🧠 记忆采证入队: ${filePath}（consolidation 时落库）\n`)
+    } catch {
+      /* fail-open */
+    }
+  }
+
   /** §3 Bash 增强（core: lint/tsc；codex 子类: lint/typecheck/test） */
   protected emitBashDone(): string {
     return "[ADD PostToolUse] 命令执行完成。如有 lint/tsc 错误请修复。\n"

package/templates/core/governance/prompt-router.ts

@@ -17,6 +17,14 @@ import {
 import { loadDevKeywords, matchTrigger } from "./vocabulary.js"
 import { writeHookEvent } from "./notify.js"
 import { event } from "./rules.js"
+import { recallMode } from "../scripts/mcp-server/shared/memory/switches.js"
+import {
+  buildStageRecallHint,
+  detectRecallStage,
+} from "../scripts/mcp-server/shared/memory/metrics/stage-words.js"
+
+/** 显式记忆回忆意图触发词（Plan §9.1：对话触发词仅作补充入口；vocabulary 文档类别 G 同步维护） */
+const MEMORY_RECALL_HINT_RE = /之前|上次|还记得|记得吗|为什么当时|类似问题|历史决策|以前的方案|曾经怎么/i
 
 /**
  * UserPromptSubmit 触发词路由基类（模板方法）:
@@ -108,6 +116,41 @@ export class PromptRouter {
     // core 协议: 无前置注入
   }
 
+  /**
+   * 显式记忆回忆提示（Spec §10 / Plan §9.1 补充入口）:
+   * 命中回忆词且 ADD_MEMORY_RECALL_MODE != off → 提示调用 recall_memory。
+   * 不做自动召回（同步 Hook ≤200ms 无 DB）；shadow 模式下提示语明示"仅显式调用"。
+   */
+  protected maybeMemoryHint(prompt: string): void {
+    try {
+      if (recallMode() === "off") return
+      if (!MEMORY_RECALL_HINT_RE.test(prompt)) return
+      const mode = recallMode()
+      const suffix = mode === "shadow" ? "（当前 shadow 模式：召回将落审计，Hook 不自动注入）" : ""
+      process.stdout.write(
+        `[Memory] 检测到历史回忆意图${suffix}。可调用 recall_memory({ query: <你的问题>, stage: "prompt" }) 获取受治理的记忆上下文（含来源与评分）。\n`
+      )
+    } catch {
+      /* fail-open */
+    }
+  }
+
+  /**
+   * 阶段确定性召回提示（Spec §2 §DeterministicRecall，Plan §3.1 方案 B1 的 Hook 侧）:
+   * 命中 ADD 阶段词 → 提示到工具侧做确定性召回（plan-start/spec-start/dps/rahs/handoff）。
+   * Hook 同步路径无 DB：只输出提示文本，不召回、不写审计；任何异常 fail-open。
+   */
+  protected maybeStageHint(prompt: string): void {
+    try {
+      const stage = detectRecallStage(prompt)
+      if (!stage) return
+      const hint = buildStageRecallHint(stage, recallMode())
+      if (hint) process.stdout.write(hint)
+    } catch {
+      /* fail-open */
+    }
+  }
+
   /** Layer 3 输出形态（core: 纯文本逐行；qoder: hookSpecificOutput JSON 包） */
   protected layer3Json(): boolean {
     return false
@@ -148,6 +191,10 @@ export class PromptRouter {
       return 0
     }
 
+    // ─── Layer 1.5: 显式记忆回忆意图（补充入口；不替代确定性召回，见 Plan §9.1）───
+    this.maybeMemoryHint(prompt)
+    this.maybeStageHint(prompt)
+
     // ─── 开发关键词检测（动态加载） ───
     const devKw = loadDevKeywords()
     if (devKw.length === 0) return 0

package/templates/core/governance/session-start-guard.ts

@@ -3,10 +3,12 @@
 //
 // 设计范式: OOP 守卫类（状态恢复/模板索引/代办/HITL 四职责聚合）。
 
-import { existsSync, readdirSync, statSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
 import { join } from "node:path"
 import { detectActiveAdd, tryResolveMagicDir } from "./common.js"
 import { PreloadTemplates } from "./preload-templates.js"
+import { L1_SNAPSHOT_FILE, L1_SNAPSHOT_TTL_MS, MEMORY_DIR_NAME, memoryMaxTokens, recallMode } from "../scripts/mcp-server/shared/memory/switches.js"
+import { estimateTokens } from "../scripts/mcp-server/shared/memory/retrieval/context-builder.js"
 
 /**
  * SessionStart 守卫（① 状态恢复 → ② 模板索引 → ③ 代办 → ④ HITL 待审批检测）:
@@ -41,6 +43,9 @@ export class SessionStartGuard {
     // ── ④ §HITL 待审批检测（扩展点: adapter 可 override 关闭）──
     this.emitHitlPending()
 
+    // ── ⑤ Memory L1 快照注入（Spec §10；fail-open，读预计算快照，无 DB）──
+    this.emitMemoryL1()
+
     return 0
   }
 
@@ -96,4 +101,46 @@ export class SessionStartGuard {
       }
     }
   }
+
+  /**
+   * ⑤ Memory L1 快照注入（ADD_MEMORY_RECALL_MODE 三态）:
+   *   off    → 不输出
+   *   shadow → 仅提示快照存在（召回可执行并落审计，但不注入上下文）
+   *   inject → 读预计算快照注入（新鲜度 ≤7 天，token 预算截断，带来源边界标签）
+   * 同步 Hook ≤200ms 约束：只读文件，任何异常 fail-open 静默跳过。
+   */
+  protected emitMemoryL1(): void {
+    try {
+      const mode = recallMode()
+      if (mode === "off" || !this.magicDir) return
+      const file = join(this.projectDir, this.magicDir, MEMORY_DIR_NAME, L1_SNAPSHOT_FILE)
+      if (!existsSync(file)) return
+      if (mode === "shadow") {
+        process.stdout.write(`[Memory] L1 快照已生成（shadow 模式未注入）。需要时调用 recall_memory 显式召回: ${file}\n`)
+        return
+      }
+      // inject：过期快照不注入
+      if (Date.now() - statSync(file).mtimeMs > L1_SNAPSHOT_TTL_MS) return
+      const text = readFileSync(file, "utf-8")
+      const budget = memoryMaxTokens()
+      if (estimateTokens(text) <= budget) {
+        process.stdout.write(text)
+        return
+      }
+      // 超预算：按行截断，不静默吞掉——追加显式截断标记
+      const lines = text.split("\n")
+      const kept: string[] = []
+      let used = 0
+      for (const line of lines) {
+        const t = estimateTokens(line)
+        if (used + t > budget) break
+        kept.push(line)
+        used += t
+      }
+      kept.push(`[Memory L1] ⚠️ 超出预算 ${budget} tokens，已截断（完整快照: ${file}）`)
+      process.stdout.write(kept.join("\n") + "\n")
+    } catch {
+      /* fail-open：记忆子系统故障不阻断 session-start（Plan §9.3） */
+    }
+  }
 }

package/templates/core/prisma/add.prisma

@@ -216,3 +216,206 @@ model CollaborationPlanBinding {
   @@unique([contractId, projectKey, adapterKey, planName])
   @@index([projectKey, adapterKey, planName])
 }
+
+// ===== Agent Memory 知识治理层（Plan: add-coder-agent-memory-plan-v2） =====
+// 数据约束（Plan §4.4）：
+// - ACTIVE 必须至少关联一条 Evidence；approve 时 approvedBy/approvedAt 必填
+// - SUPERSEDED 必须设置 supersededById，且新旧 repository/scope 兼容
+// - validUntil <= now() 不得进入默认召回；HYPOTHESIS 不得作为 Gate 强约束
+// - importance/confidence ∈ [0,1]；contentHash = sha256(规范化文本)，幂等含 repository+scope
+// - ORGANIZATION scope 首版禁用（枚举保留，写入拒绝，§17-7 定案）
+
+enum MemoryKind {
+  DECISION
+  CONSTRAINT
+  PITFALL
+  FAILURE
+  LESSON
+  PATTERN
+  CONVENTION
+  FACT
+  HANDOFF_DIGEST
+  HYPOTHESIS
+}
+
+enum MemoryStatus {
+  CANDIDATE
+  PENDING
+  ACTIVE
+  STALE
+  SUPERSEDED
+  REJECTED
+  ARCHIVED
+}
+
+enum MemoryScopeType {
+  ORGANIZATION
+  REPOSITORY
+  BRANCH
+  MODULE
+  PATH
+  SYMBOL
+  PLAN
+  SPEC
+}
+
+enum MemorySourceType {
+  PLAN
+  SPEC
+  DPS_GATE
+  DEV_OPERATION
+  RAHS_GATE
+  HANDOFF
+  MANUAL
+  IMPORT
+}
+
+enum EmbeddingState {
+  DISABLED
+  PENDING
+  READY
+  FAILED
+  STALE
+}
+
+enum RecallOutcome {
+  UNKNOWN
+  USED
+  USEFUL
+  IRRELEVANT
+  OUTDATED
+  CONTRADICTED
+  HARMFUL
+}
+
+model AddMemory {
+  id              String          @id @default(cuid())
+  kind            MemoryKind
+  status          MemoryStatus    @default(CANDIDATE)
+  topic           String
+  content         String
+  summary         String?
+
+  scopeType       MemoryScopeType
+  scopeValue      String
+  repositoryRef   String
+
+  importance      Float           @default(0.5)
+  confidence      Float           @default(0.5)
+  validFrom       DateTime        @default(now())
+  validUntil      DateTime?
+
+  supersededById  String?
+  supersededBy    AddMemory?      @relation("MemorySupersession", fields: [supersededById], references: [id])
+  supersedes      AddMemory[]     @relation("MemorySupersession")
+
+  contentHash     String
+  embeddingModel  String?
+  embeddingDim    Int?
+  embeddingState  EmbeddingState  @default(DISABLED)
+
+  createdBy       String?
+  approvedBy      String?
+  approvedAt      DateTime?
+  metadata        Json?
+  createdAt       DateTime        @default(now())
+  updatedAt       DateTime        @updatedAt
+
+  evidenceLinks   AddMemoryEvidenceLink[]
+  recalls         AddMemoryRecallItem[]
+
+  @@index([repositoryRef, status, kind])
+  @@index([scopeType, scopeValue])
+  @@index([supersededById])
+  @@index([status, validUntil])
+  @@unique([repositoryRef, contentHash, scopeType, scopeValue])
+}
+
+model AddMemoryEvidence {
+  id            String           @id @default(cuid())
+  repositoryRef String
+  sourceType    MemorySourceType
+  sourceRef     String
+  planKeyword   String?
+  excerpt       String
+  contentHash   String
+  occurredAt    DateTime?
+  metadata      Json?
+  createdAt     DateTime         @default(now())
+
+  memoryLinks   AddMemoryEvidenceLink[]
+
+  @@index([repositoryRef, sourceType, sourceRef])
+  @@index([planKeyword])
+  @@unique([repositoryRef, sourceType, sourceRef, contentHash])
+}
+
+model AddMemoryEvidenceLink {
+  memoryId    String
+  evidenceId  String
+  relation    String?
+  createdAt   DateTime          @default(now())
+
+  memory      AddMemory         @relation(fields: [memoryId], references: [id])
+  evidence    AddMemoryEvidence @relation(fields: [evidenceId], references: [id])
+
+  @@id([memoryId, evidenceId])
+}
+
+// sourceRef 约定：必须包含当次运行标识（格式 {gate}:{planKeyword}:{runId}），
+// 同一 Gate 对同一来源的重复测量由 runId 区分（Review P1 #2 回流）
+model AddMetricSnapshot {
+  id            String   @id @default(cuid())
+  repositoryRef String
+  metricType    String
+  value         Float
+  baseline      Float?
+  delta         Float?
+  unit          String?
+  planKeyword   String?
+  specRef       String?
+  commitSha     String?
+  sourceRef     String
+  metadata      Json?
+  measuredAt    DateTime @default(now())
+
+  @@index([repositoryRef, metricType, measuredAt])
+  @@unique([repositoryRef, metricType, sourceRef])
+}
+
+model AddMemoryRecall {
+  id               String          @id @default(cuid())
+  repositoryRef    String
+  query            String
+  stage            String
+  consumerRef      String?
+  scopeContext     Json
+  candidateIds     Json
+  selectedIds      Json
+  scoreBreakdown   Json
+  exclusionReasons Json?
+  rankingVersion   String
+  tokenBudget      Int
+  injectedTokens   Int
+  latencyMs        Int?
+  degradedMode     String?
+  createdAt        DateTime        @default(now())
+  items            AddMemoryRecallItem[]
+
+  @@index([repositoryRef, stage, createdAt])
+}
+
+model AddMemoryRecallItem {
+  recallId   String
+  memoryId   String
+  selected   Boolean
+  rank       Int?
+  outcome    RecallOutcome @default(UNKNOWN)
+  feedback   String?
+  updatedAt  DateTime      @updatedAt
+
+  recall     AddMemoryRecall @relation(fields: [recallId], references: [id])
+  memory     AddMemory       @relation(fields: [memoryId], references: [id])
+
+  @@id([recallId, memoryId])
+}

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

@@ -123,14 +123,54 @@ build_target() {
     [ -n "$tables" ] && EXCLUDE_ARGS=(--exclude "$tables")
     echo ">>> Atlas 同步（共库模式: 仅 ADD 治理表，其余 $(echo "$tables" | tr ',' '\n' | wc -l) 张表排除）..."
   fi
+  # Atlas 自身的版本记录 schema 不属于期望态，必须排除，否则 diff 会生成 DROP SCHEMA ... CASCADE
+  EXCLUDE_ARGS+=(--exclude atlas_schema_revisions)
   TARGET_URL="${TARGET_URL}?sslmode=disable"
 }
 
-# ④ baseline 生成（同源：Prisma schema SQL，过滤 Prisma 7 ◇ 提示）
+# ③.5 raw 对象登记（schema 表达不了的对象：trgm 索引 / 向量层；单一事实源）
+#   期望态必须能表达这些对象，否则 diff 把「raw 对象」判成多余并生成 DROP（review 发现 #2）。
+#   约束：Atlas dev-url 必须是干净库且具备同名扩展（否则 gin_trgm_ops / vector 类型无法解析）；
+#   本项目的 dev 库是一次性沙箱 → 每次 diff 前从 template1 重建（见 prepare_atlas_dev_db）。
+RAW_OBJECTS_SQL="prisma/raw-objects.sql"
+RAW_OBJECTS_VECTOR_SQL="prisma/raw-objects-vector.sql"
+
+# dev 沙箱库准备：DROP + CREATE TEMPLATE template1（template1 内已装 pg_trgm/vector）
+prepare_atlas_dev_db() {
+  local c="${PROJECT_NAME:-add-project}-dev" u="${ATLAS_DEV_USER:-admin}" d="${ATLAS_DEV_DB:-add-project-dev}"
+  podman exec "$c" true >/dev/null 2>&1 || { echo ">>> [dev-url] 容器 $c 不可达，跳过重建（依赖现有 dev 库）"; return 0; }
+  if [ "${ADD_DB_KEEP_DEV:-}" = "yes" ]; then
+    echo ">>> [dev-url] ADD_DB_KEEP_DEV=yes：沿用现有 dev 库"
+    return 0
+  fi
+  podman exec "$c" psql -U "$u" -d postgres -tAc "DROP DATABASE IF EXISTS \"$d\";" >/dev/null 2>&1 || true
+  if podman exec "$c" psql -U "$u" -d postgres -tAc "CREATE DATABASE \"$d\" TEMPLATE template1;" >/dev/null 2>&1; then
+    echo ">>> [dev-url] 已从 template1 重建沙箱库 $d（干净 + 扩展齐备）"
+  else
+    echo ">>> [dev-url] 重建 $d 失败，沿用现有库（若解析报错请检查 template1 扩展）"
+  fi
+}
+
+# 目标库是否具备 pgvector（决定是否把向量段并入期望态）
+has_pgvector_in_target() {
+  local c="${PROJECT_NAME:-add-project}-postgres" u="${DATABASE_USER:-admin}" d="${PROJECT_NAME:-add-project}" has
+  has="$(podman exec "$c" psql -U "$u" -d "$d" -tAc "SELECT 1 FROM pg_available_extensions WHERE name='vector' LIMIT 1;" 2>/dev/null || true)"
+  [ "$has" = "1" ]
+}
+
+# ④ baseline 生成（同源：Prisma schema SQL + raw 对象登记段，过滤 Prisma 7 ◇ 提示）
 generate_baseline() {
   BASELINE_SQL="$(mktemp /tmp/atlas-target.XXXXXX.sql)"
   trap 'rm -f "$BASELINE_SQL"' EXIT
   npx prisma migrate diff --from-empty --to-schema "$SCHEMA_TARGET" --script 2>/dev/null | sed '/^◇/d' > "$BASELINE_SQL"
+  if [ -f "$RAW_OBJECTS_SQL" ]; then
+    printf '\n-- ===== raw objects registry =====\n' >> "$BASELINE_SQL"
+    cat "$RAW_OBJECTS_SQL" >> "$BASELINE_SQL"
+  fi
+  if has_pgvector_in_target && [ -f "$RAW_OBJECTS_VECTOR_SQL" ]; then
+    printf '\n-- ===== raw objects registry (vector) =====\n' >> "$BASELINE_SQL"
+    cat "$RAW_OBJECTS_VECTOR_SQL" >> "$BASELINE_SQL"
+  fi
 }
 
 # ⑤ diff 检测（SQL 语句特征判定：Atlas 无变更时输出 "Schemas are synced..." 非空，不算变更）
@@ -140,10 +180,28 @@ run_atlas_diff() {
   echo "$DIFF_SQL" | grep -qE "^(CREATE|ALTER|DROP|COMMENT|-- *(Create|Modify|Drop))"
 }
 
-# ⑥ apply（确认门槛：交互输出 SQL → 确认 → apply；拒绝则跳过）
+# ⑥ apply（双门槛：DROP 守卫 → 交互确认 → apply；任一不通过则跳过）
+#   DROP 守卫（Plan 轮 3 前置 / runtime review 发现 #2）：破坏性语句一律拒绝——
+#   raw SQL 对象（如 pg_trgm GIN 索引、pgvector 列/索引）无法被 Prisma schema 表达，
+#   diff 会误判为「多余对象」并生成 DROP；若放行，索引会被静默删除且不报错。
+#   显式放行需人工设 ADD_DB_ALLOW_DROP=yes，并在迁移评审中登记（禁止默认自动放行）。
 apply_atlas_diff() {
   echo "=== 待应用 diff SQL（前 60 行）==="
   echo "$DIFF_SQL" | head -60
+  local drops
+  drops="$(printf '%s\n' "$DIFF_SQL" | grep -nE '^DROP |DROP COLUMN|DROP CONSTRAINT|DROP INDEX|DROP TABLE|DROP TYPE|DROP SCHEMA' || true)"
+  if [ -n "$drops" ]; then
+    echo "!!! 检测到破坏性语句（DROP），已拒绝应用："
+    printf '%s\n' "$drops" | sed 's/^/    /'
+    echo "    处置建议："
+    echo "      ① 若是无法被 schema 表达的 raw SQL 对象（索引/扩展/向量列）→ 核对登记清单 prisma/raw-objects.sql、prisma/raw-objects-vector.sql；"
+    echo "      ② 确需删除时人工执行，并在迁移评审中登记（能力矩阵 §六 已登记同类缺口）。"
+    if [ "${ADD_DB_ALLOW_DROP:-}" != "yes" ]; then
+      echo "    （如需在评审后放行：ADD_DB_ALLOW_DROP=yes 重新执行）"
+      return 1
+    fi
+    echo "    ⚠️ ADD_DB_ALLOW_DROP=yes 已设置：放行破坏性变更（确认已完成迁移评审）"
+  fi
   read -rp "应用以上 schema 变更？[y/N] " ANS
   if [ "$ANS" = "y" ] || [ "$ANS" = "yes" ]; then
     atlas_cmd schema apply --url "$TARGET_URL" --to "file://$BASELINE_SQL" --dev-url "$ATLAS_DEV_URL" "${EXCLUDE_ARGS[@]}"
@@ -173,6 +231,7 @@ atlas_sync() {
     echo "!!! ATLAS_DEV_URL 未配置。请运行 add-coder init（分库引导自动创建 {project}-add-dev 常驻容器并登记）或手动配置"
     return 1
   fi
+  prepare_atlas_dev_db
   build_target
   generate_baseline
   if run_atlas_diff; then