FabledScribe/src/scribe/mcp/tools/rulebooks.py

"""MCP tools for the Scribe Rulebook system.

Rulebook / topic / rule CRUD and the rule-to-rule
edges. Thin wrappers over services/rulebooks.py — ownership is enforced in the
service, and the record shape comes from rule_brief / rule_detail there rather
than being rebuilt here.

(The header used to say "Sixteen tools" and had been wrong for two milestones;
the count lives in the registration test, which fails when it drifts.)

Destructive ops (delete_*) require confirmed=True; otherwise return a
preview-style warning. Mirrors the pattern in delete_event and the design
spec.
"""
from __future__ import annotations

from scribe.mcp._context import current_user_id
from scribe.services import dedup as dedup_svc
from scribe.services import rulebooks as rulebooks_svc
from scribe.services import trash as trash_svc
from scribe.services.rule_usage import (
    record_rule_outcome, record_rule_pulled,
)


# ── Rulebook CRUD ───────────────────────────────────────────────────────

async def list_rulebooks() -> dict:
    """List all rulebooks owned by the current user.

    Returns id, title, description for each.
    """
    uid = current_user_id()
    rows = await rulebooks_svc.list_rulebooks(uid)
    return {"rulebooks": [rb.to_dict() for rb in rows]}


async def get_rulebook(rulebook_id: int) -> dict:
    """Fetch a rulebook by id with its full topic list."""
    uid = current_user_id()
    rb = await rulebooks_svc.get_rulebook(rulebook_id, uid)
    if rb is None:
        raise ValueError(f"rulebook {rulebook_id} not found")
    topics = await rulebooks_svc.list_topics(rulebook_id, uid)
    data = rb.to_dict()
    data["topics"] = [t.to_dict() for t in topics]
    return data


async def create_rulebook(title: str, description: str = "") -> dict:
    """Create a new rulebook (a themed grouping of GLOBAL rules).

    A rule in a rulebook is global: it applies in every project its owner works
    on, and reaches a session by retrieval when the work makes it relevant
    (milestone 414). There is no subscribing a project to a rulebook, and no
    muting one per project — that machinery is gone. So a rulebook's rules must
    stay general, agnostic to any single project. Project-specific rules go in
    create_project_rule.

    Args:
        title: Rulebook name.
        description: Optional short description of what this rulebook covers.
    """
    uid = current_user_id()
    rb = await rulebooks_svc.create_rulebook(
        user_id=uid, title=title, description=description,
    )
    return rb.to_dict()


async def update_rulebook(
    rulebook_id: int, title: str = "", description: str = "",
) -> dict:
    """Update an existing rulebook. Only non-empty fields are changed.

    Args:
        rulebook_id: Rulebook to update.
        title: New title. Empty string leaves unchanged.
        description: New description. Empty string leaves unchanged.
    """
    uid = current_user_id()
    fields: dict = {}
    if title:
        fields["title"] = title
    if description:
        fields["description"] = description
    rb = await rulebooks_svc.update_rulebook(rulebook_id, uid, **fields)
    if rb is None:
        raise ValueError(f"rulebook {rulebook_id} not found")
    return rb.to_dict()


async def delete_rulebook(rulebook_id: int, confirmed: bool = False) -> dict:
    """Permanently delete a rulebook (cascades to all its topics and rules).

    Pass confirmed=True to actually delete. Without confirmation, returns a
    preview describing what will be cascaded.
    """
    uid = current_user_id()
    rb = await rulebooks_svc.get_rulebook(rulebook_id, uid)
    if rb is None:
        raise ValueError(f"rulebook {rulebook_id} not found")
    if not confirmed:
        topics = await rulebooks_svc.list_topics(rulebook_id, uid)
        rule_count = 0
        for t in topics:
            rule_count += len(await rulebooks_svc.list_rules(uid, topic_id=t.id))
        return {
            "warning": (
                f"Rulebook {rulebook_id} ('{rb.title}') contains "
                f"{len(topics)} topics and {rule_count} rules; all will be "
                f"deleted. Pass confirmed=True to proceed."
            ),
            "confirmed_required": True,
        }
    batch = await trash_svc.delete(uid, "rulebook", rulebook_id)
    return {"deleted": rulebook_id, "title": rb.title, "deleted_batch_id": batch,
            "message": f'Rulebook {rulebook_id} ("{rb.title}") moved to trash. '
                       f"Restore with restore('{batch}')."}


# ── Topic CRUD ─────────────────────────────────────────────────────────

async def list_topics(rulebook_id: int) -> dict:
    """List topics inside a rulebook."""
    uid = current_user_id()
    rows = await rulebooks_svc.list_topics(rulebook_id, uid)
    return {"topics": [t.to_dict() for t in rows]}


async def create_topic(
    rulebook_id: int, title: str,
    description: str = "", order_index: int = 0,
) -> dict:
    """Create a topic within a rulebook.

    Args:
        rulebook_id: Rulebook to add the topic to.
        title: Topic name (e.g. "git-workflow").
        description: Optional description.
        order_index: Display order (0-based; default 0).
    """
    uid = current_user_id()
    topic = await rulebooks_svc.create_topic(
        rulebook_id=rulebook_id, user_id=uid,
        title=title, description=description, order_index=order_index,
    )
    return topic.to_dict()


async def update_topic(
    topic_id: int, title: str = "",
    description: str = "", order_index: int = -1,
) -> dict:
    """Update a topic. Sentinels: title="" / description="" leave unchanged;
    order_index=-1 leaves unchanged.
    """
    uid = current_user_id()
    fields: dict = {}
    if title:
        fields["title"] = title
    if description:
        fields["description"] = description
    if order_index >= 0:
        fields["order_index"] = order_index
    topic = await rulebooks_svc.update_topic(topic_id, uid, **fields)
    if topic is None:
        raise ValueError(f"topic {topic_id} not found")
    return topic.to_dict()


