@chenmk/superflow 0.5.16 → 0.5.18

package/README.md

@@ -31,6 +31,24 @@
 SuperBridge Flow is a workflow CLI for bringing OpenSpec/SDD and Superpowers
 together in real software delivery.
 
+## 0.5.18 database layers and Git gate closure
+
+- Preserve Mock logic tests while freezing separate SQL-binding, real database and HTTP-entry obligations. Required MySQL proof cannot be replaced with Mock/H2/SQLite.
+- Bind receipts to engine/version, schema, production statement and actual row observations. Retain historical evidence for its verified revision.
+- Delegate exact known legacy sdd entries to current canonical scripts after backup. Preserve unknown/custom entries and symlinks.
+- Audit effective Git Hook routes, executable state and current package content. Reject root report false PASS and tracked evidence/index mismatches, while keeping private untracked logs local.
+
+Run `superflow update --scope global --agent both`, then `superflow doctor <project>`. Unknown custom routes remain visible for owner review; filename/date is not proof of integration.
+
+## 0.5.17 acceptance evidence fixes
+
+- Per-case PASS binds retained receipts and raw output to the service entry and current source/build. Empty files, remote links, zero execution and substituted entries no longer pass.
+- Persisted fields freeze before/after values for the same business ID and expected assertions. Independent review still checks the actual Service-to-Mapper statement.
+- Keep partial results; only a complete final summary authorizes delivery. Lightweight documentation acquires no DB requirement.
+- CLI and Codex/Claude scripts use the same installation source. Repeated updates refresh version records and preserve custom state.
+
+Complete affected evidence for legacy reports. Hashes prove identity, not business correctness or authenticity.
+
 ## Why SuperBridge Flow
 
 Modern agentic coding often fails in the gap between a well-written spec and

package/README.zh-CN.md

@@ -47,6 +47,24 @@ CLI 会把 SuperBridge Flow 技能、配套 hook/command 脚本整合为单一 n
 - Claude Code：`~/.claude/skills/`、`~/.claude/scripts/`，并注册 `~/.claude/settings.json` hook
 - Codex：`~/.codex/skills/`、`~/.codex/hooks/`
 
+## 0.5.18 数据库分层与 Git 门禁接入
+
+- 保留 Mock 逻辑单测，分别冻结 SQL 生成/绑定、真实数据库、HTTP 入口义务；必测 MySQL 不能由 Mock/H2/SQLite 替代。
+- 凭证绑定引擎版本、schema、生产 statement 和实际行观测；历史证据按已验证源码版本保留。
+- 已确认旧 sdd 入口备份后委托当前规范脚本；未知/自定义入口和符号链接保留。
+- 核验实际 Git Hook 路由、执行权限及当前包内容；拒绝根级报告假 PASS 和 tracked 证据/index 错配，私有未跟踪日志仍可留本地。
+
+运行 `superflow update --scope global --agent both` 后，用 `superflow doctor <项目>` 核对实际接入。未知自定义路由明确交给 owner 核验，不能只看文件名或日期。
+
+## 0.5.17 验收证据修复
+
+- 逐用例 PASS 绑定本地执行凭证、原始输出、具体服务入口及当前源码/构建；空文件、远端链接、零执行和入口替代不再通过。
+- 持久化字段需冻结同业务 ID 前后值与预期断言；独立评审继续核对实际 Service→Mapper statement。
+- 局部结果保留 PARTIAL，最终完整汇总才可交付；轻量文档不追加数据库要求。
+- CLI、Codex/Claude 脚本使用同一安装来源，重复更新刷新版本记录并保留自定义状态。
+
+旧报告缺执行凭证时补齐受影响证据；哈希只证明身份，不证明业务正确性或防伪。
+
 ## 亮点
 
 0.5.10 加强文档交付：逐需求×真实入口核对（含排除项）、真实入口验收合同、

package/assets/manifest.json

@@ -86,5 +86,34 @@
     "codex": [
       "codex-auto-backup-hook.sh"
     ]
