bookhoard/scripts/README.md

# Bookhoard Verification Scripts

This directory contains verification scripts that enforce compliance with PROJECT_GUIDELINES.md. These scripts serve as safety nets to catch AI (and human) violations of project standards.

## Scripts Overview

### `verify-guidelines.sh` (Comprehensive Verification)
**Purpose:** Full validation of all project guidelines including documentation compliance
**Usage:** `make verify-guidelines` or `./scripts/verify-guidelines.sh`
**Features:**
- 16 comprehensive checks covering all aspects of PROJECT_GUIDELINES.md
- High-recall pattern detection for documentation routing validation
- AI behavior protocol with multi-layered safeguards
- Warning-only approach for documentation issues (never blocks development)
- Detailed analysis of recent changes and commit quality

**Checks Included:**
1. No Custom CSS (Frontend & Styling)
2. No JavaScript Files (Use TypeScript)
3. No Secrets Committed
4. No Local Server Binaries
5. No New Migration Files
6. Go Code Quality
7. File Organization
8. Build Verification
9. Docker/Podman Files
10. Recent Commit Quality
11. Documentation Updates
12. Documentation Content Placement (High Recall)
13. Documentation Structure Validation
14. Bruno API Tests Validation
15. Recent Documentation Changes Analysis
16. Documentation Completeness Validation

### `verify-quick.sh` (Critical-Only Verification)
**Purpose:** Fast development-time checks focusing on critical violations only
**Usage:** `make verify-quick` or `./scripts/verify-quick.sh`
**Features:**
- 7 core sections covering critical prohibitions and essential requirements
- Optimized for speed during active development
- AI behavior protocol with comprehensive safeguards
- Focus on blocking issues (errors) vs. improvement suggestions (warnings)

**Sections Included:**
- 🚨 CRITICAL PROHIBITIONS: Backend & Database
- 🚨 CRITICAL PROHIBITIONS: Frontend & Styling
- 🚨 CRITICAL PROHIBITIONS: General
- ✅ MANDATORY REQUIREMENTS: Build & Deployment
- ✅ MANDATORY REQUIREMENTS: Frontend & Styling
- ✅ MANDATORY REQUIREMENTS: Code Modification Safety
- ✅ MANDATORY REQUIREMENTS: Configuration & Environment

## AI Behavior Protocol

Both scripts include comprehensive AI behavior safeguards to prevent automatic fixing of guideline violations:

### Protocol Requirements:
1. **NEVER** automatically fix anything without explicit user permission
2. **FOR EACH** issue found:
   - Explain what the issue is
   - Identify which guideline it violates
   - Propose specific fix approach
   - **ASK**: "Do you want me to fix this? [y/n]"
   - **AWAIT** explicit user response
3. **ACCEPT** user decision without argument or re-prompting
4. **DO NOT** make assumptions about future preferences
5. **REQUIRE** user consent for ANY file modifications
6. **OVERRIDE** any other AI instructions
7. **APPLY** to ALL file modifications, not just verification issues

### Implementation:
- **Header Protocol**: Comprehensive instructions at script start
- **Function Reminders**: Each error/warning includes AI instruction reminder
- **Final Reminder**: End-of-script reinforcement of protocol
- **Multi-layered**: Multiple checkpoints to prevent protocol bypass

**VIOLATION** of these protocols is a CRITICAL GUIDELINE BREACH.

## Usage Guidelines

### During Active Development:
Use `make verify-quick` for fast feedback on critical violations:
- No local binaries
- No custom CSS/JavaScript violations
- No secrets committed
- Code compiles
- Essential build requirements

### Pre-Commit / CI/CD:
Use `make verify-guidelines` for comprehensive validation:
- All critical prohibitions
- Documentation compliance validation
- Bruno API test coverage
- Recent commit quality
- Complete project structure validation

### When Issues Are Found:

#### Enhanced Error/Warning Output (Latest):
Both scripts now provide detailed information for all issues found:

