agent-project-sdlc 0.1.21 → 0.1.23

package/assets/tools/harness_utils.py

@@ -55,6 +55,9 @@ TASK_PHASES = {
     "RELEASING",
     "RFC_RECALIBRATION",
 }
+RESERVED_SUSPENDED_PHASE_TARGET = "<suspended_phase>"
+TRANSITION_KINDS = {"normal", "return", "interrupt", "resume"}
+LEGACY_RFC_INTERRUPT_SOURCES = {"SPRINTING", "REVIEWING", "TESTING", "RELEASING"}
 
 
 class HarnessError(RuntimeError):
@@ -375,6 +378,41 @@ CALLABLE_TASK_TERMS = [
     "队列",
 ]
 SELF_TEST_CONTRACT_STATUSES = {"required", "not_applicable"}
+SELF_TEST_GRAPH_NODE_KINDS = {"entry", "checkpoint", "branch", "scenario", "observable_exit"}
+SELF_TEST_GRAPH_ORDINARY_NODE_LIMIT = 12
+SELF_TEST_GRAPH_HIGH_RISK_NODE_LIMIT = 25
+SELF_TEST_GRAPH_EVIDENCE_BODY_TERMS = [
+    "```",
+    "|---",
+    "actual evidence",
+    "command transcript",
+    "full command output",
+    "stdout",
+    "stderr",
+    "traceback",
+    "debug log",
+    "operator log",
+    "evidence dump",
+    "screenshot process",
+    "截图过程",
+    "调试日志",
+    "操作日志",
+    "证据正文",
+]
+RESUME_CAPSULE_REQUIRED_EVIDENCE_LEVELS = {"external_provider_live", "deployed_runtime", "business_handoff_ready"}
+RESUME_CAPSULE_REQUIRED_TARGET_KINDS = {"cloud_vm", "managed_service", "browser", "worker"}
+RESUME_CAPSULE_FIELDS = [
+    "task_id",
+    "state",
+    "canonical_path",
+    "next_step",
+    "blocker",
+    "last_passed_gate",
+    "do_not_retry",
+    "recovery_refs",
+]
+RUNBOOK_DOC_PREFIX = ".docs/09_runbooks/"
+MAX_WORKING_NOTES = 8
 
 
 def as_string_list(value: Any) -> list[str]:
@@ -417,6 +455,192 @@ def needs_runnable_task_contract(task: dict[str, Any]) -> bool:
     return contains_any(context, APPLICATION_READINESS_TASK_TERMS + PAGE_TASK_TERMS + CALLABLE_TASK_TERMS)
 
 
