docs(boundary): codify shared test helper plugin seams

AGENTS.md

@@ -73,6 +73,8 @@
 - Extension test boundary:
   - Keep extension-owned onboarding/config/provider coverage under the owning bundled plugin package when feasible.
   - If core tests need bundled plugin behavior, consume it through public `src/plugin-sdk/<id>.ts` facades or the plugin's `api.ts`, not private extension modules.
+  - Shared helpers under `test/helpers/**` are part of that same boundary. Do not hardcode repo-relative `extensions/**` imports there, and do not keep plugin-local deep mocks in shared helpers just because multiple tests use them.
+  - When core tests or shared helpers need bundled plugin public surfaces, use `src/test-utils/bundled-plugin-public-surface.ts` for `api.ts`, `runtime-api.ts`, `contract-api.ts`, `test-api.ts`, plugin entrypoint `index.js`, and resolved module ids for dynamic import or mocking.
   - If a core test is asserting extension-specific behavior instead of a generic contract, move it to the owning extension package.
 
 ## Docs Linking (Mintlify)

CONTRIBUTING.md

@@ -102,6 +102,11 @@ For coordinated change sets that genuinely need more than 10 PRs, join the **#cl
   - For targeted shared-surface work, use `pnpm test:contracts:channels` or `pnpm test:contracts:plugins`
   - These commands also cover the shared seam/smoke files that the default unit lane skips
   - If you changed broader runtime behavior, still run the relevant wider lanes (`pnpm test:extensions`, `pnpm test:channels`, or `pnpm test`) before asking for review
+- If you touched bundled-plugin boundaries in shared code, run the matching inventories:
+  - `node scripts/check-src-extension-import-boundary.mjs --json` for `src/**`
+  - `node scripts/check-sdk-package-extension-import-boundary.mjs --json` for `src/plugin-sdk/**` and `packages/**`
+  - `node scripts/check-test-helper-extension-import-boundary.mjs --json` for `test/helpers/**`
+- Shared test helpers must use `src/test-utils/bundled-plugin-public-surface.ts` instead of repo-relative `extensions/**` imports. Keep plugin-local deep mocks inside the owning bundled plugin package.
 - If you have access to Codex, run `codex review --base origin/main` locally before opening or updating your PR. Treat this as the current highest standard of AI review, even if GitHub Codex review also runs.
 - Do not submit refactor-only PRs unless a maintainer explicitly requested that refactor for an active fix or deliverable.
 - Do not submit test or CI-config fixes for failures already red on `main` CI. If a failure is already visible in the [main branch CI runs](https://github.com/openclaw/openclaw/actions), it's a known issue the Maintainer team is tracking, and a PR that only addresses those failures will be closed automatically. If you spot a _new_ regression not yet shown in main CI, report it as an issue first.

test/helpers/AGENTS.md

@@ -0,0 +1,31 @@
+# Shared Test Helper Boundary
+
+This directory holds shared test helpers reused by core and bundled plugin
+tests.
+
+## Bundled Plugin Imports
+
+- Shared helpers in this tree must not hardcode repo-relative imports into
+  `extensions/**`.
+- When a helper needs a bundled plugin public surface, go through
+  `src/test-utils/bundled-plugin-public-surface.ts`.
+- Prefer `loadBundledPluginApiSync(...)`,
+  `loadBundledPluginRuntimeApiSync(...)`,
+  `loadBundledPluginContractApiSync(...)`, and
+  `loadBundledPluginTestApiSync(...)` for eager access to exported surfaces.
+- Prefer `resolveRelativeBundledPluginPublicModuleId(...)` or
+  `resolveBundledPluginPublicModulePath(...)` when a helper needs a module id
+  or filesystem path for dynamic import, mocking, or loading a plugin entrypoint
+  such as `index.js`.
+- If `vi.hoisted(...)` is involved, do not call imported helper functions from
+  inside the hoisted callback. Resolve the module id outside the callback or
+  switch to `vi.doMock(...)`.
+- Do not keep plugin-local deep mocks or private `src/**` knowledge in shared
+  helpers. Move those helpers into the owning bundled plugin package instead.
+
+## Intent
+
+- Keep shared helpers aligned with the same public/plugin boundary that
+  production code uses.
+- Avoid shared helper debt that makes core test lanes depend on bundled plugin
+  private layout.

test/helpers/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

test/helpers/channels/AGENTS.md

@@ -3,6 +3,8 @@
 This directory holds shared channel test helpers used by core and bundled plugin
 tests.
 
+This file adds channel-specific rules on top of `test/helpers/AGENTS.md`.
+
 ## Bundled Plugin Imports
 
 - Core test helpers in this directory must not hardcode repo-relative imports