vibe-coding-master 0.7.37 → 0.7.39

package/README.md

@@ -455,7 +455,7 @@ Harness Studio is the UI for VCM harness maintenance.
 Use it to:
 
 - inspect fixed harness status
-- inspect detected project languages and verified language-server readiness
+- inspect detected project languages and language-server availability
 - run bootstrap
 - open Harness Engineer
 - review harness files
@@ -471,8 +471,12 @@ VCM bundles the Claude Code LSP bridge and loads it for Architect, Coder, and
 Reviewer sessions, including CCR launches. The project environment must still
 provide the language server for each detected language: `rust-analyzer`,
 `typescript-language-server`, `pyright-langserver`, `gopls`, `clangd`, or
-`jdtls`. Harness Studio reports a missing executable or failed startup probe
-with the backend diagnostic.
+`jdtls`. Their Agent definitions preload `vcm-code-navigation`, and their
+launches explicitly enable Glob while leaving Grep unavailable. The Harness
+guard also rejects shell text-search commands for those roles so unresolved
+semantic relationships cannot be hidden by textual fallback. Harness Studio
+reports whether the server executable and plugin can run; the role Session
+performs the real workspace warm-up and semantic query retries.
 
 Harness Engineer is task-scoped and runs from the active task worktree. The
 backend automatically starts a fresh Harness Engineer for each active task or

package/dist/backend/adapters/claude-adapter.js

@@ -20,6 +20,7 @@ export function createClaudeAdapter(runner) {
         },
         buildRoleStartCommand(role, command = "claude", permissionMode = "default", claudeSessionId, resume = false, model = "default", effort = "default", settingsOverride, appendSystemPrompt, pluginDirs = []) {
             const args = pluginDirs.flatMap((pluginDir) => ["--plugin-dir", pluginDir]);
+            args.push("--allowedTools", roleSearchToolOptIns(role).join(","));
             args.push("--agent", role);
             const sessionSettings = { ...settingsOverride };
             if (claudeSessionId) {
@@ -51,6 +52,11 @@ export function createClaudeAdapter(runner) {
         }
     };
 }
