feat(ledger): write-path stamping — a pulled canon the session then instantiates lands as a hook instance row (#2791, milestone 294 step 5)

The prior-art hook now names the shapes being written (shapes=kind:name —
every definition in the payload, or the one enclosing an Edit found by
walking the file upward) and the server stamps them as instance rows when
the session PULLED a snippet inside PULL_WINDOW that the payload references
by symbol or that the semantic arm scored for this very payload.
classified_by=hook, evidence in reason; never overrides a judgment or a
canonical row, overridable by classify_shapes. Offered-but-unopened stamps
nothing. Pulled-and-already-seen snippets stay in the semantic query as
evidence without re-entering the deduped menu. A brand-new shape gets a
provisional row the next sync confirms or vanishes. Read-scoped keys get
the hint, never the stamp. Plugin 0.1.34.

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

src/scribe/services/plugin_context.py

@@ -27,6 +27,7 @@ from scribe.services import knowledge as knowledge_svc
 from scribe.services import notes as notes_svc
 from scribe.services import projects as projects_svc
 from scribe.services import rulebooks as rulebooks_svc
+from scribe.services import shape_ledger as shape_ledger_svc
 from scribe.services import snippets as snippets_svc
 from scribe.services.access import label_shared_items, owner_names_for
 from scribe.services.embeddings import semantic_search_notes
@@ -703,6 +704,8 @@ async def build_write_path_hint(
     project_id: int = 0,
     exclude_ids: list[int] | None = None,
     exclude_sync_ids: list[int] | None = None,
+    stamp_shapes: list[tuple[str, str]] | None = None,
+    repo_key: str = "",
 ) -> dict:
     """Prior-art hint for the plugin's PreToolUse hook on Write/Edit.
 
@@ -749,9 +752,20 @@ async def build_write_path_hint(
     un-scored surfacing now has its own home: every arm emits note_usage_events,
     tagged 'write_path_sync' vs 'write_path_place' vs 'write_path_semantic', so
     each claim's pull-through rate is measurable on its own.
+
+    ``stamp_shapes`` turns the same request into the ledger's write-path feed
+    (#2791): the (kind, name) definitions the hook saw in — or enclosing —
+    the payload. When the session has PULLED a snippet recently and this
+    payload references or resembles it, those shapes land as `instance` rows
+    (classified_by=hook, see shape_ledger.stamp_write_path_instances) and
+    the result's ``stamped`` lists them. The route passes it only for a
+    caller allowed to write — a read-scoped key gets the hint, never the
+    stamp. ``repo_key`` (the hook's remote, normalised) homes a provisional
+    row for a shape the ledger has not synced yet.
     """
     cfg = await get_writepath_config(user_id)
-    empty = {"context": "", "note_ids": [], "sync_note_ids": [], "config": cfg}
+    empty = {"context": "", "note_ids": [], "sync_note_ids": [], "config": cfg,
+             "stamped": []}
     path = (path or "").strip()
     if not cfg["enabled"] or not path:
         return empty
@@ -800,6 +814,15 @@ async def build_write_path_hint(
         seen.add(nid)
         placed.append(("nearby", item))
 
+    # The stamping feed's "actually pulled it" half (#2791). Read once, before
+    # the semantic arm, because the arm's query doubles as the resemblance
+    # test: a pulled snippet this session already saw (so it sits in `seen`)
+    # must still be SCORED for this payload — it just isn't re-listed.
+    pulled: dict = {}
+    if stamp_shapes:
+        pulled = await shape_ledger_svc.recent_pulls(user_id)
+    resembles: dict[int, float] = {}
+
     # --- arm 2: by meaning ---
     scored: list[tuple[str, dict]] = []
     remaining = top_k - len(synced) - len(placed)
@@ -821,12 +844,15 @@ async def build_write_path_hint(
         query = concept_query(query) or query
     if remaining > 0 and query:
         t0 = time.perf_counter()
+        # Pulled-and-seen ids stay in the query (as evidence) but never in
+        # the menu — the dedup contract holds, the resemblance still lands.
+        pulled_seen = seen & set(pulled)
         hits = await semantic_search_notes(
             user_id, query,
-            limit=remaining,
+            limit=remaining + len(pulled_seen),
             threshold=cfg["threshold"],
             project_id=scope_project,
-            exclude_ids=seen,
+            exclude_ids=seen - pulled_seen,
             # Snippets AND recorded experience (#2246). This arm was
             # snippets-only, which is auto-inject's mistake inverted: an issue
             # saying "we tried this and it deadlocked", or a dev-log recording
@@ -845,6 +871,11 @@ async def build_write_path_hint(
             # the browse scope and never surfaces a one-to-one direct share.
             scope="browse",
         )
+        resembles = {
+            int(note.id): float(score) for score, note in hits
+            if int(note.id) in pulled
+        }
+        hits = [(s, n) for s, n in hits if int(n.id) not in seen][:remaining]
         record_retrieval(
             user_id=user_id, source="write_path", query=query,
             threshold=cfg["threshold"], limit=remaining,
@@ -879,7 +910,20 @@ async def build_write_path_hint(
                 ))
 
     menu = (placed + scored)[:max(0, top_k - len(synced))]
-    if not synced and not menu:
+
+    # The stamp runs whether or not anything is rendered — after dedup, the
+    # common case is a silent hint and a pulled canon being instantiated.
+    stamped: list[dict] = []
+    if stamp_shapes and pulled:
+        try:
+            stamped = await shape_ledger_svc.stamp_write_path_instances(
+                user_id, project_id, path=path, shapes=stamp_shapes,
+                code=code or "", pulled=pulled, resembles=resembles,
+                repo_key=repo_key,
+            )
+        except Exception:
+            logger.warning("Write-path ledger stamping failed", exc_info=True)
+    if not synced and not menu and not stamped:
         return empty
 
     owners = await owner_names_for({
@@ -943,6 +987,9 @@ async def build_write_path_hint(
         note_ids.append(int(item["id"]))
         lines.append(_prior_art_line(item, marker, owner, foreign_lang))
 
+    if stamped:
+        lines.append(_stamp_line(path, stamped))
+
     # Split by arm, which is the whole reason this table exists. The place arm
     # carries no score and so has no home in retrieval_logs; before #2085 a
     # snippet surfaced BY PLACE left no trace anywhere, making the arm that
@@ -964,9 +1011,29 @@ async def build_write_path_hint(
         "note_ids": note_ids,
         "sync_note_ids": sync_note_ids,
         "config": cfg,
+        "stamped": stamped,
     }
 
 
+def _stamp_line(path: str, stamped: list[dict]) -> str:
+    """One line saying what the ledger just recorded, so the session can
+    correct a wrong stamp in the moment rather than an audit finding it."""
+    by_snippet: dict[int, list[str]] = {}
+    for row in stamped:
+        label = f".{row['symbol']}" if row["kind"] == "css" else row["symbol"]
+        by_snippet.setdefault(int(row["snippet_id"]), []).append(f"`{label}`")
+    parts = [
+        f"{', '.join(names)} → instance of #{sid}"
+        for sid, names in by_snippet.items()
+    ]
+    return (
+        f"> Shape accounting: recorded at `{path}` — {'; '.join(parts)} "
+        "(classified_by=hook: you pulled that snippet this session and this "
+        "code references/resembles it). Not an instance? `classify_shapes` "
+        "overrides a hook stamp."
+    )
+
+
 async def _topic_titles(topic_ids: set[int]) -> dict[int, str]:
     """Map topic_id -> title for the given ids (live topics only)."""
     if not topic_ids: