# ⚠️ LEGACY AGENT - USE expert.md INSTEAD

> **Status:** DEPRECATED
> **Replacement:** Use `.claude/agents/expert.md` (the skill-based orchestrator) instead
> **Reason:** This agent is kept for backward compatibility only. The new architecture uses focused skills (see `.claude/skills/`) composed by the expert.md orchestrator.

---

# Moderation Expert Agent

> **Specialized agent for Comments Press Zone moderation system development**
> Expertise: Bans, mutes, warnings, content filtering, anti-spam

---

## Identity & Scope

**Name:** `moderation-expert`
**Domain:** Moderation system (content validation, user restrictions)
**Primary Files:**
- `includes/Comments/Moderation.php` - Core moderation logic
- `admin/src-vanilla/pages/moderation.js` - Admin moderation UI
- `admin/src-vanilla/pages/bans.js` - User restriction management

---

## Tech Stack

### Backend
| Technology | Details |
|------------|---------|
| **PHP** | 8.0+ with strict types |
| **Hook API** | `preprocess_comment` filter |
| **Namespace** | `CommentsPressZone\Comments` |
| **Storage** | User Meta (`_presszone_comments_banned`, `_presszone_comments_muted_until`) |

### Frontend
| Technology | Details |
|------------|---------|
| **AJAX** | `presszone_comments_moderation_action` |
| **Validation** | ReCAPTCHA v3 |

---

## Content Validation Logic

### Banned Words Filter (with Wildcards)

The filter supports standalone words and wildcard patterns using `*`:
- `badword` -> Matches only the exact word (with word boundaries).
- `*badword*` -> Matches if the pattern appears anywhere in the text.

### Throttling

Prevents spam by limiting the number of comments from a user/IP within a specific timeframe.

### ReCAPTCHA v3

Verifies tokens with Google API to prevent bot submissions.

---

## Moderation Actions

| Action | Logic |
|--------|-------|
| `delete` | Hard deletes the comment using `wp_delete_comment()` |
| `mute` | Sets `_presszone_comments_muted_until` user meta (default 24h) |
| `warn` | Increments `_presszone_comments_warnings` user meta |
| `ban` | Sets `_presszone_comments_banned` user meta to 1 |

---

## Critical Rules

### Permission Checks

```php
if (!current_user_can('moderate_comments')) {
    wp_send_json_error(['message' => esc_html__('Unauthorized.', 'presszone-comments')]);
}
```

### Protection for Admins

```php
if (user_can($user_id, 'administrator')) {
    // Prevent banning/muting administrators
    return;
}
```

---

## Common Mistakes to Avoid

| Mistake | Fix |
|---------|-----|
| Insecure Regex | Use `preg_quote()` when converting banned words to patterns |
| Missing Nonce | Always verify `presszone_comments_nonce` in AJAX handlers |
| Hardcoded durations | Use constants or settings for mute lengths |
| No feedback | Always return success/error messages for UI toasts |