refactor: update preflight handling and enhance low-confidence search quality guidance

- Modified preflight output structure to support both full preflight cards and flattened responses based on context.
- Updated the logic in `buildEvidenceLock` to ensure low-confidence search quality status provides clear guidance for editing restrictions.
- Added tests to validate behavior when search quality is low, ensuring readiness checks and next action messages are accurate.

Author: PatrickSys

src/index.ts

@@ -1190,17 +1190,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }
         }
 
-        // Build lean preflight: flatten to { ready, reason } for agent consumption
-        let preflightOutput: { ready: boolean; reason?: string } | undefined;
+        // For edit/refactor/migrate: return full preflight card (risk, patterns, impact, etc.).
+        // For explore or lite-only: return flattened { ready, reason }.
+        let preflightPayload: { ready: boolean; reason?: string } | Record<string, unknown> | undefined;
         if (preflight) {
           const el = preflight.evidenceLock;
-          preflightOutput = {
+          // Full card per tool schema; add top-level ready/reason for backward compatibility
+          preflightPayload = {
+            ...preflight,
             ready: el?.readyToEdit ?? false,
             ...(el && !el.readyToEdit && el.nextAction && { reason: el.nextAction })
           };
         } else if (editPreflight) {
           const el = editPreflight.evidenceLock;
-          preflightOutput = {
+          preflightPayload = {
             ready: el?.readyToEdit ?? false,
             ...(el && !el.readyToEdit && el.nextAction && { reason: el.nextAction })
           };
@@ -1221,7 +1224,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         hint: searchQuality.nextSteps[0]
                       })
                   },
-                  ...(preflightOutput && { preflight: preflightOutput }),
+                  ...(preflightPayload && { preflight: preflightPayload }),
                   results: results.map((r) => {
                     const relationships = enrichResult(r);
                     // Condensed relationships: importedBy count + hasTests flag

src/preflight/evidence-lock.ts

@@ -181,10 +181,10 @@ export function buildEvidenceLock(input: BuildEvidenceLockInput): EvidenceLock {
 
   // Hard gate: low search quality overrides everything.
   // If retrieval is bad, we CANNOT claim readiness regardless of evidence counts.
+  // Surface low-confidence guidance so callers see the actual reason edits are blocked.
   if (input.searchQualityStatus === 'low_confidence') {
     if (status === 'pass') status = 'warn';
-    nextAction =
-      nextAction || 'Search quality is low. Refine query or add concrete symbols before editing.';
+    nextAction = 'Search quality is low. Refine query or add concrete symbols before editing.';
     if (!gaps.includes('Search quality is low')) {
       gaps.push('Search quality is low — evidence may be unreliable');
     }

tests/evidence-lock.test.ts

@@ -198,3 +198,39 @@ describe('Epistemic stress detection', () => {
     expect(lock.readyToEdit).toBe(true);
   });
 });
+
+describe('Low-confidence search quality gate', () => {
+  const lowConfidenceMessage =
+    'Search quality is low. Refine query or add concrete symbols before editing.';
+
+  it('forces readyToEdit false when searchQualityStatus is low_confidence', () => {
+    const lock = buildEvidenceLock({
+      results: [makeResult('src/a.ts'), makeResult('src/b.ts'), makeResult('src/c.ts')],
+      preferredPatterns: [
+        { pattern: 'inject()' },
+        { pattern: 'signals' }
+      ],
+      relatedMemories: [makeMemory('1'), makeMemory('2')],
+      failureWarnings: [],
+      searchQualityStatus: 'low_confidence'
+    });
+
+    expect(lock.readyToEdit).toBe(false);
+    expect(lock.nextAction).toBe(lowConfidenceMessage);
+  });
+
+  it('overrides prior warn nextAction with low-confidence guidance', () => {
+    // Evidence that yields status 'warn' and "Proceed cautiously..." before low_confidence gate
+    const lock = buildEvidenceLock({
+      results: [makeResult('src/a.ts')],
+      preferredPatterns: [{ pattern: 'Use service wrapper' }],
+      relatedMemories: [makeMemory('1', { stale: true })],
+      failureWarnings: [],
+      searchQualityStatus: 'low_confidence'
+    });
+
+    expect(lock.readyToEdit).toBe(false);
+    expect(lock.nextAction).toBe(lowConfidenceMessage);
+    expect(lock.nextAction).not.toContain('Proceed cautiously');
+  });
+});