`Path Resolver v2: branch-aware context key, explicit resolution metadata, invalidation policy, AI feedback loop`

[doITmagic]

Problem

Current path resolution for RagCode tools creates friction and stale-context errors in real IDE usage:

• Requiring file_path on every call is repetitive and error-prone.
• last_valid_file_path is not branch-aware, causing wrong reuse after Git branch switches.
• Resolver decisions are opaque (AI cannot see why a path was selected).
• Cache invalidation is weak, leading to stale entries and retry loops.
• No explicit mechanism for AI to reject a resolved path and suggest correction.

This is especially problematic when users work across multiple branches/worktrees in the same repository.

---

Proposal

Implement a Path Resolver v2 with 5 components:

1. Branch-aware context key

   • Replace global workspace-only key with:
     • workspace_root + git_branch + git_head (+ worktree_id)
   • Keep temporary backward-compatible fallback to old key during rollout.

2. Explicit path-resolution metadata in every tool response

   • Add:
     • resolved_file_path
     • path_resolution_source
     • path_resolution_confidence
     • used_fallback
     • workspace_root
     • git_branch
     • git_head
     • worktree_id (if available)
     • path_context_key

3. Invalidation and anti-loop policy

   • Invalidate or isolate cache on branch switch.
   • Confidence decay on HEAD mismatch/rewrite.
   • Short TTL for fallback cache entries.
   • Prevent infinite retries on missing paths.

4. AI ↔ resolver feedback loop

   • Support request-side feedback:
     • path_feedback.status = "mismatch"
     • path_feedback.suggested_file_path
     • optional reason
   • Store suggestion as candidate; promote to last_valid only after successful resolution/execution.

5. Branch mismatch risk signal

   • Return branch_mismatch_risk: low|medium|high
   • Raise risk when path likely comes from stale/other-branch context.

---

Example response metadata (proposed)

{
  "resolved_file_path": "/abs/path/internal/config/loader.go",
  "path_resolution_source": "last_valid_file_path",
  "path_resolution_confidence": 0.86,
  "used_fallback": true,
  "workspace_root": "/home/.../go/src/github.com/doITmagic/rag-code-mcp",
  "git_branch": "feature/path-resolver-v2",
  "git_head": "a1b2c3d",
  "worktree_id": "main-worktree",
  "path_context_key": "workspace+branch+head+worktree",
  "branch_mismatch_risk": "low"
}

---

Scope

• Path resolver internals
• RagCode tool response envelope metadata
• Cache keying + invalidation behavior
• Feedback input handling

Non-goals

• Full redesign of all search tools
• UI command palette implementation (can be separate issue)
• Cross-repo context sharing

---

Acceptance Criteria

• Context key includes branch/head (and worktree when available).
• No cache collisions across branches/worktrees in tests.
• Metadata fields are present in all relevant tool responses.
• Resolver avoids infinite retry behavior on missing files.
• mismatch feedback is accepted and influences next resolution.
• Suggested paths are promoted only after successful execution.
• branch_mismatch_risk is computed and returned.
• In IDE sessions, >=80% successful calls without explicit file_path when context is inferable.

---

Suggested implementation order

1. Context key v2
2. Response metadata
3. Invalidation policy
4. Feedback loop
5. Risk flag + hardening tests