feat(search): milestones are searchable by meaning — "is there already a plan for this?" (#4078)

`search` covered notes, tasks and rules, and a milestone — the record a plan
lives in — could not be found. A project whose roadmap was written as
milestones had every later plan opened beside the one that already described
it, because nothing could have told the session it existed.

- milestone_embeddings (migration 0102): the third sibling of note_ and
  rule_embeddings, for note 3163's reason — the search is milestone-specific.
  The document is title — description, then description and the plan body,
  so a roadmap milestone with no description is still found by its design.
- Written on create, on a title/description/body update, and for a plan made
  through start_planning / create_records, fire-and-forget with the parent-row
  claim (#3262); a startup backfill covers every existing milestone. Derived,
  so it joins _NOT_INCLUDED beside the other embeddings.
- semantic_search_milestones: a project's milestones when the caller can read
  it (access.can_read_project), otherwise the caller's own; optional status.
- search(content_type="milestone"): id, title, description, status, project
  and progress. Its own shape, and not part of "all", whose results are
  note-shaped. The docstring says what it is for: ask before start_planning.
- Integration test on real Postgres: found in its project and not another,
  status narrows, an unreadable project returns nothing.

Milestone 415 step 3.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

tests/conftest.py

@@ -80,7 +80,10 @@ def _no_embedding():
     """
     from unittest.mock import MagicMock
 
-    with patch("scribe.services.notes.embed_note", MagicMock()):
+    # Milestones embed too since milestone 415; a plan created in a test would
+    # otherwise detach the same model-loading task.
+    with patch("scribe.services.notes.embed_note", MagicMock()), \
+         patch("scribe.services.milestones.embed_milestone", MagicMock()):
         yield
 
 

tests/test_integration_milestone_search.py

@@ -0,0 +1,82 @@
+"""Real-Postgres tests for finding a plan by meaning (milestone 415, step 3).
+
+A project's roadmap written as milestones was invisible to recall: `search`
+covered notes, tasks and rules, so "is there already a plan for this?" had no
+tool. What a mock cannot show is the join scoping the vectors to a project and
+to what the caller may read, so these seed real milestones with hand-made
+vectors and stub only the embedder.
+"""
+import uuid
+from unittest.mock import AsyncMock, patch
+
+import pytest
+import pytest_asyncio
+
+from scribe.models import async_session
+from scribe.models.embedding import EMBEDDING_DIM, MilestoneEmbedding
+from scribe.models.milestone import Milestone
+from scribe.models.project import Project
+from scribe.services.embeddings import CHUNKER_VERSION, semantic_search_milestones
+from tests.helpers import ensure_user
+
+pytestmark = [pytest.mark.integration, pytest.mark.usefixtures("_dispose_engine", "_no_embedding")]
+
+NEAR = [1.0] + [0.0] * (EMBEDDING_DIM - 1)
+FAR = [0.0, 1.0] + [0.0] * (EMBEDDING_DIM - 2)
+
+
+@pytest_asyncio.fixture
+async def roadmap():
+    tag = uuid.uuid4().hex[:8]
+    async with async_session() as s:
+        owner = await ensure_user(s, f"ms_search_owner_{tag}")
+        stranger = await ensure_user(s, f"ms_search_stranger_{tag}")
+        mine = Project(user_id=owner.id, title="Librarian")
+        other = Project(user_id=owner.id, title="Elsewhere")
+        s.add_all([mine, other])
+        await s.flush()
+        m3 = Milestone(user_id=owner.id, project_id=mine.id, title="M3 — Metadata",
+                       description="works, editions, providers, provenance", status="active")
+        done = Milestone(user_id=owner.id, project_id=mine.id, title="Covers",
+                         description="cover art", status="done")
+        unrelated = Milestone(user_id=owner.id, project_id=mine.id, title="Android client",
+                              description="native app", status="active")
+        foreign = Milestone(user_id=owner.id, project_id=other.id, title="Metadata elsewhere",
+                            description="same words, other project", status="active")
+        s.add_all([m3, done, unrelated, foreign])
+        await s.flush()
+        for ms, vec in ((m3, NEAR), (done, NEAR), (unrelated, FAR), (foreign, NEAR)):
+            s.add(MilestoneEmbedding(milestone_id=ms.id, chunk_index=0, embedding=vec,
+                                     chunk_text=ms.title, chunker_version=CHUNKER_VERSION))
+        ids = {"owner": owner.id, "stranger": stranger.id, "mine": mine.id,
+               "m3": m3.id, "done": done.id, "unrelated": unrelated.id, "foreign": foreign.id}
+        await s.commit()
+    return ids
+
+
+async def _found(user_id, **kw) -> list[int]:
+    with patch("scribe.services.embeddings.get_embedding", AsyncMock(return_value=NEAR)):
+        hits = await semantic_search_milestones(user_id, "book metadata and providers",
+                                                threshold=0.5, limit=10, **kw)
+    return [m.id for _s, m in hits]
+
+
+async def test_a_plan_is_found_in_its_project_and_not_in_another(roadmap):
+    found = await _found(roadmap["owner"], project_id=roadmap["mine"])
+    assert set(found) == {roadmap["m3"], roadmap["done"]}
+    assert roadmap["foreign"] not in found and roadmap["unrelated"] not in found
+
+
+async def test_status_narrows_to_open_plans(roadmap):
+    found = await _found(roadmap["owner"], project_id=roadmap["mine"], status="active")
+    assert found == [roadmap["m3"]]
+
+
+async def test_without_a_project_it_searches_the_callers_own(roadmap):
+    found = await _found(roadmap["owner"])
+    assert {roadmap["m3"], roadmap["done"], roadmap["foreign"]} <= set(found)
+
+
+async def test_a_project_the_caller_cannot_read_returns_nothing(roadmap):
+    assert await _found(roadmap["stranger"], project_id=roadmap["mine"]) == []
+    assert await _found(roadmap["stranger"]) == []

tests/test_mcp_tool_search.py

@@ -106,3 +106,34 @@ async def test_rule_search_scopes_to_the_project_it_is_given(project_id, scope):
     kwargs = found.await_args.kwargs
     assert {k: kwargs[k] for k in scope} == scope
     assert set(kwargs) & {"project_id", "everywhere"} == set(scope)
+
+
+def test_a_milestone_is_embedded_by_what_it_is_for_then_its_plan():
+    from scribe.services.embeddings import milestone_document
+
+    assert milestone_document("M3", "metadata providers", "## Goal\nx") == (
+        "M3 — metadata providers", "metadata providers\n\n## Goal\nx")
+    # A roadmap milestone written with no description is still findable by its plan.
+    assert milestone_document("M3", None, "the plan") == ("M3", "the plan")
+    assert milestone_document(None, None, None) == (None, None)
+
+
+@pytest.mark.asyncio
+async def test_milestone_search_is_its_own_shape_and_scopes_to_the_project():
+    """milestone 415: 'is there already a plan for this?' has a tool."""
+    from unittest.mock import MagicMock
+
+    _user_id_ctx.set(7)
+    ms = MagicMock(id=339, title="M3 — Metadata", description="works, editions",
+                   status="active", project_id=30)
+    found = AsyncMock(return_value=[(0.81, ms)])
+    summary = AsyncMock(return_value=[{"id": 339, "total": 0, "completed": 0}])
+    with patch("scribe.mcp.tools.search.semantic_search_milestones", found), \
+         patch("scribe.services.milestones.get_project_milestone_summary", summary):
+        out = await search(q="book metadata", content_type="milestone", project_id=30)
+    assert found.await_args.kwargs["project_id"] == 30
+    assert out["results"] == [{
+        "id": 339, "title": "M3 — Metadata", "description": "works, editions",
+        "status": "active", "project_id": 30, "total": 0, "completed": 0,
+        "similarity": 0.81,
+    }]