docs: Streamline CLAUDE.md and update Status.md with TEC CE analysis

- Simplify CLAUDE.md to focus on essential development guidance - Remove redundant agent workflow documentation - Add Technical Debt section documenting TEC Community Events dependency - Update Status.md with completed TEC CE dependency analysis session Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 20:04:11 -04:00 · 2026-01-09 20:04:11 -04:00 · 3136b96d3f
commit 3136b96d3f
parent 3d66756715
2 changed files with 142 additions and 220 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -1,286 +1,182 @@
-# CLAUDE.md - HVAC Plugin Development Guide
+# CLAUDE.md

-**Essential guidance for Claude Code agents working on the HVAC Community Events WordPress plugin.**
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

-> 📚 **Complete Best Practices**: See [docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md](docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md) for comprehensive development guidelines.
+## Project Overview

-> 📊 **Current Status**: PHP 8+ Modernization (Phase 2) in progress - debugging union type compatibility on staging
+HVAC Community Events is a WordPress plugin extending The Events Calendar (TEC) suite to create a trainer community platform. It provides custom user roles (`hvac_trainer`, `hvac_master_trainer`), event management, certificate generation, venue/organizer management, and Zoho CRM integration.

-> ⚠️ **Interim Status**: See [docs/PHP8-MODERNIZATION-INTERIM-STATUS.md](docs/PHP8-MODERNIZATION-INTERIM-STATUS.md) for current session progress
+- **Entry Point**: `hvac-community-events.php`
+- **Core Classes**: `includes/class-*.php` (all use singleton pattern)
+- **Templates**: `templates/page-*.php`
+- **TEC Integration**: Events, venues, organizers via The Events Calendar suite

-## 🚀 Quick Commands
+## Commands

-### Deployment (Most Common)
+### Deployment
 ```bash
-# Deploy to staging (primary command)
-scripts/deploy.sh staging
-
 # Pre-deployment validation (ALWAYS run first)
 scripts/pre-deployment-check.sh

-# Deploy to production (ONLY when user explicitly requests)
+# Deploy to staging
+scripts/deploy.sh staging
+
+# Deploy to production (requires explicit user request and confirmation)
 scripts/deploy.sh production
 ```

 ### Testing
 ```bash
-# Docker Development Environment
+# Start Docker test environment
 docker compose -f tests/docker-compose.test.yml up -d

-# Run E2E tests against Docker environment (headless)
+# E2E tests (headless)
 HEADLESS=true BASE_URL=http://localhost:8080 node test-master-trainer-e2e.js
+HEADLESS=true BASE_URL=http://localhost:8080 node test-comprehensive-validation.js

-# Run E2E tests with GNOME session browser (headed)
+# E2E tests (headed - requires display)
 DISPLAY=:0 XAUTHORITY=/run/user/1000/.mutter-Xwaylandauth.U8VEB3 node test-master-trainer-e2e.js
-
-# Run comprehensive test suite
-node test-comprehensive-validation.js
-
-# Use MCP Playwright when standard Playwright fails
-# (The MCP tools handle display integration automatically)
 ```

-### WordPress CLI (on server)
+### WordPress CLI (on server via SSH)
 ```bash
 wp rewrite flush
 wp eval 'HVAC_Page_Manager::create_required_pages();'
-
-# Reset user password (when wp user update fails with password hashing)
-wp eval 'wp_set_password("YourPassword123", USER_ID);'
-
-# Example for test_master user (ID: 25 on staging)
-wp eval 'wp_set_password("TestPass123", 25);'
+wp eval 'wp_set_password("Password123", USER_ID);'  # Reset password (more reliable than wp user update)
 ```

-### Test Credentials (Staging)
+### Staging Environment
 ```bash
-# Master Trainer Test Account
-Username: test_master
-Password: TestPass123
-User ID: 25
-Role: hvac_master_trainer
-
-# Password Reset Method (if login fails after wp user update)
-# SSH to staging server:
+# SSH access
 ssh roodev@146.190.76.204
-
-# Navigate to WordPress root and reset password:
 cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html
-wp eval 'wp_set_password("TestPass123", 25);'

-# Why wp_set_password instead of wp user update:
-# wp user update --user_pass sometimes has password hashing issues
-# wp_set_password properly hashes the password using wp_hash_password()
+# Test account (staging)
+Username: test_master | Password: TestPass123 | Role: hvac_master_trainer
 ```

-## 🎯 Core Development Principles
+## Architecture

-### 1. **USE MCP SERVICES PROACTIVELY**
- `mcp__sequential-thinking__sequentialthinking` for complex planning
- `mcp__zen-mcp__codereview` with GPT-5/Qwen for validation  
- `mcp__zen-mcp__thinkdeep` for complex investigations
- `WebSearch` for documentation and best practices
- **Specialized Agents**: Use agents from user's `.claude` directory for debugging, architecture, security
+### Singleton Pattern (MANDATORY)
+All core classes use the singleton pattern. Never assume static methods exist:

-### 2. **WordPress Template Architecture (CRITICAL)**
 ```php
-// ✅ ALWAYS use singleton patterns  
+// CORRECT
 echo HVAC_Breadcrumbs::instance()->render_breadcrumbs();
+HVAC_Venues::instance()->get_venues();

-// ❌ NEVER assume static methods exist
-// WRONG: HVAC_Breadcrumbs::render();
+// WRONG - will fail
+HVAC_Breadcrumbs::render();
+```

-// ✅ MANDATORY in all templates
+### Template Requirements
+All page templates MUST include:
+```php
+<?php
+defined('ABSPATH') || exit;
 define('HVAC_IN_PAGE_TEMPLATE', true);
 get_header();
-// content here
+// ... content ...
 get_footer();
 ```

-### 3. **Security-First Patterns**
+### Security Patterns
 ```php
-// Always escape output
-echo esc_html($trainer_name);
-echo esc_url($profile_link);
-
-// Always sanitize input  
+// Input sanitization
 $trainer_id = absint($_POST['trainer_id']);
+$email = sanitize_email($_POST['email']);

-// Always verify nonces
+// Output escaping
+echo esc_html($trainer_name);
+echo esc_url($profile_url);
+
+// Nonce verification
 wp_verify_nonce($_POST['nonce'], 'hvac_action');

-// Role checking (NOT capabilities)
+// Role checking (use roles, not capabilities)
 $user = wp_get_current_user();
 if (!in_array('hvac_trainer', $user->roles)) {
    wp_die('Access denied');
 }
 ```

