Merge pull request #57 from MaxLinCode/worktree-clarification-state-cleanup

Clean up clarification state persistence

Author: MaxLinCode

apps/web/src/lib/server/conversation-state.test.ts

@@ -62,7 +62,7 @@ describe("deriveConversationReplyState", () => {
       expect.objectContaining({
         slot: "time",
         status: "pending",
-        blocking: true
+
       })
     ]);
     expect(result.discourseState?.mode).toBe("clarifying");
@@ -147,7 +147,7 @@ describe("deriveConversationReplyState", () => {
           slot: "time",
           question: "What time should I schedule it?",
           status: "pending",
-          blocking: true,
+
           createdAt: "2026-03-22T16:01:00.000Z",
           createdTurnId: "assistant:1"
         }
@@ -186,12 +186,7 @@ describe("deriveConversationReplyState", () => {
         })
       ])
     );
-    expect(result.discourseState?.pending_clarifications).toEqual([
-      expect.objectContaining({
-        id: "clar-1",
-        status: "resolved"
-      })
-    ]);
+    expect(result.discourseState?.pending_clarifications).toEqual([]);
     expect(result.discourseState?.mode).toBe("confirming");
   });
 
@@ -273,7 +268,6 @@ describe("deriveConversationReplyState", () => {
           slot: "time",
           question: "What time should I schedule it?",
           status: "pending",
-          blocking: true,
           createdAt: "2026-03-22T16:01:00.000Z",
           createdTurnId: "assistant:1"
         }
@@ -299,12 +293,7 @@ describe("deriveConversationReplyState", () => {
       occurredAt: "2026-03-22T16:05:00.000Z"
     });
 
-    expect(result.discourseState?.pending_clarifications).toEqual([
-      expect.objectContaining({
-        id: "clar-1",
-        status: "resolved"
-      })
-    ]);
+    expect(result.discourseState?.pending_clarifications).toEqual([]);
     expect(result.entityRegistry).toEqual(
       expect.arrayContaining([
         expect.objectContaining({
@@ -347,7 +336,7 @@ describe("deriveMutationState", () => {
           slot: "time",
           question: "What time should I schedule it?",
           status: "pending",
-          blocking: true,
+
           createdAt: "2026-03-22T16:01:00.000Z",
           createdTurnId: "assistant:1"
         }
@@ -420,12 +409,7 @@ describe("deriveMutationState", () => {
       occurredAt: "2026-03-22T16:10:00.000Z"
     });
 
-    expect(result.discourseState.pending_clarifications).toEqual([
-      expect.objectContaining({
-        id: "clar-1",
-        status: "resolved"
-      })
-    ]);
+    expect(result.discourseState.pending_clarifications).toEqual([]);
     expect(result.discourseState.mode).toBe("editing");
   });
 

apps/web/src/lib/server/conversation-state.ts

@@ -129,7 +129,6 @@ export function deriveConversationReplyState(input: DeriveConversationReplyState
       slot: clarificationSlot,
       question: input.reply,
       status: "pending",
-      blocking: true,
       createdAt: occurredAt,
       createdTurnId: `assistant:${occurredAt}`
     });
@@ -256,7 +255,6 @@ export function deriveMutationState(input: DeriveMutationStateInput) {
       slot: input.processing.reason,
       question: input.processing.followUpMessage,
       status: "pending",
-      blocking: true,
       createdAt: occurredAt,
       createdTurnId: `assistant:${occurredAt}`
     });

apps/web/src/lib/server/llm-classifier.test.ts

@@ -156,7 +156,6 @@ describe("classifyTurn", () => {
                 slot: "time",
                 question: "What time?",
                 status: "pending",
-                blocking: true,
                 createdAt: "2026-03-20T16:00:00.000Z",
                 createdTurnId: "t-1"
               }
@@ -247,7 +246,6 @@ describe("classifyTurn", () => {
                 slot: "time",
                 question: "What time?",
                 status: "pending",
-                blocking: true,
                 createdAt: "2026-03-20T16:00:00.000Z",
                 createdTurnId: "t-1"
               }

packages/core/src/discourse-state.test.ts

@@ -16,7 +16,6 @@ import {
 function buildClarification(input: Partial<PendingClarification> & Pick<PendingClarification, "id" | "slot" | "question">): PendingClarification {
   return {
     status: "pending",
-    blocking: true,
     createdAt: "2026-03-22T10:00:00.000Z",
     createdTurnId: "assistant:turn-1",
     ...input

packages/core/src/discourse-state.ts

@@ -38,7 +38,6 @@ export const pendingClarificationSchema = z.object({
   slot: z.string().min(1),
   question: z.string().min(1),
   status: z.enum(["pending", "resolved", "cancelled"]),
-  blocking: z.boolean(),
   createdAt: z.string().datetime(),
   createdTurnId: z.string().min(1),
   priority: z.number().int().optional()
@@ -265,11 +264,7 @@ export function deriveMode(
   state: DiscourseState,
   signals: ModeDerivationSignals = {}
 ): ConversationMode {
-  const hasBlockingClarification = getActivePendingClarifications(state).some(
-    (clarification) => clarification.blocking
-  );
-
-  if (hasBlockingClarification) {
+  if (hasContractGaps(state) || getActivePendingClarifications(state).length > 0) {
     return "clarifying";
   }
 
@@ -284,6 +279,13 @@ export function deriveMode(
   return "planning";
 }
 
+function hasContractGaps(state: DiscourseState): boolean {
+  const contract = state.pending_write_contract;
+  if (!contract) return false;
+  const resolved = state.resolved_slots ?? {};
+  return contract.requiredSlots.some((slot) => resolved[slot] === undefined);
+}
+
 export function cleanupDiscourseState(
   state: DiscourseState,
   input: CleanupDiscourseStateInput = {}
@@ -524,6 +526,7 @@ export function updateDiscourseStateFromUserTurn(
     nextState = setEditableEntity(nextState, input.editableEntityId);
   }
 
+  nextState = pruneStaleClarifications(nextState);
   nextState = cleanupDiscourseState(nextState, compactObject({
     validEntityIds: input.validEntityIds
   }));
@@ -590,6 +593,7 @@ export function updateDiscourseStateFromAssistantTurn(
     nextState = setEditableEntity(nextState, input.editableEntityId);
   }
 
+  nextState = pruneStaleClarifications(nextState);
   nextState = cleanupDiscourseState(nextState, compactObject({
     validEntityIds: input.validEntityIds
   }));
@@ -613,6 +617,15 @@ export function updateDiscourseStateFromAssistantTurn(
   };
 }
 
+function pruneStaleClarifications(state: DiscourseState): DiscourseState {
+  const pending = state.pending_clarifications.filter((c) => c.status === "pending");
+  if (pending.length === state.pending_clarifications.length) return state;
+  return discourseStateSchema.parse({
+    ...state,
+    pending_clarifications: pending
+  });
+}
+
 function findPresentedItemByOrdinalOrOption(
   items: PresentedItem[],
   input: { ordinal?: number; optionKey?: string }

packages/integrations/src/openai.ts

@@ -310,9 +310,17 @@ export async function classifyTurnWithResponses(
 }
 
 function buildTurnClassifierPromptContext(context: TurnClassifierInput) {
+  const discourseState = context.discourseState ?? null;
   return {
     normalizedText: context.normalizedText,
-    discourseState: context.discourseState ?? null,
+    discourseState: discourseState
+      ? {
+          ...discourseState,
+          pending_clarifications: discourseState.pending_clarifications.filter(
+            (c) => c.status === "pending"
+          )
+        }
+      : null,
     entityRegistry: context.entityRegistry ?? []
   };
 }

packages/integrations/src/prompts/turn-classifier.ts

@@ -42,7 +42,7 @@ export const turnClassifierSystemPrompt = buildPromptSpec([
   {
     title: "Context Interpretation",
     lines: [
-      "discourseState.pending_clarifications: Active clarifications the assistant is waiting on. If blocking clarifications exist, the user is likely answering one.",
+      "discourseState.pending_clarifications: Active clarifications the assistant is waiting on. If pending clarifications exist, the user is likely answering one.",
       "discourseState.focus_entity_id / currently_editable_entity_id: The entity the conversation is focused on. Edit verbs with pronouns ('move it', 'reschedule that') refer to this entity.",
       "discourseState.mode: Current conversation mode (planning, editing, clarifying, confirming).",
       "entityRegistry: List of conversation entities including proposal_option (pending proposals), task, clarification, etc. Check for active proposals when classifying confirmation.",