leaning into uid and muid

Author: spoons-and-mirrors

lib/prompts/compress.md

@@ -38,7 +38,15 @@ Before compressing, ask: _"Is this range closed enough to become summary-only?"_
 BOUNDARY MATCHING
 You specify boundaries by matching unique text strings in the conversation. CRITICAL: In code-centric conversations, strings repeat often. Provide sufficiently unique text to match exactly once. If a match fails (not found or found multiple times), the tool will error - extend your boundary string with more surrounding context in order to make SURE the tool does NOT error.
 
+SELECTION ORDER (STRICT):
+
+1. Use `muid` / `uid` anchors first (most reliable, preferred default)
+2. Only if those are unavailable, use long distinctive verbatim substrings
+
+Do NOT use short generic status/progress phrases as boundaries (`task_id`, `Done — I ...`, short patch headers, etc.) because they commonly appear multiple times and will fail with ambiguity.
+
 WHERE TO PICK STRINGS FROM (important for reliable matching):
+
 - `muid` and `uid` strings in message and tool output annotations (MOST RELIABLE - guaranteed unique)
 - Your own assistant text responses (MOST RELIABLE - always stored verbatim)
 - The user's own words in their messages

lib/prompts/nudge.md

@@ -20,5 +20,5 @@ Avoid unnecessary context build-up with targeted uses of the `compress` tool. St
 
 If you are performing a critical atomic operation, do not interrupt it, but make sure to perform context management rapidly
 
-Be mindful of the startString and endString you use for compression and prefer using `muid` and `uid` strings for reliable boundary matching. Ensure your summaries are inclusive of all parts of the range.
+Be mindful of the startString and endString you use for compression. Use `muid` and `uid` strings AS THE DEFAULT boundary anchors whenever available (do NOT rely on generic prose snippets that can repeat). Ensure your summaries are inclusive of all parts of the range.
 </instruction>

lib/prompts/system.md

@@ -14,7 +14,13 @@ MACRO: for completed phases, distilling entire chapters of conversation
 A strategic and regular use of the `compress` tool is encouraged to maintain a focused context. Be proactive and deliberate in managing your context.
 
 BOUNDARY MATCHING
-`compress` uses inclusive string boundaries, matching a string at the start of a message or tool output will consume the entire item. User messages are annotated with `muid`, tool outputs with `uid`, and are intended for you to use as startString and endString anchors to avoid any potential mismatch errors. You can also use unique text from your own reasoning or text outputs, but be sure to provide more than enough surrounding context to ensure a unique match. The preferred way to match is still to use `muid` and `uid` strings.
+`compress` uses inclusive string boundaries, matching a string at the start of a message or tool output will consume the entire item. User messages are annotated with `muid`, tool outputs with `uid`.
+
+DEFAULT RULE (HIGH PRIORITY): Use `muid` / `uid` anchors for BOTH `startString` and `endString` whenever they exist. Treat these IDs as the canonical boundary keys.
+
+AVOID generic prose boundaries that can repeat (for example: `task_id: ...`, `Done — I ...`, short status lines, common code headers). Repeated strings will cause ambiguity failures.
+
+Fallback only if `muid`/`uid` cannot be used: choose a long, highly distinctive verbatim substring that appears exactly once.
 
 THE SUMMARY STANDARD
 Your summary MUST be technical and specific enough to preserve FULL understanding of what transpired, such that NO ambiguity remains about what asked, found, planned, done, or decided - yet noise free

lib/tools/compress.ts

@@ -24,10 +24,14 @@ export function createCompressTool(ctx: ToolContext): ReturnType<typeof tool> {
                 .object({
                     startString: tool.schema
                         .string()
-                        .describe("Unique text from conversation marking the beginning of range"),
+                        .describe(
+                            "Unique text marking range start. Prefer exact `[muid_x]` or `[uid_x]` anchors over prose.",
+                        ),
                     endString: tool.schema
                         .string()
-                        .describe("Unique text marking the end of range"),
+                        .describe(
+                            "Unique text marking range end. Prefer exact `[muid_x]` or `[uid_x]` anchors over prose.",
+                        ),
                     summary: tool.schema
                         .string()
                         .describe("Complete technical summary replacing all content in range"),

lib/tools/utils.ts

@@ -176,14 +176,19 @@ export function findStringInMessages(
     }
 
     if (exactMatches.length > 1) {
+        const candidates = exactMatches
+            .slice(0, 5)
+            .map((m) => `${m.messageId}@${m.messageIndex}`)
+            .join(", ")
         clog.error(C.BOUNDARY, `${stringType}: MULTIPLE exact matches - ambiguous`, {
             count: exactMatches.length,
             matches: exactMatches.map((m) => ({ msgId: m.messageId, idx: m.messageIndex })),
             searchString: searchString.substring(0, 150),
         })
         throw new Error(
             `Found multiple matches for ${stringType}. ` +
-                `Provide more surrounding context to uniquely identify the intended match.`,
+                `Use a [muid_x] or [uid_x] anchor when possible, or provide more unique surrounding context. ` +
+                `Candidates: ${candidates}${exactMatches.length > 5 ? ", ..." : ""}`,
         )
     }
 
@@ -260,7 +265,7 @@ export function findStringInMessages(
         })
         throw new Error(
             `Found multiple matches for ${stringType}. ` +
-                `Provide more unique surrounding context to disambiguate.`,
+                `Use a [muid_x] or [uid_x] anchor when possible, or provide more unique surrounding context to disambiguate.`,
         )
     }