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]"
```

#### Detailed Information Provided:
- **Binary files**: Lists exact file paths found
- **CSS violations**: Shows specific templates with <style> tags
- **JavaScript files**: Lists all .js files outside allowed directories
- **Build failures**: Displays compilation error logs
- **Missing files**: Shows expected file locations and purposes
- **Git ignore issues**: Displays current .gitignore contents
- **API content**: Shows exact lines and patterns found
- **Dockerfile proliferation**: Lists all Dockerfile variants found
- **Large commits**: Shows specific commits with file counts
- **Bruno coverage**: Compares API docs vs test file counts

## 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 API Tests Validation:
- Counts Bruno `.bru` 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 API Tests Explained

### Purpose:
Bruno v3.0 is an API testing tool that uses `.bru` files to define:
- API requests and responses
- Test cases and validation
- Contract testing examples

### Verification Logic:
1. **Counts Test Files**: Scans `bruno/` directory for `.bru` 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.bru
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.

## 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.