feat(ledger): the consumer map surfaces — every css row carries used_by on list_shapes, flag="unused-css" (the map's negative space, surfaced never deleted), derive groups and the write-path family carry consumers, the derive line says "used by N template(s)", coverage payload unused_css + the standing block; docs, SKILL, plugin 0.1.44; the two step-2 tests expected 5 edges where fan-out makes 6 (milestone 302 step 3, #2936)

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

tests/test_integration_shape_classify.py

@@ -703,11 +703,13 @@ async def test_consumer_map_syncs_edges_from_template_references(seeded):
         "v/B.vue": {"error-msg": 1},
         "v/C.vue": {"error-msg": 1, "btn-primary": 4},
     }
-    assert await sync_repo_consumers(pid, REPO, refs) == 5
+    # A and B consume their OWN error-msg; C defines none, so its use fans
+    # out to both rows; btn-primary resolves to the shared sheet from A and C.
+    assert await sync_repo_consumers(pid, REPO, refs) == 6
     rows = {(r.path, r.symbol): r.id for r in await live_rows(pid) if r.kind == "css"}
     edges = await consumers_of(rows.values())
     view = {(p, s): [(e.path, e.count) for e in edges.get(i, [])] for (p, s), i in rows.items()}
-    assert view[("v/A.vue", "error-msg")] == [("v/A.vue", 2)]
+    assert view[("v/A.vue", "error-msg")] == [("v/A.vue", 2), ("v/C.vue", 1)]
     assert view[("v/B.vue", "error-msg")] == [("v/B.vue", 1), ("v/C.vue", 1)]
     assert view[("assets/components.css", "btn-primary")] == [("v/A.vue", 1), ("v/C.vue", 4)]
     assert view[("web/button.css", "btn")] == []            # the seeded row: no template names it
@@ -719,6 +721,22 @@ async def test_consumer_map_syncs_edges_from_template_references(seeded):
     assert [(e.path, e.count) for e in edges[rows[("v/B.vue", "error-msg")]]] == [("v/B.vue", 1)]
     assert [(e.path, e.count) for e in edges[rows[("assets/components.css", "btn-primary")]]] == [("v/A.vue", 2)]
 
+    # The readout side: used_by per css row, the unused-css flag, and the
+    # family's consumers on the write-path check.
+    from scribe.services.shape_ledger import (
+        apply_derive_groups, used_by_map, write_time_derive,
+    )
+    owner = seeded["owner"]
+    live = [r for r in await live_rows(pid) if r.kind == "css"]
+    used = await used_by_map(live)
+    assert used[rows[("v/B.vue", "error-msg")]] == {"count": 1, "paths": ["v/B.vue"]}
+    assert used[rows[("web/button.css", "btn")]] == {"count": 0, "paths": []}
+    unused, n = await list_project_shapes(owner, pid, flag="unused-css")
+    assert n == 1 and [(r.path, r.symbol) for r in unused] == [("web/button.css", "btn")]
+    await apply_derive_groups(pid)
+    out = await write_time_derive(pid, "v/New.vue", [("css", "error-msg")])
+    assert out and out[0]["family"]["consumers"] == {"count": 2, "paths": ["v/A.vue", "v/B.vue"]}
+
     # B's rule vanishes from the tree → its edges go with the pass.
     await sync_repo_shapes(pid, REPO, [d for d in defs if d[0] != "v/B.vue"], seen_marker="m2")
     await sync_repo_consumers(pid, REPO, refs2)

tests/test_pattern_coverage.py

@@ -604,6 +604,17 @@ def test_coverage_line_names_the_proposers_standing():
     assert "; 90 unclassified (40 proposed, 2 derive groups), largest: src" in line
     line = coverage_line({**base, "proposed": 0, "derive_groups": [{"group": "a"}]})
     assert "(1 derive group)" in line
