feat(ledger): mechanical proposer — every refresh proposes instances against canon and groups derive-first candidates; agents confirm in batches (#2792, milestone 294 step 6)

Shapes now carry a content fingerprint (signature + whitespace/comment-
insensitive body_sha; migration 0080) and the proposer runs inside the
coverage refresh, the one moment bodies exist: symbol elsewhere → textual
containment → body references the canon → signature resemblance → semantic
(capped per refresh, unreached rows stay unexamined for the next). A hit is
a proposal on the row (proposed_snippet_id/basis/score), never a
classification; rows with no canon hit group by the derive-first rule
(identical body in ≥2 places, same name in ≥3 files) as proposal_basis=
derive + a group key. list_shapes(proposal=any|canon|derive|<basis>) is the
queue; confirm_shape_proposals(project_id, snippet_id|path|basis) confirms
in batches as agent instances; any classify_shapes/hook stamp retires the
proposal. Readout carries proposed + derive_groups (line, payload, card).
Plugin 0.1.35 (skill: the machine proposes, judgment classifies).

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

src/scribe/mcp/tools/shapes.py

@@ -62,6 +62,7 @@ async def list_shapes(
     include_vanished: bool = False,
     limit: int = 100,
     offset: int = 0,
+    proposal: str = "",
 ) -> dict:
     """Read a project's shape ledger — `status="unclassified"` IS the todo.
 
@@ -75,6 +76,11 @@ async def list_shapes(
         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).
+        proposal: the proposer's queue (#2792) — "any", "canon" (rows the
+            machine thinks are an instance of a snippet: `proposal` carries
+            snippet_id, basis, score), "derive" (rows that repeat with NO
+            canon: `proposal.group` names the family), or one basis
+            (symbol/text/reference/signature/semantic).
 
     Returns {"shapes": [...], "total": N} — total counts every match, not
     just this page. Each row's `classified_by` says who judged: agent /
@@ -84,20 +90,61 @@ async def list_shapes(
     was stamped an instance with the evidence in `reason`. A hook row is
     overridable by any classify_shapes call; it never overrides yours.
 
-    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.
+    THE FAST PATH through a big todo is the proposer's queue: every coverage
+    refresh matches unclassified shapes against canon (strongest basis
+    first: same symbol elsewhere → textual containment → body references
+    the canon → signature resemblance → semantic) and attaches a
+    `proposal` to each row it can speak for. Review `proposal="canon"` by
+    snippet or directory, then confirm_shape_proposals the ones that hold —
+    hundreds at a time — and classify_shapes the rest (variant/exempt, or
+    instance of a different snippet). `proposal="derive"` lists the
+    derive-first candidates: a repeating shape with NO recorded canon is
+    never N loose classifications — consolidate onto a reference,
+    create_snippet it, then classify the group against it.
     """
     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,
+        proposal=proposal,
     )
     return {"shapes": [r.to_dict() for r in rows], "total": total}
 
 
+async def confirm_shape_proposals(
+    project_id: int,
+    snippet_id: int = 0,
+    path: str = "",
+    basis: str = "",
+    min_score: float = 0.0,
+) -> dict:
+    """Confirm the proposer's canon proposals you have reviewed, in batch.
+
+    The machine proposes, judgment classifies (#2792): each matching row —
+    live, unclassified, carrying a `proposal` with a snippet_id — becomes
+    `instance` of that snippet, classified_by="agent", reason naming the
+    basis and score. Narrow to what you actually looked at: at least one of
+    snippet_id (confirm one canon's whole queue after reading its
+    `list_shapes(proposal="canon", ...)` page), path (a directory you
+    audited), or basis (e.g. "symbol" and "reference" are near-certain;
+    "semantic" deserves a look first) is required — a bare confirm-all is
+    not a judgment. min_score trims a basis's tail.
+
+    Proposals you do NOT confirm are judged with classify_shapes (variant,
+    exempt, or instance of a different snippet) — any judgment retires the
+    proposal. Requires write access. Returns {"confirmed": N}.
+    """
+    uid = current_user_id()
+    try:
+        return await shape_ledger_svc.confirm_proposals(
+            uid, project_id, snippet_id=snippet_id, path=path, basis=basis,
+            min_score=min_score,
+        )
+    except ValueError as exc:
+        return {"error": str(exc)}
+
+
 async def refresh_pattern_coverage(project_id: int) -> dict:
     """Seed or refresh the project's shape ledger NOW, and return the readout.
 
@@ -114,9 +161,17 @@ async def refresh_pattern_coverage(project_id: int) -> dict:
     owner adds one (Settings → Integrations → Git Forges); no served repo →
     bind_repo on a host a connection serves.
 
+    The refresh is also when the mechanical proposer runs (#2792): with the
+    repo bodies in hand it matches every changed unclassified shape against
+    canon and records proposals (see list_shapes proposal=), then regroups
+    the derive-first candidates. Semantic matching is capped per refresh, so
+    a large ledger's queue grows across refreshes rather than in one.
+
     Returns the accounting payload — total, accounted, counts by status,
-    unclassified, repos, largest_gaps — plus `pattern_coverage`, the same
-    one-line summary enter_project carries.
+    unclassified, repos, largest_gaps, `proposed` (canon proposals awaiting
+    confirmation), `derive_groups` (the biggest repeats-with-no-canon
+    families), `proposer` (what this refresh examined) — plus
+    `pattern_coverage`, the same one-line summary enter_project carries.
     """
     uid = current_user_id()
     coverage = await coverage_svc.refresh_for_caller(uid, project_id)
@@ -127,5 +182,8 @@ async def refresh_pattern_coverage(project_id: int) -> dict:
 
 
 def register(mcp) -> None:
-    for fn in (classify_shapes, list_shapes, refresh_pattern_coverage):
+    for fn in (
+        classify_shapes, list_shapes, refresh_pattern_coverage,
+        confirm_shape_proposals,
+    ):
         mcp.tool(name=fn.__name__)(fn)