From 5f96545ae11a414269172502afb531f8478999d8 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Wed, 21 Oct 2026 20:28:23 -0400 Subject: [PATCH] docs(6205): record_refs and moment_delivery comments drop record and milestone citations record_refs states why a guessed id is refused without quoting the operator; moment_delivery's docstrings name what each door does without the milestone and step that built it. Co-Authored-By: Claude Opus 5.5 --- src/scribe/services/moment_delivery.py | 16 ++++++++-------- src/scribe/services/record_refs.py | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/scribe/services/moment_delivery.py b/src/scribe/services/moment_delivery.py index 9402e78c..803b2108 100644 --- a/src/scribe/services/moment_delivery.py +++ b/src/scribe/services/moment_delivery.py @@ -1,4 +1,4 @@ -"""Delivering the rules mounted on a moment, through every door (milestone 458 step 4). +"""Delivering the rules mounted on a moment, through every door. One function decides what an act reaches and what arrives with it; the doors differ only in how they carry the answer: @@ -45,7 +45,7 @@ async def reachable_tools(user_id: int) -> list[str]: """ from scribe.services import rulebooks - # A moment that carries a default reply shape (milestone 500) is worth a + # A moment that carries a default reply shape is worth a # request whether or not anything is mounted on it: the shape is product, # so every install has it. shaped = {s.moment for s in reply_shapes.SHAPES.values() if s.key != reply_shapes.CORE_KEY} @@ -91,7 +91,7 @@ async def deliver_for_act( def shapes_for_act(reached: list[dict], seen: frozenset[str] = frozenset()) -> tuple[list[str], dict[str, str]]: - """The default reply shapes riding the moments this act reached (milestone 500). + """The default reply shapes riding the moments this act reached. Closing a task comes just before a completion report, a structured question is an ask, opening a plan comes before a plan is put up for @@ -114,7 +114,7 @@ async def deliver_for_turn( user_id: int, *, seen: frozenset[str] = frozenset(), project_id: int | None = None, exclude: frozenset[int] = frozenset(), held: frozenset[int] = frozenset(), ) -> dict: - """What every turn carries before its reply is written (milestone 500 step 3). + """What every turn carries before its reply is written. The core reply shape — in full once per session and again after a compaction (the ledger is swept then), otherwise its one-line reminder — @@ -147,7 +147,7 @@ async def attach_moment_rules( ) -> dict: """Carry the rules mounted on this tool call's moments in its own response. - The MCP door (#4286's attach shape): an in-band decoration on a payload + The MCP door: an in-band decoration on a payload already being returned, fail-open, and absent when there is nothing to say. The project is the record's own when it has one, else the caller's argument — a project's mounted rules belong to work in that project. @@ -184,7 +184,7 @@ async def attach_moment_rules( # ── The reply moment: the backstop at the end of a turn ───────────────── # -# The Stop hook's door, folded in from milestone 456 step 8. A reply is the +# The Stop hook's door. A reply is the # one act no tool call marks, and the moment where "please verify this on # your end" gets said — so it is checked twice over: the rules MOUNTED on the # reply moments (deterministic, somebody said they belong here), and the @@ -229,7 +229,7 @@ def _reply_query(reply: str) -> str: def reply_hold_reason(held: list[dict]) -> str: """The text the agent reads INSTEAD of its reply going out. - A practice, not a prohibition (rule 165), on the act checkpoint's model: + A practice, not a prohibition, on the act checkpoint's model: nothing here knows the reply is wrong. It names each rule with why it was raised, gives the remedy as one call per rule, and says the reply may go out unchanged — so a reader who finds the rules beside the point is out in @@ -245,7 +245,7 @@ def reply_hold_reason(held: list[dict]) -> str: parts.append(f"“{item['title']}” ({why}{trigger}) — get_rule({item['rule_id']})") noun = "a standing rule" if len(held) == 1 else "standing rules" # A mount that does not bear on this reply is a misfire worth one call: - # reports gather into an unmount proposal for the operator (step 7b). + # reports gather into an unmount proposal for the operator. mounted = [item for item in held if item.get("moment")] misfire = ( " If one mounted on a moment has nothing to do with this reply, " diff --git a/src/scribe/services/record_refs.py b/src/scribe/services/record_refs.py index e2389eb5..d476819a 100644 --- a/src/scribe/services/record_refs.py +++ b/src/scribe/services/record_refs.py @@ -1,6 +1,6 @@ """Record references written into prose: refusing guessed ids, resolving placeholders, reading the ids a message names. -THE DEFECT THIS EXISTS FOR (#4016) +THE DEFECT THIS EXISTS FOR A session about to create several records guesses the ids they will get — the last id it saw, plus one, plus two — and writes those guesses into a plan body @@ -17,8 +17,8 @@ Two halves, and they are not alternatives: rewrites the placeholders inside ONE transaction, so there is no moment at which an id has to be predicted. - REFUSING A GUESSED ID is the backstop for a session that guesses anyway. It - is a refusal, not a warning, because a warning is an instruction and the - operator's point was exactly that instructions are not always followed. + is a refusal, not a warning, because a warning is an instruction and + instructions are not always followed. HOW A GUESS IS RECOGNISED @@ -131,12 +131,12 @@ def resolve_placeholders(text: str | None, refs: dict[str, str]) -> str | None: return PLACEHOLDER_RE.sub(lambda m: refs[m.group(1)], text) -# ── Records an operator names in a message (#4796) ───────────────────────── +# ── Records an operator names in a message ───────────────────────────────── # -# "yes go ahead with 4448" says exactly which record is meant, and the prompt -# menu could not use it: a number carries no meaning to an embedding, so the -# menu filled with whatever resembled the words AROUND it. These ids are looked -# up directly instead (plugin_context.build_autoinject_hint). +# "yes go ahead with 4448" says exactly which record is meant, and a ranked +# menu cannot use it: a number carries no meaning to an embedding, so the menu +# fills with whatever resembles the words AROUND it. These ids are looked up +# directly instead (plugin_context.build_autoinject_hint). # # A guard against a false READ, not a false lookup. A number that is not a # record id still has to resolve to a record this user can open before anything