+function roleSearchToolOptIns(role) {
+    return role === "architect" || role === "coder" || role === "reviewer"
+        ? ["Glob"]
+        : ["Glob", "Grep"];
+}
 function formatDisplayArg(value) {
     if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) {
         return value;

package/dist/backend/cli/install-vcm-harness.js

@@ -53,6 +53,7 @@ const VCM_BASH_DEFAULT_TIMEOUT_MS = "600000";
 const VCM_AUTO_MEMORY_ENABLED = false;
 const VCM_HOOK_DEFINITIONS = [
     { eventName: "PreToolUse", matcher: "Bash", command: VCM_BASH_GUARD_HOOK_COMMAND, timeout: 10 },
+    { eventName: "PreToolUse", matcher: "Grep", command: VCM_BASH_GUARD_HOOK_COMMAND, timeout: 10 },
     { eventName: "UserPromptSubmit", command: VCM_HOOK_COMMAND, timeout: 5 },
     { eventName: "Stop", command: VCM_STOP_HOOK_COMMAND, timeout: 10 },
     { eventName: "StopFailure", command: VCM_HOOK_COMMAND, timeout: 5 },
@@ -65,18 +66,21 @@ const AGENT_FRONTMATTER = {
     },
     architect: {
         description: "VCM architecture role for plans, module boundaries, public contracts, verifiable behavior, and docs sync.",
-        tools: "Read, Grep, Glob, Bash, Edit, Write, Agent, LSP"
+        tools: "Read, Glob, Bash, Edit, Write, Agent, LSP",
+        skills: ["vcm-code-navigation"]
     },
     coder: {
         description: "VCM implementation role for scoped code changes and focused tests.",
-        tools: "Read, Grep, Glob, Bash, Edit, Write, Agent, LSP"
+        tools: "Read, Glob, Bash, Edit, Write, Agent, LSP",
+        skills: ["vcm-code-navigation"]
     },
     tester: {
         description: "VCM testing role for validation, test adequacy, approved-scope validation, and risk findings."
     },
     reviewer: {
         description: "VCM independent gate review role for architecture plans, validation adequacy, and code diffs.",
-        tools: "Read, Grep, Glob, Bash, Write, LSP"
+        tools: "Read, Glob, Bash, Write, LSP",
+        skills: ["vcm-code-navigation"]
     },
     translator: {
         description: "VCM task-scoped translation tool role for conversation translation, file translation, bootstrap, and memory updates."
@@ -99,6 +103,16 @@ const REQUIRED_AGENT_TOOLS = {
     coder: ["Agent", "LSP"],
     reviewer: ["LSP"]
 };
+const FORBIDDEN_AGENT_TOOLS = {
+    architect: ["Grep"],
+    coder: ["Grep"],
+    reviewer: ["Grep"]
+};
+const REQUIRED_AGENT_SKILLS = {
+    architect: ["vcm-code-navigation"],
+    coder: ["vcm-code-navigation"],
+    reviewer: ["vcm-code-navigation"]
+};
 const MANAGED_FILES = [
     {
         path: "CLAUDE.md",
@@ -266,7 +280,7 @@ const WHOLE_FILES = [
         path: ".claude/skills/vcm-code-navigation/SKILL.md",
         category: "skill",
         mode: 0o644,
-        content: renderSkillFile("VCM Code Navigation Skill", "vcm-code-navigation", "Use when Architect or Reviewer must resolve code symbols, references, implementations, call hierarchies, or bounded dependency paths.", renderVcmCodeNavigationSkillRules())
+        content: renderSkillFile("VCM Code Navigation Skill", "vcm-code-navigation", "Use when Architect, Coder, or Reviewer must resolve code symbols, references, implementations, call hierarchies, or bounded dependency paths.", renderVcmCodeNavigationSkillRules())
     },
     {
         path: ".claude/skills/vcm-final-acceptance/SKILL.md",
@@ -672,6 +686,12 @@ async function installManagedFile({ projectRoot, definition, dryRun, operations
     for (const requiredTool of REQUIRED_AGENT_TOOLS[definition.agentName] ?? []) {
         nextContent = ensureAgentTool(nextContent, requiredTool);
     }
+    for (const forbiddenTool of FORBIDDEN_AGENT_TOOLS[definition.agentName] ?? []) {
+        nextContent = removeAgentTool(nextContent, forbiddenTool);
+    }
+    for (const requiredSkill of REQUIRED_AGENT_SKILLS[definition.agentName] ?? []) {
+        nextContent = ensureAgentSkill(nextContent, requiredSkill);
+    }
     await writeIfChanged({
         targetPath,
         relativePath: definition.path,
@@ -714,7 +734,10 @@ function renderNewManagedFile(definition, block) {
         const tools = frontmatter.tools ?? "Read, Grep, Glob, Bash, Edit, Write";
         const model = frontmatter.model ? `\nmodel: ${frontmatter.model}` : "";
         const effort = frontmatter.effort ? `\neffort: ${frontmatter.effort}` : "";
-        return `---\nname: ${definition.agentName}\ndescription: ${frontmatter.description}\ntools: ${tools}${model}${effort}\n---\n\n# ${definition.title}\n\n${block}${suffix ? `\n\n${suffix}` : ""}\n`;
+        const skills = frontmatter.skills?.length
+            ? `\nskills:\n${frontmatter.skills.map((skill) => `  - ${skill}`).join("\n")}`
+            : "";
+        return `---\nname: ${definition.agentName}\ndescription: ${frontmatter.description}\ntools: ${tools}${model}${effort}${skills}\n---\n\n# ${definition.title}\n\n${block}${suffix ? `\n\n${suffix}` : ""}\n`;
     }
     return `# ${definition.title}\n\n${block}${suffix ? `\n\n${suffix}` : ""}\n`;
 }
@@ -734,6 +757,42 @@ function ensureAgentTool(content, requiredTool) {
     const nextTools = [...tools, requiredTool].join(", ");
     return content.replace(frontmatterMatch[0], frontmatterMatch[0].replace(toolsMatch[0], `tools: ${nextTools}`));
 }
+function removeAgentTool(content, forbiddenTool) {
+    const frontmatterMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
+    if (!frontmatterMatch) {
+        return content;
+    }
+    const toolsMatch = frontmatterMatch[0].match(/^tools:\s*(.*)$/m);
+    if (!toolsMatch) {
+        return content;
+    }
+    const tools = toolsMatch[1].split(",").map((tool) => tool.trim()).filter(Boolean);
+    const nextTools = tools.filter((tool) => tool !== forbiddenTool);
+    if (nextTools.length === tools.length) {
+        return content;
+    }
+    return content.replace(frontmatterMatch[0], frontmatterMatch[0].replace(toolsMatch[0], `tools: ${nextTools.join(", ")}`));
+}
+function ensureAgentSkill(content, requiredSkill) {
+    const frontmatterMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
+    if (!frontmatterMatch) {
+        return content;
+    }
+    const frontmatter = frontmatterMatch[0];
+    const skillsMatch = frontmatter.match(/^skills:[ \t]*(?:\r?\n((?:\s+-\s+[^\r\n]+\r?\n?)*))?/m);
+    if (!skillsMatch) {
+        return content.replace(frontmatter, frontmatter.replace(/\r?\n---$/, `\nskills:\n  - ${requiredSkill}\n---`));
+    }
+    const listedSkills = (skillsMatch[1] ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.match(/^\s+-\s+(.+)$/)?.[1]?.trim())
+        .filter(Boolean);
+    if (listedSkills.includes(requiredSkill)) {
+        return content;
+    }
+    const nextSkills = `${skillsMatch[0].trimEnd()}\n  - ${requiredSkill}`;
+    return content.replace(frontmatter, frontmatter.replace(skillsMatch[0], nextSkills));
+}
 function migrateLegacyManagedFile(definition, currentContent, block) {
     const legacyContent = definition.legacyWholeFile?.trimEnd();
     if (!legacyContent) {

package/dist/backend/services/code-intelligence-service.js

@@ -127,13 +127,13 @@ async function detectCodeIntelligence(fs, repoRoot, options, probe) {
         return status;
     }));
     const languages = detectedLanguages.filter((language) => language !== undefined);
-    const readyCount = languages.filter((language) => language.state === "ready").length;
+    const runnableCount = languages.filter((language) => language.state === "server_runnable").length;
     return {
         state: languages.length === 0
             ? "not_detected"
-            : readyCount === languages.length
-                ? "ready"
-                : readyCount === 0
+            : runnableCount === languages.length
+                ? "available"
+                : runnableCount === 0
                     ? "missing"
                     : "partial",
         languages
@@ -149,7 +149,7 @@ function languageState(pluginReady, serverFound, serverRunnable, probeCompleted)
     if (!probeCompleted) {
         return "server_unverified";
     }
-    return serverRunnable ? "ready" : "server_failed";
+    return serverRunnable ? "server_runnable" : "server_failed";
 }
 function languageError(state, command, probeResult) {
     if (state === "plugin_missing") {

package/dist/backend/services/harness-service.js

@@ -53,6 +53,7 @@ const VCM_BASH_DEFAULT_TIMEOUT_MS = "600000";
 const VCM_AUTO_MEMORY_ENABLED = false;
 const VCM_HOOK_DEFINITIONS = [
     { eventName: "PreToolUse", matcher: "Bash", command: VCM_BASH_GUARD_HOOK_COMMAND, timeout: 10 },
+    { eventName: "PreToolUse", matcher: "Grep", command: VCM_BASH_GUARD_HOOK_COMMAND, timeout: 10 },
     { eventName: "UserPromptSubmit", command: VCM_HOOK_COMMAND, timeout: 5 },
     { eventName: "Stop", command: VCM_STOP_HOOK_COMMAND, timeout: 10 },
     { eventName: "StopFailure", command: VCM_HOOK_COMMAND, timeout: 5 },
@@ -116,7 +117,7 @@ const HARNESS_FILES = [
         kind: "skill-vcm-code-navigation",
         path: ".claude/skills/vcm-code-navigation/SKILL.md",
         title: "VCM Code Navigation Skill",
-        frontmatter: renderSkillFrontmatter("vcm-code-navigation", "Use when Architect or Reviewer must resolve code symbols, references, implementations, call hierarchies, or bounded dependency paths."),
+        frontmatter: renderSkillFrontmatter("vcm-code-navigation", "Use when Architect, Coder, or Reviewer must resolve code symbols, references, implementations, call hierarchies, or bounded dependency paths."),
         ownership: "whole-file",
         renderRules: renderVcmCodeNavigationSkillRules
     },
@@ -198,7 +199,9 @@ const HARNESS_FILES = [
         title: "Reviewer Agent",
         memoryBlock: true,
         requiredTools: ["LSP"],
-        frontmatter: renderAgentFrontmatter("reviewer", "VCM independent gate review role for architecture plans, validation adequacy, and code diffs.", { tools: "Read, Grep, Glob, Bash, Write, LSP" }),
+        forbiddenTools: ["Grep"],
+        requiredSkills: ["vcm-code-navigation"],
+        frontmatter: renderAgentFrontmatter("reviewer", "VCM independent gate review role for architecture plans, validation adequacy, and code diffs.", { tools: "Read, Glob, Bash, Write, LSP", skills: ["vcm-code-navigation"] }),
         renderRules: renderReviewerAgentRules
     },
     {
@@ -272,8 +275,10 @@ const HARNESS_FILES = [
         title: "Architect Agent",
         memoryBlock: true,
         requiredTools: ["Agent", "LSP"],
+        forbiddenTools: ["Grep"],
+        requiredSkills: ["vcm-code-navigation"],
         blankLineBeforeEnd: true,
-        frontmatter: renderAgentFrontmatter("architect", "VCM architecture role for plans, module boundaries, public contracts, verifiable behavior, and docs sync.", { tools: "Read, Grep, Glob, Bash, Edit, Write, Agent, LSP" }),
+        frontmatter: renderAgentFrontmatter("architect", "VCM architecture role for plans, module boundaries, public contracts, verifiable behavior, and docs sync.", { tools: "Read, Glob, Bash, Edit, Write, Agent, LSP", skills: ["vcm-code-navigation"] }),
         renderRules: renderArchitectHarnessRules
     },
     {
@@ -282,7 +287,9 @@ const HARNESS_FILES = [
         title: "Coder Agent",
         memoryBlock: true,
         requiredTools: ["Agent", "LSP"],
-        frontmatter: renderAgentFrontmatter("coder", "VCM implementation role for scoped code changes and focused tests.", { tools: "Read, Grep, Glob, Bash, Edit, Write, Agent, LSP" }),
+        forbiddenTools: ["Grep"],
+        requiredSkills: ["vcm-code-navigation"],
+        frontmatter: renderAgentFrontmatter("coder", "VCM implementation role for scoped code changes and focused tests.", { tools: "Read, Glob, Bash, Edit, Write, Agent, LSP", skills: ["vcm-code-navigation"] }),
         renderRules: renderCoderHarnessRules
     },
     {
@@ -1220,7 +1227,7 @@ async function analyzeHarnessFile(fs, repoRoot, definition) {
         const migratedContent = migrateLegacyHarnessFile(definition, currentContent, expectedBlock);
         if (migratedContent) {
             const memoryUpdatedContent = definition.memoryBlock ? ensureVcmMemoryBlock(migratedContent) : migratedContent;
-            const nextContent = ensureAgentTools(memoryUpdatedContent, definition.requiredTools);
+            const nextContent = normalizeAgentFrontmatter(memoryUpdatedContent, definition);
             return {
                 definition,
                 status: {
@@ -1239,7 +1246,7 @@ async function analyzeHarnessFile(fs, repoRoot, definition) {
             };
         }
         const insertedContent = `${currentContent.trimEnd()}\n\n${expectedBlock}\n`;
-        const nextContent = ensureAgentTools(insertedContent, definition.requiredTools);
+        const nextContent = normalizeAgentFrontmatter(insertedContent, definition);
         return {
             definition,
             status: {
@@ -1261,7 +1268,7 @@ async function analyzeHarnessFile(fs, repoRoot, definition) {
     const currentBlock = match[0];
     const blockUpdatedContent = currentContent.replace(managedBlockPattern, expectedBlock);
     const memoryUpdatedContent = definition.memoryBlock ? ensureVcmMemoryBlock(blockUpdatedContent) : blockUpdatedContent;
-    const nextContent = ensureAgentTools(memoryUpdatedContent, definition.requiredTools);
+    const nextContent = normalizeAgentFrontmatter(memoryUpdatedContent, definition);
     const action = currentContent === nextContent ? "ok" : "update";
     return {
         definition,
@@ -1392,6 +1399,50 @@ function ensureAgentTool(content, requiredTool) {
 function ensureAgentTools(content, requiredTools) {
     return (requiredTools ?? []).reduce(ensureAgentTool, content);
 }
+function removeAgentTool(content, forbiddenTool) {
+    const frontmatterMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
+    if (!frontmatterMatch) {
+        return content;
+    }
+    const toolsMatch = frontmatterMatch[0].match(/^tools:\s*(.*)$/m);
+    if (!toolsMatch) {
+        return content;
+    }
+    const tools = toolsMatch[1].split(",").map((tool) => tool.trim()).filter(Boolean);
+    const nextTools = tools.filter((tool) => tool !== forbiddenTool);
+    if (nextTools.length === tools.length) {
+        return content;
+    }
+    return content.replace(frontmatterMatch[0], frontmatterMatch[0].replace(toolsMatch[0], `tools: ${nextTools.join(", ")}`));
+}
+function normalizeAgentTools(content, requiredTools, forbiddenTools) {
+    const required = ensureAgentTools(content, requiredTools);
+    return (forbiddenTools ?? []).reduce(removeAgentTool, required);
+}
+function normalizeAgentFrontmatter(content, definition) {
+    const toolsUpdated = normalizeAgentTools(content, definition.requiredTools, definition.forbiddenTools);
+    return (definition.requiredSkills ?? []).reduce(ensureAgentSkill, toolsUpdated);
+}
+function ensureAgentSkill(content, requiredSkill) {
+    const frontmatterMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
+    if (!frontmatterMatch) {
+        return content;
+    }
+    const frontmatter = frontmatterMatch[0];
+    const skillsMatch = frontmatter.match(/^skills:[ \t]*(?:\r?\n((?:\s+-\s+[^\r\n]+\r?\n?)*))?/m);
+    if (!skillsMatch) {
+        return content.replace(frontmatter, frontmatter.replace(/\r?\n---$/, `\nskills:\n  - ${requiredSkill}\n---`));
+    }
+    const listedSkills = (skillsMatch[1] ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.match(/^\s+-\s+(.+)$/)?.[1]?.trim())
+        .filter((skill) => Boolean(skill));
+    if (listedSkills.includes(requiredSkill)) {
+        return content;
+    }
+    const nextSkills = `${skillsMatch[0].trimEnd()}\n  - ${requiredSkill}`;
+    return content.replace(frontmatter, frontmatter.replace(skillsMatch[0], nextSkills));
+}
 function migrateLegacyHarnessFile(definition, currentContent, block) {
     const legacyContent = definition.legacyWholeFile?.trimEnd();
     if (!legacyContent) {
@@ -1479,7 +1530,7 @@ function withVcmClaudeHooks(settings) {
             ? hooks[definition.eventName]
             : [];
         hooks[definition.eventName] = [
-            ...existingMatchers.filter((entry) => !isVcmHookMatcher(entry)),
+            ...existingMatchers,
             {
                 ...(definition.matcher ? { matcher: definition.matcher } : {}),
                 hooks: [
@@ -1524,7 +1575,10 @@ function renderAgentFrontmatter(name, description, options = {}) {
     const tools = options.tools ?? "Read, Grep, Glob, Bash, Edit, Write";
     const model = options.model ? `\nmodel: ${options.model}` : "";
     const effort = options.effort ? `\neffort: ${options.effort}` : "";
-    return `---\nname: ${name}\ndescription: ${description}\ntools: ${tools}${model}${effort}\n---`;
+    const skills = options.skills?.length
+        ? `\nskills:\n${options.skills.map((skill) => `  - ${skill}`).join("\n")}`
+        : "";
+    return `---\nname: ${name}\ndescription: ${description}\ntools: ${tools}${model}${effort}${skills}\n---`;
 }
 function renderSkillFrontmatter(name, description) {
     return `---\nname: ${name}\ndescription: ${description}\n---`;

package/dist/backend/templates/harness/architect-agent.js

@@ -19,6 +19,13 @@ ${renderRoleMemoryRules("architect")}
 - In Debug Mode and Architecture Diagnosis Mode, writing baseline unit tests for changed code and running required L0/L1 plus applicable L2/L3 checks are part of the implementation duty; tester still owns final validation.
 - Do not make product priority or approval decisions; route those questions back to project-manager.
 
+### Semantic Code Navigation
+
+- Follow the preloaded \`vcm-code-navigation\` skill whenever work requires code definitions, implementations, references, callers, callees, or behavior paths. This applies in every Architect mode and in direct user communication.
+- Use LSP for semantic relationships. Use Glob to locate files, Read to inspect complete code, and generated context, architecture documents, or runtime evidence for boundaries LSP does not model.
+- Do not use the Grep tool or shell text-search commands such as \`grep\`, \`rg\`, or \`git grep\`.
+- If LSP cannot resolve a required project-owned relationship, record it as unresolved. Do not replace semantic evidence with text matches.
+
 ### Work Persistence
 
 - Treat Architect artifacts, not Session memory, as continuation state.
@@ -45,9 +52,8 @@ ${renderRoleMemoryRules("architect")}
 ### Planning Code Reading
 
 - Do not plan from session memory, architecture docs, generated context, or code comments alone. Re-read current-worktree source and verify actual behavior from implementation.
-- Use \`vcm-code-navigation\` for symbol definitions, implementations, references, call hierarchies, and bounded behavior paths. Start from generated indexes, use LSP semantic navigation when available, then read every resolved callable unit in full.
-- Use structural search when available and Grep for dynamic registrations, configuration or string edges, macros not resolved by LSP, documentation, and explicit fallback discovery. When LSP is available, do not treat Grep as proof of a complete symbol, caller, implementation, or reference set.
-- If LSP is unavailable or cannot resolve a required relationship, record the limitation and exact fallback evidence in \`architecture-evidence.md\`; do not claim compiler-accurate completeness from text search alone.
+- Use \`vcm-code-navigation\` for symbol definitions, implementations, references, call hierarchies, and bounded behavior paths. Start from generated indexes, use LSP semantic navigation, then read every resolved callable unit in full.
+- If LSP cannot resolve a required project-owned relationship, record the limitation in \`architecture-evidence.md\` and leave it unresolved.
 - Define the planning boundary as the affected feature or module and identify every existing or intended observable entry point for the behavior being changed.
 - Read the complete implementation of each relevant existing entry point.
 - Follow every project-owned call path the plan will change through cross-module calls, state reads and writes, persistence, side effects, completion and failure signals, and consumers.
@@ -202,7 +208,7 @@ The code-reading phase is complete only when:
 - every indirect callback, event, hook, queue, route, and dynamic dispatch path has been resolved
 - every relevant state reader and writer has been read
 - every relevant cross-file surface caller and consumer has been read
-- every semantic relationship records LSP, structural-search, Grep-fallback, runtime, external-boundary, or generated-boundary evidence
+- every semantic relationship records LSP, runtime, external-boundary, or generated-boundary evidence
 - no unresolved project-owned symbol remains
 
 Do not diagnose the root cause or choose a fix before the Code Reading Closure is complete.

package/dist/backend/templates/harness/coder-agent.js

@@ -12,6 +12,13 @@ ${renderRoleMemoryRules("coder")}
 - Implement assigned file/function-level scaffold items; do not analyze, review, dispute, or redesign architecture, module boundaries, public contracts, dependency direction, durable docs strategy, validation strategy, or final test adequacy.
 - Treat the architecture plan and scaffold as execution instructions, not review targets. Do not critique, reinterpret, or challenge them during Coder work.
 
+### Semantic Code Navigation
+
+- Follow the preloaded \`vcm-code-navigation\` skill whenever implementation requires code definitions, implementations, references, callers, callees, or behavior paths.
+- Use LSP for semantic relationships. Use Glob to locate files and Read to inspect complete code.
+- Do not use the Grep tool or shell text-search commands such as \`grep\`, \`rg\`, or \`git grep\`.
+- If LSP cannot resolve a required project-owned relationship, record it as unresolved in the completion evidence. Do not replace semantic evidence with text matches.
+
 ### Shared Coding Standards
 
 - Before editing production code or tests, read and follow \`docs/CODING_STANDARDS.md\`.
@@ -26,7 +33,7 @@ ${renderRoleMemoryRules("coder")}
 - Do not stop before editing because of predicted architecture, design, contract, validation, or test failure; implement the assigned scaffold first.
 - Use \`.ai/generated/module-index.json\` to locate approved module source and test files.
 - Use \`.ai/generated/public-surface.json\` to avoid accidental public API drift.
-- When LSP is available, use definitions and references to locate assigned callable surfaces precisely. Use Grep for text or dynamic edges, not to broaden or reinterpret the approved implementation scope.
+- Use LSP definitions and references to locate assigned callable surfaces precisely.
 
 ### Implementation
 

package/dist/backend/templates/harness/gate-review.js

@@ -15,20 +15,23 @@ Use only these decisions:
 - \`approve\`: required gate evidence is present, current, internally consistent, sufficient for that gate, and has no gate-blocking finding.
 - \`request_changes\`: evidence is missing, stale, contradictory, incomplete, insufficient, not reviewable, or unsafe.
 
+## Semantic Code Navigation
+
+Follow the preloaded \`vcm-code-navigation\` skill whenever a gate requires code definitions,
+implementations, references, callers, callees, or behavior paths. Use LSP for
+semantic relationships, Glob to locate files, Read to inspect complete code,
+and generated context, architecture documents, or runtime evidence for
+boundaries LSP does not model. Do not use the Grep tool or shell text-search
+commands such as \`grep\`, \`rg\`, or \`git grep\`. If LSP cannot resolve
+a required project-owned relationship, treat that evidence as unresolved and
+return \`request_changes\`; do not replace semantic evidence with text matches.
+
 Every Gate Review is a complete review of the current gate inputs. Review all
 required evidence and rerun every required mechanical check before deciding.
 Do not carry forward prior conclusions, closed checks, or partial verification.
 Resolving prior findings does not replace the complete review. Return \`approve\`
 or \`request_changes\` only after the review is complete.
 
-Use \`vcm-code-navigation\` whenever a gate requires definitions, implementations,
-references, call hierarchies, or a bounded behavior path. Use LSP semantic
-navigation when available and read every resolved callable unit in full. Use
-structural search when available and Grep for dynamic or textual edges and
-explicit fallback discovery. Do not treat Grep as proof of a complete symbol,
-caller, implementation, or reference set when LSP is available. If LSP cannot
-resolve required evidence, record the limitation and exact fallback basis.
-
 ## Architecture Plan Gate
 
 Format is necessary but not sufficient. Do not approve an architecture plan
@@ -469,7 +472,7 @@ If there are no findings, write:
 None.
 \`\`\`
 
-Use Bash only for read-only inspection such as \`git diff\`, \`git status\`, \`git show\`, \`ls\`, \`rg\`, \`sed\`, or \`cat\`. Do not run tests, builds, formatters, generators, package managers, or commands that modify files.
+Use Bash only for read-only inspection such as \`git diff\`, \`git status\`, \`git show\`, \`ls\`, \`sed\`, or \`cat\`. Do not run shell text-search commands, tests, builds, formatters, generators, package managers, or commands that modify files.
 
 Review only code, architecture, and documents; do not perform validation. Do not edit code, tests, durable docs, role files, route files, or handoff artifacts. Do not assign findings or remediation work to VCM roles, choose fixes, decide Replan, or decide whether user intervention is needed.
 

package/dist/backend/templates/harness/vcm-code-navigation-skill.js

@@ -1,22 +1,24 @@
 export function renderVcmCodeNavigationSkillRules() {
     return `## Purpose
 
-Use this skill when Architect or Reviewer must establish symbol definitions, implementations, references, callers, callees, or a bounded behavior path from current-worktree evidence.
+Use this skill when Architect, Coder, or Reviewer must establish symbol definitions, implementations, references, callers, callees, or a bounded behavior path from current-worktree evidence.
 
 ## Navigation Order
 
 1. Define the affected feature or module boundary and locate entry symbols with \`.ai/generated/module-index.json\` and \`.ai/generated/public-surface.json\` when available.
-2. When LSP is available, use workspace or file symbols, definitions, implementations, references, and incoming or outgoing call hierarchy to resolve project-owned relationships.
-3. Read the complete project-owned callable unit at every resolved location.
-4. Expand one project-owned dependency hop at a time until the required behavior path has no unresolved symbol.
-5. Use structural search when available, and use Grep for dynamic registrations, configuration or string edges, macros not resolved by LSP, documentation, and explicit fallback discovery.
+2. Start each navigation run with LSP \`documentSymbol\` on a known affected project source file. This initializes the actual role-session language server and proves that it can parse that file; an executable version probe is not workspace readiness.
+3. Use LSP workspace or file symbols, definitions, implementations, references, and incoming or outgoing call hierarchy to resolve project-owned relationships.
+4. If an initial workspace-symbol request is empty or reports indexing, do not conclude that the symbol is absent. After a successful file-symbol request, retry the same bounded workspace query at most two more times. If it still cannot resolve, record the operation and result as unresolved.
+5. Read the complete project-owned callable unit at every resolved location.
+6. Expand one project-owned dependency hop at a time until the required behavior path has no unresolved symbol.
+7. Use Glob, generated context, architecture documents, and runtime evidence to locate dynamic registrations, configuration or string edges, macros, documentation, and external boundaries that LSP does not model.
 
 ## Evidence
 
-- Record each resolved relationship and whether it came from LSP, structural search, Grep fallback, runtime evidence, or a generated boundary.
-- Do not treat a Grep result as proof of a complete definition, caller, implementation, or reference set when LSP is available.
+- Record each resolved relationship and whether it came from LSP, runtime evidence, an external boundary, or a generated boundary.
 - When an empty LSP result contradicts a direct call in the code, another LSP result, or runtime evidence, treat the relationship as unresolved. Record the contradiction and use exact fallback evidence.
-- If LSP is unavailable or cannot resolve a relationship, record that limitation and the exact fallback evidence. Do not describe text-search results as compiler-accurate or complete.
+- If LSP is unavailable or cannot resolve a required project-owned relationship, record that limitation and leave the relationship unresolved. Do not substitute text search for semantic navigation.
+- Do not use the Grep tool or shell text-search commands such as \`grep\`, \`rg\`, or \`git grep\`.
 - Generated indexes and architecture docs locate likely code; reading current-worktree implementation establishes behavior.
 
 ## Context Boundary