feat(rules)!: a rule cannot be created, or edited into, having no trigger (#4099)

`when_to_apply` is not metadata. `rule_document` embeds a rule as
`{title} — {trigger}` / `When to apply: {trigger}\n\n{statement}`, the trigger
appearing twice so purpose dominates a short vector — the shape note 2485
measured on snippets (a 0.153 top-to-second gap against 0.010–0.023 for
everything else). Without one the document silently becomes title + statement:
a DIFFERENT shape, ranked against a corpus it does not match, with nothing to
report it. Every bar and every rank in the system assumes one shape.

`create_preference` has refused an empty trigger since it shipped. The two rule
creators defaulted it to "" — so the shape was enforced for the record kind
that guides and optional for the kind that binds.

The guard lives in the SERVICE, because both doors reach it: the MCP tools and
the frontend's fast path in routes/rulebooks.py. Written in either alone, the
other could still create a rule that never fires. The route keeps a matching
check for the STATUS CODE only (400, not the 404 it maps ValueError to).

update_rule refuses to EMPTY an existing trigger, checked after the mutation so
it covers `clear=[...]`, an emptied form input, and any route added later.
Deliberately asked as "did this edit remove one" rather than "does one exist":
a rule predating the guard has none, and refusing to save it would freeze
precisely the unreachable records that most need fixing.

Deliberately not following arose_from_id, which the human door exempts itself
from because provenance is about auditing what the AGENT changed. That reasoning
does not reach this field — a missing trigger is not a missing explanation, it
is a rule that does not work, and it fails an operator as badly as a session.

15 test fixtures across 6 files were creating rules with no trigger. They now
pass one; that they did not is the point — curation is not a guarantee.

Step 1 of milestone 416 "Retrieval stops guessing a bar". First because every
later step assumes one document shape, and it is much cheaper to guarantee
before a corpus grows than to backfill after.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy

tests/test_integration_embedding_yields_to_delete.py

@@ -75,6 +75,7 @@ async def seeded():
     book = await rulebooks_svc.create_rulebook(uid, "Lock fixtures")
     topic = await rulebooks_svc.create_topic(book.id, uid, "locks")
     rule = await rulebooks_svc.create_rule(
+        when_to_apply="when the moment this fixture stands in for arises",
         topic.id, uid, "A rule with vectors",
         "Something for the embedder to index.",
     )

tests/test_integration_rule_verification.py

@@ -44,6 +44,7 @@ async def constraint():
     book = await rulebooks_svc.create_rulebook(uid, "Environment facts")
     topic = await rulebooks_svc.create_topic(book.id, uid, "ci")
     rule = await rulebooks_svc.create_rule(
+        when_to_apply="when the moment this fixture stands in for arises",
         topic.id, uid, "The runner has no bash",
         "Write every `run:` step in POSIX sh.",
         verify_with="read the workflow's shell setting",
@@ -153,13 +154,16 @@ async def rulebook_of_three():
     book = await rulebooks_svc.create_rulebook(uid, "Sweep fixture")
     topic = await rulebooks_svc.create_topic(book.id, uid, "mixed")
     decision = await rulebooks_svc.create_rule(
+        when_to_apply="when the moment this fixture stands in for arises",
         topic.id, uid, "dev is home", "Work directly on dev.",
     )
     never = await rulebooks_svc.create_rule(
+        when_to_apply="when the moment this fixture stands in for arises",
         topic.id, uid, "The runner has no bash", "Use POSIX sh.",
         verify_with="read the workflow's shell setting",
     )
     stale = await rulebooks_svc.create_rule(
+        when_to_apply="when the moment this fixture stands in for arises",
         topic.id, uid, "Bumps need a dashboard tick", "Tick it first.",
         verify_with="cat CI-runner/renovate/config.js",
     )

tests/test_integration_rule_versions.py

@@ -57,6 +57,7 @@ async def constraint():
     book = await rulebooks_svc.create_rulebook(uid, "History fixtures")
     topic = await rulebooks_svc.create_topic(book.id, uid, "ci")
     rule = await rulebooks_svc.create_rule(
+        when_to_apply="when the moment this fixture stands in for arises",
         topic.id, uid, "The runner has no bash",
         "Write every `run:` step in POSIX sh.",
         why="the image ships no bash",
@@ -258,6 +259,7 @@ async def test_a_version_cannot_be_read_through_a_DIFFERENT_rule(constraint):
         rule = await s.get(Rule, constraint["rule_id"])
         topic_id = rule.topic_id
     sibling = await rulebooks_svc.create_rule(
+        when_to_apply="when the moment this fixture stands in for arises",
         topic_id, constraint["uid"], "A different rule", "Unrelated.",
     )
 

tests/test_mcp_tool_rulebooks.py

@@ -62,6 +62,7 @@ async def test_create_rule_passes_required_fields():
     with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_rule
         await create_rule(
+            when_to_apply="when the moment this fixture stands in for arises",
             topic_id=10, title="dev is home", statement="Work directly on dev",
         )
     kwargs = mock.call_args.kwargs
@@ -80,6 +81,7 @@ async def test_create_rule_blocked_by_duplicate_gate():
          patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_rule", create_mock):
         from scribe.mcp.tools.rulebooks import create_rule
         out = await create_rule(topic_id=10, title="dev is home", statement="x")
+    when_to_apply="when the moment this fixture stands in for arises",
     assert out["duplicate"] is True
     assert out["existing_id"] == 47
     assert "update_rule" in out["message"]
@@ -95,6 +97,7 @@ async def test_create_rule_force_bypasses_duplicate_gate():
          _plain_detail():
         from scribe.mcp.tools.rulebooks import create_rule
         out = await create_rule(topic_id=10, title="dev is home", statement="x", force=True)
+    when_to_apply="when the moment this fixture stands in for arises",
     assert out["id"] == 5
     find_mock.assert_not_called()
 
@@ -245,6 +248,7 @@ async def test_create_project_rule_passes_required_fields():
     with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_project_rule
         await create_project_rule(
+            when_to_apply="when the moment this fixture stands in for arises",
             project_id=42,
             statement="Always run migrations through alembic, not raw SQL.",
             why="audit trail",
@@ -263,6 +267,7 @@ async def test_create_project_rule_derives_title_from_statement():
     with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_project_rule
         await create_project_rule(
+            when_to_apply="when the moment this fixture stands in for arises",
             project_id=42,
             statement="Avoid auto-generated docstrings. Reviewers find them noise.",
         )
@@ -278,6 +283,7 @@ async def test_create_project_rule_uses_explicit_title_when_given():
     with patch("scribe.mcp.tools.rulebooks.rulebooks_svc.create_project_rule", mock), _plain_detail():
         from scribe.mcp.tools.rulebooks import create_project_rule
         await create_project_rule(
+            when_to_apply="when the moment this fixture stands in for arises",
             project_id=42,
             statement="anything",
             title="no auto-docstrings",

tests/test_preference_write_path.py

@@ -10,6 +10,7 @@ A preference inverts it. The operator's framing: *"preferences are rules that
 scribe can and should update during use."* A preference that asks every time
 never drifts, and drifting is the whole feature. Reaching one through
 `create_rule(kind=...)` would mean reading it through the gate's prose, and
+when_to_apply="when the moment this fixture stands in for arises",
 the caller would hesitate over exactly the act this kind exists to make
 routine.
 

tests/test_rule_trigger_required.py

@@ -0,0 +1,119 @@
+"""A rule cannot be created, or edited into, having no trigger (#4099).
+
+WHY THIS EXISTS
+
+`when_to_apply` is not metadata. `rule_document` embeds a rule as
+`{title} — {trigger}` / `When to apply: {trigger}\n\n{statement}`, with the
+trigger appearing TWICE so purpose dominates a short vector — the shape note
+2485 measured. Drop the trigger and the document silently becomes title +
+statement: a DIFFERENT shape, ranked against a corpus it does not match, with
+nothing to report it. Every bar and every rank in the system assumes one shape.
+
+`create_preference` has always refused an empty trigger. `create_rule` and
+`create_project_rule` defaulted it to `""` — so the shape was enforced for the
+record kind that merely guides and optional for the kind that binds.
+
+WHAT THIS PINS
+
+The guard lives in the SERVICE, because both doors reach it: the MCP tools and
+the frontend's fast path in `routes/rulebooks.py`. A guard written in either
+one alone would leave the other able to create a rule that never fires, which
+is the failure mode this whole change exists to remove.
+
+These call the service directly and assert on the refusal, so an empty guard
+cannot make them pass by accident (rule 167).
+"""
+from __future__ import annotations
+
+import re
+
+import pytest
+
+from scribe.services import rulebooks as rulebooks_svc
+
+TRIGGER_RE = re.compile(r"when_to_apply", re.I)
+
+
+@pytest.mark.parametrize("blank", ["", "   ", "\n\t "])
+def test_a_rulebook_rule_needs_a_trigger(blank):
+    """Whitespace is not a trigger — it embeds exactly like an empty one."""
+    with pytest.raises(ValueError, match=TRIGGER_RE):
+        rulebooks_svc._require_trigger(blank)
+
+
+def test_a_real_trigger_passes():
+    """The guard has to let the normal case through, or the parametrised
+    refusals above would pass for a guard that rejects everything."""
+    assert rulebooks_svc._require_trigger("before any git push") is None
+
+
+@pytest.mark.asyncio
+async def test_create_rule_refuses_before_it_touches_the_database():
+    """The guard runs ahead of the ownership check, so a missing trigger is
+    reported as such rather than as whatever the session lookup says. A bogus
+    topic_id proves no database was reached: were the guard absent, this would
+    fail on the topic instead, with a different message."""
+    with pytest.raises(ValueError, match=TRIGGER_RE):
+        await rulebooks_svc.create_rule(
+            topic_id=999_999, user_id=1, title="t", statement="s",
+        )
+
+
+@pytest.mark.asyncio
+async def test_create_project_rule_refuses_too():
+    """The second door into the same defect. Named separately because the two
+    functions are separate code paths that have drifted apart before."""
+    with pytest.raises(ValueError, match=TRIGGER_RE):
+        await rulebooks_svc.create_project_rule(
+            project_id=999_999, user_id=1, title="t", statement="s",
+        )
+
+
+def test_both_creators_actually_call_the_guard():
+    """Structural, and deliberately not satisfied by the behavioural tests
+    above: those would still pass if a future edit inlined a second copy of
+    the check. One definition is the point — a rule shape enforced in two
+    places is a rule shape that will be enforced differently in two places."""
+    import inspect
+
+    for fn in (rulebooks_svc.create_rule, rulebooks_svc.create_project_rule):
+        src = inspect.getsource(fn)
+        assert "_require_trigger(when_to_apply)" in src, (
+            f"{fn.__name__} no longer delegates to the shared guard"
+        )
+
+
+def test_update_cannot_empty_a_trigger_that_exists():
+    """The create guard is worth nothing if an edit can undo it, and both
+    doors can try: `clear=['when_to_apply']` from the MCP side and an emptied
+    form input from the REST side.
+
+    Asserted on the source because the check sits mid-transaction, after the
+    mutation and before the commit — reaching it needs a database. What must
+    not silently vanish is the pairing: the before-value captured, and the
+    raise that reads it.
+    """
+    import inspect
+
+    src = inspect.getsource(rulebooks_svc.update_rule)
+    assert "trigger_before" in src, "the pre-edit trigger is no longer captured"
+    assert re.search(r"if trigger_before and not", src), (
+        "update_rule no longer refuses to empty an existing trigger"
+    )
+
+
+def test_a_rule_that_never_had_one_is_still_editable():
+    """The deliberate asymmetry, and the reason the check asks 'did this edit
+    REMOVE a trigger' rather than 'does one exist'.
+
+    A rule predating the guard has no trigger. Refusing to save it would
+    freeze exactly the records that most need fixing — the unreachable ones —
+    so the guard must not fire when there was nothing to remove.
+    """
+    import inspect
+
+    src = inspect.getsource(rulebooks_svc.update_rule)
+    assert "trigger_before and not" in src, (
+        "the guard no longer keys on the BEFORE value, so a legacy rule with "
+        "no trigger can no longer be edited at all"
+    )

tests/test_services_rulebooks.py

@@ -140,6 +140,7 @@ async def test_create_rule_requires_owned_topic():
         from scribe.services.rulebooks import create_rule
         with pytest.raises(ValueError, match="topic .* not found"):
             await create_rule(
+                when_to_apply="when the moment this fixture stands in for arises",
                 topic_id=999, user_id=7, title="x", statement="y",
             )