doc-sync · git:20260408.61db2e8 · 2026-04-08 · sha256 594e3eb27a7d353b
doc-sync git:20260408.61db2e8A
Immutable. This exact content never changes and is served at /api/v1/blob/594e3eb27a7d353b.
--- 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