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)

src/scribe/services/snippets.py

@@ -29,8 +29,10 @@ came from.
 from __future__ import annotations
 
 import asyncio
+import hashlib
 import logging
 import re
+from datetime import datetime, timezone
 
 from sqlalchemy import func, or_, select
 
@@ -303,8 +305,104 @@ def parse_snippet_fields(
 # and copying a blob into the column we index *around* would be pure weight.
 _DATA_FIELDS = (
     "name", "when_to_use", "signature", "language", "locations", "merged_from",
+    "verification",
 )
 
+# --- drift check (#2086) -----------------------------------------------------
+# A recorded snippet points at a repo · path · symbol that WILL rot: files move,
+# symbols get renamed, implementations diverge from the copy stored here. Left
+# undetected, the record degrades from "canonical reference" to "confidently
+# wrong" — which is worse than having no record, because it is surfaced with the
+# same authority either way.
+#
+# WHERE THE CHECK RUNS. Not here. Scribe has no checkout of the operator's repos
+# and must not acquire one (rule #115 — the instance stays agnostic about where
+# code lives; giving the server repo access would make every install a
+# credential problem). The agent already has the working tree, so IT does the
+# comparing and reports a verdict; the server's job is to remember the verdict,
+# make it queryable, and know when it has expired.
+#
+# WHY THE VERDICT CARRIES A CODE HASH. A stored verdict describes the code it
+# was checked against. Edit the snippet afterwards and that verdict is no longer
+# about anything — but invalidating it on write means deciding which edits count
+# (a `when_to_use` tweak shouldn't void a code check; a code rewrite must). That
+# rule is fiddly and easy to get subtly wrong. Recording the hash sidesteps it
+# entirely: a verdict whose `code_sha` no longer matches the body is self-
+# evidently expired, computed at read time, with no invalidation logic to
+# maintain and no way for an edit path to forget to call it.
+
+VERIFY_OK = "ok"
+VERIFY_MISSING = "missing"   # the recorded path is gone
+VERIFY_MOVED = "moved"       # path is there, the symbol isn't in it
+VERIFY_CHANGED = "changed"   # both present, but the source no longer matches
+VERIFY_STATUSES = (VERIFY_OK, VERIFY_MISSING, VERIFY_MOVED, VERIFY_CHANGED)
+
+# Everything that isn't a clean bill of health. "Stale" in the UI and the filter
+# means this set — the operator wants one list of things to look at, not four.
+VERIFY_DRIFTED = (VERIFY_MISSING, VERIFY_MOVED, VERIFY_CHANGED)
+
+
+def code_sha(code: str) -> str:
+    """Stable fingerprint of a snippet's code, for expiring stale verdicts.
+
+    Trailing whitespace per line and leading/trailing blank lines are stripped
+    before hashing: those change when a file is reformatted without the code
+    meaning anything different, and a verdict shouldn't expire over an editor's
+    trailing-newline habit.
+    """
+    normalized = "\n".join(line.rstrip() for line in (code or "").splitlines()).strip()
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:32]
+
+
+def compose_verification(
+    *,
+    status: str,
+    checked_code_sha: str,
+    detail: str = "",
+    path: str = "",
+    checked_at: str = "",
+) -> dict:
+    """Build the `data.verification` record. Unknown statuses are rejected here
+    rather than stored, so the filter never has to cope with a typo'd status."""
+    if status not in VERIFY_STATUSES:
+        raise ValueError(
+            f"unknown verification status {status!r} — expected one of {VERIFY_STATUSES}"
+        )
+    out = {
+        "status": status,
+        "code_sha": checked_code_sha,
+        "checked_at": checked_at or datetime.now(timezone.utc).isoformat(),
+    }
+    if (detail or "").strip():
+        out["detail"] = detail.strip()
+    if (path or "").strip():
+        out["path"] = path.strip()
+    return out
+
+
+def verification_view(note, fields: dict) -> dict:
+    """The verification readout for one snippet, including whether it's expired.
+
+    `status` is what was last reported; `current` says whether that verdict still
+    describes the code in the record. A verdict that no longer matches reads as
+    unverified, because that is what it is — nobody has checked THIS code.
+    """
+    stored = (fields.get("verification") or {}) if isinstance(fields, dict) else {}
+    if not stored or not stored.get("status"):
+        return {"status": "unverified", "current": False, "checked_at": None}
+    current = stored.get("code_sha") == code_sha(fields.get("code") or "")
+    return {
+        "status": stored["status"],
+        "current": current,
+        "checked_at": stored.get("checked_at"),
+        "detail": stored.get("detail"),
+        "path": stored.get("path"),
+        # What the operator actually wants to know: is there something to fix?
+        # An expired verdict counts as "needs looking at" even if it said ok,
+        # since the code it blessed is not the code that's there now.
+        "needs_attention": (not current) or stored["status"] in VERIFY_DRIFTED,
+    }
+
 
 def compose_data(
     *,
@@ -312,8 +410,10 @@ def compose_data(
     when_to_use: str = "",
     signature: str = "",
     language: str = "",
+    code: str = "",
     locations: list[dict] | None = None,
     merged_from: list[int] | None = None,
+    verification: dict | None = None,
 ) -> dict:
     """Build the `notes.data` mirror of a snippet's structured fields.
 
@@ -337,6 +437,19 @@ def compose_data(
     merged = _normalize_merged_from(merged_from)
     if merged:
         out["merged_from"] = merged
+    # Carried, never composed here — like merged_from. An ordinary edit must not
+    # silently drop the last drift check, and it doesn't need to invalidate it
+    # either: the verdict's code_sha expires it on read if the code moved on.
+    if verification:
+        out["verification"] = verification
+    # The current code's fingerprint — NOT the code, which stays in the body
+    # (see _DATA_FIELDS). Its only job is to make "this verdict has expired"
+    # expressible in SQL: a jsonpath can compare `@.verification.code_sha` to
+    # `@.code_sha` within the same row, so "show me everything that needs
+    # looking at" stays one index-served query instead of a post-filter that
+    # would break pagination counts.
+    if (code or "").strip():
+        out["code_sha"] = code_sha(code)
     return out
 
 
@@ -419,6 +532,7 @@ async def backfill_snippet_data(*, batch: int = 500) -> int:
                     when_to_use=fields["when_to_use"],
                     signature=fields["signature"],
                     language=fields["language"],
+                    code=fields["code"],
                     locations=fields["locations"],
                     merged_from=fields["merged_from"],
                 )
@@ -439,7 +553,13 @@ def snippet_to_dict(note) -> dict:
     ``snippet`` already reports, and shipping both would give API consumers two
     sources of truth for the same facts."""
     data = note.to_dict()
-    data["snippet"] = snippet_fields(note)
+    fields = snippet_fields(note)
+    data["snippet"] = fields
+    # Promoted out of `snippet` because it is a computed READOUT, not a recorded
+    # field: `current` and `needs_attention` are derived at read time by hashing
+    # the code, and burying them among the stored fields would invite a caller
+    # to try writing them back.
+    data["verification"] = verification_view(note, fields)
     return data
 
 
@@ -479,7 +599,7 @@ async def create_snippet(
         # body so the two can never describe different things.
         data=compose_data(
             name=name, when_to_use=when_to_use, signature=signature,
-            language=language, locations=locations,
+            language=language, code=code, locations=locations,
         ),
     )
     _embed_snippet(note)
@@ -513,6 +633,7 @@ async def list_snippets(
     repo: str = "",
     path: str = "",
     symbol: str = "",
+    verification: str = "",
 ) -> tuple[list[dict], int]:
     """List snippets (id/title/tags/preview dicts), most-recently-updated first.
 
@@ -523,7 +644,11 @@ async def list_snippets(
     ``repo`` / ``path`` / ``symbol`` are the reverse lookup: "what canonical
     helpers already live here?" They narrow to snippets recorded at a matching
     location, ANDed within one location entry, with ``path`` also matching as a
-    directory prefix. Combinable with ``q`` — search *and* place."""
+    directory prefix. Combinable with ``q`` — search *and* place.
+
+    ``verification`` narrows on the drift check: ``attention`` is the useful one
+    — everything whose recorded location or code no longer checks out, plus
+    everything whose verdict expired because the snippet was edited since."""
     return await knowledge_svc.query_knowledge(
         user_id=user_id,
         note_type=SNIPPET_NOTE_TYPE,
@@ -535,6 +660,7 @@ async def list_snippets(
         project_id=project_id,
         locations=knowledge_svc.location_parts(repo=repo, path=path, symbol=symbol)
         or None,
+        verification=verification,
     )
 
 
@@ -615,8 +741,12 @@ async def update_snippet(
         "data": compose_data(
             name=merged["name"], when_to_use=merged["when_to_use"],
             signature=merged["signature"], language=merged["language"],
-            locations=merged_locations,
+            code=merged["code"], locations=merged_locations,
             merged_from=merged.get("merged_from"),
+            # Carried through the edit rather than cleared. If this edit changed
+            # the code, the verdict's code_sha stops matching and it reads as
+            # unverified from here on — no invalidation branch to get wrong.
+            verification=merged.get("verification"),
         ),
     }
     # Recompute tags: keep any non-language, non-marker tags the note already had
@@ -639,6 +769,59 @@ async def update_snippet(
     return updated
 
 
+async def record_verification(
+    user_id: int,
+    snippet_id: int,
+    *,
+    status: str,
+    detail: str = "",
+    path: str = "",
+):
+    """Record the result of a drift check against the snippet's source.
+
+    The CHECK happens agent-side — Scribe has no checkout and shouldn't want one
+    (see the drift-check note above). This just remembers the verdict, stamped
+    with a hash of the code it was checked against so it expires by itself when
+    the snippet is edited.
+
+    Requires WRITE access: a verdict changes how the record is presented and
+    whether it shows up in the operator's "needs attention" list, so being able
+    to read a shared snippet must not let you mark it broken.
+
+    Returns the updated note, or None if the id isn't a snippet this user may
+    write. Raises ValueError on an unknown status.
+    """
+    note = await get_snippet(user_id, snippet_id)
+    if note is None:
+        return None
+    from scribe.services.access import can_write_note
+    if not await can_write_note(user_id, snippet_id):
+        return None
+
+    fields = snippet_fields(note)
+    verification = compose_verification(
+        status=status,
+        checked_code_sha=code_sha(fields.get("code") or ""),
+        detail=detail,
+        path=path or fields.get("path") or "",
+    )
+    # Rebuilt from the CURRENT stored fields plus the new verdict, so recording a
+    # check can't quietly rewrite anything else about the record. Note the body
+    # is untouched — a verdict is metadata about the snippet, not part of it, and
+    # writing it into the body would put it into the embedding.
+    data = compose_data(
+        name=fields.get("name", ""),
+        when_to_use=fields.get("when_to_use", ""),
+        signature=fields.get("signature", ""),
+        language=fields.get("language", ""),
+        code=fields.get("code", ""),
+        locations=fields.get("locations") or [],
+        merged_from=fields.get("merged_from") or [],
+        verification=verification,
+    )
+    return await notes_svc.update_note(note.user_id, snippet_id, data=data)
+
+
 async def delete_snippet(user_id: int, snippet_id: int) -> bool:
     """Retire a snippet to the trash (recoverable). Returns False if the id isn't
     a snippet this user may WRITE.
@@ -760,7 +943,10 @@ async def merge_snippets(user_id: int, target_id: int, source_ids: list[int]):
         data=compose_data(
             name=tgt_fields["name"], when_to_use=tgt_fields["when_to_use"],
             signature=tgt_fields["signature"], language=tgt_fields["language"],
-            locations=locations, merged_from=merged_from,
+            code=tgt_fields["code"], locations=locations, merged_from=merged_from,
+            # No verification carried: the survivor's code is a union of several
+            # sources, so no prior verdict describes it. It reads as unverified,
+            # which is the honest answer — nobody has checked THIS code.
         ),
     )
     if updated is None: