docs(agents): make boundary-only type validation an invariant#289
Open
gbrlcustodio wants to merge 1 commit into
Open
docs(agents): make boundary-only type validation an invariant#289gbrlcustodio wants to merge 1 commit into
gbrlcustodio wants to merge 1 commit into
Conversation
Codify that static typing is the contract for internal code and runtime isinstance guards belong only at trust boundaries (MCP tool signatures, nested values of dict-typed args), not inside internal functions. Prevents per-function defensive type checks from becoming the norm; the enforcement mechanism for internal type contracts is a type checker, not hand-written guards.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a coding-style invariant to
AGENTS.md: type validation belongs at trust boundaries, not inside internal functions.Why
A PR review (#280) flagged a missing
isinstanceguard inside a pure SDK planner (normalize_label_color). On inspection the guard was redundant: the MCP tool signature (color: str, FastMCP/pydantic-backed) already coerces and rejects the scalar at the boundary, so the planner behind it can trust its annotation. Hand-guarding every internal function reinvents dynamic typing and, once accepted, becomes the expectation everywhere.The invariant draws the line explicitly:
dict-typed args (which is whyvalidate_report_cards_filter's checks are legitimate andnormalize_label_color's would not be).Testing
Docs-only change. No code paths affected.