@chenmk/superflow 0.5.16 → 0.5.18

package/assets/scripts/superflow-test-report-lint.py

@@ -14,6 +14,7 @@ mechanically:
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import re
 import subprocess
@@ -261,7 +262,265 @@ def lint_against_tests_contract(report_path: Path, report_text: str, tests_path:
     return issues
 
 
-def lint_case_evidence(report_path: Path, report_text: str, review_path: Path) -> list[Issue]:
+def final_report_result(text: str) -> str:
+    # Only the latest explicit summary per language is authoritative. Historical
+    # notes and fenced examples do not invalidate the final execution ledger.
+    text = re.sub(r"```.*?```", "", text, flags=re.S)
+    results = {}
+    for match in re.finditer(r"^(验证结果|Verification Result)\s*[:：]\s*([A-Z_]+)\s*$", text, re.I | re.M):
+        results[match[1].lower()] = match[2].upper()
+    if len(set(results.values())) > 1:
+        return "CONFLICT"
+    return next(iter(results.values()), "MISSING")
+
+
+def verified_file(base: Path, value: str) -> Path:
+    """Local retained artifacts only. Hashes prove identity, not truthfulness."""
+    if not isinstance(value, str) or not value.strip() or re.match(r"^[a-z]+://", value, re.I):
+        raise ValueError("需要本地可读取的执行证据，远端 URL 不能作为通过凭据")
+    file = (base / value).resolve()
+    if not file.is_file() or file.stat().st_size == 0:
+        raise ValueError(f"证据文件不存在或无内容：{value}")
+    return file
+
+
+def hashed_file(base: Path, value: str, sha256: str) -> Path:
+    file = verified_file(base, value)
+    if not isinstance(sha256, str) or not re.fullmatch(r"[a-f0-9]{64}", sha256):
+        raise ValueError(f"缺少有效 SHA-256：{value}")
+    if hashlib.sha256(file.read_bytes()).hexdigest() != sha256:
+        raise ValueError(f"证据指纹不一致或源码已变化：{value}")
+    return file
+
+
+def json_equal(left, right) -> bool:
+    """JSON numbers are distinct from booleans, recursively at every level."""
+    if type(left) in (int, float) and type(right) in (int, float):
+        return left == right
+    if type(left) is not type(right):
+        return False
+    if isinstance(left, dict):
+        return left.keys() == right.keys() and all(json_equal(left[k], right[k]) for k in left)
+    if isinstance(left, list):
+        return len(left) == len(right) and all(json_equal(a, b) for a, b in zip(left, right))
+    return left == right
+
+
+def validate_database_receipt(receipt: dict, event: dict, case: dict,
+                              entry: dict, coverage: dict, change: Path,
+                              paths: set) -> None:
+    """Compare frozen database obligations, never infer SQL semantics."""
+    layer = case.get("testLayer")
+    database = entry.get("database")
+    if (entry.get("persistence") or case.get("assertions", {}).get("persistence")) and not database:
+        raise ValueError("旧持久化 PASS 缺少数据库合同，应保留为 PARTIAL")
+    for key in ("testLayer", "mockBoundary", "database"):
+        if not json_equal(event.get(key), receipt.get(key)):
+            raise ValueError(f"原始执行输出与凭证 {key} 不一致")
+    if layer is not None and receipt.get("testLayer") != layer:
+        raise ValueError("testLayer 与冻结合同不一致")
+    if database and layer not in {"logic", "sql-binding", "database", "http-entry"}:
+        raise ValueError("数据库义务缺少 testLayer，应保留 PARTIAL")
+    if layer not in {"database", "http-entry"} or not database:
+        return
+    if case.get("evidenceKind") != "real" or receipt.get("evidenceKind") != "real":
+        raise ValueError("数据库义务必须使用 real 证据")
+    actual = receipt.get("database", {})
+    for key in ("engine", "major"):
+        if not json_equal(actual.get(key), database.get(key)):
+            raise ValueError(f"数据库 {key} 与冻结合同不一致；替代引擎不能 PASS")
+    boundary = case.get("mockBoundary")
+    if not boundary or not json_equal(receipt.get("mockBoundary"), boundary):
+        raise ValueError("mockBoundary 与冻结合同不一致")
+    if (not isinstance(boundary.get("allowed"), list)
+            or not boundary.get("forbidden")
+            or set(boundary["allowed"]) & set(boundary["forbidden"])):
+        raise ValueError("必测生产链不得 mock")
+    statements = case.get("statements")
+    if not statements or not json_equal(actual.get("statements"), statements):
+        raise ValueError("生产 SQL statement 身份与冻结用例不一致")
+    source_index = {s["id"]: s for s in coverage.get("sources", [])}
+    refs = database.get("schemaSourceRefs", []) + [s["sourceRef"] for s in statements]
+    if not database.get("schemaSourceRefs"):
+        raise ValueError("数据库合同缺少 schema 来源")
+    for ref in refs:
+        source = source_index[ref]
+        source_path = hashed_file(change, source["path"], source["sha256"])
+        if source_path not in paths:
+            raise ValueError("数据库 schema/生产 SQL 来源未纳入执行源码指纹")
+    expected = case.get("databaseAssertions")
+    assertions = actual.get("assertions")
+    if not expected or not isinstance(assertions, list) or len(assertions) != len(expected):
+        raise ValueError("缺少冻结数据库数据断言")
+    for frozen, observed in zip(expected, assertions):
+        if (any(not json_equal(observed.get(k), frozen.get(k)) for k in ("id", "kind", "expected"))
+                or "actual" not in observed or observed.get("result") != "PASS"):
+            raise ValueError("数据库数据/影响行数/不变断言未达到冻结预期")
+        wanted, found = frozen["expected"], observed["actual"]
+        if frozen["kind"] == "unchangedRows":
+            if (not isinstance(wanted, dict) or not wanted
+                    or any(not isinstance(row, dict) or not row for row in wanted.values())
+                    or not isinstance(found, dict) or set(found) != {"before", "after"}
+                    or not json_equal(found["before"], wanted) or not json_equal(found["after"], wanted)):
+                raise ValueError("非目标/旧轮次缺少 keyed before/after 快照或值发生变化")
+        elif not json_equal(found, wanted):
+            raise ValueError("数据库数据/影响行数/不变断言未达到冻结预期")
+
+
+def validate_execution_receipt(file: Path, case: dict, coverage: dict, change: Path) -> None:
+    receipt = json.loads(file.read_text(encoding="utf-8"))
+    if receipt.get("schemaVersion") != "superflow.execution-receipt.v1":
+        raise ValueError("缺少 execution-receipt.v1；旧证据应保留为 PARTIAL")
+    for key, expected in [("caseId", case["id"]), ("entryId", case["entryId"]),
+                          ("level", case["level"]), ("status", "PASS")]:
+        if receipt.get(key) != expected:
+            raise ValueError(f"执行凭证 {key} 与冻结用例不一致")
+    if type(receipt.get("executed")) is not int or receipt["executed"] < 1:
+        raise ValueError("用例零执行/占位不能 PASS")
+    kind = case.get("evidenceKind", "real")
+    if kind not in {"real", "controlled-simulation", "unit"} or receipt.get("evidenceKind") != kind:
+        raise ValueError("执行证据等级与冻结合同不一致；模拟不能替代真实入口")
+    command = receipt["command"]
+    if (not isinstance(command.get("argv"), list) or not command["argv"]
+            or any(not isinstance(arg, str) or not arg.strip() for arg in command["argv"])
+            or type(command.get("exitCode")) is not int or command["exitCode"] != 0):
+        raise ValueError("缺少真实命令或命令退出码非零")
+    output = hashed_file(file.parent, command["output"], command["sha256"])
+    events = []
+    for line in output.read_text(encoding="utf-8").splitlines():
+        try:
+            event = json.loads(line)
+            if isinstance(event, dict) and event.get("caseId") == case["id"]:
+                events.append(event)
+        except ValueError:
+            continue
+    if len(events) != 1:
+        raise ValueError("原始输出缺少唯一用例执行事件；未知 ID/零执行不可 PASS")
+    event = events[0]
+    for key in ["caseId", "entryId", "level", "status", "executed", "assertions", "persistence",
+                "evidenceKind", "sources", "build", "target"]:
+        if not json_equal(event.get(key), receipt.get(key)):
+            raise ValueError(f"原始执行输出与凭证 {key} 不一致")
+    if not json_equal(event.get("command"), {"argv": command["argv"], "exitCode": command["exitCode"]}):
+        raise ValueError("原始执行命令与凭证不一致")
+    sources = receipt["sources"]
+    if not isinstance(sources, list) or not sources:
+        raise ValueError("缺少当前源码/构建指纹")
+    paths = set()
+    source_tokens = []
+    for source in sources:
+        paths.add(hashed_file(file.parent, source["path"], source["sha256"]))
+        source_tokens.append(source["path"] + ":" + source["sha256"])
+    entry = next((e for e in coverage.get("entries", []) if e["id"] == case["entryId"]), None)
+    if entry is None:
+        raise ValueError("执行凭证缺少冻结入口定义")
+    source_index = {s["id"]: s for s in coverage.get("sources", [])}
+    for ref in entry.get("sourceRefs", []):
+        source = source_index[ref]
+        if source.get("role") == "code" and (change / source["path"]).resolve() not in paths:
+            raise ValueError("执行凭证未覆盖该入口冻结的源码写入链")
+    validate_database_receipt(receipt, event, case, entry, coverage, change, paths)
+    build = receipt["build"]
+    target = receipt["target"]
+    fingerprint = hashlib.sha256("\n".join(sorted(source_tokens)).encode()).hexdigest()
+    if build.get("sourceFingerprint") != fingerprint or target.get("sourceFingerprint") != fingerprint:
+        raise ValueError("构建与运行目标未绑定当前源码指纹")
+    hashed_file(file.parent, build["artifact"], build["sha256"])
+    build_command = build["command"]
+    if (not isinstance(build_command.get("argv"), list) or not build_command["argv"]
+            or type(build_command.get("exitCode")) is not int or build_command["exitCode"] != 0):
+        raise ValueError("缺少成功构建命令")
+    build_output = hashed_file(file.parent, build_command["output"], build_command["sha256"])
+    expected_build = {"event": "build", "buildId": build["id"], "sourceFingerprint": fingerprint,
+                      "artifactSha256": build["sha256"], "argv": build_command["argv"], "exitCode": 0}
+    build_events = []
+    for line in build_output.read_text(encoding="utf-8").splitlines():
+        try:
+            value = json.loads(line)
+            if isinstance(value, dict) and value.get("event") == "build" and value.get("buildId") == build["id"]:
+                build_events.append(value)
+        except ValueError:
+            continue
+    if len(build_events) != 1 or not json_equal(build_events[0], expected_build):
+        raise ValueError("构建原始输出未关联当前源码与构建产物")
+    if target.get("buildSha256") != build["sha256"]:
+        raise ValueError("运行目标不是本次验证的构建产物")
+    if not isinstance(build.get("id"), str) or not build["id"].strip() or target.get("buildId") != build["id"]:
+        raise ValueError("真实运行目标与构建指纹不一致")
+    for key, expected in [("service", entry.get("service", entry["id"])),
+                          ("route", entry["route"]), ("kind", case["level"])]:
+        if target.get(key) != expected:
+            raise ValueError(f"真实运行目标 {key} 与冻结入口不一致")
+    assertions = receipt["assertions"]
+    required = set(case.get("assertions", {})) - {"persistence"}
+    required |= {"response", "state", "forbiddenEffects"}
+    if not isinstance(assertions, list) or {a["id"] for a in assertions} != required or len(assertions) != len(required):
+        raise ValueError("缺少冻结响应/状态/禁止副作用断言")
+    for assertion in assertions:
+        if (assertion.get("result") != "PASS" or "expected" not in assertion
+                or "actual" not in assertion or not json_equal(assertion["expected"], assertion["actual"])):
+            raise ValueError("断言失败或缺少预期值/实际值")
+    expected_writes = case.get("assertions", {}).get("persistence", [])
+    writes = receipt.get("persistence", [])
+    if not isinstance(writes, list) or len(writes) != len(expected_writes):
+        raise ValueError("缺少持久化字段同业务 ID 的调用前后对照")
+    for expected, actual in zip(expected_writes, writes):
+        for key in ["id", "table", "field", "expected"]:
+            if key not in actual or not json_equal(actual[key], expected[key]):
+                raise ValueError("持久化断言与冻结字段/预期值不一致")
+        before, after = actual["before"], actual["after"]
+        if (not before.get("businessId") or before["businessId"] != after.get("businessId")
+                or "value" not in before or "value" not in after
+                or not json_equal(after["value"], expected["expected"])
+                or (after["value"] is None and not expected.get("allowNull", False))
+                or actual.get("result") != "PASS"):
+            raise ValueError("持久化值未达到预期；结构存在/全 NULL/跨业务 ID 不能替代写入")
+
+
+def check_git_index_files(root: Path, files: list[Path]) -> None:
+    """Compare version-controlled dependencies with the actual commit snapshot.
+
+    Untracked/ignored local evidence may remain private. This does not require
+    publishing logs, and does not replace review of source/build applicability.
+    """
+    root = root.resolve()
+    for file in set(files):
+        file = file.resolve()
+        try:
+            relative = file.relative_to(root).as_posix()
+        except ValueError:
+            continue
+        tracked = subprocess.run(["git", "-C", str(root), "ls-files", "--error-unmatch", "--", relative],
+                                 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        if tracked.returncode:
+            previous = subprocess.run(["git", "-C", str(root), "cat-file", "-e", "HEAD:" + relative],
+                                      stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            if previous.returncode:
+                continue
+        indexed = subprocess.run(["git", "-C", str(root), "rev-parse", ":" + relative], capture_output=True)
+        working = subprocess.run(["git", "-C", str(root), "hash-object", "--path=" + relative, "--stdin"],
+                                 input=file.read_bytes(), capture_output=True)
+        if indexed.returncode or working.returncode or indexed.stdout.strip() != working.stdout.strip():
+            raise ValueError(f"Git index 与报告依赖工作树不一致：{relative}；请暂存已验证快照")
+
+
+def check_receipt_index(file: Path, report: Path, review: Path, root: Path) -> None:
+    receipt = json.loads(file.read_text())
+    dependencies = [file, report, review]
+    command = receipt["command"]
+    build = receipt["build"]
+    dependencies.extend((file.parent / value).resolve() for value in
+                        [command["output"], build["artifact"], build["command"]["output"]])
+    dependencies.extend((file.parent / source["path"]).resolve() for source in receipt["sources"])
+    coverage = json.loads(review.read_text())["coverage"]
+    dependencies.extend((report.parent / source["path"]).resolve() for source in coverage.get("sources", []))
+    tests = infer_tests_path(report)
+    if tests is not None:
+        dependencies.append(tests)
+    check_git_index_files(root, dependencies)
+
+
+def lint_case_evidence(report_path: Path, report_text: str, review_path: Path, index_root: Path | None = None) -> list[Issue]:
     """Check the frozen R/E/C index against per-case execution receipts."""
     issues: list[Issue] = []
     try:
@@ -280,6 +539,8 @@ def lint_case_evidence(report_path: Path, report_text: str, review_path: Path) -
         if decision.get("disposition") != "EXCLUDED"
         for case_id in decision.get("caseIds", [])
     }
+    if final_report_result(report_text) == "CONFLICT":
+        issues.append(Issue("FAIL", report_path, 0, "中英文最终验证结果冲突"))
     lines = report_text.splitlines()
     header_at = next(
         (i for i, line in enumerate(lines) if CASE_EVIDENCE_HEADER.fullmatch(line.strip())),
@@ -311,13 +572,15 @@ def lint_case_evidence(report_path: Path, report_text: str, review_path: Path) -
             issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 的入口或验收级别与冻结合同不一致"))
         if result not in CASE_RESULTS or not evidence or evidence.lower() in {"pending", "todo", "待补"}:
             issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 缺少有效结果或证据位置"))
-        elif result == "PASS" and not re.match(r"^https?://", evidence, re.I):
-            evidence_file = Path(evidence.split("#", 1)[0])
-            if not evidence_file.is_absolute():
-                evidence_file = report_path.parent / evidence_file
-            if not evidence_file.is_file():
-                issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 的通过证据文件不存在：{evidence}"))
-        if result != "PASS" and re.search(r"验证结果\s*[:：]\s*PASS|Verification Result\s*[:：]\s*PASS", report_text, re.I):
+        elif result == "PASS":
+            try:
+                evidence_file = verified_file(report_path.parent, evidence.split("#", 1)[0])
+                validate_execution_receipt(evidence_file, case or {}, coverage, report_path.parent)
+                if index_root is not None:
+                    check_receipt_index(evidence_file, report_path, review_path, index_root)
+            except (OSError, ValueError, KeyError, TypeError, AttributeError) as error:
+                issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 的通过证据不可验证：{error}"))
+        if result != "PASS" and final_report_result(report_text) == "PASS":
             issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 为 {result}，报告不能声明整体验证 PASS"))
     for case_id in receipts.keys() - required:
         issues.append(Issue("FAIL", report_path, 0, f"用例 {case_id} 未在冻结入口评审中要求执行"))
@@ -340,7 +603,7 @@ def infer_tests_path(report: Path) -> Path | None:
 
 
 def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None,
-                review_path: Path | None = None) -> list[Issue]:
+                review_path: Path | None = None, index_root: Path | None = None) -> list[Issue]:
     issues: list[Issue] = []
     text = path.read_text(encoding="utf-8", errors="replace")
     lines = text.splitlines()
@@ -349,11 +612,19 @@ def lint_report(path: Path, repo: Path | None, tests_path: Path | None = None,
     db_backed = bool(DB_BACKED_RE.search(text))
     blocked = bool(BLOCKED_RE.search(text))
     passed_or_partial = bool(PASS_WORDS.search(text) or re.search(r"Partially verified|部分验证", text, re.I))
-    issues.extend(lint_against_tests_contract(path, text, tests_path or infer_tests_path(path)))
+    adjacent_review = path.parent / ".sdd/reviews/document-review.json"
+    if review_path is None and adjacent_review.is_file():
+        review_path = adjacent_review
+    state_path = path.parent / ".sdd/state.yaml"
+    full = state_path.is_file() and re.search(r"^workflow:\s*[\"']?full[\"']?\s*$", state_path.read_text(), re.M)
+    if full and review_path is None:
+        issues.append(Issue("FAIL", path, 0, "完整 SDD 缺少冻结入口评审凭证，不能以旧关键词报告交付"))
     if review_path is not None:
-        issues.extend(lint_case_evidence(path, text, review_path))
+        issues.extend(lint_case_evidence(path, text, review_path, index_root))
+    else:
+        issues.extend(lint_against_tests_contract(path, text, tests_path or infer_tests_path(path)))
 
-    if db_backed and passed_or_partial and not blocked:
+    if review_path is None and db_backed and passed_or_partial and not blocked:
         if not TABLE_REVERSE_HEADER_RE.search(text):
             issues.append(
                 Issue(
@@ -471,6 +742,8 @@ def main() -> int:
     parser.add_argument("--tests", default="")
     parser.add_argument("--review", default="")
     parser.add_argument("--repo-root", default="")
+    parser.add_argument("--git-index-root", default="")
+    parser.add_argument("--require-complete", action="store_true")
     parser.add_argument("--warn-only", action="store_true")
     args = parser.parse_args()
 
@@ -485,7 +758,11 @@ def main() -> int:
         if tests_path is not None and not tests_path.exists():
             all_issues.append(Issue("FAIL", path, 0, f"显式指定的 tests.md 不存在：{tests_path}"))
         review_path = Path(args.review).resolve() if args.review else None
-        all_issues.extend(lint_report(path, repo, tests_path, review_path))
+        all_issues.extend(lint_report(path, repo, tests_path, review_path, Path(args.git_index_root) if args.git_index_root else None))
+        if args.require_complete:
+            text = path.read_text(encoding="utf-8")
+            if final_report_result(text) != "PASS":
+                all_issues.append(Issue("FAIL", path, 0, "完整交付要求最终验证结果 PASS；局部证据保留为 PARTIAL"))
 
     printable = []
     for issue in all_issues:

package/assets/scripts/superflow-verify-integration.sh

@@ -58,17 +58,12 @@ for REPORT in "$@"; do
   check_pattern "$REPORT" "证据等级/真实验证结论" \
     "Real integration passed|Partial real entry|Partially verified|Blocked|真实入口|API 集成|冒烟|Smoke"
 
-  if [ -x "$HOME/.codex/hooks/superflow-test-report-lint.py" ]; then
-    "$HOME/.codex/hooks/superflow-test-report-lint.py" "$REPORT"
-    if [ $? -ne 0 ]; then
-      FAILED=1
-    fi
-  fi
-
-  if grep -Eiq "跳过|未执行|待补充|TODO|后续测试|建议.*测试|是否.*测试" "$REPORT"; then
-    echo "FAIL [$REPORT] 存在跳过/待补充/后续测试类表述，不能标记完成"
+  # Always use the linter from this installation, on both Codex and Claude.
+  LINT="$(dirname "${BASH_SOURCE[0]}")/superflow-test-report-lint.py"
+  if [ ! -f "$LINT" ] || ! python3 "$LINT" --require-complete "$REPORT"; then
     FAILED=1
   fi
+
 done
 
 if [ "$FAILED" -ne 0 ]; then

package/assets/skills/superflow-design/SKILL.md

@@ -169,3 +169,9 @@ Impact` and prove writers, readers, filters, derived sync paths, consumers,
 Do not continue to `$superflow-implement` until the design guard passes. The next
 phase may generate prompts, but this phase must not skip any required SDD
 contract document or replace API/DB/tests with Superpowers prose.
+
+### 数据库分层证据
+
+按 [数据库合同](../superflow-pipeline/references/document-review-coverage.md#数据库分层合同)
+冻结并继承 `testLayer`、entry.database、生产 statement、mockBoundary 和数据断言。
+确定 schema 来源、引擎主版本、生产 Service/Mapper 边界、影响行数和非目标/旧轮次隔离断言。

package/assets/skills/superflow-docs/SKILL.md

@@ -486,3 +486,12 @@ DB 状态 | 结算/通知/展示消费点 | 真实验证方式`.
 
 When SDD docs pass quality gates, continue with `$superflow-design` for Superpowers
 technical design before prompt splitting or coding orchestration.
+
+
+逐用例 PASS 必须提供可重放本地执行凭证；冻结服务/入口、源码写入链与持久化前后值断言。沿用 pipeline/references/document-review-coverage.md 的 execution-receipt.v1 合同，旧证据保留 PARTIAL；独立评审核对精确 Mapper statement 与原始输出，完整交付运行当前安装的 lint --require-complete。哈希不等同防伪或业务充分性。
+
+### 数据库分层证据
+
+按 [数据库合同](../superflow-pipeline/references/document-review-coverage.md#数据库分层合同)
+冻结并继承 `testLayer`、entry.database、生产 statement、mockBoundary 和数据断言。
+生成文档后用必要DB仅Mock反例和真实生产SQL正例审查；辅助层不强迫DB。

package/assets/skills/superflow-implement/SKILL.md

@@ -484,3 +484,12 @@ Use a CR/Px prompt when frontend integration discovers:
 - SQL/schema drift
 
 CR/Px prompts must include the real frontend payload, screenshot or page path, error response, and validation evidence required after the fix.
+
+
+逐用例 PASS 必须提供可重放本地执行凭证；冻结服务/入口、源码写入链与持久化前后值断言。沿用 pipeline/references/document-review-coverage.md 的 execution-receipt.v1 合同，旧证据保留 PARTIAL；独立评审核对精确 Mapper statement 与原始输出，完整交付运行当前安装的 lint --require-complete。哈希不等同防伪或业务充分性。
+
+### 数据库分层证据
+
+按 [数据库合同](../superflow-pipeline/references/document-review-coverage.md#数据库分层合同)
+冻结并继承 `testLayer`、entry.database、生产 statement、mockBoundary 和数据断言。
+只执行冻结层级和断言；DB环境缺失报告PARTIAL/BLOCKED，不能自行用替代引擎或Mock补齐。

package/assets/skills/superflow-pipeline/references/document-review-coverage.md

@@ -92,9 +92,66 @@ coding-ready 复检失败会写 BLOCKED 撤销旧 READY。
 
 | 用例 ID | 入口 ID | 验收级别 | 结果 | 证据路径 |
 |---|---|---|---|---|
-| C1 | E1 | browser | PASS | logs/C1-trace.zip |
+| C1 | E1 | browser | PASS | logs/C1-receipt.json |
 
 结果只用 `PASS/FAIL/BLOCKED/PARTIAL`；证据路径指向实际命令输出、浏览器 trace、
-响应或数据库对账记录。PASS 的本地证据文件必须保留到验收并可读取；远端证据可用
-HTTP(S) 链接。阻塞项在报告正文写明原因。表格仅证明用例逐项回填，不能证明
+响应或数据库对账记录。PASS 的本地证据文件必须保留到验收并可读取；远端资料须保存为本地可核验证据。阻塞项在报告正文写明原因。表格仅证明用例逐项回填，不能证明
 证据内容正确。任何非 PASS 用例存在时，不得声明整体验证 PASS。
+
+## 可重放执行凭证（0.5.17）
+
+PASS 的证据路径现在必须指向本地 `superflow.execution-receipt.v1` JSON；不得以空文件、任意文本、远端 URL 或测试总数代替。旧报告保留 PARTIAL，补齐受影响证据后再整体 PASS。
+
+凭证字段：`caseId/entryId/level/status=PASS/executed>=1/evidenceKind`；`command{argv,exitCode=0,output,sha256}`；`sources[{path,sha256}]`；`build{id,artifact,sha256,sourceFingerprint}`；`target{service,route,kind,buildId,buildSha256,sourceFingerprint}`；`assertions[{id,expected,actual,result=PASS}]`。路径相对凭证文件，可使用授权跨仓源码；输出需保留可读取的原始日志。源码指纹为 sources 按 `path:sha256` 排序后以换行连接的 SHA-256（末尾无换行）。构建与运行目标必须关联同一指纹和产物；Agent 仍核对构建命令与实际进程/镜像。
+
+命令输出中每个用例包含一个 JSON 行执行事件，携带 `caseId/entryId/level/status/executed/assertions/persistence`，与凭证相同。普通日志可混排；未知 ID、零执行、SKIP、占位或缺少断言事件不可 PASS。一个日志可包含多个用例，各凭证分别定位自己的事件。
+
+冻结入口可增加 `service`（默认 entryId）、`persistence:[{table,field}]`；用例默认 `evidenceKind=real`，只有冻结合同明确允许时才填 `controlled-simulation` 或 `unit`。两个服务写同表也必须分别登记入口和源码链，不得交换证据。
+
+持久化写入用例在 `assertions.persistence` 冻结 `[{id,table,field,expected,allowNull?}]`，凭证/原始事件同名数组追加 `before{businessId,value}`、`after{businessId,value}`、`result`。业务 ID 一致且 after.value 等于冻结预期；新增/改字段用非空预期，历史 NULL 明确 allowNull。字段索引存在、mock 参数赋值、全 NULL 数据不能证明写入。
+
+独立评审必须检查实际 Service 调用的精确 Mapper statement 和所有写入链、运行目标、原始断言及旧通知/新申请隔离；报告的“实现已补齐”必须与源码和运行证据一致。哈希和结构不保证日志真实或断言充分，不能当作防伪签名。该扩展不增加托管协议或状态 owner；纯文档/非行为轻量任务不强加 DB 验收。
+
+原始用例事件还必须携带 evidenceKind/sources/build/target 和 command{argv,exitCode}，与凭证完全一致。build.command{argv,exitCode,output,sha256} 引用构建原始日志，其中包含 JSON 行 {event:"build",buildId,sourceFingerprint,artifactSha256,argv,exitCode:0}；日志与实际构建/运行仍由独立评审核验。最终汇总仅取最后一个中英文一致的“验证结果/Verification Result”，历史记录与代码块示例不用于晋升。
+
+## 数据库分层合同
+
+本节扩展已有 coverage/receipt v1，不增加 Skill、Hook 或状态 owner。
+语义评审发现持久化、字段展示、CAS、事务或查询语义影响时，必须在相应入口声明
+`database`；纯逻辑任务明确无持久化影响的理由后可免数据库验证。不能靠 SQL 关键词猜风险。
+
+- `case.testLayer` 为 `logic|sql-binding|database|http-entry`，与真实入口 `level` 分开。
+  logic 可 Mock 隔离逻辑；sql-binding 只证明 SQL 生成/绑定。必要 case 集合必须至少包含
+  一个 `database` 或 `http-entry` 且 `evidenceKind=real` 的用例；辅助层不强迫连接数据库。
+- `entry.database={engine,major,schemaSourceRefs,statements:[{sourceRef,id}]}` 冻结实际引擎、
+  主版本、schema 来源和精确生产 statement。MySQL 不得被 H2/SQLite 替代。
+  schema 与 Mapper XML 引用既有 sources，纳入 receipt 源码指纹；匿名 SQLite 仅验证 harness。
+- 数据库用例冻结 `statements:[{sourceRef,id}]`、
+  `mockBoundary={allowed:[外部客户端],forbidden:[必测Service/Mapper]}` 及
+  `databaseAssertions:[{id,kind,expected}]`。`kind` 是合同定义的观测类别：
+  写入包括 `affectedRows` 和 `unchangedRows`，后者必须冻结非目标记录和旧轮次实际快照；
+  其他风险由 Agent 按需求冻结断言，不由脚本推测业务规则。
+- receipt 和原始用例事件回填同一 `testLayer`、`mockBoundary`、
+  `database={engine,major,statements,assertions:[{id,kind,expected,actual,result}]}`。
+  保留原始命令、构建、入口与源码版本绑定；数据库 assertions 实际值必须等于冻结预期。
+  字段写入继续使用 `assertions.persistence` 与同业务 ID 的 before/after/expected，
+  不能用 Mock 参数、NULL、字段键或影响行数独自证明写入。
+- `http-entry` 若承担 DB 义务，必须走真实 HTTP → 生产 Service/Mapper → 同类型 DB，
+  同时执行返回、持久化和隔离断言；直接 Mapper 回放不能冒充 HTTP 或 browser 验收。
+- 旧非持久化合同保持兼容；旧持久化 PASS 缺新合同保留 PARTIAL。必要 DB 环境不可用时
+  记录 PARTIAL/BLOCKED 和原因，不把辅助 Mock/sql-binding 绿灯晋升为完整 PASS。
+  历史证据绑定固定入口、源码/构建版本和 DB 引擎时仍有效；当前源码改动需要新证据，
+  不得把历史版实际测试误说成没测试，也不能把旧结果用于当前新版本。
+
+正例：逻辑与 SQL 绑定辅助用例 + 真实生产 XML/MySQL 数据断言；纯逻辑有明确无持久化影响理由。
+反例：必要集合只有 Mock、HTTP 绕过生产 Mapper、引擎/statement/边界/来源错配、
+漏字段实际 NULL 却填 PASS。文档生成后在 source-contract 与 e2e-environment 两轮独立审查
+这些正反例；结构检查只确认冻结与观测一致，充分性和真实生产链留给独立 Agent。
+
+`unchangedRows.expected` 必须是按稳定业务 ID/轮次键索引的非空行快照对象；
+`actual={before:{业务键:行快照},after:{业务键:行快照}}` 保留两次真实查询值，
+before 与 after 均须匹配冻结 expected。布尔成功标志不能替代快照。
+所有 JSON 观测递归保留类型：boolean 不等于 number（如 true 不能证明影响行数 1），
+数组/对象中的字段同样适用；具体业务键与快照字段由文档与独立评审决定。
+
+Git 交付路径还会对 tracked 报告依赖（receipt、原始事件、构建、源码、schema/合同）核对标准化 index 对象；仅在工作树修正不能证明待提交快照。未受版本控制的私有证据不强制提交；当前源码/构建适用性仍由独立评审判断。

package/assets/skills/superflow-pipeline/references/test-execution-template.md

@@ -76,7 +76,7 @@ mvn test -Dtest=UserServiceTest
 
 | 用例 ID | 入口 ID | 验收级别 | 结果 | 证据路径 |
 |---|---|---|---|---|
-| C1 | E1 | browser | PASS | logs/C1-trace.zip |
+| C1 | E1 | browser | PASS | logs/C1-receipt.json |
 
 `PASS/FAIL/BLOCKED/PARTIAL` 之外的值无效；非 PASS 项在正文说明原因。
 数据库字段展示要分别记录非空数据按同一 ID 的 API/DB 值对账、历史 NULL 结果和
@@ -261,3 +261,5 @@ HTTP 200、字段非空、mock-only、DB-only、`BUILD SUCCESS`、`Tests are ski
 - 不允许把泛化外部失败当作通过，除非需求明确要求该失败结果
 - 不允许只检查主仓数据库结构就关闭跨仓共享表任务；必须覆盖全部消费仓实体/Mapper/SQL
 - **不允许"编译成功 + 单元测试通过"就标记任务完成，必须完成上述 checklist 全部项**
+
+执行凭证格式与持久化前后对照遵循 [document-review-coverage.md](document-review-coverage.md)，不要另建格式；历史局部结论保留，以最后一个中英文一致的验证结果为最终汇总。

package/assets/skills/superflow-pipeline/scripts/superflow-guard.sh

@@ -91,7 +91,7 @@ require_test_report_lint() {
   local -a lint_args
   root="$(project_root_for_change)"
   review="$CHANGE_DIR/.sdd/reviews/document-review.json"
-  lint_args=(--tests "$CHANGE_DIR/tests.md")
+  lint_args=(--tests "$CHANGE_DIR/tests.md" --require-complete)
   if [[ "$(state_get workflow)" == "full" && ! -f "$review" ]]; then
     issues+=("full SDD verify requires .sdd/reviews/document-review.json; complete the docs entry review before verify")
     return
@@ -101,8 +101,8 @@ require_test_report_lint() {
   fi
 
   for lint in \
-    "$root/.codex/hooks/superflow-test-report-lint.py" \
-    "$HOME/.codex/hooks/superflow-test-report-lint.py"; do
+    "${SUPERFLOW_REPORT_LINT:-$SCRIPT_DIR/../../../scripts/superflow-test-report-lint.py}" \
+    "$SCRIPT_DIR/../../../hooks/superflow-test-report-lint.py"; do
     if [[ -x "$lint" ]]; then
       output="$(mktemp)"
       if ! "$lint" "${lint_args[@]}" "$report" >"$output" 2>&1; then
@@ -907,8 +907,12 @@ case "$PHASE" in
     require_file test-report.md
     require_grep 'RED|失败证据' test-report.md "RED evidence"
     require_grep 'GREEN|通过证据' test-report.md "GREEN evidence"
-    require_grep '接口自动化|curl|Postman|Newman|pytest|RestAssured' test-report.md "interface automation evidence"
-    require_grep 'DB|数据库|SELECT|SHOW CREATE' test-report.md "DB evidence"
+    if [[ "$(state_get workflow)" == "full" ]]; then
+      require_grep '接口自动化|curl|Postman|Newman|pytest|RestAssured' test-report.md "interface automation evidence"
+    fi
+    if change_has_database_change; then
+      require_grep 'DB|数据库|SELECT|SHOW CREATE' test-report.md "DB evidence"
+    fi
     require_grep 'superflow-verify-integration|superflow-delivery-check|superflow-test-report-lint' test-report.md "SuperBridge Flow hook/script evidence"
     if change_has_external_enum_risk; then
       require_grep 'External Enum Binding|外部枚举绑定|第三方字段语义绑定|外部展示|展示文案|业务语义|财务语义|BEM|真实入口' test-report.md "external enum binding runtime evidence"

package/assets/skills/superflow-table-impact-analysis/SKILL.md

@@ -75,3 +75,9 @@ Mark the task `Blocked` when:
 `~/.codex/hooks/superflow-test-report-lint.py` enforces this for database/status
 reports that claim pass or partial pass. A report that only says "sync
 succeeded" without consumer-path evidence is blocked.
+
+### 数据库分层证据
+
+按 [数据库合同](../superflow-pipeline/references/document-review-coverage.md#数据库分层合同)
+冻结并继承 `testLayer`、entry.database、生产 statement、mockBoundary 和数据断言。
+从表、字段、CAS与事务反向发现DB义务并声明entry.database；纯逻辑明确无持久化理由可免DB。

package/assets/skills/superflow-verify/SKILL.md

@@ -180,3 +180,12 @@ This advances to `phase: archive`, sets `verify_result: pass`, and records
 
 Passing verification does not authorize automatic archive. Enter `$superflow-archive`
 and wait for explicit user confirmation.
+
+
+逐用例 PASS 必须提供可重放本地执行凭证；冻结服务/入口、源码写入链与持久化前后值断言。沿用 pipeline/references/document-review-coverage.md 的 execution-receipt.v1 合同，旧证据保留 PARTIAL；独立评审核对精确 Mapper statement 与原始输出，完整交付运行当前安装的 lint --require-complete。哈希不等同防伪或业务充分性。
+
+### 数据库分层证据
+
+按 [数据库合同](../superflow-pipeline/references/document-review-coverage.md#数据库分层合同)
+冻结并继承 `testLayer`、entry.database、生产 statement、mockBoundary 和数据断言。
+核对原始事件与receipt、源码/构建/入口/引擎版本；旧固定版本证据保留，当前源码变化需新证据。

package/assets/skills-en/superflow-design/SKILL.md

@@ -156,3 +156,9 @@ Superpowers own source-level HOW without weakening OpenSpec/SDD contracts.
 Do not continue to `$superflow-implement` until the design guard passes. The next
 phase may generate prompts, but this phase must not skip any required SDD
 contract document or replace API/DB/tests with Superpowers prose.
+
+### Database layer evidence
+
+Freeze and inherit `testLayer`, entry.database, production statements, mockBoundary,
+and data assertions from the [database contract](../superflow-pipeline/references/document-review-coverage.md#database-layer-contract).
+Resolve schema sources, engine major, production Service/Mapper boundaries, affected rows, and non-target/previous-round isolation assertions.

package/assets/skills-en/superflow-docs/SKILL.md

@@ -486,3 +486,12 @@ Use references only as needed:
 
 When SDD docs pass quality gates, continue with `$superflow-design` for Superpowers
 technical design before prompt splitting or coding orchestration.
+
+
+Per-case PASS requires retained local execution receipts. Freeze service/entry, source write chains and before/after persistence assertions using pipeline/references/document-review-coverage.md and execution-receipt.v1. Keep legacy evidence PARTIAL. Independent review checks the exact Mapper statement and raw output; full delivery runs the current installation's lint --require-complete. Hashes do not prove authenticity or business sufficiency.
+
+### Database layer evidence
+
+Freeze and inherit `testLayer`, entry.database, production statements, mockBoundary,
+and data assertions from the [database contract](../superflow-pipeline/references/document-review-coverage.md#database-layer-contract).
+Review generated documents against mock-only required-DB negatives and real production-SQL positives; auxiliary layers need no DB.

package/assets/skills-en/superflow-implement/SKILL.md

@@ -134,3 +134,12 @@ Before moving to verify, run:
 Do not claim completion from unit tests alone. Runtime code changes require
 compile/build evidence, app start evidence when applicable, real API or event
 execution, DB/log checks, hook output, and test-report updates.
+
+
+Per-case PASS requires retained local execution receipts. Freeze service/entry, source write chains and before/after persistence assertions using pipeline/references/document-review-coverage.md and execution-receipt.v1. Keep legacy evidence PARTIAL. Independent review checks the exact Mapper statement and raw output; full delivery runs the current installation's lint --require-complete. Hashes do not prove authenticity or business sufficiency.
+
+### Database layer evidence
+
+Freeze and inherit `testLayer`, entry.database, production statements, mockBoundary,
+and data assertions from the [database contract](../superflow-pipeline/references/document-review-coverage.md#database-layer-contract).
+Execute frozen layers/assertions; missing DB environments are PARTIAL/BLOCKED. Do not substitute another engine or mocks.