agent-project-sdlc 0.1.22 → 0.1.23

package/assets/templates/EVIDENCE_INDEX_TEMPLATE.md

@@ -1,6 +1,6 @@
 # [Runtime / Live Smoke] Evidence Index
 
-本文件只保存证据指针和缺口，不把证据正文塞回 implementation doc 主线。
+本文件只保存证据指针和缺口，不把证据正文塞回 implementation doc 主线或 `Development Self-Test Report`。
 
 | Scenario | Status | Evidence File / System | Gap / Next Action |
 |---|---|---|---|
@@ -11,6 +11,7 @@
 - Temporary evidence:
 - Stable artifact / CI / release record:
 - Evidence that must not be copied into main docs:
+- Development Self-Test Report reference format:
 
 ## Missing Evidence
 

package/assets/templates/EXPLORATION_APPENDIX_TEMPLATE.md

@@ -20,3 +20,5 @@
 | Decision | Promoted To |
 |---|---|
 |  | `plan.yaml#resume_capsule` / runbook / implementation doc |
+
+凡会改变下一步动作的判断，必须 promoted 到 `plan.yaml#resume_capsule.do_not_retry` 或 runbook 顶部 `Hard Constraints`；本 appendix 只能保留推导和历史背景。

package/assets/templates/IMPLEMENTATION_DOC_TEMPLATE.md

@@ -60,31 +60,37 @@ Input
 - Operator runbook: `.docs/09_runbooks/...`
 - Credential reference: Keychain item name 或 secret reference name only；不要记录明文密钥。
 - Command/UI channel:
+- Hard Constraints: 会改变下一步动作的判断必须提升到这里和 `plan.yaml#resume_capsule.do_not_retry`；不要只埋在 evidence、notes 或 appendix。
 - Do-not-retry summary: fallback / diagnostic 只写一句结论，详细内容进 exploration appendix 或 git history。
 
 ## 8. Development Self-Test Report（开发自测报告）
 
-本节只证明模块入口、核心路径、出口和最小证据，不是 debug log、operator log、runbook 或探索流水。
+本节是开发阶段可执行交接卡，只证明模块应用入口、核心路径、出口和最小证据指针。目标控制在几十行；high-risk runtime/live 场景包含 `Gate Breakdown` 时也不要超过 120 行。本节不是 debug log、operator log、runbook、evidence dump 或探索流水。
 
 - Report Status: PASS | BLOCKED | IN_PROGRESS | STALE
 - Contract Source:
+- Module Application Entry:
+- Module Key Test Path: local start / invocation -> all self-test scenarios -> all task/module promised runnable entries -> actual internal key paths / boundaries / checkpoints -> observable completion evidence
+- Module Key Test Graph: required only when `self_test_contract.graph_required: true` or `module_key_test_graph` exists; keep it as a compact DAG pointer list/table covering entry, checkpoints, scenario nodes, observable exit, and evidence refs.
 - Scenario Results:
 - Executed Gates:
-- Module Key Test Path: local start / invocation -> all self-test scenarios -> all task/module promised runnable entries -> actual internal key paths / boundaries / checkpoints -> observable completion evidence
-- Actual Evidence:
-- Missing / Blockers:
+- Observable Exit:
+- Current Blocker:
 - Testing Handoff Readiness:
+- Evidence Index Refs: `.docs/09_runbooks/..._evidence.md` 或外部 artifact / CI / command output path；不要复制证据正文。
 
 保留：
 - Runnable Entry / Module Key Test Path / Observable Exit
-- Scenario Results / Executed Gates / Actual Evidence
-- Missing / Blockers / Testing Handoff Readiness
+- Scenario Results / Executed Gates / Evidence Index Refs
+- Current Blocker / Testing Handoff Readiness
 
 不保留：
 - 每次工具探索的完整流水
 - debug log、operator log、历史操作日记或 runbook 正文
 - fallback / diagnostic 的长篇命令、截图过程或 UI 细节
 - 与当前恢复路径无关的旧失败通道；只在 appendix 或 git history 保留
+- `Actual Evidence` 正文字段；证据正文进入 Evidence Index 或外部 artifact，本节只留 refs
+- high-risk implementation doc 主线不得新增 `Evidence Dump`、`Operator Log`、`Failed Attempts`、`Screenshot Index` 等章节；这些只能进入 runbook / evidence index / exploration appendix
 
 ### Gate Breakdown（Gate 分层）
 
@@ -99,6 +105,21 @@ Input
 |---|---|---|---|---|
 |  |  |  |  |  |
 
