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/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