ima-claude 2.18.0 → 2.25.0

package/plugins/ima-claude/skills/php-fp/SKILL.md

@@ -5,84 +5,59 @@ description: "Core FP principles with anti-over-engineering focus - Simple > Com
 
 # PHP Functional Programming
 
-Core functional programming principles for PHP with anti-over-engineering enforcement. This skill provides error-preventing essentials and references to deep-dive content.
+## Anti-Over-Engineering (PRIMARY)
 
-## When to Use This Skill
+"Simple > Complex | Evidence > Assumptions"
 
-- Implementing pure, testable PHP functions
-- Need FP architectural guidance for PHP
-- Preventing over-engineering and custom FP utility creation
-- Comprehensive testing strategies with PHPUnit
-- Evidence-based performance optimization
-
-## CRITICAL: Anti-Over-Engineering (PRIMARY FOCUS)
-
-**Core Principle**: "Simple > Complex | Evidence > Assumptions"
-
-> **Clarification**: This skill prevents CREATING custom FP utility functions (pipe, compose, curry) to make PHP "feel" like Haskell. Using established libraries (Carbon, Collections, etc.) is perfectly fine. FP is a mindset—pure functions, immutability, composition—not a rigid API signature.
-
-### Don't Create Custom FP Utilities
+Don't CREATE custom FP utilities (pipe, compose, curry) to make PHP feel like Haskell. Using established libraries (Carbon, Collections) is fine. FP is a mindset — pure functions, immutability, composition — not an API signature.
 
 ```php
 <?php
-// DON'T CREATE: pipe() utility
+// DON'T: pipe() utility
 function pipe(...$functions) {
     return fn($value) => array_reduce($functions, fn($carry, $fn) => $fn($carry), $value);
 }
 
-// INSTEAD: Native early returns
+// DO: native early returns
 function validateUser(array $userData): array {
     $requiredCheck = validateRequired(['email', 'name'], $userData);
     if (!$requiredCheck['valid']) return $requiredCheck;
     return validateEmail($userData);
 }
 
-// DON'T CREATE: curry() utility
-// INSTEAD: Native closures
+// DON'T: curry() utility
+// DO: native closures
 function createValidator(array $rules): callable {
     return fn($value): array => ['valid' => empty(array_filter($rules, fn($r) => !$r['validator']($value)))];
 }
 
-// DON'T CREATE: Complex monad implementations
-// INSTEAD: Simple result arrays
+// DON'T: complex monad implementations
+// DO: simple result arrays
 function divide(float $a, float $b): array {
     return $b === 0.0 ? ['success' => false, 'error' => 'Division by zero'] : ['success' => true, 'data' => $a / $b];
 }
 ```
 
-### The 4-Question Quality Framework
-
-Before extracting or abstracting, ask:
-
-1. **"Can this be pure?"** - Separate business logic from side effects
-2. **"Can this use native patterns?"** - Avoid creating custom FP utilities, use PHP features
-3. **"Can this be simplified?"** - Choose simple solution over complex abstraction
-4. **"Is this complexity justified?"** - Evidence-based complexity decisions
+### 4-Question Quality Framework
 
-### When NOT to Extract: WordPress Example
+Before extracting or abstracting:
 
-**Context**: CRMAPI class sends webhook data via HTTP POST.
-
-**Analysis**: Applied 4-question framework - NO pure function extraction needed.
-
-- `sanitize_data()` uses `sanitize_text_field()` which applies WordPress filters - NOT PURE
-- `send_api_request()` uses WordPress HTTP API - NATIVE PATTERNS ALREADY
-- Current structure: 239 lines, ~35 lines of logic - ALREADY SIMPLE
-- Extraction would add indirection without benefits - NOT JUSTIFIED
-
-**Result**: Grade B+ (Appropriate WordPress Wrapper). Don't extract pure functions when WordPress integration IS the business logic.
+1. **"Can this be pure?"** — separate business logic from side effects
+2. **"Can this use native patterns?"** — avoid custom FP utilities
+3. **"Can this be simplified?"** — simple > complex
+4. **"Is this complexity justified?"** — evidence required
 
 ### Context-Appropriate Complexity
 
 ```php
 <?php
-// CLI Script: Simple and direct
+// CLI Script: direct
 function processFile(string $filePath): array {
     $data = file_get_contents($filePath);
     return array_map('strtoupper', array_filter(explode("\n", $data), fn($l) => trim($l) !== ''));
 }
 
-// Production Service: Appropriate error handling
+// Production Service: appropriate error handling + logging
 function processFile(string $filePath, LoggerInterface $logger): array {
     try {
         if (!file_exists($filePath)) throw new InvalidArgumentException("File not found: {$filePath}");
@@ -96,20 +71,18 @@ function processFile(string $filePath, LoggerInterface $logger): array {
 }
 ```
 
