---
description: Documentation sync rules — which docs to update when code changes in src/
globs: "src/**"
alwaysApply: false
---

# Documentation Sync Rules

These rules apply when modifying files under `src/`. They define which documentation to update and when.

---

## MANDATORY: Auto-Update Documentation

Whenever you implement changes, you **MUST** update the relevant documentation files. Never skip this step. **If you are unsure which docs to update, consult the Documentation Trigger Map below and ask the user if needed — do not skip doc updates because you're uncertain.**

### Documentation Timing Gate (BLOCKING — requires user verification first)

**You may NOT update documentation, rebuild docs, update task logs, or perform any batch-boundary step until ALL of the following gates have passed in order:**

1. **Agent Self-Evaluation Gate** — You confirmed this is the best solution (see `task.mdc` → Agent Self-Evaluation Gate).
2. **Visual Verification Gate** — If the work affects front-end/UI/visual elements, you opened a browser, took screenshots, and visually confirmed (see `task.mdc` → Visual Verification Gate).
3. **User Verification Gate** — The user has either tested and confirmed, OR explicitly waived testing.

**If the user has not yet responded to the verification prompt, you may NOT:**
- Edit any file in `docs/`
- Edit any file in `docs/task/logs/`
- Edit any file in `docs/agent-observations/`
- Stage, commit, or push any changes

**Scenario Evidence Requirement (BLOCKING):** Documentation is blocked until all required behavior-path scenarios were executed end-to-end.

**Untested Disclosure Requirement (BLOCKING):** The verification summary must include an explicit `Not Tested` section listing every unexecuted check/scenario (or `Not Tested: none`).

**CRITICAL — NO SKIPPING:** You are never permitted to bypass this timing gate on your own judgment.

### Update "Last updated" Date on Every Doc Edit

Whenever you edit **any** markdown file in `docs/`, you **MUST** also update its `> **Last updated:** YYYY-MM-DD` line (or `<!-- Updated: YYYY-MM-DD -->` comment) to today's date.

---

## Documentation Trigger Map

### 1. `docs/plugin/architecture/1-gateway-architecture.md` — Gateway Architecture

**Update when:**
- Modifying the main gateway class (extends `WC_Payment_Gateway`)
- Adding/removing payment method support
- Changing hook/filter registrations
- Modifying gateway availability logic
- Changing the plugin bootstrap/initialization flow

**What to document:**
- Class hierarchy and key methods
- Registered hooks and filters
- Gateway availability conditions
- Payment method registration flow

### 2. `docs/plugin/architecture/2-api-integration.md` — API Integration

**Update when:**
- Modifying the Glitch API client class
- Adding/changing API endpoints
- Changing authentication or request signing
- Modifying error handling or retry logic
- Changing sandbox vs production URL routing

**What to document:**
- API endpoints and methods
- Authentication flow
- Request/response format
- Error codes and handling
- Environment-specific base URLs

### 3. `docs/plugin/architecture/3-security.md` — Security

**Update when:**
- Modifying webhook signature verification
- Changing input sanitization or output escaping patterns
- Adding/modifying nonce checks
- Changing API key storage approach
- Modifying CSRF protection

**What to document:**
- Signature verification algorithm and flow
- Sanitization/escaping patterns used
- Nonce implementation details
- Credential storage approach

### 4. `docs/plugin/features/1-checkout-flow.md` — Checkout Flow

**Update when:**
- Modifying `process_payment()` method
- Changing redirect URL generation
- Modifying return/cancel URL handling
- Changing checkout form rendering
- Modifying payment initiation request format

**What to document:**
- Payment initiation flow (cart → API → redirect → return)
- URL generation logic
- Order status transitions during checkout
- Error handling for failed initiations

### 5. `docs/plugin/features/2-webhooks.md` — Webhooks

**Update when:**
- Modifying webhook endpoint registration
- Adding/changing supported event types
- Changing webhook signature verification
- Modifying idempotency/duplicate detection
- Changing order status mapping from events

**What to document:**
- Supported event types and their handling
- Webhook processing pipeline
- Idempotency implementation
- Status mapping (Glitch event → WC order status)

### 6. `docs/plugin/features/3-refunds.md` — Refunds

**Update when:**
- Modifying `process_refund()` method
- Changing refund API calls
- Adding/modifying chargeback handling
- Changing partial refund logic

**What to document:**
- Refund initiation flow
- Partial vs full refund handling
- Chargeback webhook handling
- Error states and recovery

### 7. `docs/plugin/features/4-admin-settings.md` — Admin Settings

**Update when:**
- Modifying `init_form_fields()` or admin form fields
- Adding/removing settings options
- Changing sandbox/production toggle behavior
- Modifying debug logging configuration
- Changing credential validation

**What to document:**
- Available settings fields and their purpose
- Environment switching behavior
- Debug logging configuration
- Credential validation flow

### 8. `docs/plugin/features/5-order-management.md` — Order Management

**Update when:**
- Changing order status transition logic
- Modifying order meta key storage
- Changing transaction ID mapping
- Modifying duplicate payment prevention
- Adding/changing order notes

**What to document:**
- Status transition rules (Glitch status → WC status)
- Order meta keys and their purpose
- Duplicate prevention mechanism
- Order note conventions

### Split Documentation Routing

**Routing:** Always search the `0-index.md` files first, then update the matching grouped docs.

```bash
rg -n -i "<task keywords>" docs/plugin/**/0-index.md
```

**Only update top-level aggregate docs when the user explicitly asks.**

---

## Task Ledger (Daily Files in `docs/task/logs/`)

Whenever you complete a task, you **MUST** append/update entries in today's daily task log file:

- `docs/task/logs/YYYY-MM-DD.md`

If the file doesn't exist yet, create it with the header format defined in `task.mdc`.

**Column definitions:**
- `Title` — Action-oriented, specific enough to be searchable
- `Description` — Concise, outcome-focused
- `Start Date` / `End Date` — `MM/DD/YYYY` format
- `Category` — One of: `Payment`, `Webhooks`, `Refunds`, `Admin`, `API`, `Security`, `Config`, `Bug`, `Docs`
- `Type` — `Task` or `Sprint`

**Never skip the task ledger update.**

---

## Documentation Format Guidelines

- Use Markdown with clear headers and tables
- Include code snippets for function signatures and usage examples
- Keep entries concise
- Use tables for reference data
- Date-stamp significant additions with `<!-- Added: YYYY-MM-DD -->`
- Group related items under logical sections
- When adding to an existing doc, append to the relevant section — don't restructure
