feat(write-path): the derive arm — the hint names a duplicate family (no canon) or a canon elsewhere for the shapes being written; exclude_derive channel (#2900, milestone 299 step 2)

shape_ledger.write_time_derive asks the ledger what it knows about each
named (kind, symbol): a derive-grouped family (identical body / same name
in N other files) -> "derive it now, do not add a copy"; a canonical row
at another path -> "canon #N at <path>, reuse". Judged rows at the path and
the canon own file stay silent. Rendered by _derive_line beside the
divergence line; keyed (group id / canon:<id>) on a third per-session dedup
channel in the hook (.derive.ids -> exclude_derive=).

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

src/scribe/routes/plugin.py

@@ -129,6 +129,10 @@ async def write_path_prior_art():
                              surfaced. A separate channel on purpose: a reuse
                              hint shown early must not suppress the record-sync
                              nudge when the recorded file is edited later.
+        exclude_derive (opt) — comma-separated derive keys (a derive group id
+                             or `canon:<snippet_id>`) already named this
+                             session by the ledger arm (#2900); its own
+                             channel, like the two above.
         shapes (opt)       — comma-separated `kind:name` definitions the hook
                              found in (or enclosing) the payload, kind being
                              css|sym. The shape ledger's write-path feed
@@ -144,6 +148,9 @@ async def write_path_prior_art():
     project_id, repo, _unbound = await _project_scope()
     exclude_ids = _int_list(request.args.get("exclude_ids"))
     exclude_sync_ids = _int_list(request.args.get("exclude_sync_ids"))
+    exclude_derive = [
+        p.strip() for p in (request.args.get("exclude_derive") or "").split(",") if p.strip()
+    ]
     shapes = _parse_shapes(request.args.get("shapes") or "")
     api_key = getattr(g, "api_key", None)
     may_stamp = api_key is None or getattr(api_key, "scope", "") == "write"
@@ -153,6 +160,7 @@ async def write_path_prior_art():
         exclude_ids=exclude_ids, exclude_sync_ids=exclude_sync_ids,
         stamp_shapes=shapes if may_stamp else None,
         repo_key=repo_bindings_svc.normalize_repo_key(repo) if repo else "",
+        exclude_derive=exclude_derive,
     )
     return jsonify(result)
 

src/scribe/services/plugin_context.py

@@ -706,6 +706,7 @@ async def build_write_path_hint(
     exclude_sync_ids: list[int] | None = None,
     stamp_shapes: list[tuple[str, str]] | None = None,
     repo_key: str = "",
+    exclude_derive: list[str] | None = None,
 ) -> dict:
     """Prior-art hint for the plugin's PreToolUse hook on Write/Edit.
 
@@ -765,7 +766,7 @@ async def build_write_path_hint(
     """
     cfg = await get_writepath_config(user_id)
     empty = {"context": "", "note_ids": [], "sync_note_ids": [], "config": cfg,
-             "stamped": [], "divergence": []}
+             "stamped": [], "divergence": [], "derive": [], "derive_keys": []}
     path = (path or "").strip()
     if not cfg["enabled"] or not path:
         return empty
@@ -935,7 +936,20 @@ async def build_write_path_hint(
             )
         except Exception:
             logger.warning("write-time divergence check failed", exc_info=True)
