# Autonomous AI Development & Quality Protocol for AdFuz

You are developing the WordPress plugin **AdFuz** (and **AdFuz Pro**). 
As an AI coding assistant, you MUST follow this protocol without exception. You are responsible for writing secure, standard-compliant, self-verified code.

---

## 1. WordPress Security Standards (The "Rule of 4")

Every endpoint, form handler, AJAX action, or REST API callback MUST follow the **Rule of 4**:

1. **User Capability Check**:
   Always verify user capability using AdFuz's helper or core API:
   ```php
   \AdFuz\Helpers\Common::checkCapability( 'manage_options' );
   // Or:
   if ( ! current_user_can( 'manage_options' ) ) {
       wp_send_json_error( __( 'Unauthorized access', 'ad-fuz' ), 403 );
   }
   ```
2. **Nonce Verification**:
   AdFuz uses the standard nonce key `'adfuz_nonce'`. Always verify using AdFuz's helper:
   ```php
   \AdFuz\Helpers\Common::verifyNonce(); // Checks $_REQUEST['adfuz_nonce'] against 'adfuz_nonce'
   // Or manual verification:
   $nonce = isset( $_REQUEST['adfuz_nonce'] ) ? sanitize_text_field( wp_unslash( $_REQUEST['adfuz_nonce'] ) ) : '';
   if ( ! wp_verify_nonce( $nonce, 'adfuz_nonce' ) ) {
       wp_send_json_error( __( 'Invalid security token', 'ad-fuz' ), 403 );
   }
   ```
3. **Strict Input Sanitization**:
   Never trust `$_POST`, `$_GET`, or `$_REQUEST`. Always sanitize:
   - Strings: `sanitize_text_field( wp_unslash( $_POST['field'] ) )`
   - Numbers: `absint( $_POST['id'] )` or `intval( ... )`
   - Keys / Slugs: `sanitize_key( $_POST['slug'] )`
   - HTML content: `wp_kses_post( wp_unslash( $_POST['content'] ) )`
4. **Strict Output Escaping**:
   Never `echo` or print variables without an escaping function:
   - Plain text: `esc_html( $var )` or `esc_html__( 'Text', 'ad-fuz' )`
   - Attributes: `esc_attr( $var )` or `esc_attr__( 'Text', 'ad-fuz' )`
   - URLs: `esc_url( $var )`
   - Rich HTML: `wp_kses_post( $var )`
   - JSON: `wp_json_encode( $var )`

---

## 2. WordPress Core API Best Practices

- **File operations**: Never use raw PHP `unlink()`, `file_get_contents()`, `file_put_contents()`, or `curl`. Always use WordPress APIs:
  - Deleting files: `wp_delete_file( $path )`
  - HTTP requests: `wp_remote_get()`, `wp_remote_post()`
  - Filesystem: Use `$wp_filesystem` API.
- **Database operations**: Never concatenate variables into SQL strings. Always use `$wpdb->prepare()`.
  ```php
  $wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}adfuz_ads WHERE status = %s", $status ) );
  ```
- **Internationalization (i18n)**:
  - Always use textdomain `'ad-fuz'`.
  - When using placeholders (`%s`, `%d`), ALWAYS include a translators comment directly above the line:
    ```php
    /* translators: %s: Name of the ad */
    printf( esc_html__( 'Ad %s was updated.', 'ad-fuz' ), esc_html( $ad_name ) );
    ```

---

## 3. Mandatory Autonomous Verification Protocol

Whenever you write, edit, or refactor code in this plugin, you **MUST NOT** complete your response until you run the verification tool:

1. **Auto-Format Code**:
   Run `D:\localserver\ad-fuz\check-quality.bat format` (or via composer `composer format`) to automatically fix any whitespace or styling issues.
2. **Run WordPress Standards & Security Audit**:
   Run:
   ```cmd
   "D:\localhost-setup\wp-cli\wp.bat" plugin check ad-fuz --include-low-severity-warnings --include-low-severity-errors
   ```
3. **Run Zero-Blindspot Browser & Debug Log Sentinel**:
   Run:
   ```cmd
   npm run test:e2e
   ```
   (or `php check-debug-log.php verify`) to guarantee:
   - Zero JavaScript console errors or unhandled page exceptions.
   - Zero failed HTTP/AJAX requests (4xx / 5xx).
   - Zero PHP warnings, notices, fatal errors, or database failures in `wp-content/debug.log`.
4. **Zero-Defect Rule**:
   - If `wp plugin check`, `phpcs`, or the Sentinel test reports any **ERRORS** or **WARNINGS** on lines you touched, you MUST fix them autonomously before concluding.
   - Do NOT ask the user to fix styling, escaping, or translation warnings—fix them yourself.

---

## 4. Documentation Synchronization

Whenever you add a new setting, feature, shortcode, or filter to the plugin:
- Update the documentation in the companion docs project: `D:\localserver\ad-fuz-faq`.
- Follow the existing Astro / Starlight documentation structure.