-## Core FP Patterns (Quick Reference)
+## Core Patterns
 
-### 1. Purity and Side Effect Isolation
+### Purity + Side Effect Isolation
 
 ```php
 <?php
 declare(strict_types=1);
 
-// PURE: business logic
 function calculateTotal(array $items): float {
     return array_reduce($items, fn($sum, $item) => $sum + $item['price'], 0.0);
 }
 
-// ISOLATED: side effects separate
 function logAndCalculate(array $items, LoggerInterface $logger): float {
     $total = calculateTotal($items);
     $logger->info("Total: {$total}");
@@ -117,18 +90,16 @@ function logAndCalculate(array $items, LoggerInterface $logger): float {
 }
 ```
 
-### 2. Composition Over Inheritance
+### Composition Over Inheritance
 
 ```php
 <?php
-// Simple validators that compose
 function validateRequired($value): bool { return $value !== null && $value !== ''; }
 function validateEmail(string $value): bool { return filter_var($value, FILTER_VALIDATE_EMAIL) !== false; }
 function validateLength(int $min, int $max): callable {
     return fn(string $value): bool => strlen($value) >= $min && strlen($value) <= $max;
 }
 
-// Composition without utilities
 function validateUserEmail(string $email): array {
     if (!validateRequired($email)) return ['valid' => false, 'error' => 'Required'];
     if (!validateEmail($email)) return ['valid' => false, 'error' => 'Invalid email'];
@@ -137,16 +108,14 @@ function validateUserEmail(string $email): array {
 }
 ```
 
-### 3. Dependency Injection
+### Dependency Injection
 
 ```php
 <?php
-// Explicit dependencies, fully testable
 function saveUser(array $userData, PasswordHasherInterface $hasher, DatabaseInterface $db): array {
     return $db->save(['name' => $userData['name'], 'password' => $hasher->hash($userData['password'])]);
 }
 
-// Service with constructor DI
 class UserService {
     public function __construct(
         private readonly PasswordHasherInterface $hasher,
@@ -159,11 +128,10 @@ class UserService {
 }
 ```
 
-### 4. Immutability
+### Immutability
 
 ```php
 <?php
-// Always return new arrays
 function updateUserSettings(array $user, array $settings): array {
     return [...$user, 'settings' => array_merge($user['settings'] ?? [], $settings), 'updated_at' => time()];
 }
@@ -175,15 +143,12 @@ function updateItem(array $items, int $id, array $updates): array {
 }
 ```
 
-## PHP-Specific Patterns
-
-### Native Array Functions + Strict Types (MANDATORY)
+## PHP-Specific: Native Array Functions + Strict Types (MANDATORY)
 
 ```php
 <?php
 declare(strict_types=1);
 
-// Native array methods over loops
 function processUsers(array $users): array {
     return array_slice(
         array_map(fn($u) => [...$u, 'display_name' => "{$u['first_name']} {$u['last_name']}"],
@@ -192,7 +157,7 @@ function processUsers(array $users): array {
     );
 }
 
-// Match expressions (PHP 8.0+)
+// match over switch (PHP 8.0+)
 function getTierDiscount(string $tier): float {
     return match($tier) {
         'bronze' => 0.05, 'silver' => 0.10, 'gold' => 0.15, 'platinum' => 0.20, default => 0.0
@@ -209,12 +174,11 @@ function processResult(array|false $result): array {
 
 ```php
 <?php
-// Standard result shape
 function createResult($data = null, ?string $error = null): array {
     return $error !== null ? ['success' => false, 'error' => $error] : ['success' => true, 'data' => $data];
 }
 
