chore: align agent engineering rules

.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

.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 && <Component />}`) and array mapping to create lists.
+4. Separate components when doing so clarifies responsibility or enables reuse. Prefer conditional rendering (`{condition && <Component />}`) 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
 

.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
 

.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

.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:

.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

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