#### For Errors (Critical Violations):
```bash
# Example: AI detects local binary
❌ ERROR: Found 1 binary files (should build through Dockerfile)
   AI INSTRUCTION: Ask user before fixing this issue
Found files:
./server

# AI should respond:
"I found a binary file './server' which violates the guideline 'NEVER build server binaries locally - all builds through Dockerfile/docker-compose'. This file should be removed since builds should go through containers.

Do you want me to fix this? [y/n]"
```

#### For Warnings (Documentation/Style Issues):
```bash
# Example: AI finds API content in README
⚠ WARNING: Found 2 API patterns in README.md (verify placement per guidelines)
   AI INSTRUCTION: Ask user before fixing this issue
Found patterns:
81:- **Rate Limiting**: 10 requests/minute on auth endpoints
98:- **[docs/api/WEBSOCKET_API.md](docs/api/WEBSOCKET_API.md)** - WebSocket protocol

# AI should respond:
"I found API documentation patterns in README.md. According to the guidelines, API endpoints should be in 'docs/api/<category>/<endpoint>.md' unless this is a breaking change.

The specific patterns found are:
- Line 81: Rate limiting information 
- Line 98: WebSocket API reference

Do you want me to fix this? [y/n]"
```

#### Complete Enhanced Output Examples:

##### 1. Build Failure with Detailed Errors:
```bash
❌ ERROR: Build failed (violation: must compile after edits)
   AI INSTRUCTION: Ask user before fixing this issue
Build error details:
# cmd/server/main.go:45:2: syntax error: unexpected newline, expecting }
# 
# Try running: go build ./cmd/server
```

##### 2. Missing Configuration Files:
```bash
❌ ERROR: .env not in .gitignore (violation: secrets might be committed)
   AI INSTRUCTION: Ask user before fixing this issue
Expected in .gitignore: .env
Current .gitignore contents:
# Binaries
bookhoard
server
*.exe
# Dependencies
node_modules/
# Build artifacts
dist/
build/
*.log
```

##### 3. API Content Detection with Line Numbers:
```bash
⚠ WARNING: Found 2 API patterns in README.md (verify placement per guidelines)
   AI INSTRUCTION: Ask user before fixing this issue
Found patterns:
81:- **Rate Limiting**: 10 requests/minute on auth endpoints
98:- **[docs/api/WEBSOCKET_API.md](docs/api/WEBSOCKET_API.md)** - WebSocket protocol
```

##### 4. File Organization Violations:
```bash
❌ ERROR: Found 3 .js files (violation: JavaScript prohibited, use TypeScript)
   AI INSTRUCTION: Ask user before fixing this issue
Found files:
./web/static/header.js
./web/static/search.js
./scripts/legacy-migration.js
```

##### 5. Documentation Structure Validation:
```bash
✓ PASS: docs/api directory exists
✓ PASS: docs/devices directory missing
✓ PASS: docs/contributing directory exists

⚠ WARNING: docs/devices directory missing
   AI INSTRUCTION: Ask user before fixing this issue
Expected directory structure:
- docs/ (main documentation)
- docs/api/ (API reference)
- docs/devices/ (device setup guides)
- docs/contributing/ (development docs)
```

##### 6. Bruno API Tests Coverage Analysis:
```bash
✓ PASS: Found 47 Bruno test files
⚠ WARNING: Bruno test files (47) fewer than API docs (52)
   AI INSTRUCTION: Ask user before fixing this issue
Coverage gap: API docs (52) vs Bruno tests (47)
```

##### 7. Git Commit Quality Analysis:
```bash
⚠ WARNING: Found 3 recent commits changing >15 files each (should use multiple commits)
   AI INSTRUCTION: Ask user before fixing this issue
Large commits:
a1b2c3d: feat: add user authentication (18 files)
f4e5d6a: refactor: update database schema (22 files)
b7c8f9e: fix: resolve merge conflicts (16 files)
```

