@equilateral_ai/mindmeld 3.0.0

package/hooks/README.md

@@ -0,0 +1,494 @@
+# Rapport Claude Code Hooks
+
+**Phase 5: Claude Code Integration**
+
+This directory contains hooks for integrating Rapport with Claude Code, enabling real-time context injection and pattern harvesting during development sessions.
+
+---
+
+## Available Hooks
+
+### 1. `session-start.js` - Context Injection
+
+**Purpose**: Inject ONLY relevant standards and team patterns at session start
+
+**Execution**: Called when Claude Code session begins
+
+**Performance**: < 500ms target (achieves ~200ms)
+
+**Output**: Formatted markdown context with:
+- Project name and team members
+- Top 10 most relevant standards
+- High-correlation team patterns
+- Recent team learning (last 7 days)
+
+**Usage**:
+```bash
+# Test directly
+node hooks/session-start.js
+
+# Via npm script
+npm run test:session-start
+```
+
+**Configuration**:
+```json
+{
+  "claudeCode": {
+    "hooks": {
+      "sessionStart": "hooks/session-start.js"
+    }
+  }
+}
+```
+
+### 2. `pre-compact.js` - Pattern Harvesting
+
+**Purpose**: Harvest patterns and validate compliance before conversation compaction
+
+**Execution**: Called before Claude Code compacts conversation history
+
+**Output**: JSON summary with:
+- Patterns detected count
+- Violations found
+- Patterns reinforced
+- Promotion candidates
+
+**Usage**:
+```bash
+# Test directly
+node hooks/pre-compact.js '{"transcript":"Created handler with wrapHandler"}'
+
+# Via npm script
+npm run test:pre-compact
+```
+
+**Configuration**:
+```json
+{
+  "claudeCode": {
+    "hooks": {
+      "preCompact": "hooks/pre-compact.js"
+    }
+  }
+}
+```
+
+---
+
+## How Hooks Work
+
+### SessionStart Flow
+
+```
+1. Claude Code calls session-start.js
+2. Hook checks if Rapport configured
+3. If not configured → return empty string (instant)
+4. If configured:
+   a. Ensure standards ingested (cached check)
+   b. Detect project context
+   c. Identify relevant standards (top 10)
+   d. Load team patterns (correlation > 0.7)
+   e. Format context injection
+5. Return formatted context to Claude Code
+6. Claude Code injects into system prompt
+```
+
+### PreCompact Flow
+
+```
+1. Claude Code calls pre-compact.js with session transcript
+2. Hook checks if Rapport configured
+3. If not configured → return skipped status
+4. If configured:
+   a. Extract file changes from transcript
+   b. Detect patterns in changed files
+   c. Validate patterns against standards
+   d. Record violations for team learning
+   e. Reinforce valid patterns
+   f. Check for promotion candidates
+5. Return summary to Claude Code
+```
+
+---
+
+## Performance Characteristics
+
+### SessionStart
+
+| Metric | Target | Achieved |
+|--------|--------|----------|
+| First run (with ingestion) | < 1000ms | ~500ms |
+| Subsequent runs (cached) | < 500ms | ~200ms |
+| Unconfigured project | < 50ms | ~10ms |
+
+**Optimizations**:
+- Fast bail if Rapport not configured
+- Cached standards ingestion check
+- Limited to top 10 standards
+- Efficient project structure analysis
+- No deep file content parsing
+
+### PreCompact
+
+| Metric | Target | Achieved |
+|--------|--------|----------|
+| Pattern detection | < 500ms | ~200-300ms |
+| Validation | < 200ms | ~100-150ms |
+| Total execution | < 1000ms | ~300-500ms |
+
+**Optimizations**:
+- Parallel pattern validation
+- Cached database queries
+- Simple regex-based pattern detection
+- Graceful degradation on errors
+
+---
+
+## Graceful Degradation
+
+Both hooks are designed to **never block Claude Code sessions**:
+
+1. **Configuration Missing**: Return empty/skipped
+2. **Database Unavailable**: Return cached data
+3. **Standards Not Ingested**: Skip validation
+4. **Hook Execution Error**: Log and return empty
+5. **Timeout**: Return partial results
+
+**Example**:
+```javascript
+try {
+  const context = await injectContext();
+  return context;
+} catch (error) {
+  console.error('[Rapport] Hook error (non-fatal):', error.message);
+  return ''; // Don't block session
+}
+```
+
+---
+
+## Testing
+
+### Comprehensive Test Suite
+
+```bash
+# Run all tests
+npm run test:hooks
+
+# Test specific hooks
+npm run test:session-start
+npm run test:pre-compact
+
+# Performance benchmark
+npm run test:benchmark
+```
+
+### Test Script: `scripts/test-claude-hooks.js`
+
+**Features**:
+- SessionStart hook testing
+- PreCompact hook testing
+- RapportClient integration testing
+- RelevanceDetector testing
+- Performance benchmarking (5 iterations)
+
+**Example Output**:
+```
+=== Performance Benchmark ===
+
+  Iteration 1: 245ms
+  Iteration 2: 198ms
+  Iteration 3: 187ms
+  Iteration 4: 192ms
+  Iteration 5: 201ms
+
+Results:
+  Average: 204.60ms
+  Min: 187ms
+  Max: 245ms
+  Target: 500ms
+  ✓ PASSED
+```
+
+---
+
+## Configuration
+
+### Required Files
+
+1. **`.rapport/config.json`**: Project configuration
+   ```json
+   {
+     "projectId": "project_abc123",
+     "projectName": "my-project",
+     "collaborators": [...]
+   }
+   ```
+
+2. **`.equilateral-standards/`**: Symlink to standards repo
+   ```bash
+   ln -s ../equilateral-standards .equilateral-standards
+   ```
+
+3. **`package.json`**: Hook configuration
+   ```json
+   {
+     "claudeCode": {
+       "hooks": {
+         "sessionStart": "hooks/session-start.js",
+         "preCompact": "hooks/pre-compact.js"
+       }
+     }
+   }
+   ```
+
+### Optional Configuration
+
+```json
+{
+  "claudeCode": {
+    "config": {
+      "standardsPath": ".equilateral-standards",
+      "maxContextLength": 50000,
+      "maxStandards": 10,
+      "sessionStartTimeout": 500
+    }
+  }
+}
+```
+
+---
+
+## Example Outputs
+
+### SessionStart Context
+
+```markdown
+# Rapport Context - my-project
+
+## Team
+- Jim Ford (jim@equilateral.ai)
+- Team Member (member@company.com)
+
+## Relevant Standards
+
+### Lambda Database Connection
+**Category**: serverless-saas-aws
+**Rule**: NEVER use connection pools in Lambda functions
+
+**Example**:
+```javascript
+let client;
+async function getClient() {
+  if (!client) {
+    client = new Client({
+      connectionString: process.env.DB_CONNECTION_STRING
+    });
+    await client.connect();
+  }
+  return client;
+}
+```
+
+**Anti-patterns**:
+- ❌ Using new Pool() in Lambda functions
+- ❌ Fetching SSM parameters at runtime
+
+---
+
+### API Gateway CORS Standards
+**Category**: serverless-saas-aws
+**Rule**: NEVER use DefaultAuthorizer (breaks CORS preflight)
+
+**Example**:
+```yaml
+GetUserFunction:
+  Type: AWS::Serverless::Function
+  Properties:
+    Auth:
+      Authorizer: MyAuthorizer
+```
+
+**Anti-patterns**:
+- ❌ DefaultAuthorizer in SAM templates
+
+## Team Patterns
+
+### wrapHandler Usage
+**Correlation**: 95%
+**Usage**: 42 times across 5 projects
+**Rule**: Always use wrapHandler for Lambda functions
+
+---
+
+*Context provided by Rapport - mindmeld.dev*
+```
+
+### PreCompact Summary
+
+```json
+{
+  "patternsDetected": 5,
+  "violations": 1,
+  "reinforced": 4,
+  "promotionCandidates": 0,
+  "elapsed": 287
+}
+```
+
+---
+
+## Troubleshooting
+
+### Hook Not Executing
+
+**Symptoms**: Context not appearing in Claude Code
+
+**Solutions**:
+1. Check `package.json` has correct hook paths
+2. Verify hooks are executable: `chmod +x hooks/*.js`
+3. Ensure `.rapport/config.json` exists
+4. Check Claude Code logs for errors
+
+### Slow Performance
+
+**Symptoms**: SessionStart takes > 1 second
+
+**Solutions**:
+1. Run `npm run test:benchmark` to measure
+2. Check if standards need ingestion
+3. Verify database connection is fast
+4. Reduce `maxStandards` in config
+
+### No Standards Shown
+
+**Symptoms**: Context empty or minimal
+
+**Solutions**:
+1. Verify `.equilateral-standards/` exists
+2. Check standards ingestion: `SELECT COUNT(*) FROM rapport.standards_patterns`
+3. Test RelevanceDetector: `npm run test:hooks --relevance`
+4. Verify project characteristics detected
+
+### Violations Not Detected
+
+**Symptoms**: PreCompact always shows 0 violations
+
+**Solutions**:
+1. Check standards_patterns table populated
+2. Verify PatternValidator working: `npm run test:hooks --client`
+3. Check session transcript format
+4. Verify pattern detection logic
+
+---
+
+## Architecture
+
+```
+hooks/
+├── session-start.js
+│   ├── injectContext()
+│   ├── checkRapportConfiguration()
+│   └── formatContextInjection()
+│
+└── pre-compact.js
+    ├── harvestPatterns()
+    ├── validatePatterns()
+    └── checkPromotionCandidates()
+
+↓ Uses ↓
+
+src/index.js (RapportClient)
+├── ensureStandardsIngested()
+├── getRelevantStandards()
+├── detectPatternsFromSession()
+├── validatePattern()
+├── recordViolation()
+└── reinforcePattern()
+
+↓ Uses ↓
+
+src/core/
+├── RelevanceDetector.js
+│   └── detectRelevantStandards()
+├── PatternValidator.js
+│   └── validatePattern()
+└── StandardsIngestion.js
+    └── ingestEquilateralStandards()
+```
+
+---
+
+## Integration Points
+
+### Claude Code
+
+**SessionStart**:
+- Called at session initialization
+- Receives context string
+- Injects into system prompt
+
+**PreCompact**:
+- Called before compaction
+- Receives session transcript JSON
+- Processes results asynchronously
+
+### Rapport Database
+
+**Tables Used**:
+- `rapport.standards_patterns` - Ingested standards
+- `rapport.pattern_usage` - Pattern reinforcement
+- `rapport.projects` - Project configuration
+
+### .equilateral-standards
+
+**Read Operations**:
+- Standards markdown files
+- Anti-pattern examples
+- Cost impact data
+- Enforcement rules
+
+---
+
+## Best Practices
+
+### Do's
+
+✅ Keep SessionStart under 500ms
+✅ Always gracefully degrade on errors
+✅ Limit context to top 10 standards
+✅ Use cached ingestion checks
+✅ Log timing information
+
+### Don'ts
+
+❌ Never block Claude Code session
+❌ Don't fetch all standards
+❌ Avoid deep file content parsing
+❌ Don't make network calls during hooks
+❌ Don't fail on missing configuration
+
+---
+
+## Future Enhancements
+
+1. **Dynamic Standard Selection**: ML-based relevance scoring
+2. **User Preferences**: Customize standard visibility
+3. **Context Caching**: Redis-based cache layer
+4. **Incremental Learning**: Real-time pattern updates
+5. **Cross-Project Insights**: Share patterns across projects
+
+---
+
+## Support
+
+**Documentation**: `/Users/jamesford/Source/rapport/docs/PHASE_5_CLAUDE_CODE_INTEGRATION.md`
+**Test Suite**: `npm run test:hooks`
+**Issues**: Contact jim@equilateral.ai
+
+---
+
+**Version**: 3.0.0
+**Status**: ✅ Production Ready
+**Last Updated**: 2025-12-20