diff --git a/.cursor/rules/core-development.mdc b/.cursor/rules/core-development.mdc
index bd5d4e671..a7cf0cb49 100644
--- a/.cursor/rules/core-development.mdc
+++ b/.cursor/rules/core-development.mdc
@@ -24,11 +24,11 @@ Do not affirm my statements or assume my conclusions are correct. Question assum
## Coding Standards
- Plan before coding, explain reasoning for complex suggestions
-- No code comments - write self-explanatory code
+- Follow the code comment guidance in `AGENTS.md`
- Keep imports alphabetically sorted
- Keep code SOLID but simple - separation of concerns without over-engineering
-- Aim to keep files under 300 lines - split when it improves clarity
-- Write tests for critical paths only. Use AAA pattern.
+- Treat file length as a signal; split only for reuse, meaningful separation, or clearer testing
+- Follow the testing requirements in `AGENTS.md`. Use the AAA pattern.
- Run `npm run lint` for lint check
## Prohibited Actions
diff --git a/.cursor/rules/declarative-react.mdc b/.cursor/rules/declarative-react.mdc
index cf8b2d28d..3dcd72406 100644
--- a/.cursor/rules/declarative-react.mdc
+++ b/.cursor/rules/declarative-react.mdc
@@ -15,7 +15,7 @@ Always write React code in a declarative style.
3. Use hooks (`useState`, `useReducer`, `useEffect`, `useMemo`, `useCallback`) responsibly:
- Avoid running imperative logic in `useEffect` that can be expressed through declarative data-flow.
- Derive data instead of duplicating state.
-4. Build UI by **composing** smaller components. Prefer conditional rendering (`{condition && }`) and array mapping to create lists.
+4. Separate components when doing so clarifies responsibility or enables reuse. Prefer conditional rendering (`{condition && }`) and array mapping to create lists.
5. Keep side-effects isolated; only place effectful code inside `useEffect`, `useLayoutEffect`, or custom hooks.
6. Use **refs** sparingly and only for non-DOM data persistence, not for styling or visibility toggling.
7. Prefer **controlled components** for forms. Keep input values in React state.
@@ -24,6 +24,8 @@ Always write React code in a declarative style.
10. Favor pure functions and immutable data patterns to make render output predictable.
11. **Avoid cascading state updates**: Never create chains where updating one state triggers a `useEffect` that updates another state. Instead, derive values using `useMemo` or calculate them during render.
12. **Prefer direct state updates over useEffect chains**: When you need to update multiple related state values, do it directly in the event handler rather than creating cascading useEffect dependencies.
+13. **Keep hooks non-visual**: Custom hooks return state and actions, not rendered elements.
+14. **Avoid trivial memoization**: Calculate inexpensive derived values during render instead of wrapping them in `useMemo` or `useCallback`.
## Anti-Patterns to Avoid
diff --git a/.cursor/rules/development-guidelines.mdc b/.cursor/rules/development-guidelines.mdc
index bc581baf9..955cc8549 100644
--- a/.cursor/rules/development-guidelines.mdc
+++ b/.cursor/rules/development-guidelines.mdc
@@ -17,17 +17,14 @@ alwaysApply: true
## File Organization
-- Break code into multiple smaller files instead of creating large monolithic files
- Keep files focused on a single responsibility or closely related functionality
-- Aim for files under 200-300 lines when possible
-- Split large components, services, or modules into logical sub-modules
+- Treat file length as a signal; split only for reuse, meaningful separation, or clearer testing
+- Avoid single-use helper files and pass-through abstractions
- Use clear directory structure to organize related files
## Testing Requirements
-- Write tests for all new code functionality
-- Add tests when modifying existing code to ensure no regressions
-- Focus on testing the most critical paths and edge cases
+- Follow the testing requirements in `AGENTS.md`
- Follow existing testing patterns and conventions in the codebase
- Ensure tests are deterministic and properly isolated
diff --git a/.cursor/rules/development-workflow.mdc b/.cursor/rules/development-workflow.mdc
index 00412cb51..f2aa448fa 100644
--- a/.cursor/rules/development-workflow.mdc
+++ b/.cursor/rules/development-workflow.mdc
@@ -17,13 +17,13 @@ alwaysApply: true
## During Development
1. **Follow Patterns**: Use existing patterns and conventions
-2. **Write Tests**: Add tests for critical paths
+2. **Write Tests**: Follow the testing requirements in `AGENTS.md`
3. **Type Safety**: Use TypeScript strictly
4. **Document APIs**: Document all public interfaces
## After Implementation
-1. **Run Tests**: Ensure all tests pass
+1. **Run Tests**: Run and verify the merge gate required by `AGENTS.md` before release integration
2. **Lint Code**: Fix any linting issues
3. **Check Dependencies**: Verify no circular dependencies
4. **Test Integration**: Verify with other packages
diff --git a/.cursor/rules/general-code-style.mdc b/.cursor/rules/general-code-style.mdc
index 5984d4e72..8cbc1fdbe 100644
--- a/.cursor/rules/general-code-style.mdc
+++ b/.cursor/rules/general-code-style.mdc
@@ -22,7 +22,8 @@ alwaysApply: true
## Self-Documented Code
- Avoid adding comments that can be a constant or a well-named function
-- Always prefer to create small functions that describe themselves
+- Prefer existing or local functions for small, stateless, single-use behavior; extract helpers when they provide reuse
+ or meaningful separation
- Only add comments to explain "why" when it is truly not understandable from the code itself
- Do NOT add comments that explain "what" the code does (the code should be self-explanatory)
- Examples of unnecessary comments to avoid:
diff --git a/.cursor/rules/wordpress.mdc b/.cursor/rules/wordpress.mdc
index e4d0aa3d0..bc4708413 100644
--- a/.cursor/rules/wordpress.mdc
+++ b/.cursor/rules/wordpress.mdc
@@ -12,7 +12,8 @@ You are an expert in WordPress, PHP, and related web development technologies.
- Provide precise, technical PHP and WordPress examples
- Adhere to PHP and WordPress best practices for consistency and readability
-- Emphasize object-oriented programming (OOP) for better modularity
+- Use OOP for state, lifecycle, contracts, or reusable behavior; prefer existing or local functions for small, stateless,
+ single-use behavior
- Focus on code reusability through iteration and modularization, avoiding duplication
- Use descriptive and meaningful function, variable, and file names
- Directory naming conventions: lowercase with hyphens (e.g., wp-content/themes/my-theme)
@@ -22,7 +23,8 @@ You are an expert in WordPress, PHP, and related web development technologies.
- Utilize features of PHP 7.4+ (e.g., typed properties, arrow functions) where applicable
- Follow WordPress PHP coding standards throughout the codebase
-- Enable strict typing by adding `declare(strict_types=1);` at the top of PHP files
+- Prefer `declare(strict_types=1);` in appropriate new or already-strict code; do not add it as unrelated cleanup in
+ existing integration files
- Leverage core WordPress functions and APIs wherever possible
- Maintain WordPress theme and plugin directory structure and naming conventions
- Implement robust error handling:
@@ -34,11 +36,11 @@ You are an expert in WordPress, PHP, and related web development technologies.
- For database interactions:
- Use WordPress's `$wpdb` abstraction layer
- Apply `prepare()` statements for all dynamic queries to prevent SQL injection
- - Use the `dbDelta()` function for managing database schema changes
+ - Use the `dbDelta()` function for schema changes only after custom storage is justified under `AGENTS.md`
## Dependencies
-- Ensure compatibility with the latest stable version of WordPress
+- Ensure compatibility with the repository's minimum supported WordPress and PHP versions
- Use Composer for dependency management in advanced plugins or themes
## WordPress Best Practices
diff --git a/AGENTS.md b/AGENTS.md
index dc50d2700..80bf88ea6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -103,7 +103,8 @@ plugins.
- Namespace: `Code_Snippets\` — all new classes must live under this namespace and be PSR-4 autoloaded.
- Vendor dependencies: always use the prefixed namespace `Code_Snippets\Vendor\…` (Imposter-prefixed).
-- Guard direct execution at the top of every standalone file: `defined('ABSPATH') || exit;`
+- Guard direct execution at the top of executable entry points and procedural files with
+ `defined('ABSPATH') || exit;`; do not add guards to autoloaded class files.
- Use `wp_die()` for fatal admin errors; never `die()` or `exit` with user-facing output.
- In `src/php/Plugin.php` (and Core bootstrap), rely on `autoload.php`; avoid manual `require_once` chains.
- Avoid creating custom database tables. Prefer WordPress-native storage: `wp_options` for settings/flags, transients
@@ -127,8 +128,11 @@ plugins.
- Prefer direct state updates in event handlers over using `useEffect` to synchronize multiple state values.
- Use controlled components for forms; keep input values in React state.
- Derive computed values at render-time rather than duplicating them in separate state.
-- **Component composition**: Break components into smaller, focused units. Use JSX for markup rather than
- `createElement` in utility functions.
+- **Hooks**: Hooks return state and actions, not rendered elements.
+- **Clarity**: Avoid nested ternaries, trivial memoization, unnecessary ARIA roles, and props that repeat component
+ defaults.
+- **Component composition**: Separate components when doing so clarifies responsibility or enables reuse. Use JSX for
+ markup rather than `createElement` in utility functions.
- Do not create 'index.ts' barrel files for components or hooks; import them directly to avoid circular dependencies and
improve tree-shaking.
- Reuse existing functions and components where possible, creating new common components under
@@ -140,10 +144,10 @@ plugins.
### Code Organization
-- Keep individual source files under 300 lines to improve maintainability and testability; split larger files into
- focused modules.
-- Maintain a direct mapping between source classes and their test files; if a test file grows large, consider whether
- the source class can be broken into smaller concerns.
+- Treat file length as a signal, not a reason to split cohesive code. Extract code only for reuse, meaningful separation,
+ or clearer testing; avoid single-use and pass-through abstractions.
+- Maintain a direct mapping between source classes and their test files; split source classes and tests only when doing
+ so creates a meaningful separation or clearer testing boundary.
---
@@ -154,6 +158,8 @@ plugins.
plugins using the same libraries.
- **Snippet model** — core data unit is `Code_Snippets\Model\Snippet`; use its API for reading/writing snippet data, not
raw DB access.
+- **Data boundaries** — models preserve data, remote response decoding normalizes remote data, and rendering handles
+ presentation sanitation and escaping.
- **Hook-driven extensibility** — use WordPress filters and actions as the primary extension mechanism; expose a filter
before changing any default behaviour that may be preference-driven.
- **Safe mode** — `src/php/Core/load.php` boots a recovery path when safe mode is active; any change to snippet
@@ -168,8 +174,11 @@ plugins.
- **Development branches:** `feat/…`, `fix/…`, `chore/…`, `hotfix/…`
- Branch from `core-beta` for all feature and fix work.
- Open PRs back into `core-beta`.
-- Use **merge commits** (not squash/rebase) when merging dev branches into `core-beta`.
+- Preserve granular history during development and use merge commits for active stack propagation. Squash-merging a
+ large, fully reviewed chain into `core-beta` is preferred after explicit approval and a passing chain-peak matrix.
- Hotfixes branch from `core` and merge directly back into `core`.
+- Intermediate stacked PRs may fail when the failure is understood and fixed later in the same chain. The current chain
+ peak must pass the complete required matrix before release integration.
### Commit Messages