feat(shapes): the write-path hook suggests and no longer stamps (milestone 439 step 4)

The hook used to land its evidence as `instance` rows, classified_by=hook —
a permanent verdict nobody read, and the source of the weak stamps that
poisoned two ledgers (#4608). Now the agent that wrote the code judges it at
the end of the turn, and the hook's evidence is what it is shown.

- shape_ledger.suggest_write_path_instances (was stamp_write_path_instances):
  same evidence and form gate, but it writes a PROPOSAL — proposed_snippet_id,
  basis "reference" (named) or "semantic" (resembles), score — and never a
  status. A judged row is left alone; a new shape gets an unclassified
  provisional row so the suggestion reaches the end-of-turn question as
  "looks like #N". By-name uses edges stay: a fact, not a verdict.
- The prior-art line says "looks like #N … when you judge this turn's
  shapes, say whether it is", and the result key is `suggested`.
- write_time_divergence takes `suggested`; _RESEMBLE_MIN re-documented as the
  suggestion bar and the weak-stamp line.
- reusing-code skill no longer says the pull stamps an instance.
- Tests moved to the new contract, plus a guard that nothing the hook does
  writes classified_by="hook".

Plugin version minted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/test_integration_shape_classify.py

@@ -322,15 +322,16 @@ async def test_sync_refiles_rows_whose_snippet_was_purged(seeded):
 
 
 @pytest.mark.integration
-async def test_write_path_stamp_is_evidence_that_yields_to_judgment(seeded):
-    """Pulled + referenced → every named shape of the snippet's kind becomes
-    an instance row, classified_by=hook, carrying the evidence as reason. A
-    later agent judgment on one of them stands against a re-stamp; the hook
-    may only overwrite nobody's judgment or its own. The outsider stamps
-    nothing (write-gated like every other ledger write)."""
+async def test_write_path_evidence_is_a_proposal_never_a_verdict(seeded):
+    """Milestone 439. Pulled + referenced → every named shape of the
+    snippet's kind CARRIES the snippet as a proposal (basis "reference"),
+    and its status is untouched: the agent that wrote it says what it is.
+    A judgment is never touched, not even by a proposal. The outsider
+    writes nothing (write-gated like every other ledger write). The uses
+    edge — a fact about the code — is still recorded."""
     from datetime import datetime, timezone
 
-    from scribe.services.shape_ledger import stamp_write_path_instances
+    from scribe.services.shape_ledger import suggest_write_path_instances
 
     owner, other, pid, sid = (
         seeded["owner"], seeded["other"], seeded["pid"], seeded["snippet"]
@@ -338,84 +339,98 @@ async def test_write_path_stamp_is_evidence_that_yields_to_judgment(seeded):
     pulled = {sid: datetime.now(timezone.utc)}
     code = "app = factory()\nreturn app\n"          # references the snippet's symbol
 
-    assert await stamp_write_path_instances(
+    assert await suggest_write_path_instances(
         other, pid, path="src/app.py", shapes=[("sym", "make_app")],
         code=code, pulled=pulled,
     ) == []
 
-    stamped = await stamp_write_path_instances(
+    suggested = await suggest_write_path_instances(
         owner, pid, path="src/app.py",
         shapes=[("sym", "make_app"), ("sym", "Config"), ("css", "nope")],
         code=code, pulled=pulled,
     )
-    assert {s["symbol"] for s in stamped} == {"make_app", "Config"}   # css skipped: no css canon
-    rows, _ = await list_project_shapes(owner, pid, snippet_id=sid)
+    assert {s["symbol"] for s in suggested} == {"make_app", "Config"}   # css skipped: no css canon
+    rows, _ = await list_project_shapes(owner, pid, path="src/app.py")
     by_symbol = {r.symbol: r for r in rows}
-    assert by_symbol["make_app"].status == "instance"
-    assert by_symbol["make_app"].classified_by == "hook"
-    assert by_symbol["make_app"].reason == f"hook: pulled #{sid}; payload references `factory`"
+    for name in ("make_app", "Config"):
+        row = by_symbol[name]
+        assert row.status == "unclassified" and row.classified_by is None, name
+        assert (row.proposed_snippet_id, row.proposal_basis) == (sid, "reference"), name
+    # The by-name reference is still recorded as a call-site fact.
+    users, _ = await list_project_shapes(owner, pid, uses=sid)
+    assert {"make_app", "Config"} <= {r.symbol for r in users}
 
-    # A judgment lands; the next stamp must leave it alone but may re-stamp
-    # its own earlier row.
+    # A judgment stands: the next suggestion leaves the judged row alone.
     await classify_shapes(owner, pid, [
         {"path": "src/app.py", "symbol": "make_app", "status": "exempt",
          "reason": "the app factory is its own thing"},
     ])
-    again = await stamp_write_path_instances(
+    again = await suggest_write_path_instances(
         owner, pid, path="src/app.py",
         shapes=[("sym", "make_app"), ("sym", "Config")], code=code, pulled=pulled,
     )
     assert {s["symbol"] for s in again} == {"Config"}
     rows, _ = await list_project_shapes(owner, pid, path="src/app.py")
-    by_symbol = {r.symbol: r for r in rows}
-    assert by_symbol["make_app"].status == "exempt"
-    assert by_symbol["Config"].status == "instance"
+    assert {r.symbol: r.status for r in rows}["make_app"] == "exempt"
 
     # Neither pulled nor in play → nothing, even with shapes named.
-    assert await stamp_write_path_instances(
+    assert await suggest_write_path_instances(
         owner, pid, path="src/util.py", shapes=[("sym", "helper")],
         code="print('unrelated')", pulled=pulled,
     ) == []
 
+    # And nothing the hook does writes classified_by="hook" any more.
+    async with async_session() as s:
+        hook_rows = (await s.execute(select(CodeShape).where(
+            CodeShape.project_id == pid, CodeShape.classified_by == "hook",
+        ))).scalars().all()
+    assert hook_rows == []
+
 
 @pytest.mark.integration
-async def test_a_brand_new_shape_gets_a_provisional_row_the_sync_settles(seeded):
+async def test_a_brand_new_shape_gets_a_provisional_row_carrying_the_suggestion(seeded):
     """The shape being written right now has no ledger row yet. With the
-    hook's repo key it gets a provisional one — seen markers empty — so the
-    stamp survives until the next sync, which confirms it (sets the marker)
-    or stamps it vanished. Without a repo key only existing rows are touched."""
+    hook's repo key it gets a provisional, UNCLASSIFIED one — seen markers
+    empty — carrying the suggestion to the end-of-turn question; the sync
+    confirms it or stamps it vanished. Without a repo key only existing rows
+    carry a suggestion."""
     from datetime import datetime, timezone
 
-    from scribe.services.shape_ledger import stamp_write_path_instances
+    from scribe.services.shape_ledger import suggest_write_path_instances, unjudged_shapes
 
     owner, pid, sid = seeded["owner"], seeded["pid"], seeded["snippet"]
     pulled = {sid: datetime.now(timezone.utc)}
     code = "def build():\n    return factory()\n"
 
-    assert await stamp_write_path_instances(
+    assert await suggest_write_path_instances(
         owner, pid, path="src/new.py", shapes=[("sym", "build")],
         code=code, pulled=pulled,                              # no repo_key
     ) == []
-    stamped = await stamp_write_path_instances(
+    suggested = await suggest_write_path_instances(
         owner, pid, path="src/new.py", shapes=[("sym", "build")],
         code=code, pulled=pulled, repo_key=REPO,
     )
-    assert [s["symbol"] for s in stamped] == ["build"]
+    assert [s["symbol"] for s in suggested] == ["build"]
     async with async_session() as s:
         row = (await s.execute(select(CodeShape).where(
             CodeShape.project_id == pid, CodeShape.path == "src/new.py",
         ))).scalar_one()
-        assert row.status == "instance" and row.classified_by == "hook"
+        assert row.status == "unclassified" and row.classified_by is None
+        assert row.proposed_snippet_id == sid
         # "Unset" is the column's empty default — the markers are non-null
         # Text, and the sync is what first fills them.
         assert row.first_seen_commit == "" and row.last_seen_commit == ""
 
-    # The sync sees the shape in the tree → confirmed, stamp intact.
+    # The end-of-turn question shows the suggestion as evidence.
+    asked = await unjudged_shapes(pid, [("src/new.py", "sym", "build")], repo_key=REPO)
+    assert asked[0]["evidence"]["looks_like"]["snippet_id"] == sid
+
+    # The sync sees the shape in the tree → confirmed, still unjudged.
     await sync_repo_shapes(
         pid, REPO, SHAPES + [("src/new.py", "sym", "build")], seen_marker="abc123",
     )
     rows, _ = await list_project_shapes(owner, pid, path="src/new.py")
-    assert rows[0].status == "instance" and rows[0].last_seen_commit == "abc123"
+    assert rows[0].status == "unclassified" and rows[0].last_seen_commit == "abc123"
 
     # The sync no longer sees it → vanished, out of the live accounting.
     await sync_repo_shapes(pid, REPO, SHAPES, seen_marker="def456")
@@ -866,19 +881,19 @@ async def test_a_second_confirm_dialog_is_detected_and_named(seeded):
 
     # In-band: the hook names the shape at write time → the check names the canon.
     named = await write_time_divergence(
-        pid, f"{comp}/Danger.vue", [("sym", "confirmDanger")], stamped=[]
+        pid, f"{comp}/Danger.vue", [("sym", "confirmDanger")], suggested=[]
     )
     assert named == [{"symbol": "confirmDanger", "kind": "sym", "canon_snippet_id": sid,
                       "instances": 4, "judged": 4}]
     # ...but an already-judged shape, or one just stamped as the canon's
     # instance, is not re-litigated.
-    assert await write_time_divergence(pid, f"{comp}/Trash.vue", [("sym", "onTrash")], stamped=[]) == []
+    assert await write_time_divergence(pid, f"{comp}/Trash.vue", [("sym", "onTrash")], suggested=[]) == []
     assert await write_time_divergence(
         pid, f"{comp}/New.vue", [("sym", "onNew")],
-        stamped=[{"symbol": "onNew", "kind": "sym", "snippet_id": sid}],
+        suggested=[{"symbol": "onNew", "kind": "sym", "snippet_id": sid}],
     ) == []
     # A directory with no dominant canon is silent.
-    assert await write_time_divergence(pid, "src/other.py", [("sym", "thing")], stamped=[]) == []
+    assert await write_time_divergence(pid, "src/other.py", [("sym", "thing")], suggested=[]) == []
 
     # The judgment answers the question and clears the flag.
     await classify_shapes(owner, pid, [
@@ -956,7 +971,7 @@ async def test_weak_stamps_elect_no_canon_and_their_flags_are_withdrawn(seeded):
     rows, total = await list_project_shapes(owner, pid, flag="divergence")
     assert total == 0, "a flag whose canon no longer dominates is withdrawn"
     assert await write_time_divergence(
-        pid, f"{comp}/Danger.vue", [("sym", "confirmDanger")], stamped=[]
+        pid, f"{comp}/Danger.vue", [("sym", "confirmDanger")], suggested=[]
     ) == []
     # Nothing was un-judged: the stamps stand until someone reads them.
     async with async_session() as session:

tests/test_write_path_trigger.py

@@ -1291,9 +1291,9 @@ async def test_stamping_needs_named_shapes_and_a_recent_pull():
          patch.object(pc, "semantic_search_notes", AsyncMock(return_value=[])), \
          patch.object(pc, "record_retrieval", MagicMock()), \
          patch.object(pc.shape_ledger_svc, "recent_pulls", pulls), \
-         patch.object(pc.shape_ledger_svc, "stamp_write_path_instances", stamp):
+         patch.object(pc.shape_ledger_svc, "suggest_write_path_instances", stamp):
         out = await pc.build_write_path_hint(1, "src/x.py", code=REAL_CODE, project_id=4)
-        assert out["stamped"] == []
+        assert out["suggested"] == []
         pulls.assert_not_awaited()                       # no shapes → no read
         out = await pc.build_write_path_hint(
             1, "src/x.py", code=REAL_CODE, project_id=4,
@@ -1301,7 +1301,7 @@ async def test_stamping_needs_named_shapes_and_a_recent_pull():
         )
     pulls.assert_awaited_once()
     stamp.assert_not_awaited()                           # shapes, but no pull
-    assert out["stamped"] == []
+    assert out["suggested"] == []
 
 
 @pytest.mark.asyncio
@@ -1330,7 +1330,7 @@ async def test_a_pulled_snippet_already_seen_is_evidence_not_menu():
          patch.object(pc, "record_retrieval", MagicMock()), \
          patch.object(pc, "owner_names_for", AsyncMock(return_value={})), \
          patch.object(pc.shape_ledger_svc, "recent_pulls", AsyncMock(return_value={7: _ts()})), \
-         patch.object(pc.shape_ledger_svc, "stamp_write_path_instances", stamp):
+         patch.object(pc.shape_ledger_svc, "suggest_write_path_instances", stamp):
         out = await pc.build_write_path_hint(
             1, "src/x.py", code=REAL_CODE, project_id=4, exclude_ids=[7],
             stamp_shapes=[("sym", "debounce")], repo_key="git.example.com/a/b",
@@ -1355,11 +1355,11 @@ async def test_a_pulled_snippet_already_seen_is_evidence_not_menu():
     assert skw["resembles"] == {7: 0.91}
     assert skw["shapes"] == [("sym", "debounce")]
     assert skw["repo_key"] == "git.example.com/a/b"
-    assert out["stamped"][0]["snippet_id"] == 7
-    # And the session is told what landed, with the way to correct it.
+    assert out["suggested"][0]["snippet_id"] == 7
+    # And the session is shown it as evidence for its own end-of-turn judgment.
     assert "Shape accounting" in out["context"]
-    assert "`debounce` → instance of #7" in out["context"]
-    assert "classify_shapes" in out["context"]
+    assert "`debounce` → looks like #7" in out["context"]
+    assert "When you judge this turn's shapes" in out["context"]
 
 
 @pytest.mark.asyncio
@@ -1376,15 +1376,15 @@ async def test_a_stamp_renders_even_when_the_hint_is_otherwise_silent():
          patch.object(pc, "record_retrieval", MagicMock()), \
          patch.object(pc, "owner_names_for", AsyncMock(return_value={})), \
          patch.object(pc.shape_ledger_svc, "recent_pulls", AsyncMock(return_value={5: _ts()})), \
-         patch.object(pc.shape_ledger_svc, "stamp_write_path_instances",
+         patch.object(pc.shape_ledger_svc, "suggest_write_path_instances",
                       AsyncMock(return_value=stamped)):
         out = await pc.build_write_path_hint(
             1, "web/b.css", code=".btn-primary { color: red; }" * 4, project_id=4,
             stamp_shapes=[("css", "btn-primary")],
         )
     assert out["note_ids"] == []
-    assert out["stamped"] == stamped
-    assert "`.btn-primary` → instance of #5" in out["context"]
+    assert out["suggested"] == stamped
+    assert "`.btn-primary` → looks like #5" in out["context"]
 
 
 @pytest.mark.asyncio
@@ -1397,13 +1397,13 @@ async def test_a_failing_stamp_does_not_sink_the_hint():
          patch.object(pc, "record_retrieval", MagicMock()), \
          patch.object(pc, "owner_names_for", AsyncMock(return_value={})), \
          patch.object(pc.shape_ledger_svc, "recent_pulls", AsyncMock(return_value={12: _ts()})), \
-         patch.object(pc.shape_ledger_svc, "stamp_write_path_instances",
+         patch.object(pc.shape_ledger_svc, "suggest_write_path_instances",
                       AsyncMock(side_effect=RuntimeError("ledger down"))):
         out = await pc.build_write_path_hint(
             1, "src/x.py", code=REAL_CODE, project_id=4, stamp_shapes=[("sym", "f")],
         )
     assert out["sync_note_ids"] == [12]
-    assert out["stamped"] == []
+    assert out["suggested"] == []
 
 
 def test_route_stamps_only_for_a_caller_allowed_to_write():
@@ -1760,7 +1760,7 @@ async def test_a_record_this_arm_withheld_itself_is_not_a_near_miss():
          patch.object(pc, "owner_names_for", AsyncMock(return_value={})), \
          patch.object(pc.shape_ledger_svc, "recent_pulls",
                       AsyncMock(return_value={7: _ts()})), \
-         patch.object(pc.shape_ledger_svc, "stamp_write_path_instances",
+         patch.object(pc.shape_ledger_svc, "suggest_write_path_instances",
                       AsyncMock(return_value=[])), \
          patch.object(pc, "semantic_search_notes",
                       _search_reporting(0.9, fake_note(