@mrclrchtr/supi-code-intelligence 6.3.0 → 6.4.0

package/src/substrate/lsp/source-tracking.ts

@@ -0,0 +1,247 @@
+import { statSync } from "node:fs";
+import * as path from "node:path";
+import {
+  type CodeRequestControl,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
+import type {
+  BulkTrackFileOutcome,
+  WorkspaceLspRuntime,
+  WorkspaceSourceInventory,
+} from "@mrclrchtr/supi-lsp/api";
+import { isMissingFileError, MAX_BULK_TRACK_FILES } from "@mrclrchtr/supi-lsp/api";
+
+/** Typed session state for sentinel maintenance and automatic source tracking. */
+export interface LspMaintenanceState {
+  readonly sentinelSnapshot: Map<string, number>;
+  readonly sourceBaseline: ReadonlySet<string> | null;
+  readonly createdSourceQueue: readonly string[];
+}
+
+/** Source discovery and tracking facts from one broad diagnostic refresh. */
+export interface SourceTrackingReport {
+  readonly status: WorkspaceSourceInventory["status"];
+  readonly reason: WorkspaceSourceInventory["reason"];
+  readonly observedFileCount: number;
+  readonly discovered: readonly string[];
+  readonly tracked: readonly string[];
+  readonly unsupported: readonly string[];
+  readonly unavailable: readonly string[];
+  readonly deferred: number;
+}
+
+/** Create empty source state with an optional lifecycle-seeded sentinel snapshot. */
+export function createLspMaintenanceState(
+  sentinelSnapshot: Map<string, number> = new Map(),
+): LspMaintenanceState {
+  return {
+    sentinelSnapshot,
+    sourceBaseline: null,
+    createdSourceQueue: [],
+  };
+}
+
+/** Replace the sentinel portion of maintenance state without source state. */
+export function withSentinelSnapshot(
+  state: LspMaintenanceState,
+  sentinelSnapshot: Map<string, number>,
+): LspMaintenanceState {
+  return { ...state, sentinelSnapshot };
+}
+
+/** Discover source additions and process a bounded queue for one refresh. */
+export async function trackCreatedSources(options: {
+  readonly runtime: WorkspaceLspRuntime;
+  readonly cwd: string;
+  readonly state: LspMaintenanceState;
+  readonly scope?: string | null;
+  readonly control?: CodeRequestControl;
+}): Promise<{ state: LspMaintenanceState; report: SourceTrackingReport }> {
+  const inventory = await options.runtime.scanWorkspaceSources(options.control);
+  throwIfCodeRequestInterrupted(options.control);
+  if (inventory.status === "limited") {
+    return {
+      state: options.state,
+      report: createReport({
+        cwd: options.cwd,
+        inventory,
+        discovered: [],
+        tracked: [],
+        unsupported: [],
+        unavailable: [],
+        deferred: options.state.createdSourceQueue,
+        control: options.control,
+      }),
+    };
+  }
+
+  const discovered = discoverCreatedPaths(
+    options.state.sourceBaseline,
+    inventory.files,
+    options.control,
+  );
+  const queue = removeMissingPaths(
+    options.state.sourceBaseline === null
+      ? []
+      : deduplicatePaths([...options.state.createdSourceQueue, ...discovered], options.control),
+    options.control,
+  );
+  const selected = selectScopedPaths(queue, options.cwd, options.scope, options.control).slice(
+    0,
+    MAX_BULK_TRACK_FILES,
+  );
+  const batch =
+    selected.length === 0
+      ? { outcomes: [] as const }
+      : await options.runtime.bulkTrackFiles(selected, options.control);
+  const nextQueue = retainQueuePaths(queue, selected, batch.outcomes, options.control);
+  const nextState: LspMaintenanceState = {
+    sentinelSnapshot: options.state.sentinelSnapshot,
+    sourceBaseline: new Set(inventory.files),
+    createdSourceQueue: nextQueue,
+  };
+
+  const tracked = pathsForOutcome(batch.outcomes, "tracked");
+  const unsupported = pathsForOutcome(batch.outcomes, "unsupported");
+  const unavailable = pathsForOutcome(batch.outcomes, "unavailable");
+  return {
+    state: nextState,
+    report: createReport({
+      cwd: options.cwd,
+      inventory,
+      discovered,
+      tracked,
+      unsupported,
+      unavailable,
+      deferred: nextQueue,
+      control: options.control,
+    }),
+  };
+}
+
+function discoverCreatedPaths(
+  baseline: ReadonlySet<string> | null,
+  current: readonly string[],
+  control?: CodeRequestControl,
+): string[] {
+  if (baseline === null) return [];
+  const discovered: string[] = [];
+  for (const filePath of current) {
+    throwIfCodeRequestInterrupted(control);
+    if (!baseline.has(filePath)) discovered.push(filePath);
+  }
+  return discovered;
+}
+
+function selectScopedPaths(
+  queue: readonly string[],
+  cwd: string,
+  scope: string | null | undefined,
+  control?: CodeRequestControl,
+): string[] {
+  const resolvedScope = scope === null || scope === undefined ? null : path.resolve(cwd, scope);
+  const selected: string[] = [];
+  for (const filePath of queue) {
+    throwIfCodeRequestInterrupted(control);
+    if (resolvedScope === null || isWithinOrEqual(resolvedScope, filePath)) selected.push(filePath);
+  }
+  return selected;
+}
+
+function retainQueuePaths(
+  queue: readonly string[],
+  selected: readonly string[],
+  outcomes: readonly BulkTrackFileOutcome[],
+  control?: CodeRequestControl,
+): string[] {
+  const selectedSet = new Set(selected);
+  const outcomeByPath = new Map(outcomes.map((outcome) => [outcome.file, outcome] as const));
+  const unstarted: string[] = [];
+  const unavailable: string[] = [];
+
+  for (const filePath of queue) {
+    throwIfCodeRequestInterrupted(control);
+    if (!selectedSet.has(filePath)) {
+      unstarted.push(filePath);
+      continue;
+    }
+    const outcome = outcomeByPath.get(filePath);
+    if (!outcome) {
+      unstarted.push(filePath);
+    } else if (outcome.kind === "unavailable") {
+      unavailable.push(filePath);
+    }
+  }
+  return [...unstarted, ...unavailable];
+}
+
+function pathsForOutcome(
+  outcomes: readonly BulkTrackFileOutcome[],
+  kind: BulkTrackFileOutcome["kind"],
+): string[] {
+  return outcomes.filter((outcome) => outcome.kind === kind).map((outcome) => outcome.file);
+}
+
+function createReport(options: {
+  cwd: string;
+  inventory: WorkspaceSourceInventory;
+  discovered: readonly string[];
+  tracked: readonly string[];
+  unsupported: readonly string[];
+  unavailable: readonly string[];
+  deferred: readonly string[];
+  control?: CodeRequestControl;
+}): SourceTrackingReport {
+  return {
+    status: options.inventory.status,
+    reason: options.inventory.reason,
+    observedFileCount: options.inventory.observedFileCount,
+    discovered: displayPaths(options.cwd, options.discovered, options.control),
+    tracked: displayPaths(options.cwd, options.tracked, options.control),
+    unsupported: displayPaths(options.cwd, options.unsupported, options.control),
+    unavailable: displayPaths(options.cwd, options.unavailable, options.control),
+    deferred: options.deferred.length,
+  };
+}
+
+function displayPaths(
+  cwd: string,
+  filePaths: readonly string[],
+  control?: CodeRequestControl,
+): string[] {
+  const displayed: string[] = [];
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    const relativePath = path.relative(cwd, filePath);
+    displayed.push((relativePath || path.basename(filePath)).replaceAll(path.sep, "/"));
+  }
+  return displayed;
+}
+
+function deduplicatePaths(filePaths: readonly string[], control?: CodeRequestControl): string[] {
+  const unique = new Set<string>();
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    unique.add(filePath);
+  }
+  return [...unique];
+}
+
+function removeMissingPaths(filePaths: readonly string[], control?: CodeRequestControl): string[] {
+  const existing: string[] = [];
+  for (const filePath of filePaths) {
+    throwIfCodeRequestInterrupted(control);
+    if (!isMissingFile(filePath)) existing.push(filePath);
+  }
+  return existing;
+}
+
+function isMissingFile(filePath: string): boolean {
+  try {
+    statSync(filePath);
+    return false;
+  } catch (error) {
+    return isMissingFileError(error);
+  }
+}