-### 4. **WordPress Specialized Agents (PRIMARY DEVELOPMENT TOOLS)**
+### File Structure
+```
+includes/
+├── class-hvac-plugin.php          # Main controller (singleton)
+├── class-hvac-shortcodes.php      # Shortcode management
+├── class-hvac-scripts-styles.php  # Asset management
+├── class-hvac-route-manager.php   # URL routing
+├── class-hvac-venues.php          # Venue CRUD (singleton)
+├── class-hvac-organizers.php      # Organizer management (singleton)
+├── class-hvac-training-leads.php  # Lead tracking (singleton)
+├── admin/                         # Admin classes
+├── certificates/                  # Certificate generation
+├── communication/                 # Email templates
+├── zoho/                          # Zoho CRM integration
+└── find-trainer/                  # Public trainer directory

-**MANDATORY**: Use project-specific WordPress agents for ALL development activities:
-
-```bash
-# WordPress Plugin Development (primary agent for features/fixes)
-claude --agent wordpress-plugin-pro "Add event validation system"
-
-# Code Review (MANDATORY after any code changes) 
-claude --agent wordpress-code-reviewer "Review security of latest changes"
-
-# Troubleshooting (first response to any issues)
-claude --agent wordpress-troubleshooter "Debug event creation form issues"
-
-# Testing (MANDATORY before any deployment)
-claude --agent wordpress-tester "Run comprehensive test suite for staging deployment"
-
-# Deployment (for all staging/production deployments)
-claude --agent wordpress-deployment-engineer "Deploy latest changes to staging"
+templates/page-*.php               # Page templates (hierarchical URLs)
+assets/{css,js}/                   # Frontend assets
+tests/                             # Docker environment and E2E tests
+scripts/                           # Deployment and maintenance scripts
 ```

-**Agent Selection Guide:**
- 🔧 **wordpress-plugin-pro**: New features, WordPress hooks, TEC integration, role management
- 🛡️ **wordpress-code-reviewer**: Security review, WordPress standards, performance analysis  
- 🔍 **wordpress-troubleshooter**: Debugging, plugin conflicts, user access issues
- 🧪 **wordpress-tester**: Comprehensive testing, E2E tests, deployment validation (**MANDATORY before deployments**)
- 🚀 **wordpress-deployment-engineer**: Staging/production deployments, CI/CD, backups
+### URL Structure
+- Trainer: `/trainer/dashboard/`, `/trainer/event/manage/`, `/trainer/certificate-reports/`
+- Master Trainer: `/master-trainer/dashboard/`, `/master-trainer/trainers/`
+- Public: `/training-login/`, `/find-a-trainer/`

-### 5. **Testing & Debugging Process**
-1. **Use wordpress-troubleshooter agent for systematic diagnosis**
-2. **Create comprehensive test suite with wordpress-tester agent**
-3. **Apply wordpress-code-reviewer for security validation**  
-4. **Run mandatory pre-deployment tests with wordpress-tester**
-5. **Use wordpress-deployment-engineer for staging deployment and validation**
+## Critical Warnings
+
+### NEVER Do
+- Deploy to production without explicit user request
+- Skip pre-deployment validation (`scripts/pre-deployment-check.sh`)
+- Use static method calls without verifying singleton pattern
+- Re-enable monitoring infrastructure (causes PHP segmentation faults)
+
+### Disabled Systems (DO NOT RE-ENABLE)
+The following monitoring systems are PERMANENTLY DISABLED due to causing PHP segmentation faults:
+`HVAC_Background_Jobs`, `HVAC_Health_Monitor`, `HVAC_Error_Recovery`, `HVAC_Security_Monitor`, `HVAC_Performance_Monitor`, `HVAC_Backup_Manager`, `HVAC_Cache_Optimizer`
+
+## Zoho CRM Integration
+
+Located in `includes/zoho/`. Maps WordPress data to Zoho CRM:
+- Events → Campaigns
+- Trainers → Contacts
+- Attendees → Contacts + Campaign Members
+- RSVPs → Leads + Campaign Members
+
+**Admin Page**: `/wp-admin/admin.php?page=hvac-zoho-sync`
+
+**Important**: Staging environment blocks all write operations to Zoho CRM. Only production can sync data.
+
+## Docker Test Environment

-### 6. **WordPress Error Detection & Site Health**
 ```bash
