docs(6209): preference door, systems and notes tools, lesson surfacing, rule versions, backup round trip, JSON reader, charter search, provenance, location filter

Ten more test files: issue, milestone, rule, decision and snippet numbers
come out of docstrings, comments and messages; the preference door states
what a preference is instead of quoting the framing; the JSON reader says
why jq is not assumed instead of what every hook used to do; the backup
round trip's column warning no longer claims the import side is unguarded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 21:33:08 -04:00
co-authored by Claude Opus 5.5
parent fa41e006a7
commit ead4a7e2ad
10 changed files with 69 additions and 74 deletions
+8 -9
View File
@@ -1,14 +1,13 @@
"""The preference write path, and how it differs from a rule's (milestone 399).
"""The preference write path, and how it differs from a rule's.
WHY TWO DOORS AT ALL
`create_rule`'s docstring IS the approval gate (#3557): it tells its caller to
`create_rule`'s docstring IS the approval gate: it tells its caller to
propose, offer three answers, and wait. That is right for a rule — the person
a rule binds should have agreed to be bound.
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
A preference inverts it: it is a rule 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=..., when_to_apply="when the moment this fixture stands in for arises")` would mean reading it through the gate's prose, and
the caller would hesitate over exactly the act this kind exists to make
routine.
@@ -18,7 +17,7 @@ So the asymmetry is the product, and these tests pin it.
TWO PRESENCE CHECKS, NEVER AN ABSENCE
The tempting guard is "create_preference's docstring does NOT run the approval
loop". That is the shape snippet #3352 warns against: an absence check passes
loop". That is a trap: an absence check passes
against a docstring that has been deleted, emptied, or rewritten into
something else entirely, and it reads as coverage while proving nothing.
@@ -35,7 +34,7 @@ from tests.helpers import fake_rule, plain_rule_detail as _plain_detail
from tests.helpers import tool_doc as _doc
# The tool layer reads its caller from a ContextVar the HTTP transport sets.
# With no request in flight, the module binds it itself (snippet #2836).
# With no request in flight, the module binds it itself.
pytestmark = pytest.mark.usefixtures("_bind_user")
MODULE = "scribe.mcp.tools.rulebooks"
@@ -176,7 +175,7 @@ def test_the_preference_door_says_to_write_it():
"""Half two. The inverting instruction has to be PRESENT, not merely
unaccompanied by a gate.
An agent that has internalised #3557 will hesitate to write or rewrite a
An agent that has internalised the rule gate will hesitate to write or rewrite a
preference unless told plainly that this door is different. Silence here
does not read as permission — it reads as an omission, and the caller
falls back on the behaviour it already knows.
@@ -194,7 +193,7 @@ def test_the_preference_door_says_to_write_it():
def test_the_preference_door_names_the_force_distinction():
"""The routing test, stated positively (rule 165).
"""The routing test, stated positively.
The confusion this milestone exists to fix is that a session cannot tell
which kind it is holding. If the docstring stops drawing the line, the