+### Module Key Test Graph（复杂 / high-risk 路径需要）
+
+只记录实际 handoff path 的 DAG 骨架和 evidence pointer；不要放 command output、截图过程、operator log、debug log、runbook 正文、失败探索或历史流水。
+
+| Node ID | Kind | Label | Scenario Ref | Expected Exit | Evidence Ref |
+|---|---|---|---|---|---|
+| entry-local-start | entry |  |  |  |  |
+| scenario-st-001 | scenario |  | ST-001 |  | `.docs/09_runbooks/...#ST-001` |
+| exit-observable | observable_exit |  |  |  |  |
+
+| From | To |
+|---|---|
+| entry-local-start | scenario-st-001 |
+| scenario-st-001 | exit-observable |
+
 ## 9. Testing Handoff Contract（测试交接合同）
 
 - Entry:

package/assets/templates/PLAN_TEMPLATE.yaml

@@ -12,7 +12,7 @@ next_task_sequence: 2
 #   blocker: "current blocker, or none with context"
 #   last_passed_gate: "last concrete PASS gate or checkpoint"
 #   do_not_retry:
-#     - "known failed path or repeated trap to avoid"
+#     - "known failed path, repeated trap, or strategy-changing hard constraint; e.g. if PC WeChat shows QR after confirmed login, first classify rule_assumption_gap vs operator_induced_logout_or_session_reset before rescanning"
 #   recovery_refs:
 #     - ".docs/04_implementation/example.md"
 #     - ".docs/09_runbooks/example_live_smoke_runbook.md"
@@ -93,6 +93,36 @@ tasks:
       runnable_entry: "command / URL / endpoint / worker command"
       observable_exit: "response / page state / side effect / log / artifact"
       module_key_test_path: "local start command / URL -> all self-test scenarios -> all task/module promised runnable entries -> internal key paths / boundaries / checkpoints -> observable completion evidence"
+      # Set graph_required: true for complex/high-risk handoff paths:
+      # scenario >= 3, multiple branches/entries, runtime/live/provider/browser/worker,
+      # or paths that Review/Testing must consume explicitly. The graph is a
+      # lightweight DAG handoff skeleton, not an execution trace, runbook, log,
+      # evidence dump, or graph engine input.
+      graph_required: false
+      module_key_test_graph:
+        nodes:
+          - id: "entry-local-start"
+            kind: "entry"
+            label: "local start command / URL"
+          - id: "checkpoint-core-path"
+            kind: "checkpoint"
+            label: "core module boundary or checkpoint"
+          - id: "scenario-st-001"
+            kind: "scenario"
+            label: "ST-001 expected behavior"
+            scenario_ref: "ST-001"
+            expected_exit: "observable response / side effect / page state"
+            evidence_ref: ".docs/09_runbooks/example_evidence.md#ST-001"
+          - id: "exit-observable"
+            kind: "observable_exit"
+            label: "observable response / side effect / page state"
+        edges:
+          - from: "entry-local-start"
+            to: "checkpoint-core-path"
+          - from: "checkpoint-core-path"
+            to: "scenario-st-001"
+          - from: "scenario-st-001"
+            to: "exit-observable"
       required_gates:
         - "npm run smoke"
       scenarios:

package/assets/templates/RUNBOOK_TEMPLATE.md

@@ -10,7 +10,12 @@
 - Last known good checkpoint:
 - Primary blocker:
 
-## 2. Operator Path
+## 2. Hard Constraints
+
+- 会改变下一步动作的判断必须写在这里，并同步到 `plan.yaml#resume_capsule.do_not_retry` 或 implementation doc `Current Operator Path`。
+- Example: PC 微信已登录后再次出现 QR 时，先判定 `rule_assumption_gap` vs `operator_induced_logout_or_session_reset`，不得直接进入重新扫码流程。
+
+## 3. Operator Path
 
 ```txt
 canonical:
@@ -21,26 +26,26 @@ UI channel:
 do not prefer:
 ```
 
-## 3. Preconditions
+## 4. Preconditions
 
 - Required access:
 - Required local tools:
 - Required remote services:
 - Safety / cleanup notes:
 
-## 4. Resume Steps
+## 5. Resume Steps
 
 1. 
 2. 
 3. 
 
-## 5. Fallbacks And Diagnostics
+## 6. Fallbacks And Diagnostics
 
 - Preferred fallback:
 - Diagnostic-only paths:
 - Do not retry:
 
-## 6. Linked Evidence
+## 7. Linked Evidence
 
 - Evidence index:
 - Exploration appendix:

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,27 @@ 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 = [
@@ -441,6 +465,182 @@ def requires_resume_capsule(task: dict[str, Any]) -> bool:
     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)
@@ -483,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
 
 
@@ -643,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")
@@ -731,7 +1101,7 @@ def validate_resume_capsule_contract(data: dict[str, Any]) -> None:
     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 or attempts not to repeat",
+        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"))