+def requires_resume_capsule(task: dict[str, Any]) -> bool:
+    if task.get("phase") != "SPRINTING":
+        return False
+    evidence_level = task.get("evidence_level")
+    target_runtime = task.get("target_runtime_environment")
+    required = str(evidence_level.get("required") or "") if isinstance(evidence_level, dict) else ""
+    kind = str(target_runtime.get("kind") or "") if isinstance(target_runtime, dict) else ""
+    return required in RESUME_CAPSULE_REQUIRED_EVIDENCE_LEVELS or kind in RESUME_CAPSULE_REQUIRED_TARGET_KINDS
+
+
+def self_test_graph_evidence_ref_is_body(value: str) -> bool:
+    stripped = value.strip()
+    lowered = stripped.lower()
+    return "\n" in stripped or len(stripped) > 180 or any(term in lowered for term in SELF_TEST_GRAPH_EVIDENCE_BODY_TERMS)
+
+
+def graph_has_cycle(node_ids: set[str], adjacency: dict[str, list[str]]) -> bool:
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(node_id: str) -> bool:
+        if node_id in visiting:
+            return True
+        if node_id in visited:
+            return False
+        visiting.add(node_id)
+        for target in adjacency.get(node_id, []):
+            if visit(target):
+                return True
+        visiting.remove(node_id)
+        visited.add(node_id)
+        return False
+
+    return any(visit(node_id) for node_id in node_ids if node_id not in visited)
+
+
+def reachable_from(entry_id: str, adjacency: dict[str, list[str]]) -> set[str]:
+    reached: set[str] = set()
+    stack = [entry_id]
+    while stack:
+        node_id = stack.pop()
+        if node_id in reached:
+            continue
+        reached.add(node_id)
+        stack.extend(adjacency.get(node_id, []))
+    return reached
+
+
+def nodes_that_can_reach_exits(node_ids: set[str], adjacency: dict[str, list[str]], exits: set[str]) -> set[str]:
+    reverse: dict[str, list[str]] = {node_id: [] for node_id in node_ids}
+    for source, targets in adjacency.items():
+        for target in targets:
+            reverse.setdefault(target, []).append(source)
+    reached: set[str] = set()
+    stack = list(exits)
+    while stack:
+        node_id = stack.pop()
+        if node_id in reached:
+            continue
+        reached.add(node_id)
+        stack.extend(reverse.get(node_id, []))
+    return reached
+
+
+def self_test_graph_errors_for_contract(
+    task_id: str,
+    contract: dict[str, Any],
+    scenario_ids: set[str],
+    high_risk_runtime: bool,
+) -> list[str]:
+    errors: list[str] = []
+    graph_required = contract.get("graph_required")
+    if graph_required is not None and not isinstance(graph_required, bool):
+        errors.append(f"{task_id} self_test_contract.graph_required must be a boolean when set")
+    graph = contract.get("module_key_test_graph")
+    if graph_required is True and not isinstance(graph, dict):
+        errors.append(f"{task_id} self_test_contract.module_key_test_graph is required when graph_required is true")
+    if graph is None:
+        return errors
+    if not isinstance(graph, dict):
+        errors.append(f"{task_id} self_test_contract.module_key_test_graph must be a mapping")
+        return errors
+
+    nodes = graph.get("nodes")
+    edges = graph.get("edges")
+    if not isinstance(nodes, list) or not nodes:
+        errors.append(f"{task_id} self_test_contract.module_key_test_graph.nodes must be a non-empty list")
+        return errors
+    if not isinstance(edges, list) or not edges:
+        errors.append(f"{task_id} self_test_contract.module_key_test_graph.edges must be a non-empty list")
+        return errors
+
+    node_limit = SELF_TEST_GRAPH_HIGH_RISK_NODE_LIMIT if high_risk_runtime else SELF_TEST_GRAPH_ORDINARY_NODE_LIMIT
+    if len(nodes) > node_limit:
+        errors.append(
+            f"{task_id} self_test_contract.module_key_test_graph has {len(nodes)} nodes; keep ordinary graphs <= {SELF_TEST_GRAPH_ORDINARY_NODE_LIMIT} nodes and high-risk graphs <= {SELF_TEST_GRAPH_HIGH_RISK_NODE_LIMIT} nodes"
+        )
+
+    node_ids: set[str] = set()
+    entry_ids: list[str] = []
+    observable_exit_ids: set[str] = set()
+    scenario_nodes_by_ref: dict[str, list[str]] = {}
+    adjacency: dict[str, list[str]] = {}
+
+    for index, node in enumerate(nodes):
+        if not isinstance(node, dict):
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph.nodes[{index}] must be a mapping")
+            continue
+        node_id = str(node.get("id") or "").strip()
+        kind = str(node.get("kind") or "").strip()
+        label = str(node.get("label") or "").strip()
+        if not node_id:
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph.nodes[{index}].id must be set")
+            continue
+        if node_id in node_ids:
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph node id must be unique: {node_id}")
+        node_ids.add(node_id)
+        adjacency.setdefault(node_id, [])
+        if kind not in SELF_TEST_GRAPH_NODE_KINDS:
+            errors.append(
+                f"{task_id} self_test_contract.module_key_test_graph.nodes[{node_id}].kind must be one of {', '.join(sorted(SELF_TEST_GRAPH_NODE_KINDS))}"
+            )
+        if not label or is_placeholder_evidence(label):
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph.nodes[{node_id}].label must be concrete")
+        if kind == "entry":
+            entry_ids.append(node_id)
+        if kind == "observable_exit":
+            observable_exit_ids.add(node_id)
+        if kind == "scenario":
+            scenario_ref = str(node.get("scenario_ref") or "").strip()
+            if not scenario_ref:
+                errors.append(f"{task_id} self_test_contract.module_key_test_graph scenario node {node_id} must set scenario_ref")
+            elif scenario_ref not in scenario_ids:
+                errors.append(f"{task_id} self_test_contract.module_key_test_graph scenario node {node_id} references unknown scenario: {scenario_ref}")
+            else:
+                scenario_nodes_by_ref.setdefault(scenario_ref, []).append(node_id)
+        evidence_ref = node.get("evidence_ref")
+        if evidence_ref is not None:
+            evidence_ref_text = str(evidence_ref).strip()
+            if not evidence_ref_text or is_placeholder_evidence(evidence_ref_text) or self_test_graph_evidence_ref_is_body(evidence_ref_text):
+                errors.append(f"{task_id} self_test_contract.module_key_test_graph.nodes[{node_id}].evidence_ref must be a short evidence pointer, not evidence body")
+
+    if len(entry_ids) != 1:
+        errors.append(f"{task_id} self_test_contract.module_key_test_graph must have exactly one entry node")
+    if not observable_exit_ids:
+        errors.append(f"{task_id} self_test_contract.module_key_test_graph must have at least one observable_exit node")
+
+    for index, edge in enumerate(edges):
+        if not isinstance(edge, dict):
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph.edges[{index}] must be a mapping")
+            continue
+        source = str(edge.get("from") or "").strip()
+        target = str(edge.get("to") or "").strip()
+        if source not in node_ids:
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph edge references unknown from node: {source or '<empty>'}")
+            continue
+        if target not in node_ids:
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph edge references unknown to node: {target or '<empty>'}")
+            continue
+        adjacency.setdefault(source, []).append(target)
+
+    if graph_has_cycle(node_ids, adjacency):
+        errors.append(f"{task_id} self_test_contract.module_key_test_graph must be a DAG; cycles are not allowed")
+
+    reached_from_entry: set[str] = set()
+    if len(entry_ids) == 1:
+        reached_from_entry = reachable_from(entry_ids[0], adjacency)
+        unreachable = sorted(node_ids - reached_from_entry)
+        if unreachable:
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph nodes must be reachable from entry: {', '.join(unreachable)}")
+    can_reach_exit = nodes_that_can_reach_exits(node_ids, adjacency, observable_exit_ids)
+
+    for scenario_id in sorted(scenario_ids):
+        scenario_node_ids = scenario_nodes_by_ref.get(scenario_id, [])
+        if not scenario_node_ids:
+            errors.append(f"{task_id} self_test_contract.module_key_test_graph must include a scenario node for {scenario_id}")
+            continue
+        for node_id in scenario_node_ids:
+            if reached_from_entry and node_id not in reached_from_entry:
+                errors.append(f"{task_id} self_test_contract.module_key_test_graph scenario {scenario_id} must be reachable from entry")
+            if node_id not in can_reach_exit:
+                errors.append(f"{task_id} self_test_contract.module_key_test_graph scenario {scenario_id} must reach an observable_exit")
+
+    return errors
+
+
 def self_test_contract_errors_for_task(task: dict[str, Any]) -> list[str]:
     task_id = str(task.get("id") or "Task")
     required_for_runnable = needs_runnable_task_contract(task)