async def delete_topic(topic_id: int, confirmed: bool = False) -> dict:
    """Delete a topic and all its rules. Requires confirmed=True."""
    uid = current_user_id()
    topic = await rulebooks_svc.get_topic(topic_id, uid)
    if topic is None:
        raise ValueError(f"topic {topic_id} not found")
    if not confirmed:
        rules = await rulebooks_svc.list_rules(uid, topic_id=topic_id)
        return {
            "warning": (
                f"Topic {topic_id} ('{topic.title}') contains {len(rules)} "
                f"rules; all will be deleted. Pass confirmed=True to proceed."
            ),
            "confirmed_required": True,
        }
    batch = await trash_svc.delete(uid, "topic", topic_id)
    return {"deleted": topic_id, "title": topic.title, "deleted_batch_id": batch,
            "message": f'Topic {topic_id} ("{topic.title}") moved to trash. '
                       f"Restore with restore('{batch}')."}


# ── Rule CRUD ──────────────────────────────────────────────────────────

def _rule_summary(r) -> dict:
    """The list-row shape for a rule: what an agent needs to APPLY it. The
    full record (why, how_to_apply, timestamps) is get_rule's job.

    One line, because the shape itself lives in the service — this was one of
    three hand-written copies that had already drifted apart (note 3026).
    """
    return rulebooks_svc.rule_brief(r)


async def list_rules(
    rulebook_id: int = 0, topic_id: int = 0, project_id: int = 0,
) -> dict:
    """List rules — filter by rulebook, topic, and/or project.

    Args:
        rulebook_id: 0 = no filter; positive = restrict to that rulebook.
        topic_id: 0 = no filter; positive = restrict to that topic.
        project_id: 0 = no filter; positive = that project's OWN rules.
            Global rules apply to every project, so they are listed by
            rulebook or topic (or unfiltered), not under each project.

    rulebook_id and topic_id AND-combine; project_id lists a project's rules
    on its own. Ownership-scoped.
    """
    uid = current_user_id()
    rows = await rulebooks_svc.list_rules(
        user_id=uid,
        rulebook_id=rulebook_id or None,
        topic_id=topic_id or None,
        project_id=project_id or None,
    )
    return {"rules": [_rule_summary(r) for r in rows], "total": len(rows)}


async def get_rule(rule_id: int) -> dict:
    """Fetch a rule by id — full statement + why + how_to_apply.

    Also carries what a listing leaves out: the global `systems` this rule is
    about, and its `relations`. Read the relations before acting on the rule —
    a rule with a `co_surfaces` edge is half of a shape, and an `overrides`
    edge means one of the pair is not in force here.
    """
    uid = current_user_id()
    rule = await rulebooks_svc.get_rule(rule_id, uid)
    if rule is None:
        raise ValueError(f"rule {rule_id} not found")
    # THE pull that matters. The write-path rule arm's own message ends "Read
    # it with get_rule(N)", so this is the exact action the hint asks for and
    # the only evidence that one landed. Recorded after the access check, so a
    # refused read is not counted as a pull.
    record_rule_pulled(user_id=uid, rule_id=int(rule.id), source="mcp_get_rule")
    return await rulebooks_svc.rule_detail(uid, rule)


async def rule_outcome(rule_id: int, outcome: str, why: str = "") -> dict:
    """Record what a rule you read ACTUALLY CHANGED — applied, or departed from.

    Call this after a rule has been surfaced to you and you have acted. It is
    the only way the system can tell a rule that is working from a rule that
    is being read and ignored: `surfaced` says it was offered, `get_rule` says
    it was opened, and until this exists neither says whether it made any
    difference. A rule obeyed every time and a rule ignored every time leave
    identical telemetry, and the second is the one worth knowing about.

    `outcome` is one of:

      "applied"  — it changed what you did, or it confirmed the approach you
                   were already taking. `why` is optional; following a rule is
                   the ordinary case and does not need an argument.
      "departed" — you read it and deliberately did not follow it. `why` is
                   REQUIRED and is the whole value of the call: a departure
                   without its reason is indistinguishable from a miss when
                   somebody reads this back, and "somebody" is usually you, in
                   a later session, with none of today's context.

    There is deliberately NO value for "read it and ignored it". That state is
    real, and it is the one this measurement exists to expose — but it is not
    something you can report, because noticing it is the same act as not doing
    it. It is derived instead: a rule you opened and never came back to. The
    honest way to keep yourself out of that bucket is to call this, not to
    reach for a word that describes it.

    A departure is a legitimate answer and is not a confession. Rules are
    written for the common case; recording the edge you found is how the rule
    gets better, and a corpus where nothing is ever departed from is a corpus
    nobody is really reading.
    """
    uid = current_user_id()
    rule = await rulebooks_svc.get_rule(rule_id, uid)
    if rule is None:
        raise ValueError(f"rule {rule_id} not found")
    choice = (outcome or "").strip().lower()
    if choice not in ("applied", "departed"):
        raise ValueError(
            f"outcome must be 'applied' or 'departed', got {outcome!r}"
        )
    if choice == "departed" and not (why or "").strip():
        raise ValueError(
            "a departure needs its reason — pass `why`. Without it the record "
            "cannot be told from a rule that was simply missed."
        )
    record_rule_outcome(
        user_id=uid, rule_id=int(rule.id), outcome=choice,
        source="mcp_rule_outcome", detail=why,
    )
    return {
        "rule_id": int(rule.id),
        "title": rule.title,
        "outcome": choice,
        "why": (why or "").strip() or None,
        "recorded": True,
    }