-    if not synced and not menu and not stamped and not divergence:
+    # The in-band DERIVE check (#2900): the ledger's own knowledge of the
+    # names being written — a duplicate family with no canon, or a canon
+    # recorded elsewhere. This is the arm the by-name local grep could not
+    # be: it knows whether the other copies are canon or stray. Keyed per
+    # session (`exclude_derive`) so a family is named once, not per edit.
+    derive: list[dict] = []
+    if stamp_shapes and project_id:
+        try:
+            found = await shape_ledger_svc.write_time_derive(project_id, path, stamp_shapes)
+            skip = set(exclude_derive or [])
+            derive = [d for d in found if d.get("key") not in skip]
+        except Exception:
+            logger.warning("write-time derive check failed", exc_info=True)
+    if not synced and not menu and not stamped and not divergence and not derive:
         return empty
 
     owners = await owner_names_for({
@@ -1003,6 +1017,8 @@ async def build_write_path_hint(
         lines.append(_stamp_line(path, stamped))
     if divergence:
         lines.append(_divergence_line(path, divergence))
+    if derive:
+        lines.append(_derive_line(path, derive))
 
     # 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
@@ -1027,9 +1043,40 @@ async def build_write_path_hint(
         "config": cfg,
         "stamped": stamped,
         "divergence": divergence,
+        "derive": derive,
+        "derive_keys": [d["key"] for d in derive],
     }
 
 
+def _derive_line(path: str, derive: list[dict]) -> str:
+    """The ledger's word on the names being written (#2900): a duplicate
+    family to derive, or a canon to reuse — said at the write."""
+    parts = []
+    for d in derive:
+        if d.get("canon"):
+            c = d["canon"]
+            parts.append(
+                f"`{c['label']}` is canon — snippet #{c['snippet_id']} at `{c['path']}`; "
+                "pull it and reuse, don't redefine"
+            )
+            continue
+        f = d["family"]
+        how = "identical body" if f.get("identical") else "same name defined"
+        files = ", ".join(f"`{x}`" for x in f.get("files") or [])
+        more = f.get("file_count", 0) - len(f.get("files") or [])
+        if more > 0:
+            files += f" +{more} more"
+        parts.append(
+            f"`{f['label']}` is a duplicate family with no canon — {how} in "
+            f"{f.get('file_count', 0)} other file(s): {files}; derive it now: "
+            "record the canon (create_snippet) and make the copies instances "
+            "(classify_shapes) — or, if these are convention not copies, "
+            "`classify_shapes(..., status=\"exempt\", reason_code=\"convention-plumbing\")` "
+            "dismisses the family — rather than adding another copy"
+        )
+    return f"> Shape ledger at `{path}`: " + "; ".join(parts) + "."
+
+
 def _divergence_line(path: str, divergence: list[dict]) -> str:
     """Button B where button A is canon — named at the write (#2793)."""
     parts = [

src/scribe/services/shape_ledger.py

@@ -1594,6 +1594,75 @@ async def write_time_divergence(
     return out
 
 
+# How many other files a family line names before "…" — enough to go look,
+# not a wall.
+_DERIVE_FILES_SHOWN = 4
+
+
+async def write_time_derive(
+    project_id: int, path: str, shapes: list[tuple[str, str]]
+) -> list[dict]:
+    """The in-band DERIVE check (#2900): for each (kind, name) the hook
+    named at ``path``, what the ledger already knows about that name
+    elsewhere in the project —
+
+      family  the name sits in a derive-first group (identical body in N
+              files, or the same name in ≥3): "this is a known duplicate
+              family with no canon — derive it now, don't add a copy";
+      canon   a `canonical` row of that name at another path: "this is
+              canon #N at <path> — reuse, don't redefine".
+
+    Only for shapes not yet judged at ``path`` (a judged shape is not
+    re-litigated at every edit), never for the canon's own file. Returns
+    [{symbol, kind, key, family?|canon?}] — `key` is the dedup token the
+    hook keeps per session (the group id, or canon:<snippet_id>)."""
+    wanted = {(k, _norm_symbol(n)): n for k, n in shapes if n}
+    if not wanted:
+        return []
+    async with async_session() as session:
+        rows = (
+            await session.execute(
+                select(CodeShape).where(
+                    CodeShape.project_id == project_id,
+                    CodeShape.vanished_at.is_(None),
+                    CodeShape.symbol.in_({norm for (_k, norm) in wanted}),
+                )
+            )
+        ).scalars().all()
+    out: list[dict] = []
+    for (kind, norm), name in wanted.items():
+        same = [r for r in rows if r.kind == kind and _norm_symbol(r.symbol) == norm]
+        here = next((r for r in same if r.path == path), None)
+        if here is not None and here.status not in _MECHANICAL_TODO:
+            continue  # judged here (or this IS the canon): nothing to say
+        others = [r for r in same if r.path != path]
+        label = ("." if kind == "css" else "") + name
+        canon = next((r for r in others if r.status == "canonical" and r.snippet_id), None)
+        if canon is not None:
+            out.append({"symbol": name, "kind": kind, "key": f"canon:{canon.snippet_id}",
+                        "canon": {"snippet_id": canon.snippet_id, "path": canon.path,
+                                  "label": label}})
+            continue
+        grouped = [r for r in others if r.proposal_group and r.status in _MECHANICAL_TODO]
+        if here is not None and here.proposal_group:
+            grouped = [r for r in grouped if r.proposal_group == here.proposal_group] or grouped
+        if not grouped:
+            continue
+        group = grouped[0].proposal_group
+        members = [r for r in grouped if r.proposal_group == group]
+        files = sorted({r.path for r in members})
+        out.append({
+            "symbol": name, "kind": kind, "key": group,
+            "family": {
+                "group": group, "label": label,
+                "identical": not group.startswith("name:"),
+                "files": files[:_DERIVE_FILES_SHOWN], "file_count": len(files),
+                "size": len(members) + (1 if here is not None else 0),
+            },
+        })
+    return out
+
+
 async def flag_divergence(project_id: int, *, since: datetime | None) -> int:
     """Flag shapes created after ``since`` (the previous refresh) that sit
     where a canon dominates and were not proposed as that canon. With no