@@ -459,24 +683,28 @@ def self_test_contract_errors_for_task(task: dict[str, Any]) -> list[str]:
             errors.append(f"{task_id} self_test_contract.required_gates must also appear in task required_gates: {gate}")
 
     scenarios = contract.get("scenarios")
+    scenario_ids: set[str] = set()
     if not isinstance(scenarios, list) or not scenarios:
         errors.append(f"{task_id} self_test_contract.scenarios must be a non-empty list")
-        return errors
-    seen: set[str] = set()
-    for index, scenario in enumerate(scenarios):
-        if not isinstance(scenario, dict):
-            errors.append(f"{task_id} self_test_contract.scenarios[{index}] must be a mapping")
-            continue
-        scenario_id = str(scenario.get("id") or "").strip()
-        if not scenario_id:
-            errors.append(f"{task_id} self_test_contract.scenarios[{index}].id must be set")
-        elif scenario_id in seen:
-            errors.append(f"{task_id} self_test_contract scenario id must be unique: {scenario_id}")
-        seen.add(scenario_id)
-        for field in ["entry", "expected_exit", "evidence"]:
-            value = str(scenario.get(field) or "").strip()
-            if not value or is_placeholder_evidence(value):
-                errors.append(f"{task_id} self_test_contract.scenarios[{scenario_id or index}].{field} must be concrete")
+    else:
+        seen: set[str] = set()
+        for index, scenario in enumerate(scenarios):
+            if not isinstance(scenario, dict):
+                errors.append(f"{task_id} self_test_contract.scenarios[{index}] must be a mapping")
+                continue
+            scenario_id = str(scenario.get("id") or "").strip()
+            if not scenario_id:
+                errors.append(f"{task_id} self_test_contract.scenarios[{index}].id must be set")
+            elif scenario_id in seen:
+                errors.append(f"{task_id} self_test_contract scenario id must be unique: {scenario_id}")
+            else:
+                scenario_ids.add(scenario_id)
+            seen.add(scenario_id)
+            for field in ["entry", "expected_exit", "evidence"]:
+                value = str(scenario.get(field) or "").strip()
+                if not value or is_placeholder_evidence(value):
+                    errors.append(f"{task_id} self_test_contract.scenarios[{scenario_id or index}].{field} must be concrete")
+    errors.extend(self_test_graph_errors_for_contract(task_id, contract, scenario_ids, requires_resume_capsule(task)))
     return errors
 
 