async def create_rule(
    topic_id: int, title: str, statement: str, when_to_apply: str,
    why: str = "", how_to_apply: str = "", order_index: int = 0,
    arose_from_id: int = 0, verify_with: str = "", expires_when: str = "",
    system_ids: list[int] | None = None, force: bool = False,
) -> dict:
    """Create a new rule in a rulebook (a SHARED rule — keep it general).

    PROPOSE RULES READILY, AND WRITE ONE WHEN THE OPERATOR SAYS YES. Noticing
    that something has hardened into a standing instruction is valuable work,
    and a session that notices it and says nothing has thrown the observation
    away. So raise it whenever you see one. The single step that belongs
    between noticing and writing is the operator's yes: a rule binds every
    future session, and they are the person it binds.

    Their yes is also the only moment the rule is reliably IN FRONT of them.
    After the write it may not be again for months — a conditional rule is not
    read aloud at session start, and a project-scoped one does not appear in
    an unfiltered list_rules() at all. So the proposal is the review.

    When the operator asks for a rule in so many words, that IS the yes —
    write it and move on. The loop below is for the rule you thought of.

    FIRST, ASK WHAT KIND OF THING YOU ARE HOLDING. Force is the axis, and one
    question sorts it: *what happens if someone doesn't do this?*

      * "something breaks, or a boundary is crossed" → a RULE. It must be
        followed, so it is the operator's to agree to. Propose it here.
      * "it gets done a way the operator didn't want" → a PREFERENCE
        (create_preference). How they want work done; ignoring it costs
        consistency rather than correctness. No approval loop — record it.
      * "they lose time rediscovering it" → a LESSON (create_lesson). A better
        way to think about a problem, or a solution that transfers, met again
        at the moment it applies. It binds nobody, so it needs no yes.

    Asking this raises the value of noticing rather than lowering it: the
    observation is worth keeping in all three cases, and what changes is
    only which door it goes through. A proposal that turns out to be a
    lesson has not failed — it has been routed.

    A PROPOSAL CARRIES FOUR THINGS, and the fourth is the one that decides it:

      1. WHAT it would require — the statement, in the words it would carry,
         not a gloss of them. The operator is agreeing to text.
      2. INTENT — what it changes about how work gets done, and what goes
         wrong today without it. "Be careful about X" is not an intent; the
         behaviour that would differ tomorrow is.
      3. WHY NOW — the incident, observation or decision behind it. Pass that
         record as arose_from_id, and say it in the conversation too: the
         field is for the reader six months out, the sentence is for the
         person deciding.
      4. HOW IT WOULD BE ENFORCED — a test, a CI check, a hook, a schema
         constraint, a duplicate gate, a review step... or nothing, in which
         case say so plainly: "nothing — this is prose a session has to
         remember." Answer this one honestly and it will sometimes dissolve
         the rule, which is the point rather than a side effect. What a test
         can assert should BE that test; a rule is what remains when nothing
         mechanical can hold the thing. A rulebook grows by default and
         shrinks only on purpose, so a question that prevents a rule is worth
         more than any question that improves one's wording.

    THEN CLOSE WITH A QUESTION THEY CAN ANSWER IN ONE WORD. Offer these
    answers, and make "LET'S TALK ABOUT IT" the easy one:

      * "Approve it AS WRITTEN" — you create it with the statement exactly as
        shown. This is what makes element 1 load-bearing: they approved TEXT,
        so that text is what gets stored, verbatim.
      * "LET'S TALK ABOUT IT" — the wording, the scope, whether it
        wants to be a rule at all. Most good rules arrive this way, so treat
        this answer as the expected one rather than a setback.
      * "MAKE IT A PREFERENCE" — they want it done this way, but nothing
        breaks if it isn't. create_preference records it without a loop, and
        it stays yours to keep current as they correct you.
      * "MAKE IT A LESSON" — worth knowing, binding nobody. create_lesson
        stores it against the SITUATION it applies to, so a later session
        meets it at that moment rather than having to go looking. Reach for
        this whenever the answer to "what happens if someone doesn't do
        this" was "they lose time".
      * "NO" — let it go. If the observation is still worth keeping and none
        of the above fits, it is a note (create_note): recorded, findable,
        and binding on nobody.

    The middle three are not consolation prizes. They are where most good
    observations belong, and the reason the kind question is worth asking
    out loud rather than settled silently before the proposal.

    Where the interface offers structured choices, ask it that way — a
    question with named options is answered in a click, while the same
    question inside a paragraph is answered by scrolling past. Where it does
    not, write the answers out as a list. Either way ask once and let the
    answer stand; re-raising a declined proposal argues a rule
    into existence, which is the thing this whole loop exists to prevent.

    A rulebook rule is GLOBAL — it applies in every project — so it must read as
    a general standard: never pin it to one project's files, paths, or quirks.
    For a rule that applies to a single project only, use create_project_rule
    instead (no rulebook+topic ceremony). A standard only some projects share
    is still global in reach; write it so it names the kind of work it is
    about, and it arrives where that work happens.

    Write it general WITHOUT hedging for the exceptions. A project that needs
    to strengthen, narrow or replace this rule writes its own and links it
    with relate_rules(kind="overrides"), and one that adds local specifics
    uses "elaborates" — so the general form does not have to anticipate every
    project it will ever reach. A rulebook rule padded with "unless…" clauses
    for two projects is two project rules that were never written.

    Before writing a rule at all, check whether another entity already models
    the thing. A rule is prose an agent must remember and apply; the others
    are structure a tool can resolve, render and check. Visual standards are a
    DESIGN SYSTEM (tokens inherit, resolve per mode, render to a stylesheet —
    none of that survives being prose). A repeatable procedure is a PROCESS.
    Reusable code is a SNIPPET. Reach for a rule only when the thing genuinely
    is a standing instruction about how to work and nothing else can hold it.

    ONE RULE = ONE THING YOU COULD VIOLATE. If a clause can be broken on its
    own, and fixing that breakage doesn't require the neighbouring clauses, it
    is a separate rule. Rules that FAIL TOGETHER get linked with relate_rules
    (kind="co_surfaces"), never merged into one row: a merged rule cannot be
    cited or surfaced a clause at a time, and it grows without
    limit because adding to it is always cheaper than adding a rule.

    Args:
        topic_id: The topic to attach the rule to.
        title: A short imperative title (e.g. "dev is home").
        statement: The actionable instruction (required). 1-2 sentences.
        when_to_apply: WHEN this rule fires — the trigger, not the
            instruction. State the moment or the material: "before any git
            push", "when adding a value to a CHECK-gated column", "when a
            release is being cut". REQUIRED, and not as ceremony: nothing is
            preloaded, so this is the whole of how the rule is found when it
            matters — and it is half of what the rule is EMBEDDED as, so a
            rule without one is not merely hard to find, it is stored in a
            different shape from every rule it competes with. Name the SYMPTOM
            — the words someone would type while stuck — rather than the
            category: "the CI job passed locally and fails on the runner with
            a permission error" retrieves; "when touching CI config" does not.
            This field is also the rule's RETRIEVAL SURFACE — it and the
            statement are what a search is matched against, so it should
            carry the SYMPTOM, not just the situation: the words someone
            would actually type while stuck. Measured (note 3078): a rule
            whose trigger named only its situation did not surface at all
            for the problem it solves; adding the symptom to the same field
            brought it back as the top hit. Where a rule prevents a specific
            failure, put that failure's vocabulary here — the error text,
            the wrong behaviour, the dead end.
            The two spellings, side by side:
              RETRIEVES: "the migration failed with a check violation on a
                column we just extended"
              COLLAPSES: "when working on migrations"
            The second names a CATEGORY. No session ever produces a
            category — it produces the command, the error, the half-formed
            ask — so a trigger written that way leaves the embedded
            document to be carried by the title alone.
        system_ids: Ids from list_canonical_systems — the global AREAS this
            rule is about. This is what lets a rule reach a project that is
            working in that area, so a CI rule surfaces on a CI change.
        arose_from_id: The note or task that CAUSED this rule (an incident, a
            decision). Prefer this over naming the record inside `why`, which
            cannot be followed and does not survive a rewording.
        why: Optional rationale — the reason the rule exists.
        how_to_apply: Optional operationalization — when / where it kicks in.
        verify_with: How to CHECK this rule is still true. Set it only when
            the rule asserts a fact about something outside your control — a
            runner's shell, a bot's config, whether a tool exists. Those go
            false silently, with nobody present. Give a command, a path, a
            URL or a query; something runnable beats prose, because prose
            has to be re-interpreted by whoever finds it.
            LEAVE IT EMPTY for a rule that is a DECISION — a preference, a
            standard, a way of working. A decision has no truth value: it
            changes when you change it, and you know that you did. An empty
            verify_with is not a gap, it is the marker for "there is nothing
            to go and check," and the whole signal is worthless the moment
            it is filled in out of tidiness.
        expires_when: The STATE under which this rule stops being true —
            "when the runner can be given a bash shell", "when the dashboard
            approval setting is turned off". Deliberately not a date: a
            constraint expires when the ground under it moves, not on a
            schedule. Pairs with verify_with; both empty is the normal case.
        order_index: Display order within the topic (default 0).
        force: Bypass the near-duplicate gate. By default, a title-identical rule
            already in this topic BLOCKS creation and returns its id so you update
            it instead. Set true only for a genuinely distinct rule.
    """
    uid = current_user_id()
    if not force:
        dup = await dedup_svc.find_duplicate_rule(title, topic_id=topic_id)
        if dup is not None:
            return dedup_svc.duplicate_response(dup, "rule")
    rule = await rulebooks_svc.create_rule(
        topic_id=topic_id, user_id=uid,
        title=title, statement=statement, when_to_apply=when_to_apply,
        arose_from_id=arose_from_id,
        why=why, how_to_apply=how_to_apply, order_index=order_index,
        verify_with=verify_with, expires_when=expires_when,
    )
    return await rulebooks_svc.rule_detail(uid, rule, system_ids)


