enterprise-agent-designer 0.34.1

package/scripts/optional/workflow_controller.py

@@ -0,0 +1,478 @@
+#!/usr/bin/env python3
+"""Deterministic phase and completion controller for full Agent-source delivery.
+
+This controller does not judge business or Agent-design quality. It validates
+phase transitions and evidence needed to continue, package, or declare a
+handoff-ready result.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+VERSION = "0.32.1"
+SCHEMA_VERSION = "1.0"
+DEFAULT_REVIEW_VALIDATOR = (
+    ROOT / "skills/review-enterprise-agent/scripts/validate_review_receipt.py"
+)
+
+
+class WorkflowError(ValueError):
+    pass
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Control legal workflow transitions for full_agent_source delivery."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init")
+    init_parser.add_argument("state", type=Path)
+    init_parser.add_argument("--overall-goal-ref", required=True)
+    init_parser.add_argument(
+        "--workflow-mode",
+        choices=("host_integrated", "reference_only"),
+        default="reference_only",
+        help="host_integrated 表示宿主已绑定阶段 Hook；否则仅为可调用参考控制器。",
+    )
+    init_parser.add_argument("--max-invalid-receipt-retries", type=int, default=1)
+
+    event_parser = subparsers.add_parser("event")
+    event_parser.add_argument("state", type=Path)
+    event_parser.add_argument(
+        "event",
+        choices=(
+            "candidate-grounded",
+            "grounding-gate-started",
+            "source-written",
+            "source-review-prepared",
+            "source-gate-started",
+            "source-changed",
+            "review-tool-unavailable",
+            "review-resume-authorized",
+        ),
+    )
+    event_parser.add_argument("--gate", choices=("grounding-gate", "source-gate"))
+    event_parser.add_argument("--manifest", type=Path)
+    event_parser.add_argument("--reason")
+    event_parser.add_argument("--failure-evidence")
+
+    gate_parser = subparsers.add_parser("gate")
+    gate_parser.add_argument("state", type=Path)
+    gate_parser.add_argument("--gate", choices=("grounding-gate", "source-gate"), required=True)
+    gate_parser.add_argument("--receipt", type=Path, required=True)
+    gate_parser.add_argument("--expected-round", type=int, required=True)
+    gate_parser.add_argument(
+        "--validator", type=Path, default=DEFAULT_REVIEW_VALIDATOR
+    )
+
+    delivery_parser = subparsers.add_parser("delivery")
+    delivery_parser.add_argument("state", type=Path)
+    delivery_parser.add_argument("--receipt", type=Path, required=True)
+
+    status_parser = subparsers.add_parser("status")
+    status_parser.add_argument("state", type=Path)
+
+    terminal_parser = subparsers.add_parser("check-terminal")
+    terminal_parser.add_argument("state", type=Path)
+
+    return parser.parse_args()
+
+
+def load_json(path: Path) -> dict[str, object]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise WorkflowError(f"文件不存在：{path}") from exc
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise WorkflowError(f"文件无法按 UTF-8 JSON 读取：{path}：{exc}") from exc
+    if not isinstance(payload, dict):
+        raise WorkflowError(f"JSON 顶层必须是对象：{path}")
+    return payload
+
+
+def load_state(path: Path) -> dict[str, object]:
+    state = load_json(path)
+    if state.get("schema_version") != SCHEMA_VERSION:
+        raise WorkflowError("状态 schema_version 不受支持")
+    if state.get("product_version") != VERSION:
+        raise WorkflowError("状态 product_version 与当前控制器不一致")
+    if state.get("delivery_mode") != "full_agent_source":
+        raise WorkflowError("控制器当前只处理 full_agent_source")
+    return state
+
+
+def allowed_actions(state: dict[str, object]) -> list[str]:
+    phase = state.get("phase")
+    grounding = state.get("grounding_gate_status")
+    source = state.get("source_gate_status")
+
+    if phase == "discovery":
+        if grounding == "candidate_ready":
+            return ["invoke-grounding-gate"]
+        return ["continue-discovery"]
+    if phase == "grounding_review":
+        if grounding == "in_progress":
+            return ["await-grounding-receipt"]
+        if grounding == "invalid_receipt":
+            return ["retry-grounding-gate"]
+        return ["invoke-grounding-gate"]
+    if phase == "design":
+        return ["run-design-skill"]
+    if phase == "source_review":
+        if source == "not_attempted":
+            return ["prepare-source-review"]
+        if source == "prepared":
+            return ["invoke-source-gate"]
+        if source == "in_progress":
+            return ["await-source-gate-receipt"]
+        if source == "invalid_receipt":
+            return ["retry-source-gate"]
+        return ["prepare-source-review"]
+    if phase == "packaging":
+        return ["run-delivery-finalizer"]
+    if phase == "ready_for_handoff":
+        return ["provide-verified-zip-path"]
+    if phase == "blocked":
+        return ["report-blocker", "resume-after-external-change"]
+    raise WorkflowError(f"未知 phase：{phase}")
+
+
+def persist(path: Path, state: dict[str, object]) -> None:
+    state["allowed_actions"] = allowed_actions(state)
+    path = path.resolve()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(path.name + ".tmp")
+    temporary.write_text(
+        json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    temporary.replace(path)
+
+
+def initialize(args: argparse.Namespace) -> int:
+    if args.max_invalid_receipt_retries < 0:
+        raise WorkflowError("max-invalid-receipt-retries 不能小于 0")
+    if args.state.exists():
+        raise WorkflowError(f"状态文件已存在，不能覆盖：{args.state}")
+    state: dict[str, object] = {
+        "schema_version": SCHEMA_VERSION,
+        "product_version": VERSION,
+        "delivery_mode": "full_agent_source",
+        "workflow_mode": args.workflow_mode,
+        "enforcement_level": (
+            "deterministic_host_hooks"
+            if args.workflow_mode == "host_integrated"
+            else "callable_reference_only"
+        ),
+        "overall_goal_ref": args.overall_goal_ref,
+        "phase": "discovery",
+        "grounding_gate_status": "not_attempted",
+        "source_status": "not_started",
+        "source_gate_status": "not_attempted",
+        "source_snapshot_id": None,
+        "source_review_manifest": None,
+        "package_status": "not_started",
+        "delivery_receipt": None,
+        "output_zip": None,
+        "invalid_receipt_attempts": {"grounding-gate": 0, "source-gate": 0},
+        "max_invalid_receipt_retries": args.max_invalid_receipt_retries,
+        "blocked_reason": None,
+        "last_event": "initialized",
+    }
+    persist(args.state, state)
+    print_state(state)
+    return 0
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise WorkflowError(message)
+
+
+def read_manifest(path: Path) -> tuple[str, Path]:
+    payload = load_json(path)
+    snapshot = payload.get("source_snapshot_id")
+    if not isinstance(snapshot, str) or not snapshot.startswith("sha256:"):
+        raise WorkflowError("送审清单缺少有效 source_snapshot_id")
+    return snapshot, path.resolve()
+
+
+def apply_event(args: argparse.Namespace) -> int:
+    state = load_state(args.state)
+    event = args.event
+    phase = state.get("phase")
+
+    if event == "candidate-grounded":
+        require(phase == "discovery", "candidate-grounded 只能发生在 discovery")
+        state["grounding_gate_status"] = "candidate_ready"
+    elif event == "grounding-gate-started":
+        require(
+            phase == "grounding_review"
+            or (phase == "discovery" and state.get("grounding_gate_status") == "candidate_ready"),
+            "grounding-gate 尚未具备调用条件",
+        )
+        state["phase"] = "grounding_review"
+        state["grounding_gate_status"] = "in_progress"
+        state["blocked_reason"] = None
+    elif event == "source-written":
+        require(phase == "design", "source-written 只能由 design 阶段提交")
+        state["phase"] = "source_review"
+        state["source_status"] = "written"
+        state["source_gate_status"] = "not_attempted"
+        state["source_snapshot_id"] = None
+        state["source_review_manifest"] = None
+        state["package_status"] = "not_started"
+        state["delivery_receipt"] = None
+        state["output_zip"] = None
+        state["invalid_receipt_attempts"]["source-gate"] = 0
+    elif event == "source-review-prepared":
+        require(phase == "source_review", "只能在 source_review 冻结送审源码")
+        require(state.get("source_status") == "written", "源码尚未登记为 written")
+        require(args.manifest is not None, "source-review-prepared 必须提供 --manifest")
+        snapshot, manifest = read_manifest(args.manifest)
+        state["source_status"] = "frozen"
+        state["source_snapshot_id"] = snapshot
+        state["source_review_manifest"] = str(manifest)
+        state["source_gate_status"] = "prepared"
+    elif event == "source-gate-started":
+        require(phase == "source_review", "source-gate 只能发生在 source_review")
+        require(
+            state.get("source_gate_status") in {"prepared", "invalid_receipt"},
+            "source-gate 尚未冻结源码或不在可重试状态",
+        )
+        state["source_gate_status"] = "in_progress"
+        state["blocked_reason"] = None
+    elif event == "source-changed":
+        require(phase in {"source_review", "packaging", "ready_for_handoff"}, "当前没有可失效的源码许可")
+        state["phase"] = "source_review"
+        state["source_status"] = "written"
+        state["source_gate_status"] = "not_attempted"
+        state["source_snapshot_id"] = None
+        state["source_review_manifest"] = None
+        state["package_status"] = "not_started"
+        state["delivery_receipt"] = None
+        state["output_zip"] = None
+        state["invalid_receipt_attempts"]["source-gate"] = 0
+    elif event == "review-tool-unavailable":
+        require(args.gate is not None, "review-tool-unavailable 必须提供 --gate")
+        require(args.reason and args.failure_evidence, "Tool 不可用必须提供原因和真实失败依据")
+        expected_phase = "grounding_review" if args.gate == "grounding-gate" else "source_review"
+        require(phase == expected_phase, "Tool 不可用事件与当前阶段不一致")
+        state["phase"] = "blocked"
+        state[gate_status_key(args.gate)] = "tool_unavailable"
+        state["blocked_reason"] = {
+            "kind": "tool_unavailable",
+            "gate": args.gate,
+            "reason": args.reason,
+            "failure_evidence": args.failure_evidence,
+        }
+    elif event == "review-resume-authorized":
+        require(phase == "blocked", "只有 blocked 状态可以恢复评审")
+        require(args.gate is not None and args.reason, "恢复评审必须提供 gate 和原因")
+        if args.gate == "grounding-gate":
+            state["phase"] = "grounding_review"
+            state["grounding_gate_status"] = "candidate_ready"
+        else:
+            require(state.get("source_snapshot_id") is not None, "恢复 source-gate 前必须仍有冻结快照")
+            state["phase"] = "source_review"
+            state["source_gate_status"] = "prepared"
+        state["invalid_receipt_attempts"][args.gate] = 0
+        state["blocked_reason"] = None
+    else:
+        raise WorkflowError(f"未实现事件：{event}")
+
+    state["last_event"] = event
+    persist(args.state, state)
+    print_state(state)
+    return 0
+
+
+def gate_status_key(gate: str) -> str:
+    return "grounding_gate_status" if gate == "grounding-gate" else "source_gate_status"
+
+
+def mark_invalid_receipt(
+    state_path: Path,
+    state: dict[str, object],
+    gate: str,
+    reason: str,
+) -> int:
+    attempts = state["invalid_receipt_attempts"]
+    attempts[gate] = int(attempts.get(gate, 0)) + 1
+    state[gate_status_key(gate)] = "invalid_receipt"
+    state["last_event"] = f"{gate}-invalid-receipt"
+    maximum = int(state.get("max_invalid_receipt_retries", 1))
+    if attempts[gate] > maximum:
+        state["phase"] = "blocked"
+        state["blocked_reason"] = {
+            "kind": "invalid_receipt_retries_exhausted",
+            "gate": gate,
+            "reason": reason,
+        }
+    persist(state_path, state)
+    print_state(state)
+    print(f"receipt_validation={reason}")
+    return 2
+
+
+def run_receipt_validator(
+    validator: Path,
+    receipt: Path,
+    gate: str,
+    expected_round: int,
+    snapshot: str | None,
+) -> subprocess.CompletedProcess[str]:
+    command = [
+        sys.executable,
+        str(validator.resolve()),
+        str(receipt.resolve()),
+        "--expected-mode",
+        gate,
+        "--expected-round",
+        str(expected_round),
+    ]
+    if gate == "source-gate":
+        if snapshot is None:
+            raise WorkflowError("source-gate 状态缺少冻结快照")
+        command.extend(["--expected-snapshot", snapshot])
+    return subprocess.run(command, text=True, capture_output=True, encoding="utf-8")
+
+
+def apply_gate_receipt(args: argparse.Namespace) -> int:
+    state = load_state(args.state)
+    gate = args.gate
+    expected_phase = "grounding_review" if gate == "grounding-gate" else "source_review"
+    require(state.get("phase") == expected_phase, "评审收据与当前阶段不一致")
+    require(state.get(gate_status_key(gate)) == "in_progress", "当前没有等待中的评审调用")
+
+    try:
+        receipt = load_json(args.receipt)
+    except WorkflowError as exc:
+        return mark_invalid_receipt(args.state, state, gate, str(exc))
+
+    result = run_receipt_validator(
+        args.validator,
+        args.receipt,
+        gate,
+        args.expected_round,
+        str(state.get("source_snapshot_id")) if gate == "source-gate" else None,
+    )
+    if result.returncode != 0:
+        detail = (result.stdout + result.stderr).strip() or "收据校验器失败"
+        return mark_invalid_receipt(args.state, state, gate, detail)
+
+    verdict = receipt.get("verdict")
+    state[gate_status_key(gate)] = verdict
+    state["invalid_receipt_attempts"][gate] = 0
+    state["blocked_reason"] = None
+    state["last_event"] = f"{gate}-{verdict}"
+
+    if gate == "grounding-gate":
+        if verdict == "pass":
+            state["phase"] = "design"
+        elif verdict in {"revision_required", "insufficient_basis"}:
+            state["phase"] = "discovery"
+        else:
+            raise WorkflowError(f"不支持的 grounding verdict：{verdict}")
+    else:
+        if verdict == "pass":
+            state["phase"] = "packaging"
+            state["package_status"] = "not_started"
+        elif verdict == "revision_required":
+            state["phase"] = "design"
+            state["source_status"] = "written"
+            state["source_snapshot_id"] = None
+            state["source_review_manifest"] = None
+            state["package_status"] = "not_started"
+        elif verdict == "insufficient_basis":
+            state["phase"] = "discovery"
+            state["grounding_gate_status"] = "insufficient_basis"
+            state["source_status"] = "written"
+            state["source_snapshot_id"] = None
+            state["source_review_manifest"] = None
+            state["package_status"] = "not_started"
+        else:
+            raise WorkflowError(f"不支持的 source verdict：{verdict}")
+
+    persist(args.state, state)
+    print_state(state)
+    return 0
+
+
+def apply_delivery(args: argparse.Namespace) -> int:
+    state = load_state(args.state)
+    require(state.get("phase") == "packaging", "只有 source-gate pass 后才能接收交付收据")
+    receipt = load_json(args.receipt)
+    require(receipt.get("package_status") == "packaged_verified", "交付收据没有 packaged_verified")
+    require(receipt.get("handoff_status") == "ready_for_handoff", "交付收据没有 ready_for_handoff")
+    require(receipt.get("source_snapshot_id") == state.get("source_snapshot_id"), "交付收据与当前源码快照不一致")
+    output_zip = receipt.get("output_zip")
+    require(isinstance(output_zip, str) and output_zip.strip(), "交付收据缺少 output_zip")
+    zip_path = Path(output_zip).resolve()
+    require(zip_path.is_file(), f"最终 ZIP 不存在：{zip_path}")
+
+    state["phase"] = "ready_for_handoff"
+    state["package_status"] = "packaged_verified"
+    state["delivery_receipt"] = str(args.receipt.resolve())
+    state["output_zip"] = str(zip_path)
+    state["blocked_reason"] = None
+    state["last_event"] = "delivery-receipt-validated"
+    persist(args.state, state)
+    print_state(state)
+    return 0
+
+
+def is_terminal(state: dict[str, object]) -> bool:
+    output_zip = state.get("output_zip")
+    return (
+        state.get("phase") == "ready_for_handoff"
+        and state.get("package_status") == "packaged_verified"
+        and isinstance(state.get("delivery_receipt"), str)
+        and isinstance(output_zip, str)
+        and Path(output_zip).is_file()
+    )
+
+
+def print_state(state: dict[str, object]) -> None:
+    print(json.dumps(state, ensure_ascii=False, indent=2))
+    print(f"terminal={'true' if is_terminal(state) else 'false'}")
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        if args.command == "init":
+            return initialize(args)
+        if args.command == "event":
+            return apply_event(args)
+        if args.command == "gate":
+            return apply_gate_receipt(args)
+        if args.command == "delivery":
+            return apply_delivery(args)
+        state = load_state(args.state)
+        print_state(state)
+        if args.command == "check-terminal":
+            if not is_terminal(state):
+                print("WORKFLOW_NOT_TERMINAL：完整源码交付尚未取得有效终结器收据与最终 ZIP")
+                return 1
+            if state.get("workflow_mode") == "host_integrated":
+                print("WORKFLOW_TERMINAL：宿主控制链已到终态，可以提供已验证 ZIP 的准确路径")
+            else:
+                print("WORKFLOW_TERMINAL_REFERENCE_ONLY：本次显式调用链已到终态，但未证明宿主已绑定自动 Hook")
+        return 0
+    except WorkflowError as exc:
+        print(f"WORKFLOW_FAIL：{exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+