feat(ledger): divergence readout — button B where button A is canon, shape history, and judged-shape recheck (#2793, milestone 294 step 7)

Every judgment now goes through one helper that remembers the fingerprint
judged (classified_sha) and writes a code_shape_events row; the sync writes
vanished / reappeared / drifted events and flags recheck_at when a body
moves under an instance/variant. The refresh flags diverges_from on shapes
new since the previous computation that sit where one canon dominates the
judged siblings of their directory+kind and were not proposed as that canon
(a first seed flags nothing); the write-path hint asks the same question
in-band for the shapes the hook names. list_shapes(flag=divergence|recheck),
shape_history(project_id, path, symbol) (read-only), coverage line/payload/
card carry divergent + recheck. Backup v8 carries the history. Plugin 0.1.36.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/scribe/mcp/tools/shapes.py

@@ -63,6 +63,7 @@ async def list_shapes(
     limit: int = 100,
     offset: int = 0,
     proposal: str = "",
+    flag: str = "",
 ) -> dict:
     """Read a project's shape ledger — `status="unclassified"` IS the todo.
 
@@ -81,6 +82,14 @@ async def list_shapes(
             snippet_id, basis, score), "derive" (rows that repeat with NO
             canon: `proposal.group` names the family), or one basis
             (symbol/text/reference/signature/semantic).
+        flag: the divergence readout (#2793) — "divergence": shapes new
+            since the previous refresh in a directory where one canon
+            dominates the judged siblings and NOT proposed as that canon
+            (`diverges_from` names it: button B where button A is canon —
+            classify it: instance if it should use the canon, variant with
+            the why if deliberate); "recheck": judged instances/variants
+            whose body changed since judged (the judgment stands; confirm
+            it again with classify_shapes, or re-judge).
 
     Returns {"shapes": [...], "total": N} — total counts every match, not
     just this page. Each row's `classified_by` says who judged: agent /
@@ -107,11 +116,36 @@ async def list_shapes(
         uid, project_id,
         status=status, path=path, snippet_id=snippet_id,
         include_vanished=include_vanished, limit=limit, offset=offset,
-        proposal=proposal,
+        proposal=proposal, flag=flag,
     )
     return {"shapes": [r.to_dict() for r in rows], "total": total}
 
 
+async def shape_history(
+    project_id: int, path: str, symbol: str = "", limit: int = 200
+) -> dict:
+    """What was used here, when, and why — a shape's (or a directory's)
+    history from the ledger (#2793).
+
+    `shapes` are the current rows at `path` (a file, or a directory and
+    everything beneath it; `symbol` narrows to one definition) with
+    first/last-seen commits, vanished_at, and the standing judgment;
+    `events` are the state changes, oldest first: `classified` (status,
+    snippet_id, who, why — one per judgment, so a shape that was an instance
+    of #N and later a variant of #M shows both), `vanished`, `reappeared`,
+    `drifted` (the body moved under a judgment; see list_shapes flag=
+    "recheck"). Each event carries the commit the tree was read at.
+
+    Read it as a timeline: "instance of #N from <first classified at>,
+    re-judged variant of #M at <at> because <reason>, vanished at <commit>".
+    Read-only; requires read access to the project.
+    """
+    uid = current_user_id()
+    return await shape_ledger_svc.shape_history(
+        uid, project_id, path, symbol=symbol, limit=limit
+    )
+
+
 async def confirm_shape_proposals(
     project_id: int,
     snippet_id: int = 0,
@@ -184,6 +218,6 @@ async def refresh_pattern_coverage(project_id: int) -> dict:
 def register(mcp) -> None:
     for fn in (
         classify_shapes, list_shapes, refresh_pattern_coverage,
-        confirm_shape_proposals,
+        confirm_shape_proposals, shape_history,
     ):
         mcp.tool(name=fn.__name__)(fn)