+  },
+  "legacyScriptAliases": {
+    "sdd-delivery-check.sh": {
+      "target": "superflow-delivery-check.sh",
+      "knownHashes": [
+        "e536d7f745dc864efe28549831d2367a6e966f68cad299a7eaf1090794531a2f",
+        "8c44bb6f9f7f00590661663b94f75b879f5de88cdb85e22419b68dce9e308f77"
+      ]
+    },
+    "sdd-test-report-lint.py": {
+      "target": "superflow-test-report-lint.py",
+      "knownHashes": [
+        "34f1fa898042277c7ff78af71806346f8ffc208202b12a97ce5ca363ca0aeeaf"
+      ]
+    },
+    "sdd-verify-integration.sh": {
+      "target": "superflow-verify-integration.sh",
+      "knownHashes": [
+        "5ef4f28456aa7f722c7de4a59f8d82e9908433bbc5e90651eb65d1241bd1f1b5",
+        "b6520e2fe3e6980fdef8cbb0af5fb301a69a390593545137c38a8c5ea2a8c888"
+      ]
+    },
+    "sdd-sql-sync-hook.py": {
+      "target": "superflow-sql-sync-hook.py",
+      "knownHashes": [
+        "f12c036291a8048649d03aefd9be17fe9205d17d149d456ce9c8128b62dc96fb",
+        "d128efa960c86dc642d06cd454f5704eb8906c5628c4e2a92ba41278f92a8b5b"
+      ]
+    }
   }
 }

package/assets/scripts/install-sql-pre-commit.sh

@@ -1,44 +1,59 @@
 #!/bin/sh
-
-set -e
-
-REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
-if [ -z "$REPO_ROOT" ]; then
-    echo "当前目录不是 Git 仓库，无法安装 SQL pre-commit"
-    exit 1
+# Install the existing SQL and evidence gates; retain unknown/custom Git hooks.
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+case "$SCRIPT_DIR" in */.claude/scripts) AGENT=claude ;; *) AGENT=codex ;; esac
+if [ "$#" -gt 0 ]; then
+    [ "$#" -eq 2 ] && [ "$1" = "--agent" ] || {
+        echo "Usage: install-sql-pre-commit.sh [--agent codex|claude]" >&2
+        exit 2
+    }
+    AGENT="$2"
 fi
-
-HOOK_DIR="$REPO_ROOT/.git/hooks"
-HOOK_FILE="$HOOK_DIR/pre-commit"
-SQL_HOOK="$HOME/.codex/hooks/superflow-sql-sync-hook.py"
-
-mkdir -p "$HOOK_DIR"
-
-if [ -f "$HOOK_FILE" ] && ! grep -q "superflow-sql-sync-hook.py" "$HOOK_FILE"; then
-    BACKUP_FILE="$HOOK_FILE.backup.$(date +%Y%m%d%H%M%S)"
-    cp "$HOOK_FILE" "$BACKUP_FILE"
-    {
-        printf "\n"
-        printf "# SDD SQL style check\n"
-        printf "SQL_HOOK=\"\\$HOME/.codex/hooks/superflow-sql-sync-hook.py\"\n"
-        printf "if [ -x \"\\$SQL_HOOK\" ]; then\n"
-        printf "    \"\\$SQL_HOOK\" --check-staged\n"
-        printf "fi\n"
-    } >> "$HOOK_FILE"
-    chmod +x "$HOOK_FILE"
-    echo "已追加 SQL pre-commit，并备份原 hook: $BACKUP_FILE"
-    exit 0
+case "$AGENT" in codex) SUBDIR=hooks ;; claude) SUBDIR=scripts ;; *) exit 2 ;; esac
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo "Not a Git repository / 当前目录不是 Git 仓库" >&2
+    exit 2
+}
+HOOK_PATH=$(git -C "$REPO_ROOT" rev-parse --git-path hooks/pre-commit)
+case "$HOOK_PATH" in /*) HOOK_FILE="$HOOK_PATH" ;; *) HOOK_FILE="$REPO_ROOT/$HOOK_PATH" ;; esac
+if [ "$SCRIPT_DIR" = "$REPO_ROOT/.$AGENT/$SUBDIR" ]; then
+    SCRIPTS="$SCRIPT_DIR"
+    EXPRESSION='$(git rev-parse --show-toplevel)'"/.$AGENT/$SUBDIR"
+else
+    SCRIPTS="$HOME/.$AGENT/$SUBDIR"
+    EXPRESSION='$HOME'"/.$AGENT/$SUBDIR"
 fi
-
-cat > "$HOOK_FILE" <<'EOF'
+for name in superflow-sql-sync-hook.py superflow-delivery-check.sh superflow-test-report-lint.py; do
+    [ -x "$SCRIPTS/$name" ] || {
+        echo "Missing current gate: $name; run superflow update / 请先更新规范门禁" >&2
+        exit 2
+    }
+done
+[ ! -L "$HOOK_FILE" ] || { echo "Retain custom symlink / 保留自定义符号链接" >&2; exit 2; }
+mkdir -p "$(dirname "$HOOK_FILE")"
+TEMPORARY=$(mktemp "${HOOK_FILE}.superflow-XXXXXX")
+trap 'rm -f "$TEMPORARY"' EXIT HUP INT TERM
+cat > "$TEMPORARY" <<HOOK
 #!/bin/sh
-
-SQL_HOOK="$HOME/.codex/hooks/superflow-sql-sync-hook.py"
-
-if [ -x "$SQL_HOOK" ]; then
-    "$SQL_HOOK" --check-staged
+# Superflow managed Git evidence gate v1
+SCRIPTS="$EXPRESSION"
+for name in superflow-sql-sync-hook.py superflow-delivery-check.sh; do
+    [ -x "\$SCRIPTS/\$name" ] || { echo "Missing Superflow gate; run superflow update" >&2; exit 2; }
+    "\$SCRIPTS/\$name" --check-staged "\$(pwd)" || exit \$?
+done
+HOOK
+if [ -f "$HOOK_FILE" ]; then
+    if cmp -s "$HOOK_FILE" "$TEMPORARY"; then
+        chmod +x "$HOOK_FILE"
+        echo "Git gate already current / Git 门禁已接入"
+        exit 0
+    fi
+    echo "Existing custom/legacy pre-commit retained / 已保留现有自定义或旧 pre-commit" >&2
+    echo "Run superflow hook-audit for source diagnostics / 请先核对现有入口来源" >&2
+    exit 2
 fi
-EOF
-
-chmod +x "$HOOK_FILE"
-echo "已安装 SQL pre-commit: $HOOK_FILE"
+chmod +x "$TEMPORARY"
+mv "$TEMPORARY" "$HOOK_FILE"
+echo "Installed Git gate / 已安装 Git 门禁: $HOOK_FILE"

package/assets/scripts/superflow-delivery-check.sh

@@ -9,6 +9,10 @@
 
 set -u
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LINT="$SCRIPT_DIR/superflow-test-report-lint.py"
+INTEGRATION="$SCRIPT_DIR/superflow-verify-integration.sh"
+
 MODE="${1:-}"
 
 read_json_field() {
@@ -108,6 +112,18 @@ if [ "$SDD_ACTIVE" -eq 0 ] && [ -z "$SDD_DOCS_CHANGED" ]; then
 fi
 
 FAILED=0
+UNSTAGED="$(git -C "$REPO_ROOT" diff --name-only)"
+INDEX_MISMATCH=0
+while IFS= read -r staged_path; do
+  [ -n "$staged_path" ] || continue
+  if printf '%s\n' "$UNSTAGED" | grep -Fxq "$staged_path"; then
+    echo "FAIL [$staged_path] 工作树与 Git index 内容不同，证据不能证明待提交快照"
+    INDEX_MISMATCH=1
+  fi
+done <<STAGED_PATHS
+$ACTIVE_SDD_CHANGED
+STAGED_PATHS
+[ "$INDEX_MISMATCH" -eq 0 ] || exit 2
 
 fail() {
   echo "FAIL $1"
@@ -200,6 +216,24 @@ is_blocked_doc_freeze_report() {
     return 1
   fi
 
+  local final_result
+  final_result="$(python3 - "$LINT" "$file" <<'PYFINAL'
+import runpy, sys
+from pathlib import Path
+module = runpy.run_path(sys.argv[1])
+text = Path(sys.argv[2]).read_text()
+lines = text.splitlines()
+header = next((i for i, line in enumerate(lines) if module["CASE_EVIDENCE_HEADER"].fullmatch(line.strip())), None)
+active_pass = False
+if header is not None:
+    for line in lines[header + 2:]:
+        if not line.startswith("|"): break
+        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+        if len(cells) == 5 and cells[3].upper() == "PASS": active_pass = True
+print("CASE_PASS" if active_pass else module["final_report_result"](text))
+PYFINAL
+)" || return 1
+  case "$final_result" in PASS|CONFLICT|CASE_PASS) return 1 ;; esac
   grep -Eiq 'Blocked|阻塞' "$file" \
     && grep -Eiq 'SDD 文档|文档阶段|范围收口|范围冻结|任务冻结|不包含代码实现|没有 Java 实现变更|未进入实现|当前报告记录可交付边界' "$file"
 }
@@ -249,12 +283,12 @@ if [ -n "$P_DIRS" ]; then
         ok "[$rel_report] 已 staged"
         check_no_open_placeholders "$REPO_ROOT/$rel_report"
         check_has_closeout_status "$REPO_ROOT/$rel_report"
-        if [ -x "$HOME/.codex/hooks/superflow-test-report-lint.py" ]; then
-          lint_args=(--repo-root "$REPO_ROOT")
+        if [ -x "$LINT" ]; then
+          lint_args=(--repo-root "$REPO_ROOT" --git-index-root "$REPO_ROOT")
           if [ -f "$REPO_ROOT/$p_dir/tests.md" ]; then
             lint_args+=(--tests "$REPO_ROOT/$p_dir/tests.md")
           fi
-          "$HOME/.codex/hooks/superflow-test-report-lint.py" \
+          "$LINT" \
             "${lint_args[@]}" "$REPO_ROOT/$rel_report"
           if [ $? -ne 0 ]; then
             FAILED=1
@@ -283,18 +317,18 @@ fi
 VERIFY_REPORTS=$(printf '%s\n' "$REPORTS" | grep -E \
   '(^|/)embedded-changes/p[0-9][^/]*/test-report\.md$' || true)
 
