"""Both rule-creation tools tell the caller to ask before writing (#3557).

WHY THIS EXISTS

Every other gate on `create_rule` and `create_project_rule` is about SHAPE:
is this a rule or a process, is it one thing you could violate, is it general
enough for a rulebook, is it a near-duplicate. All of those improve a rule
someone has already decided to write. None of them asks the prior question —
whether the person the rule will bind has agreed to be bound by it.

That question has to be asked at the tool, because the tool is the last
surface a caller reads before the write, and because the write is not
reversible in the way it looks. A rule that exists is not a proposal that
happens to be recorded: it is a standing instruction the operator must first
DISCOVER and then argue with, and the tiering makes discovery unreliable by
design — a conditional rule is never read aloud at session start, and a
project-scoped rule does not appear in an unfiltered `list_rules()` at all.
So the cheapest moment to ask is the only good one.

The fourth element of a proposal — how the rule would be ENFORCED — is not
ceremony. It is the gate that sometimes dissolves the rule: a thing a test
can assert should be that test, and a rule is what is left over when nothing
mechanical can hold it. A rulebook grows by default and shrinks only on
purpose, so the question that prevents a rule earns more than any question
that improves one's wording.

WHAT THIS PINS, AND WHAT IT DOES NOT

STRUCTURE, never wording — the same bargain the disambiguator guard (#3123)
strikes next door. Each concept is matched against a family of synonyms, so
the paragraphs stay free to be rewritten, reordered or sharpened; only
DELETING one fails. Pinning phrasing would make every improvement a red
build, and a test that punishes editing is a test someone deletes.

It cannot tell whether an agent actually asks. Nothing in a docstring can.
It catches the regression that really happens: guidance tidied away in a
later pass by someone who read it as throat-clearing in front of the Args.
"""
import pytest

from tests.helpers import tool_doc as _doc

# Both surfaces, because the one that needs it most is the one that looks
# minor. A project rule is the least visible record the system can hold —
# absent from an unfiltered list_rules(), and absent from session start too
# whenever it is conditional — so the surface that writes one carries the
# larger risk while reading as the smaller act.
_SURFACES = [
    ("scribe.mcp.tools.rulebooks", "create_rule"),
    ("scribe.mcp.tools.rulebooks", "create_project_rule"),
]

# The four things a proposal carries, each as a family of ways to say it.
# A docstring satisfies an element by containing ANY member — that is the
# room left for rewriting. The families deliberately exclude bare words a
# docstring would contain by accident ("why", "how", "reason"), which would
# make the assertion pass on prose that says nothing of the kind.
_ELEMENTS = {
    "the approval gate itself": (
        "proposal", "propose", "approv", "unprompted", "wait for an answer",
        "not yours to call",
    ),
    "the rule's intent": ("intent", "what it changes about how work"),
    "why it is being proposed now": (
        "why now", "arose_from_id", "the incident", "prompted it",
    ),
    "how it would be enforced": ("enforc",),
}


@pytest.mark.parametrize(("module", "name"), _SURFACES)
@pytest.mark.parametrize("element", sorted(_ELEMENTS))
def test_a_rule_surface_asks_for_approval_and_its_four_parts(
    module, name, element
):
    """Each of the four proposal elements survives in each docstring."""
    doc = _doc(module, name).lower()
    assert any(token in doc for token in _ELEMENTS[element]), (
        f"{name}'s docstring no longer mentions {element}. A caller reads "
        f"this immediately before writing a rule that will bind every future "
        f"session — it is the last place the question can be raised cheaply. "
        f"Say it in whatever words you like; this guard only checks it is "
        f"still said. See create_rule's opening for the shape."
    )


@pytest.mark.parametrize(("module", "name"), _SURFACES)
def test_the_approval_gate_comes_before_the_parameter_contract(module, name):
    """It has to be read to work, and the Args: block is where reading stops.

    A caller who has decided to make the call skims down to the parameters.
    Guidance parked below them — or folded into one argument's description —
    is guidance that arrives after the decision it was meant to inform, which
    is the same as not being there.
    """
    doc = _doc(module, name).lower()
    args_at = doc.find("args:")
    assert args_at > 0, f"{name}'s docstring has no Args: block"
    gate_at = min(
        (doc.find(t) for t in _ELEMENTS["the approval gate itself"]
         if doc.find(t) >= 0),
        default=-1,
    )
    assert 0 <= gate_at < args_at, (
        f"{name} states the approval gate at or after its Args: block "
        f"(gate {gate_at}, args {args_at}). Move it to the opening — a "
        f"caller who has already decided to write the rule reads the "
        f"parameters, not the prose under them."
    )