fix: keep rule documentation in sync

Author: brianvarskonst

AGENTS.md

@@ -0,0 +1,35 @@
+# SymPress Coding Standards agent contract
+
+## Purpose and boundaries
+
+This package owns reusable PHPCS profiles and the custom `SymPress.*` sniffs. Reuse an established vendor sniff before adding a custom rule. Keep WordPress-specific allowances out of the pure PHP layer.
+
+## Read first
+
+- `docs/Rules.md`: intent, severity and false-positive posture for every custom rule.
+- `docs/Sniffs.md`: compact custom-sniff inventory.
+- `docs/Compatibility.md` and `docs/Adoption.md`: supported profiles and rollout policy.
+- `SymPress-*/ruleset.xml`: public profile composition.
+- `tests/fixtures` and `tests/unit/FixturesTest.php`: executable sniff expectations.
+
+## Verification
+
+- Fast for one sniff: run the matching PHPUnit test or `composer tests -- --filter <name>`.
+- Full: `composer qa`.
+- Use `composer cs:fix` only for intended mechanical fixes, then inspect the diff.
+
+## Invariants
+
+- New custom sniffs must fill a documented gap rather than duplicate a vendor rule.
+- Pure, WordPress, boundary and template profiles keep their layer-specific responsibilities.
+- Every custom sniff needs fixture expectations and entries in both documentation catalogs.
+- Fixers must be idempotent and preserve semantics.
+- Runtime and compatibility claims must match `composer.json` and the public rulesets.
+
+## Cross-repository impact
+
+`sympress/qa` and most SymPress PHP repositories consume these profiles. A changed default severity or profile inclusion can break every consumer and requires release notes plus representative downstream validation.
+
+## Definition of done
+
+Fixtures cover positive and negative behavior, catalog validation passes, `composer qa` is green, and compatibility/changelog text matches the manifest.

CHANGELOG.md

@@ -13,7 +13,7 @@ The format follows Keep a Changelog style sections and semantic versioning.
 
 ### Changed
 
-- Lowered the package runtime requirement to PHP 8.2+ while keeping explicit profile targets for newer PHP and WordPress stacks.
+- Raised the package runtime requirement to PHP 8.5+.
 - Allowed stable PHPCompatibility 9.x in addition to PHPCompatibility 10 alpha releases.
 - Made base layers version-neutral and mapped `SymPress-Plugin`, `SymPress-Core`, and `SymPress-Extra` to `SymPress-Enterprise-Next`.
 - Updated `SymPress-Templates` to include the WordPress security layer before applying template-specific rules.

tests/unit/RulesetConfigurationTest.php

@@ -45,4 +45,34 @@ public function testConfiguredWordPressMinimumUsesWpcsThreeConfigName(string $ru
             $contents,
         );
     }
+
+    public function testCustomSniffCatalogsMatchImplementations(): void
+    {
+        $libPath = rtrim((string) getenv('LIB_PATH'), '/');
+        $implemented = [];
+
+        foreach (glob("{$libPath}/SymPress/Sniffs/*/*Sniff.php") ?: [] as $file) {
+            $relative = substr($file, strlen("{$libPath}/SymPress/Sniffs/"));
+            [$category, $class] = explode('/', $relative);
+            $implemented[] = sprintf('SymPress.%s.%s', $category, substr($class, 0, -strlen('Sniff.php')));
+        }
+
+        sort($implemented);
+
+        foreach (['docs/Sniffs.md', 'docs/Rules.md'] as $documentation) {
+            preg_match_all(
+                '/`(SymPress\.[A-Za-z0-9.]+)`/',
+                (string) file_get_contents("{$libPath}/{$documentation}"),
+                $matches,
+            );
+            $documented = $matches[1];
+            sort($documented);
+
+            self::assertSame(
+                $implemented,
+                $documented,
+                "{$documentation} must list every implemented custom sniff once.",
+            );
+        }
+    }
 }