@@ -619,12 +847,178 @@ def load_lifecycle() -> dict[str, Any]:
     return data
 
 
-def load_phase_contracts() -> dict[str, Any]:
+def load_phase_contract_data() -> dict[str, Any]:
     data = load_yaml(".codex/pjsdlc_managed/policies/phase_contracts.yaml")
     require(isinstance(data, dict) and isinstance(data.get("phases"), dict), "phase_contracts.yaml must contain phases")
+    return data
+
+
+def load_phase_contracts() -> dict[str, Any]:
+    data = load_phase_contract_data()
     return data["phases"]
 
 
+def legacy_phase_transition_edges(phases: dict[str, Any]) -> list[dict[str, Any]]:
+    edges: list[dict[str, Any]] = []
+    for phase_name, contract in phases.items():
+        if not isinstance(contract, dict):
+            continue
+        next_phase = contract.get("next")
+        if next_phase:
+            edges.append({"from": str(phase_name), "to": str(next_phase), "trigger": "advance", "kind": "normal"})
+        for return_phase in contract.get("returns") or []:
+            if return_phase:
+                edges.append({"from": str(phase_name), "to": str(return_phase), "trigger": "return", "kind": "return"})
+
+    if "RFC_RECALIBRATION" in phases:
+        for phase_name in sorted(LEGACY_RFC_INTERRUPT_SOURCES & set(phases.keys())):
+            edges.append(
+                {
+                    "from": phase_name,
+                    "to": "RFC_RECALIBRATION",
+                    "trigger": "requirement_change",
+                    "kind": "interrupt",
+                    "effects": {"set_suspended_phase": True},
+                }
+            )
+    if "BLOCKED" in phases:
+        for phase_name in phases:
+            if phase_name == "BLOCKED":
+                continue
+            edges.append(
+                {
+                    "from": str(phase_name),
+                    "to": "BLOCKED",
+                    "trigger": "blocked",
+                    "kind": "interrupt",
+                    "effects": {"set_suspended_phase": True},
+                }
+            )
+        edges.append(
+            {
+                "from": "BLOCKED",
+                "to": RESERVED_SUSPENDED_PHASE_TARGET,
+                "trigger": "resume",
+                "kind": "resume",
+                "effects": {"clear_suspended_phase": True},
+            }
+        )
+    return edges
+
+
+def phase_transition_edges(contract_data: dict[str, Any]) -> list[dict[str, Any]]:
+    phases = contract_data.get("phases")
+    require(isinstance(phases, dict), "phase_contracts.yaml must contain phases")
+    transitions = contract_data.get("transitions")
+    if isinstance(transitions, list):
+        return [edge for edge in transitions if isinstance(edge, dict)]
+    return legacy_phase_transition_edges(phases)
+
+
+def resolve_phase_transition_target(edge: dict[str, Any], suspended_phase: str = "") -> str:
+    target = str(edge.get("to") or "")
+    if target == RESERVED_SUSPENDED_PHASE_TARGET:
+        return suspended_phase
+    return target
+
+
+def phase_transition_targets(contract_data: dict[str, Any], phase_name: str, suspended_phase: str = "") -> list[str]:
+    targets: list[str] = []
+    for edge in phase_transition_edges(contract_data):
+        if str(edge.get("from") or "") != phase_name:
+            continue
+        target = resolve_phase_transition_target(edge, suspended_phase)
+        if target:
+            targets.append(target)
+    return list(dict.fromkeys(targets))
+
+
+def find_phase_transition(
+    contract_data: dict[str, Any],
+    from_phase: str,
+    to_phase: str,
+    suspended_phase: str = "",
+) -> dict[str, Any] | None:
+    for edge in phase_transition_edges(contract_data):
+        if str(edge.get("from") or "") != from_phase:
+            continue
+        if resolve_phase_transition_target(edge, suspended_phase) == to_phase:
+            return edge
+    return None
+
+
+def phase_transition_contract_errors(contract_data: dict[str, Any], require_transitions: bool = True) -> list[str]:
+    errors: list[str] = []
+    phases = contract_data.get("phases")
+    if not isinstance(phases, dict):
+        return ["phase_contracts.yaml must contain phases"]
+
+    for phase_name, contract in phases.items():
+        if not isinstance(contract, dict):
+            errors.append(f"{phase_name} phase contract must be a mapping")
+            continue
+        for legacy_key in ["next", "returns"]:
+            if legacy_key in contract:
+                errors.append(f"{phase_name} must not define legacy {legacy_key}; use top-level transitions")
+
+    transitions = contract_data.get("transitions")
+    if not isinstance(transitions, list):
+        if require_transitions:
+            errors.append("phase_contracts.yaml must contain top-level transitions")
+        return errors
+
+    phase_names = set(str(name) for name in phases.keys())
+    seen: set[tuple[str, str, str]] = set()
+    outgoing: set[str] = set()
+    for index, edge in enumerate(transitions, start=1):
+        prefix = f"transition #{index}"
+        if not isinstance(edge, dict):
+            errors.append(f"{prefix} must be a mapping")
+            continue
+        missing = [field for field in ["from", "to", "trigger", "kind"] if not str(edge.get(field) or "").strip()]
+        for field in missing:
+            errors.append(f"{prefix} missing {field}")
+        if missing:
+            continue
+
+        from_phase = str(edge["from"])
+        to_phase = str(edge["to"])
+        trigger = str(edge["trigger"])
+        kind = str(edge["kind"])
+        if from_phase not in phase_names:
+            errors.append(f"{prefix} from references unknown phase: {from_phase}")
+        if to_phase == RESERVED_SUSPENDED_PHASE_TARGET:
+            if from_phase != "BLOCKED" or kind != "resume":
+                errors.append(f"{prefix} may use {RESERVED_SUSPENDED_PHASE_TARGET} only for BLOCKED resume")
+        elif to_phase not in phase_names:
+            errors.append(f"{prefix} to references unknown phase: {to_phase}")
+        if kind not in TRANSITION_KINDS:
+            errors.append(f"{prefix} has invalid kind: {kind}")
+
+        key = (from_phase, to_phase, trigger)
+        if key in seen:
+            errors.append(f"{prefix} duplicates transition {from_phase} -> {to_phase} ({trigger})")
+        seen.add(key)
+        outgoing.add(from_phase)
+
+        effects = edge.get("effects")
+        if effects is None:
+            continue
+        if not isinstance(effects, dict):
+            errors.append(f"{prefix} effects must be a mapping")
+            continue
+        for effect_name, effect_value in effects.items():
+            if effect_name not in {"set_suspended_phase", "clear_suspended_phase"}:
+                errors.append(f"{prefix} has unknown effect: {effect_name}")
+            if not isinstance(effect_value, bool):
+                errors.append(f"{prefix} effect {effect_name} must be boolean")
+
+    for phase_name in phase_names:
+        if phase_name not in outgoing:
+            errors.append(f"{phase_name} must have at least one outgoing transition")
+    return errors
+
+
 def load_plan(path: str = ".codex/state/plan.yaml") -> dict[str, Any]:
     data = load_yaml(path)
     require(isinstance(data, dict), f"{path} must be a mapping")
