feat(notes): a note's check is writable through both doors, and empty means empty (#3164, milestone 317 step 2)
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 14s
CI & Build / TypeScript typecheck (push) Successful in 38s
CI & Build / integration (push) Successful in 32s
CI & Build / Python tests (push) Failing after 49s
CI & Build / Build & push image (push) Skipped

The rules path's three lessons (#3096), inherited:

EMPTY MEANS NULL. The sweep's whole signal is `verify_with IS NULL` = "this is
a decision, there is nothing to go and check". A "" that is not NULL makes a
norm look like a constraint nobody has verified — and never-checked sorts
FIRST, so it would sit at the top of the sweep forever.

CLEARING IS EXPLICIT. At the MCP door "" means "leave this alone", so an agent
updating a body does not wipe a check it was never asked about — which leaves
no value meaning "remove it". `clear` names the field, and naming it cannot
happen by accident. The REST door, where a cleared form input arrives as "",
reaches the same place through normalisation: two idioms, one outcome.

THE STAMP CERTIFIES A CHECK, NOT A RECORD. Rewrite or clear `verify_with` and
`verified_at` is dropped, so the note re-enters the sweep. A note wrongly
listed as due costs one look; a note wrongly vouched for costs exactly what
the sweep exists to catch. `verified_at` is also no longer settable through an
ordinary edit — a stamp says somebody performed THIS check, and minting one
from a write that ran no check is the one thing that would make the sweep lie.

And one this path adds: not every record may carry a check. A task's decay is
its status — a done issue records what happened rather than asserting
something that can go false — and a snippet already has verify_snippet, which
compares its recorded location and code against the repo and expires its own
verdict. Both are refused with a message naming the alternative, never dropped
silently (minted_kind's reasoning, #3129), and the gate lives at the service
so the two doors cannot come to disagree.

Written as an INVARIANT over the resulting record, not a filter on which
fields were passed. That is what catches the sideways route — a checked note
being turned into a task, a write that names no check at all and would sail
past any per-field gate.

The MCP docstrings carry the norm-vs-constraint test, because at that door the
docstring IS the contract and a field described only as "how to verify this"
gets filled in on every note. Step 5 does this properly across the instruction
surfaces; this is the minimum that stops the field being misused on arrival.

tests/helpers gains `drive_update_note` — the patch stack for driving
update_note, written twice before this and now once. The note-shaped fakes
gain the trio explicitly, for fake_note's own stated reason: an unset
attribute is a truthy MagicMock, and a truthy verify_with reads as a check
that is there.
This commit is contained in:
2026-08-28 15:42:12 -04:00
parent b134fe9aa1
commit 700ef20eb0
7 changed files with 398 additions and 25 deletions
+41 -3
View File
@@ -214,17 +214,53 @@ async def test_create_note_project_zero_becomes_none():
@pytest.mark.asyncio
async def test_update_note_only_sends_non_default_fields():
"""Omitted (default) fields must NOT reach the service — otherwise they'd
overwrite real data with empty strings."""
overwrite real data with empty strings.
`clear` is always forwarded and is not a field: it is how this door says
"unset these", and an empty one says "unset nothing". Same shape the rules
door took in #3096, and the same test that had to learn about it there."""
fake = fake_note()
mock = AsyncMock(return_value=fake)
with patch("scribe.mcp.tools.notes.notes_svc.update_note", mock):
await update_note(note_id=1, title="new title")
# Service got user_id, note_id positional + only the title kwarg
args, kwargs = mock.call_args
assert args == (7, 1)
assert kwargs.pop("clear") == (), "nothing was asked to be cleared"
assert kwargs == {"title": "new title"}
@pytest.mark.asyncio
async def test_update_note_forwards_a_check_but_not_an_empty_one():
""""" means "leave this alone" at this door — an agent updating a body must
not wipe a check it was never asked about (milestone 317)."""
mock = AsyncMock(return_value=fake_note())
with patch("scribe.mcp.tools.notes.notes_svc.update_note", mock):
await update_note(note_id=1, verify_with="curl the docs")
assert mock.call_args.kwargs["verify_with"] == "curl the docs"
with patch("scribe.mcp.tools.notes.notes_svc.update_note", mock):
await update_note(note_id=1, title="t")
assert "verify_with" not in mock.call_args.kwargs
@pytest.mark.asyncio
async def test_update_note_forwards_clear_so_a_check_can_be_removed():
"""The only way to unset a field at a door where "" means "leave alone"."""
mock = AsyncMock(return_value=fake_note())
with patch("scribe.mcp.tools.notes.notes_svc.update_note", mock):
await update_note(note_id=1, clear=["verify_with"])
assert mock.call_args.kwargs["clear"] == ["verify_with"]
@pytest.mark.asyncio
async def test_create_note_forwards_the_check_fields():
mock = AsyncMock(return_value=fake_note())
with patch("scribe.mcp.tools.notes.notes_svc.create_note", mock):
await create_note(title="t", verify_with="curl", expires_when="AMO changes")
assert mock.call_args.kwargs["verify_with"] == "curl"
assert mock.call_args.kwargs["expires_when"] == "AMO changes"
@pytest.mark.asyncio
async def test_update_note_empty_tags_clears_explicitly():
"""tags=[] is an explicit clear, distinct from tags=None (omit)."""
@@ -232,7 +268,9 @@ async def test_update_note_empty_tags_clears_explicitly():
mock = AsyncMock(return_value=fake)
with patch("scribe.mcp.tools.notes.notes_svc.update_note", mock):
await update_note(note_id=1, tags=[])
assert mock.call_args.kwargs == {"tags": []}
kwargs = dict(mock.call_args.kwargs)
kwargs.pop("clear")
assert kwargs == {"tags": []}
@pytest.mark.asyncio