-if [ -n "$VERIFY_REPORTS" ] && [ -x "$HOME/.codex/hooks/superflow-verify-integration.sh" ]; then
-  VERIFY_ARGS=""
+if [ -n "$VERIFY_REPORTS" ] && [ -x "$INTEGRATION" ]; then
+  VERIFY_ARGS=()
   for report in $VERIFY_REPORTS; do
     abs_report="$REPO_ROOT/$report"
     if is_blocked_doc_freeze_report "$abs_report" && [ -z "$CODE_RUNTIME_CHANGED" ]; then
       ok "[$report] 为 SDD 文档冻结 Blocked 报告，跳过真实集成验收脚本"
       continue
     fi
-    VERIFY_ARGS="$VERIFY_ARGS $abs_report"
+    VERIFY_ARGS+=("$abs_report")
   done
-  if [ -n "$VERIFY_ARGS" ]; then
-    "$HOME/.codex/hooks/superflow-verify-integration.sh" $VERIFY_ARGS
+  if [ "${#VERIFY_ARGS[@]}" -gt 0 ]; then
+    "$INTEGRATION" "${VERIFY_ARGS[@]}"
     if [ $? -ne 0 ]; then
       FAILED=1
     fi
@@ -304,14 +338,31 @@ fi
 ROOT_REPORTS=$(printf '%s\n' "$REPORTS" | grep -E \
   '(^|/)openspec/changes/[^/]+/test-report\.md$|(^|/)doc/openspec/changes/[^/]+/test-report\.md$' || true)
 
-if [ -n "$ROOT_REPORTS" ] && [ -x "$HOME/.codex/hooks/superflow-test-report-lint.py" ]; then
+# Evidence/contract-only commits still refer to their existing root report.
+AFFECTED_ROOT_DIRS=$(printf '%s\n' "$ACTIVE_SDD_CHANGED" | sed -nE   's#^((doc/)?openspec/changes/[^/]+)/.*#\1#p' | sort -u)
+for change_root in $AFFECTED_ROOT_DIRS; do
+  case "$change_root" in */archive) continue ;; esac
+  if [ -f "$REPO_ROOT/$change_root/test-report.md" ]; then
+    ROOT_REPORTS="$ROOT_REPORTS
+$change_root/test-report.md"
+  fi
+done
+ROOT_REPORTS=$(printf '%s\n' "$ROOT_REPORTS" | sed '/^$/d' | sort -u)
+
+if [ -n "$ROOT_REPORTS" ] && [ ! -x "$LINT" ]; then
+  fail "同安装目录缺少当前 report lint，请执行 superflow update"
+fi
+if [ -n "$ROOT_REPORTS" ] && [ -x "$LINT" ]; then
   for report in $ROOT_REPORTS; do
