feat(lessons): soft links — a lesson and a rule arriving together in distinct situations are proposed as a link (milestone 440 step 3, #4637)

When one hook response puts a lesson and a rule in front of the reader, the
pair is recorded as evidence on a SUGGESTED lesson_rule_links row; once the
pair has arrived together in PROPOSE_SITUATIONS (3) distinct situations, the
next co-arrival carries one line asking the reader to judge it with
judge_lesson_link. Nothing about surfacing changes: a suggested link carries
no rule anywhere (that is #4633, confirmed links only).

- lesson_rules: co_surfaced (fail-open; only pairs the reader could confirm —
  a lesson they may write, a rule they own; judged pairs gather nothing; one
  proposal per response; PROPOSE_COOLDOWN 6h between asks), plus the pure
  counting rules: situation_key, add_evidence, proposal_due, evidence_summary.
  A situation is the prompt on /retrieve (word tokens, sorted and
  de-duplicated, so trivial rewordings count once) and the FILE on
  /prior-art (every edit to one file is one situation).
- rules_for_lessons shows a suggested link's evidence counts.
- plugin_context: build_autoinject_hint returns lesson_ids,
  build_prompt_rule_hint returns shown_rule_ids, build_write_path_hint records
  its own pair; routes/plugin /retrieve records the prompt pair. Shown lines,
  repeats included: relevance makes a co-arrival, not the session ledger.
- Evidence lives in the existing evidence column — no migration, and backup
  already carries it.
- Tests: counting rules (unit), the recorder against Postgres (bar, repeat,
  judged pairs, ownership, cooldown, evidence kept on confirm); conftest stubs
  co_surfaced for unit tests.

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

tests/test_integration_lesson_rule_links.py

@@ -241,3 +241,76 @@ async def test_deleting_the_lesson_takes_its_answer_with_it(world):
             select(LessonNoRule).where(LessonNoRule.lesson_id == world["lesson"])
         )).scalars().all()
     assert left == []
+
+
+# ── #4637: soft links from co-surfacing ─────────────────────────────────────
+
+
+async def _link(lesson_id: int, rule_id: int):
+    async with async_session() as s:
+        return (await s.execute(
+            select(LessonRuleLink).where(
+                LessonRuleLink.lesson_id == lesson_id, LessonRuleLink.rule_id == rule_id,
+            )
+        )).scalar_one_or_none()
+
+
+async def _arrive(world, prompt: str, project: int | None = None, rules=None) -> str:
+    return await links_svc.co_surfaced(
+        world["owner"], [world["lesson"]], rules or [world["r1"]],
+        arm="p", situation=prompt, project_id=project,
+    )
+
+
+async def test_distinct_situations_reach_the_bar_and_the_proposal_fires_once(world):
+    assert await _arrive(world, "the CI run is still going after twenty minutes") == ""
+    assert await _arrive(world, "deploy job hanging on the image build step") == ""
+    line = await _arrive(world, "integration lane overran its usual duration", world["mine"])
+    assert f"judge_lesson_link({world['lesson']}, {world['r1']}" in line
+
+    link = await _link(world["lesson"], world["r1"])
+    assert link.state == "suggested"
+    assert links_svc.evidence_summary(link.evidence)["situations"] == 3
+    # Within the cooldown a fourth situation is counted but not asked again.
+    assert await _arrive(world, "pipeline stuck waiting on a runner for ages") == ""
+    link = await _link(world["lesson"], world["r1"])
+    assert links_svc.evidence_summary(link.evidence)["situations"] == 4
+
+
+async def test_the_same_prompt_repeated_never_reaches_the_bar(world):
+    for _ in range(5):
+        assert await _arrive(world, "is the CI run still going") == ""
+    ev = links_svc.evidence_summary((await _link(world["lesson"], world["r1"])).evidence)
+    assert ev == {"situations": 1, "projects": 0, "co_surfaced": 5}
+
+
+async def test_a_judged_pair_gathers_nothing_and_is_never_proposed(world):
+    owner = world["owner"]
+    await links_svc.judge_link(owner, world["lesson"], world["r1"], "reject", "different failure")
+    await links_svc.judge_link(owner, world["lesson"], world["r2"], "confirm")
+    for prompt in ("first situation here", "second situation there", "third situation elsewhere"):
+        assert await _arrive(world, prompt, rules=[world["r1"], world["r2"]]) == ""
+    assert (await _link(world["lesson"], world["r1"])).evidence is None
+    assert (await _link(world["lesson"], world["r2"])).evidence is None
+
+
+async def test_a_rule_the_reader_does_not_own_is_not_paired(world):
+    for prompt in ("first situation here", "second situation there", "third situation elsewhere"):
+        assert await _arrive(world, prompt, rules=[world["foreign"]]) == ""
+    assert await _link(world["lesson"], world["foreign"]) is None
+
+
+async def test_a_suggestion_shows_its_evidence_and_leaves_the_lesson_unjudged(world):
+    await _arrive(world, "the CI run is still going after twenty minutes", world["mine"])
+    rules = (await links_svc.rules_for_lessons(world["owner"], [world["lesson"]]))[world["lesson"]]
+    assert rules[0]["state"] == "suggested"
+    assert rules[0]["evidence"] == {"situations": 1, "projects": 1, "co_surfaced": 1}
+    assert (await _judgment(world["lesson"]))["rule_judgment"] == "unjudged"
+
+
+async def test_confirming_a_suggestion_keeps_what_it_rested_on(world):
+    for prompt in ("first situation here", "second situation there", "third situation elsewhere"):
+        await _arrive(world, prompt)
+    out = await links_svc.judge_link(world["owner"], world["lesson"], world["r1"], "confirm", "same failure class")
+    assert out["state"] == "confirmed"
+    assert len(out["evidence"]["situations"]) == 3