feat(instructions): fit the delivery fold — 2k server map, floor Systems reflex, write-time systems_hint
CI & Build / Python lint (push) Successful in 3s
CI & Build / Plugin hooks (push) Successful in 7s
CI & Build / integration (push) Successful in 18s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 47s
CI & Build / Build & push image (push) Successful in 28s

Claude Code injects only the first ~2,048 chars of an MCP server's
instructions and silently cuts the rest mid-word (#2562, observed live):
_INSTRUCTIONS was 20,002 chars, so ~90% — including all Systems tagging
guidance — never reached any session. Rearchitect delivery around what
each surface actually delivers:

- _INSTRUCTIONS becomes a 1,997-char purpose-sorted map, with a header
  comment stating the budget and where detail belongs instead.
- Tool docstrings keep the per-tool HOW (audit: nearly all displaced
  topics were already duplicated there); backfill the four gaps —
  enter_project session scoping + project bootstrap, create_rule
  entity-vs-rule test, create_design_system not-a-rulebook,
  create_system two-records test.
- The plugin static context (the delivery floor) gains the
  tag-to-Systems reflex and a surfaces-layering statement; plugin
  0.1.25 -> 0.1.26 so the executing cache refreshes (#2209).
- create_task / create_note / create_snippet return a systems_hint when
  a record is created untagged in a project that has Systems — in-band
  at the exact write it applies to, fail-open like the dedup gate.
- Guards: _INSTRUCTIONS length budget, floor-states-the-reflex, and a
  displaced-topics sweep asserting every cut topic still lives on a
  delivered surface.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-09 12:53:35 -04:00
co-authored by Claude Fable 5
parent 272b7dbddf
commit 3ff8803593
12 changed files with 304 additions and 300 deletions
+31
View File
@@ -16,6 +16,30 @@ from scribe.mcp._context import current_user_id
from scribe.services import systems as systems_svc
async def untagged_systems_hint(user_id: int, project_id: int) -> str | None:
"""Nudge text for a record created untagged in a project that has Systems.
Not a tool. create_task / create_note / create_snippet attach this to
their responses so the tagging question arrives in-band at the exact write
it applies to — instruction prose alone demonstrably doesn't fire at write
time, while in-band behavior (the duplicate gate) does (#2562).
"""
# Fail-open like the dedup gate: a hint must never break a create.
try:
systems = await systems_svc.list_systems(user_id, project_id)
except Exception:
return None
if not systems:
return None
names = ", ".join(f"#{s.id} {s.name}" for s in systems)
return (
f"Created untagged. This project's Systems: {names}. If this record is "
"about one of those areas, tag it (update it with system_ids=[...]); if "
"its area is missing, create_system it and tag; if it is about no "
"particular area, leave it untagged."
)
async def create_system(
project_id: int,
name: str,
@@ -27,6 +51,13 @@ async def create_system(
Associate records with it via the `system_ids` arg on create/update_task and
create/update_note.
Create one the moment two records would share an area that has no System
yet — the same two-or-more test snippets use. Don't wait to be asked to
name an area that plainly exists in the code; an unmodelled area means
every record about it stays untaggable. Give it a one-paragraph charter,
not just a label: the description is what tells a later session whether a
record belongs here.
Args:
project_id: The project this system belongs to (required).
name: Short label (required).