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):

# 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):

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