feat(governance): 新增 release decision readback
All checks were successful
Code Review / ai-code-review (push) Successful in 18s
CD Pipeline / tests (push) Successful in 1m42s
CD Pipeline / build-and-deploy (push) Successful in 5m12s
CD Pipeline / post-deploy-checks (push) Successful in 1m32s

This commit is contained in:
Your Name
2026-06-14 11:43:03 +08:00
parent de884089d6
commit d41b1a383e
13 changed files with 1880 additions and 5 deletions

View File

@@ -124,6 +124,9 @@ from src.services.ai_agent_result_capture_no_write_readback import (
from src.services.ai_agent_result_capture_release_decision_hold import (
load_latest_ai_agent_result_capture_release_decision_hold,
)
from src.services.ai_agent_result_capture_release_decision_readback import (
load_latest_ai_agent_result_capture_release_decision_readback,
)
from src.services.ai_agent_result_capture_owner_promotion_review import (
load_latest_ai_agent_result_capture_owner_promotion_review,
)
@@ -2291,6 +2294,37 @@ async def get_agent_result_capture_release_decision_hold() -> dict[str, Any]:
) from exc
@router.get(
"/agent-result-capture-release-decision-readback",
response_model=dict[str, Any],
summary="取得 AI Agent result capture release decision readback",
description=(
"讀取最新已提交的 P2-139 release decision readback"
"此端點只回讀 P2-138 release decision hold 後的釋出、負責人、驗證器、回滾、"
"維護窗口與正式套用決策狀態,"
"不把 hold 視為決策通過、不授權 owner release、不核發 release authorization、"
"不寫 reviewer queue、Gateway queue、receipt、result capture、learning 或 PlayBook trust"
"不送 Telegram、不呼叫 Bot API、不讀 secret、不執行 production 寫入。"
),
)
async def get_agent_result_capture_release_decision_readback() -> dict[str, Any]:
"""Return the latest read-only release decision readback."""
try:
payload = await asyncio.to_thread(load_latest_ai_agent_result_capture_release_decision_readback)
return redact_public_lan_topology(payload)
except FileNotFoundError as exc:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=str(exc),
) from exc
except (json.JSONDecodeError, ValueError) as exc:
logger.error("ai_agent_result_capture_release_decision_readback_invalid", error=str(exc))
raise HTTPException(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail="AI Agent result capture release decision readback 無效",
) from exc
@router.get(
"/agent-owner-approved-fixture-dry-run",
response_model=dict[str, Any],

View File

@@ -0,0 +1,345 @@
"""
AI Agent result capture release decision readback snapshot.
Loads the latest committed P2-139 release decision readback. This module only
reads committed evidence from P2-138 release decision hold; it never treats a
hold as a passed decision, grants release authorization, writes reviewer /
Gateway queues, sends Telegram messages, writes result capture, writes learning
records, updates PlayBook trust, reads secrets, writes production targets, or
performs destructive operations.
"""
from __future__ import annotations
import json
import re
from pathlib import Path
from typing import Any
from src.services.snapshot_paths import default_evaluations_dir
_DEFAULT_EVALUATIONS_DIR = default_evaluations_dir(Path(__file__))
_SNAPSHOT_PATTERN = "ai_agent_result_capture_release_decision_readback_*.json"
_SCHEMA_VERSION = "ai_agent_result_capture_release_decision_readback_v1"
_RUNTIME_AUTHORITY = "result_capture_release_decision_readback_only_no_live_write"
def load_latest_ai_agent_result_capture_release_decision_readback(
evaluations_dir: Path | None = None,
) -> dict[str, Any]:
"""Load the newest committed release decision readback."""
directory = evaluations_dir or _DEFAULT_EVALUATIONS_DIR
candidates = sorted(directory.glob(_SNAPSHOT_PATTERN))
if not candidates:
raise FileNotFoundError(f"no AI Agent result capture release decision readback snapshots found in {directory}")
latest = candidates[-1]
with latest.open(encoding="utf-8") as handle:
payload = json.load(handle)
if not isinstance(payload, dict):
raise ValueError(f"{latest}: expected JSON object")
label = str(latest)
_require_schema(payload, label)
_require_prior(payload, label)
_require_truth(payload, label)
_require_readback_groups(payload, label)
_require_blocked_transitions(payload, label)
_require_actions(payload, label)
_require_display_redaction(payload, label)
_require_no_forbidden_display_terms(payload, label)
_require_rollup_consistency(payload, label)
return payload
def _require_schema(payload: dict[str, Any], label: str) -> None:
if payload.get("schema_version") != _SCHEMA_VERSION:
raise ValueError(f"{label}: expected schema_version={_SCHEMA_VERSION}")
status = payload.get("program_status") or {}
expected = {
"current_priority": "P2",
"current_task_id": "P2-139",
"next_task_id": "P2-140",
"read_only_mode": True,
"runtime_authority": _RUNTIME_AUTHORITY,
"overall_completion_percent": 100,
}
mismatches = _mismatches(status, expected)
if mismatches:
raise ValueError(f"{label}: program_status mismatch: {mismatches}")
if not status.get("status_note"):
raise ValueError(f"{label}: program_status.status_note is required")
def _require_prior(payload: dict[str, Any], label: str) -> None:
prior = payload.get("prior_release_decision_hold") or {}
expected = {
"schema_version": "ai_agent_result_capture_release_decision_hold_v1",
"release_decision_hold_count": 5,
"owner_decision_hold_count": 5,
"verifier_decision_hold_count": 5,
"rollback_decision_hold_count": 5,
"maintenance_window_decision_hold_count": 5,
"live_apply_decision_hold_count": 5,
"blocked_decision_transition_count": 6,
"operator_action_count": 5,
"approval_required_total": 12,
"blocked_total": 12,
}
expected.update(_zero_count_expectations())
mismatches = _mismatches(prior, expected)
if mismatches:
raise ValueError(f"{label}: prior_release_decision_hold mismatch: {mismatches}")
if not prior.get("readiness_note"):
raise ValueError(f"{label}: prior_release_decision_hold.readiness_note is required")
def _require_truth(payload: dict[str, Any], label: str) -> None:
truth = payload.get("release_decision_readback_truth") or {}
required_true = {
"p2_138_release_decision_hold_loaded",
"release_decision_readback_ready",
"owner_decision_still_required",
"verifier_decision_still_required",
"rollback_decision_still_required",
"maintenance_window_decision_still_required",
"live_apply_decision_still_required",
"redaction_review_still_required",
"release_decision_readback_only",
}
missing = sorted(field for field in required_true if truth.get(field) is not True)
if missing:
raise ValueError(f"{label}: release decision readback flags must remain true: {missing}")
required_false = {
"owner_release_authorized",
"owner_release_approved",
"owner_review_approved",
"owner_decision_approved",
"verifier_decision_approved",
"maintenance_window_approved",
"rollback_owner_confirmed",
"post_release_verifier_ready",
"final_release_candidate_approved",
"final_release_candidate_passed",
"release_decision_passed",
"release_authorization_granted",
"release_authorization_passed",
"rollback_release_passed",
"live_apply_release_passed",
"writer_apply_enabled",
"execution_apply_enabled",
"receipt_write_enabled",
"reviewer_queue_write_enabled",
"gateway_queue_write_enabled",
"telegram_send_enabled",
"bot_api_call_enabled",
"report_receipt_write_enabled",
"result_capture_write_enabled",
"learning_write_enabled",
"playbook_trust_write_enabled",
"production_write_enabled",
"secret_read_enabled",
"destructive_operation_enabled",
}
unsafe = sorted(field for field in required_false if truth.get(field) is not False)
if unsafe:
raise ValueError(f"{label}: release decision readback live/send/write flags must remain false: {unsafe}")
non_zero = sorted(field for field in _zero_count_expectations() if truth.get(field) != 0)
if non_zero:
raise ValueError(f"{label}: release decision readback live counters must remain zero: {non_zero}")
if not truth.get("truth_note"):
raise ValueError(f"{label}: release_decision_readback_truth.truth_note is required")
def _require_readback_groups(payload: dict[str, Any], label: str) -> None:
groups = {
"release_decision_readbacks": ("readback_id", "release_decision_readback", "release decision readbacks"),
"owner_decision_readbacks": ("readback_id", "owner_decision_readback", "owner decision readbacks"),
"verifier_decision_readbacks": ("readback_id", "verifier_decision_readback", "verifier decision readbacks"),
"rollback_decision_readbacks": ("readback_id", "rollback_decision_readback", "rollback decision readbacks"),
"maintenance_window_decision_readbacks": ("readback_id", "maintenance_window_decision_readback", "maintenance window decision readbacks"),
"live_apply_decision_readbacks": ("readback_id", "live_apply_decision_readback", "live apply decision readbacks"),
}
for field, (id_field, mode, group_name) in groups.items():
items = payload.get(field) or []
_require_ids(items, id_field, _expected_ids(mode), label, group_name)
for item in items:
item_id = item.get(id_field)
if item.get("readback_mode") != mode:
raise ValueError(f"{label}: {group_name} {item_id} mode is invalid")
if item.get("readback_status") not in {"readback_complete", "approval_required", "blocked_by_policy"}:
raise ValueError(f"{label}: {group_name} {item_id} readback_status is invalid")
if not item.get("readback_summary"):
raise ValueError(f"{label}: {group_name} {item_id}.readback_summary is required")
if item.get("release_decision_passed") is not False:
raise ValueError(f"{label}: {group_name} {item_id} must keep release_decision_passed=false")
if item.get("release_authorization_granted") is not False:
raise ValueError(f"{label}: {group_name} {item_id} must keep release_authorization_granted=false")
if item.get("runtime_write_allowed") is not False:
raise ValueError(f"{label}: {group_name} {item_id} must keep runtime_write_allowed=false")
if item.get("telegram_send_allowed") is not False:
raise ValueError(f"{label}: {group_name} {item_id} must keep telegram_send_allowed=false")
if "evidence_hash" in item and not _is_redacted_sha256(item.get("evidence_hash")):
raise ValueError(f"{label}: {group_name} {item_id}.evidence_hash must be redacted sha256")
def _require_blocked_transitions(payload: dict[str, Any], label: str) -> None:
items = payload.get("blocked_readback_transitions") or []
_require_count(items, 6, label, "blocked readback transitions")
for item in items:
item_id = item.get("transition_id")
if item.get("runtime_write_allowed") is not False:
raise ValueError(f"{label}: blocked readback transition {item_id} must keep runtime_write_allowed=false")
if item.get("status") not in {"blocked_by_policy", "approval_required"}:
raise ValueError(f"{label}: blocked readback transition {item_id} status is invalid")
if not item.get("reason"):
raise ValueError(f"{label}: blocked readback transition {item_id}.reason is required")
def _require_actions(payload: dict[str, Any], label: str) -> None:
items = payload.get("operator_actions") or []
_require_count(items, 5, label, "operator actions")
for item in items:
item_id = item.get("action_id")
if item.get("runtime_write_allowed") is not False:
raise ValueError(f"{label}: operator action {item_id} must keep runtime_write_allowed=false")
if item.get("status") not in {"ready_for_operator_review", "approval_required"}:
raise ValueError(f"{label}: operator action {item_id} status is invalid")
if not item.get("operator_instruction"):
raise ValueError(f"{label}: operator action {item_id}.operator_instruction is required")
def _require_display_redaction(payload: dict[str, Any], label: str) -> None:
contract = payload.get("display_redaction_contract") or {}
expected = {
"redaction_required": True,
"raw_prompt_display_allowed": False,
"private_reasoning_display_allowed": False,
"secret_value_display_allowed": False,
"raw_runtime_payload_display_allowed": False,
"internal_collaboration_content_display_allowed": False,
}
mismatches = _mismatches(contract, expected)
if mismatches:
raise ValueError(f"{label}: display_redaction_contract mismatch: {mismatches}")
if not contract.get("frontend_display_policy"):
raise ValueError(f"{label}: display_redaction_contract.frontend_display_policy is required")
def _require_rollup_consistency(payload: dict[str, Any], label: str) -> None:
rollups = payload.get("rollups") or {}
expected = {
"release_decision_readback_count": len(payload.get("release_decision_readbacks") or []),
"owner_decision_readback_count": len(payload.get("owner_decision_readbacks") or []),
"verifier_decision_readback_count": len(payload.get("verifier_decision_readbacks") or []),
"rollback_decision_readback_count": len(payload.get("rollback_decision_readbacks") or []),
"maintenance_window_decision_readback_count": len(payload.get("maintenance_window_decision_readbacks") or []),
"live_apply_decision_readback_count": len(payload.get("live_apply_decision_readbacks") or []),
"blocked_readback_transition_count": len(payload.get("blocked_readback_transitions") or []),
"operator_action_count": len(payload.get("operator_actions") or []),
}
expected.update(_zero_count_expectations())
mismatches = _mismatches(rollups, expected)
if mismatches:
raise ValueError(f"{label}: rollups mismatch: {mismatches}")
def _require_no_forbidden_display_terms(payload: Any, label: str) -> None:
forbidden = {
"work_window_transcript",
"internal_collaboration_transcript",
"raw_prompt",
"private_reasoning",
"chain_of_thought",
"authorization_header",
"secret_value",
}
found = sorted(term for term in forbidden if _contains_term(payload, term))
if found:
raise ValueError(f"{label}: forbidden display terms leaked: {found}")
def _contains_term(value: Any, term: str) -> bool:
if isinstance(value, str):
return term.lower() in value.lower()
if isinstance(value, dict):
return any(_contains_term(child, term) for child in value.values())
if isinstance(value, list):
return any(_contains_term(child, term) for child in value)
return False
def _zero_count_expectations() -> dict[str, int]:
return {
"owner_release_authorized_count": 0,
"owner_release_approved_count": 0,
"owner_review_approved_count": 0,
"owner_decision_approved_count": 0,
"verifier_decision_approved_count": 0,
"maintenance_window_approved_count": 0,
"rollback_owner_confirmed_count": 0,
"post_release_verifier_ready_count": 0,
"final_release_candidate_approved_count": 0,
"final_release_candidate_pass_count": 0,
"release_decision_pass_count": 0,
"release_authorization_granted_count": 0,
"release_authorization_pass_count": 0,
"rollback_release_pass_count": 0,
"live_apply_release_pass_count": 0,
"writer_apply_count": 0,
"execution_apply_count": 0,
"receipt_write_count": 0,
"reviewer_queue_write_count": 0,
"gateway_queue_write_count": 0,
"telegram_send_count": 0,
"bot_api_call_count": 0,
"report_receipt_write_count": 0,
"result_capture_write_count": 0,
"learning_write_count": 0,
"playbook_trust_write_count": 0,
"production_write_count": 0,
"secret_read_count": 0,
"destructive_operation_count": 0,
}
def _expected_ids(mode: str) -> set[str]:
return {
f"{mode}_result_capture",
f"{mode}_learning",
f"{mode}_playbook_trust",
f"{mode}_reviewer_queue",
f"{mode}_gateway_queue",
}
def _require_ids(
items: list[dict[str, Any]],
field: str,
expected_ids: set[str],
label: str,
group_name: str,
) -> None:
actual_ids = {str(item.get(field)) for item in items}
if actual_ids != expected_ids:
raise ValueError(f"{label}: {group_name} ids mismatch: expected={sorted(expected_ids)} actual={sorted(actual_ids)}")
def _require_count(items: list[Any], expected: int, label: str, group_name: str) -> None:
if len(items) != expected:
raise ValueError(f"{label}: expected {expected} {group_name}, got {len(items)}")
def _is_redacted_sha256(value: Any) -> bool:
return isinstance(value, str) and re.fullmatch(r"sha256:[0-9a-f]{64}", value) is not None
def _mismatches(payload: dict[str, Any], expected: dict[str, Any]) -> dict[str, dict[str, Any]]:
return {
key: {"expected": expected_value, "actual": payload.get(key)}
for key, expected_value in expected.items()
if payload.get(key) != expected_value
}

View File

@@ -0,0 +1,124 @@
from __future__ import annotations
import copy
import json
from pathlib import Path
import pytest
from src.services.ai_agent_result_capture_release_decision_readback import (
load_latest_ai_agent_result_capture_release_decision_readback,
)
def test_load_latest_release_decision_readback_snapshot() -> None:
snapshot = load_latest_ai_agent_result_capture_release_decision_readback()
assert snapshot["schema_version"] == "ai_agent_result_capture_release_decision_readback_v1"
assert snapshot["program_status"]["current_task_id"] == "P2-139"
assert snapshot["program_status"]["next_task_id"] == "P2-140"
assert snapshot["program_status"]["overall_completion_percent"] == 100
assert snapshot["program_status"]["runtime_authority"] == "result_capture_release_decision_readback_only_no_live_write"
rollups = snapshot["rollups"]
assert rollups["release_decision_readback_count"] == 5
assert rollups["owner_decision_readback_count"] == 5
assert rollups["verifier_decision_readback_count"] == 5
assert rollups["rollback_decision_readback_count"] == 5
assert rollups["maintenance_window_decision_readback_count"] == 5
assert rollups["live_apply_decision_readback_count"] == 5
assert rollups["blocked_readback_transition_count"] == 6
assert rollups["operator_action_count"] == 5
assert (
rollups["approval_required_release_decision_count"]
+ rollups["approval_required_owner_decision_count"]
+ rollups["approval_required_verifier_decision_count"]
+ rollups["approval_required_rollback_decision_count"]
+ rollups["approval_required_maintenance_window_decision_count"]
+ rollups["approval_required_live_apply_decision_count"]
) == 12
assert (
rollups["blocked_release_decision_count"]
+ rollups["blocked_owner_decision_count"]
+ rollups["blocked_verifier_decision_count"]
+ rollups["blocked_rollback_decision_count"]
+ rollups["blocked_maintenance_window_decision_count"]
+ rollups["blocked_live_apply_decision_count"]
+ rollups["critical_blocker_count"]
) == 12
assert rollups["owner_release_authorized_count"] == 0
assert rollups["owner_decision_approved_count"] == 0
assert rollups["maintenance_window_approved_count"] == 0
assert rollups["release_decision_pass_count"] == 0
assert rollups["release_authorization_granted_count"] == 0
assert rollups["reviewer_queue_write_count"] == 0
assert rollups["gateway_queue_write_count"] == 0
assert rollups["telegram_send_count"] == 0
assert rollups["result_capture_write_count"] == 0
assert rollups["learning_write_count"] == 0
assert rollups["playbook_trust_write_count"] == 0
assert rollups["production_write_count"] == 0
def test_release_decision_readback_truth_keeps_all_live_paths_closed() -> None:
snapshot = load_latest_ai_agent_result_capture_release_decision_readback()
truth = snapshot["release_decision_readback_truth"]
assert truth["p2_138_release_decision_hold_loaded"] is True
assert truth["release_decision_readback_ready"] is True
assert truth["owner_decision_still_required"] is True
assert truth["maintenance_window_decision_still_required"] is True
assert truth["release_decision_readback_only"] is True
assert truth["owner_release_authorized"] is False
assert truth["owner_decision_approved"] is False
assert truth["maintenance_window_approved"] is False
assert truth["release_decision_passed"] is False
assert truth["release_authorization_granted"] is False
assert truth["reviewer_queue_write_enabled"] is False
assert truth["gateway_queue_write_enabled"] is False
assert truth["telegram_send_enabled"] is False
assert truth["production_write_enabled"] is False
assert truth["secret_read_enabled"] is False
assert truth["destructive_operation_enabled"] is False
def test_rejects_release_decision_passed(tmp_path: Path) -> None:
snapshot = copy.deepcopy(load_latest_ai_agent_result_capture_release_decision_readback())
snapshot["release_decision_readbacks"][0]["release_decision_passed"] = True
_write_snapshot(tmp_path, snapshot)
with pytest.raises(ValueError, match="must keep release_decision_passed=false"):
load_latest_ai_agent_result_capture_release_decision_readback(tmp_path)
def test_rejects_release_authorization_granted(tmp_path: Path) -> None:
snapshot = copy.deepcopy(load_latest_ai_agent_result_capture_release_decision_readback())
snapshot["owner_decision_readbacks"][0]["release_authorization_granted"] = True
_write_snapshot(tmp_path, snapshot)
with pytest.raises(ValueError, match="must keep release_authorization_granted=false"):
load_latest_ai_agent_result_capture_release_decision_readback(tmp_path)
def test_rejects_queue_write_drift(tmp_path: Path) -> None:
snapshot = copy.deepcopy(load_latest_ai_agent_result_capture_release_decision_readback())
snapshot["rollups"]["gateway_queue_write_count"] = 1
_write_snapshot(tmp_path, snapshot)
with pytest.raises(ValueError, match="rollups mismatch"):
load_latest_ai_agent_result_capture_release_decision_readback(tmp_path)
def test_rejects_forbidden_display_terms(tmp_path: Path) -> None:
snapshot = copy.deepcopy(load_latest_ai_agent_result_capture_release_decision_readback())
snapshot["operator_actions"][0]["operator_instruction"] = "不要顯示 raw_prompt"
_write_snapshot(tmp_path, snapshot)
with pytest.raises(ValueError, match="forbidden display terms leaked"):
load_latest_ai_agent_result_capture_release_decision_readback(tmp_path)
def _write_snapshot(directory: Path, payload: dict) -> None:
path = directory / "ai_agent_result_capture_release_decision_readback_2099-01-01.json"
path.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")

View File

@@ -0,0 +1,39 @@
from __future__ import annotations
from fastapi.testclient import TestClient
from src.main import app
def test_release_decision_readback_endpoint() -> None:
client = TestClient(app)
response = client.get("/api/v1/agents/agent-result-capture-release-decision-readback")
assert response.status_code == 200
payload = response.json()
assert payload["schema_version"] == "ai_agent_result_capture_release_decision_readback_v1"
assert payload["program_status"]["current_task_id"] == "P2-139"
assert payload["program_status"]["next_task_id"] == "P2-140"
assert payload["program_status"]["overall_completion_percent"] == 100
assert payload["program_status"]["runtime_authority"] == "result_capture_release_decision_readback_only_no_live_write"
assert payload["prior_release_decision_hold"]["schema_version"] == "ai_agent_result_capture_release_decision_hold_v1"
assert payload["rollups"]["release_decision_readback_count"] == 5
assert payload["rollups"]["owner_decision_readback_count"] == 5
assert payload["rollups"]["verifier_decision_readback_count"] == 5
assert payload["rollups"]["rollback_decision_readback_count"] == 5
assert payload["rollups"]["maintenance_window_decision_readback_count"] == 5
assert payload["rollups"]["live_apply_decision_readback_count"] == 5
assert payload["rollups"]["blocked_readback_transition_count"] == 6
assert payload["rollups"]["operator_action_count"] == 5
assert payload["rollups"]["owner_release_authorized_count"] == 0
assert payload["rollups"]["owner_review_approved_count"] == 0
assert payload["rollups"]["owner_decision_approved_count"] == 0
assert payload["rollups"]["maintenance_window_approved_count"] == 0
assert payload["rollups"]["release_decision_pass_count"] == 0
assert payload["rollups"]["release_authorization_granted_count"] == 0
assert payload["rollups"]["release_authorization_pass_count"] == 0
assert payload["rollups"]["reviewer_queue_write_count"] == 0
assert payload["rollups"]["gateway_queue_write_count"] == 0
assert payload["rollups"]["telegram_send_count"] == 0
assert payload["rollups"]["production_write_count"] == 0