-    root_lint_args=(--warn-only --repo-root "$REPO_ROOT")
+    root_lint_args=(--repo-root "$REPO_ROOT" --git-index-root "$REPO_ROOT")
+    if [ -z "$CODE_RUNTIME_CHANGED" ] && [ ! -f "$REPO_ROOT/${report%/test-report.md}/.sdd/reviews/document-review.json" ] && is_blocked_doc_freeze_report "$REPO_ROOT/$report"; then
+      root_lint_args+=(--warn-only)
+    fi
     root_tests="${report%/test-report.md}/tests.md"
     if [ -f "$REPO_ROOT/$root_tests" ]; then
       root_lint_args+=(--tests "$REPO_ROOT/$root_tests")
     fi
-    "$HOME/.codex/hooks/superflow-test-report-lint.py" \
+    "$LINT" \
       "${root_lint_args[@]}" "$REPO_ROOT/$report"
     if [ $? -ne 0 ]; then
       FAILED=1

package/assets/scripts/superflow-integration-evidence-hook.sh

@@ -80,5 +80,5 @@ for report in $REPORTS; do
   REPORT_ARGS="$REPORT_ARGS $REPO_ROOT/$report"
 done
 
-"$HOME/.codex/hooks/superflow-verify-integration.sh" $REPORT_ARGS
+"$(dirname "${BASH_SOURCE[0]}")/superflow-verify-integration.sh" $REPORT_ARGS
 exit $?

package/assets/scripts/superflow-managed-executor-preflight.mjs

