feat(ledger): classify_shapes + list_shapes MCP tools; get_snippet carries the consumer map (#2789, milestone 294 step 3)

The judgment write path. classify_shapes applies a batch of classifications
to a project's live ledger rows — all-or-nothing (#2709's lesson: the whole
batch is validated, write-ACL'd, and every snippet target proven readable
before any row is touched); rows match by exact (path, symbol), kind narrows,
and shapes no live row matches come back as 'unmatched' rather than errors.
variant/exempt REQUIRE the reason — the why is the record (note 2786) — and
'unclassified' deliberately withdraws a judgment back to the todo. The 'via'
channel is caller-restricted to agent|audit|import; hook and mechanical stay
server-internal so a caller can't launder judgment as machinery.

list_shapes is the todo query (status=unclassified) with composable filters:
path is exact-or-under like recorded locations, snippet_id reads a consumer
map, include_vanished reads history; paged with the true total.

get_snippet now attaches  and  — the structured consumer
map, filtered to projects the CALLER can read so a shared snippet never side-
channels another project's file layout; attached only when non-empty (#2483).

Integration tests pin the batch atomicity, ACL gates, filter composition, the
consumer map on the MCP pull, and the SET NULL companion: a judgment whose
snippet was purged rejoins the todo on the next sync.

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

src/scribe/mcp/tools/__init__.py