@@ -658,6 +1052,16 @@ def validate_task_shape(task: dict[str, Any], index: int) -> None:
         require(isinstance(task["allowed_paths"], list) and task["allowed_paths"], f"{task['id']} must define allowed_paths")
         require(isinstance(task["required_gates"], list) and task["required_gates"], f"{task['id']} must define required_gates")
         require(isinstance(task["acceptance_criteria"], list) and task["acceptance_criteria"], f"{task['id']} must define acceptance_criteria")
+        if "working_notes" in task:
+            require(
+                isinstance(task["working_notes"], (list, str)),
+                f"{task['id']} working_notes must be a short string or list with at most {MAX_WORKING_NOTES} items",
+            )
+            note_count = len(task["working_notes"]) if isinstance(task["working_notes"], list) else (1 if str(task["working_notes"]).strip() else 0)
+            require(
+                note_count <= MAX_WORKING_NOTES,
+                f"{task['id']} working_notes must stay resume-first and contain at most {MAX_WORKING_NOTES} items; found {note_count}",
+            )
         for error in self_test_contract_errors_for_task(task):
             require(False, error)
         for error in testing_boundary_errors_for_allowed_paths(task):
@@ -672,6 +1076,54 @@ def task_sequence_number(task_id: str) -> int:
     return int(match.group(1)) if match else 0
 
 