async def create_project_rule(
    project_id: int, statement: str, when_to_apply: str, title: str = "",
    why: str = "", how_to_apply: str = "", order_index: int = 0,
    arose_from_id: int = 0, verify_with: str = "", expires_when: str = "",
    system_ids: list[int] | None = None, force: bool = False,
) -> dict:
    """Create a rule scoped to a single project (no rulebook needed).

    Use this for anything SPECIFIC to one project — its files, paths, layout,
    or quirks. This is the correct home for the project-specific detail that
    must NOT go into a rulebook (where it would be global, and reach every
    other project). General standards belong in a rulebook instead
    (create_rule). It bypasses the Rulebook -> Topic -> Rule ceremony; the
    rule surfaces by retrieval in this project's sessions only, and is listed
    in get_project's project_rules and in list_rules(project_id=...).

    PROPOSE, THEN WRITE ON A YES — create_rule's opening carries the whole
    loop: the kind question that comes first (what happens if someone doesn't
    do this — a rule binds, a preference guides, a lesson informs), the four
    things a proposal states (what it would require, its intent, why now, and
    how it would be enforced) and the one-word question that closes it
    (approve as written / talk about it / make it a preference / make it a
    lesson / no). All of it applies here unchanged. Reach for that loop MORE
    readily on this surface, not less: a project rule stays out of an
    unfiltered list_rules(), and a conditional one stays out of session start
    too, so the operator's yes is the one moment this rule is certain to have
    been seen by the person it binds.

    Check first whether a rule is the right shape at all — create_rule's
    opening asks that question and it applies identically here. A visual
    standard is a design system; a procedure is a process (create_process);
    reusable code is a snippet (create_snippet). Each of those is structure a
    tool can resolve, render and check, where a rule is only prose someone
    has to remember and apply.

    ONE RULE = ONE THING YOU COULD VIOLATE — see create_rule. A rule that
    STRICTENS or REPLACES an inherited one is not a fresh rule: write it, then
    relate_rules(kind="overrides") to the rule it supersedes, so the pair stays
    connected instead of drifting into a contradiction nobody notices. A rule
    that merely adds local detail to an inherited one uses "elaborates".

    Args:
        project_id: The project to attach the rule to.
        statement: The actionable instruction (required). 1-2 sentences.
        title: Short imperative title. If empty, derived from the first ~50
            characters of statement.
        when_to_apply: WHEN this rule fires — the trigger, not the
            instruction, and the rule's retrieval surface: name the SYMPTOM,
            the words someone would type while stuck. Show the moment rather
            than classifying it:
              RETRIEVES: "the CI job passed locally and fails on the runner
                with a permission error"
              COLLAPSES: "when touching CI config"
            See create_rule for the full argument.
        system_ids: Ids from list_canonical_systems — the global AREAS this
            rule is about. Worth setting even on a project rule: it is what
            lets a conditional one surface when the project is working in
            that area.
        arose_from_id: The note or task that CAUSED this rule. Reach for it
            harder here than on a rulebook rule — a project rule usually
            comes from one traceable incident in this repo, where a family
            rule is more often a standing preference with no single origin.
            The link is what lets a later reader judge whether the incident
            still describes the project.
        why: Optional rationale — the reason the rule exists.
        how_to_apply: Optional operationalization — when / where it kicks in.
        verify_with: How to check this rule is still true — see create_rule.
            Set it when the rule asserts a fact about someone else's software;
            leave it empty when the rule is a decision. Project rules are the
            likelier home for a real check: they name this project's files,
            paths and quirks, which is exactly the kind of claim that rots.
        expires_when: The state under which the rule stops being true — see
            create_rule. A state, not a date.
        order_index: Display order within the project's rule list (default 0).
        force: Bypass the near-duplicate gate. By default, a title-identical rule
            already on this project BLOCKS creation and returns its id so you
            update it instead. Set true only for a genuinely distinct rule.
    """
    uid = current_user_id()
    derived_title = title.strip() or statement.strip().split(".")[0][:50]
    if not force:
        dup = await dedup_svc.find_duplicate_rule(derived_title, project_id=project_id)
        if dup is not None:
            return dedup_svc.duplicate_response(dup, "rule")
    rule = await rulebooks_svc.create_project_rule(
        project_id=project_id, user_id=uid,
        title=derived_title, statement=statement, when_to_apply=when_to_apply,
        arose_from_id=arose_from_id,
        why=why, how_to_apply=how_to_apply, order_index=order_index,
        verify_with=verify_with, expires_when=expires_when,
    )
    return await rulebooks_svc.rule_detail(uid, rule, system_ids)


