feat(snippets): drift check — verify a snippet still matches its source

A recorded snippet points at a repo · path · symbol that WILL rot: files
move, symbols get renamed, implementations diverge from the copy stored
here. Nothing detected any of it, so a record degraded silently from
"canonical reference" to "confidently wrong" — worse than no record, since
it is surfaced with the same authority either way.

WHERE THE CHECK RUNS. Agent-side, which the task flagged as the design
question to settle first. Scribe has no checkout of the operator's repos
and must not acquire one: giving the server repo access would make every
install a credential problem and break instance-agnosticism (rule #115).
The agent already has the working tree, so it does the comparing; the
server remembers the verdict, makes it queryable, and knows when it has
expired. New MCP tool verify_snippet teaches the four-step procedure and
records the result; a REST endpoint mirrors it so the UI can clear a
marker after a manual fix.

WHY THE VERDICT CARRIES A CODE HASH. A verdict describes the code it was
checked against. Invalidating it on edit means deciding which edits count
— a when_to_use tweak shouldn't void a code check, a rewrite must — which
is fiddly and easy to get subtly wrong, and easy for a new write path to
forget entirely. Stamping the verdict with a hash sidesteps all of it: one
whose code_sha no longer matches is self-evidently expired, computed at
read time, no invalidation branch to maintain.

That makes "expired" the interesting filter case. It is not `drifted`
(nothing was found wrong) and not `unverified` (a check did happen), yet
it plainly needs looking at — so `verification=attention` covers both. To
keep that one index-served predicate rather than a post-filter that would
make the pagination total a lie, data now also mirrors the CURRENT code's
fingerprint as data.code_sha, and a jsonpath compares the two fields
within the row. The filter is implemented in both dialects, SQL and
Python, for the same reason the location filter is: the semantic arm's
candidates arrive already fetched.

A merge deliberately carries no verdict forward — the survivor's code is a
union of several sources, so no prior check describes it, and unverified
is the honest answer.

UI: a danger-toned drift badge on each card (an actively misleading record
outranks a merely unused one), and a "Needs attention" filter. Its empty
state says plainly that never-verified snippets don't appear there —
otherwise `attention` would mean "everything" on day one and be useless as
a worklist.

Refs #2086

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

src/scribe/mcp/tools/snippets.py

@@ -20,7 +20,7 @@ from scribe.services import systems as systems_svc
 
 async def list_snippets(
     q: str = "", tag: str = "", limit: int = 50, project_id: int = 0,
-    repo: str = "", path: str = "", symbol: str = "",
+    repo: str = "", path: str = "", symbol: str = "", verification: str = "",
 ) -> dict:
     """List recorded snippets (reusable functions/components).
 
@@ -44,6 +44,12 @@ async def list_snippets(
             OR anything beneath it, so "frontend/src" finds
             "frontend/src/lib/x.ts" as well as itself.
         symbol: Narrow to snippets recorded under this symbol name, exactly.
+        verification: Narrow on the drift check (see verify_snippet).
+            "attention" is the one to reach for — everything whose recorded
+            location or code no longer checks out, plus everything whose verdict
+            expired because the snippet was edited after it was checked. Also
+            accepts "ok", "unverified", "drifted", or a specific failure:
+            "missing", "moved", "changed".
 
     `repo`/`path`/`symbol` must all match the SAME recorded location, so a
     snippet that lives in repo A and, separately, at path B in another repo is
@@ -70,7 +76,7 @@ async def list_snippets(
     items, total = await snippets_svc.list_snippets(
         uid, q=q or None, tag=tag, limit=max(1, min(limit, 100)),
         project_id=project_id or None,
-        repo=repo, path=path, symbol=symbol,
+        repo=repo, path=path, symbol=symbol, verification=verification,
     )
     labeled = await access_svc.label_shared_items(uid, items)
     usage = await usage_for_notes([int(it["id"]) for it in labeled])
@@ -184,6 +190,58 @@ async def get_snippet(snippet_id: int) -> dict:
     return data
 
 
+async def verify_snippet(
+    snippet_id: int, status: str, detail: str = "", path: str = "",
+) -> dict:
+    """Record whether a snippet's recorded location and code still match source.
+
+    YOU do the checking — Scribe has no copy of the repo and deliberately never
+    gets one. This tool only remembers your verdict so it becomes queryable and
+    so the operator can see what has rotted.
+
+    The procedure, once per snippet you're checking:
+      1. `get_snippet(id)` — read its `snippet.locations` and `snippet.code`.
+      2. Does the recorded path still exist in the working tree? If not →
+         status="missing".
+      3. Does the recorded symbol still appear in that file? If not →
+         status="moved" (the file is there, the thing isn't).
+      4. Does the source still match the recorded code, allowing for formatting?
+         Judge whether it still does the same thing — an added parameter or a
+         changed branch is "changed"; a reindent is not. If it diverged →
+         status="changed".
+      5. All three hold → status="ok".
+
+    Put what you actually found in `detail` ("renamed to parse_location_str",
+    "moved to services/knowledge.py"). It's what makes the record fixable later
+    by someone who wasn't here, so write it for them, not as a status echo.
+
+    A verdict expires automatically if the snippet is edited afterwards: it is
+    stamped with a hash of the code it was checked against, so it can never go
+    on vouching for code nobody checked. Re-verify after fixing a record.
+
+    Args:
+        snippet_id: The snippet you checked.
+        status: "ok" | "missing" | "moved" | "changed".
+        detail: What you found — free text, shown to the operator.
+        path: The path you actually checked, if it differs from the recorded
+            one (e.g. you found the symbol at its new home). Defaults to the
+            recorded path.
+
+    Requires write access: a verdict changes how the record is presented, so
+    being able to read a snippet someone shared with you doesn't let you mark
+    it broken.
+    """
+    uid = current_user_id()
+    note = await snippets_svc.record_verification(
+        uid, snippet_id, status=status, detail=detail, path=path,
+    )
+    if note is None:
+        raise ValueError(
+            f"snippet {snippet_id} not found, or you don't have write access to it"
+        )
+    return snippets_svc.snippet_to_dict(note)
+
+
 async def update_snippet(
     snippet_id: int,
     name: str | None = None,
@@ -307,6 +365,6 @@ async def merge_snippets(target_id: int, source_ids: list[int]) -> dict:
 def register(mcp) -> None:
     for fn in (
         list_snippets, create_snippet, get_snippet, update_snippet,
-        delete_snippet, merge_snippets,
+        delete_snippet, merge_snippets, verify_snippet,
     ):
         mcp.tool(name=fn.__name__)(fn)