refactor: architectural cleanup — dead guards + long-deprecated shims (−593 LOC)

docs/ai-tools/tools-overview.md

@@ -475,16 +475,18 @@ See Tool Manager for complete documentation.
 
 ### ToolExecutor Pattern
 
-All tools integrate via the universal `ToolExecutor` class (`/inc/Engine/AI/Tools/ToolExecutor.php`):
+All tools integrate via the universal `ToolExecutor` class
+(`/inc/Engine/AI/Tools/ToolExecutor.php`) for execution, and the
+`ToolPolicyResolver` for discovery:
 
 ```php
 // Tool discovery
-$available_tools = \DataMachine\Engine\AI\ToolExecutor::getAvailableTools(
-    $agent_type,  // 'pipeline' or 'chat'
-    $handler_slug,
-    $handler_config,
-    $flow_step_id
-);
+$resolver        = new \DataMachine\Engine\AI\Tools\ToolPolicyResolver();
+$available_tools = $resolver->resolve( array(
+    'mode'             => \DataMachine\Engine\AI\Tools\ToolPolicyResolver::MODE_PIPELINE,
+    'pipeline_step_id' => $flow_step_id,
+    'engine_data'      => $engine_data,
+) );
 ```
 
 **Discovery Process**:

docs/core-system/tool-execution.md

@@ -25,28 +25,32 @@ Handles tool discovery via filters, enablement validation, and execution with co
 
 ### Tool Discovery
 
-Tools are discovered through three filter-based registration patterns:
+Tools are discovered through three filter-based registration patterns, and
+resolved via `ToolPolicyResolver::resolve()` — the single entry point for
+both chat and pipeline modes:
 
 ```php
-public static function getAvailableTools(
-    ?array $previous_step_config = null,
-    ?array $next_step_config = null,
-    ?string $current_pipeline_step_id = null
-): array
+use DataMachine\Engine\AI\Tools\ToolPolicyResolver;
+
+$resolver = new ToolPolicyResolver();
 ```
 
 **Pipeline Agent Usage** (with step context):
 ```php
-$tools = ToolExecutor::getAvailableTools(
-    $previous_step_config,    // Previous step configuration
-    $next_step_config,        // Next step configuration
-    $current_pipeline_step_id // Current pipeline step ID
-);
+$tools = $resolver->resolve( array(
+    'mode'                 => ToolPolicyResolver::MODE_PIPELINE,
+    'previous_step_config' => $previous_step_config,
+    'next_step_config'     => $next_step_config,
+    'pipeline_step_id'     => $current_pipeline_step_id,
+    'engine_data'          => $engine_data,
+) );
 ```
 
 **Chat Agent Usage** (global tools only):
 ```php
-$tools = ToolExecutor::getAvailableTools(null, null, null);
+$tools = $resolver->resolve( array(
+    'mode' => ToolPolicyResolver::MODE_CHAT,
+) );
 ```
 
 ### Tool Registration Patterns

docs/development/hooks/core-filters.md

@@ -1197,14 +1197,22 @@ Builds parameters for handler-specific tools with engine data merging (source_ur
 
 **Core Method**:
 
-#### `getAvailableTools()`
+#### `ToolPolicyResolver::resolve()`
+
+Tool discovery moved from `ToolExecutor::getAvailableTools()` (removed in 0.79)
+to `ToolPolicyResolver::resolve()`. Single entry point for chat and pipeline
+modes.
+
 ```php
-\DataMachine\Engine\AI\ToolExecutor::getAvailableTools(
-    string $agent_type,      // 'pipeline' or 'chat'
-    ?string $handler_slug,   // Handler identifier
-    array $handler_config,   // Handler configuration
-    ?string $flow_step_id    // Flow step identifier
-): array
+$resolver = new \DataMachine\Engine\AI\Tools\ToolPolicyResolver();
+
+$tools = $resolver->resolve( array(
+    'mode'                 => ToolPolicyResolver::MODE_PIPELINE, // or MODE_CHAT, MODE_SYSTEM
+    'previous_step_config' => $previous_step_config,
+    'next_step_config'     => $next_step_config,
+    'pipeline_step_id'     => $flow_step_id,
+    'engine_data'          => $engine_data,
+) );
 ```
 
 **Discovery Process**:

homeboy.json

@@ -24,6 +24,45 @@
     }
   },
   "id": "data-machine",