async def update_rule(
    rule_id: int, title: str = "", statement: str = "", when_to_apply: str = "",
    why: str = "", how_to_apply: str = "", order_index: int = -1,
    system_ids: list[int] | None = None, arose_from_id: int = 0,
    verify_with: str = "", expires_when: str = "", kind: str = "",
    clear_fields: list[str] | None = None,
) -> dict:
    """Update a rule. Empty strings / order_index=-1 leave fields unchanged.

    `kind` here is how a rule BECOMES a preference, and it is a real change of
    force rather than a relabelling — so make it deliberately and say so. The
    rule keeps its id, its history and its typed edges, which is why this is a
    field rather than a new record: everything that cites it by number stays
    correct. Ordinary edits to an existing preference belong in
    update_preference, which asks for what taught the change.

    `when_to_apply` IS HOW A RULE ARRIVES AT ALL. Nothing is preloaded since
    milestone 394, so a rule with no trigger is not a quiet rule — it is one
    no session will ever be shown. `system_ids` REPLACES the rule's areas
    (pass [] to clear), and they decide which PROJECTS a rule binds by area.

    RETROFITTING A TRIGGER HAS ITS OWN TRAP, and it is not the one create_rule
    warns about. There the field is empty and the instruction is "write one".
    Here a trigger usually already EXISTS and reads perfectly well as English —
    "during hard debugging", "when reading any request from the operator",
    "before starting an action while a previous one is still settling" — so the
    honest-looking verdict is that it is fine. It is not. Those three named a
    CATEGORY rather than a moment, and a category is not a thing any session
    ever types. `rule_document()` puts this field in twice, as the title's
    other half and again above the body, so it dominates the vector: a trigger
    describing the abstraction collapses the record toward its title and the
    rule never arrives. Measured in #3835 across 113 rules, and again in #3855
    on six preferences written before this was understood.

    So when you touch a rule with an old trigger, re-read it against the query
    that would have to match it — the command about to run, the code being
    written, the operator's actual message — and rewrite it in that vocabulary
    if it does not. Prefer the words someone produces while the rule applies,
    including the rationalisation they would be drafting to talk themselves out
    of it — that rationalisation is often the only text in existence at the
    moment the rule should fire:
      RETRIEVES: "catching yourself drafting 'this is small enough to not
        count' about a rule you have already read"
      COLLAPSES: "when the next action would conflict with a standing rule"
    See create_rule for the full argument and the measurement behind it.

    TO EMPTY A FIELD, NAME IT: clear_fields=["verify_with"]. Passing "" cannot
    do it — "" means "leave this alone" here, which is what lets you update
    two fields without wiping the other six. Clearable: why, how_to_apply,
    when_to_apply, verify_with, expires_when, arose_from_id. Clearing and
    setting the same field in one call clears it first, so the new value wins.

    Editing `verify_with` DROPS the rule's verification stamp. The stamp
    certifies a check, not a rule; once the check is reworded the old stamp
    vouches for something that no longer exists, so the rule re-enters the
    staleness sweep as never-verified.

    Args:
        verify_with: How to check the rule is still true — set it when the
            rule asserts a fact about someone else's software, leave it empty
            when the rule is a decision. See create_rule.
        expires_when: The state under which the rule stops being true. A
            state, not a date. See create_rule.
        clear_fields: Names of fields to empty, as above.
    """
    uid = current_user_id()
    fields: dict = {}
    if title:
        fields["title"] = title
    if statement:
        fields["statement"] = statement
    if when_to_apply:
        fields["when_to_apply"] = when_to_apply
    if kind:
        fields["kind"] = kind
    if arose_from_id:
        fields["arose_from_id"] = arose_from_id
    if why:
        fields["why"] = why
    if how_to_apply:
        fields["how_to_apply"] = how_to_apply
    if verify_with:
        fields["verify_with"] = verify_with
    if expires_when:
        fields["expires_when"] = expires_when
    if order_index >= 0:
        fields["order_index"] = order_index
    rule = await rulebooks_svc.update_rule(
        rule_id, uid, clear=clear_fields or (), **fields,
    )
    if rule is None:
        raise ValueError(f"rule {rule_id} not found")
    return await rulebooks_svc.rule_detail(uid, rule, system_ids)


# ── Preferences ─────────────────────────────────────────────────────────
#
# Separate tools rather than a `kind=` argument on create_rule, and the reason
# is the docstring rather than the data. create_rule's docstring IS the
# approval gate: it tells its caller to propose, offer three answers, and
# wait. A preference reached through that door would be read through that
# prose, and the caller would hesitate over exactly the act this kind exists
# to make routine. Two doors, two contracts, one table.
#
# Reads stay shared — get_rule and list_rules return preferences as they are,
# because a preference IS a rule row and a reader asking "what governs this"
# wants both. Only the WRITE contracts differ.