-# All E2E tests now include automatic WordPress error detection
-# Tests will fail fast if critical WordPress errors are detected:
-# - Fatal PHP errors (memory, syntax, undefined functions)
-# - Database connection errors
-# - Maintenance mode
-# - Plugin/theme fatal errors
-# - HTTP 500+ server errors
-
-# If test fails with "WordPress site has critical errors":
-# 1. Restore staging from production backup
-# 2. Re-seed test data to staging:
-bin/seed-comprehensive-events.sh
-# 3. Re-run tests
-```
-
-## 🏗️ Architecture Overview
-
-**WordPress Plugin Structure:**
- **Entry Point**: `hvac-community-events.php`
- **Core Classes**: `includes/class-*.php` (singleton pattern)
- **Templates**: `templates/page-*.php` (hierarchical URLs)
- **User Roles**: `hvac_trainer`, `hvac_master_trainer`
- **URL Structure**: `/trainer/dashboard/`, `/master-trainer/master-dashboard/`
-
-## ⚠️ CRITICAL REMINDERS
-
-### Never Do
- ❌ Deploy to production without explicit user request
- ❌ Skip pre-deployment validation  
- ❌ Use static method calls without verification
- ❌ Create standalone fixes outside plugin deployment
- ❌ Assume template patterns without checking existing implementation
-
-### Always Do  
- ✅ **Use WordPress agents as first choice for ALL development tasks**
- ✅ Use MCP services and specialized agents proactively
- ✅ Test on staging first
- ✅ Apply consistent singleton patterns
- ✅ Escape all output, sanitize all input
- ✅ Create comprehensive test suites before making fixes
- ✅ Reference the detailed best practices document
-
-## 📚 Key Documentation
-
-**Essential Reading:**
- **[Status.md](Status.md)** - Current project status and known issues
- **[docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md](docs/CLAUDE-CODE-DEVELOPMENT-BEST-PRACTICES.md)** - Complete development guide
- **[docs/MASTER-TRAINER-FIXES-REPORT.md](docs/MASTER-TRAINER-FIXES-REPORT.md)** - Recent major fixes and lessons learned
-
-**Reference Materials:**
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture
- **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues
- **[docs/WORDPRESS-BEST-PRACTICES.md](docs/WORDPRESS-BEST-PRACTICES.md)** - WordPress standards
- **[docs/TEST-FRAMEWORK-MODERNIZATION-STATUS.md](docs/TEST-FRAMEWORK-MODERNIZATION-STATUS.md)** - Testing infrastructure overhaul
-
-## 🧪 Docker Testing Infrastructure (New)
-
-**STATUS: August 27, 2025 - FULLY OPERATIONAL**
-
-### Docker Environment
-```bash
-# Start hermetic testing environment
 docker compose -f tests/docker-compose.test.yml up -d