package/src/tool/code_find/guidance.ts

@@ -1,8 +1,8 @@
 export const toolDescription =
-  'Search source shape with mode:"ast" or LSP workspace symbols with mode:"semantic". Modes never silently fall back. Unscoped AST scans cover visible supported files, skipping hidden and generated/dependency directories.';
+  "Search code structure or workspace symbols for structural or semantic matches. It never silently falls back to another mode or to text search.";
 
-export const promptSnippet = "explicit structural or semantic code search";
+export const promptSnippet = "search code structure or workspace symbols";
 
 export const promptGuidelines = [
-  "Use code_find for structural or semantic search evidence; use PI grep for literal/regex source search and code_graph references for symbol-identity relationships.",
+  "Use code_find for structural or semantic search, grep for text search, and code_graph for symbol relationships.",
 ];

package/src/tool/code_graph/guidance.ts

@@ -1,6 +1,6 @@
 export const toolDescription =
-  "Collect references, structural callees, and implementations for one target. Callees match source shape, not symbol identity.";
+  "Find symbol references and implementations, and list calls from a target's enclosing scope. Callee results match source shape, not symbol identity.";
 
-export const promptSnippet = "provider-backed and structural relation evidence";
+export const promptSnippet = "trace code relationships";
 
 export const promptGuidelines: string[] = [];