+def validate_resume_capsule_contract(data: dict[str, Any]) -> None:
+    current_task_id = str(data.get("current_task_id") or "")
+    current_task = task_by_id(data, current_task_id) if current_task_id else None
+    if not current_task or current_task.get("status") not in OPEN_TASK_STATUSES or current_task.get("phase") != "SPRINTING":
+        require("resume_capsule" not in data, "plan.yaml resume_capsule must only be present for the current open SPRINTING task")
+        return
+
+    capsule = data.get("resume_capsule")
+    if not requires_resume_capsule(current_task):
+        if capsule is not None:
+            require(isinstance(capsule, dict), f"{current_task_id} resume_capsule must be a mapping when present")
+        return
+
+    require(isinstance(capsule, dict), f"{current_task_id} high-risk runtime task must define top-level resume_capsule")
+    for field in RESUME_CAPSULE_FIELDS:
+        require(field in capsule, f"{current_task_id} resume_capsule missing field: {field}")
+
+    require(str(capsule.get("task_id") or "").strip() == current_task_id, f"{current_task_id} resume_capsule.task_id must match current_task_id")
+    for field in ["state", "canonical_path", "next_step", "blocker", "last_passed_gate"]:
+        value = str(capsule.get(field) or "").strip()
+        require(value and not is_placeholder_evidence(value), f"{current_task_id} resume_capsule.{field} must contain concrete recovery information")
+
+    do_not_retry = as_string_list(capsule.get("do_not_retry"))
+    require(
+        do_not_retry and not any(is_placeholder_evidence(item) for item in do_not_retry),
+        f"{current_task_id} resume_capsule.do_not_retry must list concrete paths, attempts, or strategy-changing constraints not to repeat",
+    )
+
+    refs = as_string_list(capsule.get("recovery_refs"))
+    require(refs, f"{current_task_id} resume_capsule.recovery_refs must link implementation doc and runbook/evidence documents")
+    implementation_doc = str(current_task.get("implementation_doc") or "").strip()
+    if implementation_doc:
+        require(
+            implementation_doc in refs,
+            f"{current_task_id} resume_capsule.recovery_refs must include current implementation_doc {implementation_doc}",
+        )
+    require(
+        any(ref.startswith(RUNBOOK_DOC_PREFIX) for ref in refs),
+        f"{current_task_id} resume_capsule.recovery_refs must include a runbook/evidence document under {RUNBOOK_DOC_PREFIX}",
+    )
+    for ref in refs:
+        require(
+            ref.startswith(".docs/04_implementation/") or ref.startswith(RUNBOOK_DOC_PREFIX),
+            f"{current_task_id} resume_capsule.recovery_refs may only point to implementation docs or runbook/evidence docs: {ref}",
+        )
+        require(repo_path(ref).exists(), f"{current_task_id} resume_capsule recovery_ref does not exist: {ref}")
+
+
 def validate_plan_contract(data: dict[str, Any], allow_open: bool) -> None:
     lifecycle = load_lifecycle()
     current_phase = str(lifecycle.get("current_phase") or "")
@@ -695,6 +1147,7 @@ def validate_plan_contract(data: dict[str, Any], allow_open: bool) -> None:
     current_task_id = data.get("current_task_id") or ""
     if current_task_id:
         require(task_by_id(data, current_task_id), f"current_task_id does not match a task: {current_task_id}")
+    validate_resume_capsule_contract(data)
 
     open_tasks = [task.get("id") for task in tasks if task.get("status") in OPEN_TASK_STATUSES]
     if not allow_open:

