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/services/knowledge.py

@@ -18,7 +18,7 @@ in your ambient lists.
 import json
 import logging
 
-from sqlalchemy import func, select
+from sqlalchemy import and_, func, or_, select
 
 from scribe.models import async_session
 from scribe.models.note import Note
@@ -108,6 +108,83 @@ def _location_clause(parts: dict[str, str]):
     return Note.data.path_exists(location_jsonpath(parts))
 
 
+# --- drift-check filter (#2086) ----------------------------------------------
+# `verification` selects on the drift-check verdict stored in `data.verification`
+# (see services/snippets.py). Statuses are the service's own constants; the two
+# composite values are what the operator actually asks for.
+#
+# The interesting one is `attention`. A verdict describes the code it was checked
+# against, so an OK verdict on code that has since been edited is not an OK
+# record — nobody has checked what's actually there. That is expressible in SQL
+# only because `data.code_sha` mirrors the current code's fingerprint alongside
+# the verdict's: jsonpath compares the two fields within the row, so this stays
+# one index-served predicate rather than a post-filter that would make the
+# pagination total a lie.
+
+def verification_matches(data: dict | None, value: str) -> bool:
+    """Python dialect of the verification predicate.
+
+    Keep in step with _verification_clause — the semantic arm's candidates are
+    already fetched, so there is no query left to narrow and the same rule has
+    to be expressible twice. Same arrangement as location_matches.
+    """
+    want = (value or "").strip().lower()
+    if not want:
+        return True
+    verdict = (data or {}).get("verification") or {}
+    status = verdict.get("status") or ""
+    if not status:
+        return want == "unverified"
+    expired = verdict.get("code_sha") != (data or {}).get("code_sha")
+    if want == "unverified":
+        return False
+    if want == "drifted":
+        return status != "ok"
+    if want == "attention":
+        return status != "ok" or expired
+    if want == "ok":
+        return status == "ok" and not expired
+    return status == want
+
+
+_VERIFY_DRIFTED_JSONPATH = '$.verification ? (@.status != "ok")'
+_VERIFY_EXPIRED_JSONPATH = "$ ? (@.verification.code_sha != @.code_sha)"
+_VERIFY_ANY_JSONPATH = "$.verification"
+
+
+def _verification_clause(value: str):
+    """SQL predicate for one `verification` filter value, or None for no filter."""
+    want = (value or "").strip().lower()
+    if not want:
+        return None
+    has_verdict = Note.data.path_exists(_VERIFY_ANY_JSONPATH)
+    if want == "unverified":
+        # Never checked at all. Rows predating migration 0070 have no `data`
+        # whatsoever and land here correctly — which is right, they haven't been.
+        return ~has_verdict
+    if want == "drifted":
+        return Note.data.path_exists(_VERIFY_DRIFTED_JSONPATH)
+    if want == "attention":
+        # Everything worth looking at: a failing verdict, OR an expired one.
+        return or_(
+            Note.data.path_exists(_VERIFY_DRIFTED_JSONPATH),
+            and_(has_verdict, Note.data.path_exists(_VERIFY_EXPIRED_JSONPATH)),
+        )
+    if want == "ok":
+        # A clean bill of health that still describes the current code. The
+        # `~expired` half matters: without it this would quietly include records
+        # whose blessing has lapsed, which is the exact failure the feature is
+        # meant to catch.
+        return and_(
+            Note.data.path_exists('$.verification ? (@.status == "ok")'),
+            ~Note.data.path_exists(_VERIFY_EXPIRED_JSONPATH),
+        )
+    # A specific status: 'missing' | 'moved' | 'changed'.
+    return Note.data.path_exists(
+        f"$.verification ? (@.status == {json.dumps(want)})"
+    )
+
+
 def _note_to_item(note: Note) -> dict:
     item: dict = {
         "id": note.id,
@@ -122,6 +199,22 @@ def _note_to_item(note: Note) -> dict:
         "created_at": note.created_at.isoformat(),
         "updated_at": note.updated_at.isoformat(),
     }
+    # Drift verdict (#2086), when one has been recorded. Included here rather
+    # than decorated on by the snippet layer because `current` is derivable from
+    # `data` alone — the verdict's code_sha against the row's — so this needs no
+    # body parsing and stays a plain projection of the column. Omitted entirely
+    # when unchecked, so "no key" and "never verified" don't become two states
+    # the client has to tell apart.
+    verdict = (note.data or {}).get("verification") if note.data else None
+    if verdict and verdict.get("status"):
+        item["verification"] = {
+            "status": verdict["status"],
+            "current": verdict.get("code_sha") == (note.data or {}).get("code_sha"),
+            "checked_at": verdict.get("checked_at"),
+            "detail": verdict.get("detail"),
+            "path": verdict.get("path"),
+        }
+
     # Task fields — override note_type and add status/priority/due_date
     if note.is_task:
         item["note_type"] = "task"
@@ -161,6 +254,7 @@ async def query_knowledge(
     offset: int,
     project_id: int | None = None,
     locations: dict[str, str] | None = None,
+    verification: str = "",
 ) -> tuple[list[dict], int]:
     """Query knowledge objects (non-task notes) with filters.
 
@@ -171,6 +265,10 @@ async def query_knowledge(
     Today only snippets carry locations, but the column is general, so the filter
     lives here with the query rather than in one type's service.
 
+    `verification` narrows on the drift-check verdict: 'ok', 'drifted',
+    'unverified', 'attention', or one specific failure ('missing' | 'moved' |
+    'changed'). Empty means no filter.
+
     Returns (items, total_count).
     """
     # Semantic search path — scores take priority over sort
@@ -178,6 +276,7 @@ async def query_knowledge(
         return await _semantic_knowledge_search(
             user_id, q, note_type=note_type, tags=tags, limit=limit,
             offset=offset, project_id=project_id, locations=locations,
+            verification=verification,
         )
 
     # No query = browsing. Narrower scope: a record shared directly with the
@@ -196,6 +295,10 @@ async def query_knowledge(
         if locations:
             base = base.where(_location_clause(locations))
 
+        verify_clause = _verification_clause(verification)
+        if verify_clause is not None:
+            base = base.where(verify_clause)
+
         # Count before pagination
         count_stmt = select(func.count()).select_from(base.subquery())
         total: int = (await session.execute(count_stmt)).scalar_one()
@@ -224,6 +327,7 @@ async def _semantic_knowledge_search(
     offset: int,
     project_id: int | None = None,
     locations: dict[str, str] | None = None,
+    verification: str = "",
 ) -> tuple[list[dict], int]:
     """Hybrid search: keyword matches first (title/body ILIKE), then semantic results.
 
@@ -259,6 +363,9 @@ async def _semantic_knowledge_search(
                 base = base.where(Note.tags.contains([tag]))
             if locations:
                 base = base.where(_location_clause(locations))
+            verify_clause = _verification_clause(verification)
+            if verify_clause is not None:
+                base = base.where(verify_clause)
             # Title matches first, then body-only matches, newest first within each
             base = base.order_by(
                 Note.title.ilike(pattern).desc(),
@@ -301,6 +408,8 @@ async def _semantic_knowledge_search(
             # narrow. See the comment on location_matches.
             if locations and not location_matches(note.data, locations):
                 continue
+            if verification and not verification_matches(note.data, verification):
+                continue
             semantic_notes.append(note)
     except Exception:
         logger.warning("Semantic search unavailable, using keyword results only", exc_info=True)