Merge pull request 'feat(telemetry): tell a ranker decline from a repeat before the observation window opens (#3497)' (#139) from dev into main

plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "scribe",
   "description": "Scribe system-of-record for Claude Code: MCP tools over your notes/tasks/projects/rules, a session-start push channel that surfaces your always-on rules + active-project context, process-skills (writing-plans, systematic-debugging, verification, brainstorming, reusing-code), and your saved Scribe Processes auto-surfaced as skills (/scribe:sync). Replaces superpowers + file-memory with one app-backed plugin.",
-  "version": "2026.09.04.0140",
+  "version": "2026.09.03.0329",
   "author": {
     "name": "Bryan Van Deusen"
   },

plugin/hooks/scribe_static_context.md

@@ -21,16 +21,6 @@ for the operator's work, and as your own working memory across sessions.
   compaction — call `list_always_on_rules()` (and `enter_project()` when a
   project is in scope) BEFORE acting. When a loaded rule and a default habit
   disagree, the rule wins; if no rule speaks to it, ask rather than assume.
-- **What you loaded is not all of the rules.** Only the always-on tier arrives
-  that way; conditional rules are RETRIEVED, and one you were never handed
-  binds exactly as hard. So before a consequential act, `search` for a rule
-  about it (`content_type="rule"`) rather than concluding from an empty
-  loaded set that nothing applies. "I was not told" is not the same as "there
-  is no rule," and only one of those is checkable.
-  This bites hardest on which TOOL to reach for — curling an API that has an
-  MCP client, standing up a local stack, running a suite CI owns. Those feel
-  like mechanics rather than decisions, so they raise no doubt and generate no
-  query; the moment you are most confident is the moment to look.
 - **Recall before acting** — before you answer anything about the operator's
   work or start a task, `search` Scribe first; assume a related note, task, or
   decision already exists. Concretely, reach for recall whenever a request

plugin/skills/using-scribe/SKILL.md

@@ -56,31 +56,10 @@ Two constraints on *how* that's achieved:
    re-deriving it or opening a duplicate. When a project is in scope, pass its
    `project_id` so results stay scoped.
 
-2. **Standing rules are binding — and the ones you were handed are not all of
-   them.** Load the resident set via `list_always_on_rules()` at session start
-   (see "Do this first"); treat every one as binding. Pull a rule's full
-   statement with `get_rule(id)` when it's about to bite. When a project is in
-   scope, `enter_project(id)` also returns its applicable rules.
-
-   Rules come in two tiers. **Always-on** rules are delivered — they arrive
-   whether or not you ask. **Conditional** rules are RETRIEVED, and one binds
-   just as hard for never having been handed to you. So before a consequential
-   act, `search(content_type="rule")` on what you are about to do. An empty
-   loaded set is not evidence that no rule applies; it is only evidence that
-   none was pushed, and those are different claims.
-
-   The tier split exists because delivery does not scale: every resident rule
-   costs tokens in every session forever, so a rulebook that grows past a few
-   dozen either stops growing or stops fitting. Retrieval is what lets the
-   rulebook keep growing — but retrieval only fires if something asks.
-
-   **Ask hardest where you feel most certain.** Rules about which TOOL to reach
-   for — use the forge's MCP client rather than curling its API, don't stand up
-   a local stack, don't run the suite CI owns — govern moves that feel like
-   mechanics rather than decisions. A reflex raises no doubt, so it generates
-   no query, so the rule that would have stopped it is never retrieved. That is
-   the failure this instruction exists to prevent, and confidence is its only
-   warning sign.
+2. **Standing rules are binding.** Load them via `list_always_on_rules()` at
+   session start (see "Do this first"); treat every one as binding. Pull a
+   rule's full statement with `get_rule(id)` when it's about to bite. When a
+   project is in scope, `enter_project(id)` also returns its applicable rules.
 
 3. **Update over duplicate.** When recording, prefer updating an existing
    note/rule/task over creating a new one. Search first; revise what's there.

src/scribe/mcp/server.py

@@ -45,31 +45,6 @@ from quart import Quart
 # The accepted cost: an agent that never opens create_note's docstring never
 # learns the field exists. Guidance lives in the create_note / update_note
 # docstrings and the using-scribe skill instead.
-#
-# Milestone 333 step 3 (2026-09-04) bought the HOW bullet's second clause —
-# search(content_type="rule") before a consequential act — by TRADING OUT
-# "Processes are saved procedures (follow verbatim)" and "Deletes are
-# trash-recoverable". Recorded so the trade is not silently reversed:
-#   - Both were already in test_instruction_surfaces_agree's DISPLACED_TOPICS
-#     and already stated on a delivered surface, so nothing fell off: the
-#     process reflex is in every scribe-proc-* skill listing (each says the
-#     process governs and is followed verbatim), and trash recovery is in the
-#     delete_*/list_trash/restore docstrings, which is where per-tool guidance
-#     belongs by this block's own doctrine.
-#   - What it bought is not per-tool guidance and has nowhere else to live at
-#     session-start altitude. Rules were retrievable only by RESIDENCY: the
-#     always-on preload put them in front of the agent, and nothing told a
-#     session to go looking for one it had not been handed. The tier split is
-#     therefore load-bearing on ANY install (rule 115): a delivered rule costs
-#     tokens in every session forever, so a rulebook that only delivers cannot
-#     grow past what one session can hold, and every rule worth keeping has to
-#     become resident to bind at all. Retrieval is what lets it keep growing —
-#     and retrieval fires only if something asks, which nothing told a session
-#     to do. A tool-choice reflex asks least of all (#3476, #161).
-#   - This states the PULL for conditional rules, exactly as the surrounding
-#     line states it for always-on ones. Rule 119 makes these surfaces the
-#     specification, so the same sentence lands on all three session-start
-#     surfaces, and test_instruction_surfaces_agree pins it.
 _INSTRUCTIONS = """
 Scribe is the operator's self-hosted second brain and system of record — and
 yours: recall from it before acting, record as you go. Keep no parallel copy
@@ -88,13 +63,13 @@ Hierarchy: Project -> Milestone -> Task/Note. The map, by purpose:
   active project_id to stay in scope.
 - WHERE work happens: Systems. Tag records with system_ids as you write;
   create_system when the area is unmodelled.
-- HOW: rules bind. list_always_on_rules() at start; before a consequential
-  act, search(content_type="rule") — the resident set is not all of them.
+- HOW: rules are binding — list_always_on_rules() at session start.
 - UI: the project's design system is binding — resolve_design_system /
   get_design_system_stylesheet before hand-writing a value.
 - REUSE: search snippets before writing a helper; record what you build with
   create_snippet; classify shapes against canon (classify_shapes) — a
-  consumer map is rows, never prose.
+  consumer map is rows, never prose. Processes are saved procedures (follow
+  verbatim). Deletes are trash-recoverable.
 
 A task is a note with status (*_note vs *_task tools).
 Creates are duplicate-gated: a near-match BLOCKS and returns the existing

src/scribe/mcp/tools/rulebooks.py

@@ -315,61 +315,6 @@ async def create_rule(
 ) -> 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.
-
-    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 three
-    answers, and make the middle one 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, the tier, 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.
-      * "NO" — let it go. If the observation is still worth keeping, it is a
-        note (create_note): recorded, findable, and binding on nobody.
-
-    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 three options out as three options. 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 shared by every project that gets the rulebook: an
     always_on rulebook binds ALL your projects; a subscribed rulebook binds the
     projects that opt in. So a rulebook rule must read as a general standard —
@@ -488,16 +433,6 @@ async def create_project_rule(
     the rule is returned in get_project's applicable_rules (under
     project_rules) and in list_rules(project_id=...).
 
-    PROPOSE, THEN WRITE ON A YES — create_rule's opening carries the whole
-    loop: 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 / 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);

tests/test_instruction_surfaces_agree.py

@@ -195,46 +195,6 @@ def test_displaced_topics_live_on_a_delivered_surface():
     )
 
 
-# The SECOND pull (milestone 333 step 3). `list_always_on_rules()` fetches the
-# resident tier; this one says that tier is not all of them, and that a
-# conditional rule has to be gone looking for. However a surface words the
-# surrounding prose, it names the call.
-RETRIEVE = 'content_type="rule"'
-
-
-def test_every_session_start_surface_states_the_conditional_retrieval():
-    """The push/pull asymmetry, one level in.
-
-    The tests above pin that a session PULLS the resident rules rather than
-    trusting the SessionStart push. This pins the same shape between the two
-    TIERS: an always-on rule is delivered, a conditional one is retrieved, and
-    a surface that states only the first leaves a session reading its loaded
-    set as the whole rulebook.
-
-    That reading is wrong in the direction that costs something. "Nothing was
-    pushed" and "no rule applies" are different claims, and only one of them
-    has been checked — the same asymmetry as #2198, now between tiers instead
-    of between channels.
-
-    It is also what made the always-on tier the only one that worked, on any
-    install rather than this one (rule 115). A rule nothing retrieves has to be
-    resident to bind at all, so every rule worth keeping becomes resident; and
-    a resident rule costs tokens in every session forever, so a rulebook that
-    only delivers cannot grow past what one session can hold. Retrieval is what
-    lifts that ceiling — and it only fires if something asks.
-    """
-    missing = []
-    for path in SESSION_START_SURFACES:
-        if RETRIEVE not in path.read_text():
-            missing.append(str(path.relative_to(ROOT)))
-    assert not missing, (
-        f"these surfaces state the always-on pull but never tell the agent to "
-        f"retrieve a conditional rule ({RETRIEVE}): {missing}. A session that "
-        f"reads its loaded set as the whole rulebook will act on \"I was not "
-        f"told\" as if it meant \"there is no rule\" (milestone 333 step 3)."
-    )
-
-
 def test_no_surface_names_the_push_without_stating_the_pull():
     """The exact shape #2497 took.
 

tests/test_rule_creation_asks_first.py

@@ -1,120 +0,0 @@
-"""Both rule-creation tools run the propose-then-approve loop (#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 belongs at the tool, because the tool is the last surface a
-caller reads before the write, and because the write is less reversible than
-it looks. The operator's yes is not merely consent; it is the one moment the
-rule is certainly IN FRONT of them. Afterwards it may not be again for
-months: a conditional rule is not read aloud at session start, and a
-project-scoped rule does not appear in an unfiltered `list_rules()` at all.
-The proposal IS the review, so there had better be one.
-
-WHY IT IS PHRASED AS A PRACTICE AND NOT A PROHIBITION
-
-The first cut of this guidance opened "NOT YOURS TO CALL UNPROMPTED." That is
-the wrong instrument, and the failure it invites is worse than the one it
-prevents: a caller reading a prohibition stops NOTICING rule-shaped things,
-rather than noticing them and asking. The wanted behaviour is more proposals,
-not fewer — spotting that something has hardened into a standing instruction
-is valuable work, and the only step that was ever missing came after it.
-
-So the docstrings describe what to DO: propose readily, state four things,
-close with a question the operator answers in one word. This test is written
-the same way — it asserts the parts of the loop are present, and has nothing
-to say about any wording that forbids.
-
-The fourth element — how the rule would be ENFORCED — is not ceremony. It is
-the part that sometimes dissolves the rule: a thing a test can assert should
-be that test, and a rule is what is left 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 element matches a family of synonyms, so the prose
-stays 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 proposes. 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 loop, element by element, 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 hold by accident ("why", "how", "reason", "rule"), which
-# would let the assertion pass on prose that says nothing of the kind.
-_ELEMENTS = {
-    "the invitation to propose": ("propose", "proposal"),
-    "the operator's approval": ("approve", "approval", "says yes", "a yes"),
-    "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",),
-    "the answers offered back": ("as written", "talk about it", "discuss"),
-}
-
-
-@pytest.mark.parametrize(("module", "name"), _SURFACES)
-@pytest.mark.parametrize("element", sorted(_ELEMENTS))
-def test_a_rule_surface_carries_every_part_of_the_proposal_loop(
-    module, name, element
-):
-    """Each element of propose → state four things → ask survives."""
-    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, and the proposal is the one moment that rule is certain to "
-        f"be seen by the operator. Say it in whatever words you like; this "
-        f"guard only checks it is still said. See create_rule's opening."
-    )
-
-
-@pytest.mark.parametrize(("module", "name"), _SURFACES)
-def test_the_proposal_loop_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 —
-    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"
-    loop_at = min(
-        (doc.find(t) for t in _ELEMENTS["the invitation to propose"]
-         if doc.find(t) >= 0),
-        default=-1,
-    )
-    assert 0 <= loop_at < args_at, (
-        f"{name} introduces the proposal loop at or after its Args: block "
-        f"(loop {loop_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."
-    )