docs(agents): make boundary-only type validation an invariant

[gbrlcustodio]

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 isinstance guard 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:

• Internal code trusts its annotations; a type checker is the enforcement mechanism, not runtime guards.
• Runtime checks are warranted only where untyped or external data crosses into typed code: MCP tool signatures, and the nested un-schema'd values of dict-typed args (which is why validate_report_cards_filter's checks are legitimate and normalize_label_color's would not be).

Testing

Docs-only change. No code paths affected.

[adriannoes]

Clear, well-motivated docs change.

The invariant matches how the codebase already behaves: scalar args are coerced at the MCP shell (color: str via FastMCP/pydantic), SDK planners like normalize_label_color trust the annotation, and nested JSON under dict-typed args is where runtime shape checks (validate_report_cards_filter) legitimately live. CI is green; nothing blocking merge.

Static review only (docs-only diff).

Also noted

** CLI as a boundary peer:** The MCP example lands well. Since the same SDK planners are called from CLI (color: str on Typer options in pipefy_cli), a short parallel note that CLI signatures are the same kind of trust boundary would keep MCP/CLI parity reviews aligned — optional polish, not a merge blocker.

[gbrlcustodio]

Added in 5aeb430: a parallel bullet noting the CLI command signature (Typer options like color: str in pipefy_cli) is the same trust boundary as the MCP signature, with the same SDK planners running behind it. Keeps the MCP/CLI parity framing aligned. Thanks for the catch.