docs(harness): annotate entry orchestration, enums, and exception recovery paths

src/main/java/com/superbiz/agent/harness/guard/evidence/EvidenceViolationCode.java

@@ -1,25 +1,76 @@
 package com.superbiz.agent.harness.guard.evidence;
 
+/**
+ * Evidence Guard 结构/引用违规码（规则门控，通常不调大模型）。
+ *
+ * <p>层级：Guard。校验 DiagnosisDraft 是否引用真实 tool_call、字段是否齐全等。
+ * 失败时可尝试 EvidenceRepair；仍失败则 FallbackType.EVIDENCE_VALIDATION_FAILED。
+ *
+ * <p>与 SemanticVerdict 不同：这里只问「引用是否真实、结构是否合法」，
+ * 不问「结论语义是否夸大」。
+ */
 public enum EvidenceViolationCode {
+
+    /** 缺少整份 draft。 */
     DRAFT_MISSING,
+
+    /** 缺少 analysis 列表或为空。 */
     ANALYSIS_MISSING,
+
+    /** analysis 条目缺少 id。 */
     ANALYSIS_ID_MISSING,
+
+    /** analysis id 重复。 */
     ANALYSIS_ID_DUPLICATE,
+
+    /** analysis 缺少 kind。 */
     ANALYSIS_KIND_MISSING,
+
+    /** analysis 缺少正文。 */
     ANALYSIS_TEXT_MISSING,
+
+    /** 需要工具引用但未提供。 */
     TOOL_REFERENCE_MISSING,
+
+    /** 报告级必填文本缺失。 */
     REPORT_TEXT_MISSING,
+
+    /** 结论等引用了 analysis，但引用列表缺失。 */
     ANALYSIS_REFERENCE_MISSING,
+
+    /** 引用了不存在的 analysis id。 */
     ANALYSIS_REFERENCE_UNKNOWN,
+
+    /** 缺少 limitations（诊断契约要求声明范围/缺口）。 */
     LIMITATIONS_MISSING,
+
+    /** tool 引用字段非法。 */
     TOOL_REFERENCE_INVALID,
+
+    /** 引用的 tool_call 在本 Run 账本中不存在。 */
     INVOCATION_MISSING,
+
+    /** tool_call_id 与账本记录不匹配。 */
     INVOCATION_ID_MISMATCH,
+
+    /** 该 invocation 状态不可被引用（非 READY 等）。 */
     INVOCATION_NOT_REFERENCABLE,
+
+    /** 证据 kind 与工具/投影约定不符。 */
     EVIDENCE_KIND_MISMATCH,
+
+    /** 引用了不支持的工具名。 */
     TOOL_UNSUPPORTED,
+
+    /** 投影结果不可用于校验。 */
     PROJECTION_INVALID,
+
+    /** 投影 id 与引用不一致。 */
     PROJECTION_ID_MISMATCH,
+
+    /** 投影状态与引用期望不一致。 */
     PROJECTION_STATUS_MISMATCH,
+
+    /** 从 canonical store 查找调用记录失败。 */
     CANONICAL_LOOKUP_FAILED
 }