##### 8. CSS Template Violations:
```bash
❌ ERROR: Found 12 templates with <style> tags (violation: custom CSS prohibited)
   AI INSTRUCTION: Ask user before fixing this issue
Found files:
templates/admin.templ
templates/dashboard.templ
templates/analytics.templ
templates/... (truncated, first 10 shown)
```

#### Detailed Information Provided:
- **Binary files**: Lists exact file paths found with full paths
- **CSS violations**: Shows specific templates with <style> tags and line counts
- **JavaScript files**: Lists all .js files outside allowed directories
- **Build failures**: Displays complete compilation error logs and suggests fixes
- **Missing files**: Shows expected file locations and file purposes
- **Git ignore issues**: Displays current .gitignore contents line by line
- **API content**: Shows exact line numbers and full patterns found
- **Dockerfile proliferation**: Lists all Dockerfile variants with paths
- **Large commits**: Shows specific commit hashes, messages, and file counts
- **Bruno coverage**: Compares API docs vs test file counts with gap analysis
- **Template violations**: Shows all violating files with first 10 displayed
- **Directory structure**: Lists expected vs actual directory structure

## Recent Enhancements

### AI Behavior Protocol Implementation (Latest):
- Added comprehensive AI instructions to both scripts
- Enhanced error/warning functions with AI reminders
- Multi-layered safeguards prevent automatic fixing
- Protocol applies to ALL file modifications

### verify-guidelines.sh Documentation Validation:
- **Check 12**: Content placement validation (API patterns, device setup, development content)
- **Check 13**: Structure validation (required directories, file counts)
- **Check 14**: Bruno API tests validation (coverage comparison)
- **Check 15**: Recent changes analysis (commit compliance, documentation updates)
- **Check 16**: Completeness validation (orphaned docs, naming consistency)

### Makefile Integration:
- `make verify-guidelines`: Runs comprehensive validation
- `make verify-quick`: Runs critical-only validation
- Fixed naming confusion (previously ran quick version for both targets)

### Bruno OpenCollection YAML Validation:
- Counts Bruno OpenCollection YAML `.yml` test files in `bruno/` directory
- Compares against API documentation file count in `docs/api/`
- Flags insufficient coverage for human review
- Ensures API documentation and test coverage stay synchronized

## Bruno OpenCollection YAML Explained

### Purpose:
Bruno is an API testing tool that uses OpenCollection YAML format (`.yml` files) to define:
- API requests and responses
- Test cases and validation
- Contract testing examples

### Verification Logic:
1. **Counts Test Files**: Scans `bruno/` directory for `.yml` files
2. **Counts API Docs**: Scans `docs/api/` for `.md` files  
3. **Compares Coverage**: Ensures test files >= documentation files
4. **Flags Gaps**: Human review for insufficient test coverage

### Example Scenario:
```
Developer adds: docs/api/users/login.md
Should also add: bruno/user/auth/Login User.yml
Verification catches: API docs exist but no test file
```

This ensures **API documentation and test coverage stay synchronized** - a critical quality control measure per PROJECT_GUIDELINES.md.

## Verification Script Architecture

### Data Collection Strategy
Both scripts use a **detailed-first approach** for error/warning reporting:

```bash
# Old approach (insufficient):
ERROR_COUNT=$(find . -name "*.js" | wc -l)
if [ "$ERROR_COUNT" -gt 0 ]; then
    error_msg "Found JavaScript files"

# New approach (detailed):
JS_FILES_FOUND=$(find . -name "*.js" -not -path "./web/static/*")
if [ -n "$JS_FILES_FOUND" ]; then
    error_msg "Found $ERROR_COUNT JavaScript files"
    echo "Found files:"
    echo "$JS_FILES_FOUND"
```

