Files
FabledScribe/tests/test_mcp_tool_projects.py
T
bvandeusenandClaude Opus 5 7f974d9749
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 9s
CI & Build / integration (push) Successful in 46s
CI & Build / TypeScript typecheck (push) Successful in 53s
CI & Build / Python tests (push) Successful in 1m44s
CI & Build / Build & push image (push) Successful in 23s
feat(mcp): enter_project becomes a small primer: goal, recent work, open work, vocabulary (#4045)
The handshake carried the whole project record, every milestone's plan, full
rule text, the notes most recently edited and ~9k of design guidance. For
project 2 that was ~222k characters, past what an MCP client accepts as a tool
result. Each category was walked through with the operator and sized to what a
session needs on arrival; each names the call that has the rest.

- project: id, title, status and the full goal (session start's "full goal"
  pointer still lands here). get_project keeps the whole record.
- milestone_summary: the 5 most recently touched milestones, any status, most
  recent first, without plans. Summaries gain last_touched_at: the later of
  the milestone's own edit and its newest step update, from the query that
  already counts steps. milestone_summary_omitted counts the rest and points
  to list_milestones. get_project and list_milestones list every milestone,
  also without plans.
- open_tasks: the 10 most recently touched open tasks, with or without a
  milestone, each naming its milestone. list_notes gains sort="touched"
  (the later of updated_at and the newest work-log), because a log doesn't
  bump updated_at.
- recent_notes: dropped. Retrieval surfaces notes by relevance, and
  get_recent covers recency.
- systems: id and name.
- design_system: summary plus guidance_call. get_design_system gains
  resolved_guidance, the chain-merged prose; its own guidance field is only
  the departures, so session start's old pointer to it led to a fragment.
  The session start pointer and using-scribe's "Building UI" section now
  name resolved_guidance.
- rules: rules_payload(brief=True) gives project_rules as id and title plus
  subscribed_rulebooks, and records only what it shows. Retrieval delivers
  rules in full and ignores subscriptions (#4052). Other callers unchanged.
- pattern_coverage, inception and systems_bootstrap: unchanged.

Clients: the plugin's using-scribe skill, the compaction notice and session
start are updated here; the REST project summary only gains last_touched_at.
Plugin version minted.

Tests: a size ceiling on the handshake for a large project; milestone and
task selection and naming; brief rules; resolved_guidance; the session
start pointer; and a real-Postgres test that a work-log touches its task and
a step update touches its milestone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy
2026-09-14 22:04:38 -04:00

477 lines
20 KiB
Python

"""Tests for fable_*_project tools."""
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from scribe.mcp.tools.projects import (
list_projects, get_project, create_project,
update_project, enter_project,
)
from tests.helpers import FakeMCP, fake_project
pytestmark = pytest.mark.usefixtures("_bind_user")
@pytest.fixture(autouse=True)
def _no_systems():
"""enter_project now surfaces the project's Systems as the tagging
vocabulary (#2546). These are tool-layer unit tests with no database, so
the lookup is stubbed to the common case — a project with none. The
populated shape is asserted in its own test below.
"""
with patch("scribe.mcp.tools.projects.systems_svc.list_systems",
AsyncMock(return_value=[])):
yield
@pytest.fixture(autouse=True)
def _no_coverage():
"""enter_project also reads the pattern-coverage cache (#2692) — same
deal: no database here, stub the common case (nothing computed). The
populated line is asserted in tests/test_pattern_coverage.py.
"""
with patch("scribe.mcp.tools.projects.coverage_svc.cached_coverage",
AsyncMock(return_value=None)):
yield
@pytest.fixture(autouse=True)
def _no_background_seed():
"""enter_project now fire-and-forgets a coverage self-seed (#2802). These
are no-database unit tests, so the spawn is stubbed out; the firing shape
has its own test below."""
with patch("scribe.mcp.tools.projects.spawn") as mock:
yield mock
@pytest.fixture(autouse=True)
def _no_bootstrap():
"""With _no_systems stubbing an empty vocabulary, every test here reaches
the zero-Systems branch, whose bootstrap ask (#2683) counts the project's
records — a database read. Stub the common case (young project, no ask);
the firing shape has its own test below.
"""
with patch("scribe.mcp.tools.projects.systems_tools.bootstrap_systems_ask",
AsyncMock(return_value=None)) as mock:
yield mock
@pytest.mark.asyncio
async def test_list_projects_wraps_in_dict():
rows = [fake_project(id=1), fake_project(id=2)]
with patch(
"scribe.mcp.tools.projects.projects_svc.list_projects",
AsyncMock(return_value=rows),
):
out = await list_projects()
assert len(out["projects"]) == 2
@pytest.mark.asyncio
async def test_get_project_enriches_with_milestone_summary():
p = fake_project(id=5, title="found")
milestone_summary = [{"id": 10, "title": "MS", "status": "active", "total": 3}]
applicable_payload = {
"rules": [], "truncated": False, "subscribed_rulebooks": [],
}
with patch(
"scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=p),
), patch(
"scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
AsyncMock(return_value=milestone_summary),
), patch(
"scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
AsyncMock(return_value=applicable_payload),
):
out = await get_project(project_id=5)
assert out["id"] == 5
assert out["milestone_summary"] == milestone_summary
@pytest.mark.asyncio
async def test_get_project_includes_applicable_rules_and_subscribed_rulebooks():
"""The augmented get_project response includes applicable_rules and
subscribed_rulebooks pulled from services/rulebooks.get_applicable_rules.
"""
p = fake_project(id=3, title="Fabled Assistant")
milestone_summary = []
applicable_payload = {
"rules": [
{"id": 1, "title": "dev is home",
"statement": "Work directly on dev",
"topic_title": "git-workflow",
"rulebook_title": "FabledSword family"},
],
"truncated": False,
"subscribed_rulebooks": [{"id": 1, "title": "FabledSword family"}],
}
with patch(
"scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=p),
), patch(
"scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
AsyncMock(return_value=milestone_summary),
), patch(
"scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
AsyncMock(return_value=applicable_payload),
):
out = await get_project(project_id=3)
assert out["applicable_rules"][0]["title"] == "dev is home"
assert out["subscribed_rulebooks"] == [{"id": 1, "title": "FabledSword family"}]
assert out["applicable_rules_truncated"] is False
@pytest.mark.asyncio
async def test_get_project_raises_when_not_found():
with patch(
"scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=None),
):
with pytest.raises(ValueError, match="project 999 not found"):
await get_project(project_id=999)
@pytest.mark.asyncio
async def test_create_project_passes_color_empty_as_none():
p = fake_project()
mock = AsyncMock(return_value=p)
with patch("scribe.mcp.tools.projects.projects_svc.create_project", mock):
await create_project(title="P", color="")
assert mock.call_args.kwargs["color"] is None
@pytest.mark.asyncio
async def test_update_project_only_sends_non_default_fields():
p = fake_project()
mock = AsyncMock(return_value=p)
with patch("scribe.mcp.tools.projects.projects_svc.update_project", mock):
await update_project(project_id=1, status="archived")
args, kwargs = mock.call_args
assert args == (7, 1)
assert kwargs == {"status": "archived"}
@pytest.mark.asyncio
async def test_update_project_raises_when_not_found():
with patch(
"scribe.mcp.tools.projects.projects_svc.update_project",
AsyncMock(return_value=None),
):
with pytest.raises(ValueError, match="project 999 not found"):
await update_project(project_id=999, title="x")
@pytest.mark.asyncio
async def test_enter_project_composes_full_context():
"""enter_project pulls project + rule titles + milestone summary + open
tasks in one composed call, each in its brief handshake form (#4045)."""
p = fake_project(id=5, title="P")
applicable_payload = {
"rules": [{"id": 1, "title": "r1", "statement": "s",
"topic_title": "t", "rulebook_title": "rb"}],
"project_rules": [{"id": 99, "title": "pr1", "statement": "ps"}],
"truncated": False,
"subscribed_rulebooks": [{"id": 2, "title": "rb"}],
}
milestone_summary = [{"id": 10, "title": "MS", "status": "active", "total": 3}]
task1 = MagicMock()
task1.id = 100; task1.title = "T1"; task1.status = "in_progress"
task1.priority = "high"; task1.task_kind = "work"; task1.milestone_id = 10
note1 = MagicMock()
note1.id = 200; note1.title = "N1"
note1.updated_at = None # avoids datetime mocking
with patch(
"scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=p),
), patch(
"scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
AsyncMock(return_value=applicable_payload),
), patch(
"scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
AsyncMock(return_value=milestone_summary),
), patch(
"scribe.mcp.tools.projects.notes_svc.list_notes",
AsyncMock(side_effect=[([task1], 1), ([note1], 1)]),
):
out = await enter_project(project_id=5)
assert out["project"] == {"id": 5, "title": "P", "status": "active", "goal": ""}
assert out["milestone_summary"] == milestone_summary
# Rules arrive in full by retrieval; the handshake lists the project's own
# by id and title and drops the subscription bookkeeping (#4045).
assert out["project_rules"] == [{"id": 99, "title": "pr1"}]
assert out["subscribed_rulebooks"] == [{"id": 2, "title": "rb"}]
for gone in ("applicable_rules", "applicable_rules_truncated",
"suppressed_rules", "suppressed_topics", "recent_notes"):
assert gone not in out, gone
assert out["open_tasks"] == [{
"id": 100, "title": "T1", "status": "in_progress",
"milestone_id": 10, "milestone_title": "MS",
}]
# No design system on this project -> the key is present and null, not
# absent. A caller that has to distinguish "no key" from "no system" will
# eventually get it wrong.
assert out["design_system"] is None
# No Systems -> present-and-empty, NOT absent: this key is the tagging
# vocabulary, and "this project has no named areas yet" is information the
# create-the-System instruction acts on.
assert out["systems"] == []
# Young project, no bootstrap ask -> the key is ABSENT, not null: it exists
# to be acted on, and a key that usually says null gets skipped (#2483).
assert "systems_bootstrap" not in out
@pytest.mark.asyncio
async def test_enter_project_surfaces_the_systems_vocabulary():
"""The tagging instruction is only executable if the vocabulary is in
front of the agent when it writes. It never was, and tagging stopped three
days after the feature landed — one System, nothing tagged since July 28
(#2546's audit). Trimmed to id/name/first-line: it rides on every session
start, and the full charter is get_system's job."""
p = fake_project(id=5)
sys1 = MagicMock()
sys1.id = 3
sys1.name = "retrieval"
sys1.description = "Embeddings, ranking, auto-inject.\nLong detail below."
with patch(
"scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=p),
), patch(
"scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
AsyncMock(return_value={"rules": [], "truncated": False,
"subscribed_rulebooks": []}),
), patch(
"scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
AsyncMock(return_value=[]),
), patch(
"scribe.mcp.tools.projects.notes_svc.list_notes",
AsyncMock(side_effect=[([], 0), ([], 0)]),
), patch(
"scribe.mcp.tools.projects.systems_svc.list_systems",
AsyncMock(return_value=[sys1]),
):
out = await enter_project(project_id=5)
assert out["systems"] == [{"id": 3, "name": "retrieval"}]
def _enter_project_stubs(p):
"""The four patches every enter_project test repeats, as one context list."""
return [
patch("scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=p)),
patch("scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
AsyncMock(return_value={"rules": [], "truncated": False,
"subscribed_rulebooks": []})),
patch("scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
AsyncMock(return_value=[])),
patch("scribe.mcp.tools.projects.notes_svc.list_notes",
AsyncMock(side_effect=[([], 0), ([], 0)])),
]
@pytest.mark.asyncio
async def test_enter_project_carries_the_bootstrap_ask_when_it_fires():
"""The arrival-moment half of #2683: a mature zero-Systems project greets
the session with the concrete bootstrap ask, before it is deep in a task —
the moment minting a starter vocabulary is cheapest."""
import contextlib
ask = "This project has 282 records and NO Systems modelled — ..."
with contextlib.ExitStack() as stack:
for cm in _enter_project_stubs(fake_project(id=5)):
stack.enter_context(cm)
stack.enter_context(patch(
"scribe.mcp.tools.projects.systems_tools.bootstrap_systems_ask",
AsyncMock(return_value=ask),
))
out = await enter_project(project_id=5)
assert out["systems_bootstrap"] == ask
@pytest.mark.asyncio
async def test_enter_project_never_asks_bootstrap_once_a_vocabulary_exists(
_no_bootstrap,
):
"""The ask is self-retiring: the first System ends it — enter_project must
not even evaluate it once the vocabulary is non-empty."""
import contextlib
sys1 = MagicMock()
sys1.id = 3; sys1.name = "retrieval"; sys1.description = ""
with contextlib.ExitStack() as stack:
for cm in _enter_project_stubs(fake_project(id=5)):
stack.enter_context(cm)
stack.enter_context(patch(
"scribe.mcp.tools.projects.systems_svc.list_systems",
AsyncMock(return_value=[sys1]),
))
out = await enter_project(project_id=5)
assert "systems_bootstrap" not in out
_no_bootstrap.assert_not_awaited()
@pytest.mark.asyncio
async def test_enter_project_fires_the_coverage_seed_on_the_owner(
_no_background_seed,
):
"""The arrival self-seed (#2802): entering spawns refresh_if_stale on the
project OWNER's id with the cache read the enter already did — fire and
forget, so a missing ledger seeds itself without the UI button, and the
enter stays fast."""
import contextlib
project = fake_project(id=5)
project.user_id = 42 # explicit: the OWNER, not the caller (ctx uid=7)
with contextlib.ExitStack() as stack:
for cm in _enter_project_stubs(project):
stack.enter_context(cm)
seed = stack.enter_context(patch(
"scribe.mcp.tools.projects.coverage_svc.refresh_if_stale",
MagicMock(return_value=object()),
))
await enter_project(project_id=5)
seed.assert_called_once_with(42, 5, cached=None)
_no_background_seed.assert_called_once()
assert _no_background_seed.call_args.kwargs["site"] == "enter_project.coverage_seed"
@pytest.mark.asyncio
async def test_enter_project_hands_back_the_design_system_when_the_project_has_one():
"""The handshake is where an agent learns what binds it, and a design
system binds the same way a rule does. Before this it was reachable only by
an agent that already knew to call resolve_design_system — so the standards
were present in the store and absent from the work."""
p = fake_project(id=5, design_system_id=9)
design = {"id": 9, "title": "App kit", "guidance": [{"title": "House"}],
"token_count": 95, "token_groups": ["surface"],
"inherits_from": ["House"], "description": ""}
with patch(
"scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=p),
), patch(
"scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
AsyncMock(return_value={"rules": [], "truncated": False,
"subscribed_rulebooks": []}),
), patch(
"scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
AsyncMock(return_value=[]),
), patch(
"scribe.mcp.tools.projects.notes_svc.list_notes",
AsyncMock(side_effect=[([], 0), ([], 0)]),
), patch(
"scribe.mcp.tools.projects.design_systems_svc.design_context",
AsyncMock(return_value=design),
) as ctx:
out = await enter_project(project_id=5)
assert out["design_system"]["token_count"] == 95
assert out["design_system"]["inherits_from"] == ["House"]
# Summary only: the guidance is one call away (#4045).
assert "guidance" not in out["design_system"]
assert out["design_system"]["guidance_call"] == "get_design_system(9) → resolved_guidance"
assert ctx.await_args.args == (7, 9) # caller's id, the project's system
@pytest.mark.asyncio
async def test_enter_project_raises_when_project_not_found():
with patch(
"scribe.mcp.tools.projects.projects_svc.get_project",
AsyncMock(return_value=None),
):
with pytest.raises(ValueError, match="project 999 not found"):
await enter_project(project_id=999)
def test_enter_project_registered_in_register():
"""register(mcp) registers enter_project alongside the existing tools."""
from scribe.mcp.tools.projects import register
mcp = FakeMCP()
register(mcp)
assert "enter_project" in mcp.names
# --- milestone 297: the inception doors ---------------------------------------
@pytest.mark.asyncio
async def test_create_project_without_inception_args_stays_undecided():
p = fake_project(id=5, title="P", inception=None)
with patch("scribe.mcp.tools.projects.projects_svc.create_project", AsyncMock(return_value=p)), \
patch("scribe.mcp.tools.projects.inception_svc.decide", AsyncMock()) as decide:
out = await create_project(title="P")
decide.assert_not_awaited()
assert "inception_hint" in out and "inception_effects" not in out
@pytest.mark.asyncio
async def test_create_project_with_inception_args_decides_via_mcp():
p = fake_project(id=5, title="P", inception=None)
decided = {"inception": {"via": "mcp", "choices": {}}, "effects": {"systems_seeded": []}}
with patch("scribe.mcp.tools.projects.projects_svc.create_project", AsyncMock(return_value=p)), \
patch("scribe.mcp.tools.projects.inception_svc.decide", AsyncMock(return_value=decided)) as decide:
out = await create_project(title="P", subscribe_rulebooks=[1], design_system_id=-1, seed_systems=True)
kw = decide.await_args.kwargs
assert decide.await_args.args[1] == 5 and kw["via"] == "mcp"
assert kw["choices"] == {"subscribe_rulebooks": [1],
"design_system_id": None, "seed_systems": True}
assert out["inception"]["via"] == "mcp" and "inception_effects" in out
@pytest.mark.asyncio
async def test_decide_project_inception_tool_records_an_inherit_all_decision_when_given_nothing():
from scribe.mcp.tools.projects import decide_project_inception
decided = {"inception": {"via": "mcp"}, "effects": {}}
with patch("scribe.mcp.tools.projects.inception_svc.decide", AsyncMock(return_value=decided)) as decide:
out = await decide_project_inception(project_id=5)
assert decide.await_args.kwargs["choices"] == {}
assert out["project_id"] == 5 and out["inception"]["via"] == "mcp"
@pytest.mark.asyncio
async def test_enter_project_carries_the_inception_ask_only_for_an_undecided_own_project():
applicable = {"rules": [], "project_rules": [], "truncated": False,
"subscribed_rulebooks": []}
ask = {"defaults": {}, "ask": "decide", "call": "decide_project_inception(...)"}
async def run(project):
with patch("scribe.mcp.tools.projects.projects_svc.get_project", AsyncMock(return_value=project)), \
patch("scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules", AsyncMock(return_value=applicable)), \
patch("scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary", AsyncMock(return_value=[])), \
patch("scribe.mcp.tools.projects.notes_svc.list_notes", AsyncMock(side_effect=[([], 0), ([], 0)])), \
patch("scribe.mcp.tools.projects.systems_svc.list_systems", AsyncMock(return_value=[])), \
patch("scribe.mcp.tools.projects.systems_tools.bootstrap_systems_ask", AsyncMock(return_value=None)), \
patch("scribe.mcp.tools.projects.inception_svc.inception_ask", AsyncMock(return_value=ask)) as asked:
return await enter_project(project_id=5), asked
# Own + undecided → the ask rides along.
out, asked = await run(fake_project(id=5, title="P", user_id=7, inception=None))
assert out["inception"] == ask and asked.await_count == 1
# Decided → absent, and the ask is not even built.
out, asked = await run(fake_project(id=5, title="P", user_id=7, inception={"via": "legacy"}))
assert "inception" not in out and asked.await_count == 0
# Someone else's (shared) project, undecided → not this caller's to decide.
out, asked = await run(fake_project(id=5, title="P", user_id=8, inception=None))
assert "inception" not in out and asked.await_count == 0
def test_inception_routes_and_tool_are_registered():
from scribe.app import create_app
from scribe.mcp.server import build_mcp_server
rules = {r.rule for r in create_app().url_map.iter_rules()}
assert "/api/projects/<int:project_id>/inception" in rules
assert "/api/projects/<int:project_id>/inception/defaults" in rules
mcp = build_mcp_server()
assert mcp._tool_manager.get_tool("decide_project_inception") is not None
tool = mcp._tool_manager.get_tool("create_project")
for name in ("subscribe_rulebooks", "design_system_id", "seed_systems"):
assert name in tool.parameters.get("properties", {}), name