package/src/tool/code_health/guidance.ts

@@ -1,8 +1,8 @@
 export const toolDescription =
-  "Report live diagnostics as observations, language-server route status, and final semantic health state. Tracked-file snapshots do not prove workspace completeness; server inventory and route issue counts are workspace-wide. Server-only calls are passive.";
+  "Report live diagnostics and language-server health. Diagnostic snapshots do not prove that the whole workspace is clean; server inventory and route-status counts are always workspace-wide.";
 
-export const promptSnippet = "live workspace health observations";
+export const promptSnippet = "check live diagnostics and language-server health";
 
 export const promptGuidelines = [
-  "Use code_health with refresh:true before relying on potentially stale diagnostics; explicit refresh can recover crashed routes with tracked files in scope.",
+  "Use code_health with `refresh: true` before relying on diagnostics that can be stale.",
 ];

package/src/tool/code_health/markdown.ts

@@ -15,6 +15,7 @@ import { makeRelative, renderFileScopeStatus } from "./file-scope-markdown.ts";
 import {
   formatProcessCrashRecovery,
   formatRefreshElapsed,
+  formatSourceTracking,
   formatStaleDiagnosticRestarts as formatStaleDiagnosticRestartsText,
   isFileReadinessPending,
 } from "./refresh-outcome.ts";
