[CI/CD] Add tool documentation validation to pre-commit

[dougborg]

Overview

Integrate documentation validation into the pre-commit workflow to catch errors before they're committed.

This completes Phase 1 of ADR 003.

Context

See ADR 003 for full context: docs/architecture/decisions/003-automated-tool-documentation.md

Scope

Add pre-commit hook that runs documentation validation on modified tool files.

Implementation

1. Pre-commit Configuration

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: validate-tool-docs
        name: Validate Tool Documentation
        entry: uv run python scripts/validate_tool_docs.py
        language: system
        files: stocktrim_mcp_server/src/stocktrim_mcp_server/tools/.*\.py$
        pass_filenames: true

2. Performance Requirements

• Validation should run only on modified tool files
• Total validation time < 2 seconds for typical commits
• Clear, actionable error messages
• Exit with error code 1 if validation fails

3. Error Handling

When validation fails, show:

• Which file failed
• Which validation rule failed
• Specific location in code (file:line)
• How to fix the issue

Example output:

❌ Tool documentation validation failed:

File: stocktrim_mcp_server/src/stocktrim_mcp_server/tools/foundation/products.py
Tool: delete_product
Error: Tool uses elicitation but missing 🔴 HIGH-RISK indicator

Fix: Add 🔴 HIGH-RISK OPERATION to the docstring summary line.

Tasks

• Add pre-commit hook configuration
• Test hook runs only on modified tool files
• Verify hook blocks commits with invalid documentation
• Verify performance < 2 seconds
• Document in contributing guide
• Update CI/CD to run validation on all files

Acceptance Criteria

• Pre-commit hook runs automatically on tool file changes
• Validation errors block commits
• Clear error messages guide developers to fixes
• Fast execution (< 2 seconds for typical commits)
• CI/CD runs full validation on all tools
• Documentation updated in contributing guide

Testing Plan

1. Modify tool with invalid documentation
2. Attempt to commit
3. Verify pre-commit blocks commit
4. Verify error message is clear
5. Fix documentation
6. Verify commit succeeds
7. Verify performance is acceptable

Dependencies

• Blocks: [Feature] Implement tool documentation validation #87 (validation implementation)
• Requires: Validation script from [Feature] Implement tool documentation validation #87 to be complete
• Requires: [ADR] Document automated tool documentation strategy #85 (ADR 003) for context

Related

• ADR 003: Documents validation strategy (Phase 1 completion)
• Issue [Feature] Implement tool documentation validation #87: Implements the validation script we're integrating
• Issue [Feature] Implement tool documentation generation CLI #88: Optional - generation CLI that can fix validation errors

Labels

enhancement