feat(planning): start_planning hands back the active plan that already covers the work (#4079)

Step 4 of milestone 415 "An existing plan is found before a new one is made".
A session that could not see an existing plan made a second one beside it.
start_planning and create_milestone now ask first: an ACTIVE milestone in the
project with the same title, or one that reads as the same plan (title, design
and steps against milestone embeddings), is returned with its progress and a
pointer to create_records(milestone_id=...). Nothing is created; force=true
bypasses.

- dedup.find_matching_plan / plan_gate / plan_match_response; access-checked
  before either arm (rule 78), fail-open like the other gates.
- Done milestones never block; the semantic arm needs 200+ chars of candidate.
- kb_plan_match_threshold (default 0.90) is a setting, in the Settings view,
  and pinned against the Python default by test_settings_defaults_agree.

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

tests/test_integration_milestone_search.py

@@ -1,4 +1,4 @@
-"""Real-Postgres tests for finding a plan by meaning (milestone 415, step 3).
+"""Real-Postgres tests for finding a plan by meaning (milestone 415, steps 3 and 4).
 
 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
@@ -16,6 +16,7 @@ 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 import dedup as dedup_svc
 from scribe.services.embeddings import CHUNKER_VERSION, semantic_search_milestones
 from tests.helpers import ensure_user
 
@@ -80,3 +81,46 @@ async def test_without_a_project_it_searches_the_callers_own(roadmap):
 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"]) == []
+
+
+# ── the plan gate (step 4): start_planning finds the plan before making another ──
+
+LONG = "Resolve works and editions against the metadata providers. " * 5
+
+
+async def _gate(roadmap, title, text="", project=None):
+    with patch("scribe.services.embeddings.get_embedding", AsyncMock(return_value=NEAR)):
+        return await dedup_svc.plan_gate(
+            roadmap["owner"], project or roadmap["mine"], title, text,
+        )
+
+
+async def test_the_gate_returns_an_active_plan_with_the_same_title(roadmap):
+    out = await _gate(roadmap, "  m3 — METADATA ")
+    assert out["duplicate"] is True and out["match"] == "title"
+    assert out["existing_milestone"]["id"] == roadmap["m3"]
+    assert f"create_records(milestone_id={roadmap['m3']}" in out["message"]
+
+
+async def test_the_gate_finds_a_plan_by_meaning_and_never_a_done_one(roadmap):
+    """NEAR matches m3 (active), `done` (done) and `foreign` (another project).
+    Only m3 is a plan this project is still working through."""
+    out = await _gate(roadmap, "Book metadata", LONG)
+    assert out["match"] == "semantic"
+    assert out["existing_id"] == roadmap["m3"]
+
+
+async def test_a_done_plan_and_another_projects_plan_do_not_block(roadmap):
+    assert await _gate(roadmap, "Covers") is None
+    assert await _gate(roadmap, "Metadata elsewhere") is None
+    async with async_session() as s:
+        m3 = await s.get(Milestone, roadmap["m3"])
+        m3.status = "done"
+        await s.commit()
+    assert await _gate(roadmap, "Book metadata", LONG) is None
+
+
+async def test_a_short_candidate_is_judged_by_title_alone(roadmap):
+    """A title-only embedding sits in a tight neighbourhood and matches
+    anything nearby, so a bare title never takes the semantic arm."""
+    assert await _gate(roadmap, "Book metadata", "just a title") is None

tests/test_mcp_tool_create_records.py

@@ -120,6 +120,7 @@ async def test_start_planning_hands_its_steps_to_the_service():
     from scribe.mcp.tools.tasks import start_planning
 
     with patch("scribe.mcp.tools.tasks.dedup_svc.find_duplicate_note", AsyncMock(return_value=None)), \
+         patch("scribe.mcp.tools.tasks.dedup_svc.plan_gate", AsyncMock(return_value=None)), \
          patch("scribe.mcp.tools.tasks.planning_svc.start_planning",
                AsyncMock(return_value={"milestone": {"id": 1}})) as svc:
         await start_planning(project_id=3, title="Plan", body="see {{ref:1}}",

tests/test_mcp_tool_milestones.py

@@ -12,6 +12,15 @@ from tests.helpers import fake_milestone
 pytestmark = pytest.mark.usefixtures("_bind_user")
 
 
+@pytest.fixture(autouse=True)
+def _no_plan_gate():
+    """The plan gate reads the database; these tests are about what reaches
+    the service. The gate's own tests re-patch it."""
+    with patch("scribe.mcp.tools.milestones.dedup_svc.plan_gate",
+               AsyncMock(return_value=None)):
+        yield
+
+
 @pytest.mark.asyncio
 async def test_list_milestones_returns_dict_with_progress():
     rows = [{"id": 1, "title": "MS1", "status": "active", "total": 2}]
@@ -63,6 +72,33 @@ async def test_create_milestone_empty_body_becomes_none():
     assert mock.call_args.kwargs["body"] is None
 
 
+@pytest.mark.asyncio
+async def test_create_milestone_returns_the_active_plan_that_already_covers_it():
+    match = {"duplicate": True, "existing_id": 4}
+    create = AsyncMock()
+    with patch("scribe.mcp.tools.milestones.dedup_svc.plan_gate",
+               AsyncMock(return_value=match)) as gate, \
+         patch("scribe.mcp.tools.milestones.milestones_svc.create_milestone", create):
+        out = await create_milestone(project_id=1, title="t", description="d", body="b")
+    assert out is match
+    create.assert_not_awaited()
+    assert gate.call_args.args[:3] == (7, 1, "t")
+    assert gate.call_args.args[3] == "d\n\nb"
+
+
+@pytest.mark.asyncio
+async def test_create_milestone_skips_the_gate_when_forced_or_done():
+    """force: the caller read the match. done: a record of past work is not a
+    plan competing with an open one."""
+    gate = AsyncMock(return_value={"duplicate": True})
+    create = AsyncMock(return_value=fake_milestone(id=6))
+    with patch("scribe.mcp.tools.milestones.dedup_svc.plan_gate", gate), \
+         patch("scribe.mcp.tools.milestones.milestones_svc.create_milestone", create):
+        assert (await create_milestone(project_id=1, title="t", force=True))["id"] == 6
+        assert (await create_milestone(project_id=1, title="t", status="done"))["id"] == 6
+    gate.assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_update_milestone_sends_body():
     m = fake_milestone()

tests/test_mcp_tool_planning.py

@@ -7,6 +7,13 @@ from tests.helpers import fake_task
 pytestmark = pytest.mark.usefixtures("_bind_user")
 
 
+@pytest.fixture(autouse=True)
+def _no_plan_gate():
+    """The plan gate reads the database; the tests that are about it re-patch it."""
+    with patch("scribe.mcp.tools.tasks.dedup_svc.plan_gate", AsyncMock(return_value=None)):
+        yield
+
+
 @pytest.mark.asyncio
 async def test_start_planning_tool_delegates_to_service():
     payload = {"milestone": {"id": 5}, "applicable_rules": [], "project_rules": [],
@@ -23,6 +30,42 @@ async def test_start_planning_tool_delegates_to_service():
     }
 
 
+@pytest.mark.asyncio
+async def test_start_planning_returns_the_plan_that_already_covers_it():
+    """The FabledLibrarian failure (milestone 415): a session that could not see
+    the existing plan made a second one. Now it is handed the first, and
+    nothing is created."""
+    match = {"duplicate": True, "existing_id": 12}
+    svc = AsyncMock()
+    with patch("scribe.mcp.tools.tasks.dedup_svc.plan_gate",
+               AsyncMock(return_value=match)) as gate, \
+         patch("scribe.mcp.tools.tasks.dedup_svc.find_duplicate_note", AsyncMock()) as steps, \
+         patch("scribe.mcp.tools.tasks.planning_svc.start_planning", svc):
+        from scribe.mcp.tools.tasks import start_planning
+        out = await start_planning(project_id=3, title="Metadata", body="design",
+                                   steps=[{"title": "Resolve editions", "body": "via providers"}])
+    assert out is match
+    svc.assert_not_awaited()
+    steps.assert_not_awaited()
+    # The candidate is judged by its steps as well as its design.
+    assert gate.call_args.args[:3] == (7, 3, "Metadata")
+    assert "design" in gate.call_args.args[3]
+    assert "Resolve editions\nvia providers" in gate.call_args.args[3]
+
+
+@pytest.mark.asyncio
+async def test_force_creates_the_plan_without_asking_the_gate():
+    gate = AsyncMock(return_value={"duplicate": True})
+    with patch("scribe.mcp.tools.tasks.dedup_svc.plan_gate", gate), \
+         patch("scribe.mcp.tools.tasks.planning_svc.start_planning",
+               AsyncMock(return_value={"milestone": {"id": 5}})) as svc:
+        from scribe.mcp.tools.tasks import start_planning
+        out = await start_planning(project_id=3, title="Metadata", force=True)
+    assert out["milestone"]["id"] == 5
+    svc.assert_awaited_once()
+    gate.assert_not_awaited()
+
+
 @pytest.mark.asyncio
 async def test_get_task_augments_plan_with_rules():
     applicable = {"rules": [{"id": 1, "title": "r"}], "truncated": False,

tests/test_services_dedup.py

@@ -4,10 +4,15 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 
 from scribe.services.dedup import (
+    PLAN_MATCH_DEFAULT_THRESHOLD,
     DuplicateMatch,
     duplicate_response,
     find_duplicate_note,
     find_duplicate_rule,
+    find_matching_plan,
+    get_plan_match_threshold,
+    plan_candidate_text,
+    plan_match_response,
 )
 from tests.helpers import fake_note, make_mock_session
 
@@ -342,3 +347,78 @@ def test_every_kind_has_a_suggestion_and_none_proposes_merging_notes():
     assert "merge" in _KIND_SUGGESTION["snippet"]
     assert "NOT merge" in _KIND_SUGGESTION["note"]
     assert "supersedes" in _KIND_SUGGESTION["note"]
+
+
+# ── the plan gate (milestone 415, step 4) ─────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_plan_title_match_short_circuits_the_semantic_arm():
+    ms = MagicMock(id=415, title="Plan gate")
+    sem = AsyncMock()
+    with patch("scribe.services.dedup.can_read_project", AsyncMock(return_value=True)), \
+         patch("scribe.services.dedup.async_session", return_value=_session_returning(ms)), \
+         patch("scribe.services.dedup.embeddings_svc.semantic_search_milestones", sem):
+        dup = await find_matching_plan(7, 2, " plan  GATE", "x" * 300)
+    assert (dup.id, dup.reason, dup.similarity) == (415, "title", 1.0)
+    sem.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_plan_semantic_arm_asks_for_active_plans_in_the_project_at_the_setting():
+    ms = MagicMock(id=9, title="Metadata")
+    sem = AsyncMock(return_value=[(0.912345, ms)])
+    with patch("scribe.services.dedup.can_read_project", AsyncMock(return_value=True)), \
+         patch("scribe.services.dedup.async_session", return_value=_session_returning(None)), \
+         patch("scribe.services.dedup.embeddings_svc.semantic_search_milestones", sem), \
+         patch("scribe.services.settings.get_setting", AsyncMock(return_value="0.8")):
+        dup = await find_matching_plan(7, 2, "Book metadata", "x" * 300)
+    assert (dup.id, dup.reason, dup.similarity) == (9, "semantic", 0.912)
+    kw = sem.call_args.kwargs
+    assert (kw["project_id"], kw["status"], kw["threshold"]) == (2, "active", 0.8)
+
+
+@pytest.mark.asyncio
+async def test_plan_gate_fails_open():
+    boom = MagicMock(side_effect=RuntimeError("db down"))
+    with patch("scribe.services.dedup.can_read_project", AsyncMock(return_value=True)), \
+         patch("scribe.services.dedup.async_session", boom):
+        assert await find_matching_plan(7, 2, "Anything", "x" * 300) is None
+    with patch("scribe.services.dedup.can_read_project", AsyncMock(side_effect=RuntimeError)):
+        assert await find_matching_plan(7, 2, "Anything", "x" * 300) is None
+    assert await find_matching_plan(7, 0, "No project") is None
+
+
+@pytest.mark.asyncio
+async def test_plan_gate_says_nothing_about_a_project_the_caller_cannot_read():
+    ms = MagicMock(id=415, title="Their plan")
+    session = MagicMock(return_value=_session_returning(ms))
+    with patch("scribe.services.dedup.can_read_project", AsyncMock(return_value=False)), \
+         patch("scribe.services.dedup.async_session", session):
+        assert await find_matching_plan(8, 2, "Their plan") is None
+    session.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_a_bad_threshold_setting_falls_back_to_the_default():
+    with patch("scribe.services.settings.get_setting", AsyncMock(return_value="lots")):
+        assert await get_plan_match_threshold(7) == PLAN_MATCH_DEFAULT_THRESHOLD
+    with patch("scribe.services.settings.get_setting", AsyncMock(return_value="7")):
+        assert await get_plan_match_threshold(7) == 1.0
+
+
+def test_plan_candidate_text_carries_the_steps():
+    text = plan_candidate_text(description=None, body="  design ", step_texts=["Step one\n", ""])
+    assert text == "design\n\nStep one"
+
+
+def test_plan_match_response_points_at_adding_steps_not_a_second_plan():
+    out = plan_match_response(DuplicateMatch(12, "Metadata", 0.93, "semantic"),
+                              {"total": 5, "completed": 2, "description": "providers"})
+    assert out["duplicate"] is True and out["existing_id"] == 12
+    assert out["existing_milestone"] == {
+        "id": 12, "title": "Metadata", "description": "providers", "total": 5, "completed": 2,
+    }
+    for phrase in ("create_records(milestone_id=12", "get_milestone(12)", "force=true",
+                   "2 of 5 steps"):
+        assert phrase in out["message"]

tests/test_settings_defaults_agree.py

@@ -36,28 +36,32 @@ import re
 import pytest
 
 ROOT = pathlib.Path(__file__).resolve().parents[1]
-_PY = ROOT / "src" / "scribe" / "services" / "plugin_context.py"
+_SERVICES = ROOT / "src" / "scribe" / "services"
 _VUE = ROOT / "frontend" / "src" / "views" / "SettingsView.vue"
 
-# (python constant, vue ref). Hand-written because the pairing is an editorial
-# fact — the names do not share a convention either side could derive — but
-# every entry is asserted to EXIST on both sides, so a rename fails loudly
-# here rather than silently dropping that threshold from the check.
+# (services module, python constant, vue ref). Hand-written because the
+# pairing is an editorial fact — the names do not share a convention either
+# side could derive — but every entry is asserted to EXIST on both sides, so a
+# rename fails loudly here rather than silently dropping that threshold from
+# the check.
 _PAIRS = (
-    ("AUTOINJECT_DEFAULT_THRESHOLD", "kbInjectThreshold"),
-    ("WRITEPATH_DEFAULT_THRESHOLD", "kbWritePathThreshold"),
-    ("RULEHINT_DEFAULT_THRESHOLD", "kbRuleHintThreshold"),
-    ("TOOLRULE_DEFAULT_THRESHOLD", "kbToolRuleThreshold"),
-    ("PROMPTRULE_DEFAULT_THRESHOLD", "kbPromptRuleThreshold"),
+    ("plugin_context.py", "AUTOINJECT_DEFAULT_THRESHOLD", "kbInjectThreshold"),
+    ("plugin_context.py", "WRITEPATH_DEFAULT_THRESHOLD", "kbWritePathThreshold"),
+    ("plugin_context.py", "RULEHINT_DEFAULT_THRESHOLD", "kbRuleHintThreshold"),
+    ("plugin_context.py", "TOOLRULE_DEFAULT_THRESHOLD", "kbToolRuleThreshold"),
+    ("plugin_context.py", "PROMPTRULE_DEFAULT_THRESHOLD", "kbPromptRuleThreshold"),
+    # The plan gate (milestone 415): it blocks a create, so a form showing a
+    # looser bar than the one in force would be the more misleading drift.
+    ("dedup.py", "PLAN_MATCH_DEFAULT_THRESHOLD", "kbPlanMatchThreshold"),
 )
 
 
-def _python_default(name: str) -> float:
+def _python_default(module: str, name: str) -> float:
     m = re.search(rf"^{re.escape(name)}\s*=\s*([0-9.]+)\s*$",
-                  _PY.read_text(), re.M)
+                  (_SERVICES / module).read_text(), re.M)
     assert m, (
         f"{name} is no longer a bare module-level float in "
-        f"services/plugin_context.py. If it moved or was renamed, update "
+        f"services/{module}. If it moved or was renamed, update "
         f"_PAIRS; if it was retired, drop its row — leaving it here checks "
         f"nothing while looking like coverage."
     )
@@ -75,11 +79,11 @@ def _vue_default(ref_name: str) -> float:
     return float(m.group(1))
 
 
-@pytest.mark.parametrize(("constant", "ref_name"), _PAIRS,
-                         ids=[p[0] for p in _PAIRS])
-def test_the_form_shows_the_default_the_server_uses(constant, ref_name):
+@pytest.mark.parametrize(("module", "constant", "ref_name"), _PAIRS,
+                         ids=[p[1] for p in _PAIRS])
+def test_the_form_shows_the_default_the_server_uses(module, constant, ref_name):
     """An untouched control must render the bar actually in force."""
-    server, form = _python_default(constant), _vue_default(ref_name)
+    server, form = _python_default(module, constant), _vue_default(ref_name)
     assert form == server, (
         f"SettingsView shows {form} for {ref_name} while the server defaults "
         f"to {server} ({constant}). An operator who has never set this reads "