@@ -3,6 +3,7 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 const [projectArg = ".", taskId] = process.argv.slice(2);
 if (!taskId) {
@@ -102,6 +103,35 @@ if (changeDir) {
   }
   if (!fs.existsSync(reportFile))
     errors.push(`缺少 test-report.md: ${reportFile}`);
+  const stateFile = path.join(changeDir, ".sdd/state.yaml");
+  const reviewFile = path.join(changeDir, ".sdd/reviews/document-review.json");
+  const full =
+    fs.existsSync(stateFile) &&
+    /^workflow:\s*full\s*$/m.test(fs.readFileSync(stateFile, "utf8"));
+  if (full && !fs.existsSync(reviewFile))
+    errors.push("完整 SDD 缺少冻结入口评审凭证");
+  if (fs.existsSync(reviewFile)) {
+    try {
+      execFileSync(
+        "python3",
+        [
+          path.join(
+            path.dirname(fileURLToPath(import.meta.url)),
+            "superflow-test-report-lint.py",
+          ),
+          "--tests",
+          path.join(changeDir, "tests.md"),
+          "--review",
+          reviewFile,
+          "--require-complete",
+          reportFile,
+        ],
+        { encoding: "utf8", stdio: "pipe" },
+      );
+    } catch (error) {
+      errors.push(`逐用例执行凭证门禁失败: ${error.stdout ?? error.message}`);
+    }
+  }
 }
 
 if (errors.length > 0) {

package/assets/scripts/superflow-managed-work-check.mjs

@@ -2,6 +2,8 @@
 import crypto from "crypto";
 import fs from "fs";
 import path from "path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 const [projectArg = ".", taskId, mode] = process.argv.slice(2);
 const beforeReadyEvent = mode === "--before-ready-event";
@@ -328,6 +330,39 @@ function verifyOpenSpecTasksComplete(task, executor) {
   while (current.startsWith(projectRoot)) {
     const tasksFile = path.join(current, "tasks.md");
     if (fs.existsSync(tasksFile)) {
+      const reviewFile = path.join(
+        current,
+        ".sdd/reviews/document-review.json",
+      );
+      const stateFile = path.join(current, ".sdd/state.yaml");
+      const full =
+        fs.existsSync(stateFile) &&
+        /^workflow:\s*full\s*$/m.test(fs.readFileSync(stateFile, "utf8"));
+      if (full && !fs.existsSync(reviewFile))
+        fail("完整 SDD 缺少冻结入口评审凭证");
+      if (fs.existsSync(reviewFile)) {
+        try {
+          execFileSync(
+            "python3",
+            [
+              path.join(
+                path.dirname(fileURLToPath(import.meta.url)),
+                "superflow-test-report-lint.py",
+              ),
+              "--tests",
+              path.join(current, "tests.md"),
+              "--review",
+              reviewFile,
+              "--require-complete",
+              path.join(current, "test-report.md"),
+            ],
+            { encoding: "utf8", stdio: "pipe" },
+          );
+        } catch (error) {
+          fail(`逐用例执行凭证门禁失败: ${error.stdout ?? error.message}`);
+        }
+      }
+
       const tasks = fs
         .readFileSync(tasksFile, "utf8")
         .split(/\r?\n/)

package/assets/scripts/superflow-review-coverage.mjs

@@ -127,6 +127,32 @@ export function validateCoverage(root, review, issues, checkCode = true) {
       issues.push(`入口 ${entry.id} 缺少角色、实际路由或入口类型`);
     }
     refs(entry.sourceRefs, "code", `入口 ${entry.id}`);
+    const database = entry.database;
+    if (list(entry.persistence).length && !database)
+      issues.push(
+        `入口 ${entry.id} 持久化影响缺少数据库合同；旧证据保留 PARTIAL`,
+      );
+    if (database !== undefined) {
+      if (
+        !nonempty(database?.engine) ||
+        !Number.isInteger(database?.major) ||
+        database.major < 1
+      )
+        issues.push(`入口 ${entry.id} 缺少数据库 engine/major`);
+      refs(database?.schemaSourceRefs, null, `入口 ${entry.id} 数据库 schema`);
+      const statements = list(database?.statements);
+      if (
+        !statements.length ||
+        statements.some(
+          (item) =>
+            !nonempty(item?.id) || sources.get(item.sourceRef)?.role !== "code",
+        )
+      )
+        issues.push(`入口 ${entry.id} 缺少生产 SQL statement 与源码引用`);
+      const identities = statements.map((item) => JSON.stringify(item));
+      if (new Set(identities).size !== identities.length)
+        issues.push(`入口 ${entry.id} 生产 SQL statement 重复`);
+    }
   }
   for (const test of cases.values()) {
     const entry = entries.get(test.entryId);
@@ -138,6 +164,113 @@ export function validateCoverage(root, review, issues, checkCode = true) {
         issues.push(`用例 ${test.id} 缺少 ${key} 断言`);
     }
     refs(test.sourceRefs, "contract", `用例 ${test.id}`);
+    if (
+      test.evidenceKind !== undefined &&
+      !["real", "controlled-simulation", "unit"].includes(test.evidenceKind)
+    )
+      issues.push(`用例 ${test.id} 的 evidenceKind 无效`);
+
+    const layer = test.testLayer;
+    const realDatabase = ["database", "http-entry"].includes(layer);
+    if (
+      layer !== undefined &&
+      !["logic", "sql-binding", "database", "http-entry"].includes(layer)
+    )
+      issues.push(`用例 ${test.id} 的 testLayer 无效`);
+    if (realDatabase && entry?.database) {
+      if (test.evidenceKind !== "real")
+        issues.push(`用例 ${test.id} 数据库验证必须使用 real 证据`);
+      const boundary = test.mockBoundary;
+      if (
+        !boundary ||
+        !Array.isArray(boundary.allowed) ||
+        !Array.isArray(boundary.forbidden) ||
+        boundary.forbidden.length === 0 ||
+        [...boundary.allowed, ...boundary.forbidden].some(
+          (v) => !nonempty(v),
+        ) ||
+        boundary.allowed.some((v) => boundary.forbidden.includes(v))
+      )
+        issues.push(`用例 ${test.id} 缺少明确且不冲突的 mockBoundary`);
+      const statements = list(test.statements);
+      if (
+        !statements.length ||
+        statements.some(
+          (item) =>
+            !list(entry.database.statements).some(
+              (v) => v.id === item?.id && v.sourceRef === item?.sourceRef,
+            ),
+        )
+      )
+        issues.push(`用例 ${test.id} 缺少入口冻结的生产 SQL statement`);
+      const assertions = list(test.databaseAssertions);
+      if (
+        !assertions.length ||
+        assertions.some(
+          (a) => !nonempty(a?.id) || !nonempty(a?.kind) || !("expected" in a),
+        )
+      )
+        issues.push(`用例 ${test.id} 缺少冻结数据库数据断言`);
+
+      for (const assertion of assertions) {
+        if (assertion.kind !== "unchangedRows") continue;
+        const snapshot = assertion.expected;
+        if (
+          !snapshot ||
+          typeof snapshot !== "object" ||
+          Array.isArray(snapshot) ||
+          !Object.keys(snapshot).length ||
+          Object.values(snapshot).some(
+            (row) =>
+              !row ||
+              typeof row !== "object" ||
+              Array.isArray(row) ||
+              !Object.keys(row).length,
+          )
+        )
+          issues.push(`用例 ${test.id} unchangedRows 缺少按业务键冻结的行快照`);
+      }
+      if (new Set(assertions.map((a) => a.id)).size !== assertions.length)
+        issues.push(`用例 ${test.id} 数据库断言 ID 重复`);
+      if (
+        list(entry.persistence).length &&
+        ["affectedRows", "unchangedRows"].some(
+          (kind) => !assertions.some((a) => a.kind === kind),
+        )
+      )
+        issues.push(`用例 ${test.id} 缺少影响行数/非目标与旧轮次不变断言`);
+    }
+    const writes = test.assertions?.persistence ?? [];
+    if (
+      !Array.isArray(writes) ||
+      writes.some(
+        (write) =>
+          !nonempty(write?.id) ||
+          !nonempty(write.table) ||
+          !nonempty(write.field) ||
+          !("expected" in write) ||
+          (write.expected === null && write.allowNull !== true),
+      )
+    ) {
+      issues.push(
+        `用例 ${test.id} 缺少持久化字段与非空预期值；历史 NULL 需明确 allowNull`,
+      );
+    } else {
+      const ids = new Set(writes.map((write) => write.id));
+      if (ids.size !== writes.length)
+        issues.push(`用例 ${test.id} 持久化断言 ID 重复`);
+      for (const field of ["logic", "sql-binding"].includes(layer)
+        ? []
+        : (entry?.persistence ?? [])) {
+        if (
+          !writes.some(
+            (write) =>
+              write.table === field.table && write.field === field.field,
+          )
+        )
+          issues.push(`用例 ${test.id} 缺少入口写入字段的前后值断言`);
+      }
+    }
   }
   const pairs = new Set();
   for (const decision of list(coverage.decisions)) {
@@ -174,6 +307,39 @@ export function validateCoverage(root, review, issues, checkCode = true) {
     ) {
       issues.push(`${key} 缺少对应真实入口的验收用例`);
     }
+
+    if (
+      decision.disposition !== "EXCLUDED" &&
+      entries.get(decision.entryId)?.database &&
+      !list(decision.caseIds).some(
+        (id) =>
+          ["database", "http-entry"].includes(cases.get(id)?.testLayer) &&
+          cases.get(id)?.evidenceKind === "real",
+      )
+    )
+      issues.push(`${key} 缺少必要真实数据库用例；Mock/sql-binding 不能替代`);
+
+    const database = entries.get(decision.entryId)?.database;
+    if (decision.disposition !== "EXCLUDED" && database) {
+      const executed = list(decision.caseIds).flatMap((id) => {
+        const test = cases.get(id);
+        return ["database", "http-entry"].includes(test?.testLayer) &&
+          test?.evidenceKind === "real"
+          ? list(test.statements)
+          : [];
+      });
+      if (
+        list(database.statements).some(
+          (statement) =>
+            !executed.some(
+              (item) =>
+                item.id === statement.id &&
+                item.sourceRef === statement.sourceRef,
+            ),
+        )
+      )
+        issues.push(`${key} 生产 SQL 未被必要数据库用例覆盖`);
+    }
     if (
       decision.disposition === "EXCLUDED" &&
       list(decision.caseIds).length > 0