[markshust]

Closes #529

Docs explain how things work for humans and AI; they are not a spec for the implementation. This removes every test that depends on documentation and makes that a hard rule.

Changes

RoadRunner docs

• Delete docs/packages/roadrunner-state-leaks.md. It was an internal discovery-spike record ("Task 005"), was listed under Packages because the sidebar builds that section from every file in docs/packages/, and still marked the Inertia and ReadWriteConnection leaks as open after both were fixed.
• Add its user-relevant points to the Stateful Singleton section of roadrunner.md: admin sections live for the whole worker, custom casts must be stateless, login throttle counts persist on purpose, and workers need a restart after switching between MySQL and MariaDB. Remove the link to the deleted page.

Tests that read docs

• Delete whole doc-only test files: roadrunner DocsTest, the authentication, testing and claude-plugins ReadmeTests, devai DocsPageTest and ReadmeStandardsTest, framework ArchitectureDocTest, validation DocsTest, docs-markdown AiAssistedDocsTest and AstroPipelineTest, and root ReleaseSkillTest and ReleaseDocumentationTest.
• Remove individual README, docs-page and .claude/ assertions from about 20 more files (package scaffolding and structure tests, rename-reference tests, the claude-plugins plugin tests, root CiWorkflowTest, RemoveDemoDirectoryTest and the integration HarnessTest).
• Remove the state-leak spike's three findings-document tests and the moduleSingletonIdentifiers() helper only they used. The behavioral harness tests are kept.
• MarkdownRepositoryTest now runs against tests/Fixtures/docs/ instead of the real docs tree.

Hard rule

• Added to the CLAUDE.md Key Conventions, a new section in .claude/testing.md, and the code-quality list and merge checklist in .claude/pr-review-process.md.
• Files the code ships or emits (templates, generated config, installed skill files, exception messages containing docs URLs) are product, not docs, and are still tested.

Docs lint (composer docs:lint)

• The check that every Marko\... class in a README or docs PHP example exists moved out of the test suite into bin/docs-lint.php. It now also scans the repository README.md.
• Runs in the required CI Lint job on every PR (no paths filter), even when an earlier lint step failed, and in composer ci. A wrong docs update fails a required check and can't be merged.
• Predictable: classes resolve by PSR-4 file existence from packages/*/composer.json, nothing is autoloaded. Takes about 0.5s. Exits 1 with file:line for every missing class, and refuses to pass if it finds no Markdown to scan.
• The scanner's own tests (and new tests for the script's exit codes) run against fixtures. CiWorkflowTest checks that the Lint job and composer ci both run it.

CI service images

• ci.yml and nightly.yml now pull Redis, Postgres, MySQL and MariaDB from public.ecr.aws/docker/library/ (AWS's mirror of the official Docker images). Anonymous Docker Hub pulls on shared runners were hitting toomanyrequests and failing Tests and Integration before any test ran. CiWorkflowTest now fails if a workflow image points back at Docker Hub. Local tests/Integration/compose.yml is unchanged.

Verification

• composer ci: 11,831 tests passed (333 skipped), phpcs, php-cs-fixer, PHPStan and docs:lint clean
• CI: Tests, Lint, Static analysis and Integration all green
• Planting a fake Marko\Roadrunner\DoesNotExist in roadrunner.md makes docs:lint fail with its file and line
• phpcs and php-cs-fixer --dry-run: clean
• composer phpstan: no errors

🤖 Generated with Claude Code

https://claude.ai/code/session_01HHxAV6dBdcdgA6Fm8j34Zn