feat: implement native turn interpretation and policy routing

- Refactor `interpretTurn` to derive meaning solely from message text and conversation state, removing reliance on legacy route semantics.
- Update `routeMessageTurn` to utilize the new interpretation and policy structure, ensuring clear scheduling requests execute directly.
- Enhance handling of confirmation and clarification scenarios, including proposal-first behavior only for explicit confirmation-required rules.
- Introduce new tests to validate the updated routing logic and ensure correct interpretation of various turn types.
- Document changes in architecture and decisions regarding the new routing model, emphasizing the importance of conversation state quality.

Author: MaxLinCode

apps/web/src/app/api/telegram/webhook/route.test.ts

@@ -491,6 +491,9 @@ describe("telegram webhook route", () => {
 
   it("lets mixed-intent messages fall through to the normal router even with outstanding followups", async () => {
     const { store, followUpStore } = await seedOutstandingFollowUpBundle(["Review launch checklist", "Send investor update"]);
+    const conversationResponder = vi.fn(async () => ({
+      reply: "What time tomorrow should I schedule the dentist?"
+    }));
 
     const response = await handleTelegramWebhook(
       buildRequest({
@@ -507,14 +510,25 @@ describe("telegram webhook route", () => {
         store,
         followUpStore,
         calendar: getDefaultCalendarAdapter(),
-        primeProcessingStore: seedInboxItemForProcessingTests
+        primeProcessingStore: seedInboxItemForProcessingTests,
+        conversationResponder
       }
     );
 
     expect(response.status).toBe(200);
-    expect(routeTurnWithResponsesMock).toHaveBeenCalledTimes(1);
-    expect((response.body as { processing: { outcome: string } }).processing.outcome).toBe("planned");
+    expect(response.body).toMatchObject({
+      processing: {
+        outcome: "conversation_replied",
+        reply: "What time tomorrow should I schedule the dentist?"
+      },
+      routing: {
+        policy: {
+          action: "ask_clarification"
+        }
+      }
+    });
     expect(listTasksForTests().filter((task) => task.lifecycleState === "done")).toHaveLength(0);
+    expect(conversationResponder).toHaveBeenCalledTimes(1);
   });
 
   it("also gates /start for unlinked users", async () => {
@@ -806,6 +820,58 @@ describe("telegram webhook route", () => {
     expect(editTelegramMessageMock).toHaveBeenCalledTimes(1);
   });
 
+  it("does not keep clear scheduling requests in discuss-first mode", async () => {
+    process.env.TELEGRAM_WEBHOOK_SECRET = "test-webhook-secret";
+
+    const response = await handleTelegramWebhook(
+      buildRequest({
+        update_id: 145,
+        message: {
+          message_id: 110,
+          date: 1_700_000_020,
+          text: "Schedule gym tomorrow at 6pm for 1 hour",
+          chat: {
+            id: 999,
+            type: "private"
+          },
+          from: {
+            id: 123,
+            is_bot: false,
+            first_name: "Max",
+            last_name: "Lin"
+          }
+        }
+      }),
+      {
+        store: getDefaultInboxProcessingStore(),
+        calendar: getDefaultCalendarAdapter(),
+        primeProcessingStore: seedInboxItemForProcessingTests
+      }
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.body).toMatchObject({
+      accepted: true,
+      turnRoute: "mutation",
+      routing: {
+        interpretation: {
+          turnType: "planning_request",
+          ambiguity: "none"
+        },
+        policy: {
+          action: "execute_mutation"
+        }
+      },
+      processing: {
+        outcome: "planned"
+      }
+    });
+    expect(sendTelegramMessageMock).toHaveBeenCalledWith({
+      chatId: "999",
+      text: "Checking your schedule"
+    });
+  });
+
   it("treats confirmed mutation turns as write-capable when recovery finds one concrete proposal", async () => {
     process.env.TELEGRAM_WEBHOOK_SECRET = "test-webhook-secret";
     await recordOutgoingTelegramMessageIfNew({

apps/web/src/lib/server/decide-turn-policy.test.ts

@@ -24,14 +24,14 @@ describe("decideTurnPolicy", () => {
     });
   });
 
-  it("asks for clarification when write intent still has missing slots", () => {
+  it("asks for clarification when a scheduling request is still missing required slots", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
           turnType: "planning_request",
-          confidence: 0.7,
+          confidence: 0.58,
           resolvedEntityIds: [],
-          ambiguity: "low",
+          ambiguity: "high",
           missingSlots: ["time"]
         },
         routingContext: {
@@ -46,28 +46,28 @@ describe("decideTurnPolicy", () => {
     });
   });
 
-  it("presents a proposal for medium-confidence write intent", () => {
+  it("does not force proposal mode for low-confidence writes alone", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
           turnType: "planning_request",
           confidence: 0.68,
           resolvedEntityIds: [],
-          ambiguity: "low"
+          ambiguity: "none"
         },
         routingContext: {
-          rawText: "Could we move it to tomorrow morning?",
-          normalizedText: "Could we move it to tomorrow morning?",
+          rawText: "Schedule gym tomorrow at 6pm",
+          normalizedText: "Schedule gym tomorrow at 6pm",
           recentTurns: []
         }
       })
     ).toMatchObject({
-      action: "present_proposal",
-      requiresConfirmation: true
+      action: "execute_mutation",
+      requiresConfirmation: false
     });
   });
 
-  it("executes direct confident write intent", () => {
+  it("executes complete scheduling requests with no ambiguity", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
@@ -77,8 +77,8 @@ describe("decideTurnPolicy", () => {
           ambiguity: "none"
         },
         routingContext: {
-          rawText: "Schedule gym tomorrow evening",
-          normalizedText: "Schedule gym tomorrow evening",
+          rawText: "Schedule gym tomorrow at 6pm for 1 hour",
+          normalizedText: "Schedule gym tomorrow at 6pm for 1 hour",
           recentTurns: []
         }
       })
@@ -101,7 +101,23 @@ describe("decideTurnPolicy", () => {
         routingContext: {
           rawText: "Yes",
           normalizedText: "Yes",
-          recentTurns: []
+          recentTurns: [],
+          entityRegistry: [
+            {
+              id: "proposal-1",
+              conversationId: "conversation-1",
+              kind: "proposal_option",
+              label: "Schedule it at 3pm",
+              status: "active",
+              createdAt: "2026-03-20T16:00:00.000Z",
+              updatedAt: "2026-03-20T16:00:00.000Z",
+              data: {
+                route: "conversation_then_mutation",
+                replyText: "Would you like me to schedule it at 3pm?",
+                confirmationRequired: true
+              }
+            }
+          ]
         }
       })
     ).toMatchObject({
@@ -110,45 +126,63 @@ describe("decideTurnPolicy", () => {
     });
   });
 
-  it("falls back to clarification when confirmation has no recoverable proposal", () => {
+  it("asks for clarification on ambiguous write-like turns", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
-          turnType: "confirmation",
-          confidence: 0.4,
-          resolvedEntityIds: [],
-          ambiguity: "high"
+          turnType: "edit_request",
+          confidence: 0.6,
+          resolvedEntityIds: ["task-1"],
+          ambiguity: "high",
+          ambiguityReason: "Underspecified edit."
         },
         routingContext: {
-          rawText: "Yes",
-          normalizedText: "Yes",
+          rawText: "Move it",
+          normalizedText: "Move it",
           recentTurns: []
         }
       })
     ).toMatchObject({
-      action: "ask_clarification",
-      clarificationSlots: ["proposal"]
+      action: "ask_clarification"
     });
   });
 
-  it("asks for clarification on high-ambiguity write-like turns", () => {
+  it("uses present_proposal only for explicit confirmation-required policy", () => {
     expect(
       decideTurnPolicy({
         interpretation: {
-          turnType: "edit_request",
-          confidence: 0.6,
+          turnType: "planning_request",
+          confidence: 0.93,
           resolvedEntityIds: ["task-1"],
-          ambiguity: "high",
-          ambiguityReason: "Underspecified edit."
+          resolvedProposalId: "proposal-1",
+          ambiguity: "none"
         },
         routingContext: {
-          rawText: "Move it",
-          normalizedText: "Move it",
-          recentTurns: []
+          rawText: "Schedule it tomorrow at 6pm",
+          normalizedText: "Schedule it tomorrow at 6pm",
+          recentTurns: [],
+          entityRegistry: [
+            {
+              id: "proposal-1",
+              conversationId: "conversation-1",
+              kind: "proposal_option",
+              label: "Schedule it tomorrow at 6pm",
+              status: "active",
+              createdAt: "2026-03-20T16:00:00.000Z",
+              updatedAt: "2026-03-20T16:00:00.000Z",
+              data: {
+                route: "conversation_then_mutation",
+                replyText: "Would you like me to schedule it tomorrow at 6pm?",
+                confirmationRequired: true,
+                targetEntityId: "task-1"
+              }
+            }
+          ]
         }
       })
     ).toMatchObject({
-      action: "ask_clarification"
+      action: "present_proposal",
+      requiresConfirmation: true
     });
   });
 });

apps/web/src/lib/server/decide-turn-policy.ts

@@ -18,6 +18,7 @@ export function decideTurnPolicy(input: DecideTurnPolicyInput): TurnPolicyDecisi
     activeClarifications.filter((clarification) => clarification.blocking).map((clarification) => clarification.slot)
   );
   const targetEntityId = input.interpretation.resolvedEntityIds[0];
+  const confirmationRequired = doesTurnRequireProposal(input);
 
   switch (input.interpretation.turnType) {
     case "informational":
@@ -61,7 +62,11 @@ export function decideTurnPolicy(input: DecideTurnPolicyInput): TurnPolicyDecisi
         clarificationSlots: ["proposal"]
       };
     case "clarification_answer":
-      if (input.interpretation.ambiguity === "high") {
+      if (
+        input.interpretation.ambiguity === "high" ||
+        (input.interpretation.missingSlots?.length ?? 0) > 0 ||
+        blockingSlots.length > 0
+      ) {
         return {
           action: "ask_clarification",
           reason: "Clarification answer is still too ambiguous to safely continue.",
@@ -72,15 +77,15 @@ export function decideTurnPolicy(input: DecideTurnPolicyInput): TurnPolicyDecisi
         };
       }
 
-      if (input.interpretation.resolvedProposalId) {
+      if (confirmationRequired) {
         return {
           action: "present_proposal",
-          reason: "Clarification filled a pending proposal context but confirmation is still preferred.",
+          reason: "Clarification resolved the missing details, but explicit product policy still requires proposal-first confirmation.",
           requiresWrite: false,
           requiresConfirmation: true,
           useMutationPipeline: false,
           ...(targetEntityId ? { targetEntityId } : {}),
-          targetProposalId: input.interpretation.resolvedProposalId,
+          ...(input.interpretation.resolvedProposalId ? { targetProposalId: input.interpretation.resolvedProposalId } : {}),
           clarificationSlots: input.interpretation.missingSlots
         };
       }
@@ -120,10 +125,23 @@ export function decideTurnPolicy(input: DecideTurnPolicyInput): TurnPolicyDecisi
         };
       }
 
-      if (input.interpretation.confidence >= 0.85 && input.interpretation.ambiguity === "none") {
+      if (confirmationRequired) {
+        return {
+          action: "present_proposal",
+          reason: "Write request is ready, but explicit product policy requires proposal-first confirmation.",
+          requiresWrite: false,
+          requiresConfirmation: true,
+          useMutationPipeline: false,
+          ...(targetEntityId ? { targetEntityId } : {}),
+          ...(input.interpretation.resolvedProposalId ? { targetProposalId: input.interpretation.resolvedProposalId } : {}),
+          clarificationSlots: input.interpretation.missingSlots
+        };
+      }
+
+      if (input.interpretation.ambiguity === "none") {
         return {
           action: "execute_mutation",
-          reason: "Direct confident write intent can go straight to the mutation pipeline.",
+          reason: "Write-ready request can go straight to the mutation pipeline.",
           requiresWrite: true,
           requiresConfirmation: false,
           useMutationPipeline: true,
@@ -133,26 +151,53 @@ export function decideTurnPolicy(input: DecideTurnPolicyInput): TurnPolicyDecisi
       }
 
       return {
-        action: "present_proposal",
-        reason: "Write intent is present but should be proposed before applying it.",
+        action: "ask_clarification",
+        reason: "Write intent is present but still needs clarification before applying it.",
         requiresWrite: false,
-        requiresConfirmation: true,
+        requiresConfirmation: false,
         useMutationPipeline: false,
         ...(targetEntityId ? { targetEntityId } : {}),
-        clarificationSlots: input.interpretation.missingSlots
+        clarificationSlots: input.interpretation.missingSlots ?? blockingSlots
       };
     case "unknown":
       return {
-        action: "ask_clarification",
-        reason: "Unknown turn meaning should prompt a clarification instead of guessing.",
+        action:
+          input.interpretation.ambiguity === "none" && !containsWriteVerb(input.routingContext.normalizedText)
+            ? "reply_only"
+            : "ask_clarification",
+        reason:
+          input.interpretation.ambiguity === "none" && !containsWriteVerb(input.routingContext.normalizedText)
+            ? "Unknown non-write text should stay in the conversation responder."
+            : "Unknown turn meaning should prompt a clarification instead of guessing.",
         requiresWrite: false,
         requiresConfirmation: false,
         useMutationPipeline: false,
-        clarificationSlots: input.interpretation.missingSlots ?? blockingSlots
+        clarificationSlots:
+          input.interpretation.ambiguity === "none" && !containsWriteVerb(input.routingContext.normalizedText)
+            ? undefined
+            : input.interpretation.missingSlots ?? blockingSlots
       };
   }
 }
 
 function unique(values: string[]) {
   return Array.from(new Set(values));
 }
+
+function doesTurnRequireProposal(input: DecideTurnPolicyInput) {
+  const activeProposal = (input.routingContext.entityRegistry ?? []).find(
+    (entity) =>
+      entity.kind === "proposal_option" &&
+      entity.status === "active" &&
+      entity.id === input.interpretation.resolvedProposalId &&
+      entity.data.confirmationRequired === true
+  );
+
+  return Boolean(activeProposal);
+}
+
+function containsWriteVerb(text: string) {
+  return /\b(schedule|plan|move|reschedule|shift|create|add|book|put|mark|complete|archive|cancel|delete|change|update)\b/i.test(
+    text
+  );
+}