feat(ast): add hook argument mismatch detection and docs updates

Author: noelsaw1

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- AST hook analysis: new `HookRegistrationVisitor` (`dist/bin/ast/HookRegistrationVisitor.php`) extracts `add_action`, `add_filter`, `do_action`, `apply_filters`, `remove_action`, and `remove_filter` calls from the AST, along with function/method parameter counts for cross-referencing
+- New AST rule `hook-arg-mismatch` with three checks:
+  - `arg_count`: detects callbacks that require more parameters than `accepted_args` will provide, or define extra parameters that will never receive values
+  - `priority_conflict`: flags multiple different callbacks registered on the same hook at the same priority within the scanned codebase
+  - `fire_arg_count`: detects `do_action`/`apply_filters` fire points that pass fewer arguments than registered callbacks expect
+- New AST rule `hook-inventory`: outputs all hook registrations and fire points found in scanned files, sorted by hook name and priority — no findings, just structured data for audit and exploration
+- Test fixture `dist/tests/fixtures/ast-hook-mismatch.php` covering all three hook-arg-mismatch checks including class-based `[$this, 'method']` callbacks
+- Example config `dist/bin/ast/config/hook-arg-mismatch.example.json` with `target_hooks` and `checks` options
+
 ### Changed
 
 - Admin-only hook whitelist for `spo-004-missing-cap-check`: `add_action()` calls using inherently-admin-only hooks (`admin_notices`, `admin_init`, `admin_menu`, `admin_head`, `admin_footer`, `admin_enqueue_scripts`, `admin_print_styles`, `admin_print_scripts`, `network_admin_menu`, `user_admin_menu`, `network_admin_notices`, `admin_bar_init`, `admin_action_*`, `load-*`) are now downgraded to INFO severity instead of HIGH, reducing false positives for capability check findings

ask_self/WPCC-AI-DDTK-INTEGRATION.md

@@ -86,6 +86,15 @@ the current and planned architecture.
 │   ┌─────────────────── Step 4: Runtime Verification (optional) ────────────┐    │
 │   │                        (requires running WP site)                       │    │
 │   │                                                                         │    │
+│   │   ┌───────────────────────────────────────────────────────────────────┐  │    │
+│   │   │   Playwright + Passwordless Login (pw_auth)                      │  │    │
+│   │   │                                                                   │  │    │
+│   │   │   mu-plugin auto-login · no credentials in agent context         │  │    │
+│   │   │   Authenticated page loads at near-manual-operator quality        │  │    │
+│   │   │   Drives all runtime tools below (QM, HookTrace, DOM checks)     │  │    │
+│   │   └───────────────────────────────────────────────────────────────────┘  │    │
+│   │          │ authenticated browser sessions                                │    │
+│   │          ▼                                                               │    │
 │   │   ┌─────────────────────┐     ┌──────────────────────┐                  │    │
 │   │   │   Query Monitor     │     │   HookTrace          │                  │    │
 │   │   │                     │     │                      │                  │    │
@@ -113,9 +122,9 @@ the current and planned architecture.
 │   ┌───────────────────────────────────────────────────────────────────────────┐  │
 │   │                          MCP Server (26 tools)                           │  │
 │   │                                                                          │  │
-│   │  local_wp_*  ·  wpcc_*  ·  qm_*  ·  pw_auth_*  ·  tmux_*              │  │
-│   │  ask_self_query  ·  ask_self_review  ·  wpcc_ast_check                  │  │
-│   │  hooktrace_*  (planned)                                                  │  │
+│   │  pw_auth_* (passwordless login)  ·  qm_* (profiling)  ·  wpcc_* (scan) │  │
+│   │  local_wp_* (site mgmt)  ·  tmux_* (sessions)  ·  wpcc_ast_check      │  │
+│   │  ask_self_query  ·  ask_self_review  ·  hooktrace_* (planned)           │  │
 │   └───────────────────────────────────────────────────────────────────────────┘  │
 │                                                                                 │
 └─────────────────────────────────────────────────────────────────────────────────┘
@@ -142,18 +151,20 @@ COMPONENT OWNERSHIP
   │              │    │              │    │              │
   │ · Scanner    │    │ · RAG engine │    │ · MCP server │
   │ · 54 grep    │    │ · Ingest     │    │ · Loop ctrl  │
-  │   patterns   │    │ · Query      │    │ · QM bridge  │
-  │ · Semgrep    │    │ · Review     │    │ · HookTrace  │
-  │   rules      │    │   (planned)  │    │   bridge     │
-  │ · AST checker│    │ · Harness    │    │   (planned)  │
-  │ · Pattern    │    │   config     │    │ · Playwright │
-  │   library    │    │ · System     │    │   auth       │
-  │              │    │   instruct.  │    │ · LocalWP    │
+  │   patterns   │    │ · Query      │    │ · Playwright │
+  │ · Semgrep    │    │ · Review     │    │   + password-│
+  │   rules      │    │   (planned)  │    │   less login │
+  │ · AST checker│    │ · Harness    │    │   mu-plugin  │
+  │ · Pattern    │    │   config     │    │ · QM bridge  │
+  │   library    │    │ · System     │    │ · HookTrace  │
+  │              │    │   instruct.  │    │   (planned)  │
+  │              │    │              │    │ · LocalWP    │
   │              │    │              │    │ · Recipes    │
   └──────┬───────┘    └──────┬───────┘    └──────┬───────┘
          │                   │                   │
          │     detection     │   understanding   │  orchestration
-         │     + structure   │   + enrichment    │  + runtime
+         │     + structure   │   + enrichment    │  + runtime +
+         │                   │                   │  auth
          │                   │                   │
          └───────────────────┴───────────────────┘
                       │