fix(mcp): point move mismatch guidance at landing path

[phernandez]

Summary

• Update MOVE_OUTCOME_MISMATCH recovery guidance to read and delete the actual result.file_path after a divergent move result.
• Add a bughunt integration regression that exercises the text-mode MCP path and asserts the stale source identifier is not suggested.

The real move service currently stores the requested destination verbatim, so the regression lets the real move happen and then injects a divergent returned file_path at the MCP client boundary. That matches the defensive backstop this guidance belongs to.

Testing

• Red: uv run pytest test-int/bughunt_fixes/test_move_note_edge_cases.py::test_move_outcome_mismatch_guidance_uses_actual_landing_path -q --no-cov failed before the fix on stale read_note guidance.
• Green: uv run pytest test-int/bughunt_fixes/test_move_note_edge_cases.py::test_move_outcome_mismatch_guidance_uses_actual_landing_path -q --no-cov
• uv run pytest test-int/bughunt_fixes/test_move_note_edge_cases.py -q --no-cov
• uv run pytest tests/mcp/test_tool_move_note.py -q --no-cov
• just fast-check — 3217 passed, 41 skipped, 117 warnings

Follow-up to #904.

[github-actions]

Claude finished @phernandez's task in 1m 17s —— View job

---

PR Review: fix(mcp): point move mismatch guidance at landing path

• Load tools
• Read changed files and gather context
• Review against team checklist
• Post final review

---

Summary

This is a small, focused, correct fix. When move_note detects that the file landed at a different path than requested (MOVE_OUTCOME_MISMATCH), the guidance text previously pointed agents back at the stale source identifier. After the fix it correctly references result.file_path — the actual post-move location.

Both changed lines are correct:

• read_note("{result.file_path}") — agents need to read from where the file actually ended up
• delete_note("{result.file_path}", project="{active_project.name}") — same for deletion

---

Team Checklist

Code Quality & Standards

• Follows Basic Memory's coding conventions — clean dedent(f"""...""") template, consistent with surrounding code
• Python 3.12+ type annotations and async patterns — no new functions, existing patterns preserved
• 100-character line length limit maintained
• No commented-out code blocks

Testing & Documentation

• Integration test added in test-int/bughunt_fixes/ — exercises the text-mode MCP path end-to-end
• Regression test correctly uses monkeypatch to inject divergent file_path at the client boundary without breaking the real move service
• Both positive assertions (actual path appears) and negative assertions (stale identifier absent) present
• PR body documents red/green test run — just fast-check passes (3217 tests)
• Unit tests in tests/mcp/test_tool_move_note.py explicitly verified per PR description

Basic Memory Architecture

• MCP tool remains atomic and composable — no new control flow added
• Knowledge graph consistency preserved — fix only affects the error guidance text

Security & Performance

• No security concerns — guidance text change only
• result.file_path used elsewhere in the same block already (in the **Actual:** line), so no new surface

Compatibility

• PureWindowsPath normalization already applied to result.file_path for the mismatch comparison at lines 914–915; the guidance text uses the raw value, consistent with how **Actual:** \{result.file_path}`` was already rendered above it

---

One Minor Observation

The test omits output_format from the move_note call (defaults to "text"), which is intentional — it exercises exactly the text-mode guidance path being fixed. The output_format: "json" path for MOVE_OUTCOME_MISMATCH already returns result.file_path in the structured response (lines 921–930), so it was never broken. The test correctly targets only the broken path.

No issues found. The fix is minimal, the test is well-scoped, and the PR description is accurate.

---