package/assets/tools/transition.py

@@ -1,19 +1,14 @@
 #!/usr/bin/env python3
-from harness_utils import dump_yaml, load_lifecycle, load_phase_contracts, make_arg_parser, require, run_main
-
-
-RFC_INTERRUPT_SOURCES = {"SPRINTING", "REVIEWING", "TESTING", "RELEASING"}
-
-
-def phase_targets(phase: dict) -> list[str]:
-    targets: list[str] = []
-    next_phase = phase.get("next")
-    if next_phase:
-        targets.append(str(next_phase))
-    for return_phase in phase.get("returns") or []:
-        if return_phase:
-            targets.append(str(return_phase))
-    return list(dict.fromkeys(targets))
+from harness_utils import (
+    dump_yaml,
+    find_phase_transition,
+    load_lifecycle,
+    load_phase_contract_data,
+    make_arg_parser,
+    phase_transition_targets,
+    require,
+    run_main,
+)
 
 
 def main() -> None:
@@ -24,29 +19,25 @@ def main() -> None:
     args = parser.parse_args()
 
     lifecycle = load_lifecycle()
-    phases = load_phase_contracts()
+    contract_data = load_phase_contract_data()
+    phases = contract_data["phases"]
     target = args.to
     current = lifecycle.get("current_phase")
     require(target in phases, f"Unknown target phase: {target}")
     require(current in phases, f"Current phase is not declared in phase_contracts.yaml: {current}")
 
-    legal = set(lifecycle.get("allowed_next_phases") or [])
-    legal.update(phase_targets(phases[current]))
-    if target == "RFC_RECALIBRATION" and current in RFC_INTERRUPT_SOURCES:
-        legal.add(target)
-    if target == "BLOCKED":
-        legal.add(target)
     suspended = lifecycle.get("suspended_phase")
-    if current == "BLOCKED" and suspended:
-        legal.add(suspended)
+    legal = set(phase_transition_targets(contract_data, str(current), str(suspended or "")))
+    transition = find_phase_transition(contract_data, str(current), target, str(suspended or ""))
 
     require(args.force or target in legal, f"Illegal transition {current} -> {target}. Legal: {sorted(legal)}")
 
-    if target in {"RFC_RECALIBRATION", "BLOCKED"} and current not in {"RFC_RECALIBRATION", "BLOCKED"}:
+    effects = transition.get("effects") if transition else {}
+    if not isinstance(effects, dict):
+        effects = {}
+    if effects.get("set_suspended_phase"):
         lifecycle["suspended_phase"] = current
-    elif current == "RFC_RECALIBRATION" and target == "SPRINTING":
-        lifecycle["suspended_phase"] = ""
-    elif suspended and target == suspended:
+    if effects.get("clear_suspended_phase"):
         lifecycle["suspended_phase"] = ""
 
     phase = phases[target]
@@ -54,9 +45,11 @@ def main() -> None:
     lifecycle["active_role"] = phase.get("role", "")
     lifecycle["active_skill"] = phase.get("skill", "")
 
-    lifecycle["allowed_next_phases"] = phase_targets(phase)
-    if target == "BLOCKED" and lifecycle.get("suspended_phase"):
-        lifecycle["allowed_next_phases"] = [lifecycle["suspended_phase"]]
+    lifecycle["allowed_next_phases"] = phase_transition_targets(
+        contract_data,
+        target,
+        str(lifecycle.get("suspended_phase") or ""),
+    )
 
     dump_yaml(lifecycle, ".codex/state/lifecycle.yaml")
     print(f"Transitioned {current} -> {target}")

package/assets/tools/validate_design.py

@@ -129,6 +129,11 @@ def validate_self_test_contract_tech_plan_binding(task: dict, normalized_tech_re
         contains_any(section, ["module key test path", "模块关键测试路径"]),
         f"Draft task {task_id} tech plan Development Self-Test Contract must include Module key test path: {source}",
     )
+    if contract.get("graph_required") is True:
+        require(
+            contains_any(section, ["module key test graph", "module_key_test_graph", "模块关键测试图"]),
+            f"Draft task {task_id} tech plan Development Self-Test Contract must include Module Key Test Graph when graph_required is true: {source}",
+        )
     for scenario in contract.get("scenarios") or []:
         if not isinstance(scenario, dict):
             continue