-// Chain results with early return
+// Chain with early return
 function calculate(float $a, float $b, float $c): array {
     $r1 = divide($a, $b);
     if (!$r1['success']) return $r1;
@@ -222,20 +186,16 @@ function calculate(float $a, float $b, float $c): array {
 }
 ```
 
-> **Deep dive**: See `references/core-principles.md` for complete Result Type patterns and error handling strategies.
-
-## Testing Essentials
+## Testing
 
-Pure functions enable testing ALL edge cases systematically.
+Pure functions enable systematic edge-case coverage.
 
 ```php
 <?php
 use PHPUnit\Framework\TestCase;
 
 class CalculatorTest extends TestCase {
-    /**
-     * @dataProvider discountProvider
-     */
+    /** @dataProvider discountProvider */
     public function testCalculateDiscount(float $price, float $rate, float $expected): void {
         $this->assertEquals($expected, calculateDiscount($price, $rate));
     }
@@ -243,26 +203,22 @@ class CalculatorTest extends TestCase {
     public function discountProvider(): array {
         return [
             'standard' => [100.0, 0.1, 90.0],
-            'zero' => [100.0, 0.0, 100.0],
-            'full' => [100.0, 1.0, 0.0],
+            'zero'     => [100.0, 0.0, 100.0],
+            'full'     => [100.0, 1.0, 0.0],
         ];
     }
 }
 ```
 
-> **Deep dive**: See `references/testing-patterns.md` for comprehensive PHPUnit strategies, edge case patterns, mocking, and test organization.
+## Performance: Configuration Pre-Compilation (Evidence-Based)
 
-## Performance Patterns (Evidence-Based)
-
-Optimize only when needed with evidence. Key pattern: **Configuration Pre-Compilation**.
+Optimize only with evidence. Key pattern: pre-compile config once, execute linearly.
 
 ```php
 <?php
-// Problem: O(records x config) - config accessed every iteration
-// Solution: Pre-compile configuration once
-
+// Problem: O(records × config) — config accessed every iteration
+// Solution: pre-compile once
 function createRecordProcessor(array $schema): callable {
-    // Setup once
     $fieldProcessors = array_map(fn($f) => fn($v) => transformField($v, $f['type']), $schema['fields']);
 
     return function(array $record) use ($schema, $fieldProcessors): array {
@@ -274,60 +230,25 @@ function createRecordProcessor(array $schema): callable {
     };
 }
 
-$processor = createRecordProcessor($schema); // Setup phase
-$results = array_map($processor, $records);  // Linear execution
+$processor = createRecordProcessor($schema); // setup once
+$results = array_map($processor, $records);  // linear execution
 ```
 
-**Real-world result**: Email validation in ima-espo achieved 2-5x speedup with function factory pattern. 130 tests, 236 assertions, <30ms total.
-
-## Quality Gates Checklist
-
-Before implementation:
-
-1. **"Can this be pure?"** - Separate business logic from side effects
-2. **"Can this use native patterns?"** - Avoid creating custom FP utilities
-3. **"Can this be simplified?"** - Simple > complex
-4. **"Is this complexity justified?"** - Evidence required
-5. **"Is this testable?"** - Pure functions enable comprehensive testing
-6. **"Are strict types used?"** - `declare(strict_types=1)` at file top
-
-## When to Load Reference Files
-
-### Deep Principles and Explanations
-**File**: `references/core-principles.md`
-**Load when**:
-- Learning mode or explaining WHY behind patterns
-- Making architectural decisions
-- Need complete Result Type patterns
-- Anti-pattern recognition details
-- Cross-pattern comparisons
-
-### Testing Methodology
-**File**: `references/testing-patterns.md`
-**Load when**:
-- Building comprehensive test suites
-- Improving test coverage
-- Edge case analysis and boundary testing
-- Setting up mocking strategies
-- Performance testing pure functions
-
-### Working Examples
-**Directory**: `examples/`
-**Load when**:
-- Need complete working code
-- Integration examples
-- Learning implementation patterns
-
-## Integration with Domain Skills
-
-This core skill provides the foundation for:
+Real result: ima-espo email validation — 2-5x speedup, 130 tests, 236 assertions, <30ms total.
 
-- **php-fp-wordpress**: WordPress patterns with FP principles
-- **php-fp-laravel**: Laravel patterns with FP principles (future)
-- **php-fp-symfony**: Symfony patterns with FP principles (future)
+## Quality Gates
 
-Each domain skill references this core and adds domain-specific patterns.
+1. Pure? — business logic separated from side effects
+2. Native? — no custom FP utilities
+3. Simple? — simple > complex
+4. Justified? — evidence for complexity
+5. Testable? — pure functions have tests
+6. Strict types? — `declare(strict_types=1)` at file top
 
-## Philosophy
+## Reference Files
 
-*"Pure functions, native PHP patterns, strict types, appropriate complexity, and comprehensive testing for maintainable, predictable code that respects the language and solves real problems simply."*
+| File | Load When |
+|------|-----------|
+| `references/core-principles.md` | Architectural decisions, full Result Type patterns, anti-pattern recognition |
+| `references/testing-patterns.md` | Comprehensive test suites, edge cases, mocking, performance testing |
+| `examples/` | Complete working code, integration examples |

package/plugins/ima-claude/skills/php-fp-wordpress/SKILL.md

@@ -5,28 +5,13 @@ description: "Security-first WordPress development with PHP FP principles - pure
 
 # PHP FP - WordPress
 
-Security-first WordPress development combining PHP functional programming principles with mandatory WordPress security practices.
+Security-first WordPress development: pure functions for business logic, WordPress wrappers with mandatory security.
 
-## When to Use This Skill
-
-- Building WordPress plugins or themes
-- Need security-first development practices
-- Implementing pure business logic with WordPress integration
-- Testing WordPress functionality
-
-## Core Philosophy
-
-**Security practices prevent vulnerabilities, not architectural patterns.**
-
-Hybrid approach:
-1. **Pure functions** for business logic (testable, no WordPress deps)
-2. **WordPress wrappers** with mandatory security (capability, nonce, sanitize, escape, prepare)
-
-**Foundation**: Reference `../php-fp/SKILL.md` for PHP FP core principles.
+**Foundation**: `../php-fp/SKILL.md` for PHP FP core.
 
 ## The 5 Non-Negotiable Security Practices
 
-**Evidence**: Analysis of 7,966 vulnerabilities (2024) shows these prevent 95%+ of WordPress plugin vulnerabilities.
+Evidence: 7,966 vulnerabilities (2024) — these prevent 95%+ of WordPress plugin vulnerabilities.
 
 | Practice | Prevents | Rule |
 |----------|----------|------|
@@ -36,18 +21,20 @@ Hybrid approach:
 | **Output Escaping** | XSS | Escape ALL output by context |
 | **Prepared Statements** | SQL injection | `$wpdb->prepare()` for ALL queries |
 
-### Quick Reference: Security Functions
+### Security Function Reference
 
 **Sanitization (Input)**:
+
 | Function | Use For |
 |----------|---------|
 | `sanitize_text_field()` | Plain text |
 | `sanitize_email()` | Email addresses |
 | `absint()` | Positive integers |
 | `wp_kses_post()` | HTML content |
-| `esc_url_raw()` | URLs (for storage) |
+| `esc_url_raw()` | URLs (storage) |
 
 **Escaping (Output)**:
+
 | Function | Context |
 |----------|---------|
 | `esc_html()` | HTML body |
@@ -60,37 +47,30 @@ Hybrid approach:
 ```php
 <?php
 add_action('wp_ajax_my_action', function() {
-    // 1. Capability check
     if (!current_user_can('edit_posts')) {
         wp_send_json_error('Unauthorized', 403);
     }
 
-    // 2. Nonce verification
     check_ajax_referer('my_action_nonce', 'nonce');
 
-    // 3. Sanitize input
-    $id = absint($_POST['id']);
+    $id   = absint($_POST['id']);
     $name = sanitize_text_field($_POST['name']);
 
-    // 4. Use prepared statement
     global $wpdb;
     $result = $wpdb->get_row($wpdb->prepare(
         "SELECT * FROM {$wpdb->prefix}my_table WHERE id = %d",
         $id
     ));
 
-    // 5. Escape output
     wp_send_json_success(['name' => esc_html($result->name)]);
 });
 ```
 
 ## Pure Logic + WordPress Wrapper Pattern
 
-**Separate testable business logic from WordPress integration.**
-
 ```php
 <?php
-// PURE: Zero WordPress dependencies, fully testable
+// PURE: zero WordPress dependencies, fully testable
 namespace MyPlugin\Pure;
 
 function calculate_discount(float $price, string $tier): float {
@@ -103,7 +83,6 @@ namespace MyPlugin;
 
 add_filter('product_price', function($price) {
     if (!is_user_logged_in()) return $price;
-
     $tier = get_user_meta(get_current_user_id(), 'tier', true);
     return Pure\calculate_discount($price, $tier);
 });
@@ -111,7 +90,7 @@ add_filter('product_price', function($price) {
 
 ## Inter-Plugin Communication: Hooks Only
 
-**Rule**: ALL cross-plugin calls use WordPress hooks. NEVER `function_exists()`.
+ALL cross-plugin calls use WordPress hooks. NEVER `function_exists()`.
 
 Hooks are safe no-ops — if nobody listens, nothing happens. `function_exists()` is tight coupling disguised as loose coupling.
 
@@ -125,21 +104,20 @@ if (function_exists('ima_discourse_refresh_user_meta')) {
 // GOOD — fire-and-forget side effect
 do_action('ima_discourse_refresh_user_meta', $user_id);
 
-// GOOD — transform with safe default (function composition via WP)
+// GOOD — transform with safe default
 $result = apply_filters('ima_membership_cancel_subscription', ['success' => true], $user_id, $sub_id);
 ```
 
-**Actions** (`do_action`): Side effects — "something happened, react if you care."
-**Filters** (`apply_filters`): Data transformation — chained function composition with a default return.
+- **Actions** (`do_action`): side effects — "something happened, react if you care"
+- **Filters** (`apply_filters`): data transformation — chained composition with default return
 
-The handler registers itself:
 ```php
 <?php
-// ima-discourse registers once — or doesn't. Either way, callers don't crash.
+// Handler registers itself — callers never crash if plugin is absent
 add_action('ima_discourse_refresh_user_meta', 'ima_discourse_refresh_user_meta', 10, 1);
 ```
 
-**When `function_exists()` is acceptable**: Internal guard clauses within a single plugin checking if its own functions are loaded, or checking PHP extensions (`function_exists('sodium_crypto_secretbox')`).
+`function_exists()` is acceptable only for internal guards within a single plugin, or checking PHP extensions (`function_exists('sodium_crypto_secretbox')`).
 
 ## Plugin Complexity Guide
 
@@ -149,7 +127,7 @@ add_action('ima_discourse_refresh_user_meta', 'ima_discourse_refresh_user_meta',
 | Medium | 500-2000 | Classes + pure functions |
 | Complex | 2000+ | DI Container + Services |
 
-**Rule**: Start simple, add complexity only when needed.
+Start simple, add complexity only when needed.
 
 ## File Organization
 
@@ -165,7 +143,7 @@ my-plugin/
     └── integration/           # WordPress tests
 ```
 
-## Security Checklist
+## Quality Gates
 
 - [ ] Capability checks on all privileged operations
 - [ ] Nonces on all form/AJAX submissions
@@ -176,41 +154,15 @@ my-plugin/
 - [ ] No hardcoded credentials
 - [ ] Cross-plugin calls use hooks, not `function_exists()`
 
-## Quality Gates
-
-1. **Security**: All 5 mandatory practices implemented?
-2. **Pure logic**: Business logic separated from WordPress?
-3. **Testability**: Pure functions have unit tests?
-4. **Complexity**: Architecture matches plugin size?
-
-## When to Load Reference Files
-
-### Security Deep-Dive
-**File**: [`references/security-examples.md`](references/security-examples.md)
-**Load when**: Need detailed security patterns, vulnerable vs. safe comparisons
-**Contains**: Full examples for all 5 practices, security function reference tables
-
-### FP Patterns
-**File**: [`references/fp-patterns.md`](references/fp-patterns.md)
-**Load when**: Implementing pure logic + wrapper pattern, function factories
-**Contains**: Complete membership system example, production email validator example
-
-### Plugin Architecture
-**File**: [`references/plugin-architecture.md`](references/plugin-architecture.md)
-**Load when**: Deciding plugin structure, implementing DI container
-**Contains**: Simple/medium/complex plugin patterns, file organization examples
-
-### Testing Strategy
-**File**: [`references/testing-strategy.md`](references/testing-strategy.md)
-**Load when**: Setting up tests, writing security tests
-**Contains**: Unit/integration test examples, minimal mock bootstrap, security test patterns
-
-## Success Metrics
+## Reference Files
 
-- **Security**: Zero vulnerabilities from missing practices
-- **Testability**: 95%+ coverage for pure functions
-- **Maintainability**: Clear separation of concerns
+| File | Load When |
+|------|-----------|
+| `references/security-examples.md` | Detailed security patterns, vulnerable vs. safe comparisons |
+| `references/fp-patterns.md` | Pure logic + wrapper pattern, function factories, production examples |
+| `references/plugin-architecture.md` | Plugin structure decisions, DI container implementation |
+| `references/testing-strategy.md` | Unit/integration tests, security tests, minimal mock bootstrap |
 
 ---
 
-**Evidence Base**: Analysis of 7,966 WordPress vulnerabilities (2024), WordPress Core Team standards, Wordfence/Patchstack research.
+Evidence: 7,966 WordPress vulnerabilities (2024), WordPress Core Team standards, Wordfence/Patchstack research.