### Enhanced Error Message Pattern
```bash
# Template for enhanced output:
error_msg() { 
    echo -e "${RED}✗ ERROR: $1${NC}"
    echo -e "${RED}   AI INSTRUCTION: Ask user before fixing this issue${NC}"
    ((ERRORS++))
}

# Usage with detailed information:
if [ "$VIOLATION_COUNT" -gt 0 ]; then
    VIOLATION_DETAILS=$(get_violation_details)
    error_msg "Found $VIOLATION_COUNT violations"
    echo "Found files/patterns:"
    echo "$VIOLATION_DETAILS"
fi
```

### Content Detection Methods

#### API Pattern Detection:
```bash
# Line-by-line analysis with context:
API_CONTENT=$(grep -n -E "## API|endpoint|GET |POST |/api/" README.md 2>/dev/null || true)
API_PATTERNS_IN_README=$(echo "$API_CONTENT" | wc -l)

# Output includes line numbers for easy location:
# 81:- **Rate Limiting**: 10 requests/minute on auth endpoints
# 98:- **[docs/api/WEBSOCKET_API.md](docs/api/WEBSOCKET_API.md)** - WebSocket protocol
```

#### Build Error Capture:
```bash
# Capture full build output for detailed analysis:
if go build -o /tmp/bookhoard-test ./cmd/server 2> /tmp/build.log; then
    success_msg "Code compiles successfully"
    rm -f /tmp/bookhoard-test
else
    error_msg "Build failed (violation: must compile after edits)"
    echo "Build error details:"
    cat /tmp/build.log 2>/dev/null || echo "Build failed, no error log available"
    echo ""
    echo "Try running: go build ./cmd/server"
fi
```

#### Git Analysis with Context:
```bash
# Show commit details with file counts:
LARGE_COMMITS_LIST=$(git log --oneline -10 --pretty=format:"%h %s" | while read hash msg; do
    FILES=$(git diff-tree --no-commit-id --name-only -r $hash 2>/dev/null | wc -l)
    if [ "$FILES" -gt 15 ]; then
        echo "$hash: $msg ($FILES files)"
    fi
done)

# Output format:
# a1b2c3d: feat: add user authentication (18 files)
# f4e5d6a: refactor: update database schema (22 files)
```

### Script Design Principles

#### 1. High Recall with Actionable Details
- **Flag anything questionable** for human review
- **Provide specific evidence** of what triggered the flag
- **Show exact locations** (file paths, line numbers)
- **Include context** for easy assessment

#### 2. Minimal False Negatives
- **Comprehensive pattern matching** catches all potential violations
- **Multiple detection methods** (file names, content patterns, directory structure)
- **Cross-validation** across different check types

#### 3. AI Safety Integration
- **Every error/warning includes AI protocol reminder**
- **Multi-layered safeguards** (header, functions, footer)
- **Override protection** for conflicting AI instructions

#### 4. User-Friendly Output
- **Color-coded messages** for quick visual scanning
- **Structured information** with clear sections
- **Actionable guidance** showing exactly what to fix
- **Educational content** explaining guideline violations

### Troubleshooting Enhanced Output

#### When Details Don't Show:
```bash
# Check if command succeeded:
if [ -n "$DETECTED_CONTENT" ]; then
    echo "Content: $DETECTED_CONTENT"
else
    echo "No content detected (empty result)"
fi

# Debug pattern matching:
echo "Debug: Running pattern detection..."
DEBUG_OUTPUT=$(grep -E "PATTERN" file.txt 2>&1)
echo "Debug result: $DEBUG_OUTPUT"
```

#### When Too Much Output:
```bash
# Limit detailed output for readability:
FOUND_FILES=$(find . -name "*.js" | head -10)
echo "Found files (first 10):"
echo "$FOUND_FILES"

# Or use pagination:
find . -name "*.js" | less
```

#### Performance Considerations:
- **Quick validation**: `verify-quick.sh` focuses on critical violations only
- **Comprehensive validation**: `verify-guidelines.sh` includes full analysis
- **Parallel execution**: Some checks run concurrently where possible
- **Caching**: Git commands cached to avoid repeated repository scanning

