Deepen AI review contract invariants

[dbrosio3]

This pull request introduces significant improvements to the AI review contract, prompt rendering, and validation logic. The main changes include a stricter contract for category-severity semantics, dynamic generation of prompt documentation and examples, and improved test coverage for these features. The codebase is refactored to centralize category and severity definitions, and to ensure that documentation and validation stay in sync with the contract.

AI Review Contract and Validation Enhancements:

• Added getAiReviewFindingCategorySeverity and validateAiReviewFindingSemantics functions to enforce that each finding's severity matches its category, with new validation errors reported when mismatched. [1] [2] [3] [4]
• Refactored category and severity definitions into AI_REVIEW_CATEGORY_GROUPS, and now derive AI_BLOCKING_CATEGORIES and AI_WARNING_CATEGORIES from this mapping for consistency.

Prompt Rendering and Documentation:

• Updated review-prompt.md to use template placeholders for focus areas, categories, output examples, and field documentation, which are now dynamically rendered in review-prompt.ts using the contract definitions. [1] [2] [3] [4]
• Introduced AI_REVIEW_FINDING_FIELD_PROMPT_DOCS and AI_REVIEW_OUTPUT_EXAMPLE for auto-generating up-to-date prompt documentation and JSON examples. [1] [2]

Type and API Improvements:

• Exported new types (AiReviewFindingFieldPromptDoc, AiReviewFindingKey, AiReviewTopLevelKey) and constants for better type safety and external usage. [1] [2] [3]

Code Cleanup and Refactoring:

• Removed the old validateFindingSemantics logic from review-output/normalization.ts in favor of the new centralized validation. [1] [2] [3] [4]

Test Coverage:

• Added tests to ensure category-severity validation works and that the prompt documentation and examples remain in sync with the contract. [1] [2]

These changes make the AI review contract stricter, the prompts more maintainable, and the validation logic more robust and easier to extend.