@mrclrchtr/supi-code-intelligence 1.9.0 → 1.10.0

package/src/tool/guidance.ts

@@ -17,26 +17,33 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
   CodeIntelligenceToolPromptSurface
 >;
 
-// ── Cross-family orchestration guidelines ──────────────────────────────
+// ── Intent-first orchestration guidelines ─────────────────────────────
 //
-// These are appended to the appropriate code_* tools so the model sees a
-// coherent strategy for choosing between code_*, lsp_*, and tree_sitter_*
-// tools.  They do not re-own substrate metadata — each of the other packages
-// describes and documents its own tools independently.
+// These steer the model toward choosing tools by user intent rather than
+// by implementation family.  Substrate tools (lsp_*, tree_sitter_*) are
+// described as expert follow-up surfaces, not the primary choice.
 
-const ORCHESTRATION_GUIDELINES: Record<CodeIntelligenceToolName, string[]> = {
+const INTENT_GUIDELINES: Record<CodeIntelligenceToolName, string[]> = {
   code_brief: [
-    "After code_brief, use lsp_hover/lsp_definition/lsp_references for semantic detail or tree_sitter_* for quick structure.",
+    "Use code_brief for prioritized orientation on a project, package, file, or symbol.",
+    "The planner selects the best provider (semantic or structural) automatically.",
+    "After code_brief, use lsp_hover/lsp_definition/lsp_references for deeper semantic detail or tree_sitter_* for quick structural context.",
   ],
   code_map: ["Use code_brief instead when you need prioritized guidance."],
   code_relations: [
-    "Follow caller results with lsp_references/lsp_definition; use tree_sitter_callees for structural outgoing calls.",
+    "The planner routes callers/implementations to semantic (LSP) analysis and callees to structural (tree-sitter) analysis.",
+    "Follow caller results with lsp_references/lsp_definition for additional context; use tree_sitter_callees for structural outgoing calls as a debug surface.",
   ],
   code_affected: [
-    "Use lsp_references instead when you need a plain reference list, not impact analysis.",
+    "Uses semantic evidence for blast-radius assessment. Does not fall back to heuristic text search.",
+    "Use lsp_references when you only need a plain reference list without impact analysis.",
   ],
   code_pattern: [
-    "Use tree_sitter_query or lsp_hover/lsp_definition when you need structure or semantic precision.",
+    "The only code_* tool that uses heuristic/text search behavior. For structured or semantic precision, use tree_sitter_query or lsp_hover/lsp_definition instead.",
+  ],
+  code_refactor: [
+    "Uses semantic provider for precise rename/code-action operations with safety checks.",
+    "Does not fall back to heuristic text replacement — if the provider cannot produce precise edits, the tool reports unavailable.",
   ],
 };
 
@@ -49,7 +56,7 @@ export function buildCodeIntelligenceToolPromptSurfaces(): CodeIntelligenceToolP
       {
         description: spec.description,
         promptSnippet: spec.promptSnippet,
-        promptGuidelines: [...spec.basePromptGuidelines, ...ORCHESTRATION_GUIDELINES[spec.name]],
+        promptGuidelines: [...spec.basePromptGuidelines, ...INTENT_GUIDELINES[spec.name]],
       } satisfies CodeIntelligenceToolPromptSurface,
     ]),
   ) as CodeIntelligenceToolPromptSurfaceMap;

package/src/tool/tool-specs.ts

@@ -5,6 +5,7 @@ import { executeAffectedTool } from "./execute-affected.ts";
 import { executeBriefTool } from "./execute-brief.ts";
 import { executeMapTool } from "./execute-map.ts";
 import { executePatternTool } from "./execute-pattern.ts";
+import { executeRefactorTool } from "./execute-refactor.ts";
 import { executeRelationsTool } from "./execute-relations.ts";
 
 const PathParam = Type.String({ description: "Scope path" });
@@ -28,6 +29,7 @@ export const CODE_INTELLIGENCE_TOOL_NAMES = [
   "code_relations",
   "code_affected",
   "code_pattern",
+  "code_refactor",
 ] as const;
 export type CodeIntelligenceToolName = (typeof CODE_INTELLIGENCE_TOOL_NAMES)[number];
 
@@ -94,6 +96,17 @@ const CodePatternParameters = Type.Object(
   { additionalProperties: false },
 );
 
+const CodeRefactorParameters = Type.Object(
+  {
+    operation: Type.String({ description: "Refactor operation: rename" }),
+    file: FileParam,
+    line: LineParam,
+    character: CharacterParam,
+    newName: Type.String({ description: "New name for rename operation" }),
+  },
+  { additionalProperties: false },
+);
+
 export interface CodeIntelligenceToolDefinitionSpec {
   name: CodeIntelligenceToolName;
   label: string;
@@ -162,4 +175,16 @@ export const CODE_INTELLIGENCE_TOOL_SPECS = [
     run: (params, ctx) =>
       executePatternTool(params as Parameters<typeof executePatternTool>[0], ctx),
   },
+  {
+    name: "code_refactor",
+    label: "Code Refactor",
+    description: "Apply a precise semantic refactor (rename) with direct-apply safety checks.",
+    promptSnippet: "code_refactor — semantic refactor with direct apply",
+    basePromptGuidelines: [
+      "Use code_refactor for safe semantic rename operations with precise workspace edits.",
+    ],
+    parameters: CodeRefactorParameters,
+    run: (params, ctx) =>
+      executeRefactorTool(params as Parameters<typeof executeRefactorTool>[0], ctx),
+  },
 ] as const satisfies readonly CodeIntelligenceToolDefinitionSpec[];