@@ -5,8 +5,8 @@ to a FastMCP instance. `register_all(mcp)` is the single entry point called
 from `mcp.server.build_mcp_server`.
 """
 from scribe.mcp.tools import (
-    design_systems, milestones, notes, processes, projects, recent, repos, rulebooks, search, snippets,
-    systems, tags, tasks, trash,
+    design_systems, milestones, notes, processes, projects, recent, repos, rulebooks, search, shapes,
+    snippets, systems, tags, tasks, trash,
 )
 
 
@@ -24,5 +24,6 @@ def register_all(mcp) -> None:
     repos.register(mcp)
     processes.register(mcp)
     snippets.register(mcp)
+    shapes.register(mcp)
     rulebooks.register(mcp)
     trash.register(mcp)

src/scribe/mcp/tools/shapes.py

@@ -0,0 +1,95 @@
+"""Shape-ledger MCP tools — the classification write/read surface (#2789).
+
+The accounting model (note 2786): the snippet library records CANON (small);
+the ledger accounts for EVERY extracted shape (total). These tools are how
+agents move shapes out of `unclassified` — the todo state — and how they read
+what still needs judgment. The ledger rows themselves are fed by the coverage
+refresh; these tools only ever judge what the sync has seen.
+"""
+from __future__ import annotations
+
+from scribe.mcp._context import current_user_id
+from scribe.services import shape_ledger as shape_ledger_svc
+
+
+async def classify_shapes(
+    project_id: int, classifications: list[dict], via: str = "agent"
+) -> dict:
+    """Record judgments for a project's code shapes — in batch, as rows.
+
+    EVERY shape in a bound repo should end up classified (note 2786):
+      - `instance` of snippet N — it conforms to recorded canon (family-level
+        canon in another project counts; that fully accounts for the shape).
+      - `variant` of snippet N — a deliberate, named departure. `reason`
+        (the why) is REQUIRED; it is the record.
+      - `exempt` — judged genuinely one-off. `reason` REQUIRED.
+      - `canonical` of snippet N — this row IS the snippet's reference
+        (rarely set by hand; the coverage sync stamps these mechanically).
+      - `unclassified` — withdraw a judgment; the shape rejoins the todo.
+
+    Consumer maps belong HERE, not in prose: when an audit enumerates call
+    sites of a canonical helper, each call site's defining shape is an
+    `instance` row — a sentence in a verification detail cannot be sorted,
+    queried, or diffed.
+
+    Args:
+        project_id: The project whose ledger is being judged.
+        classifications: Objects of {path, symbol, status, kind?, snippet_id?,
+            reason?}. path+symbol name the shape exactly as list_shapes shows
+            it; kind ("sym"/"css") narrows when one file defines both.
+            snippet_id is required for canonical/instance/variant; reason is
+            required for variant/exempt.
+        via: Who is judging — "agent" (default), "audit" (a sweep), or
+            "import" (carrying maps recorded elsewhere).
+
+    All-or-nothing: a structural error, a missing snippet target, or no write
+    access applies NOTHING. Returns {"classified": N, "unmatched": [...]} —
+    unmatched names shapes no live ledger row matches (the tree may have
+    moved since you listed; re-run the project's coverage refresh to re-sync).
+    """
+    uid = current_user_id()
+    return await shape_ledger_svc.classify_shapes(
+        uid, project_id, classifications, via=via
+    )
+
+
+async def list_shapes(
+    project_id: int,
+    status: str = "",
+    path: str = "",
+    snippet_id: int = 0,
+    include_vanished: bool = False,
+    limit: int = 100,
+    offset: int = 0,
+) -> dict:
+    """Read a project's shape ledger — `status="unclassified"` IS the todo.
+
+    Every extracted definition in the project's bound repos has a row here
+    (fed by the coverage refresh). Filters compose:
+
+    Args:
+        status: canonical | instance | variant | exempt | unclassified.
+        path: exact file, or a directory — matches everything beneath it
+            (the coverage line's "largest" dirs go straight in here).
+        snippet_id: rows classified against this snippet — a consumer map.
+        include_vanished: include shapes no longer in the tree (history).
+        limit/offset: page through big ledgers (limit caps at 500).
+
+    Returns {"shapes": [...], "total": N} — total counts every match, not
+    just this page. Classify what you can judge with classify_shapes; a
+    repeating shape with NO recorded canon is a derive-one-first moment
+    (consolidate onto a reference, create_snippet it, then classify the
+    rest against it), never N loose classifications.
+    """
+    uid = current_user_id()
+    rows, total = await shape_ledger_svc.list_project_shapes(
+        uid, project_id,
+        status=status, path=path, snippet_id=snippet_id,
+        include_vanished=include_vanished, limit=limit, offset=offset,
+    )
+    return {"shapes": [r.to_dict() for r in rows], "total": total}
+
+
+def register(mcp) -> None:
+    for fn in (classify_shapes, list_shapes):
+        mcp.tool(name=fn.__name__)(fn)

src/scribe/mcp/tools/snippets.py

@@ -207,6 +207,12 @@ async def get_snippet(snippet_id: int) -> dict:
     the source moved on — trust the location over the cached body and
     consider verify_snippet after you look.
 
+    When the shape ledger has judgments against this snippet, the response
+    carries `instances` (shapes classified as conforming to it — the
+    structured consumer map) and/or `variants` (named departures, each with
+    its why). Consult them before changing the snippet's contract: they are
+    the call sites your change lands on (classify_shapes maintains them).
+
     If the record belongs to someone else it carries `shared: true` with the
     `owner` and your `permission`. Read that as ONE PERSON'S SUGGESTION, not as
     established practice here: judge it on its merits, say whose it is when you
@@ -229,6 +235,16 @@ async def get_snippet(snippet_id: int) -> dict:
     await systems_tools.attach_systems(
         uid, note.user_id, data, note.id, note.project_id
     )
+    # The structured consumer map (#2789): ledger rows judged against this
+    # snippet. Attached only when non-empty (#2483) — and never for projects
+    # the caller can't read.
+    from scribe.services import shape_ledger as shape_ledger_svc
+
+    consumers = await shape_ledger_svc.snippet_consumers(uid, int(note.id))
+    if consumers["instances"]:
+        data["instances"] = consumers["instances"]
+    if consumers["variants"]:
+        data["variants"] = consumers["variants"]
     return data