@@ -57,8 +58,9 @@ function renderRefreshStatus(
     case "completed": {
       const fileReadinessPending = isFileReadinessPending(data.refresh, data.semanticState);
       lines.push(
-        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh, fileReadinessPending))}`,
+        `**${refreshAttemptLabel(data.refresh)}**: ${asSentence(completedRefreshText(data.refresh, fileReadinessPending, false))}`,
       );
+      renderSourceTracking(lines, data.refresh);
       lines.push(`**Stale assessment**: ${asSentence(staleAssessmentText(data.refresh))}`);
       lines.push("");
       return;
@@ -74,6 +76,7 @@ function renderRefreshStatus(
       lines.push(
         `**${refreshAttemptLabel(data.refresh)}**: failed — ${data.refresh.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence}`,
       );
+      renderSourceTracking(lines, data.refresh);
       lines.push("");
       return;
     }
@@ -97,6 +100,7 @@ function renderRefreshStatus(
 function completedRefreshText(
   attempt: Extract<HealthRefreshAttempt, { kind: "completed" }>,
   fileReadinessPending = attempt.fileReadiness === "pending",
+  includeSourceTracking = true,
 ): string {
   const processCrashRecovery = formatProcessCrashRecovery(attempt.processCrashRecovery);
   const noOp =
@@ -110,15 +114,26 @@ function completedRefreshText(
       ? "completed no-op — no active clients were targeted"
       : `completed — ${attempt.attemptedActiveClients} active client${plural(attempt.attemptedActiveClients)} targeted`;
   const staleRestart = noOp ? null : formatStaleDiagnosticRestarts(attempt);
-  const outcome = [staleRestart, processCrashRecovery].filter(
-    (value): value is string => value !== null,
-  );
+  const sourceTracking = formatSourceTracking(attempt.sourceTracking);
+  const outcome = [
+    includeSourceTracking ? sourceTracking : null,
+    staleRestart,
+    processCrashRecovery,
+  ].filter((value): value is string => value !== null);
   const withOutcome = outcome.length > 0 ? `${base}; ${outcome.join("; ")}` : base;
   return attempt.operationScope === "workspace-runtime"
     ? `${withOutcome}; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
     : withOutcome;
 }
 
+function renderSourceTracking(
+  lines: string[],
+  attempt: Pick<HealthRefreshAttempt, "sourceTracking">,
+): void {
+  const sourceTracking = formatSourceTracking(attempt.sourceTracking);
+  if (sourceTracking) lines.push(`**Source discovery**: ${asSentence(sourceTracking)}`);
+}
+
 function refreshAttemptLabel(attempt: Pick<HealthRefreshAttempt, "operationScope">): string {
   return attempt.operationScope === "file-runtime"
     ? "File LSP maintenance attempt"
@@ -160,10 +175,11 @@ function refreshAttemptOutcome(attempt: HealthRefreshAttempt): string {
     ? formatProcessCrashRecovery(attempt.processCrashRecovery)
     : null;
   const staleRestart = formatStaleDiagnosticRestarts(attempt);
+  const sourceTracking = formatSourceTracking(attempt.sourceTracking);
   const evidence = attempt.diagnosticEvidence
     ? `; ${formatDiagnosticEvidence(attempt.diagnosticEvidence)}`
     : "";
-  return `failed — ${attempt.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${evidence}`;
+  return `failed — ${attempt.reason}${staleRestart ? `; ${staleRestart}` : ""}${processCrashRecovery ? `; ${processCrashRecovery}` : ""}${sourceTracking ? `; ${sourceTracking}` : ""}${evidence}`;
 }
 
 function refreshOperationScopeText(attempt: HealthRefreshAttempt): string {

package/src/tool/code_health/refresh-outcome.ts

@@ -3,6 +3,7 @@ import type {
   ProcessCrashRecoveryReport,
 } from "@mrclrchtr/supi-lsp/api";
 import type { SemanticHealthState } from "../../session/health-types.ts";
+import type { SourceTrackingReport } from "../../substrate/lsp/source-tracking.ts";
 
 /** Report whether a file health result is waiting for semantic readiness. */
 export function isFileReadinessPending(
@@ -64,6 +65,16 @@ function formatProcessCrashRecoveryEntry(entry: ProcessCrashRecoveryEntry): stri
   return `${entry.name} @ ${entry.root}: ${outcome}${action}${failure}`;
 }
 
+/** Format source discovery and bounded tracking counts separately from diagnostics. */
+export function formatSourceTracking(
+  report: SourceTrackingReport | null | undefined,
+): string | null {
+  if (!report) return null;
+  const inventory =
+    report.status === "complete" ? "complete" : `limited (${report.reason ?? "unknown reason"})`;
+  return `source discovery: ${inventory}; ${report.observedFileCount} source files observed, ${report.discovered.length} discovered, ${report.tracked.length} tracked, ${report.unsupported.length} unsupported, ${report.unavailable.length} unavailable, ${report.deferred} deferred`;
+}
+
 /** Format the age of a retained refresh attempt for a status line. */
 export function formatRefreshElapsed(milliseconds: number): string {
   const seconds = Math.max(0, Math.round(milliseconds / 1_000));

package/src/tool/code_health/refresh-status.ts

@@ -14,6 +14,14 @@ import { readSemanticHealthState } from "./semantic-state.ts";
 
 /** Render current and retained health refresh status for the TUI. */
 
+/** Read source discovery counts from structured health details. */
+export function readSourceTrackingStatus(source: Record<string, unknown> | null): string | null {
+  if (!source || (source.status !== "complete" && source.status !== "limited")) return null;
+  const reason =
+    source.status === "limited" && typeof source.reason === "string" ? ` (${source.reason})` : "";
+  return `${source.status}${reason}: ${readNumber(source.observedFileCount)} observed, ${readArrayLength(source.discovered)} discovered, ${readArrayLength(source.tracked)} tracked, ${readArrayLength(source.unsupported)} unsupported, ${readArrayLength(source.unavailable)} unavailable, ${readNumber(source.deferred)} deferred`;
+}
+
 export function readRefreshStatus(data: Record<string, unknown> | null): string | null {
   const refresh = readRecord(data?.refresh);
   if (!refresh) return null;
@@ -88,19 +96,21 @@ export function readCompactRefreshStatus(data: Record<string, unknown> | null):
   const refresh = readRecord(data?.refresh);
   if (!refresh || (refresh.kind !== "completed" && refresh.kind !== "failed")) return null;
 
+  const sourceTracking = formatSourceTracking(readRecord(refresh.sourceTracking));
   const processCrashRecovery = formatCompactProcessCrashRecovery(
     readProcessCrashRecovery(refresh.processCrashRecovery),
   );
   if (refresh.kind === "failed") {
     const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
     return (
-      [staleRestart, processCrashRecovery]
+      [sourceTracking, staleRestart, processCrashRecovery]
         .filter((value): value is string => value !== null)
         .join("; ") || null
     );
   }
   const fileReadinessPending = isPendingFileReadiness(data);
   if (
+    !sourceTracking &&
     !processCrashRecovery &&
     readNumber(refresh.restartedClients) === 0 &&
     !fileReadinessPending
@@ -110,7 +120,7 @@ export function readCompactRefreshStatus(data: Record<string, unknown> | null):
 
   const staleRestart = formatStaleDiagnosticRestartsForRecord(refresh);
   const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
-  return [staleRestart, processCrashRecovery, readiness]
+  return [sourceTracking, staleRestart, processCrashRecovery, readiness]
     .filter((value): value is string => value !== null)
     .join("; ");
 }
@@ -123,6 +133,7 @@ export function readPreviousRefreshStatus(data: Record<string, unknown> | null):
   const attempt = readRecord(refresh.lastAttempt);
   if (!attempt) return null;
   const evidence = formatCompactDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  const sourceTracking = formatSourceTracking(readRecord(attempt.sourceTracking));
   const processCrashRecovery = formatCompactProcessCrashRecovery(
     readProcessCrashRecovery(attempt.processCrashRecovery),
   );
@@ -131,7 +142,7 @@ export function readPreviousRefreshStatus(data: Record<string, unknown> | null):
     attempt.kind === "completed" &&
     isFileReadinessPending(attempt, readSemanticHealthState(data?.semanticState));
   const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
-  const outcome = [readiness, staleRestart, processCrashRecovery, evidence]
+  const outcome = [readiness, sourceTracking, staleRestart, processCrashRecovery, evidence]
     .filter((value): value is string => value !== null)
     .join("; ");
   if (attempt.kind === "failed") {
@@ -170,6 +181,7 @@ function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   const attempt = readRecord(refresh.lastAttempt);
   if (!attempt) return "";
   const evidence = formatDiagnosticEvidence(readRecord(attempt.diagnosticEvidence));
+  const sourceTracking = formatSourceTracking(readRecord(attempt.sourceTracking));
   const staleRestart = formatStaleDiagnosticRestartsForRecord(attempt);
   const processCrashRecovery = formatProcessCrashRecovery(
     readProcessCrashRecovery(attempt.processCrashRecovery),
@@ -177,7 +189,7 @@ function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   const fileReadinessPending =
     attempt.kind === "completed" && isFileReadinessPending(attempt, null);
   const readiness = fileReadinessPending ? "LSP may still be warming; retry shortly" : null;
-  const outcome = [readiness, staleRestart, processCrashRecovery, evidence]
+  const outcome = [readiness, sourceTracking, staleRestart, processCrashRecovery, evidence]
     .filter((value): value is string => value !== null)
     .join("; ");
   if (attempt.kind === "failed") {
@@ -191,6 +203,15 @@ function formatLastRefreshSuffix(refresh: Record<string, unknown>): string {
   return "";
 }
 
+function formatSourceTracking(source: Record<string, unknown> | null): string | null {
+  const status = readSourceTrackingStatus(source);
+  return status ? `source discovery ${status}` : null;
+}
+
+function readArrayLength(value: unknown): number {
+  return Array.isArray(value) ? value.length : 0;
+}
+
 function formatCompactDiagnosticEvidence(evidence: Record<string, unknown> | null): string | null {
   const counts = readEvidenceCounts(evidence);
   if (!counts) return null;

package/src/tool/code_health/tui.ts

@@ -29,6 +29,7 @@ import {
   readCompactRefreshStatus,
   readPreviousRefreshStatus,
   readRefreshStatus,
+  readSourceTrackingStatus,
 } from "./refresh-status.ts";
 import { formatSemanticHealthState, readSemanticHealthState } from "./semantic-state.ts";
 
@@ -192,6 +193,8 @@ function buildStatusBar(data: Record<string, unknown> | null, theme: Theme): Tex
   const semanticStatus = readSemanticStatus(data);
   const structuralStatus = readString(data, "structuralStatus");
   const refreshStatus = readRefreshStatus(data);
+  const refresh = readRecord(data?.refresh);
+  const sourceTracking = readSourceTrackingStatus(readRecord(refresh?.sourceTracking));
 
   const lspColor = semanticStatus.startsWith("ready") ? "success" : "warning";
   const structuralColor = structuralStatus === "ready" ? "success" : "muted";
@@ -204,6 +207,7 @@ function buildStatusBar(data: Record<string, unknown> | null, theme: Theme): Tex
     lines.push(`Tree-sitter: ${theme.fg(structuralColor, structuralStatus)}`);
   }
   if (refreshStatus) lines.push(`Diagnostics: ${theme.fg("dim", refreshStatus)}`);
+  if (sourceTracking) lines.push(`Source discovery: ${theme.fg("dim", sourceTracking)}`);
 
   return new Text(lines.join("  "), 0, 0);
 }

package/src/tool/code_inspect/guidance.ts

@@ -1,6 +1,8 @@
 export const toolDescription =
-  "Inspect one exact point for syntax, the narrowest enclosing declaration, hover, definition, and nearby diagnostics. Use for point facts, not broad Orientation.";
+  "Inspect one source location for syntax, its enclosing declaration, hover information, definitions, and nearby diagnostics. Use it for point-local facts, not broad code context.";
 
-export const promptSnippet = "factual point inspection";
+export const promptSnippet = "inspect a source location";
 
-export const promptGuidelines: string[] = [];
+export const promptGuidelines = [
+  "Use code_inspect for diagnostics near a source location; use code_health for broader diagnostics or language-server status.",
+];

package/src/tool/code_orientation/guidance.ts

@@ -1,9 +1,8 @@
 export const toolDescription =
-  "Orient around the workspace or one path, module, or target focus before surgical work. Omit focus for workspace Orientation. Workspace Orientation includes manifest and dependency inventories. For one-file work, use focused path Orientation. Directory focus may surface local instruction files.";
+  "Return observed workspace or focused code context to choose what source to inspect next. Omit `focus` for workspace context. A directory focus can surface local instruction files.";
 
-export const promptSnippet = "workspace/path/module/symbol Orientation";
+export const promptSnippet = "orient around workspace or code context";
 
 export const promptGuidelines = [
-  "Use code_orientation before broad file reading when you need direct workspace, package, directory, file, or symbol facts.",
-  "Use code_graph for relationships and code_health for provider or diagnostic state.",
+  "Use code_orientation before broad source reading when workspace or path context can narrow the files.",
 ];

package/src/tool/code_refactor_apply/guidance.ts

@@ -1,5 +1,5 @@
 export const toolDescription =
-  "Apply one fresh stored refactor plan by planId after safety checks; mutates its files.";
+  "Apply a fresh stored refactor plan to change its files. It does not create or regenerate a plan.";
 
 export const promptSnippet = "apply a stored refactor plan";
 

package/src/tool/code_refactor_plan/guidance.ts

@@ -1,8 +1,6 @@
 export const toolDescription =
-  "Preview one semantic rename, extraction, import cleanup, or dead-code deletion and return a planId without mutating files.";
+  "Preview a semantic refactor without changing files or falling back to text edits.";
 
-export const promptSnippet = "preview a precise semantic refactor";
+export const promptSnippet = "preview a semantic refactor";
 
-export const promptGuidelines = [
-  "Use code_refactor_plan for preview only, then call code_refactor_apply with its planId.",
-];
+export const promptGuidelines: string[] = [];

package/src/tool/code_resolve/guidance.ts

@@ -1,8 +1,8 @@
 export const toolDescription =
-  "Resolve one provider-backed anchor or semantic symbol query to session handles, or enumerate a file's declarations as a bounded Target group. Anchors must identify real symbols";
+  "Resolve a real symbol anchor or semantic query to target handles, or list a file's declarations as a target group. Symbol lookup does not fall back to text search.";
 
-export const promptSnippet = "resolve a precise target or enumerate a file’s target group";
+export const promptSnippet = "resolve symbols or file declarations";
 
 export const promptGuidelines = [
-  "Use code_resolve when a symbol query may be ambiguous, when later calls should share a stable target handle, or when a known file’s declarations should be enumerated.",
+  "Use code_resolve when a symbol query can match multiple symbols or when a later tool requires a target handle.",
 ];

package/src/tool/guidance.ts

@@ -1,10 +1,8 @@
-// Model-facing prompt surfaces for the eight public code-intelligence tools.
-//
-// Ownership map (docs/pi/tool-guidance.md): each model-facing fact lives in
-// exactly one home — the per-tool guidance module. This aggregator assembles
-// the canonical surface map consumed by registration.
-// Parameter mechanics (formats, enum semantics, cross-field rules) live in
-// schemas.ts / per-tool spec.ts and are not repeated here.
+/**
+ * Each tool owns its model-facing text. This module assembles the canonical
+ * surface map used by registration. Parameter mechanics stay in specs and
+ * shared schemas.
+ */
 
 import type { CodeIntelligenceToolName } from "../types/index.ts";
 import {
@@ -48,9 +46,13 @@ import {
   promptSnippet as resolveSnippet,
 } from "./code_resolve/guidance.ts";
 
+/** Model-facing fields registered for one public code-intelligence tool. */
 export interface CodeIntelligenceToolPromptSurface {
+  /** Selection contract in the active provider tool definition. */
   description: string;
+  /** One-line capability phrase in the default tool list. */
   promptSnippet: string;
+  /** Optional active-tool routing or ordering reminders. */
   promptGuidelines: string[];
 }
 
@@ -59,7 +61,7 @@ export type CodeIntelligenceToolPromptSurfaceMap = Record<
   CodeIntelligenceToolPromptSurface
 >;
 
-export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptSurfaceMap = {
+export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES = {
   code_resolve: {
     description: resolveDescription,
     promptSnippet: resolveSnippet,
@@ -100,4 +102,4 @@ export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES: CodeIntelligenceToolPromptS
     promptSnippet: applySnippet,
     promptGuidelines: applyGuidelines,
   },
-};
+} satisfies CodeIntelligenceToolPromptSurfaceMap;