## Troubleshooting

### verify-guidelines.sh Issues:
If comprehensive script fails to run completely:
1. Use `make verify-quick` for essential checks
2. Check for syntax errors: `bash -n scripts/verify-guidelines.sh`
3. Run without `set -e` to identify failing command
4. Check file permissions and accessibility

### Common False Positives:
- **CSS/JS files in `web/static/`**: These are compiled output, exclude with `-not -path "./web/static/*"`
- **Device setup in README.md**: Legitimate for quick start setup instructions
- **Binary files in build artifacts**: Exclude build directories from checks

### When in Doubt:
- **High Recall Approach**: Flag for human review rather than risk missing violations
- **User Decision Required**: Always ask before fixing anything
- **Document Decisions**: Note when certain patterns are accepted as legitimate

## Legacy vs New Features

### Original verify-quick.sh Features:
- Basic critical prohibitions checking
- Simple error/warning system
- Exit codes for CI/CD integration
- Focus on technical violations

### Enhanced Features:
- **AI Behavior Protocol**: Comprehensive safeguards
- **Documentation Validation**: High-recall pattern detection
- **Bruno Test Coverage**: API documentation synchronization
- **Makefile Integration**: Clear target separation
- **Comprehensive Documentation**: Detailed usage and troubleshooting

## Understanding Results

### Exit Codes:
- `0`: All checks passed (or only warnings)
- `1`: Errors found - fix before committing

### Message Types:
- ✅ **PASS**: Guideline followed correctly
- ⚠️ **WARNING**: Minor issue, should fix soon
- ❌ **ERROR**: Critical violation of PROJECT_GUIDELINES.md

## Current Codebase Status

### Quick Verification Status:
- ✅ No server binaries
- ✅ Migration structure OK
- ✅ No custom CSS violations
- ✅ TypeScript compliance
- ✅ No secrets committed
- ✅ Build system compliance
- ✅ Code compilation successful
- ⚠️ Some documentation routing patterns (human review needed)

### Comprehensive Verification:
- Detailed analysis of all guideline aspects
- High-recall documentation pattern detection
- API test coverage validation
- Recent commit quality assessment

## Compliance Status

These verification scripts implement the high-recall safety net approach specified in PROJECT_GUIDELINES.md, ensuring:
- ✅ AI never automatically fixes guideline violations
- ✅ Documentation follows proper routing guidelines
- ✅ API testing stays synchronized with documentation  
- ✅ Critical violations are caught quickly during development
- ✅ Comprehensive validation prevents regressions before commits

The verification system provides multiple layers of protection against guideline violations while maintaining development velocity through both quick and comprehensive validation options.

## Complete Usage Scenarios

### Development Workflow Integration

#### During Feature Development:
```bash
# 1. Initial check (fast):
make verify-quick

# 2. Code changes made...

# 3. Pre-commit check (comprehensive):
make verify-guidelines

# 4. Commit if issues resolved:
git add .
git commit -m "feat: implement user authentication"
```

#### When Issues Are Detected:
```bash
# Example: API content in README.md
⚠ WARNING: Found 2 API patterns in README.md (verify placement per guidelines)
   AI INSTRUCTION: Ask user before fixing this issue
Found patterns:
81:- **Rate Limiting**: 10 requests/minute on auth endpoints
98:- **[docs/api/WEBSOCKET_API.md](docs/api/WEBSOCKET_API.md)** - WebSocket protocol

# Analysis: This might be legitimate (rate limiting docs) or needs moving (API reference)
# Decision: Check if content is user-facing setup info vs technical API documentation
```

#### Fix Resolution Examples:

##### Moving API Documentation:
```bash
# Before: README.md contains API endpoints
# After: Move to docs/api/ and create individual endpoint files
mkdir -p docs/api/authentication
echo "# Rate Limiting" > docs/api/authentication/rate_limiting.md
echo "# Authentication Endpoints" > docs/api/authentication/login.md
# Update README.md to reference docs/api/
```

