feat: ability categories and tool-ability linkage for pipeline tool scoping

[chubes4]

Summary

• Split flat datamachine ability category into 18 semantic subcategories (content, media, analytics, seo, memory, taxonomy, publishing, fetch, email, pipeline, flow, jobs, agent, settings, auth, logging, system, chat)
• Added ability / abilities metadata to all 56 tool registrations so every tool declares which ability it wraps
• Wired category-based filtering into ToolPolicyResolver — pipelines can declare tool_categories to scope which tools the AI step receives
• Agent tool policies now support categories alongside individual tool names

Problem

Every pipeline AI step got all tools tagged pipeline regardless of relevance — google_analytics, bing_webmaster, amazon_affiliate_link in an RSS→AI→publish pipeline. With extensions installed, this scales to 30-50+ tools burning 6,000-25,000 tokens per AI request before any content.

Solution

Tools inherit their category from their linked ability via the WordPress Abilities API. The ToolPolicyResolver resolves categories at runtime:

Tool declares: ability => 'datamachine/local-search'
Ability registered: category => 'datamachine/content'
Pipeline declares: tool_categories: ['datamachine/content', 'datamachine/media']
→ Tool included ✅

New files

• inc/Abilities/AbilityCategories.php — centralized category registration with constants

Key changes

• 142 files — ability category updates across all ability registrations
• ToolPolicyResolver.php — new filterByAbilityCategories() method + category support in agent policies
• AIStep.php — reads tool_categories from pipeline step or pipeline-level config
• AllAbilitiesRegisteredTest.php — validates all 18 categories

Backwards compatible

Empty tool_categories = no filtering = current behavior. Handler tools (via chubes_ai_tools) bypass category filtering since they're already scoped by adjacent step handlers.

Follow-up needed

• Extension repos (data-machine-code, data-machine-events) need their abilities updated to use subcategories
• Pipeline builder UI for category picker
• Aligns with wp-ai-client migration (Replace bundled ai-http-client with core wp-ai-client #1027) where using_abilities() + category queries replace the tool registry

Resolves phases 1-2 of #924.

[homeboy-ci]

Homeboy Results — data-machine

Audit

⚡ Scope: changed files only

✅ audit (changed files only)

• Alignment score: 0.795
• Outliers in current run: 45
• Drift increased: no
• Severity counts: info: 238, unknown: 45, warning: 462
• Top actionable findings:
  1. inc/Abilities/PermissionHelper.php — naming_mismatch — Helper-like name does not match convention suffix 'Abilities': PermissionHelper
  2. inc/Abilities/PermissionHelper.php — missing_import — Missing import: DataMachine\Abilities\PermissionHelper
  3. inc/Abilities/AgentTokenAbilities.php — missing_import — Missing import: DataMachine\Abilities\PermissionHelper
  4. inc/Abilities/AbilityCategories.php — naming_mismatch — Helper-like name does not match convention suffix 'Abilities': AbilityCategories
  5. inc/Abilities/Analytics/PageSpeedAbilities.php — missing_method — Missing method: fetchStats
  6. inc/Api/Execute.php — missing_method — Missing method: check_permission
  7. inc/Api/WebhookTrigger.php — missing_method — Missing method: check_permission
  8. inc/Api/Email.php — signature_mismatch — Signature mismatch for check_permission: different structure — expected 8 tokens, found 6. Example: public static function check_permission(): bool {
  9. inc/Core/Auth/AgentAuthMiddleware.php — missing_method — Missing method: register_routes
  10. inc/Core/Auth/AgentAuthMiddleware.php — missing_registration — Missing registration: rest_api_init

Audit findings (10 shown)

1. **inc/Abilities/PermissionHelper.php** — naming_mismatch — Helper-like name does not match convention suffix 'Abilities': PermissionHelper
2. **inc/Abilities/PermissionHelper.php** — missing_import — Missing import: DataMachine\Abilities\PermissionHelper
3. **inc/Abilities/AgentTokenAbilities.php** — missing_import — Missing import: DataMachine\Abilities\PermissionHelper
4. **inc/Abilities/AbilityCategories.php** — naming_mismatch — Helper-like name does not match convention suffix 'Abilities': AbilityCategories
5. **inc/Abilities/Analytics/PageSpeedAbilities.php** — missing_method — Missing method: fetchStats
6. **inc/Api/Execute.php** — missing_method — Missing method: check_permission
7. **inc/Api/WebhookTrigger.php** — missing_method — Missing method: check_permission
8. **inc/Api/Email.php** — signature_mismatch — Signature mismatch for check_permission: different structure — expected 8 tokens, found 6. Example: `public static function check_permission(): bool {`
9. **inc/Core/Auth/AgentAuthMiddleware.php** — missing_method — Missing method: register_routes
10. **inc/Core/Auth/AgentAuthMiddleware.php** — missing_registration — Missing registration: rest_api_init

Tooling versions

• Homeboy CLI: homeboy 0.88.7+352d04b3
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: unknown
• Action: Extra-Chill/homeboy-action@v2

---

Homeboy Action v1