enterprise-agent-designer 0.34.1

package/skills/review-enterprise-agent/scripts/validate_review_receipt.py

@@ -0,0 +1,338 @@
+#!/usr/bin/env python3
+"""Validate review-receipt structure and explicit cross-field contradictions.
+
+This script does not judge whether cited business evidence is true or sufficient.
+It only prevents a receipt from declaring pass while its own structured fields say
+that decisive evidence, replay, authority, or dependency closure is missing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+COMMON_FIELDS = {
+    "review_mode",
+    "review_scope",
+    "review_round",
+    "verdict",
+    "lowest_failed_layer",
+    "decisive_reason",
+    "evidence",
+    "preserve",
+    "return_to",
+    "next_action",
+    "change_condition",
+    "reviewed_snapshot_id",
+    "grounding_audit",
+    "source_audit",
+    "materiality_audit",
+    "authority_audit",
+}
+
+LOWEST_FAILED_LAYERS = {
+    "requirements",
+    "professional-task",
+    "role",
+    "principles",
+    "skill-topology",
+    "tool-knowledge",
+    "output-handoff",
+    "trace-runtime",
+    "none",
+}
+
+RETURN_TARGETS = {
+    "grilling",
+    "grill-with-docs",
+    "design-enterprise-agent",
+    "delivery-finalizer",
+    "user",
+}
+
+COUNTEREXAMPLE_BASIS_FIELDS = {
+    "standard_source_status",
+    "standard_source",
+    "anchor_set_completeness",
+    "all_explicit_anchors_satisfied",
+    "coverage_gap_status",
+    "coverage_gap_source",
+    "scenario_evidence_status",
+}
+
+SOURCE_AUDIT_FIELDS = {
+    "normal_case_replay",
+    "highest_risk_case_replay",
+    "finding_classification_consistent",
+    "unsupported_scope_expansion_found",
+    "skill_dependency_closure",
+}
+
+MATERIALITY_AUDIT_FIELDS = {
+    "overall_goal",
+    "consumer_decision",
+    "first_release_boundary",
+    "material_blocker_found",
+    "material_effect",
+    "same_failure_family_scope",
+    "deferred_non_blocking",
+    "late_round_blocking_justification",
+}
+
+LATE_ROUND_BLOCKING_JUSTIFICATIONS = {
+    "not_applicable",
+    "new-independent-failure-class",
+    "material-same-family-missed-instance",
+    "patch-introduced-failure",
+    "previously-unobservable-failure",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate an isolated grounding-gate or source-gate receipt."
+    )
+    parser.add_argument("receipt", type=Path)
+    parser.add_argument(
+        "--expected-mode", choices=("grounding-gate", "source-gate"), required=True
+    )
+    parser.add_argument("--expected-round", type=int)
+    parser.add_argument("--expected-snapshot")
+    return parser.parse_args()
+
+
+def load_receipt(path: Path, errors: list[str]) -> dict[str, object] | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        errors.append(f"收据不存在：{path}")
+        return None
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        errors.append(f"收据无法按 UTF-8 JSON 读取：{exc}")
+        return None
+    if not isinstance(payload, dict):
+        errors.append("收据必须是 JSON 对象")
+        return None
+    return payload
+
+
+def validate_common(
+    receipt: dict[str, object], args: argparse.Namespace, errors: list[str]
+) -> None:
+    missing = COMMON_FIELDS - set(receipt)
+    if missing:
+        errors.append(f"收据缺少字段：{sorted(missing)}")
+        return
+    if receipt.get("review_mode") != args.expected_mode:
+        errors.append("review_mode 与 --expected-mode 不一致")
+    if receipt.get("review_scope") != "isolated-subagent":
+        errors.append("review_scope 不是 isolated-subagent")
+    review_round = receipt.get("review_round")
+    if not isinstance(review_round, int) or isinstance(review_round, bool) or review_round < 1:
+        errors.append("review_round 必须是从 1 开始的正整数")
+    if args.expected_round is not None and review_round != args.expected_round:
+        errors.append("review_round 与 --expected-round 不一致")
+    if receipt.get("verdict") not in {"pass", "revision_required", "insufficient_basis"}:
+        errors.append("verdict 不在允许枚举中")
+    verdict = receipt.get("verdict")
+    lowest_failed_layer = receipt.get("lowest_failed_layer")
+    if lowest_failed_layer not in LOWEST_FAILED_LAYERS:
+        errors.append("lowest_failed_layer 不在允许枚举中")
+    elif verdict == "pass" and lowest_failed_layer != "none":
+        errors.append("pass 收据的 lowest_failed_layer 必须为 none")
+    elif verdict in {"revision_required", "insufficient_basis"} and lowest_failed_layer == "none":
+        errors.append("非 pass 收据的 lowest_failed_layer 不能为 none")
+    if receipt.get("return_to") not in RETURN_TARGETS:
+        errors.append("return_to 不在允许枚举中")
+    for name in ("decisive_reason", "next_action", "change_condition"):
+        if not isinstance(receipt.get(name), str) or not str(receipt.get(name)).strip():
+            errors.append(f"{name} 必须是非空字符串")
+    for name in ("evidence", "preserve"):
+        if not isinstance(receipt.get(name), list):
+            errors.append(f"{name} 必须是数组")
+
+    authority = receipt.get("authority_audit")
+    if not isinstance(authority, dict):
+        errors.append("authority_audit 必须是对象")
+    else:
+        for name in ("stable_rules_reviewed", "unresolved_or_unauthorized"):
+            if not isinstance(authority.get(name), list):
+                errors.append(f"authority_audit.{name} 必须是数组")
+        if receipt.get("verdict") == "pass" and authority.get("unresolved_or_unauthorized"):
+            errors.append("pass 收据仍含无权或未解决规则")
+
+
+def validate_grounding(receipt: dict[str, object], errors: list[str]) -> None:
+    if receipt.get("reviewed_snapshot_id") != "not_applicable":
+        errors.append("grounding-gate 的 reviewed_snapshot_id 必须为 not_applicable")
+    if receipt.get("source_audit") != "not_applicable":
+        errors.append("grounding-gate 的 source_audit 必须为 not_applicable")
+    if receipt.get("materiality_audit") != "not_applicable":
+        errors.append("grounding-gate 的 materiality_audit 必须为 not_applicable")
+    audit = receipt.get("grounding_audit")
+    if not isinstance(audit, dict):
+        errors.append("grounding-gate 必须提供 grounding_audit 对象")
+        return
+    if receipt.get("verdict") != "pass":
+        return
+
+    standard_mode = audit.get("standard_mode")
+    counterexample_status = audit.get("strict_counterexample_status")
+    if standard_mode == "none":
+        if counterexample_status != "not_applicable":
+            errors.append("standard_mode=none 时严格反例必须为 not_applicable")
+        return
+    if standard_mode == "runtime-input-only":
+        if counterexample_status != "not_required_contract_only":
+            errors.append(
+                "standard_mode=runtime-input-only 时必须标记 not_required_contract_only"
+            )
+        return
+    if standard_mode != "coverage-or-applicability":
+        errors.append("grounding pass 的 standard_mode 不在允许枚举中")
+        return
+    if counterexample_status != "pass":
+        errors.append("声称判断标准覆盖性或适用性时必须有严格反例 pass")
+
+    basis = audit.get("counterexample_basis")
+    if not isinstance(basis, dict):
+        errors.append("grounding pass 缺少 counterexample_basis")
+        return
+    missing = COUNTEREXAMPLE_BASIS_FIELDS - set(basis)
+    if missing:
+        errors.append(f"counterexample_basis 缺少字段：{sorted(missing)}")
+        return
+    if basis.get("standard_source_status") not in {
+        "verified-text",
+        "authorized-scope-confirmation",
+    }:
+        errors.append("严格反例没有可接受的标准来源")
+    if not isinstance(basis.get("standard_source"), str) or not str(
+        basis.get("standard_source")
+    ).strip():
+        errors.append("严格反例缺少具体标准来源")
+    if basis.get("anchor_set_completeness") != "confirmed":
+        errors.append("全部显式锚点集合尚未确认完整")
+    if basis.get("all_explicit_anchors_satisfied") is not True:
+        errors.append("没有确认全部显式锚点已经满足")
+    if basis.get("coverage_gap_status") != "confirmed":
+        errors.append("标准覆盖缺口尚未确认")
+    if not isinstance(basis.get("coverage_gap_source"), str) or not str(
+        basis.get("coverage_gap_source")
+    ).strip():
+        errors.append("标准覆盖缺口缺少具体来源")
+    if basis.get("scenario_evidence_status") not in {
+        "verified-case",
+        "self-contained-fixture",
+    }:
+        errors.append("严格反例仍是未经核证的假设场景")
+
+
+def validate_source(
+    receipt: dict[str, object], args: argparse.Namespace, errors: list[str]
+) -> None:
+    if receipt.get("grounding_audit") != "not_applicable":
+        errors.append("source-gate 的 grounding_audit 必须为 not_applicable")
+    snapshot = receipt.get("reviewed_snapshot_id")
+    if not isinstance(snapshot, str) or not snapshot.startswith("sha256:"):
+        errors.append("source-gate 收据未绑定 sha256 源码快照")
+    if args.expected_snapshot is None:
+        errors.append("source-gate 校验必须提供 --expected-snapshot")
+    elif snapshot != args.expected_snapshot:
+        errors.append("reviewed_snapshot_id 与 --expected-snapshot 不一致")
+
+    audit = receipt.get("source_audit")
+    if not isinstance(audit, dict):
+        errors.append("source-gate 必须提供 source_audit 对象")
+    else:
+        missing = SOURCE_AUDIT_FIELDS - set(audit)
+        if missing:
+            errors.append(f"source_audit 缺少字段：{sorted(missing)}")
+        elif receipt.get("verdict") == "pass":
+            if audit.get("normal_case_replay") != "pass":
+                errors.append("正常案例尚未通过源码回放")
+            if audit.get("highest_risk_case_replay") != "pass":
+                errors.append("最高风险案例尚未通过源码回放")
+            if audit.get("finding_classification_consistent") is not True:
+                errors.append("评测发现分类尚未确认一致")
+            if audit.get("unsupported_scope_expansion_found") is not False:
+                errors.append("源码或评测仍含未经依据的范围扩张")
+            if audit.get("skill_dependency_closure") != "pass":
+                errors.append("Skill 数据依赖尚未闭合")
+
+    materiality = receipt.get("materiality_audit")
+    if not isinstance(materiality, dict):
+        errors.append("source-gate 必须提供 materiality_audit 对象")
+        return
+    missing_materiality = MATERIALITY_AUDIT_FIELDS - set(materiality)
+    if missing_materiality:
+        errors.append(f"materiality_audit 缺少字段：{sorted(missing_materiality)}")
+        return
+    for name in ("overall_goal", "consumer_decision", "first_release_boundary", "material_effect"):
+        if not isinstance(materiality.get(name), str) or not str(materiality.get(name)).strip():
+            errors.append(f"materiality_audit.{name} 必须是非空字符串")
+    for name in ("same_failure_family_scope", "deferred_non_blocking"):
+        if not isinstance(materiality.get(name), list):
+            errors.append(f"materiality_audit.{name} 必须是数组")
+    late_round_justification = materiality.get("late_round_blocking_justification")
+    if late_round_justification not in LATE_ROUND_BLOCKING_JUSTIFICATIONS:
+        errors.append(
+            "materiality_audit.late_round_blocking_justification 不在允许枚举中"
+        )
+
+    verdict = receipt.get("verdict")
+    if verdict == "pass" and materiality.get("material_blocker_found") is not False:
+        errors.append("source-gate pass 仍声明存在 material blocker")
+    if verdict in {"revision_required", "insufficient_basis"}:
+        if materiality.get("material_blocker_found") is not True:
+            errors.append("source-gate 非 pass 必须确认存在 material blocker")
+        if not materiality.get("same_failure_family_scope"):
+            errors.append("source-gate 非 pass 必须记录同类失败横向扫描范围")
+    review_round = receipt.get("review_round")
+    if (
+        verdict in {"revision_required", "insufficient_basis"}
+        and isinstance(review_round, int)
+        and review_round >= 4
+        and late_round_justification
+        not in {
+            "new-independent-failure-class",
+            "material-same-family-missed-instance",
+            "patch-introduced-failure",
+            "previously-unobservable-failure",
+        }
+    ):
+        errors.append(
+            "source-gate 第 4 轮及以后继续阻断必须是新发现的独立高影响失败类、"
+            "仍具实质影响的同类遗漏、本轮修改引入的高影响失败，"
+            "或此前证据客观上无法发现的高影响失败"
+        )
+    if verdict == "pass" and late_round_justification != "not_applicable":
+        errors.append("source-gate pass 的 late_round_blocking_justification 必须为 not_applicable")
+
+
+def main() -> int:
+    args = parse_args()
+    errors: list[str] = []
+    receipt = load_receipt(args.receipt, errors)
+    if receipt is not None:
+        validate_common(receipt, args, errors)
+        if args.expected_mode == "grounding-gate":
+            validate_grounding(receipt, errors)
+        else:
+            validate_source(receipt, args, errors)
+
+    if errors:
+        print(f"RECEIPT_FAIL：{len(errors)} 个结构或显式矛盾")
+        for error in errors:
+            print(f"- {error}")
+        return 1
+    print("RECEIPT_PASS：收据结构与显式证据状态一致")
+    print("说明：该结果不判断引用事实是否真实，不替代隔离评审。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())