Preflight Validation and AI-Specific Error Guidance

[tercel]

[Problem]
When an AI agent provides invalid parameters, it usually results in an execution failure that is costly and slow. Furthermore, standard error messages (like "Invalid Type") are often too cryptic for an LLM to self-correct and retry effectively.

[Why]
Efficiency in AI interactions is measured by "successful outcomes per token." By allowing "Preflight" checks, we can catch errors in milliseconds without invoking heavy business logic. Providing "AI Guidance" in errors allows the LLM to understand how to fix its mistake.

[How]

• Executor.validate(): Implemented a non-destructive preflight method that runs Steps 1–6 (Validation, ACL, etc.) and returns a PreflightResult.
• AI Error Fields: Enhanced the error hierarchy with retryable, ai_guidance, and suggestions fields.
• Intent Metadata: Standardized x-when-to-use and x-common-mistakes metadata keys to give LLMs explicit context on module usage.