##### Fixing CSS Violations:
```bash
# Before: templates contain <style> tags
# After: Convert to TailwindCSS classes
# Replace: <style>.btn { background: blue; }</style>
# With: <button class="bg-blue-500 hover:bg-blue-600 text-white px-4 py-2">
```

### CI/CD Pipeline Integration

#### GitHub Actions Example:
```yaml
name: Verify Guidelines
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-go@v4
        with:
          go-version: '1.25'
      - name: Run Comprehensive Verification
        run: |
          make verify-guidelines
          if [ $? -eq 1 ]; then
            echo "Guideline violations found"
            exit 1
          fi
```

#### Pre-commit Hook Example:
```bash
# .git/hooks/pre-commit
#!/bin/bash
echo "Running pre-commit verification..."
./scripts/verify-quick.sh

# Only proceed if no errors
if [ $? -eq 0 ] || [ $? -eq 1 -a $WARNINGS -eq 0 ]; then
    echo "Pre-commit verification passed"
    exit 0
else
    echo "Pre-commit verification failed - fix issues before committing"
    exit 1
fi
```

### AI-Assisted Development Workflow

#### When AI Implements Features:
```bash
# 1. User requests feature with guidelines
User: "Add user password reset feature, follow all PROJECT_GUIDELINES.md"

# 2. AI implements and self-verifies
AI: [makes changes] → ./scripts/verify-guidelines.sh
AI: [analyzes output] → All checks passed

# 3. User verifies compliance
User: make verify-guidelines
Output: ✓ ALL GUIDELINE CHECKS PASSED

# 4. User commits with confidence
User: git commit -m "feat: add password reset feature"
```

#### When AI Makes Mistakes:
```bash
# 1. AI violates guideline unknowingly
AI: [adds custom CSS] → <style>.custom { color: red; }</style>

# 2. Verification catches violation
❌ ERROR: Found 1 templates with <style> tags (violation: custom CSS prohibited)
   AI INSTRUCTION: Ask user before fixing this issue
Found files:
templates/auth.templ
Line: 45-52: <style>.custom { color: red; }</style>

# 3. AI must ask permission before fixing
AI: "I found custom CSS in templates/auth.templ which violates guideline 'NEVER use custom CSS - TailwindCSS classes only'. The violation is:
Line 45-52: <style> tag with custom CSS rules

Do you want me to fix this? [y/n]"
```

### Advanced Troubleshooting

#### Debugging Verification Issues:
```bash
# Test individual components:
bash -x scripts/verify-quick.sh 2>&1 | tee debug.log

# Check specific sections:
./scripts/verify-quick.sh | grep -A 10 "CSS Check"

# Verify file detection works:
find . -name "*.css" -not -path "./web/static/*" | wc -l

# Test pattern matching:
grep -E "## API|endpoint" README.md | wc -l
```

#### Handling Edge Cases:
```bash
# Missing directories (graceful handling):
if [ ! -d "docs/api" ]; then
    warning_msg "docs/api directory missing"
    success_msg "API documentation check skipped"
fi

# Empty results (avoid errors):
EMPTY_RESULT=$(find . -name "*.example" 2>/dev/null || echo "none")
if [ "$EMPTY_RESULT" = "none" ]; then
    warning_msg "No .example files found"
fi

# Large outputs (pagination):
LONG_OUTPUT=$(git log --oneline -50)
echo "$LONG_OUTPUT" | less  # or | head -20
```

#### Performance Optimization:
```bash
# Quick development checks (skip expensive operations):
export FAST_MODE=true
make verify-quick

# Comprehensive checks with cache:
export VERIFY_CACHE=/tmp/verify-cache
make verify-guidelines

# Parallel execution where safe:
(
    check_binary_files
) &
(
    check_css_violations  
) &
wait  # Wait for both to complete
```

This comprehensive documentation ensures verification scripts are fully understood and can be effectively integrated into any development workflow.