async def create_preference(
    topic_id: int, title: str, statement: str, when_to_apply: str,
    arose_from_id: int, why: str = "", how_to_apply: str = "",
    order_index: int = 0, system_ids: list[int] | None = None,
    force: bool = False,
) -> dict:
    """Record how the operator wants work done. No approval loop — write it.

    A PREFERENCE IS NOT A RULE, and the axis is force rather than importance:

      * a RULE is what must be FOLLOWED — ignoring it breaks something or
        crosses a boundary. It is the operator's decision, so create_rule
        proposes and waits for them.
      * a PREFERENCE is how they want it DONE — ignoring it costs consistency,
        not correctness. Noticing one and recording it is ordinary work.

    If the answer to "what happens if someone doesn't do this" is "something
    breaks", you are holding a rule: propose it with create_rule instead.

    WHY IT IS WORTH RECORDING AT ALL. A preference stated in one session dies
    with that session, and the next one re-derives it or asks again. The point
    is consistency: the tenth time you do something it goes the way the ninth
    did, without the operator having to say so a tenth time.

    `when_to_apply` IS REQUIRED, and not as ceremony. A rule's trigger is
    two-thirds of its embedded document, so a preference without one is a
    record that will never surface at the moment it applies — written,
    findable by nobody, and silently useless. Name the moment in the words a
    session would actually be producing then: the command it is about to run,
    the code it is writing, the thing the operator just asked for.

    Show the moment rather than classifying it:
      RETRIEVES: "the operator pasted a stack trace and said it is still
        broken"
      COLLAPSES: "during hard debugging"
    The second is a category, and no session ever produces a category — it
    produces the command, the error text, the half-formed ask. A trigger
    naming the abstraction collapses the record toward its title and it
    never arrives. Both of those describe the same preference; only one of
    them can be found at the moment it applies.

    `arose_from_id` IS REQUIRED for the same kind of reason. A preference is
    expected to change as the work teaches it, and a corpus that drifts with
    no record of what taught each change is one nobody can audit. Point it at
    the task or note where this became clear.

    WHAT A PREFERENCE NEVER DOES: change what gets RECORDED. It shapes how
    work is done — pacing, phrasing, which tool to reach for, how much to
    check first. A dev-log, an issue and a snippet read the same whoever
    produced them, because the record has to outlive the person and their
    preferences.

    A near-duplicate BLOCKS and returns the existing id. That is the whole
    reason this corpus can stay small while being written freely: the second
    preference about a thing UPDATES the first rather than sitting beside it,
    and two preferences that quietly disagree are worse than none — retrieval
    surfaces whichever scores higher and nobody learns the other exists. The
    gate is title-based within the topic and does not care about kind, so it
    also catches a preference restating a rule that already binds.

    Args:
        topic_id: The rulebook topic to file it under. A preference is
            user-scoped: it follows the operator across every project, which
            is what separates it from a project rule.
        title: What the preference is about. Half the embedded document —
            worth as much care as the statement.
        statement: How the operator wants it done, in their terms.
        when_to_apply: The moment it applies. Required; see above.
        arose_from_id: The task or note that taught this. Required; see above.
        system_ids: Ids from list_canonical_systems — the global AREAS this
            preference is about, which is what lets it reach a session working
            in that area. `update_preference` took this and create did not, so
            a preference could only be filed after the fact (#4249).
        force: Bypass the near-duplicate gate. For a genuinely distinct
            preference, not for one that is "mostly" different — a mostly
            different preference is an update.
    """
    uid = current_user_id()
    if not when_to_apply.strip():
        raise ValueError(
            "when_to_apply is required: a preference with no trigger never "
            "surfaces at the moment it applies. Name that moment in the words "
            "a session would be producing then."
        )
    if not arose_from_id:
        raise ValueError(
            "arose_from_id is required: preferences change as the work teaches "
            "them, and a change with no record of what taught it cannot be "
            "audited. Pass the task or note where this became clear."
        )
    if not force:
        dup = await dedup_svc.find_duplicate_rule(title, topic_id=topic_id)
        if dup is not None:
            return dedup_svc.duplicate_response(dup, "rule")
    rule = await rulebooks_svc.create_rule(
        topic_id=topic_id, user_id=uid,
        title=title, statement=statement, when_to_apply=when_to_apply,
        kind="preference", arose_from_id=arose_from_id,
        why=why, how_to_apply=how_to_apply, order_index=order_index,
    )
    return await rulebooks_svc.rule_detail(uid, rule, system_ids)


