The split lets PR2 unblock the graph topology + dispatcher work
+ * without committing to a particular evaluator model. The stub is
+ * safe-by-default: it never marks a goal completed and never charges
+ * eval_llm_calls.
+ */
+@Slf4j
+@Service
+public class GoalEvaluationService {
+
+ private final GoalProperties properties;
+
+ public GoalEvaluationService(GoalProperties properties) {
+ this.properties = properties;
+ }
+
+ /**
+ * Evaluate one turn's terminal answer against the goal's exit criteria.
+ *
+ *
Returns {@link GoalEvaluationResult#fallback(String)} when the
+ * evaluator is unavailable so the calling node can skip the bookkeeping
+ * delta path. PR5 swaps this implementation with a real LLM call;
+ * until then we never block the user on evaluator latency.
+ */
+ public GoalEvaluationResult evaluate(GoalEntity goal,
+ List recentMessages,
+ String terminalAnswer) {
+ if (goal == null) {
+ return GoalEvaluationResult.fallback("no_goal");
+ }
+ if (terminalAnswer == null || terminalAnswer.isBlank()) {
+ return GoalEvaluationResult.fallback("empty_answer");
+ }
+ // PR2 placeholder: deterministic continue with a passthrough gap.
+ // Real evaluator lands in PR5 — see RFC 48 §3.9.
+ String model = properties.getEvaluatorModel();
+ if (model == null || model.isBlank()) {
+ model = "stub";
+ }
+ log.debug("[GoalEvaluation] stub evaluate goal={} answerChars={} -> decision=continue",
+ goal.getId(), terminalAnswer.length());
+ return new GoalEvaluationResult(
+ 0.0,
+ "(stub evaluator — wired in PR5)",
+ GoalEvaluationResult.DECISION_CONTINUE,
+ false,
+ model,
+ 0,
+ 0L);
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalFollowupService.java b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalFollowupService.java
new file mode 100644
index 00000000..245fa879
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalFollowupService.java
@@ -0,0 +1,67 @@
+package vip.mate.goal.service;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import vip.mate.goal.model.GoalEntity;
+import vip.mate.goal.model.GoalEvaluationResult;
+
+import java.time.Duration;
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+/**
+ * Decides whether to inject a follow-up user prompt for the next graph
+ * pass. PR2 wires the plumbing; the actual "yes, continue" path defaults
+ * to off until PR5 flips {@code mateclaw.goal.enabled=true} and operators
+ * opt their goals in via {@code auto_followup_enabled}.
+ */
+@Slf4j
+@Service
+public class GoalFollowupService {
+
+ /**
+ * Build the follow-up prompt to inject, or empty when no follow-up
+ * should fire this turn. Conditions follow RFC 48 §3.10:
+ *
maybeBuildFollowup(GoalEntity goal,
+ GoalEvaluationResult result) {
+ if (goal == null || result == null) return Optional.empty();
+ if (!Boolean.TRUE.equals(goal.getAutoFollowupEnabled())) return Optional.empty();
+ if (!GoalEvaluationResult.DECISION_CONTINUE.equals(result.decision())) {
+ return Optional.empty();
+ }
+ if (result.score() >= 0.95) return Optional.empty();
+
+ // Cooldown — last_followup_at recorded by recordFollowupInjected().
+ Integer cooldownSec = goal.getFollowupCooldownSeconds();
+ if (cooldownSec != null && cooldownSec > 0 && goal.getLastFollowupAt() != null) {
+ Duration since = Duration.between(goal.getLastFollowupAt(), LocalDateTime.now());
+ if (since.getSeconds() < cooldownSec) {
+ log.debug("[GoalFollowup] cooldown not elapsed: {}s < {}s", since.getSeconds(), cooldownSec);
+ return Optional.empty();
+ }
+ }
+
+ int turnsUsed = goal.getTurnsUsed() != null ? goal.getTurnsUsed() : 0;
+ int turnBudget = goal.getTurnBudget() != null ? goal.getTurnBudget() : Integer.MAX_VALUE;
+ // Leave at least one turn slot for the real user — refuse to burn
+ // the final slot on an auto-followup that the user can't watch.
+ if (turnsUsed >= turnBudget - 1) return Optional.empty();
+
+ int callBudget = goal.getLlmCallBudget() != null ? goal.getLlmCallBudget() : Integer.MAX_VALUE;
+ if (goal.totalLlmCallsUsed() >= (int) (callBudget * 0.9)) return Optional.empty();
+
+ String gap = result.gap();
+ if (gap == null || gap.isBlank()) gap = "the goal is not yet complete.";
+ String prompt = "Continue working on the goal. Still missing: " + gap
+ + "\nTake the next concrete step.";
+ return Optional.of(prompt);
+ }
+}
diff --git a/mateclaw-server/src/main/java/vip/mate/goal/service/GraphFlavor.java b/mateclaw-server/src/main/java/vip/mate/goal/service/GraphFlavor.java
new file mode 100644
index 00000000..3e8b633e
--- /dev/null
+++ b/mateclaw-server/src/main/java/vip/mate/goal/service/GraphFlavor.java
@@ -0,0 +1,17 @@
+package vip.mate.goal.service;
+
+/**
+ * Which graph topology a {@code GoalEvaluationNode} instance is wired into.
+ *
+ * The same node class serves both graphs but needs to know how to
+ * clear graph-specific state on follow-up: ReAct only touches
+ * {@code FINAL_ANSWER} + {@code FINISH_REASON}, while Plan-Execute has
+ * a wider set of mid-pass + terminal state to wipe before a re-plan.
+ *
+ *
Builder-time decision; the value is captured in the node constructor
+ * and never read from graph state.
+ */
+public enum GraphFlavor {
+ REACT,
+ PLAN_EXECUTE
+}
diff --git a/mateclaw-server/src/test/java/vip/mate/agent/graph/edge/GoalEvaluationDispatcherTest.java b/mateclaw-server/src/test/java/vip/mate/agent/graph/edge/GoalEvaluationDispatcherTest.java
new file mode 100644
index 00000000..5d817710
--- /dev/null
+++ b/mateclaw-server/src/test/java/vip/mate/agent/graph/edge/GoalEvaluationDispatcherTest.java
@@ -0,0 +1,52 @@
+package vip.mate.agent.graph.edge;
+
+import com.alibaba.cloud.ai.graph.OverAllState;
+import org.junit.jupiter.api.Test;
+
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * Verifies the dual-target dispatcher: instances configured for ReAct
+ * route to REASONING_NODE on followup, instances configured for
+ * Plan-Execute route to PLAN_GENERATION_NODE on followup, and both
+ * route to END otherwise.
+ */
+class GoalEvaluationDispatcherTest {
+
+ private OverAllState stateWith(boolean followup) {
+ OverAllState s = mock(OverAllState.class);
+ // The dispatcher only reads GOAL_FOLLOWUP_INJECTED; everything else
+ // can stay default.
+ lenient().when(s.value("goal_followup_injected", false)).thenReturn(followup);
+ return s;
+ }
+
+ @Test
+ void reactInstance_routesFollowupToReasoning() throws Exception {
+ GoalEvaluationDispatcher d = new GoalEvaluationDispatcher("reasoning", "__END__");
+ assertEquals("reasoning", d.apply(stateWith(true)));
+ }
+
+ @Test
+ void reactInstance_routesTerminalToEnd() throws Exception {
+ GoalEvaluationDispatcher d = new GoalEvaluationDispatcher("reasoning", "__END__");
+ assertEquals("__END__", d.apply(stateWith(false)));
+ }
+
+ @Test
+ void planExecuteInstance_routesFollowupToPlanGeneration() throws Exception {
+ GoalEvaluationDispatcher d = new GoalEvaluationDispatcher("plan_generation", "__END__");
+ assertEquals("plan_generation", d.apply(stateWith(true)));
+ }
+
+ @Test
+ void planExecuteInstance_routesTerminalToEnd() throws Exception {
+ GoalEvaluationDispatcher d = new GoalEvaluationDispatcher("plan_generation", "__END__");
+ assertEquals("__END__", d.apply(stateWith(false)));
+ }
+}
diff --git a/mateclaw-server/src/test/java/vip/mate/agent/graph/state/MateClawStateAccessorTerminalAnswerTest.java b/mateclaw-server/src/test/java/vip/mate/agent/graph/state/MateClawStateAccessorTerminalAnswerTest.java
new file mode 100644
index 00000000..b58588b7
--- /dev/null
+++ b/mateclaw-server/src/test/java/vip/mate/agent/graph/state/MateClawStateAccessorTerminalAnswerTest.java
@@ -0,0 +1,62 @@
+package vip.mate.agent.graph.state;
+
+import com.alibaba.cloud.ai.graph.OverAllState;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.lenient;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * Pins the bridge that lets GoalEvaluationNode work uniformly across
+ * graph flavors:
+ *
+ * - ReAct path: FinalAnswerNode writes FINAL_ANSWER.
+ * - Plan-Execute long path: PlanSummaryNode writes FINAL_SUMMARY.
+ * - Plan-Execute short path: DirectAnswerNode writes DIRECT_ANSWER.
+ *
+ */
+class MateClawStateAccessorTerminalAnswerTest {
+
+ private OverAllState mockState(String finalAnswer, String finalSummary, String directAnswer) {
+ OverAllState s = mock(OverAllState.class);
+ lenient().when(s.value(eq("final_answer"), eq(""))).thenReturn(finalAnswer);
+ lenient().when(s.value(eq("final_summary"), eq(""))).thenReturn(finalSummary);
+ lenient().when(s.value(eq("direct_answer"), eq(""))).thenReturn(directAnswer);
+ return s;
+ }
+
+ @Test
+ void reactPath_returnsFinalAnswer() {
+ OverAllState s = mockState("ReAct answer", "", "");
+ assertEquals("ReAct answer", new MateClawStateAccessor(s).terminalAnswer());
+ }
+
+ @Test
+ void planExecuteLongPath_returnsFinalSummary() {
+ OverAllState s = mockState("", "Plan summary text", "");
+ assertEquals("Plan summary text", new MateClawStateAccessor(s).terminalAnswer());
+ }
+
+ @Test
+ void planExecuteShortPath_returnsDirectAnswer() {
+ OverAllState s = mockState("", "", "Direct quick answer");
+ assertEquals("Direct quick answer", new MateClawStateAccessor(s).terminalAnswer());
+ }
+
+ @Test
+ void allEmpty_returnsEmptyString() {
+ OverAllState s = mockState("", "", "");
+ assertEquals("", new MateClawStateAccessor(s).terminalAnswer());
+ }
+
+ @Test
+ void finalAnswerWins_overFinalSummary() {
+ // Defensive: if both happen to be populated (shouldn't, but state
+ // is shared across graphs in tests), FINAL_ANSWER takes priority.
+ OverAllState s = mockState("ReAct answer", "stale summary", "");
+ assertEquals("ReAct answer", new MateClawStateAccessor(s).terminalAnswer());
+ }
+}
diff --git a/mateclaw-server/src/test/java/vip/mate/architecture/GoalStateKeyDoubleRegistrationTest.java b/mateclaw-server/src/test/java/vip/mate/architecture/GoalStateKeyDoubleRegistrationTest.java
new file mode 100644
index 00000000..71fc80e1
--- /dev/null
+++ b/mateclaw-server/src/test/java/vip/mate/architecture/GoalStateKeyDoubleRegistrationTest.java
@@ -0,0 +1,82 @@
+package vip.mate.architecture;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * Strict double-registration check for the persistent-goal state keys.
+ *
+ * {@link StateKeyRegistrationCoverageTest} only verifies that a key
+ * appears somewhere in {@code AgentGraphBuilder.java}; it cannot tell
+ * apart the ReAct and Plan-Execute {@code KeyStrategyFactory} blocks.
+ * History (the {@code CHAT_ORIGIN} regression) shows that "registered
+ * once" is not enough — multi-node merges silently drop keys when one
+ * graph's factory leaves them out.
+ *
+ *
Each of the five Goal state keys must therefore appear at least
+ * twice in the builder source: once per graph. This test pins that
+ * invariant so future regressions get caught at PR time.
+ */
+class GoalStateKeyDoubleRegistrationTest {
+
+ private static final String[] GOAL_KEYS = {
+ "ACTIVE_GOAL",
+ "GOAL_EVALUATION_RESULT",
+ "GOAL_FOLLOWUP_INJECTED",
+ "GOAL_FOLLOWUP_PROMPT",
+ "GOAL_EVALUATED_THIS_RUN",
+ };
+
+ @Test
+ void everyGoalKeyMustAppearAtLeastTwiceInAddStrategyCalls() throws Exception {
+ Path src = Paths.get("src/main/java/vip/mate/agent/AgentGraphBuilder.java")
+ .toAbsolutePath();
+ if (!Files.exists(src)) {
+ fail("Cannot find AgentGraphBuilder.java at " + src);
+ }
+ String content = Files.readString(src);
+
+ for (String key : GOAL_KEYS) {
+ Pattern p = Pattern.compile(
+ "\\.addStrategy\\(\\s*MateClawStateKeys\\." + key + "\\b");
+ Matcher m = p.matcher(content);
+ int count = 0;
+ while (m.find()) count++;
+ if (count < 2) {
+ fail("Goal state key " + key + " must be registered in BOTH the "
+ + "ReAct and Plan-Execute KeyStrategyFactory blocks "
+ + "(found " + count + " addStrategy occurrence(s) in "
+ + "AgentGraphBuilder.java). The architecture coverage "
+ + "test only checks 'appears somewhere'; this test "
+ + "is the strict double-registration guard documented "
+ + "in RFC 48 §3.2 v2.");
+ }
+ assertTrue(count >= 2,
+ "Sanity: " + key + " should have >=2 addStrategy calls");
+ }
+ }
+
+ @Test
+ void goalEvaluationNodeIdentifierAppearsExactlyOncePerGraph() throws Exception {
+ Path src = Paths.get("src/main/java/vip/mate/agent/AgentGraphBuilder.java")
+ .toAbsolutePath();
+ String content = Files.readString(src);
+ Pattern p = Pattern.compile(
+ "\\.addNode\\(\\s*MateClawStateKeys\\.GOAL_EVALUATION_NODE\\b");
+ Matcher m = p.matcher(content);
+ int count = 0;
+ while (m.find()) count++;
+ assertEquals(2, count,
+ "GOAL_EVALUATION_NODE must be added as a node in BOTH graphs " +
+ "(ReAct + Plan-Execute). Found " + count + " addNode calls.");
+ }
+}
diff --git a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalEvaluationServiceTest.java b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalEvaluationServiceTest.java
new file mode 100644
index 00000000..458fa972
--- /dev/null
+++ b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalEvaluationServiceTest.java
@@ -0,0 +1,79 @@
+package vip.mate.goal.service;
+
+import org.junit.jupiter.api.Test;
+import vip.mate.goal.config.GoalProperties;
+import vip.mate.goal.model.GoalEntity;
+import vip.mate.goal.model.GoalEvaluationResult;
+import vip.mate.goal.model.GoalStatus;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Covers the PR2 stub evaluator: deterministic continue + safe fallback
+ * paths. The LLM-backed evaluator lands in PR5; until then any "real"
+ * evaluation always returns continue without charging eval_llm_calls.
+ */
+class GoalEvaluationServiceTest {
+
+ private final GoalProperties props = new GoalProperties();
+ private final GoalEvaluationService svc = new GoalEvaluationService(props);
+
+ private GoalEntity goal() {
+ GoalEntity g = new GoalEntity();
+ g.setId(1L);
+ g.setTitle("ship the blog");
+ g.setStatus(GoalStatus.ACTIVE);
+ return g;
+ }
+
+ @Test
+ void nullGoal_returnsFallback() {
+ GoalEvaluationResult r = svc.evaluate(null, List.of(), "anything");
+ assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision());
+ assertFalse(r.completed());
+ assertEquals(0, r.llmCallsConsumed());
+ }
+
+ @Test
+ void emptyAnswer_returnsFallback() {
+ GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "");
+ assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision());
+ }
+
+ @Test
+ void normalCall_returnsContinue() {
+ GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "the answer text");
+ assertNotNull(r);
+ assertEquals(GoalEvaluationResult.DECISION_CONTINUE, r.decision());
+ assertFalse(r.completed());
+ assertEquals(0, r.llmCallsConsumed(),
+ "PR2 stub must not charge eval_llm_calls — that path lands in PR5");
+ }
+
+ @Test
+ void evaluatorModel_defaultsToStub_whenPropertyBlank() {
+ props.setEvaluatorModel("");
+ GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "the answer text");
+ assertEquals("stub", r.evaluatorModel());
+ }
+
+ @Test
+ void evaluatorModel_carriesPropertyValue_whenConfigured() {
+ props.setEvaluatorModel("qwen-turbo");
+ GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "the answer text");
+ assertEquals("qwen-turbo", r.evaluatorModel());
+ }
+
+ @Test
+ void fallback_doesNotChargeLlmCalls() {
+ GoalEvaluationResult r = GoalEvaluationResult.fallback("evaluator_unavailable");
+ assertEquals(0, r.llmCallsConsumed());
+ assertFalse(r.completed());
+ assertTrue(r.gap().contains("evaluator unavailable"));
+ }
+}
diff --git a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalFollowupServiceTest.java b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalFollowupServiceTest.java
new file mode 100644
index 00000000..3082e49b
--- /dev/null
+++ b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalFollowupServiceTest.java
@@ -0,0 +1,118 @@
+package vip.mate.goal.service;
+
+import org.junit.jupiter.api.Test;
+import vip.mate.goal.model.GoalEntity;
+import vip.mate.goal.model.GoalEvaluationResult;
+import vip.mate.goal.model.GoalStatus;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Covers the five follow-up gating conditions from RFC 48 §3.10. Every
+ * negative case must independently block the follow-up.
+ */
+class GoalFollowupServiceTest {
+
+ private final GoalFollowupService svc = new GoalFollowupService();
+
+ private GoalEntity goal(boolean autoEnabled) {
+ GoalEntity g = new GoalEntity();
+ g.setId(1L);
+ g.setTitle("ship");
+ g.setStatus(GoalStatus.ACTIVE);
+ g.setTurnBudget(20);
+ g.setTurnsUsed(5);
+ g.setLlmCallBudget(200);
+ g.setAgentLlmCallsUsed(30);
+ g.setEvalLlmCallsUsed(4);
+ g.setAutoFollowupEnabled(autoEnabled);
+ g.setFollowupCooldownSeconds(0);
+ return g;
+ }
+
+ private GoalEvaluationResult res(double score, String decision) {
+ return new GoalEvaluationResult(
+ score, "missing X",
+ decision, false,
+ "stub", 0, 0L);
+ }
+
+ @Test
+ void disabledAutoFollowup_returnsEmpty() {
+ Optional out = svc.maybeBuildFollowup(
+ goal(false),
+ res(0.6, GoalEvaluationResult.DECISION_CONTINUE));
+ assertTrue(out.isEmpty());
+ }
+
+ @Test
+ void completedDecision_returnsEmpty() {
+ Optional out = svc.maybeBuildFollowup(
+ goal(true),
+ res(0.99, GoalEvaluationResult.DECISION_COMPLETED));
+ assertTrue(out.isEmpty());
+ }
+
+ @Test
+ void highScore_returnsEmpty() {
+ Optional out = svc.maybeBuildFollowup(
+ goal(true),
+ res(0.96, GoalEvaluationResult.DECISION_CONTINUE));
+ assertTrue(out.isEmpty());
+ }
+
+ @Test
+ void cooldownNotElapsed_returnsEmpty() {
+ GoalEntity g = goal(true);
+ g.setFollowupCooldownSeconds(60);
+ g.setLastFollowupAt(LocalDateTime.now().minusSeconds(10));
+ Optional out = svc.maybeBuildFollowup(
+ g, res(0.6, GoalEvaluationResult.DECISION_CONTINUE));
+ assertTrue(out.isEmpty());
+ }
+
+ @Test
+ void cooldownElapsed_allowsFollowup() {
+ GoalEntity g = goal(true);
+ g.setFollowupCooldownSeconds(60);
+ g.setLastFollowupAt(LocalDateTime.now().minusSeconds(120));
+ Optional out = svc.maybeBuildFollowup(
+ g, res(0.6, GoalEvaluationResult.DECISION_CONTINUE));
+ assertTrue(out.isPresent());
+ }
+
+ @Test
+ void nearTurnBudget_returnsEmpty() {
+ GoalEntity g = goal(true);
+ g.setTurnBudget(20);
+ g.setTurnsUsed(19); // only one slot left — reserved for the real user
+ Optional out = svc.maybeBuildFollowup(
+ g, res(0.6, GoalEvaluationResult.DECISION_CONTINUE));
+ assertTrue(out.isEmpty());
+ }
+
+ @Test
+ void over90PercentLlmBudget_returnsEmpty() {
+ GoalEntity g = goal(true);
+ g.setLlmCallBudget(100);
+ g.setAgentLlmCallsUsed(85);
+ g.setEvalLlmCallsUsed(10); // total 95 = 95% > 90% guard
+ Optional out = svc.maybeBuildFollowup(
+ g, res(0.6, GoalEvaluationResult.DECISION_CONTINUE));
+ assertTrue(out.isEmpty());
+ }
+
+ @Test
+ void happyPath_returnsPrompt_containingGap() {
+ Optional out = svc.maybeBuildFollowup(
+ goal(true),
+ res(0.6, GoalEvaluationResult.DECISION_CONTINUE));
+ assertTrue(out.isPresent());
+ assertTrue(out.get().contains("missing X"));
+ assertTrue(out.get().toLowerCase().contains("next concrete step"));
+ }
+}