+  "transforms": {
+    "drop_wp_ability_dead_guards": {
+      "description": "Drop dead class_exists('WP_Ability') and class_exists('WP_Abilities_Registry') guards. Plugin header requires WP 6.9 where both classes ship in core, so every guard on these symbols is unreachable. Ref: https://github.com/Extra-Chill/data-machine/issues/XXXX",
+      "rules": [
+        {
+          "id": "simple_guard",
+          "description": "Remove standalone if ( ! class_exists( 'WP_Ability' ) ) { return; } blocks.",
+          "find": "(?s)\n\t\tif \\( ! class_exists\\( ?'WP_Ability' ?\\) \\) \\{\n\t\t\treturn;\n\t\t\\}\n",
+          "replace": "",
+          "files": "inc/Abilities/**/*.php",
+          "context": "file"
+        },
+        {
+          "id": "combined_guard_registered",
+          "description": "Drop the WP_Ability half of 'if ( ! class_exists( WP_Ability ) || self::$registered ) { return; }' guards.",
+          "find": "(?s)if \\( ! class_exists\\( 'WP_Ability' \\) \\|\\| self::\\$registered \\) \\{\n\t+return;\n\t+\\}",
+          "replace": "if ( self::$$registered ) {\n\t\t\treturn;\n\t\t}",
+          "files": "inc/Abilities/**/*.php",
+          "context": "file"
+        },
+        {
+          "id": "ternary_registry_guard",
+          "description": "Replace '(class_exists(WP_Abilities_Registry) ? WP_Abilities_Registry::get_instance() : null)' with a direct call — the ternary is unreachable.",
+          "find": "class_exists\\( 'WP_Abilities_Registry' \\) \\? \\\\WP_Abilities_Registry::get_instance\\(\\) : null",
+          "replace": "\\\\WP_Abilities_Registry::get_instance()",
+          "files": "inc/**/*.php",
+          "context": "line"
+        },
+        {
+          "id": "combined_guard_registered_engine",
+          "description": "Same as combined_guard_registered but catches the one hit in inc/Engine/ (ResolvePendingActionAbility).",
+          "find": "(?s)if \\( ! class_exists\\( 'WP_Ability' \\) \\|\\| self::\\$registered \\) \\{\n\t+return;\n\t+\\}",
+          "replace": "if ( self::$$registered ) {\n\t\t\treturn;\n\t\t}",
+          "files": "inc/Engine/**/*.php",
+          "context": "file"
+        }
+      ]
+    }
+  },
   "version_targets": [
     {
       "file": "data-machine.php",

inc/Abilities/AgentAbilities.php

@@ -23,10 +23,6 @@ class AgentAbilities {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		if ( self::$registered ) {
 			return;
 		}

inc/Abilities/AgentMemoryAbilities.php

@@ -22,10 +22,6 @@ class AgentMemoryAbilities {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		if ( self::$registered ) {
 			return;
 		}

inc/Abilities/AgentPing/SendPingAbility.php

@@ -18,10 +18,6 @@
 class SendPingAbility {
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/AgentPingAbilities.php

@@ -23,7 +23,7 @@ class AgentPingAbilities {
 	private SendPingAbility $send_ping;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/AgentRemoteCall/AgentRemoteCallAbility.php

@@ -23,10 +23,6 @@
 class AgentRemoteCallAbility {
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/AgentRemoteCallAbilities.php

@@ -21,7 +21,7 @@ class AgentRemoteCallAbilities {
 	private AgentRemoteCallAbility $remote_call;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/AgentTokenAbilities.php

@@ -21,7 +21,7 @@ class AgentTokenAbilities {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/Analytics/BingWebmasterAbilities.php

@@ -58,10 +58,6 @@ class BingWebmasterAbilities {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		if ( self::$registered ) {
 			return;
 		}

inc/Abilities/Analytics/GoogleAnalyticsAbilities.php

@@ -104,10 +104,6 @@ class GoogleAnalyticsAbilities {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		if ( self::$registered ) {
 			return;
 		}

inc/Abilities/Analytics/GoogleSearchConsoleAbilities.php

@@ -61,10 +61,6 @@ class GoogleSearchConsoleAbilities {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		if ( self::$registered ) {
 			return;
 		}

inc/Abilities/Analytics/PageSpeedAbilities.php

@@ -68,10 +68,6 @@ class PageSpeedAbilities {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		if ( self::$registered ) {
 			return;
 		}

inc/Abilities/AuthAbilities.php

@@ -31,7 +31,7 @@ class AuthAbilities {
 	public function __construct() {
 		$this->handler_abilities = new HandlerAbilities();
 
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/Chat/CreateChatSessionAbility.php

@@ -20,10 +20,6 @@ class CreateChatSessionAbility {
 	public function __construct() {
 		$this->initDatabase();
 
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/Chat/DeleteChatSessionAbility.php

@@ -19,10 +19,6 @@ class DeleteChatSessionAbility {
 	public function __construct() {
 		$this->initDatabase();
 
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/Chat/GetChatSessionAbility.php

@@ -20,10 +20,6 @@ class GetChatSessionAbility {
 	public function __construct() {
 		$this->initDatabase();
 
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/Chat/ListChatSessionsAbility.php

@@ -19,10 +19,6 @@ class ListChatSessionsAbility {
 	public function __construct() {
 		$this->initDatabase();
 
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/Chat/MarkSessionReadAbility.php

@@ -21,10 +21,6 @@ class MarkSessionReadAbility {
 	public function __construct() {
 		$this->initDatabase();
 
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/Chat/SendMessageAbility.php

@@ -25,10 +25,6 @@
 class SendMessageAbility {
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) ) {
-			return;
-		}
-
 		$this->registerAbility();
 	}
 

inc/Abilities/ChatAbilities.php

@@ -31,7 +31,7 @@ class ChatAbilities {
 	private SendMessageAbility $send_message;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/Content/EditPostBlocksAbility.php

@@ -23,7 +23,7 @@ class EditPostBlocksAbility {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/Content/GetPostBlocksAbility.php

@@ -21,7 +21,7 @@ class GetPostBlocksAbility {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/Content/InsertContentAbility.php

@@ -24,7 +24,7 @@ class InsertContentAbility {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/Content/ReplacePostBlocksAbility.php

@@ -22,7 +22,7 @@ class ReplacePostBlocksAbility {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}
 

inc/Abilities/Content/UpsertPostAbility.php

@@ -39,7 +39,7 @@ class UpsertPostAbility {
 	private static bool $registered = false;
 
 	public function __construct() {
-		if ( ! class_exists( 'WP_Ability' ) || self::$registered ) {
+		if ( self::$registered ) {
 			return;
 		}