async def update_preference(
    rule_id: int, arose_from_id: int, statement: str = "",
    when_to_apply: str = "", title: str = "", why: str = "",
    how_to_apply: str = "", order_index: int = -1,
    system_ids: list[int] | None = None, clear_fields: list[str] | None = None,
) -> dict:
    """Bring a preference up to date. Doing this mid-work is expected.

    THIS IS THE TOOL THAT MAKES A PREFERENCE DIFFERENT FROM A RULE. A rule
    waits for its author; a preference is kept current by whoever is working.
    When the operator corrects you, or you notice the preference on file no
    longer matches how they actually want this done, edit it — that is the
    feature, not a liberty being taken. A preference nothing ever updates has
    become a rule nobody enforces.

    So: no proposal, no three answers, no waiting. Update it and say in the
    conversation that you did, so the operator can disagree while it is still
    in front of them.

    `arose_from_id` IS REQUIRED, and it is the price of the ungated write.
    Every edit here is versioned, and the operator can read what changed and
    put it back — but a diff with no reason attached leaves them deciding
    whether to trust a change they cannot account for. Point at the task or
    note that taught it.

    WHEN NOT TO EDIT. If what you learned is that something MUST be done a
    certain way — that skipping it breaks something or crosses a boundary —
    that is a rule, and rules are the operator's call: propose it with
    create_rule rather than hardening a preference in place. Softening in the
    other direction is equally an edit worth flagging out loud.

    EDITING `when_to_apply` IS THE HIGHEST-LEVERAGE EDIT HERE, and the easiest
    to skip, because a preference's trigger is load-bearing in a way a rule's
    is not. Preferences get a RESERVED slot at the prompt boundary, filled by a
    kind-filtered query at limit=1 — so the corpus does not merely rank against
    rules, it ranks against ITSELF, and the trigger is almost all of what
    separates one preference from the next. Six preferences whose triggers all
    named a category ("during hard debugging", "when reading any request from
    the operator") made that slot pick close to arbitrarily on every prompt.

    So whenever you are here for any reason, read the trigger against the
    operator's message that should have summoned it. If it describes a
    situation rather than quoting the moment, rewrite it in the words they
    actually type — and in the words YOU would be producing while about to get
    this wrong:
      RETRIEVES: "the operator said 'clean this up' or 'make it work like',
        naming an outcome rather than a change"
      COLLAPSES: "when reading any request from the operator"
    update_rule carries the full argument.

    Empty strings leave fields unchanged; clear_fields empties them by name,
    exactly as update_rule does.

    Args:
        rule_id: The preference to update.
        arose_from_id: What taught this change. Required; see above.
        when_to_apply: The moment it applies, in session vocabulary. See above.
    """
    uid = current_user_id()
    if not arose_from_id:
        raise ValueError(
            "arose_from_id is required: this edit is the record of how the "
            "operator's preference changed, and a change with no reason "
            "attached cannot be judged. Pass the task or note that taught it."
        )
    fields: dict = {"arose_from_id": arose_from_id}
    if title:
        fields["title"] = title
    if statement:
        fields["statement"] = statement
    if when_to_apply:
        fields["when_to_apply"] = when_to_apply
    if why:
        fields["why"] = why
    if how_to_apply:
        fields["how_to_apply"] = how_to_apply
    if order_index >= 0:
        fields["order_index"] = order_index
    rule = await rulebooks_svc.update_rule(
        rule_id, uid, clear=clear_fields or (), **fields,
    )
    if rule is None:
        raise ValueError(f"rule {rule_id} not found")
    return await rulebooks_svc.rule_detail(uid, rule, system_ids)


async def rule_history(rule_id: int, version_id: int = 0) -> dict:
    """What a rule USED TO SAY, newest change first.

    Read this before you argue with a rule, and before you rewrite one. A
    rule that has been reworded may have been reworded for a reason you are
    about to rediscover the hard way — and the wording it replaced is often
    the fastest way to see what the current one is guarding against. The
    rescoping of rule 79 is the case this exists for: the superseded
    statement had to be hand-copied into a task log to survive the edit.

    EACH ENTRY HOLDS THE TEXT THE EDIT REPLACED, not the text it introduced.
    So "what did this say before the most recent change?" is the first entry,
    and the text the change PRODUCED is the rule as it stands now — read that
    with get_rule. Pair the two and you have the diff.

    An empty history is ordinary and means the rule has never been reworded,
    not that its history was lost. Nothing is written before milestone 323,
    so a rule edited before then starts empty too.

    Args:
        rule_id: The rule whose history to read.
        version_id: 0 (default) lists the history — when each change
            happened, by whom, and the title as it then stood. Pass an id
            from that list to read that snapshot IN FULL. The list omits
            statement and why on purpose: a rule's statement runs to
            thousands of characters, and a history carrying every field would
            cost more to read than the answer is worth.

    There is deliberately no restore. Putting an old wording back is a
    decision, so it goes through update_rule — which snapshots what it
    replaces, leaving the undo visible in the history like any other edit. A
    one-click revert would erase the only record of why the rewrite happened.
    """
    uid = current_user_id()
    if version_id:
        version = await rulebooks_svc.get_rule_version(rule_id, version_id, uid)
        if version is None:
            raise ValueError(
                f"version {version_id} not found on rule {rule_id}"
            )
        return version.to_dict(include_text=True)

    versions = await rulebooks_svc.list_rule_versions(rule_id, uid)
    if versions is None:
        raise ValueError(f"rule {rule_id} not found")
    # Fail-open, like the deletes: a missing title must not turn a readable
    # history into an error.
    try:
        rule = await rulebooks_svc.get_rule(rule_id, uid)
    except Exception:
        rule = None
    return {
        "rule_id": rule_id,
        "title": rule.title if rule else "",
        "versions": [v.to_dict(include_text=False) for v in versions],
        "total": len(versions),
        # Said in-band because an empty list is the ordinary case and reads
        # like a missing feature otherwise.
        "note": (
            "Each entry holds the text the edit REPLACED. The current wording "
            "is on the rule itself — get_rule(%d)." % rule_id
            if versions else
            "This rule has never been reworded."
        ),
    }


async def move_rule(rule_id: int, topic_id: int = 0, project_id: int = 0) -> dict:
    """Move a rule to a new home, keeping its id, history, areas and edges.

    A rule's home IS its reach. In a rulebook topic it is GLOBAL: it applies in
    every project and reaches any session whose work matches it. On a project
    it applies to that project only. So this is how a project rule that turns
    out to hold everywhere becomes global (pass `topic_id`), and how a global
    rule that only one project needs becomes that project's (pass
    `project_id`). Name exactly one.

    Reach for this INSTEAD of recreating the rule in the other home and
    deleting the original: that loses the id every record cites it by, its
    edit history, its area tags and its relations.

    A move is a decision about where a rule binds, so propose it and move on a
    yes, the way create_rule proposes a new rule — and record why where the
    decision lives (a task or note). The rule's history does not record a
    move: it holds what the rule SAID, and a move changes none of that.

    Refused with a message when: neither or both destinations are named, the
    destination is not yours, the rule is already there, or the topic already
    has a rule with this title (rename one first).
    """
    uid = current_user_id()
    rule = await rulebooks_svc.move_rule(
        rule_id, uid, topic_id=topic_id, project_id=project_id,
    )
    if rule is None:
        raise ValueError(f"rule {rule_id} not found")
    return await rulebooks_svc.rule_detail(uid, rule)


