Skip to main content

Pre-Commit Test Validation Hook

Validates CODITECT framework components before commit with quick quality checks.

Purpose​

The pre-commit test validation hook ensures code quality before commits by:

  1. Syntax Validation - Python files compile without errors
  2. Frontmatter Checks - YAML frontmatter is valid and complete
  3. Security Scan - No secrets or dangerous commands
  4. Naming Conventions - Files follow kebab-case naming
  5. Registry Consistency - New components are registered

Priority: P0 - Critical for preventing broken commits Impact: Catches issues before they enter version control

Trigger​

Event: git commit (before commit is created) Blocking: Yes - Commit fails if validation fails Timeout: 60 seconds (quick validation mode)

Validation Checks​

Quick Mode (Default)​

CheckCategoryTime
Python syntaxSCRIPTS2s
YAML frontmatterAGENTS, COMMANDS3s
JSON validityCONFIG2s
Secret patternsSECURITY5s
Name conventionsCONSISTENCY2s

Full Mode (--full flag)​

All quick checks plus:

  • Markdown link validation
  • Cross-reference integrity
  • Coverage threshold check
  • Complete registry validation

Installation​

Step 1: Create Hook Script​

Create .git/hooks/pre-commit:

#!/bin/bash
# CODITECT Pre-Commit Test Validation Hook
# Validates framework components before commit

set -e

# Configuration
CODITECT_ROOT="$(git rev-parse --show-toplevel)"
TEST_SCRIPT="${CODITECT_ROOT}/scripts/test-suite.py"
TIMEOUT=60

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

echo -e "${YELLOW}Running CODITECT pre-commit validation...${NC}"

# Check for bypass
if [ -n "$SKIP_TESTS" ]; then
    echo -e "${YELLOW}Skipping tests (SKIP_TESTS set)${NC}"
    exit 0
fi

# Get staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)

# Check if any framework files changed
FRAMEWORK_PATTERNS="agents/|commands/|skills/|scripts/|hooks/|config/"
FRAMEWORK_FILES=$(echo "$STAGED_FILES" | grep -E "$FRAMEWORK_PATTERNS" || true)

if [ -z "$FRAMEWORK_FILES" ]; then
    echo -e "${GREEN}No framework files changed, skipping validation${NC}"
    exit 0
fi

# Run quick validation
echo "Validating changed framework components..."
cd "$CODITECT_ROOT"

# Run test suite in quick mode
if timeout $TIMEOUT python3 "$TEST_SCRIPT" --quick --staged-only 2>&1; then
    echo -e "${GREEN}All validations passed${NC}"
    exit 0
else
    echo -e "${RED}Validation failed!${NC}"
    echo ""
    echo "To bypass (use sparingly): SKIP_TESTS=1 git commit"
    echo "To see full results: python3 scripts/test-suite.py"
    exit 1
fi

Step 2: Make Executable​

chmod +x .git/hooks/pre-commit

Step 3: Test Installation​

# Should run validation
git commit --allow-empty -m "test: Verify pre-commit hook"

# Should show validation output

Configuration​

Environment Variables​

VariableDefaultDescription
SKIP_TESTSunsetSkip all validation
QUICK_MODE1Use quick validation
TIMEOUT60Max execution time
VERBOSEunsetShow detailed output

Timeout Adjustment​

# For slower systems
export CODITECT_HOOK_TIMEOUT=120

Selective Validation​

# Validate only specific categories
export CODITECT_CATEGORIES="AGENTS,COMMANDS"

Bypass​

One-Time Skip​

# Skip for single commit (emergency only)
SKIP_TESTS=1 git commit -m "fix: Emergency hotfix"
# Disable hook entirely
git config core.hooksPath /dev/null

# Re-enable
git config --unset core.hooksPath

Commit Message Skip​

# Include [skip-tests] in message
git commit -m "docs: Update README [skip-tests]"

Examples​

Successful Validation​

$ git commit -m "feat: Add new agent"

Running CODITECT pre-commit validation...
Validating changed framework components...

[AGENTS] Validating agents/new-agent.md
  ✅ Frontmatter valid
  ✅ Required fields present
  ✅ Name matches filename

[SECURITY] Scanning for secrets
  ✅ No secrets detected

[CONSISTENCY] Checking naming conventions
  ✅ Kebab-case naming valid

All validations passed ✅
[main abc1234] feat: Add new agent
 1 file changed, 50 insertions(+)

Failed Validation​

$ git commit -m "feat: Add new agent"

Running CODITECT pre-commit validation...
Validating changed framework components...

[AGENTS] Validating agents/NewAgent.md
  ❌ FAIL: Filename not kebab-case (expected: new-agent.md)

[AGENTS] Validating agents/broken-agent.md
  ❌ FAIL: Missing required field 'name' in frontmatter

Validation failed!
2 errors found

To bypass (use sparingly): SKIP_TESTS=1 git commit
To see full results: python3 scripts/test-suite.py

Troubleshooting​

Hook Not Running​

Symptom: Commits proceed without validation Solution:

# Check hook exists and is executable
ls -la .git/hooks/pre-commit

# Verify not bypassed
echo $SKIP_TESTS  # Should be empty

# Check core.hooksPath
git config core.hooksPath

Timeout Issues​

Symptom: Hook fails with timeout Solution:

# Increase timeout
export CODITECT_HOOK_TIMEOUT=120

# Or use quick mode only
export QUICK_MODE=1

Python Not Found​

Symptom: python3: command not found Solution:

# Check Python installation
which python3

# Update hook to use full path
sed -i 's|python3|/usr/bin/python3|g' .git/hooks/pre-commit

False Positives​

Symptom: Valid code fails validation Solution:

# Run full test suite to debug
python3 scripts/test-suite.py --verbose

# Check specific file
python3 scripts/test-suite.py --file agents/problem-agent.md

Performance​

ModeFilesTime
Quick (1-5 files)Staged only5-10s
Quick (10+ files)Staged only15-30s
FullAll files30-60s

Optimization Tips:

  • Use --staged-only for incremental validation
  • Enable parallel validation for large commits
  • Cache unchanged file results

Implementation Files​

  • .git/hooks/pre-commit - Hook script
  • scripts/test-suite.py - Test execution engine
  • test-results/ - Output directory

Changelog​

v1.0.0 - December 10, 2025​

  • Initial implementation
  • Quick mode validation
  • Staged-only file filtering
  • Bypass mechanisms
  • Performance optimization

Status: Production Ready Owner: Testing Specialist Agent Copyright: 2025 AZ1.AI Inc. All Rights Reserved