+    # Milestone 302: a css top copy says what renders it; unused classes
+    # join the standing block only when measured (None = no evidence).
+    line = coverage_line({**base, "unclassified": 0, "proposed": 0, "derive_groups": [
+        {"group": "name:css:error-msg", "label": ".error-msg", "files": 6,
+         "consumers": {"count": 6, "paths": ["a.vue"]}}], "unused_css": 3})
+    assert "top copy .error-msg ×6 files · used by 6 templates" in line
+    assert "3 unused classes" in line
+    line = coverage_line({**base, "unclassified": 0, "proposed": 0, "derive_groups": [
+        {"group": "name:css:x", "label": ".x", "files": 2,
+         "consumers": {"count": 1, "paths": ["a.vue"]}}], "unused_css": None})
+    assert "top copy .x ×2 files · used by 1 template" in line and "unused" not in line
     # #2874: the next action on the line — biggest canon queue, widest copy.
     line = coverage_line({
         **base, "proposed": 40, "top_canon": {"snippet_id": 2844, "count": 78},

tests/test_shape_ledger.py

@@ -380,6 +380,17 @@ def test_proposal_summary_ranks_body_identical_groups_first_and_sees_scoped_rows
         row("v/J.vue", "closed-msg", "dup:abc", status="exempt"),
     ]
     out = proposal_summary(rows)
+    # Milestone 302: with consumer paths in hand, each css group says what
+    # renders it — distinct files across the members; absent otherwise.
+    assert "consumers" not in out["derive_groups"][0]
+    for i, r in enumerate(rows):      # unsaved rows have no id; give them one
+        r.id = i + 1
+    cpaths = {rows[0].id: ["v/0.vue", "v/Z.vue"], rows[1].id: ["v/1.vue"], rows[2].id: ["v/0.vue"]}
+    with_c = proposal_summary(rows, consumer_paths=cpaths)
+    badge = next(g for g in with_c["derive_groups"] if g["group"] == "name:css:status-badge")
+    assert badge["consumers"] == {"count": 3, "paths": ["v/0.vue", "v/1.vue", "v/Z.vue"]}
+    dup = next(g for g in with_c["derive_groups"] if g["group"] == "dup:abc")
+    assert dup["consumers"] == {"count": 0, "paths": []}
     assert [g["group"] for g in out["derive_groups"]] == ["dup:abc", "dup:def", "name:css:status-badge"]
     assert out["derive_groups"][0]["files"] == 3 and out["derive_groups"][0]["size"] == 3
     assert out["derive_groups"][0]["label"] == "closed-msg (identical body)"
@@ -455,7 +466,7 @@ def test_resolve_consumers_prefers_the_own_file_and_fans_out_for_shared_names():
         (1, "v/A.vue"): 2,            # own row, not B's
         (3, "v/A.vue"): 1,            # the shared sheet
         (2, "v/B.vue"): 1,            # own row
-        (2, "v/C.vue"): 1,            # C defines nothing → the other file's row
+        (1, "v/C.vue"): 1, (2, "v/C.vue"): 1,   # C defines none → every other definition
         (4, "v/C.vue"): 3, (5, "v/C.vue"): 3,   # ambiguous: both, not a guess
     }
     # Unknown tokens and an unreferenced row leave no trace.

tests/test_write_path_trigger.py

@@ -1306,7 +1306,8 @@ async def test_the_write_time_derive_check_names_a_family_or_a_canon_in_band():
         {"symbol": "log-empty", "kind": "css", "key": "name:css:log-empty",
          "family": {"group": "name:css:log-empty", "label": ".log-empty", "identical": False,
                     "files": ["a/TaskLogSection.vue", "a/WorkspaceTaskPanel.vue"],
-                    "file_count": 5, "size": 6}},
+                    "file_count": 5, "size": 6,
+                    "consumers": {"count": 6, "paths": ["a/TaskLogSection.vue", "a/V.vue"]}}},
         {"symbol": "btn-primary", "kind": "css", "key": "canon:2855",
          "canon": {"snippet_id": 2855, "path": "frontend/src/assets/components.css",
                    "label": ".btn-primary"}},
@@ -1344,8 +1345,10 @@ async def test_the_write_time_derive_check_names_a_family_or_a_canon_in_band():
     assert "Shape ledger at `frontend/src/components/New.vue`" in ctx
     # A CSS family is a repeated NAME (note 2917) and its dismissal is scoped-css;
     # a code dup family is an identical body and dismisses as convention-plumbing.
+    # A css family says what renders it (milestone 302) before the ask.
     assert "`.log-empty` is a repeated name with no canon — defined in 5 other file(s): " \
-           "`a/TaskLogSection.vue`, `a/WorkspaceTaskPanel.vue` +3 more; derive it now" in ctx
+           "`a/TaskLogSection.vue`, `a/WorkspaceTaskPanel.vue` +3 more; used by 6 templates: " \
+           "`a/TaskLogSection.vue`, `a/V.vue` +4 more; derive it now" in ctx
     assert "`slugify` is a duplicate family with no canon — identical body in 2 other file(s): " \
            "`a/x.py`, `a/y.py`; derive it now" in ctx
     assert "`.btn-primary` is canon — snippet #2855 at `frontend/src/assets/components.css`" in ctx