async def delete_rule(rule_id: int, confirmed: bool = False) -> dict:
    """Move a rule to the trash (recoverable). Requires confirmed=True."""
    uid = current_user_id()
    rule = await rulebooks_svc.get_rule(rule_id, uid)
    if rule is None:
        raise ValueError(f"rule {rule_id} not found")
    if not confirmed:
        return {
            "warning": (
                f"Rule {rule_id} ('{rule.title}') will be moved to the trash "
                f"(recoverable via restore). Pass confirmed=True to proceed."
            ),
            "confirmed_required": True,
        }
    batch = await trash_svc.delete(uid, "rule", rule_id)
    return {"deleted": rule_id, "title": rule.title, "deleted_batch_id": batch,
            "message": f'Rule {rule_id} ("{rule.title}") moved to trash. '
                       f"Restore with restore('{batch}')."}


async def relate_rules(
    from_rule_id: int, to_rule_id: int, kind: str, note: str = "",
) -> dict:
    """Draw a typed edge between two rules. Both must be yours.

    Reach for this INSTEAD of merging or duplicating:

    - kind="co_surfaces" — these two fail together, so they must arrive
      together. Use it when you are tempted to fold one rule into another
      because "either could surface without the other": that instinct is
      right and merging is the wrong fix, because a merged rule cannot be
      cited or surfaced a clause at a time. Symmetric — draw it
      once, it reads from both ends.
    - kind="overrides" — this rule supersedes that one for its scope. Use it
      when a project rule is stricter than, or replaces, an inherited one,
      instead of writing a near-copy that will drift from its parent.
    - kind="elaborates" — this rule adds local specifics to that one, and
      should arrive with it rather than instead of it.

    Idempotent: re-drawing an existing edge returns it.

    Args:
        note: WHY the edge holds. Worth writing for the same reason a rule
            carries `why` — a later reader deciding whether it still applies
            needs the reasoning, not just the fact.
    """
    uid = current_user_id()
    relation = await rulebooks_svc.add_rule_relation(
        uid, from_rule_id, to_rule_id, kind, note,
    )
    if relation is None:
        raise ValueError(
            f"rule {from_rule_id} or {to_rule_id} not found (both must be yours)"
        )
    return relation.to_dict()


async def unrelate_rules(relation_id: int) -> dict:
    """Remove one edge between rules (from relate_rules / get_rule.relations)."""
    uid = current_user_id()
    if not await rulebooks_svc.remove_rule_relation(uid, relation_id):
        raise ValueError(f"relation {relation_id} not found")
    return {"deleted": relation_id}

# ── The staleness sweep (milestone 312) ────────────────────────────────

async def rules_due_for_verification(
    older_than_days: int = 0, never_only: bool = False,
) -> dict:
    """Which standing rules assert a FACT that nobody has confirmed lately.

    A rulebook holds two kinds of thing. Most rules are DECISIONS — how the
    operator wants to work. They have no truth value and cannot rot. A few
    assert a fact about someone else's software: what a CI runner does, which
    tools exist, what a setting is currently set to. Those go false silently,
    with nobody present, and they keep being handed to every session as
    binding instructions long after they stopped being true.

    This lists the second kind, oldest verification first, never-checked at
    the top. Each row carries the rule's `verify_with` in full — you are
    about to go and run it — plus `expires_when`, and `days_since_verified`.

    Reach for it when you are curating the rulebook, when a rule's advice
    just contradicted what you observed, or periodically. Then, for each row:
    run the check, and call mark_rule_verified with what you found.

    Rules with no `verify_with` never appear here. That is correct: they are
    decisions, and there is nothing to go and check. Do not "fix" their
    absence by giving them checks — the list is only worth reading while
    everything on it genuinely can go false.

    Args:
        older_than_days: only rules last verified longer ago than this.
            Never-checked rules always qualify. 0 = no age filter.
        never_only: only rules nobody has ever verified.

    NOT filterable by project, deliberately: a project is bound by its own
    rules AND every global rule, and a filter that dropped the global ones
    would UNDER-report — which is the exact failure this whole surface exists
    to prevent. Read the whole list.
    """
    uid = current_user_id()
    rules = await rulebooks_svc.rules_due_for_verification(
        uid, older_than_days=older_than_days, never_only=never_only,
    )
    return {
        "rules": [rulebooks_svc.verification_row(r) for r in rules],
        "total": len(rules),
    }


async def mark_rule_verified(rule_id: int, still_true: bool = True) -> dict:
    """Record that you ran a rule's check — and what it said.

    Call this AFTER actually running the rule's `verify_with`, never on the
    strength of the rule sounding plausible. A stamp nobody earned is worse
    than no stamp: it moves the rule to the bottom of the sweep and buys it
    another long silence.

    `still_true=False` writes NOTHING. A rule whose check failed is not in a
    special state to be recorded — it is WRONG, and the only honest next
    moves are to correct it, retire it, or find out why. So it stays at the
    top of the sweep until someone deals with it, and the response tells you
    what the rule said would end it.

    Args:
        rule_id: the rule whose check you ran.
        still_true: True if the check passed. False if the fact it asserts is
            no longer true — say so, that is the outcome worth having.
    """
    uid = current_user_id()
    rule = await rulebooks_svc.mark_rule_verified(rule_id, uid, still_true)
    if rule is None:
        raise ValueError(
            f"rule {rule_id} not found, or carries no verify_with "
            f"(nothing to verify is not the same as verified)"
        )
    data = await rulebooks_svc.rule_detail(uid, rule)
    if still_true:
        data["verified"] = True
        return data
    data["verified"] = False
    data["next"] = (
        "This rule is no longer true and is still binding on every session "
        "that loads it. Correct it with update_rule, retire it with "
        "delete_rule, or open a task to work out what replaced it. Its "
        "verified_at is deliberately untouched, so it stays at the top of "
        "rules_due_for_verification until one of those happens."
    )
    return data


def register(mcp) -> None:
    for fn in (
        list_rulebooks, get_rulebook, create_rulebook, update_rulebook, delete_rulebook,
        list_topics, create_topic, update_topic, delete_topic,
        list_rules, get_rule, rule_outcome,
        create_rule, create_project_rule, update_rule, move_rule, delete_rule,
        create_preference, update_preference,
        relate_rules, unrelate_rules,
        rules_due_for_verification, mark_rule_verified,
        rule_history,
    ):
        mcp.tool(name=fn.__name__)(fn)