-# Access WordPress test instance
-http://localhost:8080
-
-# Services included:
-# - WordPress 6.4 (PHP 8.2) on port 8080
-# - MySQL 8.0 on port 3307
-# - Redis 7 on port 6380
-# - Mailhog (email testing) on port 8025
-# - PhpMyAdmin on port 8081
+# Services:
+# WordPress 6.4 (PHP 8.2): http://localhost:8080
+# MySQL 8.0: port 3307
+# Redis 7: port 6380
+# Mailhog: http://localhost:8025
+# PhpMyAdmin: http://localhost:8081
 ```

-### Test Framework Architecture
- **Page Object Model (POM)**: Centralized, reusable test components
- **146 Tests Migrated**: From 80+ duplicate files to modern architecture  
- **90% Code Reduction**: Eliminated test duplication through shared patterns
- **Browser Management**: Singleton lifecycle with proper cleanup
- **TCPDF Dependency**: Graceful handling of missing PDF generation library
+## Technical Debt

-### Testing Commands
-```bash
-# Run comprehensive E2E tests (ready for next session)
-HEADLESS=true BASE_URL=http://localhost:8080 node test-master-trainer-e2e.js
-HEADLESS=true BASE_URL=http://localhost:8080 node test-comprehensive-validation.js
-```
+### TEC Community Events Dependency
+The plugin still relies on "The Events Calendar: Community" (TEC CE) for event creation/editing forms via `[tribe_community_events]` shortcode. While `HVAC_Event_Manager` has custom CRUD capabilities, production code paths use TEC CE.

-## 🚨 CRITICAL WARNING: Monitoring Infrastructure Disabled
+**Removal estimate:** 9-14 days of development work.
+**Details:** See [docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md](docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md)

-**DATE: August 8, 2025**  
-**The monitoring infrastructure is PERMANENTLY DISABLED due to causing PHP segmentation faults.**
+**Status:** Deferred - Current implementation is functional and stable.

-Disabled systems: HVAC_Background_Jobs, HVAC_Health_Monitor, HVAC_Error_Recovery, HVAC_Security_Monitor, HVAC_Performance_Monitor, HVAC_Backup_Manager, HVAC_Cache_Optimizer
+## Key Documentation

-**DO NOT RE-ENABLE** without thorough debugging.
-
-## 🎯 WordPress Development Workflow
-
-1. **Start with WordPress Agents**: Choose appropriate agent based on task type
-2. **Plan with Sequential Thinking**: Agents will use `mcp__sequential-thinking` for complex tasks
-3. **Research Best Practices**: Agents will use `WebSearch` for WordPress documentation  
-4. **Apply Consistent Patterns**: Agents understand WordPress singleton patterns
-5. **Test Comprehensively**: **MANDATORY** `wordpress-tester` for all test suites and validation
-6. **Review Security**: **MANDATORY** `wordpress-code-reviewer` after code changes
-7. **Pre-Deploy Testing**: **MANDATORY** `wordpress-tester` before any deployment
-8. **Deploy Systematically**: `wordpress-deployment-engineer` for staging first
-9. **Validate with MCP**: Agents will use `mcp__zen-mcp__codereview` for quality assurance
-
-### 🚀 Quick Agent Command Reference
-```bash
-# Feature Development
-claude --agent wordpress-plugin-pro "Implement trainer approval workflow"
-
-# Bug Fixes  
-claude --agent wordpress-troubleshooter "Fix event creation form validation"
-
-# Security & Code Quality
-claude --agent wordpress-code-reviewer "Review user authentication system"
-
-# Testing (MANDATORY before deployments)
-claude --agent wordpress-tester "Run full test suite before staging deployment"
-
-# Deployments
-claude --agent wordpress-deployment-engineer "Deploy v2.1 to staging environment"
-```
-
---
-
-*This guide provides essential information for Claude Code agents. For comprehensive details, always refer to the complete best practices documentation.*
+- **[Status.md](Status.md)** - Current project status and recent changes
+- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture details
+- **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+- **[docs/TESTING-GUIDE.md](docs/TESTING-GUIDE.md)** - Testing procedures
--- a/Status.md
+++ b/Status.md
@ -1,12 +1,38 @@
 # HVAC Community Events - Project Status

-**Last Updated:** December 21, 2025
-**Current Session:** Public Map Fix (Strategy H) - In Verification
+**Last Updated:** January 5, 2026
+**Current Session:** TEC Community Events Dependency Analysis - Complete
 **Version:** 2.1.11 (Deployed to Production)

 ---

-## 🎯 CURRENT SESSION - SCHEDULED SYNC PERSISTENCE FIX (Dec 20, 2025)
+## 🎯 CURRENT SESSION - TEC COMMUNITY EVENTS DEPENDENCY ANALYSIS (Jan 5, 2026)
+
+### Status: ✅ **COMPLETE - Documented as Technical Debt**
+
+**Objective:** Analyze whether "The Events Calendar: Community" (TEC CE) plugin is still being used after recent refactoring.
+
+**Findings:**
+- The plugin **still actively relies on TEC CE** for event creation/editing
+- Core shortcode `[tribe_community_events]` is used in 7 template/class files
+- TEC CE hooks are used for field processing and form customization
+- `HVAC_Event_Manager` has custom CRUD capabilities but production paths use TEC CE
+
+**Removal Scope:**
+- **Estimated effort:** 9-14 days of development
+- **Key work:** Custom forms, date pickers, validation, template updates, testing
+- **Risk:** Recurring events complexity, Event Tickets integration
+
+**Decision:** Deferred as technical debt. Current implementation is functional and stable.
+
+### Deliverables
+1. ✅ **Analysis Report:** `docs/reports/TEC-COMMUNITY-EVENTS-DEPENDENCY-ANALYSIS.md`
+2. ✅ **CLAUDE.md Updated:** Added Technical Debt section
+3. ✅ **Status.md Updated:** This entry
+
+---
+
+## 📋 PREVIOUS SESSION - SCHEDULED SYNC PERSISTENCE FIX (Dec 20, 2025)

 ### Status: ✅ **COMPLETE - Deployed to Production**

@ -39,7 +65,7 @@

 ---

-## 🎯 CURRENT SESSION - PUBLIC MAP & DIRECTORY FIX (Dec 21, 2025)
+## 📋 PREVIOUS SESSION - PUBLIC MAP & DIRECTORY FIX (Dec 21, 2025)

 ### Status: 🔄 **IN PROGRESS - Deployed to Staging (Strategy H)**