docs(harness): add retry guide and learning roadmap; annotate retry core

src/main/java/com/superbiz/agent/harness/retry/HarnessRetryPolicies.java

@@ -3,6 +3,16 @@ package com.superbiz.agent.harness.retry;
 import java.util.Objects;
 import java.util.Set;
 
+/**
+ * 每个组件独立的重试策略集合（不可变）。
+ *
+ * <p>五个组件各有自己的 {@code maxAttempts + retryableFailures}，
+ * 因为「是否允许重试」取决于调用者知道的信息：
+ * <ul>
+ *   <li>Agent / 业务 Tool 可能有副作用或多轮上下文，不重试；</li>
+ *   <li>Router / SemanticGuard 是单轮无副作用的技术判定，允许一次技术重试。</li>
+ * </ul>
+ */
 public record HarnessRetryPolicies(
         RetryPolicy intentRouter,
         RetryPolicy diagnosisAgent,
@@ -18,6 +28,17 @@ public record HarnessRetryPolicies(
         Objects.requireNonNull(evidenceRepair, "evidenceRepair must not be null");
     }
 
+    /**
+     * 严格默认策略：
+     *
+     * <pre>
+     * intentRouter   : 2 次（超时 / 传输 / 非法输出可重试）——路由判据单轮无副作用
+     * semanticGuard  : 2 次（超时 / 传输 / 解析 / schema 可重试）——语义审查单轮无副作用
+     * diagnosisAgent : 1 次——多轮 ReAct，失败会破坏循环上下文，不重试
+     * toolCall       : 1 次——业务 Tool 可能有副作用，重试会重复副作用
+     * evidenceRepair : 1 次——只修引用，失败直接走 Fallback，不重试
+     * </pre>
+     */
     public static HarnessRetryPolicies strict() {
         RetryPolicy oneAttempt = new RetryPolicy(1, Set.of());
         return new HarnessRetryPolicies(